Options of the ENVIRONMENT Attribute

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.

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

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, Using PL/I in the Common Language Environment.

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.

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.

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.

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.

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.

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

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

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

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

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

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.

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.

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.

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

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

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.

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, The File System.

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, File-Handling Built-In Subroutines.

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.

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

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

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.

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 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.

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.

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.

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.

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:

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

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.

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

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.

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:

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

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.

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.

By default, the NO_SHARE option is enabled when a file is opened for output or update. This option is disabled when a file is opened for input.

Note that although the value can be specified to PL/I in decimal, the OpenVMS system always displays UICs in octal format.

Following is an example of a program using the OWNER_GROUP and the OWNER_MEMBER options to define the ownership of a file. Note the use of the DECODE built-in function to obtain octal numbers for the UIC.

OWNER: PROCEDURE OPTIONS(MAIN);

    DCL TEST_FILE STREAM OUTPUT FILE;

    OPEN FILE(TEST_FILE)
        ENVIRONMENT(OWNER_GROUP(DECODE('214',8)),
            OWNER_MEMBER(DECODE('10223',8)));

    PUT FILE(TEST_FILE) LIST('This file is owned by UIC [214,10223].');

    CLOSE FILE(TEST_FILE);

    END OWNER;

Following is an example of a program using the OWNER_ID option:

/*
 *  This program example creates a file owned by the identifier TEST.  (Note
 *  that the process running this program must hold the identifier with the
 *  RESOURCE attribute or the file creation will fail.)
 */
%REPLACE IDENTIFIER BY 'TEST';

OWNER_ID: PROCEDURE OPTIONS(MAIN);

    %INCLUDE $KGBDEF;
    %INCLUDE $STSDEF;
    %INCLUDE SYS$ASCTOID;

    DCL TEST_FILE STREAM OUTPUT FILE;
    DCL IDENTIFIER_VALUE FIXED BINARY;
    DCL KGB_BITS BIT(32) ALIGNED;

    /*
     *  Get the value of the identifier.  (Note: The fact that the value
     *  translates successfully does not mean that the current process
     *  holds the identifier.
     */
    STS$VALUE = SYS$ASCTOID( IDENTIFIER, IDENTIFIER_VALUE, KGB_BITS );
    IF ~STS$SUCCESS THEN SIGNAL VAXCONDITION(STS$VALUE);

    /*
     *  Does the identifier have the resource attribute?  (Note: If you
     *  want to determine whether this process holds the identifier with the
     *  resource attribute, you must use the SYS$FIND_HOLDER or SYS$CHKPRO
     *  system services.)
     */
    IF (KGB_BITS & KGB$M_RESOURCE) = '0'b
    THEN
        PUT LIST('The identifier ' ||
            IDENTIFIER || ' does not have the RESOURCE attribute.');

    OPEN FILE(TEST_FILE) ENVIRONMENT(OWNER_ID(IDENTIFIER_VALUE));

    PUT FILE(TEST_FILE)
        LIST('This file is owned by the identifier ' || IDENTIFIER || '.');

    CLOSE FILE(TEST_FILE);

    END OWNER_ID;

Note that although the value can be specified to PL/I in decimal, the OpenVMS system always displays UICs in octal format.

See the section on the OWNER_GROUP option for an example of a program using the OWNER_MEMBER option.

This option indicates that a file is in printer format, that is, the fixed control area of each record contains carriage-control information. Printer file format provides more explicit carriage control than the default type of carriage control, called carriage return format. Printer format is particularly useful in formatting a printed listing.

Note that format items are implemented in the following way:

Table 7.2, “Printer File Format Carriage Control” summarizes coding specifications for the fixed-length control area for files with printer format. The first byte in the fixed control area is called the prefix byte: it determines the carriage control to be performed before writing the record. The second byte is the postfix byte: it determines the carriage control to be performed after writing the record. The values shown in Table 7.2, “Printer File Format Carriage Control” have the same meanings in either byte; the bytes are interpreted separately.

Example 7.1, “Explicit Carriage Control” illustrates a procedure that uses explicit carriage control. The following notes are keyed to this program:

