HP 3000 Manuals

KSAM/3000 Reference Manual

FWRITELABEL 

INTRINSIC NUMBER 20

Writes a user file label.

                    IV      LA     IV     IV      O-V
     FWRITELABEL(filenum,target,tcount,labelid);

The FWRITE LABEL intrinsic writes a user-defined label onto a disc file.
This intrinsic overwrites old user labels.

PARAMETERS 

filenum          integer by value (required) 

                 A word identifier specifying the file number of the file
                 to which the label is to be written.

target           logical array (required) 

                 Contains the label to be written to the disc file.

tcount           integer by value (optional) An integer specifying the
                 number of words to be transferred from the array.

                 Default:  128 words. 

labelid          integer by value (optional) An integer specifying the
                 number of the label to be written.  The first label is
                 0.

                 Default:  A default value of 0 is assigned. 

CONDITION CODES 

CCE              Request granted.

CCG              Request denied because the calling process attempted to
                 write a label beyond the limit specified in FOPEN when
                 the file was opened.

CCL              Request denied because an error occurred.

SPECIAL CONSIDERATIONS 

Split stack calls permitted.

USING FWRITELABEL 

You can write your own labels to a KSAM file with the FWRITELABEL
intrinsic.  Such labels are useful to hold information related to the
file but not part of it.  For example, you might use a label to contain
the date and time of the last update to the file.

The number of labels that are allowed to be written to any file must be
specified in the userlabels parameter of the FOPEN intrinsic when the
file was created.  If an attempt is made to write more labels than are
specified for the file at creation, a CCG condition is returned.

In order to write labels, as with any other write request, the file must
be opened for write access.  This means that the aoptions parameter of
FOPEN must be set to one of the following:

         bits 12:4 = 0001 (octal 1) \
                     0010 (octal 2) |- write only access
                     0011 (octal 3) /
                   = 0100 (octal 4) <------ input/output access
                   = 0101 (octal 5) <------ update access

Suppose file KDATA has been created as follows:

         KFILNUM:=FOPEN(KDATA,%4004,4,,,,2);
                                 /  |    |
                                /   |    |
                               /    |    |
                  new KSAM file,    |   number of labels
                  ASCII coded       |
                                    input/output access

Then a total of two labels, each with a maximum of 128 words, can be
written to this file with FWRITELABEL. To write a second label consisting
of 60 words stored in the array LABELBUF, use the following call:

         FWRITELABEL(KFILNUM,LABELBUF,60,1);

Note that label numbering starts with zero, so the second label is
identified by the number 1.

MPE/iX 5.0 Documentation