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.
Printable version
