Enterprise COBOL for z/OS, V4.2, Language Reference

OPEN statement

The OPEN statement initiates the processing of files. It also checks or writes labels, or both.

Read syntax diagramSkip visual syntax diagram
Format 1: OPEN statement for sequential files

>>-OPEN--------------------------------------------------------->

   .---------------------------------------------------------.   
   |          .------------------------------------------.   |   
   V          V                                          |   |   
>----+-INPUT----file-name-1--+-------------------------+-+-+-+-><
     |                       |          (1)            |   |     
     |                       +-REVERSED----------------+   |     
     |                       |                     (1) |   |     
     |                       '-+------+--NO REWIND-----'   |     
     |                         '-WITH-'                    |     
     |         .--------------------------------------.    |     
     |         V                                      |    |     
     +-OUTPUT----file-name-2--+---------------------+-+----+     
     |                        '-+------+--NO REWIND-'      |     
     |                          '-WITH-'                   |     
     |      .-------------.                                |     
     |      V             |                                |     
     +-I-O----file-name-3-+--------------------------------+     
     |         .-------------.                             |     
     |         V             |                             |     
     '-EXTEND----file-name-4-+-----------------------------'     

Notes:
  1. The REVERSED and WITH NO REWIND phrases are not valid for VSAM files.
Read syntax diagramSkip visual syntax diagram
Format 2: OPEN statement for indexed and relative files

         .-----------------------------.   
         |          .-------------.    |   
         V          V             |    |   
>>-OPEN----+-INPUT----file-name-1-+--+-+-----------------------><
           |         .-------------. |     
           |         V             | |     
           +-OUTPUT----file-name-2-+-+     
           |      .-------------.    |     
           |      V             |    |     
           +-I-O----file-name-3-+----+     
           |         .-------------. |     
           |         V             | |     
           '-EXTEND----file-name-4-+-'     

Read syntax diagramSkip visual syntax diagram
Format 3: OPEN statement for line-sequential files

         .-----------------------------.   
         |          .-------------.    |   
         V          V             |    |   
>>-OPEN----+-INPUT----file-name-1-+--+-+-----------------------><
           |         .-------------. |     
           |         V             | |     
           +-OUTPUT----file-name-2-+-+     
           |         .-------------. |     
           |         V             | |     
           '-EXTEND----file-name-4-+-'     

The phrases INPUT, OUTPUT, I-O, and EXTEND specify the mode to be used for opening the file. At least one of the phrases INPUT, OUTPUT, I-O, or EXTEND must be specified with the OPEN keyword. The INPUT, OUTPUT, I-O, and EXTEND phrases can appear in any order.

INPUT
Permits input operations.
OUTPUT
Permits output operations. This phrase can be specified when the file is being created.

Do not specify OUTPUT for files that:

  • Contain records. The file will be replaced by new data.

    If the OUTPUT phrase is specified for a file that already contains records, the data set must be defined as reusable and cannot have an alternate index. The records in the file will be replaced by the new data and any ALTERNATE RECORD KEY clause in the SELECT statement will be ignored.

  • Are defined with a DD dummy card. Unpredictable results can occur.
I-O
Permits both input and output operations. The I-O phrase can be specified only for files assigned to direct access devices.

The I-O phrase is not valid for line-sequential files.

EXTEND
Permits output operations that append to or create a file.

The EXTEND phrase is allowed for sequential access files only if the new data is written in ascending sequence. The EXTEND phrase is allowed for files that specify the LINAGE clause.

For QSAM files, do not specify the EXTEND phrase for a multiple file reel.

If you want to append to a file, but are unsure if the file exists, use the SELECT OPTIONAL clause before opening the file in EXTEND mode. The file will be created or appended to, depending on whether the file exists.

file-name-1 , file-name-2 , file-name-3 , file-name-4
Designate a file upon which the OPEN statement is to operate. If more than one file is specified, the files need not have the same organization or access mode. Each file-name must be defined in an FD entry in the data division and must not name a sort or merge file. The FD entry must be equivalent to the information supplied when the file was defined.
REVERSED
Valid only for sequential single-reel files. REVERSED is not valid for VSAM files.

If the concept of reels has no meaning for the storage medium (for example, a direct access device), the REVERSED and NO REWIND phrases do not apply.

NO REWIND
Valid only for sequential single-reel files. It is not valid for VSAM files.

For information on file sizes, see Compiler limits

