Input-Output Section

The INPUT-OUTPUT Section describes the Input-Output environment of the program. When compiling with a relaxed syntax check, the header for this section is optional.

General Format:

       [ [ INPUT-OUTPUT SECTION. ] 
              [ FILE-CONTROL. ] { file-control-entry } ... 
              [ I-O-CONTROL. [ i-o-control-entry ] ] ] ]

General Rules:

The General Rules for the Statements and Clauses of the Environment Division entries are described below.

File-Control Paragraph

The FILE-CONTROL paragraph contains information about the files in the program.

General Format:

       [ FILE-CONTROL. ] { file-control-sequence } ... 

              SELECT [OPTIONAL} filename 
              select_clause_sequence '.'

Syntax:

The file-control-sequence is a description of the attributes of an Indexed, Sequential, Relative, or Sort file.
The select_clause_ sequence is a sequence of clauses, as described below, which provide the information needed to create, and manage the named file.
Not all clauses are valid in all file formats. Below are the valid usages of clauses in Indexed, Sequential, Relative, and Sort files respectively:

General Rules:

The General Rules for each of the different file formats is described below.

Indexed File Format

General Format:

       SELECT [OPTIONAL] file-name 
              ASSIGN TO [ DYNAMIC ] [ { DISK } ] [ assignment-name ] 
                        [ EXTERNAL] 

       [ ORGANIZATION IS ] INDEXED 

       [ ACCESS MODE IS { SEQUENTIAL } ] 
                        { RANDOM     } 
                        { DYNAMIC    }

       [ RECORD KEY IS record-key ] 
       [ ALTERNATE RECORD KEY IS alt-rec-key [WITH [NO] DUPLICATES] ] 

       [ LOCK MODE IS {MANUAL WITH LOCK ON [MULTIPLE]   {RECORD }} ] 
                                                        {RECORDS} 
                     {AUTOMATIC WITH LOCK ON [MULTIPLE] {RECORD }} 
                                                        {RECORDS} 
                     {EXCLUSIVE } 
                     [ WITH ROLLBACK ] 

       [ SHARING [WITH] { ALL OTHER } ]. 
                        { NO OTHER  } 
                        { READ ONLY } 

       [ RESERVE {number} [AREA ]] 
                 {NO    } [AREAS] 
       [ COLLATING SEQUENCE IS alphabet-name ] 

       [ FILE STATUS IS file-status-var1 ] .

Sequential file format

General Format:

       SELECT [OPTIONAL} filename 

              ASSIGN TO [ DYNAMIC ] [ { DISK } ] [ assignment-name ] 
                        [ EXTERNAL] { PRINTER } 

       [ [ ORGANIZATION IS ] {[BINARY] SEQUENTIAL} ] 
                              [RECORD] 
                              [LINE ] 

       [ ACCESS MODE IS SEQUENTIAL ] 

       [ LOCK MODE IS { MANUAL    } ] 
                      { AUTOMATIC } 
                      { EXCLUSIVE } 

       [ SHARING [WITH] { ALL OTHER } ]. 
                        { NO OTHER  } 
                        { READ ONLY } 

       [ RESERVE {number} [AREA ]] 
                 {NO    } [AREAS] 

       [ RECORD DELIMITER IS STANDARD-1 ] 

       [ FILE STATUS IS file-status-var1 ] 

       [ PADDING CHARACTER IS padding-char ].

Relative file format

General Format:

       SELECT [OPTIONAL} filename 
              ASSIGN TO [ DYNAMIC ] [ { DISK } ] [ assignment-name ] 
                        [ EXTERNAL] 

       [ ORGANIZATION IS ] RELATIVE 

       [ ACCESS MODE IS { SEQUENTIAL } ] 
                        { RANDOM     } 
                        { DYNAMIC    } 

       [ RELATIVE KEY IS relative-key ] 

       [ LOCK MODE IS {MANUAL WITH LOCK ON [MULTIPLE] {RECORD }} ] 
                                                      {RECORDS} 
              {AUTOMATIC WITH LOCK ON [MULTIPLE] {RECORD }} 
                                                 {RECORDS} 
              {EXCLUSIVE                                  } 

       [ SHARING [WITH] { ALL OTHER } ]. 
                        { NO OTHER  } 
                        { READ ONLY } 

       [ RESERVE {number} [AREA ]] 
                 {NO    } [AREAS] 

       [ FILE STATUS IS file-status-var1 ] .

Sort file format

General Format:

       SELECT file-name 
              ASSIGN TO [ DYNAMIC ] [ { DISK } ] [ assignment-name ] 
                        [ EXTERNAL] 

       [ FILE STATUS IS file-status-var1 ] .

File control clauses

Assign clause

The ASSIGN clause describes where the data will be stored.

