System Subroutines A 3.x Sampler (Functions/Subroutines/Programs)

System Subroutines A 3.X Sampler

Basics

User Interaction

Subroutines don't do screen I/O other than through PROGRESS.

You have source to PROGRESS.

@FILE.ERROR

Used to report errors encountered in the routine.

Subroutines will null out don't rely on it being unchanged.

Use in conjunction with STATUS() to determine error handling.

Calling routine can deal with the error or call FSMSG

copyrow_sub("MYVOC", "MYROW", "VOC", "NEWVOCITEM", "O")

If @FILE.ERROR then

fsmsg()

End

copyrow_sub("MYTABLE", "MYROW", "VOC", "", "")

If @FILE.ERROR<FSCODE$> = "W179" Then

* great! it already exists!

End Else

fsmsg()

End

Some errors will be generated by the subroutine. Some errors, usually I/O related, will be passed back, by the subroutine, unchanged.

Multiple errors come back delimited by @RM.

STATUS() values

Parameter initialization

Passed parameters are not assumed to be initialized

Uninitialized parms are assigned a default (usually null)

COPYROW_SUB

Copies one or more rows.

COPYROW_SUB(SourceTable, SourceIds, TargetTable, TargetIds, Options)

Errors Returned

DELETEROW_SUB

Deletes one or more rows from a table.

DELETEROW_SUB(Table, RowIds, Options)

Errors Returned

MAKETABLE_SUB

Creates a table. This routine must be called twice to create both the data and the dictionary; once for each.

MAKETABLE_SUB(Volume, Table, MediaMap, FieldList, AttachFlag)

Fieldlist layout

The fieldlist parameter is a dynamic array. Each field in the array represents a column in the dictionary. Each value in the field has a special meaning. Only "F" type fields can be created.

Errors Returned

DELETETABLE_SUB

Deletes a table.

DELETETABLE_SUB (TableName, Options)

Errors Returned

MAKEACCOUNT_SUB

Creates a new application (account).

MAKEACCOUNT_SUB (Name, Location, NewList, Options)

The NewList row is a list of new tables and rows to create in the new application. By default, the NEWAPPLICATIONLIST row in SYSENV is used. Each field in the list contains the name of the table to create. The first value in the field is the table name. Dictionaries must be explicitly given. The second and subsequent values are rows to create in the new table. The wildcard "*" is used to indicate that all rows from the currently attached table of the same name should be copied.

In the first value, if MFSs are to be automatically installed on the table they follow the table name and are separated by @SVM.

Examples:

MYTABLE2*

Copies all rows from the currently attached MYTABLE into the new MYTABLE in the new application.

MYTABLEnMY.MFS

Creates MYTABLE in the new application. Installs MY.MFS on the new table.

MYTABLEnMY.MFS2IMPORTANTROW

Creates MYTABLE in the new application, installing MY.MFS. Only copies in IMPORTANTROW from the currently attached MYTABLE.

Errors Returned

SECUREACCOUNT_SUB

Changes attributes of an application (account).

SECUREACCOUNT_SUB(Request, Name, AppRecord, Status)

AppRecord layout:

Status codes:

Errors Returned

Error conditions are reported in Status.

DELETEACCOUNT_SUB

Removes an application (account) from the system.

DELETEACCOUNT_SUB (Name, VolumeList, Options)

Errors Returned

USER_SUB

Allows user maintenance (creation, secure, delete).

USER_SUB(Request, Name, UserInfo, Status)

Request codes:

UserInfo record layout:

Status codes:

Errors Returned

Error conditions are reported in Status.

SETALIAS_SUB

Sets up an alias (QFILE).

SETALIAS_SUB(Volume, Application, Password, Table, Alias, Options)

Errors Returned

REBUILDINDEX_SUB

Rebuilds one or more indexes in a table.

REBUILDINDEX_SUB(DataTable, DataHandle, IndexHandle, FieldInfo, FlagAll)

FieldInfo layout:

Relational Justification and Sort Direction

Errors Returned

Example

declare subroutine rebuildindex_sub, fsmsg

declare function index.open

tablename = "PEOPLE_10000"

open tablename to datahandle else

fsmsg()

stop

end

open "DICT", tablename to @dict else

fsmsg()

stop

end

if index.open("!":tablename, indexhandle) else

fsmsg()

stop

end

fieldinfo = ""

fieldinfo<1, 1> = "AGE"

fieldinfo<1, 2> = "Btree"

fieldinfo<1, 3> = ""

fieldinfo<1, 4> = "AGE"

fieldinfo<1, 5> = 1 ;* Btree

fieldinfo<1, 6> = 4 ;* Column position

fieldinfo<1, 7> = 1 ;* Convert to Uppercase

fieldinfo<1, 8> = "RL"

fieldinfo<1, 9> = "AA"

fieldinfo<1, 10> = 0 ;* single value

fieldinfo<2, 1> = "ADDRESS"

fieldinfo<2, 2> = "CrossRef"

fieldinfo<2, 3> = ""

fieldinfo<2, 4> = "ADDRESS_XREF"

fieldinfo<2, 5> = 1 ;* Btree

fieldinfo<2, 6> = 5

fieldinfo<2, 7> = 1 ;* Convert to Uppercase

fieldinfo<2, 8> = "LL"

fieldinfo<2, 9> = "AA"

fieldinfo<2, 10> = 0 ;* single value

fieldinfo<3, 1> = "CITY"

fieldinfo<3, 2> = "Relational"

fieldinfo<3, 3> = "CITIES*PEOPLE_IN_CITY*BOT" ;* Related info

fieldinfo<3, 4> = "CITY"

fieldinfo<3, 5> = 2 ;* Relational

fieldinfo<3, 6> = 6

fieldinfo<3, 7> = 1 ;* Convert to Uppercase

fieldinfo<3, 8> = "LL"

fieldinfo<3, 9> = "AA" ;* Sort for "BOT" index

fieldinfo<3, 10> = 0 ;* single value

rebuildindex_sub(tablename, datahandle, indexhandle, fieldinfo, 0)

if @file.error then

fsmsg()

end