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 [device] [file-spec]
[ [ ORGANIZATION IS ] [BINARY] SEQUENTIAL ]
[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 ]
[ PADDING CHARACTER IS pad-char ] .
Format 2 - Relative Files
SELECT [OPTIONAL] file-name
ASSIGN TO [device] [file-spec]
[ ORGANIZATION IS ] RELATIVE
[ ACCESS MODE IS
{ SEQUENTIAL [ RELATIVE KEY IS rel-key ] } ]
{ RANDOM RELATIVE KEY IS rel-key }
{ 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 ] .
See the multiple-option format at the end of the formats.
Format 3 - Indexed Files
SELECT [OPTIONAL] file-name
ASSIGN TO [device] [file-spec]
[ WITH {COMPRESSION} ... ]
{ENCRYPTION }
[ COMPRESSION CONTROL VALUE IS factor ]
[ ORGANIZATION IS ] INDEXED
[ ACCESS MODE IS {SEQUENTIAL} ]
{RANDOM }
{DYNAMIC }
[ RECORD KEY IS key-name [= seg-name ...] ]
[ 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 ]
[ COLLATING SEQUENCE IS alphabet-name ] .
Format 4 - Sort Files
SELECT file-name ASSIGN TO [device] [file-spec] [ FILE STATUS IS status-variable ] .
WITH { LOCK ON [ MULTIPLE ] { RECORD } } [WITH ROLLBACK]
{ RECORDS }
{ ROLLBACK }
Syntax Rules
1. File-spec must be either a nonnumeric literal or the name of an alphanumeric Working-Storage data item. See section 6.1.3 of the User's Guide for information about creating Vision indexed files.
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. Status-variable must be the name of an alphanumeric Working-Storage or Linkage data item with a size of 2 characters.
4. Rel-key must name an unsigned integer data item. It must not be in the record description entry for the same file.
5. Factor must be a numeric literal from zero to 100, inclusive.
6. 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).
7. 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.
8. If seg-name is used to define a split RECORD KEY, then 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.
9. If seg-name is used to define a split ALTERNATE RECORD KEY, then 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.
10. Number must be an integer literal.
11. Alphabet-name is the name of an alphabet declared in the Special-Names paragraph.
12. 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.
13. 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.
14. Each file described in the Data Division must be specified exactly once in the FILE-CONTROL paragraph.
15. Each file described by a SELECT clause must have exactly one corresponding file description in the Data Division.
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. (See sction 6.4.7, I/O Status.)
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:
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. The ASSIGN clause specifies the association of the file to a storage device. The rules for interpreting the ASSIGN clause are described in the ACUCOBOL-GT User's Guide, section 2.8. If the file-spec phrase is missing, then file-name will be treated as an alphanumeric literal and substituted for it (exception: rule 7a 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.
7. 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, then the device phrase is ignored. If it is a sequential file, then the following applies depending on the device phrase used:
a) 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, then 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.
b) 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.
c) 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.
d) RANDOM, DISK, DISC, TAPE, CONSOLE - Indicates no additional processing. This is the same as if the device phrase were omitted.
e) MERGE, SORT, SORT-MERGE, SORT-WORK - Also indicates no additional processing. These device phrases may be associated with a sort file only.
8. 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 Vision 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 Chapter 6 of the User's Guide for specifics about the Vision file system.
9. The WITH ENCRYPTION phrase specifies that record encryption is desired on the file. Encryption is currently available with the Vision indexed file system only. The ENCRYPTION clause takes effect only when the file is initially created or re-created via the OPEN statement.
10. 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.
11. 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.
12. Records in an ORGANIZATION IS INDEXED file are uniquely identified by the values in the record's primary key. The primary key is identified by the RECORD KEY clause. Records are ordered in ascending collating sequence by the primary key.
13. The ALTERNATE RECORD KEY clause specifies additional record keys for an indexed file. If the WITH DUPLICATES phrase is present, then 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, all keys allow duplicates.
14. Up to 16 seg-names may be specified in Vision Version 4 to indicate that a primary or alternate key consists of non-contiguous data elements. In Vision Version 3, up to six seg-names may be specified, and in Version 2, only one seg-name may be specified. The key-name or alt-name is then a user-defined word that can be used in READ and START.
15. 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 (see Chapter 6).
16. 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, then the MASS-UPDATE option is implied for each OPEN (except for OPEN INPUT). See the OPEN statement for details on these options.
17. 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).
18. If the LOCK ON MULTIPLE RECORDS phrase is used, then the program may lock more than one record in the file at once. If the MULTIPLE option is not used, then each I-O statement automatically unlocks the currently locked record before executing. When the MULTIPLE option is used, then 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.
19. If the LOCK phrase is omitted, then LOCK MODE IS AUTOMATIC is implied. When you are using ICOBOL compatibility mode, however, the default is LOCK MODE IS MANUAL WITH MULTIPLE RECORDS.
20. The RECORD DELIMITER and RESERVE AREA clauses are treated as commentary by the compiler.
21. If the ROLLBACK clause is specified, then WITH LOCK ON MULTIPLE RECORDS will automatically be in effect. However, if you compile with the "-Fl" option, then you must specify multiple locking rules for the files that need them.
22. 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.
23. 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. See Appendix G for more details.