FWRITELABEL

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.

FWRITELABEL

Technical documentation

» Table of Contents

PARAMETERS

CONDITION CODES

SPECIAL CONSIDERATIONS

USING FWRITELABEL