HP 3000 Manuals HP 3000 Manuals
Chapter 5 File Input and Output
Introduction to File Input and Output
COBOL allows for four distinct kinds of input-output (I/O):
1. Record Sequential I/O
2. Line Sequential I/O (MF)
3. Relative I/O
4. Indexed I/O
Record Sequential Input/Output
Record sequential I/O allows the programmer to access records of a file
in an established sequence. The sequence is established as a result of
writing the records to the file.
Organization of Line and (MF) Record Sequential Files.
Sequential files are organized such that each record in the file except
the first has a unique predecessor record, and each record except the
last has a unique successor record. These predecessor-successor
relationships are established by the order of WRITE statements when the
file is created. Once established, the predecessor-successor
relationships do not change except in the case where records are added to
the end of the file.
________________________________________________________________________
|Line Sequential Input/Output |
| |
|(MF) |
| |
|Line sequential I/O allows the programmer to access records of a text |
|file in an established sequence. Line sequential files are |
|identical in format to those files produced by your operating |
|system editor. The records are stored with trailing spaces |
|removed. |
| |
|If the words sequential file or sequential organization are used in |
|this chapter without specifying LINE or RECORD, then the sentence |
|applies to both forms. The default behavior for sequential files is |
|sensitive to the SEQUENTIAL directive. See your COBOL System |
|Reference for details. |
________________________________________________________________________
Access Mode.
The only access available for sequential files is sequential access mode;
the sequence in which records are accessed is the order in which the
records were originally written.
Relative Input-Output
Relative I/O allows the programmer to access records within a mass
storage file in either a random or sequential manner. Each record in a
relative file is identified by an integer value greater than zero which
specifies the record's ordinal position in the file.
Organization of Relative Files.
Relative file organization is permitted only on disk devices. A relative
file consists of records which are identified by relative record numbers.
The file can be thought of as being composed of a serial string of areas,
each capable of holding a logical record. Each of these areas has a
relative record number. Records are stored and retrieved via this
number. For example, ten denotes the tenth record area.
Access Mode.
In sequential access mode, records are accessed in the ascending order of
the relative record numbers of those records which currently exist within
the file.
In random access mode, the programmer controls the sequence in which
records are accessed. The desired record is accessed by placing its
relative record number in a relative key data item.
In dynamic access mode, the programmer can change at will between
sequential access and random access, using the appropriate forms of
input-output statements.
Indexed Input-Output
Indexed I/O allows the programmer to access records within a mass storage
file in either a random or sequential manner. Each record in an indexed
file is identified by the value of one or more keys within that record.
Organization of Indexed Files.
An indexed file is a mass storage file in which data records can be
accessed by the value of a key. A record description can include one or
more key data items, each of which is associated with an index. Each
index provides a logical path to the data records, according to the
contents of a data item within each record which is the record key for
that index.
The data item named in the RECORD KEY clause of the file control entry
for a file is the prime record key for that file. For purposes of
inserting, updating and deleting records in a file, each record is
identified solely by the value of its prime record key. This value
should, therefore, be unique and must not be changed when updating the
record. See your COBOL System Reference for further details.
The data item named in the ALTERNATE RECORD KEY clause of the file
control entry for a file is an alternative record key for that file. The
value of an alternative record key can be non-unique if the DUPLICATES
phrase is specified. These keys provide alternative access paths for
retrieval of records from the file.
________________________________________________________________________
|(MF) |
|Micro Focus provides an extension which allows the key field to |
|be a split key. A split key is a key comprising two or more |
|data items, which may or may not be contiguous, in the record |
|description. |
________________________________________________________________________
Access Mode.
In sequential access mode, records are accessed in the ascending order of
the record key values. Records within a set of records which have
duplicate record key values are retrieved in the order in which the
records were written into the set.
In random access mode, the programmer controls the sequence in which
records are accessed. The desired record is accessed by placing the
value of its record key in the record key data item.
In dynamic access mode, the programmer can change at will between
sequential access and random access, using appropriate forms of
input-output statements.
File Position Indicator
The file position indicator identifies the next record to be accessed
within a given file during certain input-output sequences. The setting
of the file position indicator is affected only by CLOSE, OPEN, START and
READ statements. The file position indicator has no effect on files
opened in the output or extend mode.
I/O Status
If the FILE STATUS clause is specified in a file control entry, a value
is placed into the specified two-character data item during the execution
of an OPEN, CLOSE, READ, WRITE, REWRITE, DELETE, UNLOCK or START
statement before any applicable USE procedure is executed, to indicate to
the COBOL program the status of that input-output operation.
The file status keys described in the following pages are for those files
which conform fully to the ANSI standard and which use none of the
extensions available with this COBOL system.
________________________________________________________________________
|(MF) |
|Use of extensions, for example, specifying a file as LINE SEQUENTIAL, |
|affects the status keys returned. Additional information is provided |
|under the relevant verbs. |
________________________________________________________________________
Status Key 1.
The leftmost character position of the FILE STATUS data item is known as
status key 1 and is set to indicate one of the following conditions upon
completion of the input-output operation on a file of any organization.
"0" - Successful completion
"1" - At end
"2" - Invalid key
"3" - Permanent error
"4" - Logic error (ANS85)
"9" - Run-Time System error message
The meaning of the above conditions is as follows:
"0" Successful completion. The input-output statement was successfully
executed.
"1" At end. The sequential READ statement was unsuccessfully executed
either because of an attempt to read a record when no next logical
record exists in the file or because the first READ statement was
executed for a file described with the OPTIONAL clause when that
file was not available to the program at the time its associated
OPEN statement was executed.
"2" Invalid key. The input-output statement on a non-sequential file
was unsuccessfully executed because of one of the following:
Sequence error
Duplicate key
No record found
Boundary violation
"3" Permanent error. The input-output statement was unsuccessfully
executed because of a boundary violation for a sequential file or
because of an input-output error, such as a data check parity error
or transmission error.
________________________________________________________________________
|(ANS85) |
| |
| |
| |
|"4" Logic error. The input-output statement was unsuccessfully |
| executed, either because an improper sequence of input-output |
| operations was performed on the file, or because a limit defined |
| by the user was violated. |
| |
________________________________________________________________________
"9" Run-Time System error message. The input-output statement was
unsuccessfully executed because of a condition that is specified by
the Run-Time System error message number. This value is used only
to indicate a condition not indicated by other defined values of
status key 1, or by specified combinations of the values of status
key 1 and status key 2.
Status Key 2.
The rightmost character position of the FILE STATUS data item is known as
status key 2 and is used to further describe the results of the
input-output operation.
The combination of status key 1 and status key 2 defines the result of
the input-output operation as detailed below:
Successful Completion
If status key 1 contains "0" to indicate the successful completion of the
input-output operation, status key 2 can contain one of the following
values:
"0" (all files) No further information is available
"2" (indexed files only) Indicates one of two possibilities:
* For a READ statement, the key value for the current key of
reference is equal to the value of that same key in the next
record within the current key of reference.
* For a WRITE or REWRITE statement, the record just written
created a duplicate key value for at least one alternate
record key for which duplicates are allowed.
________________________________________________________________________
|(ANS85) |
| |
| |
| |
|"4" (all files) Indicates that the length of the record being |
| processed does not conform to the fixed file attributes for that |
| file. |
| |
|"5" (all files) Indicates that the referenced optional file was not |
| present at the time the OPEN statement was executed. |
| |
|"7" (record sequential files only) Indicates that for a CLOSE |
| statement with the NO REWIND, REEL/UNIT or FOR REWIND phrase, or |
| an OPEN statement with the NO REWIND phrase, the referenced file |
| is a non-reel/unit medium. |
| |
________________________________________________________________________
AT END Condition with Unsuccessful Completion
If status key 1 contains "1" to indicate the AT END condition, status key
2 can contain one of the following values:
"0" (all files) Indicates that there is no next logical record. This
can be caused by two conditions:
* The end of the file has been reached.
* A sequential READ statement has been attempted for the first
time on an optional input file that is not present.
________________________________________________________________________
|(ANS85) |
| |
| |
| |
|"4" (relative files only) Indicates that the number of significant |
| digits in the relative record number is larger than the size of |
| the relative key data item described for that file. |
| |
________________________________________________________________________
INVALID KEY Condition with Unsuccessful Completion
If status key 1 contains "2" to indicate INVALID KEY condition, status
key 2 indicates the cause of the condition by one of the values:
"1" (sequentially accessed indexed files) Indicates a sequence error.
The ascending sequence requirements of successive record key values
have been violated (see "The WRITE Statement" later in this
chapter), or the prime record key value has been changed by the
COBOL program between the successful execution of a READ statement
and the execution of the next REWRITE statement for that file.
"2" (relative and indexed files only) Indicates a duplicate key value.
An attempt has been made either to write a record that would create
a duplicate prime record key or to write or rewrite a record that
would create a duplicate alternate record key when the DUPLICATES
phrase is not specified for that alternate record key.
"3" (relative and indexed files only) Indicates no record found. An
attempt has been made to access a record, identified by a key, and
that record does not exist in the file, or a START or READ statement
has been attempted on an optional input file that is not present.
________________________________________________________________________
|(ANS85) |
| |
| |
| |
|"4" (relative and indexed files only) Indicates a boundary violation |
| arising from one of the following conditions: |
| |
| |
| * An attempt has been made to write beyond the externally |
| defined boundaries of a file. |
| |
| * A sequential WRITE statement has been attempted for a |
| relative file, but the number of significant digits in |
| the relative record number is larger than the size |
| of the relative key data item described for the |
| file. |
| |
________________________________________________________________________
Permanent Error Condition with Unsuccessful Completion
If status key 1 contains "3" to indicate a permanent error condition,
status key 2 can contain one of the following values to indicate the
cause of that error:
"0" (all files) Indicates that no further information is available
concerning the cause of the error.
"4" (sequential files only) Indicates a boundary violation. An attempt
has been made to write beyond the externally defined boundaries of a
file.
________________________________________________________________________
|(ANS85) |
| |
| |
| |
|"5" (all files) Indicates that an OPEN statement with the INPUT, I/O,|
| or EXTEND phrase has been attempted on a non-optional file that |
| is not present. |
| |
|"7" (all files) Indicates that an OPEN statement has been attempted |
| on a file which will not support the open mode specified in the |
| OPEN statement. The possible violations are: |
| |
| |
| * The EXTEND or OUTPUT phrase has been specified but the |
| file will not support write operations. |
| |
| * The I/O phrase has been specified but the file will not |
| support the input and output operations that are |
| permitted for a relative file when opened in the I/O |
| mode. |
| |
| * The INPUT phrase has been specified but the file will not |
| support read operations. |
| |
|"8" (all files) Indicates that an OPEN statement has been attempted |
| on a file previously closed with lock. |
| |
|"9" (all files) Indicates that a conflict has been detected between |
| the fixed file attributes and the attributes specified for that |
| file in the program. |
| |
________________________________________________________________________
________________________________________________________________________
|Logic Error Condition with Unsuccessful Completion |
| |
|(ANS85) |
| |
|If status key 1 contains "4" to indicate a logic error condition, |
|status key 2 can contain one of the following values to indicate the |
|cause of that error: |
| |
| |
| |
|"1" (all files) Indicates that an OPEN statement has been attempted |
| for a file already in open mode. |
| |
|"2" (all files) Indicates that a CLOSE statement has been attempted |
| for a file not in open mode. |
| |
|"3" (all files, sequential access mode only) Indicates that the last |
| input-output statement executed for the associated file, prior to|
| the execution of a DELETE or REWRITE statement, was not a |
| successfully executed READ statement. |
| |
|"4" (record sequential files only) Indicates that a boundary |
| violation exists. A possible violation is that an attempt |
| has been made to WRITE or REWRITE a record that is larger |
| than the largest, or smaller than the smallest, record |
| allowed by the RECORD IS VARYING clause of the associated |
| file. |
| |
|"5" (all files ) An attempt has been made to REWRITE a record to a |
| file, and the record is not the same size as the record being |
| replaced. |
| |
| For line sequential files this refers to the physical size of the|
| record, that is after space removal, tab compression and null |
| insertion. In this case, the physical size of the new record is |
| allowed to be smaller than that of the record being replaced. |
| (MF) |
| |
|"6" (all files) Indicates that a sequential READ statement has been |
| attempted on a file open in input or I/O mode, but no valid next |
| record has been established. This can be caused by the following|
| conditions: |
| |
| |
| * The preceding START statement was unsuccessful. |
| |
| * The preceding READ statement was unsuccessful but did not |
| cause an at end condition. |
| |
| * The preceding READ statement caused an at end condition. |
| |
|"7" (all files) Indicates that the execution of a READ or START |
| statement has been attempted on a file not open in input or I/O |
| mode. |
| |
|"8" (all files) Indicates that the execution of a WRITE statement |
| has been attempted on a file not open in I/O, output or |
| extend mode, or on a file open I/O in sequential access |
| mode. |
| |
|"9" (all files) Indicates that the execution of a DELETE or REWRITE |
| statement has been attempted on a file not open in I/O |
| mode. |
| |
________________________________________________________________________
Run-Time System Error Message
If status key 1 contains "9" to indicate a run-time system error message,
status key 2 contains the run-time system error message number in binary.
These are described in full in the Error Messages.
The AT END Condition.
The AT END condition can occur as a result of the execution of a READ
statement. For details of the causes of the condition, see "The READ
Statement" later in this chapter.
The INVALID KEY Condition.
The INVALID KEY condition can occur as a result of the execution of a
START, READ, WRITE, REWRITE or DELETE statement. For details of the
causes of the condition, see "The START Statement" , "The READ
Statement" , "The WRITE Statement" , "The REWRITE Statement" ,
and "The DELETE Statement" later in this chapter.
If the INVALID KEY condition exists after the execution of the
input-output operation specified in an input-output statement, the
following actions occur in the order shown:
1. A value is placed in the FILE STATUS data item, if specified for
this file, to indicate an INVALID KEY condition. (See "I/O
Status" earlier in this chapter.)
2. If the INVALID KEY phrase is specified in the statement causing
the condition, control is passed to the INVALID KEY imperative
statement. Any USE procedure specified for this file is not
executed.
3. If the INVALID KEY phrase is not specified, but a USE procedure is
specified, either explicitly or implicitly, for this file, that
procedure is executed.
When the INVALID KEY condition occurs, execution of the input-output
statement which recognized the condition is unsuccessful, and the file is
not affected.
Note that INVALID KEY does not trap errors when status key 1 is set to
"9". Such errors must be trapped either by explicitly testing the status
key or by using declaratives instead of the INVALID KEY clause.
Valid Combinations of Status Keys 1 And 2.
In the following table, "S" indicates a Record Sequential file, "L"
indicates a Line Sequential file, (MF) "R" indicates a Relative file and
"I" indicates an Indexed file.
A particular combination of status key 1 and status key 2 is valid for a
given file organization if the letter for that organization is found at
the corresponding intersection in the table.
Table 5-1. Valid Combinations of Status Keys 1 and 2
![[]](../../pic3k/M013027/FFN7563c50.gif)
________________________________________________________________________
|Sharing Files on Multi-user Systems |
| |
|(MF) |
| |
|The Run-Time System (RTS) supports this COBOL system's multi-user |
|facilities which allow files to be shared between users in a |
|multi-user environment, and allow programs accessing those files to |
|prevent access to records or entire files while data is being |
|updated. |
| |
|In single-user environments the multi-user syntax has no effect at |
|run-time, but programs can be developed for use in both single- and |
|multi-user environments. |
| |
|Files are either active or inactive. An active file is open to one or|
|more run-units. An inactive file is one that is not open to any |
|run-unit. |
| |
|Active files can be open in one of two modes: exclusive or |
|shareable. |
| |
|When record locking is in effect, all file updates require that a |
|record lock be acquired for the record to be updated. |
| |
|Exclusive |
| |
|A file which is in exclusive mode is open to one run-unit only; any |
|other run-unit which attempts to access it will receive a "File |
|locked" error and be denied access. Exclusive mode implies that a |
|file lock is held by the one run-unit which is able to access the |
|file; the file lock is released by that run-unit closing the |
|file. |
| |
|Shareable |
| |
|A file which is in shareable mode is available to any number of |
|run-units, each of which can protect data while using the file by |
|locking one or more records at a time in the file. This prevents |
|other run-units from acquiring a lock on the individual records that |
|are locked, but does not prevent access to the file otherwise. |
|The organization of the file affects the way the file can be |
|shared. |
| |
|Record Sequential Files |
| |
|Record sequential files opened for INPUT can be shared between |
|run-units but records cannot be locked in the file. Files opened for |
|I/O or EXTEND can also be made shareable and each run-unit can |
|maintain one or more record locks for the file. Files opened for |
|OUTPUT always have an exclusive file lock. |
________________________________________________________________________
________________________________________________________________________
|Line Sequential Files |
| |
|(MF) |
| |
|Line sequential files that are opened INPUT or EXTEND can be made |
|shareable but records cannot be locked in the file. Files that are |
|opened OUTPUT always have an exclusive file lock. |
| |
|Relative and Indexed Files |
| |
|Files that are opened in INPUT mode are shareable, but records |
|cannot be locked in the file. Files that are opened I/O can |
|be shareable but files that are opened OUTPUT or EXTEND are |
|exclusive. |
| |
|Record Locking |
| |
|Each run-unit that is sharing access to a file can be locking either a|
|single record or multiple records in that file. A run-unit cannot |
|select single record locking and multiple record locking for the same |
|file. |
| |
|Single Record Lock |
| |
|A run-unit that has specified single record locking for a file (either|
|explicitly or implicitly) can hold only one record lock in that file |
|at any one time. There are two ways in which a run-unit can acquire a|
|record lock: manually or automatically. |
| |
|Manual Record Locking |
| |
|The run-unit acquires a lock only if it accesses a record with a READ |
|WITH LOCK statement. |
| |
|Automatic Record Locking |
| |
|The run-unit acquires a lock whenever it reads a record in the file, |
|unless you specify the READ WITH NO LOCK statement. |
| |
|Releasing Single Record Locks |
| |
|The lock is released by the same run-unit: |
| |
| |
| * Accessing any record in the file with any file operation |
| (except START for relative and indexed files) |
| |
| * Executing an UNLOCK statement on that file |
| |
| * Executing a COMMIT statement |
| |
| * Executing a ROLLBACK statement |
| |
| * Closing the file |
________________________________________________________________________
________________________________________________________________________
|Multiple Record Locks |
| |
|(MF) |
| |
|Locking of multiple records in a file is available only when |
|the organization of that file is relative, indexed or record |
|sequential. |
| |
|A run-unit that has specified multiple record locking for a file can |
|hold a number of record locks in one file simultaneously. This |
|prevents other run-units from updating or acquiring a lock on those |
|locked records, but does not deny them access to any records that are |
|not locked. There are two ways in which record locks can be acquired:|
|manually or automatically. |
| |
|Manual Record Locking |
| |
|The run-unit acquires a lock only if it accesses a record with a READ |
|WITH KEPT LOCK statement. |
| |
|Automatic Record Locking |
| |
|The run-unit acquires a lock whenever it reads a record in the file, |
|unless you explicitly specify that it should not. If the WRITELOCK |
|directive has been specified at the time the program was submitted to |
|your COBOL system, then a lock is acquired if the run-unit accesses |
|the file with a WRITE or REWRITE statement (see your COBOL System |
|Reference). |
| |
|Releasing Multiple Record Locks |
| |
|The locks are released by the same run-unit: |
| |
| |
| * Executing a DELETE statement referencing a record for which a |
| lock is held. In this case, only the lock on that record is |
| released |
| |
| * Executing an UNLOCK statement for that file |
| |
| * Executing a COMMIT statement |
| |
| * Executing a ROLLBACK statement |
| |
| * Closing the file |
________________________________________________________________________
________________________________________________________________________
|(MF) |
|Table 5-2 , Table 5-3 and Table 5-4 show the default type |
|of locking which is used when files are opened in a particular open |
|mode. The default locking can be midified if the AUTOLOCK directive |
|was specified at the time the program was submitted to your |
|COBOL system (see your COBOL System Reference). The tables also |
|indicate whether the default type of locking can be overridden for |
|individual files. This is done by inserting a suitable clause in |
|the SELECT statement for the file. (See section The Select |
|Statement later in this chapter for details of the required |
|syntax.) |
________________________________________________________________________
Table 5-2. Default Locking For Record Sequential Files
-------------------------------------------------------------
| | | | |
| OPEN Mode | No Directive | AUTOLOCK | Override in |
| | | Directive | SELECT |
| | | | Statement |
| | | | |
-------------------------------------------------------------
| | | | |
| INPUT | No lock | No lock | Yes, but |
| | | | only to |
| | | | Exclusive |
| | | | |
-------------------------------------------------------------
| | | | |
| I\O | Exclusive | Lock on | Yes |
| | | single | |
| | | record | |
| | | | |
-------------------------------------------------------------
| | | | |
| OUTPUT | Exclusive | Exclusive | No |
| | | | |
-------------------------------------------------------------
| | | | |
| EXTEND | Exclusive | No lock | Yes, the |
| | | | file can be |
| | | | made |
| | | | shareable |
| | | | but no |
| | | | records are |
| | | | locked |
| | | | |
-------------------------------------------------------------
Table 5-3. Default Locking For Line Sequential Files (MF)
-------------------------------------------------------------
| | | | |
| OPEN Mode | No Directive | AUTOLOCK | Override in |
| | | Directive | SELECT |
| | | | Statement |
| | | | |
-------------------------------------------------------------
| | | | |
| INPUT | No lock | No lock | No |
| | | | |
-------------------------------------------------------------
| | | | |
| I\O | Exclusive | No lock | No |
| | | | |
-------------------------------------------------------------
| | | | |
| OUTPUT | Exclusive | Exclusive | No |
| | | | |
-------------------------------------------------------------
| | | | |
| EXTEND | Exclusive | No lock | No |
| | | | |
-------------------------------------------------------------
Table 5-4. Default Locking For Relative And Indexed Files (MF)
-------------------------------------------------------------
| | | | |
| OPEN Mode | No Directive | AUTOLOCK | Override in |
| | | Directive | SELECT |
| | | | Statement |
| | | | |
-------------------------------------------------------------
| | | | |
| INPUT | No lock | No lock | Yes, but |
| | | | only to |
| | | | Exclusive |
| | | | |
-------------------------------------------------------------
| | | | |
| I\O | Exclusive | Automatic | Yes |
| | | lock on | |
| | | single | |
| | | record | |
| | | | |
-------------------------------------------------------------
| | | | |
| OUTPUT | Exclusive | Exclusive | No |
| | | | |
-------------------------------------------------------------
| | | | |
| EXTEND | Exclusive | Exclusive | No |
| | | | |
-------------------------------------------------------------
________________________________________________________________________
|(MF) |
| |
|Notes: |
| |
| |
| 1. A file opened for OUTPUT causes the file to become exclusive, |
| regardless of the specified lock mode. |
| |
| 2. The programmer can select the type of locking for individual |
| files by accepting the default locking (see Table 5-2 , |
| Table 5-3 and Table 5-4 ) or by including a LOCK MODE |
| clause in the file-control entry (see section "The FILE-CONTROL|
| Entry" later in this chapter). |
________________________________________________________________________