2 Sort Statements and Functions

The WORKFILE IS # Statement

The WORKFILE IS # statement describes the hierarchical structure on which FIND, QFIND and SORT will operate, where the scratch area is for SORT, and where the results of executing a FIND, QFIND or SORT are stored.

WORKFILE IS # file number [ ;THREAD IS

[ set id , ... ] set id ] thread list

(up to 10 sets allowed)

The parameters are:

file number
A numeric expression having an integer value from 1 though 10, and used to identify a file previously defined by an ASSIGN statement.
set id
A numeric or string expression used to identify a data set. If numeric, this parameter references a data set number for the current data base (specified in the last DBASE IS statement). If a string, this parameter references a data set name for the current data base.
path id
A numeric expression having an integer value from 1 through 8. This expression selects which data path to use between the first data set specified (set id) and the next in the thread list. It is needed only when more than one path exists between two sets being linked in the thread. If only one path exists for the data set specified, it is not necessary to list the path id parameter.
link
An Eloquence variable which is currently linked via an IN DATA SET statement to an item found in the detail data set to which it is attached. The variable must match in type and length the search item in the master data set which follows in the thread list. If the variable refers to a sub-item, it may only be the first sub-item.
NOTE: The path or link parameters cannot be specified on the last data set in the thread list, since these operations specify a relationship between the set to which it is attached and the next set listed in the thread.

Some examples of the WORKFILE IS # statement are: 

  WORKFILE IS#1; THREAD IS"CUSTOMER"
  WORKFILE IS#X+3; THREAD IS "CUSTOMER":2, "DATE"
  WORKFILE IS#8; THREAD IS "CUSTOMER":2, "ORDER"
Up to 10 data sets can be specified for any thread list. The number of sets in the list is referred to as the thread length. Each set must be related to the sets on either side of it (or one side if it is at the end of the thread) by a path in the data base (or a synthetic path using the LINK option). This defines the hierarchical structure, with the leftmost set in the thread list usually being the highest (usually the least commonly occuring) in the hierarchy. Successful execution of WORKFILE IS # converts the file into a workfile. To convert a file to a workfile, the file must be ASSIGNed in exclusive mode. The file remains a workfile until either another file is assigned in its place (same file number) or it is de-assigned. Closing the data base to which the workfile pertains automatically de-assigns the workfile.

The workfile is used to store all pointers generated by FIND, QFIND and SORT BY operations. Initially, the workfile contains no pointers, so any attempt to access them (via READ #) will result in an error. The REC function returns 0 to indicate this null state. Pointers can be put in the workfile by executing SORT BY, FIND, QFIND, FIND ALL or PRINT #.

The workfile is composed of logical records whose lengths in bytes are 4 times the thread length. Thus, a 4-byte pointer is stored for each set in the thread in any given logical record. Pointers may range in the value from 1 to the capacity of the set to which they pertain. (The first pointer in the record corresponds to the first set in the thread, the second pointer corresponds to the second set, and so on.)

In the case where more than one path connects two adjacent sets in the thread, it is necessary to specify which path is to be used. This is done by suffixing the first of the sets with a ":" and following that with a path id. The path id for a particular path is determined by using the schema listing. To find the path with path id n, for example, scan the detail for the nth occurrence of the master set name. If the path id is not specified, 1 is assumed.

A method exists for defining data set relationships independent of the data base structure. This method is used to link a detail data set to a master data set in the thread list. This is done by using the LINK option, which specifies an item in the detail data set and is used to perform a calculated access into the specified master data set. This item must match the type and length of the search item in the master data set (which is then the set id following the LINK in the thread list).

All SORT BY, FIND and QFIND operations work with the current workfile. Executing another WORKFILE IS # deactivates the current workfile and defines a new one. All subsequent SORTs, QFINDS and FINDs then work on the new file. The information in the old workfile is still intact, however, and can be accessed via READ # and PRINT # statements.

Since it may by desirable to return to do additional FINDs and SORTs on the previous workfile, a method is provided for saving and reactivating a workfile. This is done by executing another WORKFILE IS # which does not include the thread list. This will deactivate (but not erase) the current workfile and allow you to activate an old workfile. Do not attempt to reactivate the workfile by respecifying the thread list, since this loses all information currently in the file by resetting WFLEN to 0.

Expressions are allowed in all WORKFILE IS # parameters. When invoking multiple-line function subprograms, however, these subprograms cannot execute SORT BY, FIND, WORKFILE IS #, IN DATA SET or DBASE IS statements.

Eloquence Sort Manual - 19 DEC 2002