Using KSAM/XL and KSAM 64 (32650-90886)

Chapter 3 37
Obtaining File Information
Accessing Key Information From a Program
Accessing Key Information From a Program
Like the FGETINFO intrinsic, the FGETKEYINFO intrinsic provides access and status
information about the keys of a KSAM file. It provides detailed information about the key
location, type, and length in a parameter format similar to the FOPEN intrinsic key
parameter. The FGETKEYINFO intrinsic also provides access information, such as a count of
the number of times the key file has been accessed by various intrinsics, or the date and
time the file was created, closed, updated, or written to.
Accessing User-Defined Labels
A user label is an optional method of adding documentation to your file. You can write your
own labels to a KSAM file with the FWRITELABEL intrinsic. For example, you can use a
label to enter the date and time of the last file update. These labels are read with the
FREADLABEL intrinsic.
Specify the number of user labels to be created in the
userlabel parameter of the FOPEN
intrinsic. In order to write labels, the file must be open. To do so, set the
aoptions
parameter of the FOPEN intrinsic to one of the write, input/output, or update access
specifications.
The following example shows the intrinsic call to write information to the second file label.
FWRITELABEL(KFILNUM,LABELBUF,60,1);
In this example, the 60 halfwords of text contained in the variable LABELBUF are to be
written in the second user label. Note that label numbering starts with zero. The second
label is identified by the number 1 in the last parameter. If this parameter contains zero or
is omitted, the first label is written.
You can read the contents of user labels using the FREADLABEL intrinsic. During the
normal reading of a file, user labels are skipped. The FREADLABEL intrinsic, therefore,
should be called immediately after the file has been opened. To read a user label, the file
must be opened with read, input/output, or update access, and the user labels to be read
must be identified.
Issue the following FREADLABEL intrinsic call to read the user label written in the previous
example.
FREADLABEL(KFILNUM,LABEL2,,1)
The variable LABEL2 returns the contents of the second user label. By default, the call
returns 128 halfwords from the label.