The options of the ENVIRONMENT attribute provided by PL/I allow you to:

• Describe the attributes of a file when it is created.
• Request special processing and optimization options when the file is being read or written.
• Specify the disposition of a file when it is closed.

Most of the options of the ENVIRONMENT attribute correspond directly to OpenVMS Record Management Services (RMS) options and control values. PL/I, in some cases, provides different defaults than RMS.

7.1 Specifying and Using ENVIRONMENT Options

All ENVIRONMENT options can be specified in the declaration of a file constant or in an OPEN statement. Certain options can also be specified in a CLOSE statement.

ENVIRONMENT options fall into the following categories, based on whether they require an argument and the type of argument required:

• Options that require you to specify an expression representing a value to override a default value provided by PL/I
• Options that require you to provide a reference to a variable that either contains information pertinent to opening the related file or that will receive information when the related file is opened
• Options that can be specified with a Boolean expression that enables or disables the option (if no value is specified with an option, the option is enabled)

All arguments must be specified in parentheses following the name of the ENVIRONMENT option. For example:

ENVIRONMENT (MAXIMUM_RECORD_SIZE(1024), FILE_ID_TO(WORKFILE_ID), FIXED_LENGTH_RECORDS('1'B) )

Considerations for specifying each type of argument are given in the following sections.

7.1.1.1 Expressions

You can use integer expressions and character expressions in expression arguments for ENVIRONMENT options. The ways you can specify these arguments differ for DECLARE statements and for OPEN and CLOSE statements.

In a DECLARE statement, you must specify a constant expression. Integer expressions can consist of integer constants, constant identifiers defined by %REPLACE statements, and the operators +, -, *, and /. You must specify character expressions using character-string constants.

In an OPEN or a CLOSE statement, you can specify the argument using constant expressions or variable references, or expressions or variable references of the required type.

If a single variable is specified for an expression, its data type must be convertible to the data type of the option. All integer constants and expressions are converted to FIXED BINARY.

You can specify all character-string expressions using varying or nonvarying strings. The description of the option specifies the maximum length of a string argument.

For any of these options, PL/I applies a default value if no option is specified for the file when it is opened.

7.1.1.2 Variable References

Options that are specified by variable references cannot be specified in a DECLARE statement. The data type of the variable must match the data type described in the option description.

7.1.1.3 Boolean Values

For an option that can be enabled or disabled, you can specify a Boolean constant, that is, '1'B (to enable) or '0'B (to disable) the option in a DECLARE statement. In an OPEN or CLOSE statement, you can specify a Boolean constant, variable, or expression.

An option that is specified without a value is interpreted as enabled. For example, the following are equivalent:

ENVIRONMENT(FIXED_LENGTH_RECORDS) ENVIRONMENT(FIXED_LENGTH_RECORDS('1'B))

For arguments of this type, PL/I converts any non-Boolean value to BIT(1) ALIGNED.

7.1.2 Interpretation of ENVIRONMENT Options for Existing Files

Many ENVIRONMENT options specify values that can be set only when a file is created. For example, the length of records in a file with fixed-length records is set when the file is created and cannot be changed thereafter. When these options are specified for a file, they apply to the file only if the opening of the file actually results in the creation of a new file. If the file opening causes an existing file to be opened, the option is ignored.

7.1.3 Determining ENVIRONMENT Options

A PL/I program can determine the value or setting of an ENVIRONMENT option at run time for an indicated file by calling the DISPLAY built-in subroutine. This built-in subroutine returns information about a specified PL/I file to a user-specified structure. The member names in the structure correspond to the keywords of the ENVIRONMENT attribute.

For a description of the values returned by this subroutine and for an example of calling it, see Chapter 9.

Certain ENVIRONMENT options themselves return information to the program when an existing file is opened. For example, you can specify the FIXED_CONTROL_SIZE_TO option when an existing file with a fixed control area is opened. PL/I returns the size of the fixed control area to the program.

7.1.4 Device Independence of ENVIRONMENT Options

Many ENVIRONMENT options apply only to a particular type of device or to a specific file organization. For example, the REWIND_ON_CLOSE and REWIND_ON_OPEN options apply only to magnetic tape files, and the FILE_SIZE option applies only to disk files.

When any ENVIRONMENT option is specified for a device to which the option does not apply, the option is ignored.

7.1.5 Conflicting and Invalid ENVIRONMENT Options

Conflicting or invalid options or values for options can be detected during compilation or at run time. At compile time, the compiler issues a diagnostic message to indicate the error.

At run time, the UNDEFINEDFILE condition is signaled if conflicting options are in effect or if conflicting values are specified for the same option. For example, if the FILE_SIZE option is specified in the DECLARE and OPEN statements for a given file and if the options specify different values, UNDEFINEDFILE is signaled.

