The MERGE statement combines two or more identically sequenced files on
a set of specified keys, and during the process makes records available, in
merged order, to an output procedure or to an output file.
General Format
Syntax Rules
- File-name-1 must be described in a sort-merge file description entry
in the Data Division.
- Procedure-name-1 represents the name of an output procedure.
- Procedure-name-1 and procedure-name-2 must be section-names.
This restriction is
removed.
-
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.
- 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.
- The words THRU and THROUGH are equivalent.
-
Data-name-1 is a KEY data-name and is subject to the following rules:
- The data items identified by KEY data-names must be described in
records associated with file-name-1.
- KEY data-names can be qualified.
- The data items identified by KEY data-names must not be variable
length items.
- 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.
- 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.
-
KEY data items can be
floating-point items.
-
If the KEY is an
external floating-point item, the key is treated as alphanumeric. The sequence
in which the records are merged depends on the collating sequence used.
-
If the KEY is an
internal floating-point item, the sequence of key values will be in numeric
order.
- No more than one file-name from a multiple file reel can appear in
the MERGE statement.
- File-names must not be repeated in the MERGE statement.
- MERGE statements can appear anywhere except in the declaratives
portion of the Procedure Division.
-
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.
-
If the GIVING phrase is
specified and the file referenced by file-name-4 contains variable length
records, the size of the records contained in the file referenced by
file-name-1 must not be less than the smallest record nor greater than the
largest record described for file-name-4. If the file referenced by file-name-4
contains fixed length records, the size of the records contained in the file
referenced by file-name-1 must not be greater than the largest record described
for file-name-4.
- If you want to specify more than 10 file-names in the USING or GIVING
clause, you must use the Compiler directive CALLSORT"EXTSM"; this
allows you to specify up to 255 files.
General Rules
- The MERGE statement merges all records contained on the files
referenced by file-name-2 and file-name-3.
- 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.
- 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, and so on.
- 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.
- 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.
- 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:
- follows the order of the associated input files as specified in
the MERGE statement
- is such that all records associated with one input file are
returned prior to the return of records from another input file.
- 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:
- First, the collating sequence established by the COLLATING
SEQUENCE phrase, if specified, in that MERGE statement.
- Second, the collating sequence established as the program
collating sequence.
- 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.
- 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:
- 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.
- 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.
- 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.
- 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 Concepts of the COBOL
Language.)
- 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.
- 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.
- 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:
- The processing of the file is initiated. The initiation is
performed as if an OPEN statement with the OUTPUT phrase had been executed.
- 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.
- 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.
- 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.
-
Segmentation, as defined in the chapter Segmentation in your
Language Reference - Additional Topics, can be applied to
programs containing the MERGE statement. However, the following restrictions
apply:
- 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:
- totally within non-independent segments, or
- wholly contained in a single independent segment.
- If a MERGE statement appears in an independent segment, then any
output procedure referenced by that MERGE statement must be contained:
- totally within non-independent segments, or
- wholly within the same independent segment as that MERGE
statement.
-
The SORT-RETURN special register is available to source elements with a MERGE
statement. 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 MOVE statement transfers data, in accordance with the rules of
editing, to one or more data areas.
General Formats
Format 1
Format 2
Directives
- In addition to Compiler directives which provide flagging and modify
the reserved word list, the following directives may impact either the syntax
or semantics described in this section.
- BYTE-MODE-MOVE - impacts the behavior of MOVE statements in which
the sending and receiving items share a part of their storage (that is,
overlapping moves).
- DBCS (DBSPACE) - impacts what characters are used for space
filling DBCS receiving items.
- DE-EDIT - controls whether the value of numeric-edited sending
fields is determined by their PICTURE clause or not.
- TRUNC - determines when the sending item includes a value larger
than a binary receiving values size, whether truncation occurs based on the
storage available or the PICTURE clause.
Syntax Rules
All Formats
- Identifier-1 and literal represent the sending area; identifier-2
represents the receiving area.
- A data item must not be specified as an operand of a MOVE statement,
if its usage is one of the following:
INDEX
OBJECT-REFERENCE
POINTER,
PROCEDURE-POINTER
ENTRY-POINTER,
MONITOR-POINTER, MUTEX-POINTER, SEMAPHORE-POINTER or THREAD-POINTER.
-
If either the sending or
receiving item is a DBCS (USAGE DISPLAY-1) item, then both must be DBCS items.
The figurative constant SPACE can be the DBCS sending item.
Format 1
-
When Format 1 is
specified, all identifiers can be either group or elementary items. The data in
the sending area is moved into the data item referenced by each identifier-2 in
the order in which it is specified.
-
Identifier-1 may be a
numeric function-identifier.
Format 2
- CORR is an abbreviation for CORRESPONDING.
- When the CORRESPONDING phrase is used, all identifiers must be group
items.
- The following items can be part of a group that is referenced in a
MOVE CORRESPONDING statement; however, no movement of this item will take
place:
POINTER,
PROCEDURE-POINTER
OBJECT-REFERENCE
EVENT-POINTER,
MONITOR-POINTER, MUTEX-POINTER, SEMAPHORE-POINTER, THREAD-POINTER.
- A pointer data item can be part of a group that is referenced in a
MOVE CORRESPONDING statement; however, no movement of the pointer data item
will take place.
General Rules
All Formats
-
If identifier-1 is a
numeric function-identifier, then identifier-2 must be either a numeric or
numeric edited item.
- The data designated by the literal or identifier-1 is moved to the
data item referenced by each identifier-2, in the order in which it is
specified. The rules referring to identifier-2 also apply to the other
receiving areas. Any subscripting or indexing associated with identifier-2, is
evaluated immediately before the data is moved to the respective data item.
If identifier-1 is
reference modified, subscripted, or is a function- identifier, the reference
modifier, subscript, or function-identifier is evaluated only once, immediately
before data is moved to the first of the receiving operands.
The result of the
statement:
MOVE a(b) TO b, c(b)
is equivalent to:
MOVE a(b) TO temp
MOVE temp TO b
MOVE temp TO c(b)
where temp
is an intermediate result item provided by your COBOL
system.
- Any MOVE in which the sending and receiving items are both elementary
items is an elementary move. Every elementary item belongs to one of the
following categories: numeric, alphabetic, alphanumeric, numeric edited,
alphanumeric edited
or floating-point.
These categories are described in the PICTURE clause. Numeric
literals belong to the category numeric, and nonnumeric literals belong to the
category alphanumeric. The figurative constant ZERO belongs to the category
numeric when moved to a numeric or numeric-edited item. The figurative constant
ZERO belongs to the category alphanumeric in all other cases. The figurative
constant SPACE belongs to the category alphabetic. All other figurative
constants belong to the category alphanumeric.
The following rules apply to an elementary move between these
categories:
- The figurative constant SPACE, or an alphanumeric edited, or
alphabetic data item must not be moved to a numeric or numeric edited data
item.
- A numeric edited data item must not be moved to a numeric or
numeric edited data item.
This restriction is
removed.
- A numeric literal, the figurative constant ZERO, a numeric data
item or a numeric edited data item must not be moved to an alphabetic data
item.
- A non-integer numeric literal or a non-integer numeric data item
must not be moved to an alphanumeric or alphanumeric-edited data item.
- All other elementary moves are legal and are performed according
to the rules given in General Rule 5.
- Any necessary conversion of data from one form of internal
representation to another takes place during legal elementary moves, along with
any editing specified for
,or de-editing implied
by,
the receiving data item:
- When an alphanumeric edited or alphanumeric item is a receiving
item, alignment and any necessary space filling takes place as defined in the
section Standard Alignment Rules in the chapter Concepts of the COBOL
Language. If the size of the sending item is greater than the size of the
receiving item, the excess characters are truncated on the right after the
receiving item is filled. If the sending item is described as being signed
numeric, the operational sign will not be moved; if the operational sign
occupies a separate character position (see the section The SIGN Clause
earlier in this chapter), that character will not be moved and the size of the
sending item will be considered to be one less than its actual size (in terms
of standard data format characters).
- When a numeric or numeric edited item is the receiving item,
alignment by decimal point and any necessary zero-filling takes place as
defined in the section Standard Alignment Rules in the chapter
Concepts of the COBOL Language, except where zeros are replaced because
of editing requirements.
When the sending
operand is numeric edited, de-editing is implied to establish the operand's
unedited numeric value, which can be signed; then the unedited numeric value is
moved to the receiving field. The effect of de-editing depends on the setting
of the DE-EDIT Compiler directive
When a signed numeric item is the receiving item, the sign of
the sending item is placed in the receiving item. (See the section The SIGN
Clause earlier in this chapter.) Conversion of the representation of the
sign takes place as necessary. If the sending item is unsigned, a positive sign
is generated for the receiving item.
When an unsigned numeric item is the receiving item, the
absolute value of the sending item is moved and no operational sign is
generated for the receiving item.
When a data item described as alphanumeric is the sending item,
data is moved as if the sending item were described as an unsigned numeric
integer.
When the receiving item is numeric or numeric-edited and the
sending item is defined as alphanumeric, if the content of the sending item is
not an integer, the results of the move are undefined. If the alphanumeric
sending item is a literal whose contents do not represent an integer, an error
will be reported, and zero moved to the target. (See the section
Incompatible Data earlier in this chapter.)
When the numeric data
item is the sending item the action of the move will be such that a reverse of
the move would cause the same value to appear in the numeric edited field
(except or truncation). If the data item contains data which does not conform
to the edited picture, zero is moved to the target.
- When a receiving field is described as alphabetic, justification
and any necessary space-filling takes place as defined in the section
Standard Alignment Rules in the chapter Concepts of the COBOL
Language. If the size of the sending item is greater than the size of the
receiving item, the excess characters are truncated on the right after the
receiving item is filled.
-
When the receiving
field is floating-point, the sending item is converted first to internal
floating-point and then moved. When data is moved to or from an external
floating-point item, the data is converted first to or from its equivalent
internal floating-point value.
-
When the receiving
field is DBCS the sending item must also be DBCS; no conversion takes place. If
the sending and receiving items are not the same size the data item will be
either truncated or padded with DBCS spaces on the right.
- Any move that is not an elementary move is treated exactly as if it
were an alphanumeric to alphanumeric elementary move, except that no conversion
of data from one form of internal representation to another takes place. In
such a move, the receiving area will be filled without consideration for the
individual elementary or group items contained in either the sending or
receiving area, except as noted in the General Rules of the OCCURS clause.
- Table 14-1 summarizes the legality of the various types of MOVE
statements. The general rule reference indicates the rule that prohibits the
move or the behavior of a legal move.
Format 2
- If the CORRESPONDING phrase is used, selected items in identifier-1
are moved to selected items in identifier-2, according to the rules given in
the section The CORRESPONDING Phrase earlier in this chapter. The
results are the same as if the user had referred to each pair of corresponding
identifiers in separate MOVE statements.
The process is repeated
for each destination group.
Table 14-1: MOVE Statement Data Categories
Category of Sending
Item |
Category of Receiving
Data Items1 |
Alphabetic |
Alphanumeric-Edited/
Alpha-numeric |
Numeric Integer/Non-Integer |
Numeric-Edited External/Internal
Floating Point |
DBCS |
Alphabetic |
Yes/4c |
Yes/4a |
No/3a |
No/3a |
No/4e |
Alphanumeric |
Yes/4c |
Yes/4a |
Yes/4b2 |
Yes/4b |
No/4e |
Alphanumeric-Edited |
Yes/4c |
Yes/4a |
No/3a |
No/3a |
No/4e |
Numeric Integer |
No/3b |
Yes/4a |
Yes/4b |
Yes/4b |
No/4e |
Numeric Non-Integer |
No/3b |
No/3c |
Yes/4b |
Yes/4b |
No/4e |
Numeric-Edited |
No/3b |
Yes/4a |
Yes/4b |
Yes/4b |
No/4e |
DBCS |
No/4e |
No/4e |
No/4e |
No/4e |
Yes/4e |
- The relevant rule number is quoted in these columns
- An error will be reported if a non-integer alphanumeric literal
sending item is used
The MULTIPLY statement causes numeric data items to be multiplied and
sets the values of data items equal to the results.
General Formats
Format 1
Format 2
Syntax Rules
All Formats
- Each identifier must refer to a numeric elementary item, except that
in Format 2 each identifier following the word GIVING must refer to either an
elementary numeric item or an elementary numeric edited item.
- Each literal must be a numeric literal.
-
The composite of operands is
determined by using all receiving data items. See the section Arithmetic
Statements in the chapter Procedure Division.
-
Floating-point data items
and literals can be used anywhere a numeric data item or literal can be
specified.
General Rules
All Formats
- See the sections The ROUNDED Phrase, The ON SIZE ERROR
Phrase, Arithmetic Statements, Overlapping Operands and Multiple
Results In Arithmetic Statements in this chapter.
Format 1
- When Format 1 is used, the value of identifier-1 or literal-1 is
multiplied by the value of identifier-2. The value of the multiplier
(identifier-2) is replaced by this product; similarly for each successive
occurrence of identifier-2 in the left-to-right order in which identifier-2 is
specified.
Format 2
- When Format 2 is used, the value of identifier-1 or literal-1 is
multiplied by identifier-2 or literal-2 and the result is stored in the data
item referenced by each identifier-3.
The NEXT SENTENCE statement transfers control to the next COBOL
sentence, that is, following the next period. It does not transfer control to
the logically next COBOL verb as occurs with the CONTINUE verb.
General Format
Syntax Rules
- The NEXT SENTENCE statement can be used anywhere a conditional
statement or an imperative-statement can be used.
General Rules
- The NEXT SENTENCE statement redirects the flow of execution to the
logically next COBOL verb following the next period.
The NOTE statement introduces a sentence or paragraph that will be
treated as comments.
General Format
Syntax Rules
- The character-string can be any combination of characters from the
computer character set.
General Rules
- If a NOTE statement is the first sentence of a paragraph, the entire
paragraph is treated as comment.
- If a NOTE statement appears as other than the first sentence of a
paragraph, text up to the next separator period is treated as comment.
The ON statement allows selective execution of procedural statements on
a periodic basis.
General Format
Syntax Rules
- Identifier-1, identifier-2 and identifier-3 must describe unsigned
integer numeric elementary items.
- Literal-1, literal-2 and literal-3 must be unsigned numeric literals.
General Rules
- Prior to the first execution of each ON statement
, a counter, implicitly defined for that ON statement (the
implicit-ON-counter), is initialized to be zero.
- Identifier-1, identifier-2 and identifier-3 should, if specified,
contain positive integer values at the time of execution of the ON statement.
Varying these values between executions of the ON statement will affect
subsequent executions of the ON statements.
- The implicit ON counter cannot be affected in any way other than by
transfer of
execution flow to that ON statement. (The ON counter of a called
program can only be reset by the cancelling of that program; execution of the
EXIT PROGRAM statement and subsequent CALL of the program without intervening
CANCEL has no effect upon the implicit ON counter value.)
- The following value-list is then evaluated:
- the current value of identifier-1 or literal-1,
- a sequence of values being the results of repeatedly adding the
current value of identifier-2 or literal-2 to the current value of identifier-1
or literal-1 until the value of identifier-3 or literal-3 is reached.
The implicit-ON-counter is then compared with each of this list of
values. If an equality is found, then imperative-statement-1 is executed. If no
equality is found, then imperative-statement-2, if specified, is executed.
The OPEN statement initiates the processing of files. It also performs
checking and/or writing of labels and other input-output operations.
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.
All dialects in this COBOL
implementation fully support this syntax. The FLAGSTD Compiler directive can be
used to detect all occurrences of this syntax.
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 a conforming X/Open COBOL source program.
The OPEN statement allocates
system resources for a synchronization data item and initializes the data
item.
General Formats
Format 1 (Record Sequential Files)
Format 2 ( Line Sequential, Relative And Indexed Files)
where sharing-phrase is:
Format 3 (Synchronization Data
Items)
Syntax Rules
All Formats (All Files)
- The files referenced in the OPEN statement need not all have the same
organization or access.
-
If SHARING ALL is
specified and the INPUT phrase is not specified, the LOCK MODE clause must be
specified in the file control entry for file-name-1.
Format 1 (Record Sequential Files)
-
NO REWIND is documentary
only.
- The
I-O phrase can be
used only for disk files.
- The EXTEND phrase must be used only for files for which the LINAGE
clause has not been specified.
- The EXTEND phrase must not be specified with multiple file reels.
Format 2 (
Line
Sequential,
Relative and Indexed Files)
-
The EXTEND phrase can be
used for files in sequential access mode.
-
The SHARING phrase must
not be specified for files with line sequential organization.
Format 3 (Synchronization Data
Items)
-
Identifier-1 must reference
an elementary data item with a USAGE of EVENT-POINTER, MONITOR-POINTER,
MUTEX-POINTER or SEMAPHORE-POINTER.
General Rules
Formats 1 and 2 (All Files)
- 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.
-
The successful execution
of an OPEN statement determines the availability of the file and results in the
file connector referenced by the file-name being in an open mode. The
successful execution of an OPEN statement associates the file with the
file-name through a file connector.
The key words INPUT, OUTPUT, I-O, and EXTEND specify the type of
input-output operations intended for the file through the file connector and
establish the open mode. (See table 14-4, Permissible Combinations of
Statements and OPEN Modes.)
A file is available if it is physically present and is recognized by
the file handling system. Table 14-2, Opening Available and Unavailable Files
(file not currently open), shows the results of opening available and
unavailable files that are not currently open. Table 14-3, Opening Available
Shared Files that are Currently Open by Another File Connector, shows the
results of opening available and unavailable files that are currently open by
another file connector.
Table 14-2: Opening Available and Unavailable Files (file not
currently open)
Open Mode |
File is available |
File is unavailable |
INPUT |
Normal open |
Open is unsuccessful |
INPUT (optional file) |
Normal open |
Normal open; the first read causes the at end condition or
invalid key condition |
I-O |
Normal open |
Open is unsuccessful |
I-O (optional file) |
Normal open |
Open causes the file to be created |
OUTPUT |
Normal open; the file contains no records |
Open causes the file to be created |
EXTEND |
Normal open |
Open is unsuccessful |
EXTEND (optional file) |
Normal open |
Open causes the file to be created |
Table 14-3: Opening available shared files that are currently
open by another file connector
Open request |
Most restrictive existing sharing
mode and open mode |
sharing with no other |
sharing with read only |
sharing with all other |
extend I-O input
output |
extend I-O
output |
input |
extend I-O
output |
input |
SHARING WITH NO OTHER |
EXTEND I-O INPUT
OUTPUT |
Unsuccessful open |
Unsuccessful open |
Unsuccessful open |
Unsuccessful open |
Unsuccessful open |
SHARING WITH READ ONLY |
EXTEND I-O |
Unsuccessful open |
Unsuccessful open |
Unsuccessful open |
Unsuccessful open |
Normal open |
INPUT |
Unsuccessful open |
Unsuccessful open |
Normal open |
Unsuccessful open |
Normal open |
OUTPUT |
Unsuccessful open |
Unsuccessful open |
Unsuccessful open |
Unsuccessful open |
Unsuccessful open |
SHARING WITH ALL OTHER |
EXTEND I-O |
Unsuccessful open |
Unsuccessful open |
Unsuccessful open |
Normal open |
Normal open |
INPUT |
Unsuccessful open |
Normal open |
Normal open |
Normal open |
Normal open |
OUTPUT |
Unsuccessful open |
Unsuccessful open |
Unsuccessful open |
Unsuccessful open |
Unsuccessful open |
- The successful execution of an OPEN statement makes the associated
record area available
.
- In Table 14-2, "X" at an intersection indicates that
the specified statement, used in the access mode given for that row, can be
used with the open mode given at the top of the column.
Table 14-4: Permissible Combinations of Statements and OPEN
Modes
File Access Mode |
OPEN Mode |
Statement |
Input |
Output |
Input-Output |
Extend |
Sequential |
READ |
X |
|
X |
|
WRITE |
|
X |
|
X |
REWRITE |
|
|
X |
|
Random (Non-Sequential
Files) |
READ |
X |
|
X |
|
WRITE |
|
X |
X |
|
REWRITE |
|
|
X |
|
START |
|
|
|
|
DELETE |
|
|
X |
|
Dynamic (Non-Sequential
Files) |
READ |
X |
|
X |
|
WRITE |
|
X |
X |
|
REWRITE |
|
|
X |
|
START |
X |
|
X |
|
DELETE |
|
|
X |
|
Note: The START and DELETE statements can not be used with
record
or line
sequential files.
-
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.)
-
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.
-
A file can be opened with
the INPUT, OUTPUT, EXTEND and
I-O phrases in the
same run unit. Following the initial execution of an OPEN statement for a file
connector, each subsequent OPEN statement execution for that same file
connector must be preceded by the execution of a CLOSE statement for that file
connector, even if the file is optional.
- Execution of the OPEN statement does not obtain or release the first
data record.
- The external name of the file specified in the SELECT clause for a
file is processed as follows:
- When the INPUT phrase is specified, execution of the OPEN
statement causes the name to be checked in accordance with the operating system
conventions for opening files for input.
- When the OUTPUT phrase is specified, execution of the OPEN
statement causes the name to be checked in accordance with the operating system
conventions for opening files for output.
- 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.
-
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 in 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, unless the file is optional.
- 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:
- The labels are checked in accordance with the operating
system-specified conventions for input-output label checking.
- The new labels are written in accordance with the operating
system-specified conventions for input-output label writing.
- 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.
-
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.
-
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).
-
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.
-
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.
-
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.
-
Only shareable files opened
for I-O can
acquire record locks.
- If execution of the OPEN statement is unsuccessful, the physical file
is not affected and the following actions take place in this order:
- 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.
- Any applicable USE AFTER EXCEPTION procedure is executed. (See
the section The USE Statement in this chapter.)
- 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:
- If the OPTIONAL phrase is specified in the SELECT clause for the file, the
file is created
- If the NOT OPTIONAL phrase is specified in the SELECT clause for the file, an
error occurs
- If neither phrase is specified, and the
directive OPTIONAL-FILE was specified when the source element was compiled, the
file is created.
- If neither phrase is specified, and the directive NOOPTIONAL-FILE
was specified when the source element was compiled, an error occurs.
- If an input file is designated with the OPTIONAL phrase in its SELECT
clause, when the file is opened there is 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.
- 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.
-
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:
- The beginning file labels are processed only in the case of a
single reel/unit file.
- The beginning reel/unit labels on the last existing reel/unit are
processed as though the file was being opened with the INPUT phrase.
- The existing ending file labels are processed as though the file
is being opened with the INPUT phrase. These labels are then deleted.
- Processing then proceeds as though the file had been opened with
the OUTPUT phrase.
- The I-O
phrase permits the opening of a file for both input and output operations,
except files with
ORGANIZATION LINE SEQUENTIAL.
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 SHARING phrase can be
specified only for shared files. (See
the section Sharing
Mode in the chapter Concepts of a Compilation Group .)
-
The SHARING phrase
specifies what operations may be performed on the file through other file
connectors sharing the file. (See
the section Sharing
Mode in the chapter Concepts of a Compilation Group .)
-
The SHARING phrase
overrides any SHARING clause in the file control entry of the file connector
associated with the file-name. If there is no SHARING phrase on the OPEN
statement, then file sharing is completely specified in the file control entry.
If neither a SHARING phrase on the OPEN statement nor a SHARING clause in the
file control entry is specified, the sharing mode is established for the file
connector in accordance with
the rules specified in
the section Sharing Mode in the chapter Concepts of a Compilation
Group.
Format 1 (Record Sequential Files)
- If the storage medium for the file permits rewinding, the following
rules apply:
- Execution of the OPEN statement causes the file to be positioned
at its beginning.
- When the REVERSED phrase is specified, the file is positioned at
its end by execution of the OPEN statement.
- 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)
-
I-O mode is not
allowed for line sequential files unless the REWRITE-LS Compiler directive is
set.
Format 3 (Synchronization
Data Items)
- Prior to the successful execution of an OPEN statement for a given
synchronization data item, no statement can be executed that references that
data item.
- The successful execution of an OPEN statement determines the
availability of the synchronization data item.
- Execution of the OPEN statement causes the RETURN-CODE special
register to be updated with one of the values specified for the CBL_MUTEX APIs.
- Following the initial execution of an OPEN statement for a
synchronization data item, each subsequent OPEN statement execution for that
same data item must be preceded by the execution of a CLOSE statement for that
data item.
- If identifier-1 references an event data item, the execution of the
OPEN statement initializes the data item to FALSE.
- If identifier-1 references a monitor data item, the execution of the
OPEN statement initializes the monitor to NOT BROWSING, NOT READING, and NOT
WRITING.
- If identifier-1 references a mutex data item, the execution of the
OPEN statement initializes the data item to OFF.
- If identifier-1 references a semaphore data item, the execution of
the OPEN statement initializes the data item to zero.
Copyright © 2001 Micro Focus International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.