General Format:

       ASSIGN TO [ DYNAMIC ] [ { DISK } ] [ assignment-name ] 
                 [ EXTERNAL]   { PRINTER }

Syntax:

assignment-name is either a non-numeric literal or an alphanumeric data item in the working-storage section.
File-name and assignment-name may be the same name.

General Rules:

The DYNAMIC phrase indicates that assignment name is a data item. assignment-name does not need to be initialized to a value when the run unit is initiated, but it must have a value when the OPEN statement is executed.
The EXTERNAL phrase indicates that assignment name is a COBOL word. COBOL-IT will look for a file of the exact name, or an environment variable that matches assignment name to resolve the filename.
The DISK and PRINTER phrases can only be used with files described with sequential files, as determined by the ORGANIZATION clause.
The PRINTER phrase causes the file to be considered a Print file. Print files can only be OPENed OUTPUT, and EXTEND. Records that written to a Print files strip trailing spaces. See Using Data Files in the Getting Started with COBOL-IT document for more information on how COBOL-IT resolves filenames included in the ASSIGN clause.
Unix command pipes are not supported by COBOL-IT. Notations such as "| cmd" or "< cmd" in a file name are not supported. If this functionality is required, you should use the use CALL "SYSTEM", write output to a temporary file, and then address the temporary file in your ASSIGN Clause.

Lock mode clause

General Format:

       [LOCK MODE IS {MANUAL WITH LOCK ON [MULTIPLE] {RECORD }} ] 
                                                     {RECORDS} 

              {AUTOMATIC WITH LOCK ON [MULTIPLE] {RECORD }} 
                                                 {RECORDS} 

              {EXCLUSIVE                                 } 

              [ WITH ROLLBACK ]

General Rules:

The file system must support COMMIT and ROLLBACK, otherwise the WITH ROLLBACK clause, COMMIT statement and ROLLBACK statement have no effect.
When the WITH ROLLBACK phrase is used in the LOCK MODE clause, a file may use the COMMIT and ROLLBACK statements.
WITH ROLLBACK implies LOCK MODE IS AUTOMATIC, as any of the I-O statements WRITE, REWRITE, DELETE automatically place a lock on the record that is the target of the I-O statement. These locks are released when either the COMMIT or ROLLBACK statement is executed.
The effect of the ROLLBACK statement is that all record updates, through WRITE, REWRITE, DELETE statements since the last COMMIT or ROLLBACK statement are nullified, or “rolled back”.
The effect of the COMMIT statement is that all record updates, through WRITE, REWRITE, DELETE statements are flushed to from buffers to the data source, and locks released.

Access Clause

The ACCESS clause describes whether the data will be accessible sequentially, or through keyed READs, or both.

General Format:

       [ACCESS [MODE] IS { SEQUENTIAL } ] 
                         { RANDOM     } 
                         { DYNAMIC    }

General Rules:

ACCESS MODE IS SEQUENTIAL indicates that records are only accessible sequentially, through READ NEXT statements, which retrieve the next record, as defined by the organization of the file.
ACCESS MODE IS SEQUENTIAL can be applied to files described with ORGANIZATION that is SEQUENTIAL, RELATIVE, or INDEXED.
ACCESS MODE IS RANDOM indicates that records are only accessible through READs on a KEY.
ACCESS MODE IS RANDOM can be applied to files described with ORGANIZATION that is RELATIVE or INDEXED. For relative files, the RELATIVE KEY is the key of reference. For indexed files, the RECORD KEY is the key of reference.
ACCESS MODE IS DYNAMIC indicates that records are accessible either through READ NEXT statements, or READs on a KEY.
ACCESS MODE IS DYNAMIC can be applied to files described with ORGANIZATION that is RELATIVE or INDEXED.
If no ACCESS MODE is described, then ACCESS MODE IS SEQUENTIAL is assumed.

Alternate Record Key Clause

The ALTERNATE RECORD KEY clause describes a non-primary RECORD KEY which may or may not accept DUPLICATES.

General Format:

       [ ALTERNATE RECORD KEY IS alt-rec-key [WITH [NO] DUPLICATES] ] 

       [ ALTERNATE RECORD KEY IS split-key-name = item1, item2 … 
                                             [WITH [NO] DUPLICATES] ]

Syntax:

alt-rec-key is a data item in the file's FD record description.
split-key name must be unique in the module.

General Rules:

The number of alternate record keys in a file is set when the file is created. alt-rec-key names a data element within the file description (FD) as an alternate key of reference for the file.
split-key-name is a user defined name that is associated with a series of non-contiguous data elements within the file description as a key of reference. Split-key-name is needed when using split keys, and referencing the non-contiguous data elements in a READ KEY IS [record-key] or START KEY IS [record-key] statement.
The WITH DUPLICATES phrase indicates that the data file may contain more than one record matching the given alternate record key of reference.
The WITH NO DUPLICATES phrase indicates that the alternate record key of reference is a unique identifier of a record within the file.

