File-Handling Built-In Subroutines

The DISPLAY built-in subroutine returns information about a specified file. Its calling sequence is as follows:

CALL DISPLAY (file-reference,variable-reference);

The format of the data returned by DISPLAY is defined in the data structure PLI_FILE_DISPLAY. This structure is declared in the text module PLI_FILE_DISPLAY in the default INCLUDE library PLI$STARLET (the PL/I compiler searches this library by default when it compiles a PL/I program). Each member of PLI_FILE_DISPLAY contains, on return from a call to DISPLAY, a value associated with the file for which information is requested. To refer to a value, you refer to the corresponding member name in the structure. Tables 9.2 through 9.4 summarize the members of the structure as follows:

You declare the structure PLI_FILE_DISPLAY with the BASED attribute; thus, to use this variable you must also declare a pointer variable to reference the structure and use an ALLOCATE statement to allocate storage for it before calling DISPLAY. For example:

%INCLUDE PLI_FILE_DISPLAY;
DECLARE STATE_FILE FILE RECORD KEYED,
        FILEPTR POINTER;
        OPEN FILE(STATE_FILE);
        ALLOCATE PLI_FILE_DISPLAY SET (FILEPTR);
        CALL DISPLAY (STATE_FILE,FILEPTR->PLI_FILE_DISPLAY);

Following this call to DISPLAY, you can reference any of the members of FILEPTR->PLI_FILE_DISPLAY to determine information about the file STATE_FILE. The following statements use the EXPANDED_TITLE field to display the expanded file specification of STATE_FILE and the INDEXED and NUMBER_OF_KEYS fields to display the number of keys in the file:

PUT SKIP EDIT('File',FILEPTR->EXPANDED_TITLE,
                             'opened for input')
             (A,X,A,X,A);
IF FILEPTR->INDEXED THEN PUT SKIP EDIT
      ('It is indexed with',FILEPTR->NUMBER_OF_KEYS,'keys')
      (A,X,A,X,A);

If you do not use the structure PLI_FILE_DISPLAY, as shown in this example, you must provide a structure that has the same declaration as PLI_FILE_DISPLAY. To obtain a copy of PLI_FILE_DISPLAY, use the LIBRARY command. For example:

$ LIBRARY/TEXT/EXTRACT=PLI_FILE_DISPLAY/OUTPUT=FILESTRUC.PLI -
$_SYS$LIBRARY:PLI$STARLET

Here, FILESTRUC.PLI is the name of the output file into which the LIBRARY command will copy PLI_FILE_DISPLAY.

Table 9.2, “ENVIRONMENT Option Values Returned by DISPLAY” summarizes the values returned by DISPLAY that correspond to ENVIRONMENT options and the data type of each structure member. For information on ENVIRONMENT options, see Chapter 7, Options of the ENVIRONMENT Attribute.

Table 9.3, “File Attribute Information Returned by DISPLAY” summarizes the file attribute information returned by DISPLAY. All names in the table are level-2 members of the structure PLI_FILE_DISPLAY.

Table 9.4, “Device Information Returned by DISPLAY” lists the names of the structure members that contain information about the device to which a file is written or from which the file is to be read. All of the names in Table 9.4, “Device Information Returned by DISPLAY” are level-3 members of the structure PLI_FILE_DISPLAY; they each appear within the following minor structures, which have identical declarations:

If the field PLI_FILE_DISPLAY.DEVICE.SPL is true, then the members of the minor structure DEVICE contain information about the device that is spooled. Members of minor structure PLI_FILE_DISPLAY.SPOOLING_DEVICE contain information about the intermediate, or spooling, device.

All fields within these structures are BIT(1) values.

The EXTEND built-in subroutine increases the amount of space allocated to a disk file. Its calling sequence is as follows:

CALL EXTEND (file-reference,integer-expression);

Use the EXTEND built-in subroutine to explicitly extend a file during processing. Normally, RMS extends a file automatically, using a current extension size value, whenever an output operation causes a file to exceed its allocated space. The default value that RMS uses to extend a file is set by the ENVIRONMENT option EXTENSION_SIZE.

You can improve the performance of a program that is going to add a large number of records to a file by making an explicit call to EXTEND before adding records to the file. If the call to EXTEND occurs before records are added, then RMS does not need to extend the file during the actual I/O operations.

The FLUSH built-in subroutine writes all RMS buffers that have been modified and preserves all of the file attributes of the file. This subroutine provides the ability to checkpoint a file during its processing and ensure its integrity. Its calling sequence is as follows:

CALL FLUSH (file-reference);

Use the FLUSH subroutine to explicitly request RMS to write all internal file buffers back to the file. This subroutine is called implicitly by the REWIND and NEXT_VOLUME built-in subroutines.

The FREE built-in subroutine unlocks all the locked records in a specified file. Its calling sequence is as follows:

CALL FREE (file-reference);

The NEXT_VOLUME built-in subroutine performs the positioning and labeling functions necessary when the next volume is required during I/O to a magnetic tape file that spans more than one physical tape volume. Its calling sequence is as follows:

CALL NEXT_VOLUME (file-reference);

When a multivolume tape file is being read or written, volume switching is normally transparent to the PL/I program. RMS and the magnetic tape Ancillary Control Program (ACP) perform all the steps necessary to ensure that the next required volume is physically mounted, initialized, and verified.

However, when a program must advance to the next volume before reaching the end of the current volume on input, or before the end of the tape is reached on output, it can call the NEXT_VOLUME built-in subroutine. This subroutine performs all the necessary volume checking when a multivolume tape file is being read. When a file is being written, the subroutine writes the appropriate information on the output tapes.

For more detailed explanations of volume switching, see the OpenVMS Record Management Services Reference Manual and the OpenVMS DCL Dictionary.

The RELEASE built-in subroutine unlocks a specified record in a file. Its calling sequence is as follows:

CALL RELEASE (file-reference,variable-reference);

The REWIND built-in subroutine positions a file so that the next record to be read will be the first record in the file or index. Its calling sequence is as follows:

CALL REWIND (file-reference);

Use this subroutine to begin processing a file at its logical beginning. This subroutine is valid for disk files of all organizations and for sequential files on tape volumes. The position of the file following the call to the REWIND subroutine is as follows:

You can also use the REWIND built-in subroutine to reposition a stream file after an end-of-file condition. Normally, if end-of-file (Ctrl/z on a terminal) is entered during an input operation on a stream input file, the PL/I program must close the input file and reopen it before any more data can be read. However, an ENDFILE ON-unit can be written as follows:

ON ENDFILE(STREAMFIL) CALL REWIND(STREAMFIL);

This ON-unit calls the REWIND built-in subroutine each time an end-of-file condition is encountered for the file constant STREAMFIL. The REWIND built-in subroutine repositions the stream file at its beginning so that the program can continue reading input.

The SPACEBLOCK built-in subroutine positions a file forward or backward a specified number of blocks. This subroutine can be used to process unlabeled magnetic tapes, as well as sequential disk files that are being processed with block I/O. Its calling sequence is as follows:

CALL SPACEBLOCK (file-reference,integer-expression);