File-Control Paragraph

The FILE-CONTROL paragraph contains descriptions of the physical aspects of the files the program uses.

General Format

[ FILE-CONTROL. ] { file-control-entry } ...
or 
{ file-control-entry } ...
File-control-entry has one of the following formats:

Format 1 — Sequential Files

SELECT [ OPTIONAL ] file-name
   ASSIGN TO [ DYNAMIC ] [ device ] [ file-spec ]
             [ EXTERNAL]
[ [ ORGANIZATION IS ] [BINARY] SEQUENTIAL ]
                      [RECORD]
                      [LINE ]
[ ACCESS MODE IS SEQUENTIAL ]
[ RESERVE {number} [ALTERNATE] [AREA ]]
          {NO }                [AREAS]
[ LOCK MODE IS {EXCLUSIVE}
               {AUTOMATIC}
               {MANUAL }
 [ RECORD DELIMITER IS [ STANDARD-1 ]
[ FILE STATUS IS status-variable [status-variable-2]]
[ PADDING CHARACTER IS pad-char ] .

Format 2 - Relative Files

SELECT [ OPTIONAL ] file-name
   ASSIGN TO [ DYNAMIC ] [ device ] [ file-spec ]
             [ EXTERNAL]
[ ORGANIZATION IS ] RELATIVE
[ ACCESS MODE IS
  { SEQUENTIAL [ RELATIVE KEY IS rel-key ] } ]
  { RANDOM       [RELATIVE] KEY IS rel-key   }
                 [ACTUAL]
  { DYNAMIC RELATIVE KEY IS rel-key        }
[ LOCK MODE IS { EXCLUSIVE                      }
                 { AUTOMATIC [ multiple-option ] }
                 { MANUAL    [ multiple-option ] }
  [ RESERVE {number} [ALTERNATE] [AREA ]]
            {NO    }             [AREAS]
  [ FILE STATUS IS status-variable [status-variable-2] ] .

See the multiple-option format at the end of the formats.

Format 3 - Indexed Files

SELECT [ OPTIONAL ] file-name
   ASSIGN TO [ DYNAMIC ] [ device ] [ file-spec ]
             [ EXTERNAL]
 [ WITH {COMPRESSION} ... ]
        {ENCRYPTION }
 [ COMPRESSION CONTROL VALUE IS factor ]
 [ ORGANIZATION IS ] INDEXED
 [ ACCESS MODE IS {SEQUENTIAL} ]
                  {RANDOM    }
                  {DYNAMIC   }
 [ RECORD KEY IS key-name [= seg-name ...]
    [ WITH [NO] DUPLICATES ] ] ...
 [ ALTERNATE RECORD KEY IS alt-name [= seg-name ...]
    [ WITH [NO] DUPLICATES ] ] ... 
 [ LOCK MODE IS { EXCLUSIVE [ WITH MASS-UPDATE ] }
                { AUTOMATIC [ multiple-option  ] }
                { MANUAL    [ multiple-option  ] }
 [ RESERVE {number} [ALTERNATE] [AREA ]]
           {NO    }             [AREAS]
 [ FILE STATUS IS status-variable [status-variable-2] ]
 [ COLLATING SEQUENCE IS alphabet-name ] .

Format 4 - Sort Files

SELECT file-name
   ASSIGN TO [ DYNAMIC ] [ device ] [ file-spec ]
             [ EXTERNAL]
 [ FILE STATUS IS status-variable [status-variable-2]] .
Note: multiple-option has the following format for both Format 2 and Format 3. 
WITH { { LOCK ON } [ MULTIPLE ] { RECORD } } [WITH ROLLBACK]
     { ROLLBACK }

Syntax Rules

  1. File-spec must be either a nonnumeric literal or the name of an alphanumeric Working-Storage data item.
  2. Device must be one of these words: INPUT, OUTPUT, INPUT-OUTPUT, RANDOM, DISK, DISC, PRINT, PRINTER, PRINTER-1, TAPE, CASSETTE, CARD-PUNCH, CARD-READER, CONSOLE, MAGNETIC-TAPE, DISPLAY, KEYBOARD, SORT, MERGE, SORT-MERGE, or SORT-WORK. The last four may be used only with sort files.
  3. If DYNAMIC is specified, file-spec must be specified and must be the name of a data item. This data item need not be defined in the program, although it can be.
  4. If EXTERNAL is specified, file-spec must be specified and must be a user-defined COBOL word.
  5. status-variable must be the name of an alphanumeric (or USAGE DISPLAY numeric) Working-Storage or Linkage data item with a size of 2 characters. Status-variable-2 must be the name of a group item that is 6 characters (this is not checked by the compiler).
  6. rel-key must name an unsigned integer data item. It must not be in the record description entry for the same file.
  7. factor must be a numeric literal from zero to 100, inclusive.
  8. The key of an indexed file may have any PICTURE and USAGE. Regardless of the PICTURE and USAGE specified, the key is always treated as an alphanumeric data item when the sort order of the file is determined (the individual bytes are compared with the collating sequence).
  9. seg-name must name a data item in the same file's record description entry. A seg-name may not be a group item that contains variable-occurrence data items.
  10. If seg-name is used to define a split RECORD KEY, key-name is a user-defined word. Otherwise, key-name must name a data item in the same file's record description entry. It may not be a group item that contains variable-occurrence data items.
  11. If seg-name is used to define a split ALTERNATE RECORD KEY, alt-name is a user-defined word. Otherwise, alt-name must name a data item in the same file's record description entry. It may not be a group item that contains variable-occurrence data items.
  12. number must be an integer literal.
  13. alphabet-name is the name of an alphabet declared in the Special-Names paragraph.
  14. pad-char must be either a single-character literal or a single-character alphanumeric data item. When a PADDING CHARACTER is specified, the last block of the file is padded with pad-char. When the file is read, any final portion of a block that consists solely of padding characters is skipped.
  15. SELECT must be the first clause in a FILE-CONTROL entry. The other clauses may follow in any order. The SELECT clause may appear in Area A; all other clauses must appear in Area B.
  16. Each file described in the Data Division must be specified exactly once in the FILE-CONTROL paragraph.
  17. Each file described by a SELECT clause must have exactly one corresponding file description in the Data Division.
  18. ORGANIZATION IS RECORD SEQUENTIAL is synonymous with ORGANIZATION IS BINARY SEQUENTIAL.

General Rules

  1. When the FILE STATUS clause is specified, a value will be moved into status-variable after the execution of every statement that references the corresponding file. This value indicates the status of the statement status-variable-2 is treated as commentary by the compiler. See I/O Status for more information.
  2. The ACCESS MODE clause specifies the order in which records are read or written. If it is not specified, SEQUENTIAL is implied.
  3. For sequential access, the records are accessed according to the organization of the file:
    Sequential files     The sequence is the same as that established by the execution of WRITE statements that created the file
    Relative files The sequence is the order of ascending relative record numbers for the file's existing records
    Indexed files The sequence is the order of ascending record key values for the file's current key of reference
  4. Random access indicates that the file will be accessed only by key value.
  5. Dynamic access indicates that the file will be accessed both randomly and sequentially.
  6. RELATIVE KEY results in record key numbers that are one-based. ACTUAL KEY may be specified for RANDOM access mode and when compiling version 8.1 and greater objects in IBM DOS/VS (-cv) and HP3000 (-cp) compatibility modes. For such files, the record key numbers will be zero-based. For example, if you have a relative file with a fixed record length of 3 bytes and a relative file with the following contents: 
    AAABBBCCC
the record keys for the different modes are:
     RELATIVE  ACTUAL
AAA:    1        0
BBB:    2        1
CCC:    3        2
  7. The ASSIGN clause specifies the association of the file to a storage device. If the file-spec phrase is missing, file-name will be treated as an alphanumeric literal and substituted for it (exception: rule 8.a below). In this case, file-name should conform to the host operating system's rules for file names. Note that the ASSIGN clause is required even if both device and file-spec are missing.
  8. The device phrase of the ASSIGN clause is not required. If it is specified, it can affect the processing of the file in a variety of ways. If the file is not a sequential file, the device phrase is ignored. If it is a sequential file, the following applies depending on the device phrase used:
    1. PRINT, PRINTER, PRINTER-1 — A sequential file marked with one of these device phrases will be treated as a print file. Print files may not be opened for INPUT or I/O. When records are written to a print file, trailing spaces are first removed from the record. Print files have printer carriage control information added to them as specified by the WRITE statements that add records to the file. If PRINTER or PRINTER-1 is specified, and no file-spec is specified, the external file name is treated as PRINTER or PRINTER-1 (unless RM/COBOL compatibility mode is being used, in which case rule 6 applies instead). Normally, these names are translated at runtime to the name of the system spooler. This is an exception to rule 6 above.
    2. CARD-PUNCH, CARD-READER, CASSETTE, INPUT, INPUT-OUTPUT, MAGNETIC-TAPE, OUTPUT — Any of these device phrases indicates that trailing spaces should be removed from records before they are added to the file. This will have effect only if the file is a "line" sequential file. When records are read from one of these files, the records are automatically padded with spaces to reach the maximum record size. A file with one of these designators may not be opened for I/O.
    3. DISPLAY, KEYBOARD — Causes the default file type to be line sequential. You may override this by specifying the file type explicitly in the ORGANIZATION clause. This rule is provided for compatibility with ICOBOL, which uses this method for specifying line sequential files.
    4. RANDOM, DISK, DISC, TAPE, CONSOLE — Indicates no additional processing. This is the same as if the device phrase were omitted.
    5. MERGE, SORT, SORT-MERGE, SORT-WORK — Also indicates no additional processing. These device phrases may be associated with a sort file only.
  9. The word "DYNAMIC" in an ASSIGN phrase indicates that file-spec is the name of a variable that contains the file's name. Because this is the normal meaning of file-spec when it refers to a variable, the word DYNAMIC is largely commentary.
  10. When DYNAMIC is specified, if file-spec refers to a variable that is not otherwise defined, the compiler creates a Working-Storage variable by that name that is PIC X(256). It is the program's responsibility to move a valid file name to this data item prior to opening the file.
  11. The word EXTERNAL in an ASSIGN phrase indicates that the COBOL word that makes up file-spec is the name of the file itself. This name is processed first by ignoring any characters that appear before the last hyphen in the word (including the hyphen itself). For example: 
       ASSIGN TO EXTERNAL UT-S-MYFILE

    results in MYFILE being used for the file name. In other COBOL systems, this name is normally assigned to a specific file name using environment variables. This kind of name mapping occurs automatically under Micro Focus. There is no special meaning associated with ASSIGN phrases containing the EXTERNAL option. Such files have name mapping applied through the environment just like all other files.

    Note: If neither DYNAMIC nor EXTERNAL is included in the ASSIGN clause, you can use the --fileAssign= compiler option to specify DYNAMIC or EXTERNAL at compile time. For more information, see File Options.
  12. The WITH COMPRESSION phrase of the ASSIGN clause specifies that file record compression is desired. This phrase must be specified before the ORGANIZATION IS INDEXED phrase. The Micro Focus indexed file system supports compression, but not all file systems do. The WITH COMPRESSION phrase takes effect only when the file is initially created or re-created via the OPEN statement. When no compression factor is specified (see next paragraph), WITH COMPRESSION uses the default compression factor (70).

    A compression factor other than the default may be selected via the COMPRESSION CONTROL VALUE IS clause. The factor must be a numeric literal from zero (meaning no compression) to 100 (maximum compression). A compression factor of 1 is equivalent to the default compression.

    The exact meaning of the compression factor depends upon the host file system. See Indexed Files Vision for specifics about the Vision file system.

  13. The WITH ENCRYPTION phrase specifies that record encryption is desired on the file. Encryption is currently available with the Micro Focus indexed file system only. The ENCRYPTION clause takes effect only when the file is initially created or re-created via the OPEN statement.
  14. The ORGANIZATION clause specifies the logical structure of the file. This is established when a file is first created and may not be changed. If it is absent, then SEQUENTIAL organization is implied. Records stored in an ORGANIZATION IS RELATIVE file are uniquely identified by record number. The relative record number of a given record specifies the record's ordinal position in the file. The first record has a relative record number of one.
  15. Records in an ORGANIZATION IS INDEXED file are uniquely identified by the values in the record's primary key.
  16. The primary key is identified by the RECORD KEY clause. Records are ordered in ascending collating sequence by the primary key. If the WITH DUPLICATES phrase is present, the primary key may contain duplicate values, if the indexed file system supports them. The Micro Focus indexed file system supports duplicate primary key values. If WITH DUPLICATES is used with a file system that does not support them, when the file is created via the OPEN statement a status of 0M is returned, indicating that the file was successfully created but that duplicate primary keys are not supported. When WITH DUPLICATES is used with Micro Focus and other file systems that support it, the rules that govern how REWRITE and DELETE operations are handled are determined by the file system. The rules for Micro Focus are as follows:
    1. If the last record locked via a READ statement is still locked and it matches the primary key value specified in a REWRITE or DELETE statement, that record is the record rewritten or deleted.
    2. Otherwise, the first record with the matching key value is rewritten or deleted.

    For information about how HP e3000 KSAM handles REWRITE and DELETE with duplicate primary keys, see HP COBOL Conversions in Transitioning to ACUCOBOL-GT.

    The WITH NO DUPLICATES phrase is commentary. By default, duplicate primary key values are not allowed.

  17. The ALTERNATE RECORD KEY clause specifies additional record keys for an indexed file. If the WITH DUPLICATES phrase is present, these key values may contain duplicated values. Otherwise, each key value must be unique for a given key.

    You may specify the word NO in front of the word DUPLICATES in a declaration of an alternate indexed file key. This is useful for ICOBOL compatibility mode where, by default, alternate keys allow duplicates.

  18. Up to 16 seg-names may be specified in Micro Focus to indicate that a primary or alternate key consists of non-contiguous data elements. The key-name or alt-name is then a user-defined word that can be used in READ and START.
  19. The OPTIONAL phrase, if specified, indicates that the file need not be present when the program is run. The exact effects of this phrase are detailed in the discussion of the OPEN Statement. Note that the -Fp compile option causes all files to be treated as if the OPTIONAL phrase is present.
  20. The LOCK MODE clause specifies how file and record locking should be handled for the file. Each mode has the following characteristics:
    AUTOMATIC Each time a record is read from a file open for I/O, that record is locked unless the WITH NO LOCK option is used on the READ statement. Files open for INPUT do not lock records
    MANUAL Records read from a file with manual locking are locked only if the WITH LOCK option is used on the READ statement. Like automatic mode, files open for INPUT do not lock records even if WITH LOCK is specified
    EXCLUSIVE Exclusive mode files are opened with a lock on the entire file. No locking options may be specified on an OPEN statement associated with an exclusive mode file. Instead, files opened for INPUT are treated as if they were opened with the ALLOWING READERS phrase, and files opened for OUTPUT, I-O, or EXTEND are treated as if they were opened with the ALLOWING NO OTHERS phrase. If the WITH MASS-UPDATE phrase is used, the MASS-UPDATE option is implied for each OPEN (except for OPEN INPUT). See the OPEN Statement for details on these options
  21. If the COLLATING SEQUENCE phrase is used, the alphabet-name is the name of an alphabet declared in Special-Names. This alphabet can be standard or can be a custom alphabet defined by the programmer to allow special handling. For example, upper-case and lower-case letters could be mapped together so that two keys that are alphabetically the same (but differ in case) would be treated as the same letter. European character sets can also be re-ordered in Special-Names (so that keys are sorted alphabetically).
  22. If the LOCK ON MULTIPLE RECORDS phrase is used, the program may lock more than one record in the file at once. If the MULTIPLE option is not used, each I-O statement automatically unlocks the currently locked record before executing. When the MULTIPLE option is used, record locks are released only when an UNLOCK or a CLOSE statement is executed for the file. The ROLLBACK clause is useful when you compile with -Fl, which enables single locking rules as the lock mode default. When the ROLLBACK clause is used with this phrase, multiple locking rules are enabled for the file, regardless of the compiler option used.
  23. If the LOCK phrase is omitted, LOCK MODE IS AUTOMATIC is implied, unless the -Fm compiler option is used, in which case LOCK MODE IS MANUAL is implied. In ICOBOL compatibility mode (-Ci), the default is LOCK MODE IS MANUAL WITH MULTIPLE RECORDS.
  24. The RECORD DELIMITER and RESERVE AREA clauses are treated as commentary by the compiler.
  25. If the ROLLBACK clause is specified, WITH LOCK ON MULTIPLE RECORDS will automatically be in effect. However, if you compile with the -Fl option, you must specify multiple locking rules for the files that need them.
  26. If the ROLLBACK clause is specified, the runtime will automatically effect a START TRANSACTION before opening the file, and a COMMIT after opening it. Thus, every OPEN of the file will automatically be done within a transaction; the COBOL code need not explicitly include the START TRANSACTION and COMMIT.
  27. It is possible that a RECORDING MODE clause may appear in the IBM DOS/VS COBOL -Cv compatibility mode and be ignored by the ACUCOBOL-GT compiler.
Parent topic: Input-Output Section