Collating Sequence Clause

The COLLATING SEQUENCE clause names the alphabet used for purposes of sorting a key in an indexed file. The alphabet must be declared in SPECIAL-NAMES.

General Format:

[ COLLATING SEQUENCE IS alphabet-name ]

General Rules:

The alphabet-name used in the COLLATING SEQUENCE clause must be either an alphabet name that is declared in SPECIAL-NAMES with an ALPHABET clause, or EBCDIC.

File status clause

The FILE STATUS clause returns the status of the most recent FILE I/O operation.

General Format:

[ FILE STATUS IS file-status-var ]

Syntax:

file-status-var may be declared as PIC 99 or PIC XX.

General Rules:

file-status-var is updated following every I-O operation for the associated file.
A status of “00” indicates a successful I-O operation.
For information on how unsuccessful I-O operations update file-status-var, see File Status Codes.

Lock Mode Clause

The LOCK MODE clause describes the means by which LOCKing of records will be applied within the File.

General Format:

       [LOCK MODE IS {MANUAL WITH LOCK ON [MULTIPLE] {RECORD }} ] 
                                                     {RECORDS} 

              {AUTOMATIC WITH LOCK ON [MULTIPLE] {RECORD }} 
                                                 {RECORDS} 
              {EXCLUSIVE                                 } 

              {WITH ROLLBACK }

General Rules:

If there is no LOCK MODE clause, then LOCK MODE is AUTOMATIC is assumed unless a SHARING clause in the SELECT statement or in the OPEN statement indicates otherwise. Note that some file systems and some operating systems do not support record locking. In these cases, all references to LOCK MODE are treated as commentary.
The LOCK MODE IS MANUAL phrase applies when there is a READ on a record in a file that is OPENed in the I-O mode. When LOCK MODE IS MANUAL, the READ statement must include a WITH LOCK clause in order for a lock to be applied.
The LOCK MODE IS AUTOMATIC phrase applies when there is a READ on a record in a file that is OPENed in the I-O mode. When LOCK MODE IS AUTOMATIC, the record retrieved by the READ is locked automatically, unless the READ statement includes a WITH NO LOCK clause.
The LOCK MODE IS EXCLUSIVE phrase locks the entire file for exclusive use.
The WITH LOCK ON MULTIPLE RECORDS phrase allows the file to hold multiple record locks within the same file.
The WITH ROLLBACK phrase is recognized, and syntax is validated. However, the WITH ROLLBACK clause is otherwise treated as commentary.

LINE ADVANCING Clause

The LINE ADVANCING clause is recognized, and syntax is validated. However, the LINE ADVANCING clause is otherwise treated as commentary.

General Rules:

There are no General Rules.

OPTIONAL Clause

The OPTIONAL clause affects the behaviour of the OPEN statement when the file being OPEN’ed is not present.

General Rules:

When the OPTIONAL clause is included in the SELECT phrase, the OPEN statement does not require that the named file be available in order for the OPEN to be successful.
The effect of the OPTIONAL clause varies depending on the OPEN mode.
- OPEN INPUT: The OPEN succeeds, but the file is not created. The first attempt to READ data in the file fails.
- OPEN I-O: The OPEN succeeds and the file is created. WRITEs to the file are successful.
- OPEN Extend: The OPEN succeeds and the file is created. WRITEs to the file are successful.

ORGANIZATION Clause

The ORGANIZATION clause describes the logical structure of the file.

General Format:

       [ [ ORGANIZATION IS ] {INDEXED           } ] 
                            {[BINARY] SEQUENTIAL} 
                             [RECORD] 
                             [LINE ] 
                            {RELATIVE           }

General Rules ;

ORGANIZATION IS INDEXED phrase indicates that the file is an indexed file. Indexed files can be accessed sequentially, or through a RECORD KEY, which identifies a record, and which establishes the order in which the records are ordered in the file.
The ORGANIZATION IS RELATIVE phrase indicates that the file is a relative file. Relative files can be accessed sequentially, or through a RELATIVE KEY, which represents a record’s ordinal position in the file.
ORGANIZATION IS SEQUENTIAL indicates that the file is a sequential file. Sequential files can only be accessed sequentially. Records are stored in a sequential file in the order in which they were added to the file.
ORGANIZATION IS BINARY/RECORD SEQUENTIAL indicates that the file is a sequential file, and does not contain record delimiters.
BINARY and RECORD are synonyms.
ORGANIZATION IS LINE SEQUENTIAL indicates that the file is a sequential file, and contains record delimiters.

PADDING CHARACTER Clause

The PADDING CHARACTER designates a single character literal to pad the last block of the file.

