System Functions
KEY( ) Return Key of Next Record
   
Format KEY(chan[,fileopt])

Where:

chan Channel or logical file number of the file to reference.
fileopt Supported file options:
END=stmtref End-of-File transfer
ERR=stmtref Error transfer
KNO=num | string$ File access key number (num) or name (string$)
KEY=keyvalue Key value to convert/generate See Generate Key below
IND=num Record index
RNO=num Record number.
stmtref Program line number or statement label to which to transfer control in case of an error / exception.
Returns Key of next record in file
   
Description The KEY( ) function returns the key of either the next record in the file specified or, via the IND= or RNO= options, the key of the record at the index/record number specified. The result is based on:
  • The current file access key or,
  • The access key specified using the KNO= option.

For more information, see File Handling in the ProvideX User's Guide.

   
Generate Key option The new KEY function allows the user to get the internal generated key value for a file when specifying a KEY= option in the function. This feature is supported for those files/tables that allow multi-segment alternate keys such as standard PVX keyed files, EFF files, Databases, and Memory tables.

Internally when dealing with a mutliple segment alternate key the system generates a simple string consisting of the various field values used to reference the file. When accessing a file by a multi-segmented key, the programmer can specify each of the segment values to be provided in the KEY= clause of the I/O operation with each key segment separated by a colon. For example READ (1, KEY=A$:B$:C$) tells the system to use A$ as the value for the first field segment of the key, B$ for the second, and C$ the third.

The KEY function allows you to specify a KEY= clause with the segments in order to return the generated key based on the segments you provided.

For example, a multi-segment key with the following segments: the first is 10-characters long, the second is 5-characters long, and the third is 5-characters long. A KEY(fileno, KEY=A$:B$:C$) will return a string comprised of the individual key elements, each $00$ padded to the corresponding lengths of the multi-segment key. Therefore, A$ would be a length of 10, B$ would be a length of five, etc.

The KNO= clause can be specified in order select the specific key you want generated.

A typical example might be to set the BEGIN or END values in a SELECT directive as in:

SELECT .... FROM <fileno> BEGIN KEY(<fileno>, KEY=S1$:S2$:S3$)
....
NEXT RECORD

A KEY function that specifies a KEY= clause does not affect the current status or position of the file.

Key generation is +PxPlus Exclusive
   
Example 0010 OPEN (13)"CUSTNO"
0020 LET K$=KEY(13,END=1000)
0030 READ (13,KEY=K$)R$
0040 PRINT "Key: ",K$," Data: ",R$
0050 GOTO 0020
1000 PRINT "End-of-file"
1010 END