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.

By default, 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 the PL/I file with a UNIX file. The default file would be F. To change the name, use the title option of the DEFAULT_FILE_NAME environment option. Refer to Section 5.6, “DEFAULT_FILE_NAME Option” for more information.

The following sections describe in more detail how 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 a POSIX 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.

This file specification completely defines a file on the local system. When accessing the file OUTFILE, the program will be written to the file /usr/payroll/january.

OPEN FILE (OUTFILE)
TITLE ('/usr/payroll/january');

The following is an example of using a variable to specify the title:

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.

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.

If the value of the specified title begins with a dollar sign ($) the value is interpreted as an environment variable and substituted accordingly. If the substituted value contains a dollar sign ($) it is also interpreted as an environment variable. This process terminates when no further substitutions can be made or there are no more dollar signs.

Upon completion of the translation phase, if the DEFAULT_FILE_NAME option of the ENVIRONMENT attribute is used, the name associated with the file is merged with the DEFAULT_FILE_NAME option.

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. Note that the final file specification cannot exceed the value of MAXPATHLEN as defined in <sys/param.h>.

Before executing a program at the shell level, you can create an environment variable to assign a UNIX 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 OUTPUT;

The local file specification created on the local system is INFILE.

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

% setenv NEWFILE /usr/users/you/databases/phonebook

/usr/users/you/databases/phonebook

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

STATE_NAME = NEBRASKA

STATES = /usr/BACKUP

They also assume the following current default device and directory:

/usr/users/malcolm

Example 1:

DECLARE STATES FILE RECORD OUTPUT;
OPEN FILE(STATES) TITLE ('/usr/STATE.DATA/NEVADA');

Steps:

Final Specification: /usr/STATE.DATA/NEVADA

Example 2:

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

Steps:

Final Specification: /usr/users/malcolm/NEBRASKA

Example 3:

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

Steps:

Final Specification: /usr/BACKUP

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 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 file system or from the PL/I run-time system. Note that file system errors are mapped to RMS (VAX Record Management Services) errors by the PL/I run-time library for compatibility with VAX PL/I.

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 the system include file $RMSDEF (/usr/lib/cmplrs/pli100/usr/include/rmsdef.in).

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 UNIX 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:

PL/I unhandled exception at 0x00401380:
PL/I ERROR condition.
PL/I UNDEFINEDFILE condition on file 'INFILE'.
FILENAME: '/usr/users/tim/databases/myfile.dat'.
FILENAME, FNF, File not found.

In this example, the error occurred because an OPEN statement could not find the specified file. This fatal error terminates the program.