Environment Division for File Input and Output [ COBOL/HP-UX Language Reference for the Series 700 and 800 ] MPE/iX 5.0 Documentation
COBOL/HP-UX Language Reference for the Series 700 and 800
Environment Division for File Input and Output
For details of the Configuration Section see the chapter The Nucleus.
Input-Output Section
The FILE-CONTROL Paragraph.
Function
The FILE-CONTROL paragraph names each file and allows specification of
other file-related information.
General Format
Click here to view figure.
The FILE-CONTROL Entry.
Function
The FILE-CONTROL entry names a file and can specify other file-related
information.
________________________________________________________________________
|(XOPEN) |
|Although they are a part of the standard COBOL definition, the RECORD |
|DELIMITER and RESERVE phrases and ellipses in the ASSIGN clause are |
|explicitly excluded from the X/Open COBOL language definitions and |
|should not be used in X/Open COBOL source programs. |
________________________________________________________________________
General Formats
Format 1 (Record Sequential Files)
Click here to view figure.
Click here to view figure.
Format 3 (Relative Files)
Click here to view figure.
Format 4 (Indexed Files)
Click here to view figure.
Format 5 (Sort-Merge Files)
Click here to view figure.
Syntax Rules
All Formats (All Files)
1. The SELECT clause must be specified first in the file control
entry. The clauses which follow the SELECT clause can appear in
any order.
2. Each file described in the Data Division must be named once, and
only once, as file-name in the FILE-CONTROL paragraph. Each file
specified in the file control entry must have a file description
entry in the Data Division.
3. If the ACCESS MODE clause is not specified, the ACCESS MODE IS
SEQUENTIAL clause is implied.
________________________________________________________________________
|(MF) |
| |
| |
| |
|4. Data-name-1 can be declared in the Data Division as an |
| alpha-numeric or group data item long enough to hold the external|
| name of the file. If it is not explicitly declared within the |
| program, your COBOL system will declare it implicitly as an |
| alphanumeric data item long enough to hold the maximum |
| permissible size of program name. If data-name-1 occurs in the |
| FROM option, the data item must be explicitly declared in the |
| Data Division. |
| |
|5. The NOT OPTIONAL phrase has effect only when the file is opened |
| input-output. |
| |
|6. External-file-reference, data-name-1, or literal-1 specifies the |
| external name of the file. |
| |
| If the EXTERNAL or DYNAMIC option is used, literal-1 must not be |
| specified. |
| |
| If the DYNAMIC option is used, the word specified |
| for the external file name will be interpreted as |
| external-file-reference. |
| |
| If literal-1 is not specified, but neither the EXTERNAL nor the |
| DYNAMIC option is used, then either EXTERNAL or DYNAMIC is |
| assumed depending on the setting of the ASSIGN system directive |
| (see your COBOL System Reference). |
| |
________________________________________________________________________
7. Data-name-2 must be defined in the Data Division as a two-character,
alphanumeric data item or a two-character numeric data item with
USAGE DISPLAY (OSVS) (VSC2) and must not be defined in the File,
LOCAL-STORAGE (MF) or the Communication Sections of the Data
Division.
________________________________________________________________________
|(VSC2) |
| |
| |
| |
|8. Data-name-3 must be defined as a group item of 6 bytes in the |
| Working-Storage or Linkage Section of the Data Division. |
| |
________________________________________________________________________
________________________________________________________________________
|(OSVS) (VSC2) |
| |
| |
| |
|9. Data-name-4 must be defined in the Working-Storage Section as an |
| alphanumeric data item. |
| |
________________________________________________________________________
10. All data names can be qualified.
Format 1 (Record Sequential Files only)
________________________________________________________________________
|(ANS85) |
| |
| |
| |
|11. Literal-2 must be a one-character nonnumeric literal. |
| |
|12. Data-name-5 can be qualified. It must be defined in the Data |
| Division as a one-character data item of category alphanumeric. |
| It cannot be defined in the Communication, File or Report |
| Sections of the Data Division. |
| |
|13. Character-string must not be a reserved word, a user-name or a |
| literal. |
| |
________________________________________________________________________
Formats 1 and 2 (Record and Line Sequential Files)
14. When the ORGANIZATION clause is not specified, sequential
organization is assumed. (See Syntax Rule 19 below.)
________________________________________________________________________
|(MF) |
| |
| |
| |
|15. KEYBOARD means console input. |
| |
|16. DISPLAY means console output. |
| |
|17. PRINTER specifies the system's main printer. |
| |
|18. PRINTER-1 specifies the system's second printer. |
| |
|19. If both RECORD and LINE are omitted from the ORGANIZATION phrase,|
| one or the other of these options is assumed according to the |
| setting of the COBOL system directive SEQUENTIAL (see your COBOL |
| System Reference). |
| |
________________________________________________________________________
Format 3 (Relative Files)
20. If a relative file is to be referenced by a START statement, the
RELATIVE KEY phrase must be specified for that file.
21. Data-name-5 must not be defined in a record description entry
associated with that file-name.
22. The data item referenced by data-name-5 must be defined as an
unsigned integer.
Format 4 (Indexed Files)
________________________________________________________________________
|(MF) |
| |
| |
| |
|23. Split-key-name is a concatenation of one or more data items |
| within a record associated with that file-name. It can be |
| referenced only in START and READ statements. |
| |
________________________________________________________________________
24. The data items referenced by data-name-5 and data-name-8 and any
data-names referenced by split-key-name-1 and split-key-name-2 (MF)
must be defined as alphanumeric data items within a record
description entry associated with the file-name.
________________________________________________________________________
|(OSVS) (VSC2) (MF) |
|Any of these data items can be defined as any supported data category.|
|However, the key is still treated as an alphanumeric item for the |
|input and output statements against the file named in the SELECT |
|clause. |
________________________________________________________________________
25. Data-name-5 and data-name-8 and any data-names referenced by
split-key-name-1 and split-key-name-2 (MF) cannot describe an item
whose size is variable. (See "The OCCURS Clause" in the chapter
The Nucleus.)
26. Data-name-8 or split-key-name-2 (MF) cannot reference an item whose
leftmost character position corresponds to the leftmost character
position of an item referenced by data-name-5 or split-key-name-1.
(MF)
________________________________________________________________________
|(OSVS) (VSC2) |
| |
| |
| |
|27. If the PASSWORD clause is specified, it must immediately |
| follow its associated RECORD KEY or ALTERNATE RECORD KEY |
| clause. |
| |
________________________________________________________________________
Format 5 (Sort-Merge Files)
28. Each sort or merge file described in the Data Division must be named
once and once only as file-name in the FILE-CONTROL paragraph. Each
sort or merge file specified in the file control entry must have a
sort-merge file description entry in the Data Division.
29. Since file-name represents a sort or merge file, only the ASSIGN
clause is permitted to follow file-name in the FILE-CONTROL
paragraph.
General Rules
All Formats (All Files)
1. The ASSIGN clause specifies the association of the file referenced
by file-name-1 to a storage medium. (See your COBOL System
Reference.) The first assignment takes effect:
________________________________________________________________________
|(OSVS) (VSC2) (MF) |
|subsequent assignments within any one ASSIGN clause are documentary |
|only. |
________________________________________________________________________
2. The RESERVE clause allows the user to specify the required number
of input-output areas.
________________________________________________________________________
|(MF) |
|The RESERVE clause is documentary only, unless the COBOL System |
|Reference specific to your operating system indicates otherwise. |
________________________________________________________________________
3. The ORGANIZATION clause specifies the logical structure of a file.
The file organization is established at the time a file is created
and cannot subsequently be changed.
4. When the FILE STATUS clause is specified, a value will be moved by
the Run-Time System into the data item specified by data-name-2
after the execution of every statement that references that file
either explicitly or implicitly. This value indicates the status
of execution of the statement. (See the section I/O Status
earlier in this chapter.)
________________________________________________________________________
|(MF) |
|Data-name-3, if specified, is documentary only. |
________________________________________________________________________
________________________________________________________________________
|(MF) |
| |
| |
| |
|5. The PASSWORD clause is documentary only. |
| |
|6. The use of the reserved word DYNAMIC in an ASSIGN clause |
| indicates that the value of literal-1 or data-name-1 in that |
| ASSIGN clause is the specified file's name in the external |
| file-storage environment. |
| |
|7. The use of the reserved word EXTERNAL in an ASSIGN clause |
| indicates that external-file-reference identifies the specified |
| file to the external environment for possible further mapping to |
| an external file-storage environment name. (See your COBOL |
| System Reference for details on setting up external-file-name for|
| your particular operating environment.) |
| |
| If external-file-reference contains the character "-", then only |
| that part of the name following the last "-" is used to identify |
| the file to the external environment. |
| |
|8. The DISK option without external-file-reference, data-name-1 or |
| literal-1 and without the FROM option, specifies a disk file |
| whose name will be given in a VALUE OF FILE-ID clause in the file|
| description for the file. If that file description contains |
| no VALUE OF FILE-ID clause, the name of the disk file is |
| assumed to be the same as file-name-1 (known as the internal |
| file-name). |
| |
|9. If any of the keywords DISK, KEYBOARD, DISPLAY, PRINTER or |
| PRINTER-1 are followed by external-file- reference, data-name-1 |
| or literal-1, that keyword is ignored. |
| |
|10. The DISK option with the FROM option specifies a disk file whose |
| name on the disk is the value of data-name-1. However, if when |
| an OPEN statement is executed for that file, data-name-1 contains|
| all spaces, the name of the disk file is assumed to be the same |
| as file-name-1 (known as the internal-file-name). |
| |
________________________________________________________________________
11. The OPTIONAL phrase applies only to files opened in the INPUT, I/O
or EXTEND mode. Its specification is required for files that are
not necessarily present each time the object program is executed.
________________________________________________________________________
|(MF) |
| |
|Formats 1, 3 and 4 (Record Sequential, Relative and Indexed |
|files) |
| |
| |
| |
|12. The LOCK MODE clause is an optional clause in the file control |
| entry and is used to specify the locking technique used for the |
| file. |
| |
| If this clause is omitted, opening the file causes it to become |
| exclusive, with the exception of OPEN INPUT. |
| |
| When LOCK MODE IS EXCLUSIVE is specified, the run unit acquires a|
| lock on the whole file when it opens the file. |
| |
| When LOCK MODE IS AUTOMATIC or LOCK MODE IS MANUAL is specified, |
| the file that the run unit opens is shareable. Files opened |
| OUTPUT, and indexed and relative files opened EXTEND are, |
| however, always exclusive. |
| |
|13. The ROLLBACK clause requests transaction logging for a file under|
| those COBOL systems that support that feature. In other COBOL |
| systems, this clause is documentary only. See your COBOL System |
| Reference for details of how it is implemented in your |
| system. |
| |
| If the ROLLBACK clause is specified then WITH LOCK ON MULTIPLE |
| RECORDS will automatically be in effect. |
| |
|14. The WITH LOCK ON RECORD clause specifies single record locking |
| for the file. |
| |
| The WITH LOCK ON MULTIPLE RECORDS clause specifies multiple |
| record locking for the file. This clause must be present if |
| multiple record locking is required. |
| |
|15. If LOCK MODE IS AUTOMATIC WITH LOCK ON RECORD is specified for a |
| file, a record lock is acquired by the execution of the READ |
| statement and is released upon execution of a subsequent |
| I/O operation on this file, with the exception of a START |
| statement. |
| |
| If LOCK MODE IS AUTOMATIC WITH LOCK ON MULTIPLE RECORD is |
| specified for a file, a record lock is acquired by the execution |
| of the READ statement and is not released until a CLOSE, COMMIT, |
| ROLLBACK or UNLOCK statement is executed. |
| |
|16. If LOCK MODE IS MANUAL WITH LOCK ON RECORD is specified, a lock |
| is acquired by a READ statement only if it includes the WITH LOCK|
| phrase, and is released upon execution of a subsequent |
| I/O operation on this file, with the exception of a START |
| statement. |
| |
| If LOCK MODE IS MANUAL WITH LOCK ON MULTIPLE RECORDS is |
| specified, a record lock is acquired by the READ WITH KEPT LOCK |
| statement and is not released until a CLOSE, COMMIT, ROLLBACK or |
| UNLOCK statement is executed. |
| |
________________________________________________________________________
________________________________________________________________________
|(MF) |
| |
| |
| |
|17. When the lock mode is MANUAL or AUTOMATIC, single record locking |
| is assumed unless the WITH LOCK ON MULTIPLE RECORDS phrase is |
| included. |
| |
|18. If a file is defined as EXTERNAL and the operating system |
| file-name is assigned by means of a file name, for example, by |
| use of either the DYNAMIC directive or keyword, using data-name-1|
| in the SELECT/ ASSIGN statement, or using Format 2 of the VALUE |
| OF phrase of an FD, then the following rules should be |
| followed: |
| |
| |
| a. identifier with the same name should be used to contain |
| the physical file name in all programs which reference the|
| file. |
| |
| b. definition of the identifier which contains the |
| physical file name should also contain the EXTERNAL |
| attribute. |
| |
| No violation of these rules will be detected at compile time, |
| but, if any program in the run-unit violates these rules, the |
| results at run-time will be undefined. |
| |
| For further details of the effects of record locking, see your |
| COBOL System Reference. |
| |
________________________________________________________________________
Format 1 (Record Sequential Files)
19. The MULTIPLE REEL or MULTIPLE UNIT phrase must be specified if it is
possible or intended that the file can be closed by use of the CLOSE
REEL or CLOSE UNIT statement.
20. Records in the file are accessed in the sequence specified by
predecessor-successor record relationships which are established by
the execution of WRITE statements when the file is created or
extended.
________________________________________________________________________
|(MF) |
| |
| |
| |
|21. Using the LINE ADVANCING FILE phrase causes a file suitable for a|
| printer to be produced. This file will have an initial |
| carriage-return character, and each record is written with AFTER |
| ADVANCING 1 LINE as the default advancing phrase. See |
| your COBOL System Reference for further details of the |
| format. |
| |
________________________________________________________________________
________________________________________________________________________
|(ANS85) |
| |
| |
| |
|22. The PADDING CHARACTER clause is documentary only. (MF) If the |
| associated file connector is an external file connector, all |
| PADDING CHARACTER clauses in a run unit which are associated with|
| that file connector must have the same specification. If |
| data-name-5 is external, it must reference an external data |
| item. |
| |
|23. The RECORD DELIMITER clause (MF) is documentary only. |
| |
________________________________________________________________________
Format 2 (Line Sequential Files)
________________________________________________________________________
|(MF) |
| |
| |
| |
|24. When LINE SEQUENTIAL ORGANIZATION is specified either implicitly |
| or explicitly, the file is treated as consisting of fixed length |
| records, each containing one line of data. The records are |
| stored with trailing spaces removed. The definition of a line of|
| data varies among different operating systems. Some terminate |
| line "records" with one or both of the Carriage Return and Line |
| Feed characters, and some pad out as fixed length records. Your |
| COBOL system, therefore, always produces files which are |
| compatible in this respect with the editor software in any |
| operating system. |
| |
|25. The LOCK MODE IS clause is documentary only. |
| |
________________________________________________________________________
Format 3 (Relative Files)
26. When access mode is sequential, records in the file are accessed in
order of ascending relative record numbers of existing records in
the file.
27. When access mode is random, the value of the RELATIVE KEY data item
indicates the record to be accessed.
28. All records stored in a relative file are uniquely identified by
relative record numbers, which also specify the record's logical
ordinal position in the file. The first logical record has a
relative record number of 1, and subsequent logical records have
relative record numbers of 2, 3, 4, ... .
29. The data item specified by data-name-5 is used to communicate a
relative record number between the user and the operating system.
Format 4 (Indexed Files)
30. When access mode is sequential, records in the file are accessed in
order of ascending record key values within a given key of
reference.
31. When access mode is random, the value of the record key data item
indicates the record to be accessed.
32. The RECORD KEY clause specifies the record key that is the prime
record key for the file. The values of the prime record key must be
unique among records of the file. This prime record key provides an
access path to records in an indexed file.
33. The ALTERNATE RECORD KEY clause specifies a record key that is an
alternative record key for the file. This alternate record key
provides an alternative access path to records in an indexed file.
34. The data description of data-name-5 or split-key-name-1 (MF) and
data-name-8 or split-key-name-2, (MF) as well as of relative
locations within a record, must be the same as that used when the
file was created. The number of alternate keys for the file must
also be the same as that used when the file was created. This
checking is configurable (see your COBOL System Reference for
details).
35. The DUPLICATES phrase specifies that the value of the associated
record key can be duplicated within any of the records in the file.
If the DUPLICATES phrase is not specified, the value of the
associated record key must not be duplicated among any of the
records in the file.
36. For duplicate values the correct duplicate entry must be located
using sequential reads from the first duplicate entry.
37. The file-control entry names a sort or merge file and specifies the
association of the file to a storage medium.
Format 5 (Sort-Merge Files)
38. When the SORT STATUS clause is specified, a value is placed into the
two-character data item specified by data-name-2 after the execution
of each sort operation. This value indicates the status at
completion of the operation.
The resulting status of the sort operation is indicated by valid
combinations of status keys 1 and 2. For explanations of status
keys 1 and 2 and definitions of status, see the section I/O Status
earlier in this chapter.
The following combinations of status keys are possible. Status key
1=0 and status key 2=0 indicates successful completion. Status key
1=3 and status key 2=0 indicates a permanent error. If status key
1=9, status key 2 contains an operating system error message number.
The FILE STATUS clause can be used instead of a SORT STATUS clause,
but is treated as a synonym for it, when specified for a SORT or
merge file.
The I/O-CONTROL Paragraph.
Function
The I/O-CONTROL paragraph specifies the points at which rerun is to be
established, the memory area which is to be shared by different files,
and for files with sequential organization the location of files on a
multiple file reel.
________________________________________________________________________
|(ANS85) |
|The RERUN and MULTIPLE FILE TAPE clauses of the I/O-CONTROL paragraph |
|are classed as obsolete elements in the ANSI'85 standard and are |
|scheduled to be deleted from the next full revision of the ANSI |
|Standard. |
________________________________________________________________________
________________________________________________________________________
|(MF) |
|All dialects within this COBOL implementation fully support this |
|syntax. Refer to your COBOL System Reference for details on |
|using the FLAGSTD directive to detect all occurrences of this |
|syntax. |
________________________________________________________________________
________________________________________________________________________
|(XOPEN) |
|Although they are a part of the standard COBOL definition, the RERUN |
|and MULTPIPLE FILE TAPE clauses are explicitly excluded from the |
|X/Open COBOL language definitions and should not be used in X/Open |
|COBOL source programs. |
________________________________________________________________________
General Formats
Format 1 (Sequential Files)
Click here to view figure.
Format 2 (Relative and Indexed Files)
Click here to view figure.
Format 3 (Sort-Merge Files)
Click here to view figure.
Syntax Rules
All Formats (All Files)
1. The I/O-CONTROL paragraph is optional.
2. File-name-1 must be a sequentially organized file.
3. When either the integer-1 RECORDS clause or the integer-2
CLOCK-UNITS clause is specified, character-string must be given in
the RERUN clause.
4. The two forms of the SAME clause (SAME AREA, SAME RECORD AREA) are
considered separately in the following:
More than one SAME clause can be included in a program. However:
a. A file-name must not appear in more than one SAME AREA
clause.
b. A file-name must not appear in more than one SAME RECORD
AREA clause.
c. If one or more file-names of a SAME AREA clause appear in a
SAME RECORD AREA clause, all of the file-names in that SAME
AREA clause must appear in the SAME RECORD AREA clause.
However, additional file-names not appearing in that SAME
AREA clause can also appear in that SAME RECORD AREA
clause. The rule that only one of the files mentioned in a
SAME AREA clause can be open at any one time takes
precedence over the rule that all files mentioned in a SAME
RECORD AREA clause can be open at any one time.
5. The files referenced in the SAME AREA or SAME RECORD AREA clause
need not all have the same organization or access.
________________________________________________________________________
|(MF) |
| |
| |
| |
|6. Character-string must not be a reserved word, a literal or a |
| user-name. |
| |
________________________________________________________________________
Format 1 (Record Sequential Files)
7. The END OF REEL/UNIT clause can only be used if file-name-2 is a
sequentially organized file.
8. More than one RERUN clause can be specified for a given file-name-2,
subject to the following restrictions:
a. When multiple integer-1 RECORD clauses are specified, no two
of them can specify the same file-name-2.
b. When multiple END OF REEL or END OF UNIT clauses are
specified, no two of them can specify the same file-name-2.
Format 2 (Relative and Indexed Files)
9. When multiple integer-1 RECORDS clauses are specified, no two of
them can specify the same file-name-2.
10. Only one RERUN clause containing the CLOCK-UNITS clause can be
specified.
Format 3 (Sort-Merge Files)
11. In the SAME AREA clause, SORT and SORT-MERGE are equivalent.
12. If the SAME SORT AREA or SAME SORT-MERGE AREA clause is used, at
least one of the file-names must represent a sort or merge file.
Files that do not represent sort or merge files can also be named in
the clause.
13. The three formats of the SAME clause (SAME RECORD AREA, SAME SORT
AREA, SAME SORT-MERGE AREA) are considered separately in the
following:
More than one SAME clause can be included in a program, however:
a. A file-name must not appear in more than one SAME RECORD AREA
clause.
b. A file-name that represents a sort or merge file must not
appear in more than one SAME SORT AREA or SAME SORT-MERGE
AREA clause.
c. If a file-name that does not represent a sort or merge file
appears in a SAME AREA clause and one or more SAME SORT AREA
or SAME SORT-MERGE AREA clauses, all of the files named in
that SAME AREA clause must be named in that SAME SORT AREA or
SAME SORT-MERGE AREA clause(s).
14. The files referenced in the SAME SORT AREA, SAME SORT-MERGE AREA, or
SAME RECORD AREA clause need not all have the same organization or
access.
General Rules
All Formats (All Files)
________________________________________________________________________
|(MF) |
| |
| |
| |
|1. The RERUN clause is documentary only. |
| |
________________________________________________________________________
2. The SAME AREA clause specifies that two or more files that do not
represent sort or merge files are to use the same memory area during
processing. The area being shared includes all storage area
assigned to the files specified. It is not, therefore, valid to
have more than one of the files open at the same time. (See Syntax
Rule 4c.)
3. The SAME RECORD AREA clause specifies that two or more files are to
use the same memory area for processing the current logical record.
All of the files can be open at the same time. A logical record in
the SAME RECORD AREA is considered as a logical record of each
opened output file whose file-name appears in this SAME RECORD AREA
clause and of the most recently read input file whose file-name
appears in this SAME RECORD AREA clause. This is equivalent to an
implicit redefinition of the area; that is, records are aligned on
the leftmost character position.
________________________________________________________________________
| |
| 4. The APPLY clause is documentary only. (MF) |
| |
________________________________________________________________________
Format 1 (Record Sequential Files)
________________________________________________________________________
| |
| 5. The MULTIPLE FILE clause is documentary only. (MF) |
| |
________________________________________________________________________
Format 3 (Sort-Merge Files)
6. The SAME RECORD AREA clause specifies that two or more files are to
use the same memory area for processing of the current logical
record. All of the files can be open at the same time. A logical
record in the SAME RECORD AREA is considered as a logical record of
each opened output file whose file-name appears in this SAME RECORD
AREA clause and of the most recently read input file whose file-name
appears in this SAME RECORD AREA clause. This is equivalent to
implicit redefinition of the area; that is, records are aligned on
the leftmost character position.
7. If the SAME SORT AREA or SAME SORT-MERGE AREA clause is used, at
least one of the file-names must represent a sort or merge file.
Files that do not represent sort or merge files can also be named in
the clause. This clause specifies that storage is shared as
follows:
a. The SAME SORT AREA or SAME SORT-MERGE AREA clause specifies a
memory area which will be made available for use in sorting
or merging each sort or merge file named. Thus any memory
area allocated for the sorting or merging of a sort or merge
file is available for reuse in sorting or merging any of the
other sort or merge files.
b. In addition, storage areas assigned to files that do not
represent sort or merge files can be allocated as needed for
sorting or merging the sort or merge files named in the SAME
SORT AREA or SAME SORT-MERGE AREA clause.
c. Files other than sort or merge files do not share the same
storage area with each other. If the user wishes these files
to share the same storage area with each other, he must also
include in the program a SAME AREA or SAME RECORD AREA clause
naming these files.
d. During the execution of a SORT or MERGE statement that refers
to a sort or merge file named in this clause, any
non-sort-merge files named in this clause must not be open.
MPE/iX 5.0 Documentation
HP 3000 Manuals