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.
-
The SET statement is used
to assign object references.
-
The SET statement is used
to alter the value of a synchronization data item.
-
The SET statement is used
to assign the address of a synchronization data item to another synchronization
data item.
General Formats
Format 1
Format 2
Format 3
Format 4
Format 5
Format 6
Format 7
Format 8
Format 9 (Value of Event-pointer)
Format 10 (Address of Event-pointer)
Format 11 (Value of Monitor-pointer)
Format 12 (Address of Monitor-pointer)
Format 13 (Value of Mutex-pointer)
Format 14 (Address of Mutex-pointer)
Format 15 (Value of Semaphore-pointer)
Format 16 (Address of Semaphore-pointer)
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.
Identifier-2 must be
declared in the Linkage Section.
Identifier-1 must be
declared in the Linkage Section, the Local-Storage Section or the
Working-Storage 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.
Format 8
- Identifier-9 must be any item of class object that is permitted as a
receiving item.
- Identifier-10 must be a class-name or an object reference; the
predefined object reference SUPER must not be specified.
- If the data item referenced by identifier-9 is a universal object
reference, the only predefined object references that may be specified for
identifier-10 are SELF and NULL.
- If the data item referenced by identifier-9 is described with an
interface-name that identifies the interface int-1, the data item referenced by
identifier-10 mustl be one of the following:
- an object reference described with an interface-name that
identifies an interface conforming to int-1;
- an object reference described with a class-name, subject to the
following rules:
- if described with a FACTORY phrase, the interface of the
factory object of the specified class must conform to int-1,
- if described without a FACTORY phrase, the interface of the
objects of the specified class must conform to int-1;
- an object reference described with an ACTIVE-CLASS phrase,
subject to the following rules:
- if described with a FACTORY phrase, the interface of the
factory object of the class containing the data item referenced by
identifier-10 must conform to int-1,
- if described without a FACTORY phrase, the interface of the
objects of the class containing the data item referenced by identifier-10 must
conform to int-1;
- a class-name, where the interface of its factory object conforms
to int-1;
- the predefined object reference SELF, where the interface of the
object containing the SET statement conforms to int-1;
- the predefined object reference NULL.
- If the data item referenced by identifier-9 is described with a
class-name, the data item referenced by identifier-10 must be either of the
following:
- an object reference described with a class-name, subject to the
following rules:
- if the data item referenced by identifier-9 is described with
an ONLY phrase, the data item referenced by identifier-10 must be described
with the ONLY phrase, and the class-name specified in the description of the
data item referenced by identifier-10 shall be the same as the class-name
specified in the description of the data item referenced by identifier-9,
- if the data item referenced by identifier-9 is described
without an ONLY phrase, the class-name specified in the description of the data
item referenced by identifier-10 must reference the same class or a subclass of
the class specified in the description of the data item referenced by
identifier-9,
- the presence or absence of the FACTORY phrase shall be the
same as in the description of the data item referenced by identifier-9;
- an object reference described with an ACTIVE-CLASS phrase,
subject to the following rules:
- the data item referenced by identifier-9 must not be
described with the ONLY phrase,
- the class containing the data item referenced by
identifier-10 must be the same class or a subclass of the class specified in
the description of the data item referenced by identifier-9,
- the presence or absence of the FACTORY phrase must be the
same as in the description of the data item referenced by identifier-9;
- the predefined object reference SELF, subject to the following
rules:
- the data item referenced by identifier-9 must not be
described with the ONLY phrase,
- the class of the object containing the SET statement must be
the same class or a subclass of the class specified in the description of the
data item referenced by identifier-9,
- if the data item referenced by identifier-9 is described
without a FACTORY phrase, the object containing the SET statement shall be an
instance object,
- if the data item referenced by identifier-9 is described with
a FACTORY phrase, the object containing the SET statement shall be a factory
object;
- a class-name, provided the data item referenced by identifier-9
is described with the FACTORY phrase, and class-name references the same class
or a subclass of the class specified in the description of the data item
referenced by identifier-9;
- the predefined object reference NULL.
- If the data item referenced by identifier-9 is described with an
ACTIVE-CLASS phrase, the data item referenced by identifier-10 must be either
of the following:
- an object reference described with the ACTIVE-CLASS phrase, where
the presence or absence of the FACTORY phrase is the same as in the data item
referenced by identifier-9;
- the predefined object reference SELF, subject to the following
rules:
- if the data item referenced by identifier-9 is described
without a FACTORY phrase, the object containing the SET statement must be an
instance object,
- if the data item referenced by identifier-9 is described with
a FACTORY phrase, the object containing the SET statement must be a factory
object;
- the predefined object reference NULL.
Format 9
-
Event-pointer-1 must be defined as a data item with USAGE
EVENT-POINTER.
Format 10
-
Event-pointer-1 and
event-pointer-2 must be defined as data items with USAGE EVENT-POINTER.
Format 11
-
Monitor-pointer-1 must be defined as a data item with
USAGE MONITOR-POINTER.
-
If the NOT phrase is
specified, then the CONVERTING phrase must not be specified.
Format 12
-
Monitor-pointer-1 and
monitor-pointer-2 must be defined as data items with USAGE MONITOR-POINTER.
Format 13
-
Mutex-pointer-1 must be defined as a data item with USAGE
MUTEX-POINTER.
Format 14
-
Mutex-pointer-1 and
mutex-pointer-2 must be defined as data items with USAGE MUTEX-POINTER.
Format 15
-
Semaphore-pointer-1 must be defined as a data item
with USAGE SEMAPHORE-POINTER.
-
Identifier-11 must
reference an integer.
Format 16
-
Semaphore-pointer-1 and
semaphore-pointer-2 must be defined as data items with USAGE SEMAPHORE-POINTER.
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 runtime
element 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
- The following
steps are repeated for each recurrence of index-name-1 or identifier-5. 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 is evaluated immediately before the value of that
data item is changed.
- If
index-name-1 is specified, 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/11c |
Valid/11a |
No/11b |
Integer Data Item |
No/11c |
Valid/11a |
No/11b |
Index-Name |
Valid/11c |
Valid/11a |
Valid/11b1 |
Index Data Item |
No/11c |
Valid/11a1 |
Valid/11b1 |
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.
Format 8
- If identifer-10 is an object reference, a reference to the object
identified by identifier-10 is placed into each data item referenced by
identifier-9 in the order specified.
- If identifier-10 is a class-name, a reference to the factory object
of the class identified by identifier-10 is placed into each data item
referenced by identifier-9 in the order specified.
Formats 9 and 10
-
If more than one
event-pointer-1 is specified, the results are the same as if a separate SET
statement had been written for each event-pointer-1 in the same order as
specified in the SET statement.
Format 9
-
The execution of the SET
statement sets the value of the event referenced by event-pointer-1 to TRUE or
FALSE.
Note: When an event is set to FALSE, the execution of any thread
which executes a WAIT statement which references that event will suspend until
the event is set to TRUE in another thread.
Format 10
-
Event-pointer-1 is set to
reference the same event data item that event-pointer-2 references.
Formats 11 and 12
-
If more than one
monitor-pointer-1 is specified, the results are the same as if a separate SET
statement had been written for each monitor-pointer-1 in the same order as
specified in the SET statement.
Format 11
-
If the NOT phrase is not
specified, the value of the monitor referenced by monitor-pointer-1 is set to
one of BROWSING, READING, or WRITING, thus establishing the corresponding form
of lock. This specific lock type for this specific monitor must be eventually
released by a SET statement either with a matching NOT phrase or a matching
CONVERTING FROM phrase.
For example, the lock established by
SET mon-1 TO READING
can be cleared by
SET mon-1 TO NOT READING
-
The CONVERTING phrase is
used to change the current type of lock established on a monitor. The lock type
specified in the FROM phrase must be currently established by that thread and
upon successful execution of the statement, that lock will have been changed,
in one atomic operation, to the lock type specified in the TO phrase.
-
Nested locks can be
obtained by the execution of successive SET monitor statements with no
intervening SET statement that releases the lock. Once a READING lock is
established, no BROWSING or WRITING lock is allowed to nest within that thread.
Once a BROWSING lock or a WRITING lock is established, any other level of lock
is allowed to nest within that thread.
Format 12
-
Monitor-pointer-1 is set to
reference the same monitor data item that monitor-pointer-2 references.
Formats 13 and 14
-
If more than one
mutex-pointer-1 is specified, the results are the same as if a separate SET
statement had been written for each mutex-pointer-1 in the same order as
specified in the SET statement.
Format 13
-
The execution of the SET
statement sets the value of the mutex referenced by mutex-pointer-1 to ON or
OFF.
-
When a mutex is set to ON,
the execution of any thread that attempts to set that mutex to ON will suspend
until the mutex is set to OFF in the thread that set it ON.
Format 14
-
Mutex-pointer-1 is set to
reference the same mutex data item that mutex-pointer-2 references.
Formats 15 and 16
-
If more than one
semaphore-pointer-1 is specified, the results are the same as if a separate SET
statement had been written for each semaphore-pointer-1 in the same order as
specified in the SET statement.
Format 15
-
The contents of the
semaphore data item referenced by semaphore-pointer-1 are incremented (UP BY)
or decremented (DOWN BY) by a value that corresponds to the value of integer-4
or the data item referenced by identifier-11; thereafter, the process is
repeated for each recurrence of semaphore-pointer-1. For each repetition, the
value of the data item referenced by identifier-11 is used as it was at the
beginning of the execution of the statement.
-
If a semaphore is set DOWN
BY n and the semaphore is less than n, the thread is suspended until another
thread raises the semaphore to above n.
Format 16
-
Semaphore-pointer-1 is set
to reference the same semaphore data item that semaphore-pointer-2 references.
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 sorted 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 or METHOD 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 or METHOD 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 output
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 runtime elements. 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.
The START statement initiates
execution of a thread, either synchronously or asynchronously.
General Formats
Format 1 (Relative Files)
Format 2 (Indexed Files)
Format 3 (Threads)
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.
Format 3 (Threads)

