The File System

In a PL/I program, all I/O operations are performed on a file, using the name of a file constant or file variable. When the file is opened, PL/I associates the name of the file constant with a specific device or file on the computer system.

When a file variable is specified in an OPEN statement or in an I/O statement, the name used is that of the file constant with which the variable is currently associated. For example:

DECLARE F FILE,
        G FILE VARIABLE;

        G = F;
        OPEN FILE(G);

In this example, F is a file constant and G is a file variable assigned the value of F. In the OPEN statement, PL/I uses the name F to associate PL/I file with an OpenVMS file. The default file would be F.DAT.

The following sections describe in more detail how Endless PL/I associates a file constant with a device or file.

When you specify the TITLE option on an OPEN statement, you can include all or part of an OpenVMS file specification to indicate the file or device to be associated with the PL/I file. The following examples illustrate the use of the TITLE option.

OPEN FILE (OUTFILE)
     TITLE('DB1:[PAYROLL.DAT]JANUARY.LOG;2');

This file specification completely defines a file on the local OpenVMS system.

OPEN FILE (PRINTFILE) PRINT TITLE('LPC0:SAMPLE.DAT');

This output file will be directed to LPC0:, the system printer device. The listing file will have the title SAMPLE.DAT on its burst page. OpenVMS spools low-speed I/O devices such as printers by accumulating data for the device in a file, and then queuing the file for processing when it is closed.

NAME = 'TEST'||COUNT;
⋮
OPEN FILE(NEWFILE) OUTPUT TITLE(NAME);

The specification of this file is determined by the value of COUNT. For example, if COUNT is 5 when this OPEN statement executes, the file created is TEST5.DAT.

When no TITLE option is specified, PL/I supplies a default value for the file's title. The default title is the name of the file constant associated with the PL/I file. Whenever a title does not completely specify a file, PL/I takes the following steps, in order:

If the file specification that is finally achieved is invalid or represents an illegal device or file (for example, an input file cannot be found), the UNDEFINEDFILE condition is signaled.

At DCL command level before executing a program, you can create a logical name to assign an OpenVMS file specification to the identifier of a PL/I file constant or to a value specified in a TITLE option. For example, suppose your PL/I program declares and opens a file as follows:

DECLARE INFILE FILE;
⋮
OPEN FILE (INFILE) RECORD INPUT;

Before running the program, you might associate an OpenVMS file with the identifier INFILE:

$ DEFINE INFILE DB1:[TEMP]A.DAT

The DEFINE command assigns the PL/I file INFILE the OpenVMS file specification DB1:[TEMP]A.DAT. In OpenVMS terms, the name INFILE is a logical name, and the name DB1:[TEMP]A.DAT is an equivalence name for the logical name.

You can also use the DEFINE command to specify alternate device or file equivalents for the PL/I default file constants SYSIN and SYSPRINT. For example, to redirect output for the default file SYSPRINT, you could issue the following command:

$ DEFINE SYSPRINT TEST.OUT

While this assignment is in effect, any PL/I procedure that outputs data to SYSPRINT (without opening SYSPRINT with an explicit title) will create a file named TEST.OUT on the current default device.

Logical names can also be established by other commands. For example, you can specify a logical name for a device when you enter an ALLOCATE or MOUNT command while placing the device on line. For example:

$ ALLOCATE
$_Device:   MT:
$_Log_Name: INFILE
_MTA1: ALLOCATED

This ALLOCATE command allocates a tape drive and establishes the logical name INFILE for it. When a PL/I program reads from the file INFILE, the system translates the name INFILE and uses the tape MTA1: as the input device.

OPEN FILE(INFILE) TITLE ('NEWFILE');

$ DEFINE NEWFILE LARGO.TXT

TITLE ('STATES.')

TITLE ('_DBB1:[APPLIC.FILES]MASTER.SRC')

Use the DEFAULT_FILE_NAME option of the ENVIRONMENT attribute to specify default values for a file specification when a file is opened.

For example:

OPEN FILE (REPORT) RECORD OUTPUT
           ENVIRONMENT (
                    DEFAULT_FILE_NAME('.LIS'));

The default file type LIS will be applied in the following cases:

PL/I uses the punctuation in the DEFAULT_FILE_NAME option to determine which portion of the file specification is specified. Thus, the period (.) in the preceding example indicates that the value is a file type. An unpunctuated name is treated as a file name; a name terminated by a colon (:) is treated as a device name (and can therefore be a logical name).

When the DEFAULT_FILE_NAME option is not specified for a file, and no file type is specified, PL/I supplies the default file type DAT.

PL/I applies the value of the DEFAULT_FILE_NAME option after it establishes the file's title. Thus, in the preceding example, the title, REPORT, is established before the value '.LIS' is applied. Note that the only time a file name in a DEFAULT_FILE_NAME option is used is when the TITLE option specifies a null string; that is, the TITLE option is specified as follows:

TITLE('')

A DEFAULT_FILE_NAME option can specify any portion of a file specification. For example:

DECLARE REMOTE_FILE FILE RECORD INPUT
       ENV(DEFAULT_FILE_NAME(
         'RONDO::DBB2:[MALCOLM].TXT'));