General rules

  • If a file opened with the INPUT phrase is an optional file that is not available, the OPEN statement sets the file position indicator to indicate that an optional input file is not available.
  • Execution of an OPEN INPUT or OPEN I-O statement sets the file position indicator:
    • For indexed files, to the characters with the lowest ordinal position in the collating sequence associated with the file.
    • For sequential and relative files, to 1.
  • When the EXTEND phrase is specified, the OPEN statement positions the file immediately after the last record written in the file. (The record with the highest prime record key value for indexed files or relative key value for relative files is considered the last record.) Subsequent WRITE statements add records as if the file were opened OUTPUT. The EXTEND phrase can be specified when a file is being created; it can also be specified for a file that contains records, or that has contained records that have been deleted.
  • For VSAM files, if no records exist in the file, the file position indicator is set so that the first format 1 READ statement executed results in an AT END condition.
  • When NO REWIND is specified, the OPEN statement execution does not reposition the file; prior to OPEN statement execution, the file must be positioned at its beginning. When the NO REWIND phrase is specified (or when both the NO REWIND and REVERSE phrases are omitted), file positioning is specified with the LABEL parameter of the DD statement.
  • When REVERSED is specified, OPEN statement execution positions the QSAM file at its end. Subsequent READ statements make the data records available in reversed order, starting with the last record.

    When OPEN REVERSED is specified, the record format must be fixed.

  • When the REVERSED, NO REWIND, or EXTEND phrases are not specified, OPEN statement execution positions the file at its beginning.

If the PASSWORD clause is specified in the file-control entry, the password data item must contain a valid password before the OPEN statement is executed. If a valid password is not present, OPEN statement execution is unsuccessful.

Label records

If label records are specified for the file when the OPEN statement is executed, the labels are processed according to the standard label conventions, as follows:

INPUT files
The beginning labels are checked.
OUTPUT files
The beginning labels are written.
I-O files
The labels are checked; new labels are then written.
EXTEND files
The following procedures are executed:
  • Beginning file labels are processed only if this is a single-volume file.
  • Beginning volume labels of the last existing volume are processed as though the file was being opened with the INPUT phrase.
  • Existing ending file labels are processed as though the file was being opened with the INPUT phrase; they are then deleted.
  • Processing continues as if the file were opened as an OUTPUT file.

When label records are specified but not present, or are present but not specified, execution of the OPEN statement is unpredictable.

OPEN statement notes

  1. The successful execution of an OPEN statement determines the availability of the file and results in that file being in open mode. A QSAM file is available if it has a DD allocation and is physically present. A VSAM file is available if it has a DD allocation, has been defined using VSAM access method services, and contains records or has previously contained records. For more information regarding file availability, see Opening a file (EDS, KSDS, or RRDS) in the Enterprise COBOL Programming Guide. The following table shows the results of opening available and unavailable files.

    Table 1. Availability of a file
    Opened as File is available File is unavailable
    INPUT Normal open Open is unsuccessful. (file status 35)
    INPUT (optional file) Normal open Normal open; the first read causes the at end condition or the invalid key condition. (file status 05)
    I-O Normal open Open is unsuccessful. (file status 35)
    I-O (optional file) Normal open Open causes the file to be created. (file status 05)
    OUTPUT Normal open; the file contains no records Open causes the file to be created.
    EXTEND Normal open Open is unsuccessful. (file status 35)
    EXTEND (optional file) Normal open Open causes the file to be created. (file status 05)
  2. The successful execution of the OPEN statement places the file in open status and makes the associated record area available to the program.
  3. The OPEN statement does not obtain or release the first data record.
  4. You can move data to or from the record area only when the file is in open status.
  5. An OPEN statement must be successfully executed prior to the execution of any of the permissible input-output statements, except a SORT or MERGE statement with the USING or GIVING phrase. In the following table, an 'X' indicates that the specified statement can be used with the open mode given at the top of the column.

Table 2. Permissible statements for sequential files
Statement Input open mode Output open mode I-O open mode Extend open mode
READ X   X  
WRITE   X   X
REWRITE     X  

In the following table, an 'X' indicates that the specified statement, used in the access mode given for that row, can be used with the open mode given at the top of the column.

Table 3. Permissible statements for indexed and relative files
File access mode Statement Input open mode Output open mode I-O open mode Extend open mode
Sequential READ X   X  
WRITE   X   X
REWRITE     X  
START X   X  
DELETE     X  
Random READ X   X  
WRITE   X X  
REWRITE     X  
START        
DELETE     X  
Dynamic READ X   X  
WRITE   X X  
REWRITE     X  
START X   X  
DELETE     X  

In the following table, an 'X' indicates that the specified statement can be used with the open mode given at the top of the column.

Table 4. Permissible statements for line-sequential files
Statement Input open mode Output open mode I-O open mode Extend open mode
READ X      
WRITE   X   X
REWRITE        
  1. A file can be opened for INPUT, OUTPUT, I-O, or EXTEND (sequential and line-sequential files only) in the same program. After the first OPEN statement execution for a given file, each subsequent OPEN statement execution must be preceded by a successful CLOSE file statement execution without the REEL or UNIT phrase (for QSAM files only), or the LOCK phrase.
  2. If the FILE STATUS clause is specified in the file-control entry, the associated file status key is updated when the OPEN statement is executed.
  3. If an OPEN statement is issued for a file already in the open status, the EXCEPTION/ERROR procedure (if specified) for this file is executed.


Rate this page

[ Index | Table of contents ]