For run-time errors, an ON-unit can reference the ONCODE built-in function to determine the specific error, if desired. If no ON-unit exists for the UNDEFINEDFILE condition, the PL/I run-time system displays an error message describing the error that occurred.

7.2 Summary of ENVIRONMENT Options

The options to the PL/I ENVIRONMENT attribute are summarized in alphabetical order in Table 7-1. Columns in Table 7-1 provide the following information:

Option and Usage	Gives the name of the ENVIRONMENT option, its argument (if any), and a brief description of its usage. An option that does not show an argument can be specified with a Boolean argument.
Specify At	Indicates when the option is meaningful. The possible items in this column are as follows: Create-the option can be specified on a DECLARE or OPEN. It is meaningful only when a file is created. Open-the option can be specified on a DECLARE or OPEN. It is meaningful when an existing file is opened. Close-the option can be specified on a DECLARE, OPEN, or CLOSE. It takes effect when the file is closed. Update-the option is meaningful when an existing file is opened with the UPDATE attribute or with the ENVIRONMENT option APPEND.
Valid I/O Types	Indicates whether the option is valid for stream or record files.
Default Value	Indicates the default value, if any, when the option is not specified for a file.
Data Type	Specifies the required data type of the argument.

Appendix B lists the options and their corresponding RMS equivalents.

Table 7-1 Summary of ENVIRONMENT Options

