Subroutine

Documents

ATTACHTABLE_SUB (sample code)

ATTACHTABLE_SUB( volumeName, tableList, options )

ATTACHTABLE_SUB attaches tables, making them available for subsequent processing. The subroutine can attach all available tables on a volume, or a selected list only. A table is available to ATTACHTABLE_SUB if it belongs to the current application or if it is global.

You can use a table alias (Qfile) to attach a table that belongs to another application. However, if the second application has a password, the alias definition (in the SYSALIAS table) must include the password. Add it to the second attribute of the definition. For example:

SYSALIAS
SAMPLE,MYPASSWORD
SAMPLE_CUSTOMERS

For more information about creating an alias for a table, see "Creating an alias (synonym) for a table" in Chapter 22 of the Advanced Revelation User's Guide.

If a table is qualified with a user name, you can attach it by including the appropriate user prefix. For details, see "Table names and users (qualified table names)" in Chapter 22 of the Advanced Revelation User's Guide.

If there are two tables of the same name, but one belongs to the current application and the other is global, the table belonging to the application is attached. You can attach the table REVMEDIA, but only if you are in the SYSPROG application.

Options

Values and Errors Returned

If an error has occured, the system variable status( ) is set to 1, otherwise status( ) is zero. Specific errors are returned in @file.error. Multiple errors are delimited with @RM. Possible values are:

DELETETABLE_SUB

