Options of the ENVIRONMENT Attribute

The APPEND option opens an existing file for output so that new records are added following the current end-of-file. The format of this option is as follows:

APPEND [ (boolean-expression) ]

Use the APPEND option to open a file and position it at the end-of-file. For example, to add records at the end of a file, you can open the file as follows:

DECLARE LISTFILE FILE SEQUENTIAL OUTPUT;
⋮
OPEN FILE(LISTFILE) ENVIRONMENT(APPEND);

This OPEN statement opens the file LISTFILE. The file is positioned at its current end-of-file.

The BLKSIZE option sets the size of a buffer in BUFFERED file. This option is valid only with BUFFERED files and is ignored otherwise. The format of this option is:

BLKSIZE(size)

A positive integer or a fixed binary(31) static variable specifying the maximum block size for the file. Valid values range from the current record size to 32767 bytes. Note that the actual length of a variable-length record includes the four control bytes containing length information.

Although PL/I provides a default of the current record size, this default will not give you any of the advantages of buffered I/O. To improve performance when using buffers to write to a file, specify a block-size that is a multiple of the record size plus any control bytes.

The CONSECUTIVE option specifies that records in a file are placed in physical sequence. Once the location of one record is determined, the next record location can be determined by its physical position in the file.

CONSECUTIVE [ (boolean-expression) ]

The CONSECUTIVE option is enabled by default; you need not specify it explicitly.

The DEFAULT_FILE_NAME option specifies default file name for a file. Its format is:

DEFAULT_FILE_NAME [ (character-expression) ]

The next example shows how to open the file /usr/users/tim/employee.dat:

OPEN FILE (INFILE) INPUT TITLE('employee')
       ENVIRONMENT(DEFAULT_FILE_NAME('/usr/users/tim/*.dat'));

The following example shows how to open the file /tmp/workfile:

OPEN FILE (INFILE) INPUT TITLE('workfile')
       ENVIRONMENT(DEFAULT_FILE_NAME('/tmp/'));

The DELETE option specifies that the file is to be deleted when it is closed. The format of this option is:

DELETE [ (boolean-expression) ]

Use this option to delete an existing file. For example:

DECLARE INFILE FILE;
OPEN FILE (INFILE) ENVIRONMENT (DELETE);
CLOSE FILE(INFILE);

When this CLOSE statement is executed, the file associated with the PL/I file constant INFILE is deleted.

The F, FB, FS, and FSB options all equate to the dec/ansi dialect FIXED_LENGTH_RECORDS option. Blocking and spanning are unsupported. The format of this option is:

F [ (boolean-expression) ]

See Section 5.11, “FIXED_LENGTH_RECORDS Option” for more information.

When the FILE_ID option is specified in the opening of an existing file, PL/I uses the value specified in the FILE_ID option to locate the file. The format of the option is:

FILE_ID(variable-reference)

Use the FILE_ID_TO option to obtain the file identification when you create a file. Its format is:

FILE_ID_TO(variable-reference)

This option allows you to save the internal file identification of a file created with the TEMPORARY option so that you can access the file later and eventually delete it.

For an example of the FILE_ID_TO and FILE_ID options used for temporary files, see the following description of the TEMPORARY option.

The FIXED_LENGTH_RECORDS option specifies that all records in the file are to be of the same length. If you do not specify this option when you create a file, the records in the file will be variable length by default. The format of this option is:

FIXED_LENGTH_RECORDS [ (boolean-expression) ]

When the FIXED_LENGTH_RECORDS option is specified for the creation of a file, the size of each record can be specified with the MAXIMUM_RECORD_SIZE option. If MAXIMUM_RECORD_SIZE is not specified, PL/I provides a default length of 512 bytes for stream files and a default length of 480 bytes for relative files. There is no default for indexed files.

The GROUP_PROTECTION option defines the type of access to be permitted to the file by other users in the owner's group (also see id(1)). The format of this option is:

GROUP_PROTECTION (character-expression)

The MAXIMUM_RECORD_SIZE option specifies the largest size that records in a file can have. The actual meaning of this option varies according to the type of file:

The format of this option is:

MAXIMUM_RECORD_SIZE(integer-expression)

The MAXIMUM_RECORD_SIZE option is meaningful when a file is created and when it is opened. If the specified opened size does not match the specified created size, the results are undefined. If not specified, PL/I provides a default length based on the file organization and record format as follows:

The OWNER_PROTECTION option defines the type of access to be permitted to the file by the file's owner and by other users with the same user identification (UID). Refer to id(2) for more information. The format of this option is:

OWNER_PROTECTION (character-expression)

The RECORD_ID_ACCESS option indicates that the records in a file will be accessed randomly, using the internal identification of the records. The format of this option is:

RECORD_ID_ACCESS [ (boolean-expression) ]