General Format:

[ PADDING CHARACTER IS padding-char ]

Syntax:

padding-char is a single character literal or alphanumeric data item.

General Rules:

If padding-char is not specified, the SPACE is used as padding-char.
When a PADDING CHARACTER is defined, that character is used to pad the last block of the file.

RECORD DELIMITER Clause

The RECORD DELIMITER clause is recognized, and syntax is validated. However, the RECORD DELIMITER clause is otherwise treated as commentary.

General Format:

[ RECORD DELIMITER IS STANDARD-1 ]

General Rules:

There are no General Rules.

RECORD KEY Clause

The RECORD KEY clause names the field in the file definition of an indexed file that is to be considered the primary key, for purposes of RANDOMly accessing records.

General Format:

       [ RECORD KEY IS record-key ] 

       [ RECORD KEY IS split-key-name = item1 item2 … ]

Syntax:

record-key is a data item in the file's FD record description.
split-key-name must be unique in the module.

General Rules:

RECORD KEY is defined when the file is created.
Record-key names a data element within the file description (FD) as a primary key of reference for the file, determining the order in which records are retrieved when READ using RECORD KEY.
RECORD KEY is a unique identifier of a record within the file.
split-key-name is a user defined name that is associated with a series of non-contiguous data elements within the file description as a key of reference. Split-key-name is needed when using split keys, and referencing the non-contiguous data elements in a READ KEY IS [record-key] or START KEY IS [record-key] statement.

RELATIVE KEY Clause

The RELATIVE KEY clause names the field in the working-storage section that is to be considered the relative key, for purposes of RANDOMly accessing records in a relative file.

General Format:

[ RELATIVE KEY IS rel-key ]

Syntax:

rel-key is an unsigned integer data item declared in the working-storage section.

General Rules:

Relative files can be accessed through a RELATIVE KEY, which is stored in an unsigned data item declared in the working-storage section, and which represents a record’s ordinal position in the file.
rel-key must be set to a positive integer value before performing I-O operations.

RESERVE Clause

The RESERVE clause is recognized, and syntax is validated. However, the RESERVE clause is otherwise treated as commentary.

General Format:

       RESERVE {number} [AREA ]] 
               {NO }   [AREAS]

General Rules:

There are no General Rules.

The SHARING clause describes the situations in which concurrent access to a file is allowed from multiple processes.

General Format:

       [ SHARING [WITH] { ALL OTHER } ]. 
                        { NO OTHER  } 
                        { READ ONLY }

General Rules:

The SHARING clause sets a level of restrictiveness on whether a file that has been OPENed can be OPENed by another file connector. Conditions causing a failed OPEN are marked with the word “Fails”, and conditions leading to a successful OPEN are marked with the word “Succeeds” in the table below:

Table 1

SORT TABLE

A SHARING phrase on an OPEN statement takes precedence over a SHARING phrase in a SELECT statement.

I-O-CONTROL

The I-O-CONTROL paragraph describes input-output rules that are applicable for specified files.

General Format:

       I-O-CONTROL. 
              [ APPLY WRITE-ONLY ON {file-name} ... ] ... 
              [ SAME [RECORD ] AREA FOR {file-name} ... ] ... 
                     [SORT ] 
                     [SORT-MERGE] 
              [ MULTIPLE FILE TAPE CONTAINS 
              { file-name [ POSITION position-integer ] } ... ] ... .

Syntax:

file-name is a file described by a SELECT clause in the FILE-CONTROL paragraph.
position-integer is an integer literal.

General Rules:

The APPLY clause is recognized, and syntax is validated. However, the APPLY clause is otherwise treated as commentary.
The SAME RECORD AREA clause causes the listed files to share the same memory. Care should be taken to ensure that of the listed files, only one is OPEN at a time.
The SAME SORT AREA clause is recognized, and syntax is validated. However, the SAME SORT AREA clause is otherwise treated as commentary.
The SAME SORT-MERGE AREA clause is recognized, and syntax is validated. However, the SAME SORT-MERGE AREA clause is otherwise treated as commentary.
The MULTIPLE FILE TAPE clause is recognized, and syntax is validated. However, the MULTIPLE FILE TAPE clause is otherwise treated as commentary.

Input-Output Section

File-Control Paragraph

Indexed File Format

Sequential file format

Relative file format

Sort file format

File control clauses

Assign clause

Lock mode clause

Access Clause

Alternate Record Key Clause

Collating Sequence Clause

File status clause

Lock Mode Clause

LINE ADVANCING Clause

OPTIONAL Clause

ORGANIZATION Clause

PADDING CHARACTER Clause

RECORD DELIMITER Clause

RECORD KEY Clause

RELATIVE KEY Clause

RESERVE Clause

SHARING Clause

I-O-CONTROL