DELETETABLE_SUB (TableName, 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

SETALIAS_SUB

Sets up an alias (QFILE).

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

Errors Returned

MAKEACCOUNT_SUB (sample code)

Creates a new application (account).

MAKEACCOUNT_SUB (Name, Location, NewList, Options)

Errors Returned

SECUREACCOUNT_SUB

Changes attributes of an application (account).

SECUREACCOUNT_SUB(Request, Name, AppRecord, Status)

AppRecord layout:

Values returned and Errors Returned

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:

Values returned and Errors Returneds:

BUILDINDEX_SUB (Sample Code)

BUILDINDEX_SUB( indexType, indexName, indexInfo, clearFlag, đ
indexHandle, sortFileName)

Using BUILDINDEX_SUB

Builds an index in a single table. The index to be built can be a Btree index, a Cross Reference indexes, or a Relational index.

+ The subroutine BUILDINDEX_SUB cannot build Quickdex or Rightdex indexes. To build those, use the system subroutine ???

dataTable

The name of the table with for which you want to rebuild indexes. The table must be attached.

dataHandle

The file handle for dataTable.

F If you are rebuilding an index for a symbolic column, you must also open the dictionary of the table to @DICT before calling BUILDINDEX_SUB.

indexHandle

The file handle for the index table (the !file) associated with dataTable. For example, if you are rebuilding indexes in the table SAMPLE_CUSTOMERS, you must also open !SAMPLE_CUSTOMERS and pass the file handle of the index in this parameter. You can use the system subroutine INDEX.OPEN to open the index table.

fieldInfo

An array (@FM-delimited) of indexes (columns) to rebuild. Each index to be rebuilt is one field in this array, with details about each index as values (@VM-delimited) within each field. The layout of each field is as follows:

Most of this information can be read directly from the dictionary entry of the column for which the index is being rebuilt. (See the second example program for details on where to find this information.)

One exception is the information for justification and sort direction. For Relational indexes, use this table to determine what values to pass:

flagAll

Set to true (1) if all indexes in the table are being rebuilt. This allows faster processing.

Warning! If not all indexes are being rebuilt or if you are not sure if all indexes are being rebuilt do not set this flag. You will lose index information.

Values returned

The return status of BUILDINDEX_SUB is indicated by the system variable @file.error. If the process completes successfully, the variable is null. Multiple errors are delimited with record marks (@RM). The error number appears in field 1 of each @file.error "record", and additional information about the error appears in field 2. Possible errors are:

Notes

Status line display

The BUILDINDEX_SUB subroutine displays information in the status line — first as it scans the data in the table, and then as it rebuilds the index. For tables with more than 100 rows, the status line is updated only every 100 rows. There is no option to suppress this display.

Locking and multi-user access to indexes

While you are rebuilding indexes, no other user can be updating the index (meaning that users cannot change any indexed columns throughout the table). To ensure that no other users are updating the index, the control entry *INDEXING and the 0 (zero) entry in the index (!table) are locked. During the rebuild itself, these index entries are locked: name*INDEXING, name*, ad name*ROOT.

BUILDINDEX_SUB loops until all of these entries are locked. Therefore, if another user has any of these entries in use, the rebuild process halts until the entry is available. By the same token, once the rebuild process is underway, any attempt to update the index will simply wait until the control entries are available again.

It is therefore recommended that you do not attempt to rebuild indexes during periods of heavy use, because your rebuild process could be delayed, and because while it is running, no user can be updating the indexes.

Quitting during the rebuild process

The user is able to abort the rebuild process by pressing [Esc] while a rebuild is underway. However, this leaves the indexes in an unpredictable condition; the indexes cannot be used until the are rebuilt.. You should always test to see if the process has been interrupted, and if so, to warn the user that the indexes should be rebuilt before they are used.

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

BTREE.READ (code)

Using BTREE.READ

There are times when you need direct access to indexed values. Much of the time, the system subroutine, BTREE.EXTRACT will perform this job quickly and efficiently, returning a sub-set of record keys that matches the required specifications. However, while BTREE.EXTRACT is powerful, versatile, and easy to use, it has two limitations:

_ It will only return up to 64K worth of record keys, even though there may be more keys that would match the search criteria.

_ It returns only the record keys, not the index values.

You can use system subroutine BTREE.READ to address these limitations.
BTREE.READ returns the complete index record that contains the searched-for value. Since each index record contains the record keys to the next and previous records in the index you use the record returned by BTREE.READ as a start and follow pointers from there.

Syntax Use

Figure 1 demonstrates calling BTREE.READ.

Index Leaf Record Structure

BTREE.READ returns a Btree index leaf node. Understanding the structure of the leaf node will help you understand BTREE.READ. A leaf node is a 5 field record. Each field has a different meaning.

Field 1 - Node Flag

The first field in the index leaf record contains a value of either "0", "1", or "2", where "2" denotes that this record contains index values and keys. The other values indicate that the record contains branch information and no actual index values.

Field 2 - Forward Pointer

The second field contains the record key to the next record in the index, assuming ascending order.
The index record keys take the form of <fieldname>*<optional-identifier>*<separator value>. The optional identifier is used when there is more than one index leaf record that contains a single indexed value, common in large files with relatively few index values for a field, i.e. a status code field that can contain only a few possible values. The separator value is the same as the value returned by BTREE.READ in sep. If field 2 is empty then this is the last leaf record in the index.

Field 3 - Backward Pointer

The third field contains the record key to the previous record in the index, again assuming ascending order. If field 3 is empty, then this is the first leaf record in the index.

Field 4 - Indexed Values

Field 4 contains a value-mark delimited list of index values, sorted in either left-justified (alphabetical) or right-justified (numeric). The BTREE.READ argument i references a position in this list.

Field 5 - Record Keys

Field 5, the last field in the index leaf record, contains a multivalued list of keys. Each value is associated with the index value in the same position in field 4. If more than one key is associated with an index value, then the keys are delimited with subvalue marks.


Multi-User Access

BTREE.READ does not perform any locking. If your index file is being updated by multiple users simultaneously these problems could result:

The forward or backward pointer in record could point to a non-existant record. The values in the index could change as you traverse the index. To prevent the index from changing as you traverse the index, you should lock the root node of the index (the "FieldName*ROOT" record in the indexing file) before accessing the index. Users will still be allowed to update the data file and to post new index transactions. Be sure to unlock the root when you're finished with the index. If you must allow updates while traversing the index use this strategy to account for a shifting index:

If your read of the next index record fails, reread the current record from the index. This will give you an updated version of the record with new pointers. If the new pointer fails (the read still doesn't return a record) call BTREE.READ again with using the last index value in val. This will give you a new starting position within the index from which to to start traversing. Warning! Both of these techniques could result in your program missing records or in your program processing the same record twice.

/* This program searches the customer_name index using BTREE.READ and returns all records that have an indexed value between "SMITH" and "THOMPSON". */

DECLARE SUBROUTINE BTREE.READ, FSMSG

EQU TRUE$ TO 1
EQU FALSE$ TO 0
EQU NULL$ TO "" DIM I_RECORD(5)
MAT I_RECORD = NULL$
I = NULL$
SEP = NULL$
FOUND = NULL$
I_FILEVAR = NULL$
FIELD = "CUSTOMER_NAME"
VALUE = "SMITH"
MAX_VALUE = "THOMPSON"

/* Get the sort information from the index.*/
SORT_METHOD = XLATE("!SAMPLE_CUSTOMERS", FIELD, 1, "X")
OPEN "!SAMPLE_CUSTOMERS" TO INDEX_FILE ELSE
FSMSG()
STOP
END

OPEN "SAMPLE_CUSTOMERS" TO CUSTOMER_FILE ELSE
FSMSG()
STOP
END

LOCKED = FALSE$
LOOP
LOCK INDEX_FILE, FIELD:"*ROOT" THEN
LOCKED = TRUE$
END
UNTIL
LOCKED
REPEAT

BTREE.READ(INDEX_FILE,FIELD,VALUE,SORT_METHOD,MAT,I_RECORD,I,SEP,FOUND)

/* Find the starting position in the key list in element five of the index leaf record. */

IF I > 1 THEN
POS = INDEX(I_RECORD(5), @VM, I-1) + 1
END ELSE
POS = 1
END

FLAG = NULL$
DONE = FALSE$

LOOP
/* Get the next key to process */
REMOVE @ID FROM I_RECORD(5) AT POS SETTING FLAG
READ @RECORD FROM CUSTOMER_FILE, @ID THEN
GOSUB PROCESS_RECORD
END

IF FLAG = 3 THEN
/* REMOVE sets FLAG to 3 when a value mark is found. Finding a value mark indicates the indexed value has changed. */

IF I_RECORD(4)<1,I> > MAX_VALUE THEN
/* No more valid values to process. */
DONE = TRUE$
END

END ELSE
IF FLAG ELSE
/* If flag = 0 then we have reached the end of the current leaf record and it is time to read the next record or stop. */
IF I_RECORD(2) THEN
/* There is a pointer to another record. */
MATREAD I_RECORD FROM INDEX_FILE, I_RECORD(2) THEN
/* Start at the beginning of the list of keys in the new record.*/
POS = 1
I = 1
END ELSE
/* Recovery logic goes here if you're not locking the index. */
DONE = TRUE$
END
END ELSE
/* There are no more index records. */
DONE = TRUE$
END
END
END
UNTIL DONE
REPEAT
UNLOCK INDEX_FILE, FIELD:"*ROOT" ELSE
FMSG()
END

PROCESS_RECORD:
/* Logic to process records goes here. */

RETURN

DELETELIST_SUB

DELETELIST_SUB( deleteTableName, deleteRecName )

Removes a list saved earlier with the TCL command SAVELIST or the subroutine SAVELIST_SUB.

Values returned and  Errors Returned

The return status of SAVELIST_SUB is indicated by the system variable @file.error. Multiple errors are delimited with record marks (@RM). The error number appears in field 1 of each @file.error "record", and additional information about the error appears in field 2. Possible errors are:

Under some circumstances, DELETELIST_SUB sets these values for status( ):

Correct use of DELETELIST_SUB

list = "phonelist"
table = ""     /* defaults to LISTS */
call deletelist_sub( table, list )
if status() # -2 then
  call fsmsg()
end

GETLIST_SUB

GETLIST_SUB( sourceTableName, sourceRecName, options )

Retrieves a list of keys saved earlier with the TCL SAVELIST command or with the system subroutine SAVELIST_SUB, and makes it into the currently active list (in cursor zero). If @BROWSE.MODE is true, the list is put directly into @BROWSE.LIST (up to 32K).

Values returned and Errors Returned 

The return status of GETLIST_SUB is indicated by the system variable @file.error. Multiple errors are delimited with record marks (@RM). The error number appears in field 1 of each @file.error "record", and additional information about the error appears in field 2. Possible errors are:

Under some circumstances, GETLIST_SUB sets these values for status( ):

Correct use of GETLIST_SUB

tablename = ""  ;  * table name defaults to LISTS
listname  = "SORTED_CUSTOMERS"
call getlist_sub( tablename, listname )

if @list.active then
  reccount = @file.error<2>
  call msg( "%1% rows were selected!", "", "", reccount )
  perform "LIST SAMPLE_CUSTOMERS"
end else
  if @file.error<1> = "B558" then
     text     = "Please run the Customer sort option"
     text<-1> = "before choosing this report!"
     call msg( text )
  end else
     call fsmsg()
  end ; * if @file.error
end ; *  if @list.active
call deletelist_sub( tablename, listname )
stop

SAVELIST_SUB

SAVELIST_SUB( saveTableName, saveRecName, options )

Using SAVELIST_SUB

Saves a currently-active select list to a table, from where it can be re-activated using the TCL GETLIST command or the subroutine GETLIST_SUB. The select list to be saved can be active or latent; if the list is latent, it is resolved before being saved. By default, the select list remains active after being saved.

Options

Values returned and Errors Returned 

The return status of SAVELIST_SUB is indicated by the system variable @file.error. Multiple errors are delimited with record marks (@RM). The error number appears in field 1 of each @file.error "record", and additional information about the error appears in field 2. Possible errors are:

Under some circumstances, SAVELIST_SUB sets these values for status( ):

Correct use of SAVELIST_SUB

perform "SELECT SAMPLE_CUSTOMERS LATENT (S)"
call savelist_sub( "", "CUSTLIST", "")
if status() ne -2 then
call fsmsg()
end else
reccount = @file.error<2,3>
text = "%1% rows selected and saved!"
call msg( text, "", "", reccount )
end

/* savelist is still active */
perform "LIST SAMPLE_CUSTOMERS CITY"

GETCONFIGURE (Sample Code)

error = GETCONFIGURE( configureRecord )

A function that loads an array with information about the current configuration of the system. This includes much of the information displayed by the TCL WHO command.

configureRecord

This parameter returns an array (@FM-delimited) of information about the current system. The entry CONFIGURE.RECORD.EQUS in the SYSINCLUDE table provides text constants for the positions of this array. The layout is this:

Values returned

The return value for GETCONFIGURE is a single number indicating the success of the operation:

CALCULATEX

CALCULATEX
CALCULATEX is an external function that evaluates the specified field.
result = CALCULATEX(field, dict, id, record, mv)
Using CALCULATEX
CALCULATEX differs from R/BASIC CALCULATE only in relieving
the user of the necessity to save and restore the values of
@DICT, @RECORD, and @ID.
field
Field contains the name of the dictionary field to evaluate.
dict
Dict contains the source dictionary file.
id
Put the record key of the source record in id.
record
Place the source record in record.
mv
Mv contains the value number of the source value in a
multivalued field.  This value should be 0 (zero) if the
field is single-valued.
Values returned
CALCULATEX returns the result of evaluating field in the
specified dictionary.
Correct Use of CALCULATEX
/* The following code opens a file and its associated
dictionary, then uses CALCULATEX to evaluate one multivalue
in a field from SAMPLE_CUSTOMERS. */

DECLARE SUBROUTINE FSMSG, MSG
DECLARE FUNCTION CALCULATEX

file  = "SAMPLE_CUSTOMERS"
field = "CONTACT_NAME"
dict  = "DICT SAMPLE_CUSTOMERS"
id    = 6
mv    = 2

OPEN file TO filevar ELSE FSMSG(); STOP
OPEN dict TO @DICT ELSE FSMSG(); STOP
READ @RECORD FROM filevar,id ELSE FSMSG(); STOP

result   = CALCULATEX(field, @DICT, id, @RECORD, mv)
text     = "Multivalue ":mv:" of the ":field:" field"
text<<-1>> = "for record ":id:" evaluates to
":result

MSG(text,"","","")

DRVREADY

EXIT_SYSTEM

EXIT_SYSTEM( displayMessage )

Does a clean logoff from Advanced Revelation from within an R/BASIC program. In addition to logging off, EXIT_SYSTEM accomplishes these tasks:

· Writes out any cached index updates that might be pending because BATCH.INDEXING has been invoked. For details about BATCH.INDEXING, see the Revelation Technologies Knowledge Base.

· Detaches all volumes belonging to Environmental Bonds (or other non-native filing systems) so that those filing systems can run their own cleanup operations.

displayMessage

If this parameter is passed true, the normal Advanced Revelation logoff message (W170) is displayed.

USERCONVERSION

U307A is what is known as a user code. Primarily it is in there for Pick compatibility and were never removed from the product. Below are all the user codes available:

OpenInsight and ARev ICONV

OpenInsight and ARev OCONV

ARev OCONV

(Note the square brackets around the OCONV values!)

Additionally there is an OCONV validation called a G Correlative. Essentially, it is the limited version of the field function. The format is GStartPos-1DelimiterNumValues.

StartPos is the starting position passed into the FIELD function starting position value less 1.
Delimited is the charachter passed into the FIELD function delimiter value.
NumValues is the starting position passed into the FIELD function number of values to return
For example,
OCONV( 'A*B*C*D*E*F*G*H*I','G2*3')
will return C*D*E.

Note that the G Correlative does not require the square brackets. Also note that that starting position number must be 9 or lower. Also, the starting position number is one less than the value passed into the FIELD function.

REBUILDREVBOOT_SUB

(Code)

REBUILDREVBOOT_SUB( locations )

Using REBUILDREVBOOT_SUB

When you start Advanced Revelation, the program gets its bootstrap information from a DOS file called REVBOOT. This includes the object code for the initial system programs, the network driver, the default error handler, and the text that displays while Advanced Revelation is loading.

The REVBOOT file is constructed from copies of entries in various system tables such as SYSOBJ, SYSENV, and SYSTEXT. REBUILDREVBOOT_SUB allows you to change the bootstrap information by assembling fresh copies of these entries (after you have made changes to them) and writing them out as a new copy of the REVBOOT file. The most common types of changes are:

· Changing network drivers.

· Changing the text of logon messages, such as “Welcome to Advanced Revelation”, “Processing ...”, the prompt text for passwords and account names, and the text of error messages that are displayed during logon.

· Changing the list of programs that are permanently loaded into memory while Advanced Revelation is running (the programs in INITIAL_LOAD).

For example, to change the text of a logon message, you can edit the entry called RTP1*PARMS in the SYSTEXT table. After making changes, run REBUILDREVBOOT_SUB, which will recreate REVBOOT, including the text changes that you have made.

Before writing out an updated REVBOOT file, the REBUILDREVBOOT_SUB subroutine makes a copy of the existing REVBOOT file under the name REVBOOT.OLD. Note that if you run REBUILDREVBOOT_SUB repeatedly, you will overwrite REVBOOT.OLD each time.

+ Always to back up the DOS REVBOOT file before experimenting with REBUILDREVBOOT_SUB (even though the subroutine makes one copy of your existing file). If your REVBOOT file contains errors, you will not be able to log into Advanced Revelation.

You do not need to be in the SYSPROG application to run this subroutine, but you must have access to all the system tables listed in the table under location, below.

locations

An array of information that overrides the defaults for REBUILDREVBOOT_SUB:

· The location where REBUILDREVBOOT_SUB can find certain system information (such as the logon text).

· The name of the network driver.

· The name and location of the DOS file that the subroutine creates (the default is REVBOOT).

You need to pass a value in this parameter only if you want REBUILDREVBOOT_SUB to find components for the new REVBOOT file somewhere other than their default locations or if you are changing network drivers. By specifying alternative locations for the components of the REVBOOT file, you can make changes to copies of these components and preserve the originals in case you want to restore the default values at a later time.

You can also pass information in location that causes REBUILDREVBOOT_SUB to write out the bootstrap information under a different name or to a location other than the default directory. This feature is useful if you want to create one or more alternate DOS files that you can experiment with when logging on to Advanced Revelation (by copying them to REVBOOT), or if you want to rebuild the REVBOOT file belonging to a different copy of Advanced Revelation.

The location array consists of 8 fields, most of which have two values, the first for a table name and the second for the name of a row in the table. The layout of this array, the definitions of its elements, and its default values are in the table that follows. To override a default value, pass an array that is null except for any values that you want to change.

Values returned

The return status of REBUILDREVBOOT_SUB is indicated by error values in @file.error. If there has been no error, @file.error is null. Multiple errors are delimited with record marks (@RM). The error number appears in field 1 of each @file.error "record", and additional information about the error appears in

field 2. Possible errors are:

@file.error may also contains errors values indicating problems in creating or writing the REVBOOT file at DOS. For possible values, see OSWRITE and OSOPEN in the R/BASIC manual.

Notes

Changing the network driver

Network drivers are different versions of the Linear Hash filing system object code ($RTP57A), one each for the different types of network operating systems that are supported in Advanced Revelation. A list of possible network drivers appears in the entry DRIVERTABLE in the table SYSNETWORKS. The layout of that entry is:

You can change a network driver in two ways:

· Change <1> of the DRIVERTABLE entry to the name of the new driver before running REBUILDREVBOOT_SUB.

· Pass in <3, 2> of location the name (clear text) of the new driver.

In either case, the name that you use must match exactly (case sensitive) one of the names in field 2 of DRIVERTABLE. If you are keeping the network driver object code in a table other than SYSNETWORKS, pass the name of the alternative table in <3,1> of location.

Changing the text of logon messages

You can change the change the text of logon messages in two ways:

· Modify the entry RTP1*PARMS in SYSTEXT before calling REBUILDREVBOOT_SUB.

· Copy RTP1*PARMS from SYSTEXT to another table (and optionally, to another row key name), and pass the new table name and row key in <7,1> (table) and <7,2> (row key) when calling REBUILDREVBOOT_SUB.

You must not disturb the layout of the text row, because the positions in the row are associated with particular errors and tasks (for example, position 34 of the row is the text that displays underneath the logon banner).

Changing the contents of the program stack (INITIAL_LOAD)

The row INITIAL_LOAD in the SYSENV table contains a list of programs that are loaded into memory when you first log onto Advanced Revelation. A number of these programs remain memory resident at all times for speed.

+ For details about using INITIAL_LOAD, see entries R33 and R50 in the Advanced Revelation KnowledgeBase.

To change the list of programs loaded as part of INITIAL_LOAD:

· Modify the entry INITIAL_LOAD in SYSENV before calling REBUILDREVBOOT_SUB.

· Copy INITIAL_LOAD from SYSENV to another table (and optionally, to another row key name), and pass the new table name and row key in <6,1> (table) and <6,2> (row key) when calling REBUILDREVBOOT_SUB.

Correct use of REBUILDREVBOOT_SUB

/* an example of how to change the network driver */
location = ''

* must match a name in DRIVERTABLE<2> in SYSNETWORKS
location<3,2> = "Novell NetWare"
call rebuildrevboot_sub( location )
if @file.error then
call fsmsg()
end
stop