PRINTER_FORMAT_EXAMPLE: PROCEDURE OPTIONS(MAIN);

    /*
     * Declare structure definitions for carriage-control bit fields
     * and a FIXED BIN(15) variable for the fixed control area
     */                                                     /* ❶ */
    DECLARE
        1 LINE_FEEDS STATIC,
          2 COUNT BIT (7),                  /* Contains count of line feeds */
          2 INDICATOR BIT(1) INIT('0'B),    /* Must be zero */
        1 CARRIAGE_CONTROL STATIC,
          2 CODE BIT(5),                    /* Bits 0-4 ASCII code for action */
          2 FILLER BIT(2) INIT('00'b),      /* Bits 5 and 6 */
          2 EXPLICIT BIT(1) INIT('1'B),     /* Bit 7 must be set */
        CONTROL_FIELD BIT(16) ALIGNED;

    /*
     * Set up variables for form feeds and carriage returns
     */
    DECLARE
        (NEW_LINE,NEW_PAGE) BIT(8); /* ❷ */

    /*
     * Declare PRINTFILE with character-string variable for I/O
     */
    DECLARE
        PRINTFILE RECORD OUTPUT FILE ENV(
                FIXED_CONTROL_SIZE(2), /* ❸ */
                PRINTER_FORMAT),
        PRINTREC CHARACTER(80) VARYING;

    /*
     * Set up the NEW_PAGE and NEW_LINE variables using the
     * CARRIAGE_CONTROL structure as a template.
     */
    POSINT(CODE) = 12;            /* Assign ASCII code for form feed */
    NEW_PAGE = STRING(CARRIAGE_CONTROL);

    POSINT(CODE) = 13;            /* Assign ASCII code for CR */
    NEW_LINE = STRING(CARRIAGE_CONTROL);

    OPEN FILE(PRINTFILE);

    /*
     * Output first line with no carriage control
     */
    PRINTREC = 'Output first line with no carriage control'; /* ❹ */
    WRITE FILE(PRINTFILE) FROM(PRINTREC);

    /*
     * Prepare to output five line feeds followed by a new line
     */
    POSINT(LINE_FEEDS.COUNT) = 5;  /* assign 5 to LINE_FEEDS.COUNT */ /* ❺ */
    CONTROL_FIELD = STRING(LINE_FEEDS) || NEW_LINE;
    PRINTREC = 'Record preceded by 5 line feeds ';

    WRITE FILE(PRINTFILE) FROM (PRINTREC) OPTIONS(
                FIXED_CONTROL_FROM(CONTROL_FIELD));

    /*
     * Prepare to output a page eject followed by a new line
     */
    CONTROL_FIELD = NEW_PAGE || NEW_LINE; /* ❻ */
    PRINTREC = 'New page';

    WRITE FILE(PRINTFILE) FROM(PRINTREC) OPTIONS( /* ❼ */
                FIXED_CONTROL_FROM(CONTROL_FIELD));

    CLOSE FILE(PRINTFILE) ENV(SPOOL); /* ❽ */

    END PRINTER_FORMAT_EXAMPLE;

When you use the READ_AHEAD option, you can specify the number of buffers to be used in the MULTIBUFFER_COUNT option. When READ_AHEAD is in effect and no multibuffer count is specified, RMS uses two buffers by default.

When READ_AHEAD is enabled, the data transfer and the reading ahead are transparent to the PL/I program.

The READ_CHECK option is meaningful when a file is created or opened. An existing file can be opened for input or for update.

This option is useful for applications that must verify all I/O operations to ensure that data was successfully transferred. However, use of this option decreases the speed and efficiency of I/O operations.

If READ_CHECK is specified when a file is created, READ_CHECK is the default for all subsequent openings of the file, unless explicitly disabled.

You must open a file with this option to use the RECORD_ID_TO and RECORD_ID options of the record I/O statements. These options are described in Chapter 8, Input/Output Statement Options.

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 RETRIEVAL_POINTERS option is meaningful when a file is created or opened.

When a disk is initialized, the default window size is set by the /WINDOW qualifier of the DCL command INITIALIZE. You can override this value for the opening of a specific file by specifying the RETRIEVAL_POINTERS option to increase the speed with which records can be accessed.

However, you should avoid specifying a value that is too large. Space for the pointers is allocated from system space, and a large number of pointers could have an adverse effect on system performance.

The REVISION_DATE option is meaningful only when the file is closed.

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

Magnetic tape file positioning is described in Chapter 6, Record Input/Output.

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.

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.

By default, the SHARED_WRITE option is disabled.