Option and Usage	Specify At	Valid I/O Types	Default Value	Data Type
APPEND Places output for a file at the end of a file.	Create Open	Record Stream	Disabled	BIT(1)
BACKUP_DATE (variable) Overrides the default backup date of the file.	Create Open	Record Stream	Date and time file was last backed up	BIT(64) ALIGNED
BATCH Submits a copy of the file to the system batch job queue on close.	Create Open Close	Record Stream	Disabled	BIT(1)
BLOCK_BOUNDARY_FORMAT Indicates that records must not cross block boundaries.	Create	Record Stream	Disabled	BIT(1)
BLOCK_IO Specifies a file will be read or written by block instead of records.	Create Open	Record	Disabled	BIT(1)
BLOCK_SIZE (expression) Specifies the size of a block for the creation of a magnetic tape file.	Create	Record Stream	Mount BLOCKSIZE Value	FIXED BINARY
BUCKET_SIZE (expression) Defines the number of 512-byte blocks in a bucket for an indexed sequential or a relative file.	Create	Record	Maximum record size	FIXED BINARY
CARRIAGE_RETURN_FORMAT Indicates that records in the file will be printed with default carriage control.	Create	Record	Enabled	BIT(1)
CONTIGUOUS Specifies that an output file must be placed in a physically contiguous extent on disk.	Create	Record Stream	Disabled	BIT(1)
CONTIGUOUS_BEST_TRY Requests that if possible an output file be placed in a physically contiguous extent on disk.	Create	Record Stream	Disabled	BIT(1)
CREATION_DATE (variable) Overrides default creation date of the file.	Create	Record Stream	Current date and time	BIT(64) ALIGNED
CURRENT_POSITION Leaves magnetic tape positioned at last close.	Create Open	Record Stream	Disabled	BIT(1)
DEFAULT_FILE_NAME (expression) Defines a default file specification for a file.	Create Open	Record Stream	'.DAT'	CHAR(128)
DEFERRED_WRITE Requests file system optimization of output.	Create Open	Record	Disabled	BIT(1)
DELETE Specifies that the file be deleted when it is closed.	Create Open Close	Record Stream	Disabled	BIT(1)
EXPIRATION_DATE (variable) Defines the expiration date for a magnetic tape file.	Create	Record Stream	Creation date	BIT(64) ALIGNED
EXTENSION_SIZE (expression) Specifies a default extension size for a disk file.	Create Open	Record Stream	System default	FIXED BINARY
FILE_ID (variable) Identifies a file by its internal file identification.	Open	Record Stream	Not applicable	(6)FIXED BINARY
FILE_ID_TO (variable) Identifies a file by its internal file identification.	Create Open	Record Stream	Not applicable	(6)FIXED BINARY
FILE_SIZE (expression) Defines the initial number of blocks to be allocated for a file.	Create	Record Stream	Not applicable	FIXED BINARY
FIXED_CONTROL_SIZE (expression) Defines records as variable length with fixed-length control, and specifies the size of the fixed control area.	Create	Record	Disabled	FIXED BINARY
FIXED_CONTROL_SIZE_TO (variable) Defines records as variable length with fixed-length control and specifies the size of the fixed control area. On open, returns the length of the fixed control area.	Create Open	Record	Disabled	FIXED BINARY
FIXED_LENGTH_RECORDS Specifies a file with fixed-length records of a maximum record size.	Create	Record	Disabled	BIT(1)
GROUP_PROTECTION (expression) Defines the type of file access allowed to members of the owner's group.	Create	Record Stream	Current process default	CHAR(4)
IGNORE_LINE_MARKS Specifies that end-of-line characters are not to be treated as field delimiters in GET LIST statements.	Create Open	Stream	Disabled	BIT(1)
INDEX_NUMBER (expression) Specifies the initial index to use in accessing records in an indexed sequential file.	Create Open	Record	0	FIXED BINARY
INDEXED Defines an indexed sequential file.	Create Open	Record	Disabled	BIT(1)
INITIAL_FILL Requests the file system to leave unused space in file index overflow buckets.	Open	Record	Disabled	BIT(1)
MAXIMUM_RECORD_NUMBER (expression) Specifies the largest record number that will be valid for records in a relative file.	Create	Record	0	FIXED BINARY
MAXIMUM_RECORD_SIZE (expression) Specifies the maximum size that is valid for any record in the file.	Create	Record	512 bytes 1	FIXED BINARY
MULTIBLOCK_COUNT (expression) Specifies the number of blocks to be allocated for file system buffering.	Create Open	Record	Current process default	FIXED BINARY
MULTIBUFFER_COUNT (expression) Specifies the number of buffers to be allocated for file system buffering.	Create Open	Record	Current process default	FIXED BINARY
NO_SHARE Prohibits all types of shared access to the file.	Create Open	Record	Enabled 2	BIT(1)
OWNER_GROUP (expression) Specifies the group number in the user identification code (UIC) of the owner of the file.	Create	Record Stream	Current process group number	FIXED BINARY
OWNER_ID (expression) Specifies the entire 32-bit identifier of the owner of the file; can be used instead of OWNER_GROUP and OWNER_MEMBER.	Create	Record Stream	Current process identifier (UIC)	FIXED BINARY
OWNER_MEMBER (expression) Specifies the member number in the user identification code (UIC) of the owner of the file.	Create	Record Stream	Current process member number	FIXED BINARY
OWNER_PROTECTION (expression) Specifies the type of file access allowed the owner of the file.	Create	Record Stream	Current process default	CHAR(4)
PRINTER_FORMAT Specifies that records in the file will be printed with printer format carriage control embedded in the fixed control area of the records.	Create	Record	Disabled	BIT(1)
READ_AHEAD Requests file system optimization on read operations.	Open	Record Stream	Disabled	BIT(1)
READ_CHECK Requests verification of read operations.	Create Open	Record Stream	Disabled	BIT(1)
RECORD_ID_ACCESS Indicates that records will be accessed by internal file system identification.	Create Open	Record	Disabled	BIT(1)
RETRIEVAL_POINTERS (expression) Specifies the number of file system extent pointers to be maintained for file access.	Create Open	Record Stream	Current system default	FIXED BINARY
REVISION_DATE (variable) Overrides the default revision date of the file.	Close	Record Stream	Date and time file is closed	BIT(64) ALIGNED
REWIND_ON_CLOSE Requests that a magnetic tape volume be rewound when the file is closed.	Create Open Close	Record Stream	Disabled	BIT(1)
REWIND_ON_OPEN Requests that a magnetic tape volume be rewound when the file is opened.	Create Open	Record Stream	Enabled	BIT(1)
SCALARVARYING Specifies that varying character strings will be read/written using the entire storage of the variable.	Create Open	Record	Disabled	BIT(1)
SHARED_READ Allows other users to read records in the file.	Create Open	Record	Enabled 3	BIT(1)
SHARED_WRITE Allows other users to read and write records in the file.	Create Open	Record	Disabled	BIT(1)
SPOOL Queues a copy of the file to the system printer when the file is closed.	Create Open Close	Record Stream	Disabled	BIT(1)
SUPERSEDE Replaces an existing file with the same file name, file type, and version number.	Create	Record Stream	Disabled	BIT(1)
SYSTEM_PROTECTION (expression) Defines the type of file access allowed to users with system user identification codes (UICs).	Create	Record Stream	Current process default	CHAR(4)
TEMPORARY Specifies a temporary file for which no directory entry is made.	Create	Record Stream	Disabled	BIT(1)
TRUNCATE Truncates a sequential file at its logical end-of-file when the file is closed.	Create Update Close	Record Stream	Disabled	BIT(1)
USER_OPEN (entry-name) Specifies a user-written function to open the file.	Create Open	Record Stream	RMS Open	ENTRY
WORLD_PROTECTION (expression) Specifies the type of file access allowed to general system users.	Create	Record Stream	Current process default	CHAR(4)
WRITE_BEHIND Requests file system optimization on output operations.	Create Update	Record Stream	Disabled	BIT(1)
WRITE_CHECK Requests verification of output operations.	Create Update	Record Stream	Disabled	BIT(1)

The following sections describe each option in detail.