HP 3000 Manuals HP 3000 Manuals
General Formats (Continued)
File I/O Concepts
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 FILESTATUS 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.
For MF only: 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.
"4" For ANS85 only: 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.
"4" For ANS85 only: (all files) Indicates that the length of the
record being processed does not conform to the fixed file
attributes for that file .
"5" For ANS85 only: (all files) Indicates that the referenced
optional file was not present at the time the OPEN statement was
executed .
"7" For ANS85 only: (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.
"4" For ANS85 only: (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 section 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.
" 4 " For ANS85 only: (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.
" 5 " For ANS85 only: (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" For ANS85 only: (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 " For ANS85 only: (all files) Indicates that an OPEN statement has
been attempted on a file previously closed with lock.
" 9" For ANS85 only: (record sequential, relative and indexed files)
Indicates that a conflict has been detected between the fixed
file attributes and the attributes specified for that file in the
program.
For ANS85 only: Logic Error Condition with Unsuccessful Completion.
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 MF only: 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 your 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 section
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 sections 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 the section
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 only), "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 Table 4-10.
![[]](../../pic3k/M015064/FFN1433c50.gif)
Table 4-10 : Valid Combinations of Status Keys 1 and 2
For MF and XOPEN only: Sharing Files on Multi-user Systems
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.
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 a record lock
for the file. Files opened for OUTPUT always have an exclusive file
lock.
Line Sequential Files.
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. A run unit can acquire a record lock in two ways:
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.
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. Record
locks can be acquired in two ways: manually or automatically.
Manual Record Locking.
The run unit acquires a lock only if it accesses a record with a READ
WITH LOCK or 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.
Tables 4-15, 4-16 and 4-17 show the default type of locking which is used
when files are opened in a particular open mode. The default locking can
be modified 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.)
For MF only: X/Open restricts those X/Open conforming source programs
that use locking to either single record locks with automatic locking, or
multiple record locks with manual locking.
Table 4-15 : Default Locking For Record Sequential Files
-------------------------------------------------------------------------
| | | | |
| OPEN Mode | No Di- | AUTOLOCK | Override in SELECT |
| | rective | Directive | 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 4-16 : Default Locking For Line Sequential Files
-------------------------------------------------------------------------
| | | | |
| OPEN Mode | No Di- | AUTOLOCK | Override in SELECT |
| | rective | Directive | Statement |
| | | | |
-------------------------------------------------------------------------
| | | | |
| INPUT | No lock | No lock | No |
| | | | |
-------------------------------------------------------------------------
| | | | |
| I/O | Exclusive| No lock | No |
| | | | |
-------------------------------------------------------------------------
| | | | |
| OUTPUT | Exclusive| Exclusive | No |
| | | | |
-------------------------------------------------------------------------
| | | | |
| EXTEND | Exclusive| No lock | No |
| | | | |
-------------------------------------------------------------------------
Table 4-17 : Default Locking For Relative And Indexed Files
-------------------------------------------------------------------------
| | | | |
| OPEN Mode | No Di- | AUTOLOCK | Override in SELECT |
| | rective | Directive | 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 |
| | | | |
-------------------------------------------------------------------------
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 Tables 4-15, 4-16 and 4-17)
or by including a LOCK MODE clause in the file-control entry (see
section The File-Control Entry later in this chapter).