If you specify the DELETE option in conjunction with the SPOOL option, the file is submitted to the queue SYS$PRINT when it is closed and marked to be deleted after printing.

You can control the queue to which the file is submitted by using the DEFINE command to equate the logical name SYS$PRINT with the name of a specific queue before running the program. For example:

$ DEFINE SYS$PRINT LPC0:
$ RUN PRINTER

If the PL/I program PRINTER closes a file with the SPOOL option, the file is queued to LPC0: (the printer device).

By default, the file system creates a new file and assigns it a new version number whenever a file is opened for output. Consequently, if a file specification does not include a version number, many versions of a file may be created. If the file's TITLE option or DEFAULT_FILE_NAME option specifies an explicit version number, the ERROR condition is signaled if a file with that version number already exists.

In some cases, you may want to specify an explicit version number to ensure that a single version of a specific file be maintained. In these cases, specify the SUPERSEDE option in conjunction with a TITLE value or DEFAULT_FILE_NAME value to ensure that multiple versions of the file are not created.

When you create a file with the TEMPORARY option, the file system does not create a directory entry for the file. A file thus created can be used during the execution of the program and deleted on completion, without the overhead required to create and remove the directory entry.

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 no directory entry is created for a temporary file, 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;

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.

Note that the FILE_ID and the FILE_ID_TO options, which are necessary for reaccessing a temporary file, cannot be used across the DECnet.

The TEMPORARY option is also useful in conjunction with the BATCH or SPOOL options. For example, if you create a file that is to be printed but that can be deleted after printing, you can specify it as follows:

DECLARE PRINTFILE FILE  PRINT ENVIRONMENT (
                     SPOOL, TEMPORARY, DELETE);

When this file is closed, it is automatically queued for printing. Once it is printed, it is deleted.

You can specify this option to conserve disk space. If a file's allocation is greater than its contents require, and if the file is not expected to increase in size, you may want to use this option to reclaim the allocated, but unused, space.

The following example shows a PL/I program that creates a file 1000 blocks long.

/*
 * This program allocates 1000 blocks to the file new.tmp.
 */
OPEN_TEST: PROC OPTIONS(MAIN);

DCL F FILE OUTPUT;

OPEN FILE(F) ENVIRONMENT(USER_OPEN(MY_OPEN))  TITLE('NEW.TMP');

RETURN;

    /*
     * This function sets the appropriate bit in the FAB to allocate
     * 1000 blocks for the file.
     */
    MY_OPEN:PROC(FAB,RAB,OPEN_FLAG) RETURNS(FIXED BIN);

    %INCLUDE $FABDEF;
    %INCLUDE $RABDEF;

    DCL 1 FAB LIKE FABDEF;
    DCL 1 RAB LIKE RABDEF;
    DCL OPEN_FLAG FIXED BIN;
    DCL STATUS FIXED BIN;
    %INCLUDE SYS$OPEN;
    %INCLUDE SYS$CREATE;

    /*
     * Store the allocation quantity.
     */
    FAB.FAB$L_ALQ = 1000;
    /*
     * Call sys$open or sys$create and return its status to the Run-Time
     * Library.
     */
    IF OPEN_FLAG = 1 THEN
        STATUS = SYS$OPEN(FAB,,);
    ELSE
        STATUS = SYS$CREATE(FAB,,,);
    RETURN(STATUS);

    END MY_OPEN;

END OPEN_TEST;

When you use the WRITE_BEHIND option, you can specify the number of buffers to be used in the MULTIBUFFER_COUNT option. If you specify WRITE_BEHIND and do not specify a multibuffer count, RMS uses two buffers by default.

When the WRITE_BEHIND option is in effect, there is no way for the program to determine when a buffer has been written to disk. To ensure the integrity of a file that is being processed with the WRITE_BEHIND option, you can use the FLUSH built-in subroutine to periodically write all buffers back to disk. The FLUSH built-in subroutine is described in Chapter 9, File-Handling Built-In Subroutines.

The WRITE_CHECK option is meaningful when a file is created or opened. An existing file can be opened either for update or for output with the APPEND option.

This option is useful for applications that must verify all I/O operations, to ensure that data was successfully transferred. However, use of this option decreases the speed and efficiency of I/O operations.

If WRITE_CHECK is specified when a file is created, WRITE_CHECK is the default for all subsequent openings of the file, unless explicitly disabled.