Kednos PL/I for OpenVMS Systems
User Manual

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) ]

Rules

• The APPEND option is meaningful only when an existing file is opened with the OUTPUT attribute. It overrides the default action for opening an output file, which is to create a new file with a higher version number.
• If the APPEND option is specified when a file is created, the option is ignored; that is, if the file does not exist, a new file is created.
• APPEND conflicts with the SUPERSEDE option; it is invalid for a file opened with the INPUT or UPDATE attribute.

Usage

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 on a magnetic tape, you can open the file as follows:

DECLARE TAPEFILE FILE SEQUENTIAL OUTPUT; . . . OPEN FILE(TAPEFILE) ENVIRONMENT(APPEND);

This OPEN statement opens the file TAPEFILE. The file constant TAPEFILE is assumed to be a logical name. The system translates the logical name to locate the tape device with which it is associated. The tape is positioned at its current end-of-file.

APPEND can also be used for sequential disk files and for mailboxes.

7.2.2 BACKUP_DATE Option

The BACKUP_DATE option lets you specify a date and time field for the file's backup date, allowing you to override the existing backup date and time. The format of this option is as follows:

BACKUP_DATE (variable-reference)

variable-reference

Specifies the name of a BIT(64) ALIGNED variable containing an absolute time value in system format. The value specifies the date and time to be used as the file's backup date and time.

Rules

The BACKUP_DATE option is meaningful only when the file is opened or created.

Usage

You can obtain the time value required by using the Convert ASCII String to Binary Time system service (SYS$BINTIM). For an example of a call to this procedure to obtain a system time value, see Chapter 11.

7.2.3 BATCH Option

The BATCH option requests that the file be submitted to the system batch job queue when it is closed. The format of this option is as follows:

BATCH [ (boolean-expression) ]

Rules

• The BATCH option can be specified when a file is created, opened, or closed.
• This option applies only to stream files or to sequential record files.
• Once the BATCH option has been specified for a file on a particular file opening, it cannot be disabled.
• BATCH conflicts with the INDEXED option and with the KEYED and DIRECT file description attributes.

Usage

When you specify both the TEMPORARY and DELETE options in conjunction with the BATCH option, the file is submitted to the batch job queue and is marked for deletion after the batch job is completed.

7.2.4 BLOCK_BOUNDARY_FORMAT Option

The BLOCK_BOUNDARY_FORMAT option indicates that records in the file must not cross block boundaries. The format of this option is as follows:

BLOCK_BOUNDARY_FORMAT [ (boolean-expression) ]

Rules

• The BLOCK_BOUNDARY_FORMAT option is meaningful only when a file is created.
• This option applies only to sequential files; it is ignored if specified for relative or indexed sequential files.
• If the BLOCK_BOUNDARY_FORMAT option is specified for a file, the maximum record size must be less than 512 bytes.
• BLOCK_BOUNDARY_FORMAT conflicts with the BLOCK_IO option. However, a file that is created with the BLOCK_BOUNDARY_FORMAT option can later be read with the BLOCK_IO option.

Usage

The BLOCK_BOUNDARY_FORMAT option can be paired with the CARRIAGE_RETURN_FORMAT or PRINTER_FORMAT option to define the attributes of a file's records.

This option can be useful for the creation of files that will be read in terms of blocks. Note, however, that this option can result in unused disk space when records do not fill blocks.

7.2.5 BLOCK_IO Option

The BLOCK_IO option indicates that all I/O operations on the file will be in terms of physical blocks rather than records. In an I/O statement, a block is treated as if it were a single logical record. The format of this option is as follows:

BLOCK_IO [ (boolean-expression) ]

Rules

• The BLOCK_IO option is meaningful when a file is created or opened. The file can be opened with any of the attributes INPUT, OUTPUT, or UPDATE. If the file is opened for output, the created file is always sequential.
• This option applies only to disk files and to magnetic tape files.
• The BLOCK_IO option conflicts with the STREAM file description attribute and with the following ENVIRONMENT options:
  • BLOCK_BOUNDARY_FORMAT
  • CARRIAGE_RETURN_FORMAT
  • FIXED_CONTROL_SIZE
  • FIXED_LENGTH_RECORDS
  • PRINTER_FORMAT
  • RECORD_ID_ACCESS

