Kednos PL/I for OpenVMS Systems
User Manual

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 as follows:

FILE_ID(variable-reference)

variable-reference

Specifies the name of a 6-element array variable that gives the file identification obtained when the file was created.

The variable must be declared as (6) FIXED BINARY and must be connected.

Rules

• The FILE_ID option is valid only when an existing file is opened.
• This option conflicts with the TITLE, DEFAULT_FILE_NAME, and FILE_ID_TO options.
• If there is no file with the indicated file identification, the UNDEFINEDFILE condition is signaled.
• The FILE_ID option cannot be used with DECnet.
• This option is provided only for use with the TEMPORARY option.
• You must specify the FILE_ID option to reopen a file that was created with the TEMPORARY option.

When a file is created, the FILE_ID_TO option requests PL/I to return the file identification to a user-specified variable. Its format is as follows:

FILE_ID_TO(variable-reference)

variable-reference

Specifies the name of a 6-element array variable to receive the file identification of the created file.

The variable must be declared as (6) FIXED BINARY and must be connected.

Rules

• The FILE_ID_TO option is meaningful when a file is created or opened.
• This option applies only to disk files.
• FILE_ID_TO conflicts with the FILE_ID option.
• The FILE_ID_TO option cannot be used with DECnet.
• This option is provided only for use with temporary files.

Usage

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.

7.2.20 FILE_SIZE Option

The FILE_SIZE option lets you specify the number of blocks to be initially allocated for a file. The format of the FILE_SIZE option is as follows:

FILE_SIZE(integer-expression)

integer-expression

Is a value in the range 0 through 4,294,967,295, giving the number of 512-byte blocks. A value of 0 indicates no allocation.

