FREADLABEL

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.

FREADLABEL

Technical documentation

» Table of Contents

PARAMETERS

CONDITION CODES

SPECIAL CONSIDERATIONS

USING FREADLABEL