- Literal-1 must be a nonnumeric literal and cannot be a figurative
constant.
- Identifier-1 must be defined as an alphanumeric data item such that
its value can be a COBOL or non-COBOL program-name.
- Identifier-3 must be defined as either USAGE POINTER or a data item
that is 4 bytes in size. The definition depends on the definition of the
GIVING/RETURNING item within the EXIT PROGRAM / STOP RUN statement for the new
thread. If identifier-3 is defined as a USAGE POINTER item, it must not be a
function-identifier.
- Thread-pointer-1 must be defined as USAGE THREAD-POINTER.
- Identifier-4 must be defined as an integer data item that has a
length of at least 4 digits.
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 last 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 KEY 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.
Format 3 (Threads)

- Literal-1, identifier-1, or procedure-pointer-1 must reference a
program-id which is either the outermost program-id in a compilation unit, an
ENTRY point in a program or a label in another language. This will be the
starting point of the newly created thread's execution.
- If identifier-2 is specified, the starting point of the newly created
thread must be defined in such a way that it accepts a single parameter that is
passed by reference.
- If the BY CONTENT phrase is specified, the contents of identifier-2
are copied to a system allocated, thread-safe work area and a reference to this
work area will be passed to the starting point of the newly created thread.
This work area will remain valid during the entire execution of the created
thread, irrespective of the lifetime of the creating program's data areas.
- If the BY CONTENT phrase is not specified, a direct reference to
identifier-2 is passed to the starting point of the newly created thread. It is
left to the programmer to ensure that this data area remains valid while the
newly created thread references it.
- If the RETURNING phrase is specified, the newly created thread
executes to completion, returns a value in identifier-3 and returns control to
the START statement.
- If the IDENTIFIED BY phrase is specified, execution of the newly
created thread is initiated, a handle to reference the newly created thread is
placed into thread-pointer-1 and control is returned to the START statement.
The handle can be used in a WAIT statement to retrieve a returned value,
synchronize execution and free the thread's resources. This handle is a valid
thread handle as used by the CBL_THREAD_ Api.
- If neither the RETURNING phrase nor the IDENTIFIED phrase is
specified, the newly created thread is initiated and control is returned to the
START statement. All resources of the thread will be automatically freed when
the thread terminates.
- If the STATUS phrase is specified, the execution of the START
statement places into identifier-4 one of the return codes specified for the
CBL_THREAD_ Api.
- If the START statement fails, one of the return codes specified for
the CBL_THREAD_ Api is placed into identifier-4, if specified, and then one of
the following occurs:
- If the ON EXCEPTION phrase is specified, control is transferred
to imperative-statement-1. Execution then continues according to the rules for
each statement specified in imperative-statement-1. If a procedure branching or
conditional statement that causes explicit transfer of control is executed,
control is transferred in accordance with the rules of that statement;
otherwise, upon completion of the execution of imperative-statement-1, control
is transferred to the end of the START statement and the NOT ON EXCEPTION
phrase, if specified, is ignored.
- Otherwise, if the NOT ON EXCEPTION phrase or the STATUS phrase is
specified, control is transferred to the end of the START statement and the NOT
ON EXCEPTION phrase, if specified, is ignored.
- Otherwise, the run-unit will terminate with an RTS error.
- If the START statement is successful, the following occurs in the
order specified:
- If the STATUS phrase, is specified, ZERO is moved to
identifier-4.
- If the NOT ON EXCEPTION phrase is specified, control is
transferred to imperative-statement-2. Execution then continues according to
the rules for each statement specified in imperative-statement-2. If a
procedure branching or conditional statement that causes explicit transfer of
control is executed, control is transferred in accordance with the rules of
that statement; otherwise, upon completion of the execution of
imperative-statement-2, control is transferred to the end of the START
statement and the ON EXCEPTION phrase, if specified, is ignored.
The STOP statement causes a permanent or temporary suspension of the
execution of the run unit.
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.
-
If a STOP RUN GIVING
statement is executed within a thread created with the START statement (format
3 threads) and if the ADDRESS OF clause is not specified, identifier-1 must be
defined as either USAGE POINTER or a data item that is 4 bytes in size. The
definition depends on the definition of the RETURNING item within the START
statement. If identifier-1 is defined as a USAGE POINTER item, it must not be a
function-identifier.
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.
-
Execution of a STOP RUN
statement causes a return value to be set in the system area generally
available for non-COBOL runtime elements 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 run unit 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 run unit 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 run unit 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.
When executed within a
thread created with a START statement or the CBL_CREATE_THREAD (necessarily in
the multi-threaded run-time system), a STOP RUN GIVING statement does not end
the run-unit; it simply provides a return value and terminates the thread. It
is equivalent to:
CALL 'CBL_THREAD_EXIT' USING BY VALUE ADDRESS OF thread-parm
STOP RUN in threads not created by the START statement or
CBL_THREAD_CREATE (that is, the main thread, or a thread created by a program
written in another programming language) will wait for all active
CBL_THREAD_CREATE threads to finish and then terminate the run unit.
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 is determined as follows (see the section
Arithmetic Statements
in the chapter
Procedure Division):
- In Format 1, by using all of the operands in a given statement.
- In Format 2, by using all of the operands in a given statement
excluding the data items that follow the word GIVING.
- In Format 3, 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.
-
Identifier-1 must not be reference modified.
-
Identifier-1 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 USE 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 WAIT statement suspends the current thread's execution until the
targeted thread's execution terminates and optionally retrieves the value
returned from the targeted thread's execution.
The WAIT statement suspends execution until an event is TRUE.
General Formats
Format 1 (Thread)