This option specifies a node name, device, directory, and file type. The file name must be supplied when the file is opened. For example:

OPEN FILE(REMOTE_FILE) TITLE('ALLEGRO');

This statement opens the file RONDO::DBB2:[MALCOLM]ALLEGRO.TXT.

Another OPEN statement for the file can specify a different TITLE option, for example, TITLE('ANDANTE'), to open a different file.

After logical name translation and after values supplied by the DEFAULT_FILE_NAME option, if any, are applied, the defaults that the file system applies are as follows:

The following examples enumerate the steps in completing a file specification. All examples assume that the following logical name assignments are in effect:

They also assume the following current default device and directory:

DBB1:[MALCOLM]

In the following example, the value in the TITLE option represents the complete file specification:

DECLARE STATES FILE RECORD OUTPUT;
OPEN FILE(STATES) TITLE ('_DMA2:[STATE.DATA]NEVADA.DAT;2');

Thus, the final specification is: _DMA2:[STATE.DATA]NEVADA.DAT;2

The following example uses several steps to obtain the file specification:

DCL STATES FILE INPUT ENVIRONMENT(
                    DEFAULT_FILE_NAME ('[STATE.FILES].DAT'));
OPEN FILE(STATES) TITLE ('MISSOURI');

The steps are:

The following example includes the translation of a logical name:

DECLARE STATES FILE RECORD OUTPUT;
OPEN FILE(STATES) TITLE ('STATE_NAME');

The steps are:

In the following example, no title is specified and the default title is applied:

DCL STATES FILE RECORD OUTPUT;
OPEN FILE (STATES);

The steps are:

The following example specifies a tape file:

DCL TAPEFILE FILE RECORD ENVIRONMENT(
          DEFAULT_FILE_NAME('TAPEFILE:'));
OPEN FILE(TAPEFILE) OUTPUT TITLE('TAPE1.FIL');

The steps are:

An ON-unit can be a generalized error-handling routine, written so that it responds to specific errors or prints an error message. Following are the PL/I built-in functions that provide meaningful information in an ON-unit to handle a file system error:

Whenever an error is signaled, the built-in function ONCODE makes available the condition value associated with the specific error. When a PL/I program is executing under control of the OpenVMS operating system, the value returned by the ONCODE built-in function is a unique 32-bit condition value that indicates the reason for the error. This value is from the system, from RMS, or from the PL/I run-time system.

The built-in function ONFILE returns a character string giving the name of the file constant on which the error occurred.

If the file was being accessed by key, the ONKEY built-in function returns the key value that caused the error to be signaled.

You can write an ON-unit to detect and correct errors that occur during file operations. The following example shows an ON-unit that detects whether a record with a given key value was not found or whether an attempt was made to write a record whose key duplicates the value of an existing key.

ON KEY(STATE_FILE) BEGIN;
  %INCLUDE $RMSDEF;

/* Check for a record not found */
     IF ONCODE() = RMS$_RNF       /* if record not found */
     THEN DO;
        PUT SKIP EDIT(STATENAME,'Not found.')
                 (A,X,A);
        STOP;
        END;

/* Check for duplicate key */
     ELSE
       IF ONCODE = RMS$_DUP
       THEN DO;
          PUT SKIP EDIT('Record already exists for',
                       STATENAME)
                 (A,X,A);
          STOP;
          END;
   END;

In this example, the ON-unit declares symbolic names for two specific status values returned by ONCODE:

In an ON-unit for the KEY condition, ONCODE may also return the value associated with the status code RMS$_KEY. This code indicates that a key value is invalid; for example, it is an incorrect data type.

The symbolic names for RMS status codes are declared as %REPLACE constants in module $RMSDEF of PLI$STARLET.

If a file system error occurs during the execution of a PL/I statement, the PL/I run-time system signals either the specific PL/I condition name or the ERROR condition. If no user-specified ON-units exist to handle either the specific PL/I condition or the ERROR condition, PL/I performs its default condition handling.

If any active procedure specified OPTIONS (MAIN), a default PL/I condition handler is present and executed. It prints a PL/I run-time error message. If there is no default PL/I handler, the error signal is passed to the default condition handler established by the OpenVMS system, which prints the message associated with the RMS error. If the error was a fatal error, the handler terminates the program; otherwise, the program continues.

The following example illustrates the type of message that the PL/I run-time system displays when an error occurs during an I/O operation:

%PLI-F-ERROR, PL/I ERROR condition.
-PLI-I-IOERROR, I/O error on file 'STATE_FILE'
-PLI-I-FILENAME, File name:'_DB7:[PROJECT]STDATA.DAT;'
-PLI-I-NOTKEYD, Not a KEYED file.
%TRACE-F-TRACEBACK, symbolic stack dump follows

module name     routine          line   relative PC  absolute PC
FLOWERS         BEGIN%35           35      00000085     00000C88
FLOWERS         BEGIN%29           29      000000BD     00000C02
FLOWERS         FLOWERS            25      000000D3     00000B42

In this example, the error occurred because a keyed I/O statement was specified for a file lacking the KEYED attribute.