Usage

Disk Files: When a disk file is opened for block I/O, each READ or WRITE statement always transfers data beginning on a block boundary; multiple physical blocks can be read or written. The number of bytes transferred in an I/O operation depends on the size of the input or output variable specified in the READ or WRITE statement. When a READ statement reads fewer bytes than specified by the size of the input variable, the ERROR condition is signaled; this condition is equivalent to an end-of-file indication.

When a disk file is opened with the BLOCK_IO option and with the KEYED and UPDATE attributes, the file can be accessed with keyed READ, REWRITE, and WRITE statements. In this case, the key value is the virtual block number of a block. The first block is always numbered 1. There is no distinction between the statements REWRITE KEY(n) and WRITE KEYFROM(n); both statements store data in the block numbered n of the file. If the file is a sequential file, it is extended if necessary.

Magnetic Tape Files: In a magnetic tape file, the size of the block is the size specified when the tape was created; if the tape was not previously written, the block size is set when the tape is mounted. Sequential READ and WRITE statements transfer a block at a time.

7.2.6 BLOCK_SIZE Option

The BLOCK_SIZE option specifies the size, in bytes, of the blocks when a magnetic tape file is created. Its format is as follows:

BLOCK_SIZE(integer-expression)

integer-expression

Specifies a numeric value in the range 20 through 65,532, giving the number of bytes in a block for the tape file. If the BLOCK_SIZE option is not specified, or if the expression is specified as 0, the block size specified when the tape volume was mounted is used by default.

Rules

• The BLOCK_SIZE option is meaningful only when a file is created.
• This option applies only to magnetic tape files.

Usage

When a tape file is opened with the BLOCK_IO option of ENVIRONMENT, the block size of the file is used to determine the number of bytes to be transferred in a single I/O operation.

7.2.7 BUCKET_SIZE Option

The BUCKET_SIZE option lets you specify the number of blocks to be used for each bucket when you create a relative file. The BUCKET_SIZE option has the following format:

BUCKET_SIZE(integer-expression)

integer-expression

Is a fixed binary value in the range 0 through 32, representing the number of blocks in each bucket. If the bucket size is specified as 0, or if it is not 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.

Rules

• The BUCKET_SIZE option is meaningful only when a file is created.
• This option applies only to relative files.

Usage

Selection of a bucket size for a relative file depends on the size of the records in the file. Although records within a bucket can cross block boundaries, records cannot cross bucket boundaries. Therefore, the number of blocks per bucket that you specify with this option must conform to one of the following formulas.

Relative Files with Fixed-Length Records

bsiz = ((rlen + 1)*rnum)/512

bsiz

Is the number of blocks per bucket, rounded up to the next higher integer. The result must be in the range 1 through 32.

rlen

Is the size of the fixed-length records (specified by the MAXIMUM_RECORD_SIZE option).

rnum

Is the number of records that you want in each bucket.

The overhead required for these files consists of one byte for each record.

Relative Files with Variable-Length Records

bsiz = ((rmax + 3)*rnum)/512

bsiz

Is the number of blocks per bucket, rounded up to the next higher integer. The result must be in the range 1 through 32.

rmax

Is the maximum size of any record in the file (specified by the MAXIMUM_RECORD_SIZE option).

rnum

Is the number of records that you want in each bucket.

The overhead required for these files is three bytes for each record.

Relative Files with Variable Fixed-Length Control Records

bsiz = ((rmax +fsiz +3)*rnum)/512

bsiz

Is the number of blocks per bucket, rounded up to the next higher integer. The result must be in the range 1 through 32.

rmax

Is the maximum size of the data portion of any record in the file (specified by the MAXIMUM_RECORD_SIZE option).

fsiz

Is the size of the fixed-length control area of records (specified by the FIXED_CONTROL_SIZE option).

rnum

Is the number of records you want in each bucket.

The overhead required for these files consists of three bytes, plus the fixed control size, for each record.

By careful calculation of a bucket size, you can improve I/O operations on the file. In general, a bucket size of between four and eight blocks results in good performance for most files. For detailed information on file design and space considerations, see the OpenVMS Record Management Services Reference Manual.

7.2.8 CARRIAGE_RETURN_FORMAT Option