You must open a file with this option to use the RECORD_ID_TO and RECORD_ID options of the record I/O statements. See Chapter 6, Input/Output Statement Options for more information.

When a file is opened with the RECORD_ID_ACCESS option, access by record identification can be mixed with sequential access or access by key during this opening. However, a statement cannot specify a record both by key and by record identification.

The RECSIZE option specifies the largest size that records in a file can have. The actual meaning of this option varies according to the type of file:

The format of this option is:

RECSIZE(integer-expression)

If RECSIZE is not specified, PL/I provides a default length based on the file organization and record format as follows:

The SCALARVARYING option specifies that character strings with the VARYING attribute be read and written in strict accordance with the PL/I ANSI standard. Its format is as follows:

SCALARVARYING [ (boolean-expression) ]

The SCALARVARYING option has the following effect on I/O operations involving VARYING character-string variables:

Thus, records to be read into or from variables with the VARYING attribute should be images of a varying character string—including the 2-byte count field at the beginning of the string.

When SCALARVARYING is not specified, character-string variables with the VARYING attribute are handled so as to facilitate reading and writing files with variable-length records. The rules are as follows:

For strings with the VARYING attribute that are embedded in arrays or structures, the entire storage is always read or written.

When a file is to be read with SCALARVARYING in effect, the target variable must be declared CHARACTER VARYING, and the length of the target variable must match the record length of each record in the file, minus two bytes. If the length does not match, the ERROR condition is signaled.

The following example illustrates reading a file with the SCALARVARYING option (presumably the file was created with the SCALARVARYING option in effect):

DECLARE EOF BIT(1) ALIGNED INITIAL('0'B);
DECLARE STRING CHARACTER(80) VARYING,
        INFILE FILE RECORD INPUT;
OPEN FILE(INFILE) ENVIRONMENT(SCALARVARYING);
ON ENDFILE(INFILE) EOF = '1'B;
READ FILE(INFILE) INTO(STRING);
DO WHILE (^EOF);
       PUT SKIP LIST(LENGTH(STRING),STRING);
       READ FILE(INFILE) INTO(STRING);
END;

The file defined as INFILE must have 82-byte records: the first two bytes of each record must contain the length of the data within the record. This READ statement reads 82 bytes, and uses the first two as the length and contents of each string.

The SHARED_READ option specifies that other users who have concurrent access to the file can read records in it. The format of this option is:

SHARED_READ [ (boolean-expression) ]

By default, the SHARED_READ option is disabled when a file is opened for output or update; that is, sharing is not allowed by default if anyone is writing to the file. SHARED_READ is enabled when a file is opened for input, that is, sharing is allowed if no one is writing to the file.

The SUPERSEDE option specifies that if a file already exists with the same name and type, it will be deleted and a new file created in its place. This is the default. The format of this option is:

SUPERSEDE [ (boolean-expression) ]

By default, the file system creates a new file whenever a file is opened for output.

The TEMPORARY option creates a temporary file name using tempnam(3s). The format of this option is:

TEMPORARY [ (boolean-expression) ]

When you create a file with the TEMPORARY option, the file system calls tempnam(3s) to create a uniquely named temporary file. A file thus created can be used during the execution of the program and deleted on completion, without cluttering up the current working directory.

The file can be deleted when it is closed or, if needed later, can be deleted after it has been reused. You specify deletion by using the DELETE option when you open, reopen, or close the file.

However, because the name of the temporary file is not available to a PL/I application, the file can be reaccessed only by its internal file identification. You can obtain this identification by specifying the FILE_ID_TO option when the file is created. For example:

DECLARE                        WORKFILE FILE OUTPUT SEQUENTIAL,
                       WORKFILE_ID (6) FIXED BINARY(31);
OPEN FILE(WORKFILE) ENVIRONMENT (
       TEMPORARY,
       FILE_ID_TO(WORKFILE_ID));
⋮
CLOSE FILE(WORKFILE);
⋮
OPEN FILE (WORKFILE) ENVIRONMENT (
       FILE_ID(WORKFILE_ID),
       DELETE);

These statements declare the file WORKFILE, open it with the FILE_ID_TO option, close it, and later reopen it, using the FILE_ID option and specifying the file identification obtained when the file was first opened. The second OPEN statement also specifies the DELETE option of ENVIRONMENT, so that the file is deleted when it is subsequently closed.

The V, VB, VS, and VSB options all equate to the variable length record format, which is the default record format for all dialects. Blocking and spanning are unsupported.

V [ (boolean-expression) ]

The variable record format is enabled by default; you need not specify it explicitly.

The WORLD_PROTECTION option defines the type of access to be permitted to the file by users who are not in the owner's group and who are not the superuser. Refer to id(1). The format of this option is:

WORLD_PROTECTION(character-expression)