| Procedure Division - PERFORM - ROLLBACK |
| Object COBOL Language Extensions | |
The SEARCH statement is used to
search a table for a table element that satisfies the specified
condition and to adjust the associated index-name to indicate that table
element.
General Format
Format 1
Format 2
Note that the required relational character "=" is not
underlined to avoid confusion with other symbols.
Syntax Rules
All Formats (All Files)
- Identifier-1 must not be subscripted or indexed, but its description
must contain an
OCCURS clause and an
INDEXED BY clause. The description of identifier-1 in Format 2 must
also contain the KEY IS phrase in its OCCURS clause.
- Identifier-2, when specified, must be described as USAGE IS INDEX or as
a numeric elementary item without any positions to the right of the assumed
decimal point.
-
If the END-SEARCH phrase is
specified, the NEXT SENTENCE phrase must not be specified.
END-SEARCH can be specified
with NEXT SENTENCE. If the NEXT SENTENCE phrase is executed, control will
not pass to the next statement following the END-SEARCH, but instead will
pass to the statement after the closest following period.
-
Both imperative-statement-1 and
imperative-statement-2 can be replaced by a conditional statement.
Format 1
- Condition-1, condition-2, and so on, can be any condition as described
in the section Conditional Expressions earlier in this chapter.
-
Identifier-1, the table
element being searched, can be an internal or external floating-point item.
Format 2
- All referenced condition-names must be defined as having only a single
value. The data-name associated with a condition-name must appear in the
KEY clause of identifier-1. Each data-name-1, data-name-2 can be
qualified. Each data-name-1, data-name-2 must be indexed by the first
index-name associated with identifier-1 along with other indices or literals
as required, and must be referenced in the KEY clause of identifier-1.
Identifier-3, identifier-4, or identifiers specified in
arithmetic-expression-1, arithmetic-expression-2 must not be referenced in
the KEY clause of identifier-1 or be indexed by the first index-name
associated with identifier-1.
When a data-name in the KEY clause of identifier-1 is referenced, or
when a condition-name associated with a data-name in the KEY clause of
identifier-1 is referenced, all preceding data-names in the KEY clause of
identifier-1 or their associated condition-names must also be referenced.
-
Identifier-1, the table
element being searched, can not be a floating-point item.
-
Neither data-name-1 nor
data-name-2, the key data items, can be floating point items. However,
identifier-3, identifier-4, literal-1, or literal-2, the items against which
the key is compared, can be floating-point items.
General Rules
All Formats
- The scope of a SEARCH statement can be terminated by any of the
following:
-
An END-SEARCH phrase at the
same level of nesting.
- separator period.
- An ELSE
or END-IF
associated with a previous IF statement.
- After execution of imperative-statement-1 or imperative-statement-2,
that does not terminate with a GO TO statement, control passes to the next
executable sentence.
- If identifier-1 is a data item subordinate to a data item that contains
an OCCURS clause (providing for a
two- or
three-dimensional table), an index-name must be associated with each
dimension of the table through the INDEXED BY phrase of the OCCURS clause.
Only the setting of the index-name associated with identifier-1 (and the
data item identifier-2 or index-name-1, if present) is modified by the
execution of the SEARCH statement. To search an entire two or three
dimensional table it is necessary to execute a SEARCH statement several
times. Prior to each execution of a SEARCH statement, SET statements must be
executed whenever index-names must be adjusted to appropriate settings.
Format 1
- If Format 1 of the SEARCH is used, a
serial type of
search operation takes place, starting with the current index setting.
- If, at the start of execution of the SEARCH statement, the index-name
associated with identifier-1 contains a value that corresponds to an
occurrence number that is greater than the highest permissible occurrence
number for identifier-1, the SEARCH is terminated immediately. The number
of occurrences of identifier-1, the last of which is the highest
permissible, is discussed in the OCCURS clause. (See the section The
OCCURS Clause earlier in this chapter.) Then, if the AT END phrase is
specified, imperative- statement-1 is executed; if the AT END phrase is
not specified, control passes to the next executable sentence.
- If, at the start of execution of the SEARCH statement, the index-name
associated with identifier-1 contains a value that corresponds to an
occurrence number that is not greater than the highest permissible
occurrence number for identifier-1 (the number of occurrences of
identifier-1, the last of which is the highest permissible is discussed in
the OCCURS clause), the SEARCH statement operates by evaluating the
conditions in the order that they are written, making use of the index
settings, wherever specified, to determine the occurrence of those items
to be tested. If none of the conditions is satisfied, the index name for
identifier-1 is incremented to obtain reference to the next occurrence.
The process is then repeated using the new index-name settings unless the
new value of the index-name settings for identifier-1 corresponds to a
table element outside the permissible range of occurrence values, in which
case the search terminates as indicated in General Rule 1a above. If one
of the conditions is satisfied upon its evaluation, the search terminates
immediately and the imperative statement associated with that condition is
executed; the index-name remains set at the occurrence which caused the
condition to be satisfied.
- If the VARYING phrase is not used, the index-name that is used for the
search operation is the first (or only) index-name that appears in the
INDEXED BY phrase of identifier-1. Any other index-names for identifier-1
remain unchanged.
- If the VARYING index-name-1 phrase is specified, and if index-name-1
appears in the INDEXED BY phrase of identifier-1, that index-name is used
for this search. If this is not the case, or if the VARYING identifier-2
phrase is specified, the first (or only) index-name given in the INDEXED BY
phrase of identifier-1 is used for the search. In addition, the following
operations will occur:
- If the VARYING index-name-1 phrase is used, and if index-name-1
appears in the
INDEXED BY phrase of another table entry, the occurrence number
represented by index-name-1 is incremented by the same amount as, and at
the same time as, the index-name associated with identifier-1 is
incremented.
- If the VARYING identifier-2 phrase is specified, and identifier-2 is
an index data item, then the data item referenced by identifier-2 is
incremented by the same amount as, and at the same time as, the index
associated with identifier-1 is incremented. If identifier-2 is not an
index data item, the data item referenced by identifier-2 is incremented
by the value (1) at the same time as the index referenced by the
index-name associated with identifier-1 is incremented.
Format 2
- The results of the
SEARCH ALL operation are predictable only when:
- The data in the table is ordered in the same manner as described in
the ASCENDING/DESCENDING KEY clause associated with the description of
identifier-1, and:
- The contents of the key(s) referenced in the WHEN clause are
sufficient to identify a unique table element.
- If Format 2 of the SEARCH is used, a
non-serial type of search operation can take place; the initial setting
of the index-name for identifier-1 is ignored and its setting is varied
during the search operation with the restriction that at no time is it set
to a value that exceeds the value which corresponds to the last element of
the table, or that is less than the value that corresponds to the first
element of the table. The length of the table is discussed in the OCCURS
clause. If any of the conditions specified in the WHEN clause cannot be
satisfied for any setting of the index within the permitted range, control
is passed to imperative-statement-1 of the AT END phrase, when specified, or
to the next executable sentence when this phrase is not specified; in either
case the final setting of the index is not predictable. If all conditions
can be satisfied, the index indicates an occurrence that allows the
conditions to be satisfied, and control passes to imperative-statement-2.
- The index-name that is used for the search operation is the first (or
only) index-name that appears in the INDEXED BY phrase of identifier-1. Any
other index-names for identifier-1 remain unchanged.
-
Neither
imperative-statement-2 nor NEXT SENTENCE is required. Without them, the
SEARCH statement sets the index to the value in the table that matched the
condition.
Figure 16-5 shows a flowchart of the Format 1 SEARCH operation containing
two WHEN phrases.
Figure 16-1: Flowchart of SEARCH Operation Showing Two WHEN Phrases
- These operations are options included only when specified in the SEARCH
statement.
- Each of these control transfers is to the next executable sentence
unless the imperative-statement ends with a GO TO statement.
The SERVICE
statement is used to establish addressability to Linkage Section items
usually in a CICS program.
General Format
Syntax Rules
- SERVICE LABEL is generated by the mainframe CICS preprocessor to
indicate control flow. It is not intended for general use.
- The SERVICE LABEL statement can appear only in the Procedure Division,
not in the Declaratives Section.
- Identifier should be either the first 01-level item representing the
BLL-cell block in the Linkage Section, or another Linkage Section 01-level
item for which addressability needs to be re-established following an EXEC
CICS statement.
General Rules
- At the statement following the SERVICE LABEL statement, all registers
that can no longer be valid are reloaded.
- If the OS/VS COBOL BLL mechanism is used in a CICS program,
addressability to the parameter list must be established at the start of the
Procedure Division. This is done by adding a SERVICE RELOAD identifier
statement at the start of the Procedure Division where the identifier is the
first item in Linkage Section and it includes pointers to all other entries
in the Linkage Section.
- If a locate-mode EXEC CICS statement is included in a program compiled
with the OSVS Compiler directive, then a SERVICE RELOAD statement must
follow each such CICS command and the identifier must be the same pointer
(BLL-cell reference) used in the CICS command.
- In a CICS program compiled with the OSVS Compiler directive, any time a
reference is made to a Linkage Section which is greater than 4096 bytes
long, a SERVICE RELOAD statement should be made to re-establish
addressability to that portion of the data item greater than 4096 byte.
- The SERVICE RELOAD statement is documentary only in a program compiled
with the VSC2 Compiler directive.
-
The SET statement is used to
alter the status of
external
switches.
-
The SET statement is used to
alter the value of
conditional
variables.
-
The SET statement is used to
assign the address of a data item to a pointer data item. It is also used to
adjust the contents of a pointer data item.
- The SET statement establishes
reference points for
table handling operations by setting indices associated with table
elements.
-
The SET statement is used to
assign the address of a program or an entry-point in a program to a
procedure-pointer data item.
General Formats
Format 1
Format 2
Format 3
Format 4
Format 5
Format 6
Format 7
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.
- STICKY-LINKAGE - determines whether addresses of data items placed in
pointer data items by the SET statement are retained between invocations
of a subprogram.
Syntax Rules
All Formats
- The figurative constant NULL or NULLS or the data item referenced by
pointer-name-2 or procedure-pointer-name-2 represents the sending area.
ADDRESS OF identifier-2, ENTRY identifier-8, ENTRY literal-1 or the value
held in the sending area, represents the sending value.
The data item referenced by pointer-name-1, pointer-name-3 or
procedure-pointer-name-1 or the COBOL system area implied by ADDRESS OF
identifier-1 represents the receiving area.
Identifier-3, integer-1 or LENGTH OF identifier-4 represents the
increment value.
Format 1
-
Mnemonic-name-1 must be
associated with an external switch, the status of which can be altered.
See the section The
Special-Names Paragraph for details of which external switches can be
referenced in the SET statement.
Format 2
-
Condition-name-1 must be
associated with a conditional variable.
-
If the FALSE phrase is
specified, the FALSE phrase must be specified in the VALUE clause of the
Data Description entry for condition-name-1.
-
Each FALSE or TRUE phrase
applies to the occurrences of condition-name-1 that precede that phrase and
follow a previous FALSE or TRUE phrase, if any.
Format 3
-
Identifier-1 must reference a
level 01 or level 77 data item that is declared in the Linkage Section.
-
Identifier-2 must reference a
data item with a level of 77 or between 01 and 49 inclusive
that is declared in the
Linkage-Section.
-
Pointer-name-1, pointer-name-2
must each be an identifier that references an elementary data item with
USAGE IS POINTER.
Format 4
-
Pointer-name-3 must be an
identifier that references an elementary data item with USAGE IS POINTER.
-
Identifier-3 must be an
elementary numeric integer.
-
Integer-1 may be signed.
Format 5
- Identifier-5 and identifier-6 must each reference an index data item or
an elementary item described as an integer. If both are specified, they must
not both reference an elementary item.
Formats 5 and 6
- Integer-2 and integer-3 may be signed. Integer-2 must be positive.
Format 6
- Identifier-7 must reference an elementary numeric integer.
Format 7
-
Procedure-pointer-name-1 and
procedure-pointer-name-2 must each be an identifier that references an
elementary data item with USAGE IS PROCE
DURE-POINTER.
-
Identifier-8 must be defined as
an alphanumeric data item such that its value can be a COBOL or a non-COBOL
program name.
-
Literal-1 must be a nonnumeric
literal.
General Rules
Format 1
-
The status of each external
switch associated with the specified mnemonic-name-1 is modified such that
the truth value resulting from evaluation of a condition-name associated
with that switch will reflect an on status if the ON phrase is specified, or
an off status if the OFF phrase is specified. (See the section Switch-Status
Condition earlier in this chapter.)
Format 2
-
The literal in the VALUE clause
associated with condition-name-1 is placed in the conditional variable
according to the rules of the VALUE clause (see the section The VALUE
Clause earlier in this chapter.) If more than one literal is specified
in the VALUE clause, the conditional variable is set to the value of the
first literal that appears in the VALUE clause.
-
If multiple condition-names are
specified, the results are the same as if a separate SET statement had been
written for each condition-name-1 in the same order as specified in the SET
statement.
-
If the FALSE phrase is
specified, the literal in the FALSE phrase of the VALUE clause associated
with condition-name-1 is placed in the conditional variable according to the
rules for the VALUE clause. (See the section The VALUE Clause earlier
in this chapter.)
Format 3
-
The sending value represents
the address of a data item. If pointer-name-2 is specified, the sending
value is the value contained with the data item referenced by
pointer-name-2. If ADDRESS OF identifier-2 is specified, the sending value
represents the address of identifir-2.
-
If pointer-name-1 is
specified, the sending value is moved to the data name referenced by
pointer-name-1.
-
If ADDRESS OF identifier-1 is
specified, the sending value is moved to a COBOL system area and the object
program subsequently operates such that the area of storage referenced by
identifier-1 is located at the address represented by the sending value.
Whether or not the link is
retained between invocations of a subprogram is dependent on the
STICKY-LINKAGE Compiler directive.
Format 4
-
Before execution of the SET
statement, the value of the data item referenced by pointer-name-3 must
represent the address of a data item within a logical record, the original
address. After execution of the SET statement, the value of the data item
referenced by pointer-name-3 represents the new address. If the original
address and the new address do not both lie within the same logical record,
(or, for environments in which address space is segmented, within the same
segment) then the results of using the value of the data item referenced by
pointer-name-3 are undefined.
-
If the UP clause is specified,
the new address is formed by adding the number of bytes given by the
increment value to the original address.
-
If the DOWN clause is
specified, the new address is formed by subtracting the number of bytes
given by the increment value from the original address.
Format 5
-
- Index-name-1 is set to a value causing it to refer to the table
element that corresponds in occurrence number to the table element
referenced by index-name-2, identifier-6, or integer-2. If identifier-6
references an index data item, or if index-name-2 is related to the same
table as index-name-1, no conversion takes place.
- If identifier-5 references an index data item, it can be set equal to
either the contents of index-name-2 or identifier-6 where identifier-6
also references an index item; no conversion takes place in either case.
- If identifier-5 does not reference an index data item, it can be set
only to an occurrence number that corresponds to the value of
index-name-2. Neither identifier-6 nor integer-2 can be used in this case.
- The process is repeated for all recurrence of index-name-1, or
identifier-5, if specified. Each time the value of index-name-2 or
identifier-6 is used as it was at the beginning of the execution of the
statement. Any subscripting or indexing associated with identifier-5 and
so on is evaluated immediately before the value of the respective data
item is changed.
- Data in the following table represents the validity of various operand
combinations in the SET statement. The general rule reference indicates the
applicable general rule.
Table 16-1: SET Index Statement Valid Operand Combinations
Sending Item |
Receiving Item |
Integer Data Item |
Index-Name |
Index Data Item |
Integer Literal |
No/9c |
Valid/9a |
No/9b |
Integer Data Item |
No/9c |
Valid/9a |
No/9b |
Index-Name |
Valid/9c |
Valid/9a |
Valid/9b1 |
Index Data Item |
No/9c |
Valid/9a1 |
Valid/9b1 |
1 = No conversion takes place.
Formats 5 and 6
- Index-names are associated with a given table by being specified in the
INDEXED BY phrase of the OCCURS clause for that table.
- If index-name-1 is specified, the value of the index after the execution
of the SET statement must correspond to an occurrence number of an element
in the table associated with index-name-1. The value of the index associated
with an index-name after the execution of a PERFORM or SEARCH statement may
be set to an occurrence number that is outside the range of its associated
table. (See the sections The PERFORM Statement and The SEARCH
Statement earlier in this chapter.)
If index-name-2 is specified, the value of the index before the
execution of the SET statement must correspond to an occurrence number of
an element in the table associated with index-name-1.
If index-name-3 is specified, the value of the index both before and
after the execution of the SET statement must correspond to an occurrence
number of an element in the table associated with index-name-3.
Format 6
- The contents of index-name-3 are incremented (UP BY) or decremented
(DOWN BY) by a value that corresponds to the number of occurrences
represented by the value of integer-3 or the data item referenced by
identifier-7; thereafter, the process is repeated for each recurrence of
index-name-3. For each repetition, the value of the data item referenced by
identifier-7 is used as it was at the beginning of the execution of the
statement.
Format 7
-
The sending value represents
the address of the start of a procedure within a COBOL or non-COBOL program.
-
The sending value is moved to
the data item referenced by procedure-pointer-name-1.
-
If procedure-pointer-name-2 is
specified, the sending value is the value contained within the data item
referenced by procedure-pointer-name-2.
-
Literal-1 or the content of the
data item referenced by identifier-8 is the name of the referenced
procedure. If the referenced procedure is a COBOL procedure, the name of the
referenced procedure must contain the program-name contained in the
PROGRAM-ID paragraph of the referenced program or the entry-name contained
in the ENTRY statement of the referenced procedure.
If the program being called is
not a COBOL program, the rules for the formation of the program or
procedure name are given in your COBOL system documentation on interfacing.
If the referenced procedure
has been previously made available and remains available at the time of
execution of the SET statement, then the sending value represents the
address of the referenced procedure.
If the referenced procedure is
not available at the time of execution of the SET statement, then the
sending value represents the address of a COBOL system error procedure.
The SORT statement creates a
sort file by executing input procedures or by transferring records from
another file, sorts the records in the sort file on a set of specified keys,
and in the final phase of the
sort operation, makes available each record from the sort file, in
sorted order to some output procedures or to an output file.
The SORT statement can also be
used to sort the elements of a
table.
Examples:
- Examples of using the SORT verb with input and output procedures to
order elements in a file are provided in the Examples chapter in
your Language Reference - Additional Topics.
- Examples of using the SORT verb to order elements in a table are
provided in the Examples chapter in your Language Reference
- Additional Topics.
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.
- CALLSORT - specifies the program to be used to handle SORT and MERGE
operations.
Syntax Rules
All Formats
- A Format 1
SORT statement cannot appear in the declaratives portion of the
Procedure Division, or in an input or output procedure associated with a
SORT or MERGE statement.
A Format 2 SORT can appear in
the Declaratives Section.
- Data-name-1 is a
KEY data-name and is subject to the following rules:
- KEY data-names can be qualified.
- The data items identified by KEY data-names must not be variable
length items.
- KEY data items can be floating-point items.
-
If the KEY is an external
floating-point item, the compiler will treat the data item as character
data, rather than numeric data. The sequence in which the records are
sorted depends on the collating sequence used.
-
If the KEY data item is
internal floating-point, the sequence of key values will be in numeric
order.
Format 1
- File-name-1 must be described in a Sort-Merge File Description entry in
the Data Division.
- 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.
- 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.
- 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.
- If the file referenced by file-name-1 contains variable length
records, all the data items identified by key data-names must be contained
within the first x character positions of the record, where x equals the
minimum record size specified for the file referenced by file-name-1.
- The words THRU and THROUGH are equivalent.
- File-name-2 and file-name-3 must be described in the file description
entry, not in a sort-merge file description entry, in the Data Division.
-
The files referenced by
file-name-2 and file-name-3 can reside on the same multiple file reel.
-
If file-name-3 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.
- No pair of file-names in the same
SORT statement can be specified in the SAME SORT AREA or SAME
SORT-MERGE AREA clause. File-names associated with the
GIVING phrase can not be specified in the same SAME clause.
-
If the GIVING phrase is
specified and the file referenced by file-name-3 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 larger than the
largest record described for file-name-3. If the file referenced by
file-name-3 contains fixed length records, the size of the records contained
in the file referenced by file-name-1 must not be larger than the largest
record described for the file referenced by file-name-3.
If the data descriptions of
the elementary items that make up these records are not identical, it is
the programmer's responsibility to describe the corresponding records in
such a manner as to cause equal amounts of character positions to be
allocated for the corresponding records.
-
If the
USING phrase is specified and the file referenced by file-name-1
contains variable length records, the size of the records contained in the
file
referenced by file-name-2 must not be less than the smallest record nor
larger 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 file referenced by file-name-2 must not be larger
than the largest record described for the file referenced by file-name-1.
- Procedure-name-1 represents the name of an input procedure.
Procedure-name-3 represents the name of an output procedure.
- Procedure-name-1, procedure-name-2, procedure-name-3 and
procedure-name-4 must be section-names.
This restriction is removed.
- 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.
Format 2
-
Data-name-2 can be qualified
and must have an OCCURS clause in the data description entry.
-
The data item referenced by
data-name-1 must be the same as the data item referenced by data-name-2, or
an entry subordinate to the data item referenced by data-name-2.
-
Unless data-name-1 and
data-name-2 are the same, the data item referenced by data-name-1 must not
be described by an entry containing an
OCCURS clause. The data item referenced by data-name-1 must not be
subordinate to an entry containing an OCCURS clause that is also subordinate
to data-name-2.
-
The KEY phrase can be omitted
only if the description of the table referenced by data-name-2 contains a
KEY phrase.
-
If data-name-2 references a
data item subordinate to a data item that contains an OCCURS clause, an
index-name must be associated with each data item containing an OCCURS
clause to which the data item referenced by data-name-2 is subordinate.
General Rules
All Formats
- The words ASCENDING and DESCENDING are transitive across all occurrences
of data-name-1 until another word ASCENDING or DESCENDING is encountered.
- The data items referenced by the specifications of data-name-1 are the
key data items which determine the order in which records are returned from
the file referenced by file-name-1 or the order in which the
table elements are stored after
sorting takes place. The order of significance of the keys is the order
in which they are specified in the
SORT statement, without regard to their association with
ASCENDING or
DESCENDING phrases.
- If the
DUPLICATES phrase is specified and the contents of all the key data
items associated with one data record or table element are equal to the
contents of the corresponding key data items associated with one or more
other data records or table elements, the order of return of these records
is:
- The order of the associated input files as specified in the SORT
statement, or by means of a run-time switch. Within a given input file the
order is that in which the records are accessed from that file.
- The order in which these records are released by an input procedure,
when an input procedure is specified.
- The relative order of the contents of these table elements before
sorting takes place.
- If the DUPLICATES phrase is not specified and the contents of all the
key data items associated with one data record or table element are equal to
the contents of the corresponding key data items associated with one or more
other data records or table elements, the order of return of these records
or the relative order of the contents of these table elements is undefined.
- 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 SORT statement in the following order of precedence:
- First, the collating sequence established by the
COLLATING SEQUENCE phrase, if specified, in the SORT statement.
- Second, the collating sequence established as the program collating
sequence.
Format 1
- The
SORT statement releases all the records in the file referenced by
file-name-2 or released by an input procedure to the file referenced by
file-name-1, and returns them to an output procedure, or to the file
referenced by file-name-3, in an order determined by the
ASCENDING and
DESCENDING phrases and the values of the data items referenced by the
specifications of data-name-1.
- To determine the relative order in which two records returned from the
file referenced by file-name-1, the contents of corresponding key data items
are compared according to the rules for comparison of operands in a relation
condition, starting with the most significant key data item:
- If the contents of the corresponding key data items are not equal and
the key is associated with the ASCENDING phrase, the record containing the
key data item with the lower value is returned first.
- If the contents of the corresponding key data items are not equal and
the key is associated with the DESCENDING phrase, the record containing
the key data item with the higher value is returned first.
- If the contents of the corresponding key data items are equal, the
determination is made on the contents of the next most significant key
data item.
- The execution of the SORT statement consists of three distinct phases as
follows:
- Records are made available to the file referenced by file-name-1. This
is achieved either by the execution of RELEASE statements in the input
procedure or by the implicit execution of READ statements for file-name-2.
When this phase commences, the file referenced by file-name-2 must not be
in the open mode. When this phase terminates, the file referenced by
file-name-2 is not in the open mode.
- The file referenced by file-name-1 is sequenced. No processing of the
files referenced by file-name-2 and file-name-3 takes place during this
phase.
- The records of the file referenced by file-name-1 are made available
in sorted order. The so
rted records are either written to the file referenced by
file-name-3, or, by the execution of a RETURN statement, are made
available for processing by the output procedure. When this phase
commences, the file referenced by file-name-3 must not be in the open
mode. When this phase terminates, the file referenced by file-name-3 is
not in the open mode.
- The input procedure can consist of any procedure needed to select,
modify or copy the records that are made available one at a time by the
RELEASE statement to the file referenced by file-name-1. The range includes
all statements that are executed as a result of a transfer of control by
CALL, EXIT without the optional PROGRAM phrase, GO TO and PERFORM statements
in the range of the input procedure. The range of the input procedure must
not cause the execution of any MERGE, RETURN or SORT statement.
- If an input procedure is specified, control is passed to the input
procedure before the file referenced by file-name-1 is sequenced by the SORT
statement. The compiler inserts a return mechanism at the end of the last
statement in the input procedure and when control passes the last statement
in the input procedure, the records that have been released to the file
referenced by file-name-1 are sorted.
- If the USING phrase is specified, all the records in the file(s)
referenced by file-name-2 are transferred to the file referenced by
file-name-1. For each of the files referenced by file-name-2 the execution
of the SORT 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 and the WITH LOCK phrases had been
executed
.
- The logical records are obtained and released to the sort operation.
Each record is obtained as if a READ statement with the NEXT and AT END
phrases had been executed. If the file referenced by file-name-1 contains
fixed length records, any record in the file referenced by file-name-2
containing fewer character positions than that specified for file-name-1
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. 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 contents of the data item
referenced by a RECORD VARYING DEPENDING ON or OCCURS DEPENDING ON clause
specified in the File Description entry for file-name-1.
- The processing of the file is terminated. The termination is performed
as if a CLOSE statement without optional phrases had been executed. This
termination is performed before the file referenced by file-name-1 is
sequenced by the SORT statement.
For a relative file, the content of the Relative Key data item is
undefined after the execution of a
SORT statement if file-name-2 is not referenced in the
GIVING phrase.
These implicit functions are performed such that any associated USE
AFTER EXCEPTION procedures are executed; however, the execution of such a
USE procedure must not cause the execution of any statement manipulating
the file referenced by file-name-2 or accessing the record area
associated with file-name-2.
The value of the data item referenced by a RECORD VARYING DEPENDING ON
clause specified in the File Description entry for file-name-2 is
undefined upon completion of the SORT 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 sorted order from the file referenced by file-name-1.
The range includes all statements that are executed as a result of a
transfer of control by CALL, EXIT without the optional PROGRAM phrase, GO TO
and PERFORM statements in the range of the output procedure, as well as all
statements in the Declarative procedures that are executed as a result of
the execution of statements in the range of the output procedure. The range
of the input procedure must not cause the execution of any MERGE, RELEASE or
SORT statement.
- If an output procedure is specified, control passes to it after the file
referenced by file-name-1 has been sequenced by the SORT statement. The
compiler inserts a return mechanism at the end of the last statement in the
output procedure and when control passes the last statement in the output
procedure, the return mechanism provides for termination of the sort and
then passes control to the next executable statement after the
SORT statement. Before entering the output procedure, the sort
procedure reaches a point at which it can select the next record in sorted
order when requested. The RETURN statements in the output procedure are the
requests for the next record.
- If the
GIVING phrase is specified, all the sorted records are written on the
file referenced by file-name-3 as the implied output procedure for the SORT
statement. For each of the files referenced by file-name-3, the execution of
the SORT 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. This
initiation is performed after the execution of any input procedure.
- The logical records are returned and written onto the file. The
records are written as if a WRITE statement without any optional phrases
had been executed. If the file referenced by file-name-3 is described with
fixed-length records, any record in the file referenced by file-name-1
containing fewer character positions than that specified for file-name-3
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-3. If the file referenced by file-name-3
is described with variable-length records,the size of any record written
to file-name-3 is the size of that record when it was read from
file-name-1, regardless of the contents of the data item referenced by a
RECORD VARYING DEPENDING ON or OCCURS DEPENDING ON clause specified in the
File Description entry for file-name-3.
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 a SORT 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 procedures are executed; however, the execution of such a
USE procedure must not cause the execution of any statement manipulating
the file referenced by file-name-3 or accessing the record area
associated with file-name-3. On the first attempt to write beyond the
externally-defined boundaries of a file, the USE AFTER EXCEPTION
procedure, if any, associated with the file is executed; if control is
returned as specified by the rules of the USE statement, no additional
implicit write operations are executed for that file and the processing
of the file is terminated as specified in this part.
The value of the data item referenced by a RECORDING VARYING DEPENDING
ON clause specified in the File Description entry for file-name-1 is
undefined upon completion of the SORT statement for which the
GIVING phrase is specified.
- Segmentation, as defined in the chapter Segmentation in your
Language Reference - Additional Topics, can be applied to
programs containing the SORT statement. However, the following restrictions
apply:
- If a
SORT statement appears in a section that is not in an independent
segment, then any input procedures or output procedures referenced by that
SORT statement must appear:
- Totally within non-independent segments, or
- Wholly contained in a single independent segment.
- If a SORT statement appears in an independent segment, then any input
procedures or output procedures referenced by that SORT statement must be
contained:
- Totally within non-independent segments, or
- Wholly within the same independent segment as that SORT statement.
-
The SORT-RETURN special
register is available to SORT programs. It contains a return code of 0
(successful) or 16 (unsuccessful) at the completion of a sort operation. You
can set the
SORT-RETURN special
register to 16 in an error declarative or input/output procedure to
terminate a sort operation before all records are processed. The operation
is terminated on the next RETURN or RELEASE statement.
Format 2
-
The
SORT statement sorts the table referenced by data-name-2 and presents
the sorted table in data-name-2 either in the order determined by the
ASCENDING or
DESCENDING phrases, if specified, or in the order determined by the
KEY phrase associated with data-name-2.
-
To determine the relative order
in which the table elements are stored after sorting, the contents of the
corresponding key data items are compared according to the rules for
comparison of operands in a relation condition, starting with the most
significant key data item.
- If the contents of the corresponding key data items are not equal and
the key is associated with the ASCENDING phrase, the table element
containing the key data item with the lower value has the lowest
occurrence number.
- If the contents of the corresponding key data items are not equal and
the key is associated with the DESCENDING phrase, the table element
containing the key data item with the higher value has the lowest
occurrence number.
- If the contents of the corresponding key data items are equal, the
determination is based on the contents of the next most significant key
data item.
-
The number of occurrences of
table elements referenced by data-name-2 is determined by the rules in the
OCCURS clause.
-
If data-name-2 references a
data item which is subordinate to a data item which contains an OCCURS
clause, the first or only index-name associated with each such superordinate
table must be set to the desired occurrence number before the SORT statement
is executed.
-
If the KEY phrase is not
specified, the sequence is determined by the KEY phrase in the Data
Description entry of the table referenced by data-name-2.
-
If the KEY phrase is specified,
it overrides any KEY phrase specified in the Data Description entry of the
table referenced by data-name-2.
-
If the key phrase is specified
but data-name-1 is omitted, the data item referenced by data-name-2 is the
key data item.
-
The
sorted table elements of the table referenced by data-name-2 are placed
in the table referenced by data-name-2.
-
The COLLATING SEQUENCE phrase
is treated as documentary only.
The
START statement provides a basis for logical positioning within a
relative or indexed file for subsequent retrieval of records. This statement
is not available for files with sequential organization.
General Formats
Format 1 (Relative Files)
Format 2 (Indexed Files)
Note that the required relational characters ">", " <",
">=", "<=" and "=" are not underlined to
avoid confusion with other symbols, such as ">"
(greater than or equal to).
Syntax Rules
All Formats (Relative and Indexed Files)
- File-name-1 must be the name of a relative or indexed file.
- File-name-1 must be the name of a file with sequential or dynamic
access.
- Data-name-1 can be qualified.
- The INVALID KEY phrase must be specified if no applicable USE procedure
is specified for file-name-1.
This rule is not enforced.
Format 1 (Relative Files)
- If the
KEY phrase is specified, data-name-1 must be the data item specified in
the RELATIVE KEY phrase of the associated file control entry.
Format 2 (Indexed Files)
- If the KEY phrase is specified, data-name-1 can reference a data item
specified as a record key associated with file-name-1. It can also reference
any data item of category alphanumeric, subordinate to the data item
specified as a
record key associated with file-name-1, whose leftmost character
position corresponds to the leftmost character position of that record key
data item.
-
Split-key-name-1 can reference
one or more data items, and is specified as a record key associated with
file-name-1.
-
WITH SIZE specifies the number
of characters in the key to be used in the positioning process.
-
Identifier-1 must be the name
of an elementary integer data item when used with the
WITH SIZE phrase.
General Rules
All Formats (All Files)
- File-name-1 must be open in the INPUT or I/O mode at the time that the
START statement is executed. (See the section The OPEN Statement
earlier in this chapter.)
- If the KEY phrase is not specified, the relational operation IS EQUAL TO
is implied.
- Execution of the START statement causes the value of the
FILE STATUS data item, if any, associated with file-name-1 to be
updated. (See the section I/O Status earlier in this chapter.)
-
The START statement never
acquires, detects or releases recordlocks.
Format 1 (Relative Files)
- The type of comparison specified by the relational operator in the
KEY phrase occurs between a key associated with a record in the file
referenced by file-name-1 and a data item as specified in General Rule 6.
-
If the relational operator
specifies that the key must be equal to, greater than, or greater than or
equal to the data item, then
the file
position indicator is positioned to the
first logical record currently existing in the file whose key
satisfies the comparison.
-
If the relational operator
specifies that the key must be less than, or less than or equal to the
data item, then the file position indicator is positioned to the l
ast logical record currently existing in the file whose key satisfies
the comparison.
- If the comparison is not satisfied by any record in the file, an
INVALID KEY condition exists. The execution of the
START statement will be unsuccessful, and the position of the file
position indicator will be undefined. (See the section The INVALID KEY
Condition in this chapter.)
- The comparison described in General Rule 5 uses the data item referenced
by the RELATIVE KEY clause associated with file-name-1. A RELATIVE KEY
clause must be associated with file-name-1.
Format 2 (Indexed Files)
- The type of comparison specified by the relational operator in the KEY
phrase occurs between a key associated with a record in the file referenced
by file-name-1 and a data item as specified in General Rule 8. If
file-name-1 references an indexed file and the operands are of unequal size,
the comparison proceeds as though the longer one were truncated on the right
so that its length is equal to that of the shorter. All other nonnumeric
comparison rules apply except that the presence of the
PROGRAM COLLATING SEQUENCE clause will have no effect on the
comparison. (See the section Comparison Of Nonnumeric Operands
earlier in this chapter.)
-
If the relational operator
specifies that the key must be equal to, greater than, or greater than or
equal to the data item, then
the file
position indicator is positioned to the
first logical record currently existing in the file whose key
satisfies the comparison.
-
If the relational operator
specifies that the key must be less than, or less than or equal to the
data item, then the file
position indicator is positioned to the
last logical record currently existing in the file whose key
satisfies the comparison. If this key has duplicate entries, the file
position indicator is positioned to the last of these entries.
- If the comparison is not satisfied by any record in the file, an
INVALID KEY condition exists, the execution of the START statement is
unsuccessful, and the position of the file position indicator is
undefined. (See the section The INVALID KEY Condition in this
chapter.)
- If the KEY phrase is specified, the comparison described in General Rule
7 uses the data item referenced by data-name.
- If the K
EY phrase is not specified, the comparison described in General Rule 7
uses the data item referenced in the RECORD KEY clause associated with
file-name-1.
- After successful execution of the
START statement, a key of
reference is established and used in subsequent Format 3 READ
statements as follows (see the section The READ Statement earlier in
this chapter):
- If the KEY phrase is not specified, the prime record key specified for
file-name-1 becomes the key of reference.
- If the KEY phrase is specified, and data-name-1
or split-key-name-1
is specified as a record key for file-name-1, that record key becomes
the key of reference.
- If the KEY phrase is specified, and data-name-1
or split-key-name-1
is not specified as a record key for file-name-1, the record key whose
leftmost character position corresponds to the leftmost character
position of the data item specified by data-name-1
or split-key-name-1
becomes the key of reference.
- If execution of the START statement is not successful, the key of
reference is undefined.
The STOP statement causes a permanent or temporary suspension of the
execution of the object program.
The
STOP literal 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 within 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 Stop literal format is explicitly excluded
from the X/Open COBOL language definitions and should not be used in an
X/Open COBOL conforming source program.
General Format
Format 1
Format 2
Syntax Rules
- Literal-1 must not be a figurative constant that begins with the word
ALL.
- If literal-1 is numeric, then it must be an unsigned integer.
A signed integer is allowed.
-
Integer-1 may be signed.
- If a STOP RUN statement appears in a consecutive sequence of imperative
statements within a sentence, it must appear as the last statement in that
sequence.
This rule is not enforced,
although any statements in the sentence that follow the STOP RUN statement
will not be executed.
-
GIVING and RETURNING are
equivalent.
-
Identifier-1 must be no larger
than 8 bytes in size.
General Rules
- If the RUN phrase is specified, execution of the run unit ceases and
control is transferred to the operating system.
- During the execution of a STOP RUN statement, an implicit CLOSE
statement without any optional phrases is executed for each file that is in
the open mode in the run unit. Any USE procedures associated with any of
these files are not executed.
- If the run unit has been accessing messages, the STOP RUN statement
causes the message control system (MCS) to eliminate form the queue any
message partially received by that unit. Any portion of a message
transferred from the run unit via a send statement, but not terminated by an
EMI or EGI, is purged from the system.
-
Execution of a STOP RUN
statement causes a return value to be set in the system area generally
available for non-COBOL programs to return a value. If the operating system
supports the facility of returning a value from a program that is run to the
operating system environment then it will return the value from the system
area.
If the GIVING phrase is not
specified then the object program operates as if the system area were
declared as a COBOL numeric data item with USAGE COMP-5 and with a size
determined by the operating environment external to the COBOL system and as
if a MOVE statement had been executed with the RETURN-CODE as the sending
item and the system area as the receiving item. (See the section Special
Registers in the chapter Concepts of the COBOL Language for
details of RETURN-CODE.)
If the GIVING identifier-1
phrase is specified, identifier-1 must describe the same number of
character positions as is required to hold the return value in the system
area and must be of the type and usage that is expected by the operating
system. Typically identifier-1 will need to be declared with an explicit or
implicit PIC S9 (9) USAGE COMP-5. The object program operates as if a
MOVE statement had been executed with identifier-1 as the sending item and
the system area as the receiving item.
IF the GIVING integer-1 phrase
is specified, integer-1 must not be larger than the value that can be held
in the system area. The object program operates as if a MOVE statement had
been executed with integer-1 as the sending item and the system area as the
receiving item.
- If STOP literal-1 is specified, the execution of the run unit is
suspended and literal-1 is communicated to the operator. Continuation of the
execution of the run unit begins with the next executable statement when the
operator presses the ENTER key or its equivalent.
The STRING statement provides juxtaposition of the partial or complete
contents of two or more data items into a single data item.
General Format
Syntax Rules
- Each literal can be any figurative constant without the optional word
ALL.
- All literals must be described as nonnumeric literals, and all
identifiers, except identifier-4, must be described implicitly or explicitly
as USAGE IS DISPLAY.
- Identifier-3 must represent an elementary alphanumeric data item without
editing symbols or the JUSTIFIED clause.
- Identifier-4 must represent an elementary numeric integer data item of
sufficient size to contain a value equal to the size plus 1 of the area
referenced by identifier-3. The "P" can not be used in the PICTURE
character-string of identifier-4.
- Where identifier-1 or identifier-2 is an elementary numeric data item,
it must be described as an integer without the symbol "P" in its
PICTURE character-string.
-
Identifier-3 must not be
reference modified.
-
Identifier-3 can be reference
modified.
General Rules
- Identifier-1, or literal-1, represents the sending item. Identifier-3
represents the receiving item.
- Literal-2, identifier-2, indicate the character(s) delimiting the move.
If the SIZE phrase is used, the complete data item defined by identifier-1,
or literal-1, is moved. When a figurative constant is used as the delimiter,
it stands for a single character nonnumeric literal.
- When a figurative constant is specified as literal-1, or literal-2, it
refers to an implicit one-character data item whose usage is DISPLAY.
- When the STRING statement is executed, the transfer of data is governed
by the following rules:
- Those characters from literal-1, or from the contents of the data item
referenced by identifier-1, are transferred to the contents of
identifier-3 in accordance with the rules for alphanumeric to alphanumeric
moves, except that no space filling will be provided. (See the section
The MOVE Statement earlier in this chapter.)
- If the DELIMITED phrase is specified without the SIZE phrase, the
contents of the data item referenced by identifier-1, or the value of
literal-1, is transferred to the receiving data item in the sequence
specified in the STRING statement beginning with the leftmost character
and continuing from left to right until the end of the data item is
reached, or until the character(s) specified by literal-2, or by the
contents of identifier-2 are encountered. The character(s) specified by
literal-2, or by the data item referenced by identifier-2 are not
transferred.
- If the
DELIMITED phrase is specified with the SIZE phrase, the entire
contents of literal-1, or the contents of the data item referenced by
identifier-1, are transferred, in the sequence specified in the STRING
statement, to the data item referenced by identifier-3 until all data has
been transferred or the end of the data item referenced by identifier-3
has been reached.
- If the
POINTER phrase is specified, identifier-4 is explicitly available to
the programmer, who is then responsible for setting its initial value. The
initial value must not be less than one.
- If the
POINTER phrase is not specified, the following General Rules apply as
if the user had specified identifier-4 with an initial value of 1.
- When characters are transferred to the data item referenced by
identifier-3, the moves behave as though the characters were moved one at a
time from the source into the character position of the data item referenced
by identifier-3 designated by the value associated with identifier-4, and
then identifier-4 was increased by one prior to the move of the next
character. The value associated with identifier-4 is changed during
execution of the STRING statement only by the behavior specified above.
- At the end of execution of the STRING statement, only the portion of the
data item referenced by identifier-3 that was referenced during the
execution of the STRING statement is changed. All other portions of the data
item referenced by identifier-3 will contain data that was present before
this execution of the STRING statement.
- Before each move of a character to the data item referenced by
identifier-3, if the value associated with the data item referenced by
identifier-4 is either less than one or exceeds the number of character
positions in the data item referenced by identifier-3, no (further) data is
transferred to the data item referenced by identifier-3,
and the NOT ON OVERFLOW
phrase, if specified, is ignored
and control is transferred to the end of the STRING statement or, if the
ON OVERFLOW phrase is specified, to imperative- statement-1. If control is
transferred to imperative- statement-1, execution continues according to
the rules for each statement specified in imperative-statement-1. If a
procedure 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-1, control is transferred to the end of the STRING
statement.
-
If, at the time of execution of
a STRING statement with the NOT ON
OVERFLOW phrase, the conditions described in General Rule 9 are not
encountered, after completion of the transfer of data according to the other
general rules, the ON OVERFLOW phrase, if specified, is ignored and control
is transferred to the end of the STRING statement or, if the NOT ON OVERFLOW
phrase is specified, to imperative- statement-2. If control is transferred
to imperative- statement-2, execution continues according to the rules for
each statement specified in imperative-statement-2. If a procedure 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 STRING
statement.
-
The END-STRING phrase delimits
the scope of the STRING statement. (See the section Explicit And
Implicit Scope Terminators in the chapter Concepts of the COBOL
Language.)
The SUBTRACT statement is used to subtract one, or the sum of two or more,
numeric data items from one or more items, and set the values of one or more
items equal to the results.
General Formats
Format 1
Format 2
Format 3
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, and in Format
3 each identifier must refer to a group item.
- The
composite of
operands must not contain more than 18 digits. (See the section The
Arithmetic Statements earlier in this chapter.)
- In Format 1 the composite of operands is determined by using all of
the operands in a given statement.
- In Format 2 the composite of operands is determined by using all of
the operands in a given statement excluding the data items that follow the
word GIVING.
- In Format 3 the composite operands is determined separately for each
pair of corresponding data items.
Formats 1 and 2
- Each literal must be a numeric literal.
-
Floating-point data items and
literals can be used anywhere numeric data items and literals can be
specified.
Format 3
- CORR is an abbreviation for CORRESPONDING.
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.
-
The COBOL system ensures
enough places are carried so as not to lose significant digits during
execution.
Format 1
- All literals or identifiers preceding the word FROM are added together
and this total is subtracted from the current value of identifier-2 storing
the result immediately into identifier-2, and repeating this process
respectively for each operand following the word FROM.
Format 2
- In Format 2, all literals or identifiers preceding the word FROM are
added together, the sum is subtracted from literal-2 or identifier-2 and the
result of the subtraction is stored as the new value of each data item
referenced by identifier-3.
Format 3
- If Format 3 is used, data items in identifier-1 are subtracted from and
stored into corresponding data items in identifier-2.
The TRANSFORM statement is used to alter characters according to a
transformation rule.
General Format
Syntax Rules
- Identifier-3 can be any elementary item except a numeric item with USAGE
other than DISPLAY, or a group item.
- Identifier-1 and identifier-2 should be elementary alphabetic or
alphanumeric items.
- Nonnumeric-literal-2 or identifier-2 must be either one character long
or the same length as nonnumeric-literal-1 or identifier-1.
General Rules
- The use of figurative-constant-1 and/or figurative-constant-2 is
equivalent to the use of a single-character nonnumeric- literal with the
same value.
- If either identifier-1 or identifier-2 references the same computer
storage area as identifier-3, the result of the TRANSFORM is undefined. (See
the section The REDEFINES Clause earlier in this chapter.)
- If characters are repeated in nonnumeric-literal-1 or identifier-1, then
the result of the TRANSFORM operation is undefined.
- Execution of the TRANSFORM statement scans identifier-3 for occurrences
of individual characters from identifier-1 or nonnumeric-literal-1. When a
match is found, the corresponding character (or the single character of a
one-character field) from identifier-2 or nonnumeric-literal-2 is
substituted into that character position in identifier-3. The correspondence
between identifier-1 or nonnumeric- literal-1 and identifier-2 or
nonnumeric-literal-2 is by occurrence number of the character within the
data item (starting from the left).
The
UNLOCK statement releases all
record locks held by the run unit on a named file.
General Format
Syntax Rule
File-name must occur in the SELECT statement of the FILE CONTROL entry.
General Rules
- The file referenced by file-name must already be opened with the OPEN
statement.
- The UNLOCK statement releases all record locks held by the run unit on a
named file.
The UNSTRING statement causes contiguous data in a sending field to be
separated and placed into multiple receiving fields.
General Format
Syntax Rules
- Each literal must be a nonnumeric literal. In addition, each literal can
be any figurative constant without the optional word ALL.
- Identifier-1, identifier-2, identifier-3, and identifier-5 must be
described, implicitly or explicitly, as an alphanumeric data-item.
- Identifier-4 can be described as either alphabetic (except that the
symbol "B" can not be used in the PICTURE character-string),
alphanumeric, or numeric (except that the symbol "P" can not be
used in the PICTURE character-string), and must be described as USAGE IS
DISPLAY.
-
Syntax Rules 2 and 3 do not
apply. Instead, the following rules apply:
- Identifier-1 must be alphanumeric
- Identifier-2 and identifier-3 must be USAGE DISPLAY and must not be
edited
- Identifier-5 must be USAGE DISPLAY
- Identifier-4 can be USAGE DISPLAY
- Identifier-4 can have any USAGE that defines a numeric data item as
long as the data results in a valid MOVE operation.
-
Identifier-4 must not be
defined as a floating-point item.
- Identifier-6 and identifier-8 must reference integer data items, (except
that the symbol " P" can not be used in the PICTURE
character-string).
- Identifier-1 must be described as an elementary numeric integer data
item of sufficient size to contain a value equal to 1 plus the size of the
data item referenced by identifier-1. The symbol "P" can not be
used in the PICTURE character string of identifier-7.
- No identifier can name a level 88 entry.
- The DELIMITER IN phrase and the COUNT IN phrase can be specified only if
the DELIMITED BY phrase is specified.
-
The source of an UNSTRING
operation can be reference modified.
General Rules
- All references to identifier-2, literal-1, apply equally to
identifier-3, literal-2, respectively and all recursions thereof.
- Identifier-1 represents the sending area.
- Identifier-4 represents the data receiving area. Identifier-5 represents
the receiving area for delimiters.
- Literal-1 or the data item referenced by identifier-2 specifies a
delimiter.
- The data item referenced by identifier-6 represents the count of the
number of characters within the data item referenced by identifier-1
isolated by the delimiters for the move to the data item referenced by
identifier-4. This value does not include a count of the delimiter
character(s).
- The data item referenced by identifier-7 contains a value that indicates
a relative character position within the area defined by identifier-1.
- The data item referenced by identifier-8 is a counter that records the
number of data items acted upon during the execution of an UNSTRING
statement.
- When a figurative constant is used as the delimiter, it stands for a
single character nonnumeric literal.
When the ALL phrase is specified, one occurrence or two or more
contiguous occurrences of literal-1 (figurative constant or not) or the
contents of the data item referenced by identifier-2 are treated as if it
were only one occurrence, and this occurrence is moved to the receiving
data item according to the rules in General Rule 13d.
- When any examination encounters two contiguous delimiters, the current
receiving area is either space or zero filled according to the description
of the receiving area.
- Literal-1 or the contents of the data item referenced by identifier-2
can contain any character in the computer's character set.
- Each literal-1 or the data item referenced by identifier-2 represents
one delimiter. When a delimiter contains two or more characters, all of the
characters must be present in contiguous positions of the sending item and
in the order given, to be recognized as a delimiter.
- When two or more delimiters are specified in the DELIMITED BY phrase, an
"OR" condition exists between them. Each delimiter is compared to
the sending field. If a match occurs, the character(s) in the sending field
is considered to be a single delimiter. No character(s) in the sending field
can be considered a part of more than one delimiter.
Each delimiter is applied to the sending field in the sequence specified
in the UNSTRING statement.
- When the UNSTRING statement is initiated, the current receiving area is
the data item referenced by identifier-4. Data transferred from the data
item referenced by identifier-1 to the data item referenced by identifier-4
according to the following rules:
- If the
POINTER phrase is specified, the string of characters referenced by
identifier-1 is examined beginning with the relative character position
indicated by the contents of the data item referenced by identifier-7. If
the POINTER phrase is not specified, the string of characters is examined
beginning with the leftmost character position.
- If the DELIMITED BY phrase is specified, the examination proceeds left
to right until either a delimiter specified by the value of literal-1 or
the data item referenced by identifier-2 is encountered. (See General Rule
11.) If the DELIMITED BY phrase is not specified, the number of characters
examined is equal to the size of the current receiving area. However, if
the sign of the receiving item is defined as occupying a separate
character position, the number of characters examined is one less than the
size of the current receiving area.
If the end of the data item referenced by identifier-1 is encountered
before the delimiting condition is met, the examination terminates with
the last character examined.
- The characters thus examined (excluding the delimiting character(s),
if any) are treated as an elementary alphanumeric data item, and are moved
into the current receiving area according to the rules for the MOVE
statement. (See the section The MOVE Statement earlier in this
chapter.)
- If the DELIMITER IN phrase is specified, the delimiting character(s)
are treated as an elementary alphanumeric data item and are moved into the
data item referenced by identifier-5 according to the rules for the MOVE
statement. (See the section The MOVE Statement earlier in this
chapter.) If the delimiting condition is the end of the data item
referenced by identifier-1, then the data item referenced by identifier-5
is space-filled.
- If the COUNT IN phrase is specified, a value equal to the number of
characters thus examined (excluding the delimiter character(s) if any) is
moved into the area referenced by identifier-6 according to the rules for
an elementary move.
- If the DELIMITED BY phrase is specified the string of characters is
further examined beginning with the first character to the right of the
delimiter. If the DELIMITED BY phrase is not specified, the string of
characters is further examined beginning with the character to the right
of the last character transferred.
- After data is transferred to the data item referenced by identifier-4,
the current receiving area is the data item referenced by the next
recurrence of identifier-4. The behavior described in paragraph 13b.
through 13f. is repeated until either all the characters are exhausted in
the data item referenced by identifier-1, or until there are no more
receiving areas.
- The initialization of the contents of the data items associated with the
POINTER phrase or the
TALLYING phrase is the responsibility of the user.
- The contents of the data item referenced by identifier-7 will be
incremented by one for each character examined in the data item referenced
by identifier-1. When the execution of an UNSTRING statement with a POINTER
phrase is complete, the contents of the data item referenced by identifier-7
will contain a value equal to the initial value plus the number of
characters examined in the data item referenced by identifier-1.
- When the execution of an UNSTRING statement with a TALLYING phrase is
completed, the contents of the data item referenced by identifier-8 contains
a value equal to its initial value plus the number of data receiving items
acted upon.
- Either of the following situations causes an overflow condition:
- An UNSTRING is initiated, and the value in the data item referenced by
identifier-7 is less than 1 or greater than the size of the data item
referenced by identifier-1.
- If, during execution of an UNSTRING statement, all data receiving
areas have been acted upon, and the data item referenced by identifier-1
contains characters that have not been examined.
- When an overflow condition exists, the UNSTRING operation is terminated,
the NOT
ON OVERFLOW phrase, if specified, is ignored and
control is transferred to the end of the UNSTRING statement or, if the
ON OVERFLOW phrase is specified, to imperative-statement-1. If control is
transferred to imperative-statement-1, execution continues according to the
rules for each statement specified in imperative-statement-1. If a
procedure 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-1, control is transferred to the end of the UNSTRING
statement.
-
The END-UNSTRING phrase
delimits the scope of the UNSTRING statement. (See the section Explicit
And Implicit Scope Terminators in the chapter Concepts of the COBOL
Language.)
- If, at the time of execution of an UNSTRING statement, the conditions
described in General Rule 17 are not encountered, after completion of the
transfer of data according to the other general rules, the ON
OVERFLOW phrase, if specified, is ignored and control is transferred to
the end of the UNSTRING statement
or, if the NOT ON OVERFLOW
phrase is specified, to imperative-statement-2. If control is transferred
to imperative- statement-2, execution continues according to the rules for
each statement specified in imperative-statement-2. If a procedure
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 UNSTRING
statement.
- The evaluation of subscription and indexing for the identifiers is as
follows:
- Any subscripting or indexing associated with identifier-1,
identifier-7, or identifier-8 is evaluated only once, immediately before
any data is transferred as the result of the execution of the UNSTRING
statement.
- Any subscripting or indexing associated with identifier-2, -3, -4, -5,
or -6 is evaluated immediately before the transfer of data into the
respective data item.
-
22..Any subscripting associated
with the DELIMITED BY identifier, the INTO identifier, the DELIMITER IN
identifier, or the COUNT IN identifier is evaluated once, immediately before
the examination of the sending fields for the delimiter.
- If identifier-1, -2 or -3, occupies the same storage area as
identifier-4, -5, -6, -7 or -8, or if identifier-4, -5 or -6 , occupies the
same storage area as identifier-7 or -8, or if identifier-7 and identifier-8
occupy the same storage area, the result of the execution of this statement
is undefined, even if they are defined by the same data description entry.
The U
SE statement specifies procedures for input-output error handling, that
are in addition to the standard procedures provided by the input-output
control system.
General Formats
Format 1 (Sequential , Relative and Indexed Files)
Format 2 (Record Sequential Files)
Format 3 (Relative And Indexed Files)
Syntax Rules
All Formats (All Files)
- Format 1 is the
ERROR declarative.
Formats 2 and 3 are the
LABEL declarative.
- A
USE statement, when present, must immediately follow a section header
in the Declaratives Section and must be followed by a period followed by a
space.
- The USE statement itself is never executed; it merely defines the
conditions calling for the execution of the
USE procedures.
- The files implicitly or explicitly referenced in a USE statement need
not all have the same organization or access.
Format 1 (Sequential, Relative and Indexed Files)
- The same file-name can appear in a different specific arrangement of the
format. Appearance of a file-name in a USE statement must not cause the
simultaneous request for execution of more than one USE procedure.
The same file-name must not
appear in more than one USE AFTER EXCEPTION statement within the same
Procedure Division.
- The words
ERROR and EXCEPTION are equivalent and can be used interchangeably.
Formats 2 and 3 (Record Sequential, Relative and Indexed
Files)
-
If both BEGINNING and ENDING
are omitted, the effect is as though both BEGINNING and ENDING had been
specified.
Format 2 (Record Sequential Files)
-
REEL and UNIT are treated as
equivalent.
-
If both FILE and REEL/UNIT are
omitted, the effect is as though both REEL or UNIT and FILE had been
specified.
-
Any one file-name and any one
OPEN mode can appear in only one declarative for each of the possible
combinations of BEGINNING/ENDING and FILE/REEL as shown below:
BEGINNING FILE
BEGINNING REEL/UNIT
ENDING FILE
ENDING REEL/UNIT
General Rules
All Formats (All Files)
- After execution of a USE procedure, control is returned to the invoking
routine.
- Within a USE procedure, there must not be any reference to any
non-declarative procedures. Conversely, in the non-declarative portion there
must be no reference to procedure-names that appear in the declarative
portion, except that PERFORM statements can refer to a
USE statement.
This restriction can be
ignored.
- Within a
USE procedure, there must be no execution of any statement that would
cause the execution of a USE procedure that had previously been invoked and
had not yet returned control to the invoking routine.
Format 1 (Sequential, Relative and Indexed Files)
- The designated procedures are executed by the input-output system after
completing the standard input-output error routine, or upon recognition of
the AT END condition, when the AT END phrase has not been specified in the
input-output statement.
-
When file-name-1 is specified
explicitly, no other USE statement applies to file-name-1.
- The GIVING phrase is documentary only.
Formats 2 and 3 (Record Sequential, Relative and Indexed
Files)
-
If the BEGINNING phrase is
specified explicitly or implicitly, the following actions are taken during
the execution of an applicable OPEN statement:
Open Mode |
Action |
INPUT |
Read header labels
Execute beginning declarative |
OUTPUT |
Execute beginning declarative
Write header labels |
I/O |
Read header labels
Execute beginning declarative
Write header labels |
EXTEND |
Read header labels
Execute beginning declaratives (trailer labels treated as header)
Write header labels |
-
If the ENDING phrase is
specified explicitly or implicitly, the following actions are taken during
the execution of an applicable CLOSE statement:
Open Mode |
Action |
INPUT |
Read trailer labels
Execute ending declarative |
OUTPUT |
Execute ending declarative
Write trailer labels |
I/O |
Read trailer labels
Execute ending declarative
Write trailer labels |
EXTEND |
Execute ending declaratives
Write trailer labels |
-
The statement GO TO
MORE-LABELS is treated as a simple jump to the start of the declarative
procedure in which it appears.
The
WRITE statement releases a logical record for an output or input-output
file. For sequential files it can also be used for vertical positioning of
lines within a logical page.
Although they are a part of the
standard COBOL definition, mnemonic names in the
ADVANCING phrase are explicitly excluded from the X/Open COBOL language
definitions and should not be used in X/Open COBOL source programs.
General Formats
Format 1 (Record
and Line
Sequential Files)
Format 2 (Record Sequential Files)
Format 3 (Record Sequential Files)
Format 4 (Relative and Indexed Files)
Directives and Run-time Switches
- 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.
- WRITE-LOCK - causes a WRITE statement to acquire a record lock when
multiple recording locking is used.
- FDCLEAR - causes the contents of the record area to be predictable
after a WRITE statement.
- The following run-time switches may impact the semantics described in
this section.
- N - controls the insertion of null characters before control
characters when writing line sequential records.
- T - controls the insertion of tab characters when writing line
sequential records.
Syntax Rules
All Formats (All Files)
-
If identifier-1 is a
function-identifier, it must reference an alpha-numeric function. When
identifier-1 is not a function-identifier, record-name and identifier-1 must
not reference the same storage area.
- Record-name is the name of a logical record in the File Section of the
Data Division and can be qualified.
-
Record-name can define a
floating-point item.
-
Identifier-1 can be defined
as a floating-point item.
Format 1 (Record Sequential Files)
-
When the mnemonic-name
associated with
TAB is specified the result is to cause the paper to throw to the
standard vertical tabulation position. A user-defined mnemonic-name can be
used instead of TAB if it is associated in the SPECIAL-NAMES paragraph. (See
the section The SPECIAL-NAMES Paragraph.)
- When identifier-2 is used in the
ADVANCING phrase, it must be the name of an elementary integer data
item.
- Integer, or the value of the data item referenced by identifier-2, can
be zero.
-
Integer can be signed.
- If the
END-OF-PAGE phrase is specified, the linage clause must be specified in
the file description entry for the associated file.
- The words END-OF-PAGE and
EOP are equivalent.
- The ADVANCING mnemonic-name phrase cannot be specified when writing a
record to a file whose file description entry contains the
LINAGE clause.
-
The phrases ADVANCING PAGE and
END-OF-PAGE must not both be specified in a single WRITE statement.
This restriction can be
ignored.
Alternatively, function-name
can itself be used instead of an associated mnemonic name.
Format 2 (Record Sequential Files)
-
This format cannot be specified
when writing a record to a file whose file description entry contains the
LINAGE clause.
-
If this format of the
WRITE statement is used for writing to a given file, then every WRITE
statement used for that file should be in this format.
-
In the
AFTER POSITIONING phrase, identifier-2 must be defined as a
single-character alphanumeric item. See General Rule 18 for itspossible
values.
Format 4 (Relative And Indexed Files)
- The INVALID KEY phrase must be specified if an applicable USE procedure
is not specified for the associated file.
This rule is not enforced.
General Rules
All Formats (All Files)
- The results of the execution of the
WRITE statement with the FROM phrase is equivalent to the execution of:
- The statement:
MOVE identifier-1 TO record-name
according to the rules specified for the MOVE statement, followed by:
- The same WRITE statement without the
FROM phrase.
The contents of the record area prior to the execution of the implicit
MOVE statement have no effect on the execution of this WRITE statement.
After execution of the WRITE statement is complete, the information in
the area referenced by identifier-1 is available, even though the
information in the area referenced by record-name can not be. (See General
Rule 13.)
- The file position indicator is unaffected by the execution of a WRITE
statement.
- The execution of the WRITE statement causes the value of the FILE STATUS
data item, if any, associated with the file to be updated. (See the section
I/O Status earlier in this chapter.)
- The maximum record size for a file is established at the time the file
is created and must not subsequently be changed.
- The number of character positions on a mass storage device to store a
logical record in a file may or may not be equal to the number of character
positions defined by the logical description of that record in the program.
- The execution of the WRITE statement releases a logical record to the
operating system.
-
If the execution of the WRITE
statement is unsuccessful, the I/O status of the file-name associated with
record-name is updated and control is transferred according to the rules of
the USE statement following the execution of any USE AFTER EXCEPTION
procedure applicable to the file-name associated with record-name. (See the
section The USE Statement in this chapter.)
Format 1 (Record Sequential Files)
- If the logical end of the representation of the printed page is reached
during the execution of a
WRITE statement with the
END-OF-PAGE phrase, the imperative-statement specified in the
END-OF-PAGE phrase is executed. The logical end is specified in the LINAGE
clause associated with record-name.
- An end-of-page condition is reached whenever the execution of a given
WRITE statement with the END-OF-PAGE phrase occurs, when the execution of
such a WRITE statement causes the LINAGE-COUNTER to equal or exceed the
value specified by integer-2 or the data item referenced by data-name-2 of
the
LINAGE clause, if specified. In this case, the WRITE statement is
executed and then the imperative statement in the END-OF-PAGE phrase is
executed.
An automatic page overflow condition is reached whenever the execution
of a given WRITE statement (with or without an END-OF-PAGE phrase) cannot
be fully accommodated within the current page body.
This occurs when a WRITE statement, if executed, would cause the
LINAGE-COUNTER to exceed the value specified by integer-1 or the data item
referenced by data-name-1 of the LINAGE clause. In this case, the record is
presented on the logical page before or after (depending on the phrase
used) the device is repositioned to the first line that can be written on
the next logical page as specified in the LINAGE clause. The imperative
statement in the END-OF-PAGE clause, if specified, is executed after the
record is written and the device has been repositioned.
If integer-2 or data-name-2 of the LINAGE clause is not specified, no
end-of-page condition distinct from the page overflow condition is
detected. In this case, the end-of-page condition and page overflow
condition occur simultaneously.
If integer-2 or data-name-2 of the LINAGE clause is specified, but the
execution of a given WRITE statement would cause LINAGE-COUNTER to
simultaneously exceed the value of both integer-2 or the data item
referenced by data-name-2 and integer-1 or the data item referenced by
data-name-1, then the operation proceeds as if integer-2 or data-name-2 had
not been specified.
Format 1 (Line Sequential Files)
-
If the
ADVANCING phrase is not used, automatic advancing of one line is
provided to act in accordance with the convention of your operating system
text editor (usually as if you had specified BEFORE ADVANCING 1 LINE).
-
When an attempt is made to
write beyond the externally defined boundaries of a
sequential file, an
exception condition exists and the contents of the record area are
unaffected. The following actions take place:
- The value of the
FILE STATUS data item, if any, of the associated file is set to a
value indicating a boundary violation. (See the section I/O Status
in this chapter.)
- If a USE
AFTER STANDARD EXCEPTION declarative is explicitly or implicitly
specified for the file, that declarative procedure will be executed.
- If a USE AFTER STANDARD EXCEPTION declarative is not explicitly or
implicitly specified for the file, the result will be undefined.
-
After the recognition of an
end-of-unit of an output file that is contained on more than one physical
reel/unit, the WRITE statement performs the following operations:
- The standard ending reel/unit procedure.
- The reel/unit swap.
- the standard beginning of reel/unit label procedure.
-
If you have a fixed length
record file, where records of different lengths are being redefined, you
need to be aware that the entire buffer area is written to the file. You
might, therefore, need to space-fill if the current record is shorter than
the previous one.
-
If, during the successful
execution of a
WRITE statement with the NOT END-OF-PAGE phrase, the end-of-page
condition does not occur, control is transferred to imperative-statement-2
after execution of the input-ouput operation.
Format 1 (Record
and Line
Sequential Files)
- Both the ADVANCING phrase and the
END-OF-PAGE phrase allow control of the vertical positioning of each
line on a representation of a printed page.
If the ADVANCING phrase is not used, automatic advancing is provided
when output is directed to a list-device (PRINTER or PRINTER-1), to act as
if the user had specified AFTER ADVANCING 1 LINE. If the
ADVANCING phrase is used, advancing is provided as follows:
- If identifier-2 is specified, the representation of the printed page
is advanced the number of lines equal to the current value associated with
identifier-2.
- If integer is specified, the representation of the printed page is
advanced in the number of lines equal to the value of integer.
- If mnemonic-name is specified, the representation of the printed page
is advanced as specified under the SPECIAL-NAMES paragraph.
- If the
BEFORE phrase is used, the line is presented before the
representation of the printed page is advanced according to rules a, b,
and c above.
- If the
AFTER phrase is used, the line is presented after the representation
of the printed page is advanced according to rules a, b, and c above.
- If PAGE is specified, the record is presented on the logical page
before or after (depending on the phrase used) the device is repositioned
to the next logical page. If the record to be written is associated with a
record sequential file whose file description entry contains a
LINAGE clause, the device is repositioned to the first line that can
be written on the next logical page as specified in the LINAGE clause.
- The phrases ADVANCING PAGE and
END-OF-PAGE must not both be specified in a single
WRITE statement.
Formats 1, 2, and 3 (Sequential Files)
- The associated file must be open in the OUTPUT or EXTEND mode at the
time of the execution of this statement. (See the section The OPEN
Statement in this chapter.)
- The logical record released by the execution of the WRITE statement is
no longer available in the record area unless the associated file is named
in a
SAME RECORD AREA clause or the execution of the WRITE statement was
unsuccessful due to a boundary violation.
The logical record is also available to the program as a record of other
files referenced in the SAME RECORD AREA clause as the associated output
file, as well as to the file associated with record-name.
Format 2 (Record Sequential Files)
-
When the
AFTER POSITIONING phrase is used in a
WRITE statement, the system will move a suitable character into the
first position of the record before it is written to the file. This first
character position must be reserved by the user for this purpose. If the
identifier-2 option is used, then the character moved into the output record
is simply the value held by identifier-2 and should be one of the following:
Identifier-2
|
Interpretation
|
(space) |
Single-spacing |
0 |
Double-spacing |
|
Triple-spacing |
+ |
Suppress spacing |
1-9 |
Skip to channel 1-9, respectively |
A, B, C |
Skip to channel 10, 11, 12, respectively |
V, W |
Pocket select 1 or 2 |
If the integer-1 option is used, then the character placed in the output
record is determined as follows:
Integer
|
Output Character
|
Interpretation
|
0 |
1 |
Skip to channel 1 |
1 |
(space) |
Single-space |
2 |
0 |
Double-spacing |
3 |
|
Triple-spacing |
-
The
END-OF-PAGE phrase, if specified, is documentary and as such is never
executed.
Format 3 (Record Sequential Files)
-
When an attempt is made to
write beyond the externally defined boundaries of a sequential file, an
INVALID KEY condition occurs. When the INVALID KEY condition is
recognized by the COBOL system, the execution of the
WRITE statement is unsuccessful; the contents of the record area are
unaffected, and the
FILE STATUS data item, if any, of the associated file is set to a value
indicating the cause of the condition. Execution of the program proceeds
according to the rules stated in The INVALID KEY Condition in this chapter
(see also the section I/O Status in this chapter).
Format 4 (Relative and Indexed Files)
- The associated file must be open in the OUTPUT, I/O or EXTEND mode at
the time of execution of this statement; an indexed file must not be open in
the
I/O mode with sequential access mode. (See the sections The
FILE-Control Entry and The OPEN Statement in this chapter.)
- The logical record released by the execution of the WRITE statement is
available in the record area only if the associated file is named in a SAME
RECORD AREA clause, or the execution of the WRITE statement is
unsuccessful due to an INVALID KEY condition.
The logical record is also available to the program as a record of other
files referenced in the same
SAME RECORD AREA clause as the associated output file, as well as to
the file associated with record-name.
- When the INVALID KEY condition is recognized, the execution of the WRITE
statement is unsuccessful; the contents of the record area are unaffected,
and the FILE STATUS data item, if any, of the associated file is set to a
value indicating the cause of the condition. Execution of the program
proceeds according to the rules stated in The INVALID KEY Condition in this
chapter (see also the section I/O Status in this chapter).
Format 4 (Relative Files)
- When a file is opened in the OUTPUT mode, records can be placed into the
file by one of the following:
- If access mode is
sequential, the
WRITE statement will cause a record to be released to the operating
system. The first record will have a relative record number of one and
subsequent records released will have relative record numbers of 2, 3, 4,
... . If the
RELATIVE KEY data item has been specified in the file control entry
for the associated file, the relative record number of the record just
released will be placed into the RELATIVE KEY data item by the operating
system during execution of the WRITE statement.
- If access mode is
random or
dynamic, the value of the RELATIVE KEY data item must be initialized
in the program, prior to the execution of the WRITE statement, with the
relative record number, or be associated with the record in the record
area. That record is then released to the operating system by execution of
the WRITE statement.
- When a file is opened in
I/O mode and access mode is random or dynamic, the value of the
RELATIVE KEY data item must be initialized by the program with the relative
record number to be associated with the record in the record area. Execution
of a WRITE statement then causes the contents of the record area to be
released to the operating system.
- The
INVALID KEY condition exists under the following circumstances:
- When access mode is random or
dynamic, and the RELATIVE KEY data item specifies a record which
already exists in the file, or:
- When an attempt is made to write beyond the externally defined
boundaries of the file.
Format 4 (Indexed Files)
- Execution of the WRITE statement causes the contents of the
record area to be released. The operating system uses the contents of
the
record keys so that subsequent access of the record can be made via any
of those specified record keys.
- The value of the prime record key should be unique within the records in
the file.
- The data item specified as the prime record key must be set by the
program to the desired value prior to the execution of the
WRITE statement.
- If
sequential access mode is specified for the file, records must be
released to the operating system in ascending order of prime record key
values.
- If
random or
dynamic access mode is specified, records can be released to the
operating system in any program-specified order.
- When the
ALTERNATE RECORD KEY clause is specified in the file control entry for
an indexed file, the value of the
alternate record key can be non-unique only if the
DUPLICATES phrase is specified for that data item. In this case, the
operating system provides storage of records so that when records are
accessed sequentially, those records are retrieved in the order in which
they are released to the operating system.
- The
INVALID KEY condition exists under the following circumstances:
- When sequential access mode is specified for a file opened in OUTPUT
mode, and the value of the prime record key is not greater than the value
of the prime record key of the previous record, or:
- When the file is opened in OUTPUT or
I/O mode, and the value of the prime record key is equal to the value
of a prime record key of a record already existing in the file, or:
- When the file is opened in OUTPUT or I/O mode, and the value of an
alternate record key for which duplicates are not allowed equals the
corresponding data item of a record already existing in the file, or:
- When an attempt is made to write beyond the externally defined
boundaries of the file.
-
Transfer of control following
the successful or unsuccessful execution of the WRITE operation depends on
the presence or absence of the INVALID KEY and NOT INVALID KEY phrases. (See
the section Invalid Key Condition in this chapter.)
Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
| Procedure Division - PERFORM - ROLLBACK |
| Object COBOL Language Extensions | |