The CARRIAGE_RETURN_FORMAT option indicates that each record in the file is to be preceded by a line feed and followed by a carriage return when the line is written to a carriage-control device such as a terminal or line printer. The format of this option is as follows:

CARRIAGE_RETURN_FORMAT [ (boolean-expression) ]

Rules

• The CARRIAGE_RETURN_FORMAT option is meaningful only when a file is created.
• CARRIAGE_RETURN conflicts with the PRINTER_FORMAT and BLOCK_IO options and with the PRINT file description attribute.

Usage

CARRIAGE_RETURN_FORMAT is the default format for record files.

This type of carriage control is an attribute of the file that is known to the file system; it does not require space within the file's records.

7.2.9 CONTIGUOUS Option

The CONTIGUOUS option specifies that disk space for the associated file be allocated using contiguous blocks on the disk. The format of this option is as follows:

CONTIGUOUS [ (boolean-expression) ]

Rules

• The CONTIGUOUS option is meaningful only when a file is created.
• This option applies only to disk files.
• If specified with the CONTIGUOUS_BEST_TRY option, the CONTIGUOUS_BEST_TRY option takes precedence.

Usage

By default, a disk file consists of noncontiguous areas, or extents, on a disk volume. When a file is accessed, the file system must maintain a pointer to each extent. However, there is a maximum number of extents that can be maintained. For very large files that must be accessed quickly, an initial allocation of contiguous space can result in more efficient I/O operations.

The CONTIGUOUS option is generally used with the FILE_SIZE option to specify exactly how much contiguous space is to be allocated for the file when it is first created. When the FILE_SIZE option is not specified, the size of the first allocation is determined by the default cluster size of the disk (usually three to five blocks).

If there is not enough contiguous space on the given volume for the specified size, the UNDEFINEDFILE 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$_FULL.

If the file need not be entirely contiguous, use the CONTIGUOUS_BEST_TRY option instead of the CONTIGUOUS option.

Note that both the CONTIGUOUS and CONTIGUOUS_BEST_TRY options apply only to the first allocation of space for the file. If the file is later extended in any way, the new space allocations may or may not be contiguous with the first allocation.

7.2.10 CONTIGUOUS_BEST_TRY Option

This option requests that, if possible, disk space for a new file be allocated in contiguous space on the disk. When the file system allocates space, it tries to place the file in contiguous blocks. The format of this option is as follows:

CONTIGUOUS_BEST_TRY [ (boolean-expression) ]

Rules

• The CONTIGUOUS_BEST_TRY option is meaningful only when a file is created.
• This option applies only to disk files.
• CONTIGUOUS_BEST_TRY overrides the CONTIGUOUS option.

The CREATION_DATE option lets you specify a date and time field for the file's creation, allowing you to override the default creation date and time. The format of the CREATION_DATE option is as follows:

CREATION_DATE (variable-reference)

variable-reference

Specifies the name of a BIT(64) ALIGNED variable containing an absolute time value in system format. The value specifies the date and time to be used as the file's creation date and time.

Rules

The CREATION_DATE option is meaningful only when a file is created.

Usage

You can obtain the time value required by using the Convert ASCII String to Binary Time system service (SYS$BINTIM).

7.2.12 CURRENT_POSITION Option

The CURRENT_POSITION option specifies that a magnetic tape volume be positioned immediately after the most recently closed file when the next file is created. The format of this option is as follows:

CURRENT_POSITION [ (boolean-expression) ]

Rules

• The CURRENT_POSITION option is meaningful only when a file is created.
• This option applies only to magnetic tape files.
• If the REWIND_ON_OPEN option is also selected, it takes precedence over the CURRENT_POSITION option.

Usage

This option lets you close an output file on magnetic tape and proceed to write another file on the same tape immediately after the current file. For example:

DECLARE TAPEFILE FILE RECORD OUTPUT ENV( DEFAULT_FILE_NAME('TAPEFILE:')); OPEN FILE(TAPEFILE) ENV(CURRENT_POSITION) TITLE('TAPE1.FIL'); CLOSE FILE(TAPEFILE); OPEN FILE(TAPEFILE) TITLE('TAPE2.FIL')'

When the second OPEN statement is executed, the tape identified by the logical name TAPEFILE retains the position it had following the CLOSE statement.