Format 2 (Event)

Syntax Rules
Format 1 (Thread)
- Thread-pointer-1 must be defined as USAGE THREAD-POINTER.
- Identifier-1 must be defined either as USAGE POINTER or must be 4
bytes in size. It must not be a function-identifier.
- Identifier-2 must be defined as an integer data item that has a
length of at least 4 digits.
Format 2 (Event)
- Event-pointer-1 must be defined as USAGE EVENT-POINTER.
General Rules
Format 1 (Thread)
- Thread-pointer-1 must contain a thread handle as returned from the
START statement with the IDENTIFIED BY phrase or from the CBL_THREAD_ Api.
- A successful WAIT statement suspends the current thread's execution
until the termination of the thread referenced by the thread handle contained
in thread-pointer-1.
- If the RETURNING phrase is specified, a successful WAIT statement
returns a value in identifier-1.
- After the successful execution of a WAIT statement, the thread handle
contained in thread-pointer-1 is invalid.
- If the STATUS phrase is specified, the execution of the WAIT
statement places into identifier-4 one of the return codes specified for the
CBL_THREAD_ Api.
- If the WAIT statement fails, one of the return codes specified for
the CBL_THREAD_ Api is placed into identifier-2, if specified, and then one of
the following occurs:
- If the ON EXCEPTION phrase is specified, control is transferred
to imperative-statement-1. Execution then continues according to the rules for
each statement specified in imperative-statement-1. If a procedure branching or
conditional statement that causes explicit transfer of control is executed,
control is transferred in accordance with the rules of that statement;
otherwise, upon completion of the execution of imperative-statement-1, control
is transferred to the end of the WAIT statement and the NOT ON EXCEPTION
phrase, if specified, is ignored.
- Otherwise, if the NOT ON EXCEPTION phrase or the STATUS phrase is
specified, control is transferred to the end of the WAIT statement and the NOT
ON EXCEPTION phrase, if specified, is ignored.
- Otherwise, the run-unit will terminate with an RTS error.
- If the WAIT verb is successful, the following occurs in the order
specified:
- If the STATUS phrase, is specified, ZERO is moved to
identifier-2.
- If the NOT ON EXCEPTION phrase is specified, control is
transferred to imperative-statement-2. Execution then continues according to
the rules for each statement specified in imperative-statement-2. If a
procedure branching or conditional statement that causes explicit transfer of
control is executed, control is transferred in accordance with the rules of
that statement; otherwise, upon completion of the execution of
imperative-statement-2, control is transferred to the end of the WAIT statement
and the ON EXCEPTION phrase, if specified, is ignored.
Format 2 (Event)
- A successful WAIT statement suspends execution until the event
referenced by event-pointer-1 is TRUE.
Note: Execution resumes immediately if the event referenced by
event-pointer-1 is TRUE when the statement is executed.
- If the WAIT statement fails, the run-unit will terminate with an RTS
error.
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
.
- 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
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
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
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
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 runtime element, 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
runtime element 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
runtime element 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 © 2001 Micro Focus International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.