To specify a value larger than 2,147,483,647 (the largest value that can be contained in a fixed binary integer in PL/I, you must express the number as a negative value; RMS interprets the number as an unsigned integer.

Rules

• The FILE_SIZE option is meaningful only when a file is created.
• This option applies only to disk files.

Usage

The FILE_SIZE option can optimize I/O operations on large files. When you initially create a file that will require a large amount of space and to which new records will be added frequently, you can reduce the file system overhead required to allocate space each time the file is extended by requesting an initial allocation amount. For example:

DECLARE MONTHLY_TRANSACT FILE RECORD OUTPUT ENVIRONMENT (FILE_SIZE (128));

If you do not specify the FILE_SIZE option, or if you specify a file size of 0, PL/I uses the default extension quantity for the file when the first write or put operation occurs on the file. The default extension quantity is defined in the EXTENSION_SIZE option or supplied by default.

If the specified file size is not a multiple of the cluster size of the disk, the allocation is rounded up to a multiple of the cluster size.

If you allocate more space for a file than it requires, the unused space is wasted.

7.2.21 FIXED_CONTROL_SIZE Option

The FIXED_CONTROL_SIZE option specifies that a file will have a fixed-length control area associated with each variable-length record and specifies the size of the fixed control area. The format of this option is as follows:

FIXED_CONTROL_SIZE(integer-expression)

integer-expression

Is an integer expression in the range 0 through 255, indicating the number of bytes in the fixed control field of the record. If you specify a value of 0, PL/I uses the default size of two bytes.

Rules

• The FIXED_CONTROL_SIZE option is meaningful only when a file is created.
• This option applies only to relative and sequential files with variable-length records.
• The FIXED_CONTROL_SIZE option conflicts with the BLOCK_IO and INDEXED options and with the STREAM and UPDATE file description attributes.
• You must specify the FIXED_CONTROL_SIZE option to create a file containing records with a fixed-length control area.

Usage

When a file is created with the FIXED_CONTROL_SIZE option, WRITE and REWRITE statements for the file can specify the FIXED_CONTROL_FROM option to write a value into the fixed control area. For example:

DECLARE OUTFILE FILE RECORD OUTPUT ENVIRONMENT ( FIXED_CONTROL_SIZE (2)); OPEN FILE(OUTFILE); WRITE FILE (OUTFILE) FROM (NEWLINE) OPTIONS ( FIXED_CONTROL_FROM(LINE_NUMBER));

If the FIXED_CONTROL_FROM option is not specified when a record is written to a file with fixed control records, PL/I write zeros in the fixed-control area of the record.

7.2.22 FIXED_CONTROL_SIZE_TO Option

The FIXED_CONTROL_SIZE_TO option is used to open an existing file with fixed control records. PL/I returns the length of the fixed control area to a user-specified variable. The format of this option is as follows:

FIXED_CONTROL_SIZE_TO(variable-reference)

variable-reference

Specifies the name of a fixed binary variable to receive the length of the fixed-control area.

The variable must be declared as FIXED BINARY.

Rules

• The FIXED_CONTROL_SIZE_TO option is meaningful only when an existing file is opened.
• This option applies only to relative and sequential files with variable-length records.
• If this option is specified for a file that does not have fixed-control records, PL/I returns a zero to the specified variable.

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 as follows:

FIXED_LENGTH_RECORDS [ (boolean-expression) ]

Rules

• The FIXED_LENGTH_RECORDS option is meaningful only when a file is created.
• The FIXED_LENGTH_RECORDS option conflicts with the FIXED_CONTROL_SIZE and BLOCK_IO options and with the combination of the STREAM and OUTPUT file description attributes.

Usage

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 510 bytes for sequential files and a default length of 480 bytes for relative files.

7.2.24 GROUP_PROTECTION Option

The GROUP_PROTECTION option defines the type of access to be permitted to the file by other users in the owner's group. The format of this option is as follows:

GROUP_PROTECTION (character-expression)

character-expression

Is a 1- to 4-character string expression indicating the access privileges to be granted to users in the owner's group. The expression can contain any of the following letters to indicate the access allowed:

Letter	Meaning
R	Read access is allowed.
W	Write access is allowed.
E	Execute access is allowed.
D	Delete access is allowed.

The lowercase forms of these letters are also permitted. Letters can be repeated, but the maximum length of the string is 4 characters. All other characters are invalid. If any other character is present in the string, the UNDEFINEDFILE condition is signaled.

Rules

• The GROUP_PROTECTION option is meaningful only when a file is created.
• If no protection options are specified, PL/I uses the current system and process defaults. If any protection options are specified, the protection for unspecified user categories defaults to no access.

The IGNORE_LINE_MARKS option overrides the default manner in which PL/I interprets end-of-line indicators on stream input operations, which is to treat an end-of-line on a stream input operation as a field delimiter in a GET LIST or GET EDIT statement. The format of this option is as follows:

IGNORE_LINE_MARKS [ (boolean-expression) ]

Rules

• The IGNORE_LINE_MARKS option can be specified when a file is opened.
• This option applies only to stream input files; that is, it conflicts with the RECORD, OUTPUT, and UPDATE attributes and with any attributes that imply these attributes.

Usage

When IGNORE_LINE_MARKS is specified for a stream file, an end-of-line terminator such as a carriage return or escape character is ignored, and a GET statement continues to read characters in the input stream until a space, tab, or comma is encountered. For example:

123 [Return] 456,

If these lines are entered in response to a GET statement, the resulting input variable is given the value 123456; the carriage return is ignored, and the GET statement reads input data until the comma is encountered.

7.2.26 INDEX_NUMBER Option

The INDEX_NUMBER option specifies which index is to be used initially to process an indexed sequential file. Its format is as follows:

INDEX_NUMBER(integer-expression)

integer-expression

Specifies the initial index to be used. The value of the expression must be the number of an index for records in the file, where the primary index is 0, the secondary index is 1, and so on.

Rules

• The INDEX_NUMBER option can be specified when a file is opened for input or update.
• This option is meaningful only for indexed sequential files.

Usage

If the INDEX_NUMBER option is specified for opening an indexed sequential file for sequential access, the records will be accessed in the order of their occurrence in the index specified by the INDEX_NUMBER option.

If the file is opened for keyed access, the INDEX_NUMBER option specifies the initial index to be used. This value can be changed in the following statements:

• Any subsequent record I/O statement that specifies the INDEX_NUMBER option
• A WRITE statement that specifies the KEYFROM option
• Any statement that specifies the RECORD_ID option

In the latter two cases, the index number is set to 0, the primary index.

7.2.27 INDEXED Option

The INDEXED option specifies that a file is an indexed sequential file. The format of this option is as follows:

INDEXED [ (boolean-expression) ]

Rules

• The INDEXED option is meaningful when an existing file is opened.
• This option applies only to indexed sequential files.
• INDEXED conflicts with the APPEND, BATCH, BLOCK_IO, FIXED_CONTROL_SIZE, MAXIMUM_RECORD_NUMBER, and PRINTER_FORMAT options and with the PRINT file description attribute.

Usage

The INDEXED option is never required; however, you can use it as a check when you open an existing indexed sequential file so that PL/I will verify the file's organization before opening it.

7.2.28 INITIAL_FILL Option

The INITIAL_FILL option specifies, when an indexed sequential file is opened, that the initial fill value specified when the file was created is to be used.

As an indexed sequential file is initially loaded with records, the fill size specified causes buckets to appear full when they are actually less than full. Thus, room remains in each bucket for subsequent additions to the file.

The format of this option is as follows:.

INITIAL_FILL [ (boolean-expression) ]

Rules

The INITIAL_FILL option is meaningful only when an indexed sequential file is initially opened for output.

7.2.29 MAXIMUM_RECORD_NUMBER Option

The MAXIMUM_RECORD_NUMBER option sets, for a relative file, the largest record number that can be written to the file. The format of this option is as follows:

MAXIMUM_RECORD_NUMBER(integer-expression)

integer-expression

A numeric expression that must yield an integer result in the range 0 through 2,147,483,647.

If you specify 0, or if this option is not specified, there is no maximum number and no run-time checking of record numbers is performed.

Rules

• The MAXIMUM_RECORD_NUMBER option is meaningful only when a file is created.
• This option applies only to relative files.
• MAXIMUM_RECORD_NUMBER conflicts with the INDEXED option and with the STREAM file description attribute.

Usage

The MAXIMUM_RECORD_NUMBER option lets you specify an upper limit to the values that can be specified for relative record numbers in the file. When a maximum number has been set, then the file system checks the relative number of each record that is written to the file. If a relative record number is not in the correct range, the KEY condition is signaled. If referenced in an ON-unit for this condition, the ONCODE built-in function returns the value associated with the RMS status code RMS$_MRN.

7.2.30 MAXIMUM_RECORD_SIZE Option

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:

• For a file with fixed-length records, the maximum record size indicates the size of each record in bytes.
• For a file with variable-length records, the maximum record size is the size in bytes of the largest record that can be written to the file.
• For variable-length records with fixed-length control, the maximum record size does not include the fixed control area size.
• For relative files, the maximum record size is used in conjunction with the bucket size to determine the cell size in bytes.

The format of this option is as follows:

MAXIMUM_RECORD_SIZE(integer-expression)

integer-expression

Is a numeric expression with values in the range 1 to a maximum determined by record format and file organization, as in the following table.

File Organization	Record Format	Maximum
Sequential	Fixed or variable length	32,767
Relative	Fixed length	31,998
Relative	Variable length	31,998
Indexed sequential	Fixed length	16,362
Indexed sequential	Variable length	16,360

For variable-length records with a fixed-length control area, the size of the fixed control area must be subtracted from the maximum value allowed.

A value of 0 indicates that there is no user-defined limit to the size of records.

If the value is out of range, the UNDEFINEDFILE condition is signaled.

Rules

The MAXIMUM_RECORD_SIZE option is meaningful only when a file is created. If not specified, PL/I provides a default length based on the file organization and record format as follows:

File Organization	Record Format	Default
Sequential	Fixed length	512
Sequential	Variable length	510
Relative	Fixed or variable length	480

If the file has variable with fixed-length control records, the size of the fixed control area is subtracted from the default value listed.

7.2.31 MULTIBLOCK_COUNT Option

The MULTIBLOCK_COUNT option specifies the number of blocks to be allocated in each internal buffer for operations on a sequential disk file. Its format is as follows:

MULTIBLOCK_COUNT(integer-expression)

integer-expression

Is a fixed binary expression in the range 0 through 127, indicating the number of blocks to be allocated to each buffer. If 0 is specified, PL/I uses the system default. You can determine the current system default by entering the DCL command SHOW RMS_DEFAULT. Use the SET RMS_DEFAULT command to establish a new default value, if desired.

If the value is not within the required range, the UNDEFINEDFILE condition is signaled.

Rules

• The MULTIBLOCK_COUNT option is meaningful when a file is created or opened.
• This option applies only to sequential disk files. It is ignored if the BLOCK_IO option is specified or if the file is not a sequential disk file.

Usage

The MULTIBLOCK_COUNT option can optimize I/O operations on sequential disk files. By default, RMS transfers data in 512-byte disk blocks. To improve I/O access time, you can specify a multiple of 512-byte blocks to specify that a larger number of blocks be transferred with each input or output operation. In general, a multiblock count of between 12 and 16 results in good performance for sequential I/O.

The MULTIBLOCK_COUNT option can also be used with the MULTIBUFFER_COUNT option to request a specified number of I/O buffers, each of which can contain the given number of blocks.

7.2.32 MULTIBUFFER_COUNT Option

The MULTIBUFFER_COUNT option specifies the number of buffers to be allocated for file operations; it has the following effects, depending on the organization of the file:

• For relative and indexed sequential files, it results in a cache of buckets that can improve random access.
• For sequential files, multiple buffers allow throughput to be increased on file transfers when either the READ_AHEAD or the WRITE_BEHIND option is also selected. If neither of these options is specified, the MULTIBUFFER_COUNT option is meaningless for sequential files.

Its format is as follows:

MULTIBUFFER_COUNT(integer-expression)

integer-expression

Specifies a value in the range -128 through 127, indicating the number of buffers to be allocated; RMS uses the absolute value of the field. If 0 is specified, PL/I applies the current RMS default. This default can be set with the DCL command SET RMS_DEFAULT; its current value can be determined with the command SHOW RMS_DEFAULT.

If either the READ_AHEAD or the WRITE_BEHIND option is specified and the MULTIBUFFER_COUNT option is not specified, PL/I uses the RMS default value of two buffers.

Rules

• The MULTIBUFFER_COUNT option is meaningful when a file is created or opened.
• This option applies only to disk files.
• This option has no effect if BLOCK_IO is specified.

Usage

When you use the MULTIBUFFER_COUNT option, it decreases the number of actual data transfers and thus increases a program's execution speed. For example:

OPEN FILE(REL_FILE) ENVIRONMENT(READ_AHEAD, MULTIBLOCK_COUNT(4) , MULTIBUFFER_COUNT(4));

This option can be specified for sequential, relative, or indexed sequential files. For inserting records in an indexed sequential file, a good rule of thumb is to specify one buffer for each index in use, plus two or more buffers for data. Thus, an indexed sequential file with a primary key and two alternate keys could be opened with the following ENVIRONMENT specification:

ENVIRONMENT (MULTIBUFFER_COUNT(5))

This option specifies five buffers.

Multibuffering is also effective for sequential files when combined with the ENVIRONMENT options READ_AHEAD or WRITE_BEHIND. These options are described individually in this chapter.