HP 3000 Manuals HP 3000 Manuals
FREADLABEL
INTRINSIC NUMBER 19
Reads a user file label.
IV LA IV IV O-V
FREADLABEL(filenum,target,tcount,labelid);
The FREADLABEL intrinsic reads a user-defined label from a disc file.
Before reading occurs, the user's read-access capability is verified.
Note that MPE automatically skips over any unread user labels when the
first FREAD intrinsic call is issued for a file; therefore the FREADLABEL
intrinsic should be called immediately after the FOPEN intrinsic has
opened the file.
PARAMETERS
filenum integer by value (required)
A word identifier supplying the file number of the file
whose label is to be read.
target logical array (required)
An array in the stack to which the label is to be
transferred. This array should be large enough to hold
the number of words specified by tcount.
tcount integer by value (optional)
An integer specifying the number of words to be
transferred from the label. Tcount must not be greater
than 128 words.
Default: 128 words.
labelid integer by ualue (optional) An integer specifying the
label number where the first user label is numbered 0.
Default: A default value of 0 is assigned.
CONDITION CODES
CCE The label was read
CCG The intrinsic referenced a label beyond the last label
written on the file.
CCL The label was not read because an error occurred.
SPECIAL CONSIDERATIONS
Split stack calls permitted.
USING FREADLABEL
If the KSAM file contains one or more user labels (written with
FWRITELABEL), you can read these labels with the FREADLABEL intrinsic.
During the normal file reads with FREAD, FREADC, FREADBYKEY, or FREADDIR,
any user labels are ignored. The number of user labels that can be
written to the file is specified by the userlabels parameter of FOPEN, or
in the BUILD command of KSAMUTIL.
Since MPE checks to insure that you have opened the file with read access
before executing FREADLABEL, you must open the file with an FOPEN
aoptions setting that permits reading. It must be one of the following:
bits 12:4 = 0000 (octal 0) read only access
= 0100 (octal 4) input/output access
= 0101 (octal 5) update access
In addition, the FOPEN userlabels parameter must be set to a value of 1
or greater depending on the number of labels that may be written to the
file.
Suppose you have opened the file KDATA with the following call:
KFILNUM:=FOPEN(KDATA,3,4,,,,2);
/ ^ \
/ | \
/ | number of labels
old user/ |
domain |
|
|
input/output access
You might read the second label with the following call:
FREADLABEL(KFILNUM,LABELBUF,,1)
This reads the second label into the array LABELBUF. Note that label
numbering begins with 0; if the labelid parameter were zero or omitted,
then the first label would be read. By default, the number of words read
from the label is 128.