Show pageOld revisionsBacklinksBack to top This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong. ====== System Subroutines A 3.x Sampler (Functions/Subroutines/Programs) ====== ====== ====== ==== Created at 14 NOV 1996 02:26PM ==== **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 |-2|No error. Informational info in @FILE.ERROR | |-1|User abandoned process | |0 |Logical error | |1 |Physical error, possibly recoverable (eg drive door open).| |2 |Fatal error. | ** 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) |SourceTable|Required. The source table for the rows to be copied. | |SourceIds |The ids for the source rows to be copied. Multiple ids are separated by @FM. Wildcard "*" can be used to indicate all rows should be copied. If you like, you can activate a select list and pass SourceIds as null. The select list will be used.| |TargetTable|The table into which the source rows should be copied. If null, the target table is the same as the source table. | |TargetIds |The new ids for the rows to be copied. If null, the rows are copied to the same name. | |Options |See the documentation for COPYROW for a list of supported options. | ** Errors Returned** ** ** |W179|Target row already exists. | |W180|Target row does not exist. | |S805|Number of rows copied. (Informational)| |W106|User quit while waiting for a lock. | |W107|Source row does not exist. | |B403|Unable to write row. | **__ __DELETEROW_SUB** Deletes one or more rows from a table. DELETEROW_SUB(Table, RowIds, Options) |Table |Required. The name of the table from which to delete rows. | |RowIds |The ids for the rows to be deleted. Multiple ids are separated by @FM. An active select list may be used, if so, pass RowIds as null.| |Options|See the documentation for DELETEROW for a list of supported options. | ** Errors Returned** ** ** |W106|User quit while waiting for lock. | |W189|Number of rows deleted (informational)\\ \\ **__ __**| **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) |Volume |The volume onto which to create the table. If null, the default volume defined in the current volume is used. This is typically DATAVOL. | |Table |Required. The name of the table to create. Tables can be created in other applications by including the application name with the tablename, separated by an asterisk. TABLE*APPNAME The default is to create the table in the current application.| |MediaMap |The media map record for the table. Usually passed as a null, this can be used to preinstall MFSs on the newly created table. | |FieldList |A list of fields to create in the new dictionary. See below for the layout of this parameter. | |AttachFlag|Pass a 1 (true) if the newly created table is to be attached. The default is to not attach the table. | ** 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. |1) Name |The name of the dictionary item. No validation of the name is performed by this routine. The name is assumed to have been validated by the calling program.| |2) Datatype|The generic datatype to be applied to the column. | |3) KeyFlag |If this is true, the column is part of the key. | |4) MVFlag |If this is true, the column is multivalued, otherwise it is single valued. | ** Errors Returned** ** ** |S140|Process not available (can't run in a runtime) | |S141|Parameter required. | |W506|Unable to create table.\\ \\ **__ __** | **DELETETABLE_SUB** Deletes a table. DELETETABLE_SUB (TableName, Options) |Tablename|The name of the currently attached table to delete. | |Options |See the documentation for DELETETABLE for a list of supported options.| ** Errors Returned** ** ** |S140|Process not available.| |S141|Parameter required. | **__ __MAKEACCOUNT_SUB** Creates a new application (account). MAKEACCOUNT_SUB (Name, Location, NewList, Options) |Name |The name of the application to create. The name must not conflict with other application or user names. | |Location|Where to put the application specific tables. If not provided a new subdirectory under the current AREV is created using the same name as the application (or the first 8 characters of the name). Volume pointers may be used but only LH volumes are allowed.| |NewList |Key to the row in the SYSENV table containing the list of tables to create in the new application. See below for the structure of the NewList record. The default is NEWAPPLICATIONLIST. | |Options |See the documentation for MAKEAPPLICATION for supported 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** ** ** |W526|Application name is required. | |R120|The application already exists. | |S101|The location volume must be Linear Hash.| |S102|Unable to create //Location.// | |W544|Unable to read //NewList//. | |W500|Mismatch between table and volume. | **__ __SECUREACCOUNT_SUB** Changes attributes of an application (account). SECUREACCOUNT_SUB(Request, Name, AppRecord, Status) |Request |Required. The action to perform. 0 = Get application information. 1 = Update application information. | |Name |Required. The name of the application. | |AppRecord|If Request = 0, the application record is returned here. If Request = 1 you pass the updated application record here. See below for the structure of the record.| |Status |One of six status codes. See below for status codes. | **//AppRecord//** layout: |1 |The literal "ACCOUNT". | |2 |Startup command (logon verb). | |3 |Restriction level. | |4 |Environment. | |5 |Reserved. | |6 |Password (you pass it unencrypted, the system will encrypt.)| |7 |Logto passwords (mv list). | |8 |Logto startup commands (mv list). | |9 |Logto restriction levels (mv list). | |10|Shell code and command. | |11|Logto shell code and command. | |12|Reserved. | |13|Default location for the application. | **//Status//** codes: |0|Successful operation. | |1|No application name given. | |2|//Name// is not an application name. (The row exists in SYSENV but it is not an application.)| |3|//Name// does not exist. | |4|Invalid //Request// code passed. | |5|I/O error. Calling program should check @FILE.ERROR. | ** Errors Returned** Error conditions are reported in //Status//. **__ __DELETEACCOUNT_SUB** Removes an application (account) from the system. DELETEACCOUNT_SUB (Name, VolumeList, Options) |Name |Required. The name of the application to delete. | |VolumeList|A list of volumes on which there are tables belonging to the application to be deleted. The system will find and delete the application tables on these volumes. Multiple volumes are separated by @FM.| |Options |"S" to suppress progress information display. | ** Errors Returned** ** ** |W172|Application name required. | |W508|SYSPROG may not be deleted.| **__ __USER_SUB** Allows user maintenance (creation, secure, delete). USER_SUB(Request, Name, UserInfo, Status) |Request |The action to perform. See below for a list of valid request codes. | |Name |The user name on which to perform the action. | |UserInfo|This parameter is used to get information back or to supply information to the subroutine. A user record. See below for the layout of the user record.| |Status |A status code. See below for status codes. | **//Request//** codes: |0|Create a new user. (username passed in //Name//) | |1|Update user information. (username passed in //Name//. //Userinfo// contains new user record).| |2|Get user information. (username passed in //Name//. User record returned in //UserInfo//.) | |3|Delete a user. (username passed in //Name//) | **//UserInfo//** record layout: |1|The literal "USER". | |2|Application the user belongs to.| |3|Startup command (logon verb). | |4|Restriction level. | |5|Environment. | |6|Reserved. | |7|Password. | |8|Shell code and command. | **//Status//** codes: |0|Successful completion. | |1|No //Name// given. | |2|//Name// is not a user. | |3|//Name// does not exist. | |4|Invalid //Request//. | |5|I/O error. Check @FILE.ERROR for details. | |6|Application name given in user record does not exist.| |7|//Name// already exists. | ** Errors Returned** Error conditions are reported in //Status//. **__ __SETALIAS_SUB** Sets up an alias (QFILE). SETALIAS_SUB(Volume, Application, Password, Table, Alias, Options) |Volume |The volume containing the table to which to set an alias. | |Application|The name of the application that owns the table. | |Password |The password to the application, if any. | |Table |The name of the table to which to set the alias. | |Alias |The alias name. If //Alias// is not provided the system name SYSALIAS is used.| |Options |See the documentation for SETALIAS for supported options. | ** Errors Returned** ** ** |W125|Password is incorrect. | |W116|Application name is incorrect. | |W505|//Alias// is unavailable after SETALIAS_SUB. | |W500|Mismatch between volume and table. | |W517|Unable to attach table in the application on the volume.| **__ __REBUILDINDEX_SUB** Rebuilds one or more indexes in a table. REBUILDINDEX_SUB(DataTable, DataHandle, IndexHandle, FieldInfo, FlagAll) |DataTable |The name of the data portion of the table with indexes. | |DataHandle |The filehandle to //DataTable//. The calling program must open the table before calling this routine. The calling program must open the dictionary of the table to @DICT before calling this routine. | |IndexHandle|The filehandle to the !//DataTable//. The calling program must open the !table before calling this routine (INDEX.OPEN is a good choice). | |FieldInfo |An @FM delimited list of indexes to rebuild. See below for the structure required for each index type. | |FlagAll |Set to True (1) if all indexes in the table are being rebuilt. This allows for faster processing in how the !table is handled. If all indexes are not being rebuilt or you're not sure if all indexes are being rebuilt **DO NOT SET THIS FLAG**. You will lose index information.| **//FieldInfo//** layout: |1 |Name of the column. For CrossRef indexes this is the name of the column without the "_XREF". | |2 |Literal text for the index type (Btree, CrossRef, Related To) | |3 |Desc for Relational indexes, the description of the relationship. | |4 |The name of the column. For Btree and Relational indexes, this is the same as the information in value 1. For CrossRef indexes this is the name of the column //with// the trailing "_XREF". | |5 |Index type. 1 for Btree and CrossRef, 2 for Relational. | |6 |The field on which the index is placed. For real fields use the field number or the field name (using the field number will be faster). For symbolics, use the field name. | |7 |A flag determining whether the data should be converted to uppercase. 1 (true) means data should be converted. 0 (false) indicates data should not be converted. | |8 |The justification of the column. For Btree and CrossRef indexes this is the justifcation of the column (as defined in the dictionary) followed by the literal "L". See below for a table of justification codes used with Relational indexes.| |9 |Sort direction. For Btree and CrossRef indexes this is always "AA". See below for a table of sort directions for Relational indexes. | |10|Mv flag. True if the column is multivalued, false otherwise. | **//Relational//** Justification and Sort Direction |**Index Sort Type**|**Justification (Dict just + value in this colum)**|**Sort Direction**| |AL |L |AA | |AR |R |AA | |DL |L |AD | |DR |R |AD | |TOP |L |AD | |BOT |L |AA | ** Errors Returned** ** ** |FS421|User cancelled process. | |FS259|Related table is not available. | |B286 |Invalid index name. | |B702 |Index must be rebuilt. | |S195 |Out of disk space. Unable to rebuild index.| ** 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 kb/kb_articles/kb0060.txt Last modified: 2024/01/30 13:36by 127.0.0.1