Procedure Division for File Input and Output (cont.) [ 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
Procedure Division for File Input and Output (cont.)
The MERGE Statement
Function
The MERGE statement combines two or more identically sequenced files on a
set of specified keys, and during the process makes records available, in
merge order, to an output procedure or to an output file.
General Format
Click here to view figure.
Syntax Rules
1. File-name-1 must be described in a sort-merge file description
entry in the Data Division.
2. Procedure-name-1 represents the name of an output procedure.
3. Procedure-name-1 and procedure-name-2 must be section-names.
________________________________________________________________________
|This restriction is removed. (ANS85) (OSVS) |
________________________________________________________________________
________________________________________________________________________
|(ANS85) |
| |
| |
| |
|4. If the file referenced by file-name-1 contains variable length |
| records, the size of the records contained in the files |
| referenced by file-name-2 and file-name-3 must not be less than |
| the smallest record, nor greater than the largest record |
| described for file-name-1. If the file referenced by file-name-1|
| contains fixed length records, the size of the records contained |
| in the files referenced by file-name-2 and file-name-3 |
| must not be greater than the largest record described for |
| file-name-1. |
| |
________________________________________________________________________
5. File-name-2, file-name-3, and file-name-4 must be described in a
file description entry, not in a sort-merge file description entry,
in the Data Division.
6. The words THRU and THROUGH are equivalent.
7. Data-name-1, is a KEY data-name and is subject to the following
rules:
a. The data items identified by KEY data-names must be described
in records associated with file-name-1.
b. KEY data-names can be qualified.
c. The data items identified by KEY data-names must not be
variable length items.
d. If file-name-1 has more than one record description, then the
data items identified by KEY data-names need be described in
only one of the record descriptions. The same character
position referenced by a key data-name in one record
description entry are taken as the key in all records of the
file.
e. None of the data items identified by KEY data-names can be
described by an entry which either contains an OCCURS clause
or is subordinate to an entry which contains an OCCURS
clause.
________________________________________________________________________
|(OSVS) (VSC2) (MF) |
| |
| |
| |
|f. KEY data items can be floating-point items. |
| |
|g. If the KEY is an external floating-point item, the key is treated|
| as alphanumeric. The sequence in whichthe records are merged |
| depends on the collating sequence used. |
| |
|h. If the KEY is an internal floating-point item, the sequence of |
| key values will be in numeric order. |
| |
________________________________________________________________________
8. No more than one file-name from a multiple file reel can appear in
the MERGE statement.
9. File-names must not be repeated within the MERGE statement.
10. MERGE statements can appear anywhere except in the declaratives
portion of the Procedure Division.
________________________________________________________________________
|(ANS85) |
| |
| |
| |
|11. If file-name-4 references an indexed file, the first |
| specification of data-name-1 must be associated with an ASCENDING|
| phrase, and the data item referenced by that data-name-1 must |
| occupy the same character positions in its record as the |
| data item associated with the prime record key for that |
| file. |
| |
________________________________________________________________________
________________________________________________________________________
|(ANS85) |
| |
| |
| |
|12. If the GIVING phrase is specified and the file referenced by |
| file-name-4 contains variable length records, the size |
| of the records not contained in the file referenced by |
| file-name-1 must be less than the smallest record nor greater |
| than the record described for file-name-4. If the file by |
| file-name-4 contains fixed length records, the size of |
| the records contained in the file referenced by -name-1 |
| must not be greater than the largest record described for |
| file-name-4. |
| |
________________________________________________________________________
General Rules
1. The MERGE statement merges all records contained on the files
referenced by file-name-2 and file-name-3.
2. If the file referenced by file-name-1 contains only fixed length
records, any record in the file referenced by file-name-2 or
file-name-3 containing fewer character positions than that fixed
length is space filled on the right, beginning with the first
character position after the last character in the record, when
that record is released to the file referenced by file-name-1.
3. The data-names following the word KEY are listed from left to
right in the MERGE statement in order of decreasing significance
without regard to how they are divided into KEY phrases. The
leftmost data-name is the major key, the next data-name is the
next more significant key, etc.
a. When the ASCENDING phrase is specified, the merged sequence
will be from the lowest value of the contents of the data
items identified by the key data-names to the highest
value, according to the rules for comparison of operands in
a relation condition.
b. When the DESCENDING phrase is specified, the merged
sequence will be from the highest value of the contents of
the data items identified by the key data-names to the
lowest value, according to the rules for comparison of
operands in a relation condition.
4. When, according to the rules for comparison of operands in
relation condition, the contents of all the key data items of one
data record are equal to the corresponding key data items of one
or more other data records, the order of return of these records:
a. Follows the order of the associated input files as
specified in the MERGE statement.
b. Is such that all records associated with one input file are
returned prior to the return of records from another input
file.
5. The collating sequence that applies to the comparison of the
nonnumeric key data items specified is determined at the beginning
of the execution of the MERGE statement in the following order of
precedence:
a. First, the collating sequence established by the COLLATING
SEQUENCE phrase, if specified, in that MERGE statement.
b. Second, the collating sequence established as the program
collating sequence.
6. The results of the merge operation are undefined unless the
records in the files referenced by file-name-2 and file-name-3 are
ordered as described in the ASCENDING or DESCENDING KEY phrases
associated with the MERGE statement.
7. All the records in the files referenced by file-name-2 and
file-name-3 are transferred to the file referenced by file-name-1.
At the start of execution of the MERGE statement, the files
referenced by file-name-2 and file-name-3 must not be in the open
mode. For each of the files referenced by file-name-2 and
file-name-3 the execution of the MERGE statement causes the
following actions to be taken:
a. The processing of the file is initiated. The initiation is
performed as if an OPEN statement with the INPUT phrase had
been executed. If an output procedure is specified, this
initiation is performed before control passes to the output
procedure.
b. The logical records are obtained and released to the merge
operation. Each record is obtained as if a READ statement
with the NEXT and the AT END phrases had been executed.
If the file referenced by file-name-1 is described with
variable length records, the size of any record written to
file-name-1 is the size of that record when it was read
from file-name-2 or file-name-3, regardless of the content
of the data item referenced in the DEPENDING ON phrase of
either a RECORD IS VARYING clause or an OCCURS clause
specified in the sort-merge file description entry for
file-name-1.
For a relative file, the content of the relative data key
item is undefined after the execution of the MERGE
statement.
c. The processing of the file is terminated. The termination
is performed as if a CLOSE statement without optional
phrases had been executed. If an output procedure is
specified, this termination is not performed until after
control passes the last statement in the output procedure.
These implicit functions are performed such that any
associated USE AFTER EXCEPTION/ERROR procedures are
executed.
The value of the data item referenced by the DEPENDING ON
phrase of a RECORD IS VARYING clause specified in the file
description entry for file-name-2 or file-name-3 is
undefined upon completion of the MERGE statement.
8. The output procedure can consist of any procedure needed to
select, modify or copy the records that are made available one at
a time by the RETURN statement in merged order from the file
referenced by file-name-1. The range includes all statements that
are executed as the result of a transfer of control by CALL, EXIT,
GO TO, and PERFORM statements in the range of the output
procedure, as well as all statements in declarative procedures
that are executed as a result of the execution of statements in
the range of the output procedure. The range of the output
procedure must not cause the execution of any MERGE, RELEASE, or
SORT statement. (See the section "Explicit and Implicit
Specifications" in the chapter COBOL Concepts.)
9. If an output procedure is specified, control passes to it during
execution of the MERGE statement. The compiler inserts a return
mechanism at the end of the last statement in the output
procedure. When control passes the last statement in the output
procedure, the return statement provides for termination of the
merge, and then passes control to the next executable statement
after the MERGE statement. Before entering the output procedure,
the merge procedure reaches a point at which it can select the
next record in merged order when requested. The RETURN statements
in the output procedure are the requests for the next record.
10. During the execution of the output procedure, no statement can be
executed manipulating the file referenced by, or accessing the
record area associated with, file-name-2, file-name-3, or
file-name-4.
11. If the GIVING phrase is specified, all the merged records are
written on the file referenced by file-name-4 as the implied
output procedure for the MERGE statement. At the start of
execution of the MERGE statement, the file referenced by
file-name-4 must not be in the open mode. For each of the files
referenced by file-name-4, the execution of the MERGE statement
causes the following actions to be taken:
a. The processing of the file is initiated. The initiation is
performed as if an OPEN statement with the OUTPUT phrase
had been executed.
b. The merged logical records are returned and written onto
the file. Each record is written as if a WRITE statement
without any optional phrases had been executed.
If the file referenced by file-name-4 is described with
variable length records, the size of any record written to
file-name-4 is the size of that record when it was read
from file-name-1, regardless of the content of the data
item referenced in the DEPENDING ON phrase of either a
RECORD IS VARYING clause or an OCCURS clause specified in
the file description entry for file-name-4.
For a relative file, the relative key data item for the
first record returned contains the value "1"; for the
second record returned, the value "2", and so on. The
content of the relative key data item is undefined after
execution of the MERGE statement.
c. The processing of the file is terminated. The termination
is performed as if a CLOSE statement without optional
phrases had been executed.
These implicit functions are performed such that any associated
USE AFTER EXCEPTION/ERROR procedures are executed; however, the
execution of such a USE procedure must not cause the execution of
any statement manipulating the file referenced by, or accessing
the record area associated with, file-name-4. On the first
attempt to write beyond the externally defined boundaries of the
file, any USE AFTER EXCEPTION/ERROR procedure specified for the
file is executed; if control is returned from the USE procedure or
if no such USE procedure is specified, the processing of the file
is terminated as in paragraph 11c above.
The value of the data item referenced by the DEPENDING ON phrase
of a RECORD IS VARYING clause specified in the file description
entry for file-name-1 is undefined upon completion of the MERGE
statement for which the GIVING phrase is specified.
12. If the file referenced by file-name-4 contains only fixed length
records, any record in the file referenced by file-name-1
containing fewer character positions than that fixed length is
space filled on the right, beginning with the first character
position after the last character in the record, when that record
is returned to the file referenced by file-name-4.
13. Segmentation, as defined in the chapter Segmentation, can be
applied to programs containing the MERGE statement. However, the
following restrictions apply:
a. If the MERGE statement appears in a section that is not in
an independent segment, then any output procedure
referenced by that merge statement must appear:
1) Totally within non-independent segments, or
2) Wholly contained in a single independent segment.
b. If a MERGE statement appears in an independent segment,
then any output procedure referenced by that MERGE
statement must be contained:
1) Totally within non-independent segments, or
2) Wholly within the same independent segment as that
MERGE statement.
________________________________________________________________________
|(OSVS) (VSC2) (MF) |
| |
| |
| |
|14. The SORT-RETURN special register is available to MERGE programs. |
| It contains a return code of 0 (successful) or 16 (unsuccessful) |
| at the completion of the merge operation. You can set the |
| special register to 16 in the output procedure to terminate a |
| merge operation before all records are processed. The operation |
| is terminated on the next RETURN statement. |
| |
________________________________________________________________________
The OPEN Statement
Function
The OPEN statement initiates the processing of files. It also performs
checking and/or writing of labels and other input-output operations.
________________________________________________________________________
|(ANS85) |
|The REVERSED phrase of the OPEN statement is classed as an obsolete |
|element in the ANSI'85 standard and is 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 it is a part of the standard COBOL definition, the REVERSED |
|phrase of the OPEN statement is 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.
Format 2 (Line Sequential, Relative And Indexed Files)
Click here to view figure.
Syntax Rules
All Formats (All Files)
1. The files referenced in the OPEN statement need not all have the
same organization or access.
Format 1 (Record Sequential Files)
________________________________________________________________________
| |
| 2. NO REWIND is documentary only. (MF) |
| |
________________________________________________________________________
3. The I/O phrase can be used only for disk files.
4. The EXTEND phrase must be used only for files for which the LINAGE
clause has not been specified.
5. The EXTEND phrase must not be specified with multiple file reels.
Format 2 (Line Sequential, (MF) Relative and Indexed Files)
________________________________________________________________________
|(ANS85) |
| |
| |
| |
|6. The EXTEND phrase can be used for files in sequential access |
| mode. |
| |
________________________________________________________________________
General Rules
All Formats (All Files)
1. Prior to the successful execution of an OPEN statement for a given
file, no statement (except for a SORT or MERGE statement with the
USING or GIVING phrases) can be executed that references that file,
either explicitly or implicitly.
2. The successful execution of an OPEN statement determines the
availability of the file and results in the file being in an open
mode.
3. The successful execution of an OPEN statement makes the associated
record area available to the program.
4. An OPEN statement must be successfully executed prior to the
execution of any of the permissible input-output statements. In
Table 5-6 , "X" at an intersection indicates that the specified
statement, used in the access mode given for that row, can be used
with the file organization and open mode given at the top of the
column.
________________________________________________________________________
|(MF) |
| |
| |
| |
|5. If the WITH LOCK phrase is specified, the OPEN statement |
| acquires a lock on the whole file. (This is equivalent to |
| specifying LOCK MODE IS EXCLUSIVE in the SELECT statement for |
| the file. See the section The SELECT Statement in this |
| chapter.) |
| |
________________________________________________________________________
________________________________________________________________________
|(ANS85) |
| |
| |
| |
|6. If, during the execution of an OPEN statement, a file attribute |
| conflict occurs, the execution of the OPEN statement is |
| unsuccessful. Your COBOL system defines which of the fixed file |
| attributes are validated during the execution of the OPEN |
| statement. See your file handling documentation for more |
| details. The validation of fixed file attributes can vary |
| depending on the organization and/or storage medium of the |
| file. |
| |
________________________________________________________________________
Table 5-6. Permissible Combinations of Statements and OPEN Modes
------------------------------------------------------------------------------------------------
| | |
| File Access Mode | OPEN Mode |
| | |
------------------------------------------------------------------------------------------------
| | | | | | |
| | Statement | Input | Output | Input- | Extend |
| | | | | Output | |
| | | | | | |
------------------------------------------------------------------------------------------------
| | | | | | |
| Sequential | READ WRITE | X | X | X | X |
| | REWRITE | | | | |
| | | | | X | |
| | | | | | |
------------------------------------------------------------------------------------------------
| | | | | | |
| Random | READ WRITE | X | X | X | |
| (Non-Sequential | REWRITE | | | X | |
| Files) | START DELETE | | | X | |
| | | | | | |
| | | | | X | |
| | | | | | |
------------------------------------------------------------------------------------------------
| | | | | | |
| Dynamic | READ WRITE | X | X | X | |
| (Non-Sequential | REWRITE | | | X | |
| Files) | START DELETE | | | X | |
| | | X | | X | |
| | | | | X | |
| | | | | | |
------------------------------------------------------------------------------------------------
Note: The START and DELETE statements can not be used with record or
line (MF) sequential files.
________________________________________________________________________
|(ANS85) |
| |
| |
| |
|7. A file can be opened with the INPUT, OUTPUT, EXTEND and I/O |
| phrases in the same program. Following the initial execution of |
| an OPEN statement for a file, each subsequent OPEN statement |
| execution for that same file must be preceded by the execution of|
| a CLOSE statement for that file. |
| |
________________________________________________________________________
8. Execution of the OPEN statement does not obtain or release the first
data record.
9. The ASSIGNed name in the SELECT statement for a file is processed as
follows:
a. When the INPUT phrase is specified, execution of the OPEN
statement causes the ASSIGNed name to be written in
accordance with the operating system conventions for opening
files for input.
b. When the OUTPUT phrase is specified, execution of the OPEN
statement causes the ASSIGNed name to be written in
accordance with the operating system conventions for opening
files for output.
10. The file description entry for file-name-1, file-name-2,
file-name-3, and file-name-4 must be equivalent to that used when
this file was created.
11. For files being opened with the INPUT or I/O phrase, the OPEN
statement sets the file position indicator to the first record
currently existing within the file for indexed and sequential files,
and record position one for relative files. If no records exist in
the file, the file position indicator is set such that the next
executed READ statement for an indexed or sequential file will
result in an AT END condition. If the file does not exist, OPEN
INPUT will cause an error status.
12. When the I/O phrase is specified and the LABEL RECORDS clause
indicates label records are present, the execution of the OPEN
statement includes the following steps:
a. The labels are checked in accordance with the operating
system-specified conventions for input-output label checking.
b. The new labels are written in accordance with the operating
system-specified conventions for input-output label writing.
13. Upon successful execution of an OPEN statement with the OUTPUT
phrase specified, a file is created. At that time the associated
file contains no data records. If a file of the same name exists it
will be deleted. If write-protected an error will occur.
________________________________________________________________________
|(ANS85) |
| |
| |
| |
|14. When the EXTEND phrase is specified, the OPEN statement positions|
| the file immediately after the last logical record for that file.|
| The last logical record for a sequential file is the last record |
| written in the file. In a relative file it is the currently |
| existing record with the highest relative record number, and in |
| an indexed file it is the currently existing record with the |
| highest prime key value. |
| |
________________________________________________________________________
15. Execution of the OPEN statement causes the value of the FILE STATUS
data item to be updated (see the section "I/O Status" earlier in
this chapter).
________________________________________________________________________
|(MF) |
| |
| |
| |
|16. When LOCK MODE IS EXCLUSIVE is specified in the SELECT/ |
| ASSIGN statement of a file, successful execution of an OPEN |
| statement of that file locks the file exclusively to that run |
| unit. |
| |
|17. When LOCK MODE IS AUTOMATIC or LOCK MODE IS MANUAL is specified |
| in the SELECT/ASSIGN statement of a file, the file that |
| is referred to is shareable. More than one run unit can |
| successfully open such a file. |
| |
|18. A file opened for OUTPUT, and relative and indexed files opened |
| EXTEND, are implicitly defined as files with an exclusive lock, |
| that is, they are not shareable. |
| |
|19. Only shareable files opened for I/O can acquire record |
| locks. |
| |
________________________________________________________________________
20. If execution of the OPEN statement is unsuccessful, the physical
file is not affected and the following actions take place in this
order:
a. A value is placed in the I/O status associated with file-name
to indicate the condition that caused the OPEN statement to
be unsuccessful.
b. Any applicable USE AFTER EXCEPTION procedure is executed.
(See the section "The USE Statement" in this chapter.)
21. The I/O phrase permits the opening of a file for both input and
output operations. If the file does not exist, the following rules
apply:
a. If the OPTIONAL phrase is specified, the file is created
b. If the NOT OPTIONAL phrase is specified, an error occurs
c. If neither phrase is specified, and the directive
OPTIONAL-FILE was specified when the program was compiled,
the file is created.
d. If neither phrase is specified, and the directive
NOOPTIONAL-FILE was specified when the program was compiled,
an error occurs.
22. If an input file is designated with the OPTIONAL phrase in its
SELECT clause, the object program causes an interrogation for the
presence or absence of this file. If the file is not present, the
first READ statement for this file causes the AT END condition to
occur.
23. When the EXTEND phrase is specified, the OPEN statement positions
the file immediately following the last logical record of that file.
Subsequent WRITE statements referencing the file will add records to
the file as though the file had been opened with the OUTPUT phrase.
If the file does not exist it will be created.
________________________________________________________________________
|(ANS85) |
| |
| |
| |
|24. When the EXTEND phrase is specified and the LABEL RECORDS clause |
| in this file's FD indicates label records are present, the |
| execution of the OPEN statement includes the following |
| steps: |
| |
| |
| a. The beginning file labels are processed only in the case |
| of a single reel/unit file. |
| |
| b. The beginning reel/unit labels on the last existing |
| reel/unit are processed as though the file was being |
| opened with the INPUT phrase. |
| |
| c. The existing ending file labels are processed as though |
| the file is being opened with the INPUT phrase. These |
| labels are then deleted. |
| |
| d. Processing then proceeds as though the file had been |
| opened with the OUTPUT phrase. |
| |
________________________________________________________________________
Format 1 (Record Sequential Files)
25. If the storage medium for the file permits rewinding, the following
rules apply:
a. Execution of the OPEN statement causes the file to be
positioned at its beginning.
b. When the REVERSED phrase is specified, the file is positioned
at its end by execution of the OPEN statement.
26. When the REVERSED phrase is specified, the subsequent READ
statements for the file make the data available in reversed order;
that is, starting with the last record.
Format 2 (Line Sequential Files)
________________________________________________________________________
|(MF) |
| |
| |
| |
|27. I/O mode is not allowed for line sequential files unless the |
| REWRITE-LS system directive is set (see your COBOL System |
| Reference). |
| |
________________________________________________________________________
Formats 1 and 2 (Record , Line (MF) Sequential, Relative and Indexed
Files)
28. The I/O phrase permits the opening of a file for both input and
output operations, except files with ORGANIZATION LINE SEQUENTIAL.
(MF) If the file does not exist, it will be created and used as an
empty file for input unless NOT OPTIONAL was specified in the SELECT
statement. An attempt to READ from the newly created file will
cause an error.
The READ Statement
Function
For sequential access, the READ statement makes available the next or
previous (MF) logical record from a file. For random access, the READ
statement makes available a specified record from a mass storage file.
General Formats
Format 1 (Record Sequential Files)
Click here to view figure.
Click here to view figure.
Format 3 (Relative And Indexed Files)
Click here to view figure.
Format 4 (Relative Files)
Click here to view figure.
Format 5 (Indexed Files)
Click here to view figure.
Syntax Rules
All Formats (All Files)
1. The INTO phrase must not be used when the input file contains
logical records of various sizes as indicated by their record
descriptions. This restriction has been removed. (ANS85) The
storage area associated with identifier and the storage area which
is the record area associated with file-name must not be the same
storage area.
________________________________________________________________________
|(OSVS) (VSC2) (MF) |
| |
| |
| |
|2. Identifier can be a floating-point data item. |
| |
________________________________________________________________________
3. The INVALID KEY phrase or the AT END phrase must be specified if no
applicable USE procedure is specified for file-name.
________________________________________________________________________
|This rule is not enforced. (OSVS) (VSC2) (MF) |
________________________________________________________________________
Formats 1, 3, 4 and 5 (Record Sequential, Relative and Indexed Files)
________________________________________________________________________
|(MF) |
| |
| |
| |
|4. The WITH LOCK phrase can be included only when single records are|
| being locked manually in a shareable file. |
| |
________________________________________________________________________
________________________________________________________________________
|(MF) |
| |
| |
| |
|5. The WITH NO LOCK phrase is only allowed when records are being |
| locked manually or automatically in a shareable file. |
| |
________________________________________________________________________
Format 3 (Relative and Indexed Files)
6. The NEXT or PREVIOUS phrases must be specified for files in dynamic
access mode when records are to be retrieved sequentially.
Formats 3, 4 and 5 (Relative And Indexed Files)
________________________________________________________________________
|(MF) |
| |
| |
| |
|7. The WITH KEPT LOCK phrase can be included only when multiple |
| records are being locked manually in a shareable file. |
| |
________________________________________________________________________
Formats 4 and 5 (Relative And Indexed Files)
8. Format 4 or 5 is used for files in random access mode or for files
in dynamic access mode when records are to be retrieved randomly.
Format 5 (Indexed Files)
9. Data-name must be the name of a data item specified as a record key
associated with file-name.
10. Data-name can be qualified.
________________________________________________________________________
|(MF) |
| |
| |
| |
|11. Split-key-name is a concatenation of one or more data items |
| specified as a record key associated with file-name. |
| |
________________________________________________________________________
General Rules
All Formats (All Files)
1. The associated file must be open in the INPUT or I/O mode at the
time the statement is executed. (See the section "The OPEN
Statement" earlier in this chapter.)
2. The execution of the READ statement causes the value of the FILE
STATUS data item, if any, associated with file-name to be updated.
(See the section "I/O Status" earlier in this chapter.)
3. When the logical records of a file are described by more than one
record description, these records automatically share the same
storage area; this is equivalent to an implicit redefinition of the
area. The contents of any data items which lie beyond the range of
the current data record are undefined at the completion of the
execution of the READ statement.
4. If the INTO phrase is specified, the record being read is moved from
the record area to the area specified by identifier according to the
rules specified for the MOVE statement without the CORRESPONDING
phrase. The implied MOVE does not occur if execution of the READ
statement was unsuccessful. Any subscripting or indexing associated
with identifier is evaluated after the record has been read and
immediately before it is moved to the data item.
5. When the INTO phrase is used, the record being read is available in
both the input record area and the data area associated with
identifier.
6. If the file position indicator indicates that no next logical record
exists, or that an optional input file is not present, the following
occurs in the order specified:
a. A value, derived from the setting of the file position
indicator, is placed into the I/O status associated with
file-name-1 to indicate the at end condition. (See the
section I/O Status in this chapter.)
b. If the AT END phrase is specified in the statement
causing the condition, control is transferred to AT END
imperative-statement-1. Any USE AFTER EXCEPTION procedure
associated with the file connector referenced by file-name-1
is not executed. Execution then continues according to the
rules for each statement specifed in imperative-statement-1.
If a procedure branching or conditional statement that causes
explicit transfer of control is executed, control is
transferred in accordance with the rules of that
statement; otherwise, upon completion of the execution of
imperative-statement-1, control is transferred to the end of
the READ statement and the NOT AT END phrase, if specified,
is ignored.
c. If the AT END phrase is not specified, a USE AFTER STANDARD
EXCEPTION procedure must be associated with this file-name-1,
and that procedure is executed. Return from that procedure
is to the next executable statement following the end of the
READ statement.
________________________________________________________________________
|(ANS85) |
|When the AT END condition occurs, the execution of the READ statement |
|is unsuccessful. |
________________________________________________________________________
7. Following the unsuccessful execution of any READ statement, the
contents of the associated record area are undefined and the file
position indicator is set to indicate that no next record has been
established.
Format 1 (Record Sequential Files)
8. The record to be made available by the READ statement is determined
as follows:
________________________________________________________________________
|(ANS85) |
| |
| |
| a. If the file position indicator was positioned by the execution |
| of the OPEN statement, the record pointed to by the file |
| position indicator is made available. |
| |
| b. If the file position indicator was positioned by the execution |
| of a previous READ statement, the file position indicator |
| is updated to point to the next existing record in the |
| file. |
________________________________________________________________________
________________________________________________________________________
|(MF) |
|However if the previous statement was a READ, and if that READ |
|returned a locked record status, the file position indicator is left |
|unchanged. The record pointed to by the file position indicator is |
|made available. |
________________________________________________________________________
9. If the end of a reel or unit is recognized during the execution of a
READ statement, and end-of-file has not been reached, the following
procedures are executed:
a. The standard ending reel/unit label procedure.
b. A reel/unit swap.
c. The standard beginning reel/unit label procedure.
d. The first data record of the new reel/unit is made available.
10. If a file described with the OPTIONAL clause is not present at the
time the file is opened, then at the time of execution of the first
READ statement for the file, the AT END condition occurs and
execution of the READ statement is unsuccessful. The standard end
of file procedures are not performed. (See sections "The
FILE-CONTROL Paragraph" , "The OPEN Statement" , and "The USE
Statement" in this chapter.) Execution of the program then
proceeds as in General Rule 13.
________________________________________________________________________
|(MF) |
| |
| |
| |
|11. For files opened for INPUT, the READ, READ WITH LOCK or |
| READ WITH KEPT LOCK statements do not acquire a record |
| lock. |
| |
|12. Two or more run units can share a sequential output file by |
| opening it EXTEND with AUTOMATIC or MANUAL record locking. |
| Records that are appended to the file are in unspecified |
| order. |
| |
|13. For files opened for I/O: |
| |
| |
| a. With LOCK MODE AUTOMATIC, unless the WITH NO LOCK |
| phrase is specified each record is locked as it is |
| read. |
| |
| b. With LOCK MODE MANUAL, a simple READ statement does |
| not acquire a lock on the record - the READ WITH |
| LOCK statement must be used to acquire a record |
| lock. The WITH NO LOCK phrase, if specified, is |
| documentary. |
| |
| c. The use of multiple or single record locking determines |
| when the record lock is released. (See section "The |
| FILE-CONTROL Paragraph" in this chapter.) |
| |
________________________________________________________________________
14. If an end-of-file status occurs on a READ statement in a file opened
for I/O or INPUT by one run unit and opened EXTEND by another run
unit, the run unit that attempted the READ must close the file.
This run unit has no access to the appended records because the
status remains end-of-file.
Formats 1, 2 and 3 (Sequential, Relative and Indexed Files)
15. If an AT END condition does not occur during the execution of a READ
statement, the AT END phrase, if specified, is ignored and the
following actions occur:
a. The file position indicator is set and the I/O status
associated with file-name-1 is updated.
b. If an exception condition which is not an at end condition
exists, control is transferred according to the rules of the
USE statement following the execution of any USE AFTER
EXCEPTION procedure applicable to file-name-1. (See the
section The USE Statement in this chapter.)
c. If no exception condition exists, the record is made
available in the record area and any implicit move resulting
from the presence of an INTO phrase is executed. Control is
transferred to the end of the READ statement or to
imperative-statement-2, if specified. In the latter case,
execution continues according to the rules for each statement
specified in imperative-statement-2. If a control branching
or conditional statement which causes explicit transfer of
control is executed, control is transferred in accordance
with the rules for that statement; otherwise, upon completion
of the execution of imperative-statement-2, control is
transferred to the end of the READ statement.
16. If when a READ statement with the NEXT option is executed, no next
logical record exists in the file, the AT END condition occurs, and
the execution of the READ statement is considered unsuccessful. See
the section "I/O Status" earlier in this chapter.
17. For sequential files or (ANS85) files in sequential access mode, the
NEXT phrase is optional and has no effect on the execution of the
READ statement.
Format 3 (Relative and Indexed Files)
18.
________________________________________________________________________
|(MF) |
|Following a READ which encounters a locked record status, the file |
|position indicator points at the locked record. A subsequent READ |
|NEXT or READ PREVIOUS will retrieve the same record again. |
________________________________________________________________________
________________________________________________________________________
|(ANS85) |
|The NOT AT END phrase is only executed following successful completion|
|of the operation. |
________________________________________________________________________
________________________________________________________________________
|(MF) |
| |
| |
| |
|19. If when a READ statement with the PREVIOUS option is executed no |
| previous logical record exists in the file, the AT END |
| condition |
| |
| occurs, and the execution of the READ statement is considered |
| unsuccessful. |
| |
________________________________________________________________________
20. When the AT END condition has been recognized, the next Format 1 or
Format 2 READ statement, if any, executed for that file must be a
READ NEXT statement, if AT END occurred because noprevious logical
record existed. Otherwise (MF) the AT END condition must be followed
by:
a. A successful CLOSE statement followed by the execution of a
successful OPEN statement for that file.
b. A successful START statement for that file.
c. A successful Format 4 (or Format 5 for indexed files) READ
statement for that file.
21. For a file for which dynamic access mode is specified, a READ
statement with the NEXT phrase specified causes the next logical
record to be retrieved from the file as described in General Rule
20. (MF)
22. The record to be made available by the READ statement is determined
as follows:
a. If the file position indicator was positioned by the
execution of an OPEN statement, and the PREVIOUS option is
specified, the AT END condition occurs. Otherwise (MF) if the
file position indicator was positioned by the execution of
the START or OPEN statement and the record is still
accessible through the path indicated by the file position
indicator, the record pointed to by the file position
indicator is made available. If the record is no longer
accessible, which can have been caused for a relative file by
deletion of the record, or for an indexed file by a change in
an alternate key, the file position indicator is updated to
point to the next or, if the PREVIOUS option is specified,
the previous (MF) existing record within the established key
of reference, and that record is then made available.
b. If the file position indicator was positioned by the
execution of a previous READ statement, the file position
indicator is updated to point to the next or, if the PREVIOUS
option is specified, the previous (MF) existing record in the
file.
________________________________________________________________________
|(MF) |
|However, if the previous statement was a READ, and if that READ |
|returned a locked record status, the file position indicator is left |
|unchanged. The record pointed to by the file position indicator is |
|made available. |
________________________________________________________________________
________________________________________________________________________
|(MF) |
| |
| |
| |
|23. If the lock mode is MANUAL with single record locking and the |
| referenced file is opened I/O, the run unit acquires a |
| record lock on the record only if the WITH LOCK phrase is |
| specified. A simple READ statement does not acquire a |
| record lock. To read past a locked record the file position |
| indicator should be updated using the START statement. |
| This, however, cannot be used on alternate keys which allow |
| duplicates. |
| |
________________________________________________________________________
________________________________________________________________________
|(MF) |
| |
| |
| |
|24. If the lock mode is MANUAL with multiple record locking and the |
| referenced file is opened I/O, the run unit acquires a |
| lock on the record only if the WITH KEPT LOCK phrase is |
| specified. A simple READ statement does not acquire a |
| record lock. To read past a locked record the file position |
| indicator should be updated using the START statement. |
| This, however, cannot be used on alternate keys which allow |
| duplicates. |
| |
| Your COBOL system can provide additional run-time methods of |
| reading past a locked record. See your COBOL System Reference |
| for additional information. |
| |
________________________________________________________________________
Formats 3 and 4 (Relative Files)
25. If the RELATIVE KEY phrase is specified, the execution of a READ
statement updates the contents of the RELATIVE KEY data item so that
it contains the relative record number of the record made available.
26. The execution of a READ statement sets the file position indicator
to, and makes available, the record whose relative record number is
contained in the data item named in the RELATIVE KEY phrase for the
file. If the file does not contain such a record, the INVALID KEY
condition exists and execution of the READ statement is
unsuccessful. (See section "The INVALID KEY Condition" in this
chapter.)
Formats 3 and 5 (Relative and Indexed Files)
27. The WITH WAIT phrase ensures that a lock is acquired on the record,
waiting if necessary.
28. The IGNORE LOCK phrase causes the READ to proceed as if the record
were not locked.
Format 5 (Indexed Files)
29. For an indexed file being sequentially accessed, records having the
same duplicate value in an alternate record key which is the key of
reference are made available in the same order in which they are
released by execution of WRITE statements, or by execution of
REWRITE statements which create such duplicate values.
30. If the KEY phrase is not specified the prime record key is
established as the key of reference for this retrieval. If dynamic
access mode is specified, this key of reference is also used for
retrievals by any subsequent executions of Format 3 READ statements
for the file.
31. If the KEY phrase is specified, data-name-1 or split-key-name (MF)
is established as the key of reference for this retrieval. If
dynamic access mode is specified, this key of reference is also used
for retrievals by any subsequent executions of Format 3 READ
statements for the file until a different key of reference is
established for the file.
32. Execution of a Format 5 READ statement causes the value of the key
of reference to be compared with the value contained in the
corresponding data item of the stored records in the file, until the
first record having an equal value is found. The file position
indicator is positioned to this record which is then made available.
If no record can be so identified, the INVALID KEY condition exists
and execution of the READ statement is unsuccessful. (See the
section "The INVALID KEY Condition" in this chapter.)
MPE/iX 5.0 Documentation
HP 3000 Manuals