7.2.13 DEFAULT_FILE_NAME Option

The DEFAULT_FILE_NAME option specifies default fields for the file specification associated with the PL/I file reference. Its format is as follows:

DEFAULT_FILE_NAME [ (character-expression ) ]

character-expression

Is a character-string expression specifying one or more components of an OpenVMS file specification. If no value or a null string is specified, PL/I applies no default values for file specifications.

The string can have a maximum length of 128 characters.

Rules

• The DEFAULT_FILE_NAME option is meaningful when a file is created or opened.
• When the DEFAULT_FILE_NAME option is not specified, PL/I applies the default file type DAT to file specifications that do not contain a file type.

Usage

For an explanation of the steps that PL/I takes to complete a file specification, including its use of the value of the DEFAULT_FILE_NAME option, see Chapter 4.

7.2.14 DEFERRED_WRITE Option

The DEFERRED_WRITE option requests that modified I/O buffers not be written back to the disk file until the buffers are needed for other purposes. The format of this option is as follows:

DEFERRED_WRITE [ (boolean-expression) ]

Rules

• The DEFERRED_WRITE option is meaningful when a file is created or opened. An existing file can be opened for update or opened with the APPEND option.
• This option applies only to relative and indexed sequential files.
• If a file is opened with the SHARED_READ or SHARED_WRITE option and the DEFERRED_WRITE option, the DEFERRED_WRITE option will be ignored.

Usage

The DEFERRED_WRITE option can provide better I/O performance for output operations, especially when a relative or indexed sequential file is being initially loaded with records, and the records are being added sequentially.

If a system problem occurs when I/O is being performed with the DEFERRED_WRITE option enabled, data may be lost. To ensure the integrity of the file during processing with this option, a PL/I program can call the FLUSH built-in subroutine at critical times to rewrite all buffers. The FLUSH built-in subroutine is described in Chapter 9.

7.2.15 DELETE Option

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

DELETE [ (boolean-expression) ]

Rules

• The DELETE option can be specified when a file is created, opened, or closed.
• Once the DELETE option has been enabled for a file on a particular open, it cannot be disabled.

Usage

When this option is used in conjunction with the SPOOL or BATCH options, the file is marked to be deleted after it is either printed or processed as a batch job.

You can also 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 OpenVMS file associated with the PL/I file constant INFILE is deleted.

7.2.16 EXPIRATION_DATE Option

The EXPIRATION_DATE option specifies the time at which a magnetic tape or disk file expires. The file cannot be deleted or overwritten until the date specified. The format of the EXPIRATION_DATE option is as follows:

EXPIRATION_DATE (variable-reference)

variable-reference

Specifies the name of a BIT(64) ALIGNED variable that contains an absolute time value or a delta time value in system format. The value specifies the date and time at which a file expires.

Rule

The EXPIRATION_DATE option is meaningful only when a file is created.

Usage

You can obtain the time value required by using the Convert ASCII String to Binary Time system service (SYS$BINTIM).

7.2.17 EXTENSION_SIZE Option

The EXTENSION_SIZE option sets the default extension quantity for a file, that is, the number of blocks to be added to a disk file when a PUT or WRITE operation increases the size of the file beyond its original allocation. The format of the EXTENSION-SIZE option is as follows:

EXTENSION_SIZE(integer-expression)

integer-expression

Is a fixed binary integer in the range 0 through 65,535, indicating the extension quantity in 512-byte blocks.

Rules

• The EXTENSION_SIZE option is meaningful when a file is created or opened. An existing file can be opened for update or for output with the APPEND option.
• This option applies only to disk files.
• When an extension size is specified in the opening of an existing file, the extension value is set for the duration of this file opening. When the file is closed, the default set when the file was created is reestablished.

Usage

Using the EXTENSION_SIZE option can improve the efficiency of I/O operations to files that are frequently enlarged.

Each time the addition of a record to a file requires the file system to allocate additional disk extents for the file, RMS allocates the amount of space specified by the EXTENSION_SIZE value. Thus, if you specify a value that is larger than the default that RMS uses, the number of times that the file must be extended will be decreased.

However, if a large extension quantity is specified for a file, and the file does not require the allocated space, the disk space is wasted.