| Procedure Division - PERFORM - ROLLBACK |
|
Object COBOL Language Extensions | |
The SEARCH statement is used to
search a table for a table element that satisfies the specified
condition and to adjust the associated index-name to indicate that table
element.
General Format
Format 1
Format 2
Note that the required relational character "=" is not
underlined to avoid confusion with other symbols.
Syntax Rules
All Formats (All Files)
- Identifier-1 must not be subscripted or indexed, but its description
must contain an
OCCURS clause and an
INDEXED BY clause. The description of identifier-1 in Format 2
must also contain the KEY IS phrase in its OCCURS clause.
- Identifier-2, when specified, must be described as USAGE IS INDEX or
as a numeric elementary item without any positions to the right of the
assumed decimal point.
-
If the END-SEARCH phrase is
specified, the NEXT SENTENCE phrase must not be specified.
END-SEARCH can be
specified with NEXT SENTENCE. If the NEXT SENTENCE phrase is executed,
control will not pass to the next statement following the END-SEARCH,
but instead will pass to the statement after the closest following
period.
-
Both imperative-statement-1
and imperative-statement-2 can be replaced by a conditional statement.
Format 1
- Condition-1, condition-2, and so on, can be any condition as
described in the section Conditional Expressions earlier in this
chapter.
-
Identifier-1, the table
element being searched, can be an internal or external floating-point
item.
Format 2
- All referenced condition-names must be defined as having only a
single value. The data-name associated with a condition-name must appear
in the
KEY clause of identifier-1. Each data-name-1, data-name-2 can be
qualified. Each data-name-1, data-name-2 must be indexed by the first
index-name associated with identifier-1 along with other indices or
literals as required, and must be referenced in the KEY clause of
identifier-1. Identifier-3, identifier-4, or identifiers specified in
arithmetic-expression-1, arithmetic-expression-2 must not be referenced
in the KEY clause of identifier-1 or be indexed by the first index-name
associated with identifier-1.
When a data-name in the KEY clause of identifier-1 is referenced, or
when a condition-name associated with a data-name in the KEY clause of
identifier-1 is referenced, all preceding data-names in the KEY clause
of identifier-1 or their associated condition-names must also be
referenced.
-
Identifier-1, the table
element being searched, can not be a floating-point item.
-
Neither data-name-1 nor
data-name-2, the key data items, can be floating point items. However,
identifier-3, identifier-4, literal-1, or literal-2, the items against
which the key is compared, can be floating-point items.
General Rules
All Formats
- The scope of a SEARCH statement can be terminated by any of the
following:
-
An END-SEARCH phrase at
the same level of nesting.
- separator period.
- An ELSE
or END-IF
associated with a previous IF statement.
- After execution of imperative-statement-1 or imperative-statement-2,
that does not terminate with a GO TO statement, control passes to the
next executable sentence.
- If identifier-1 is a data item subordinate to a data item that
contains an OCCURS clause (providing for a
two- or
three-dimensional table), an index-name must be associated with
each dimension of the table through the INDEXED BY phrase of the OCCURS
clause. Only the setting of the index-name associated with identifier-1
(and the data item identifier-2 or index-name-1, if present) is modified
by the execution of the SEARCH statement. To search an entire two or
three dimensional table it is necessary to execute a SEARCH statement
several times. Prior to each execution of a SEARCH statement, SET
statements must be executed whenever index-names must be adjusted to
appropriate settings.
Format 1
- If Format 1 of the SEARCH is used, a
serial type of
search operation takes place, starting with the current index
setting.
- If, at the start of execution of the SEARCH statement, the
index-name associated with identifier-1 contains a value that
corresponds to an occurrence number that is greater than the highest
permissible occurrence number for identifier-1, the SEARCH is
terminated immediately. The number of occurrences of identifier-1,
the last of which is the highest permissible, is discussed in the
OCCURS clause. (See the section The OCCURS Clause earlier in
this chapter.) Then, if the AT END phrase is specified, imperative-
statement-1 is executed; if the AT END phrase is not specified,
control passes to the next executable sentence.
- If, at the start of execution of the SEARCH statement, the
index-name associated with identifier-1 contains a value that
corresponds to an occurrence number that is not greater than the
highest permissible occurrence number for identifier-1 (the number
of occurrences of identifier-1, the last of which is the highest
permissible is discussed in the OCCURS clause), the SEARCH statement
operates by evaluating the conditions in the order that they are
written, making use of the index settings, wherever specified, to
determine the occurrence of those items to be tested. If none of the
conditions is satisfied, the index name for identifier-1 is
incremented to obtain reference to the next occurrence. The process
is then repeated using the new index-name settings unless the new
value of the index-name settings for identifier-1 corresponds to a
table element outside the permissible range of occurrence values, in
which case the search terminates as indicated in General Rule 1a
above. If one of the conditions is satisfied upon its evaluation,
the search terminates immediately and the imperative statement
associated with that condition is executed; the index-name remains
set at the occurrence which caused the condition to be satisfied.
- If the VARYING phrase is not used, the index-name that is used for
the search operation is the first (or only) index-name that appears in
the INDEXED BY phrase of identifier-1. Any other index-names for
identifier-1 remain unchanged.
- If the VARYING index-name-1 phrase is specified, and if index-name-1
appears in the INDEXED BY phrase of identifier-1, that index-name is
used for this search. If this is not the case, or if the VARYING
identifier-2 phrase is specified, the first (or only) index-name given
in the INDEXED BY phrase of identifier-1 is used for the search. In
addition, the following operations will occur:
- If the VARYING index-name-1 phrase is used, and if index-name-1
appears in the
INDEXED BY phrase of another table entry, the occurrence
number represented by index-name-1 is incremented by the same amount
as, and at the same time as, the index-name associated with
identifier-1 is incremented.
- If the VARYING identifier-2 phrase is specified, and identifier-2
is an index data item, then the data item referenced by identifier-2
is incremented by the same amount as, and at the same time as, the
index associated with identifier-1 is incremented. If identifier-2
is not an index data item, the data item referenced by identifier-2
is incremented by the value (1) at the same time as the index
referenced by the index-name associated with identifier-1 is
incremented.
Format 2
- The results of the
SEARCH ALL operation are predictable only when:
- The data in the table is ordered in the same manner as described
in the ASCENDING/DESCENDING KEY clause associated with the
description of identifier-1, and:
- The contents of the key(s) referenced in the WHEN clause are
sufficient to identify a unique table element.
- If Format 2 of the SEARCH is used, a
non-serial type of search operation can take place; the initial
setting of the index-name for identifier-1 is ignored and its setting is
varied during the search operation with the restriction that at no time
is it set to a value that exceeds the value which corresponds to the
last element of the table, or that is less than the value that
corresponds to the first element of the table. The length of the table
is discussed in the OCCURS clause. If any of the conditions specified in
the WHEN clause cannot be satisfied for any setting of the index within
the permitted range, control is passed to imperative-statement-1 of the
AT END phrase, when specified, or to the next executable sentence when
this phrase is not specified; in either case the final setting of the
index is not predictable. If all conditions can be satisfied, the index
indicates an occurrence that allows the conditions to be satisfied, and
control passes to imperative-statement-2.
- The index-name that is used for the search operation is the first (or
only) index-name that appears in the INDEXED BY phrase of identifier-1.
Any other index-names for identifier-1 remain unchanged.
-
Neither
imperative-statement-2 nor NEXT SENTENCE is required. Without them, the
SEARCH statement sets the index to the value in the table that matched
the condition.
Figure 16-5 shows a flowchart of the Format 1 SEARCH operation
containing two WHEN phrases.
Figure 16-1: Flowchart of SEARCH Operation Showing Two WHEN Phrases
- These operations are options included only when specified in the
SEARCH statement.
- Each of these control transfers is to the next executable sentence
unless the imperative-statement ends with a GO TO statement.
The SERVICE
statement is used to establish addressability to Linkage Section
items usually in a CICS program.
General Format
Syntax Rules
- SERVICE LABEL is generated by the mainframe CICS preprocessor to
indicate control flow. It is not intended for general use.
- The SERVICE LABEL statement can appear only in the Procedure
Division, not in the Declaratives Section.
- Identifier should be either the first 01-level item representing the
BLL-cell block in the Linkage Section, or another Linkage Section
01-level item for which addressability needs to be re-established
following an EXEC CICS statement.
General Rules
- At the statement following the SERVICE LABEL statement, all registers
that can no longer be valid are reloaded.
- If the OS/VS COBOL BLL mechanism is used in a CICS program,
addressability to the parameter list must be established at the start of
the Procedure Division. This is done by adding a SERVICE RELOAD
identifier statement at the start of the Procedure Division where the
identifier is the first item in Linkage Section and it includes pointers
to all other entries in the Linkage Section.
- If a locate-mode EXEC CICS statement is included in a program
compiled with the OSVS Compiler directive, then a SERVICE RELOAD
statement must follow each such CICS command and the identifier must be
the same pointer (BLL-cell reference) used in the CICS command.
- In a CICS program compiled with the OSVS Compiler directive, any time
a reference is made to a Linkage Section which is greater than 4096
bytes long, a SERVICE RELOAD statement should be made to re-establish
addressability to that portion of the data item greater than 4096 byte.
- The SERVICE RELOAD statement is documentary only in a program
compiled with the VSC2 Compiler directive.
-
The SET statement is used
to alter the status of
external
switches.
-
The SET statement is used
to alter the value of
conditional
variables.
-
The SET statement is used
to assign the address of a data item to a pointer data item. It is also
used to adjust the contents of a pointer data item.
- The SET statement establishes
reference points for
table handling operations by setting indices associated with
table elements.
-
The SET statement is used
to assign the address of a program or an entry-point in a program to a
procedure-pointer data item.
-
The SET statemet 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
that is declared in the
Linkage-Section.
-
Pointer-name-1,
pointer-name-2 must each be an identifier that references an elementary
data item with USAGE IS POINTER.
Format 4
-
Pointer-name-3 must be an
identifier that references an elementary data item with USAGE IS
POINTER.
-
Identifier-3 must be an
elementary numeric integer.
-
Integer-1 may be signed.
Format 5
- Identifier-5 and identifier-6 must each reference an index data item
or an elementary item described as an integer. If both are specified,
they must not both reference an elementary item.
Formats 5 and 6
- Integer-2 and integer-3 may be signed. Integer-2 must be positive.
Format 6
- Identifier-7 must reference an elementary numeric integer.
Format 7
-
Procedure-pointer-name-1
and procedure-pointer-name-2 must each be an identifier that references
an elementary data item with USAGE IS PROCE
DURE-POINTER.
-
Identifier-8 must be
defined as an alphanumeric data item such that its value can be a COBOL
or a non-COBOL program name.
-
Literal-1 must be a
nonnumeric literal.
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
-
- 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 so
rted records are either written to the file referenced by
file-name-3, or, by the execution of a RETURN statement, are made
available for processing by the output procedure. When this phase
commences, the file referenced by file-name-3 must not be in the
open mode. When this phase terminates, the file referenced by
file-name-3 is not in the open mode.
- The input procedure can consist of any procedure needed to select,
modify or copy the records that are made available one at a time by the
RELEASE statement to the file referenced by file-name-1. The range
includes all statements that are executed as a result of a transfer of
control by CALL, EXIT without the optional PROGRAM 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 l
ast logical record currently existing in the file whose key
satisfies the comparison.
- If the comparison is not satisfied by any record in the file, an
INVALID KEY condition exists. The execution of the
START statement will be unsuccessful, and the position of the
file position indicator will be undefined. (See the section The
INVALID KEY Condition in this chapter.)
- The comparison described in General Rule 5 uses the data item
referenced by the RELATIVE KEY clause associated with file-name-1. A
RELATIVE KEY clause must be associated with file-name-1.
Format 2 (Indexed Files)
- The type of comparison specified by the relational operator in the
KEY phrase occurs between a key associated with a record in the file
referenced by file-name-1 and a data item as specified in General Rule
8. If file-name-1 references an indexed file and the operands are of
unequal size, the comparison proceeds as though the longer one were
truncated on the right so that its length is equal to that of the
shorter. All other nonnumeric comparison rules apply except that the
presence of the
PROGRAM COLLATING SEQUENCE clause will have no effect on the
comparison. (See the section Comparison Of Nonnumeric Operands
earlier in this chapter.)
-
If the relational
operator specifies that the key must be equal to, greater than, or
greater than or equal to the data item, then
the file
position indicator is positioned to the
first logical record currently existing in the file whose
key satisfies the comparison.
-
If the relational
operator specifies that the key must be less than, or less than or
equal to the data item, then the file
position indicator is positioned to the
last logical record currently existing in the file whose key
satisfies the comparison. If this key has duplicate entries, the
file position indicator is positioned to the last of these entries.
- If the comparison is not satisfied by any record in the file, an
INVALID KEY condition exists, the execution of the START
statement is unsuccessful, and the position of the file position
indicator is undefined. (See the section The INVALID KEY
Condition in this chapter.)
- If the KEY phrase is specified, the comparison described in General
Rule 7 uses the data item referenced by data-name.
- If the K
EY phrase is not specified, the comparison described in General
Rule 7 uses the data item referenced in the RECORD KEY clause associated
with file-name-1.
- After successful execution of the
START statement, a key of
reference is established and used in subsequent Format 3 READ
statements as follows (see the section The READ Statement
earlier in this chapter):
- If the KEY phrase is not specified, the prime record key
specified for file-name-1 becomes the key of reference.
- If the KEY phrase is specified, and data-name-1
or split-key-name-1
is specified as a record key for file-name-1, that record key
becomes the key of reference.
- If the KEY phrase is specified, and data-name-1
or split-key-name-1
is not specified as a record key for file-name-1, the record key
whose leftmost character position corresponds to the leftmost
character position of the data item specified by data-name-1
or split-key-name-1
becomes the key of reference.
- If execution of the START statement is not successful, the key of
reference is undefined.
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 must not contain more than 18 digits. (See the section
The Arithmetic Statements earlier in this chapter.)
- In Format 1 the composite of operands is determined by using all
of the operands in a given statement.
- In Format 2 the composite of operands is determined by using all
of the operands in a given statement excluding the data items that
follow the word GIVING.
- In Format 3 the composite operands is determined separately for
each pair of corresponding data items.
Formats 1 and 2
- Each literal must be a numeric literal.
-
Floating-point data items
and literals can be used anywhere numeric data items and literals can be
specified.
Format 3
- CORR is an abbreviation for CORRESPONDING.
General Rules
All Formats
- See the sections The ROUNDED Phrase, The ON SIZE ERROR
Phrase, Arithmetic Statements, Overlapping Operands
and Multiple Results In Arithmetic Statements in this chapter.
-
The COBOL system ensures
enough places are carried so as not to lose significant digits during
execution.
Format 1
- All literals or identifiers preceding the word FROM are added
together and this total is subtracted from the current value of
identifier-2 storing the result immediately into identifier-2, and
repeating this process respectively for each operand following the word
FROM.
Format 2
- In Format 2, all literals or identifiers preceding the word FROM are
added together, the sum is subtracted from literal-2 or identifier-2 and
the result of the subtraction is stored as the new value of each data
item referenced by identifier-3.
Format 3
- If Format 3 is used, data items in identifier-1 are subtracted from
and stored into corresponding data items in identifier-2.
The TRANSFORM statement is used to alter characters according to a
transformation rule.
General Format
Syntax Rules
- Identifier-3 can be any elementary item except a numeric item with
USAGE other than DISPLAY, or a group item.
- Identifier-1 and identifier-2 should be elementary alphabetic or
alphanumeric items.
- Nonnumeric-literal-2 or identifier-2 must be either one character
long or the same length as nonnumeric-literal-1 or identifier-1.
General Rules
- The use of figurative-constant-1 and/or figurative-constant-2 is
equivalent to the use of a single-character nonnumeric- literal with the
same value.
- If either identifier-1 or identifier-2 references the same computer
storage area as identifier-3, the result of the TRANSFORM is undefined.
(See the section The REDEFINES Clause earlier in this chapter.)
- If characters are repeated in nonnumeric-literal-1 or identifier-1,
then the result of the TRANSFORM operation is undefined.
- Execution of the TRANSFORM statement scans identifier-3 for
occurrences of individual characters from identifier-1 or
nonnumeric-literal-1. When a match is found, the corresponding character
(or the single character of a one-character field) from identifier-2 or
nonnumeric-literal-2 is substituted into that character position in
identifier-3. The correspondence between identifier-1 or nonnumeric-
literal-1 and identifier-2 or nonnumeric-literal-2 is by occurrence
number of the character within the data item (starting from the left).
The
UNLOCK statement releases all
record locks held by the run unit on a named file.
General Format
Syntax Rule
File-name must occur in the SELECT statement of the FILE CONTROL entry.
General Rules
- The file referenced by file-name must already be opened with the OPEN
statement.
- The UNLOCK statement releases all record locks held by the run unit
on a named file.
The UNSTRING statement causes contiguous data in a sending field to be
separated and placed into multiple receiving fields.
General Format
Syntax Rules
- Each literal must be a nonnumeric literal. In addition, each literal
can be any figurative constant without the optional word ALL.
- Identifier-1, identifier-2, identifier-3, and identifier-5 must be
described, implicitly or explicitly, as an alphanumeric data-item.
- Identifier-4 can be described as either alphabetic (except that the
symbol "B" can not be used in the PICTURE character-string),
alphanumeric, or numeric (except that the symbol "P" can not
be used in the PICTURE character-string), and must be described as USAGE
IS DISPLAY.
-
Syntax Rules 2 and 3 do not
apply. Instead, the following rules apply:
- Identifier-1 must be alphanumeric
- Identifier-2 and identifier-3 must be USAGE DISPLAY and must not
be edited
- Identifier-5 must be USAGE DISPLAY
- Identifier-4 can be USAGE DISPLAY
- Identifier-4 can have any USAGE that defines a numeric data item
as long as the data results in a valid MOVE operation.
-
Identifier-4 must not be
defined as a floating-point item.
- Identifier-6 and identifier-8 must reference integer data items,
(except that the symbol " P" can not be used in the PICTURE
character-string).
- Identifier-1 must be described as an elementary numeric integer data
item of sufficient size to contain a value equal to 1 plus the size of
the data item referenced by identifier-1. The symbol "P" can
not be used in the PICTURE character string of identifier-7.
- No identifier can name a level 88 entry.
- The DELIMITER IN phrase and the COUNT IN phrase can be specified only
if the DELIMITED BY phrase is specified.
-
The source of an UNSTRING
operation can be reference modified.
General Rules
- All references to identifier-2, literal-1, apply equally to
identifier-3, literal-2, respectively and all recursions thereof.
- Identifier-1 represents the sending area.
- Identifier-4 represents the data receiving area. Identifier-5
represents the receiving area for delimiters.
- Literal-1 or the data item referenced by identifier-2 specifies a
delimiter.
- The data item referenced by identifier-6 represents the count of the
number of characters within the data item referenced by identifier-1
isolated by the delimiters for the move to the data item referenced by
identifier-4. This value does not include a count of the delimiter
character(s).
- The data item referenced by identifier-7 contains a value that
indicates a relative character position within the area defined by
identifier-1.
- The data item referenced by identifier-8 is a counter that records
the number of data items acted upon during the execution of an UNSTRING
statement.
- When a figurative constant is used as the delimiter, it stands for a
single character nonnumeric literal.
When the ALL phrase is specified, one occurrence or two or more
contiguous occurrences of literal-1 (figurative constant or not) or
the contents of the data item referenced by identifier-2 are treated
as if it were only one occurrence, and this occurrence is moved to the
receiving data item according to the rules in General Rule 13d.
- When any examination encounters two contiguous delimiters, the
current receiving area is either space or zero filled according to the
description of the receiving area.
- Literal-1 or the contents of the data item referenced by identifier-2
can contain any character in the computer's character set.
- Each literal-1 or the data item referenced by identifier-2 represents
one delimiter. When a delimiter contains two or more characters, all of
the characters must be present in contiguous positions of the sending
item and in the order given, to be recognized as a delimiter.
- When two or more delimiters are specified in the DELIMITED BY phrase,
an "OR" condition exists between them. Each delimiter is
compared to the sending field. If a match occurs, the character(s) in
the sending field is considered to be a single delimiter. No
character(s) in the sending field can be considered a part of more than
one delimiter.
Each delimiter is applied to the sending field in the sequence
specified in the UNSTRING statement.
- When the UNSTRING statement is initiated, the current receiving area
is the data item referenced by identifier-4. Data transferred from the
data item referenced by identifier-1 to the data item referenced by
identifier-4 according to the following rules:
- If the
POINTER phrase is specified, the string of characters
referenced by identifier-1 is examined beginning with the relative
character position indicated by the contents of the data item
referenced by identifier-7. If the POINTER phrase is not specified,
the string of characters is examined beginning with the leftmost
character position.
- If the DELIMITED BY phrase is specified, the examination proceeds
left to right until either a delimiter specified by the value of
literal-1 or the data item referenced by identifier-2 is
encountered. (See General Rule 11.) If the DELIMITED BY phrase is
not specified, the number of characters examined is equal to the
size of the current receiving area. However, if the sign of the
receiving item is defined as occupying a separate character
position, the number of characters examined is one less than the
size of the current receiving area.
If the end of the data item referenced by identifier-1 is
encountered before the delimiting condition is met, the
examination terminates with the last character examined.
- The characters thus examined (excluding the delimiting
character(s), if any) are treated as an elementary alphanumeric data
item, and are moved into the current receiving area according to the
rules for the MOVE statement. (See the section The MOVE
Statement earlier in this chapter.)
- If the DELIMITER IN phrase is specified, the delimiting
character(s) are treated as an elementary alphanumeric data item and
are moved into the data item referenced by identifier-5 according to
the rules for the MOVE statement. (See the section The MOVE
Statement earlier in this chapter.) If the delimiting condition
is the end of the data item referenced by identifier-1, then the
data item referenced by identifier-5 is space-filled.
- If the COUNT IN phrase is specified, a value equal to the number
of characters thus examined (excluding the delimiter character(s) if
any) is moved into the area referenced by identifier-6 according to
the rules for an elementary move.
- If the DELIMITED BY phrase is specified the string of characters
is further examined beginning with the first character to the right
of the delimiter. If the DELIMITED BY phrase is not specified, the
string of characters is further examined beginning with the
character to the right of the last character transferred.
- After data is transferred to the data item referenced by
identifier-4, the current receiving area is the data item referenced
by the next recurrence of identifier-4. The behavior described in
paragraph 13b. through 13f. is repeated until either all the
characters are exhausted in the data item referenced by
identifier-1, or until there are no more receiving areas.
- The initialization of the contents of the data items associated with
the
POINTER phrase or the
TALLYING phrase is the responsibility of the user.
- The contents of the data item referenced by identifier-7 will be
incremented by one for each character examined in the data item
referenced by identifier-1. When the execution of an UNSTRING statement
with a POINTER phrase is complete, the contents of the data item
referenced by identifier-7 will contain a value equal to the initial
value plus the number of characters examined in the data item referenced
by identifier-1.
- When the execution of an UNSTRING statement with a TALLYING phrase is
completed, the contents of the data item referenced by identifier-8
contains a value equal to its initial value plus the number of data
receiving items acted upon.
- Either of the following situations causes an overflow condition:
- An UNSTRING is initiated, and the value in the data item
referenced by identifier-7 is less than 1 or greater than the size
of the data item referenced by identifier-1.
- If, during execution of an UNSTRING statement, all data receiving
areas have been acted upon, and the data item referenced by
identifier-1 contains characters that have not been examined.
- When an overflow condition exists, the UNSTRING operation is
terminated,
the NOT
ON OVERFLOW phrase, if specified, is ignored and
control is transferred to the end of the UNSTRING statement or, if
the ON OVERFLOW phrase is specified, to imperative-statement-1. If
control is transferred to imperative-statement-1, execution continues
according to the rules for each statement specified in
imperative-statement-1. If a procedure branching or conditional
statement which causes explicit transfer of control is executed,
control is transferred in accordance with the rules for that
statement; otherwise, upon completion of the execution of
imperative-statement-1, control is transferred to the end of the
UNSTRING statement.
-
The END-UNSTRING phrase
delimits the scope of the UNSTRING statement. (See the section Explicit
And Implicit Scope Terminators in the chapter Concepts of the
COBOL Language.)
- If, at the time of execution of an UNSTRING statement, the conditions
described in General Rule 17 are not encountered, after completion of
the transfer of data according to the other general rules, the ON
OVERFLOW phrase, if specified, is ignored and control is
transferred to the end of the UNSTRING statement
or, if the NOT ON
OVERFLOW phrase is specified, to imperative-statement-2. If control is
transferred to imperative- statement-2, execution continues according
to the rules for each statement specified in imperative-statement-2.
If a procedure branching or conditional statement which causes
explicit transfer of control is executed, control is transferred in
accordance with the rules for that statement; otherwise, upon
completion of the execution of imperative-statement-2, control is
transferred to the end of the UNSTRING statement.
- The evaluation of subscription and indexing for the identifiers is as
follows:
- Any subscripting or indexing associated with identifier-1,
identifier-7, or identifier-8 is evaluated only once, immediately
before any data is transferred as the result of the execution of the
UNSTRING statement.
- Any subscripting or indexing associated with identifier-2, -3,
-4, -5, or -6 is evaluated immediately before the transfer of data
into the respective data item.
-
22..Any subscripting
associated with the DELIMITED BY identifier, the INTO identifier, the
DELIMITER IN identifier, or the COUNT IN identifier is evaluated once,
immediately before the examination of the sending fields for the
delimiter.
- If identifier-1, -2 or -3, occupies the same storage area as
identifier-4, -5, -6, -7 or -8, or if identifier-4, -5 or -6 , occupies
the same storage area as identifier-7 or -8, or if identifier-7 and
identifier-8 occupy the same storage area, the result of the execution
of this statement is undefined, even if they are defined by the same
data description entry.
The U
SE statement specifies procedures for input-output error handling,
that are in addition to the standard procedures provided by the
input-output control system.
General Formats
Format 1 (Sequential , Relative and Indexed Files)
Format 2 (Record Sequential Files)
Format 3 (Relative And Indexed Files)
Syntax Rules
All Formats (All Files)
- Format 1 is the
ERROR declarative.
Formats 2 and 3 are the
LABEL declarative.
- A
USE statement, when present, must immediately follow a section
header in the Declaratives Section and must be followed by a period
followed by a space.
- The USE statement itself is never executed; it merely defines the
conditions calling for the execution of the
USE procedures.
- The files implicitly or explicitly referenced in a USE statement need
not all have the same organization or access.
Format 1 (Sequential, Relative and Indexed Files)
- The same file-name can appear in a different specific arrangement of
the format. Appearance of a file-name in a USE statement must not cause
the simultaneous request for execution of more than one USE procedure.
The same file-name must
not appear in more than one USE AFTER EXCEPTION statement within the
same Procedure Division.
- The words
ERROR and EXCEPTION are equivalent and can be used
interchangeably.
Formats 2 and 3 (Record Sequential, Relative and Indexed
Files)
-
If both BEGINNING and
ENDING are omitted, the effect is as though both BEGINNING and ENDING
had been specified.
Format 2 (Record Sequential Files)
-
REEL and UNIT are treated
as equivalent.
-
If both FILE and REEL/UNIT
are omitted, the effect is as though both REEL or UNIT and FILE had been
specified.
-
Any one file-name and any
one OPEN mode can appear in only one declarative for each of the
possible combinations of BEGINNING/ENDING and FILE/REEL as shown below:
BEGINNING FILE
BEGINNING REEL/UNIT
ENDING FILE
ENDING REEL/UNIT
General Rules
All Formats (All Files)
- After execution of a USE procedure, control is returned to the
invoking routine.
- Within a USE procedure, there must not be any reference to any
non-declarative procedures. Conversely, in the non-declarative portion
there must be no reference to procedure-names that appear in the
declarative portion, except that PERFORM statements can refer to a
USE statement.
This restriction can be
ignored.
- Within a
USE procedure, there must be no execution of any statement that
would cause the execution of a USE procedure that had previously been
invoked and had not yet returned control to the invoking routine.
Format 1 (Sequential, Relative and Indexed Files)
- The designated procedures are executed by the input-output system
after completing the standard input-output error routine, or upon
recognition of the AT END condition, when the AT END phrase has not been
specified in the input-output statement.
-
When file-name-1 is
specified explicitly, no other USE statement applies to file-name-1.
- The GIVING phrase is documentary only.
Formats 2 and 3 (Record Sequential, Relative and Indexed
Files)
-
If the BEGINNING phrase is
specified explicitly or implicitly, the following actions are taken
during the execution of an applicable OPEN statement:
Open Mode |
Action |
INPUT |
- Read header labels
- Execute beginning declarative
|
OUTPUT |
- Execute beginning declarative
- Write header labels
|
I/O |
- Read header labels
- Execute beginning declarative
- Write header labels
|
EXTEND |
- Read header labels
- Execute beginning declaratives (trailer labels treated as
header)
- Write header labels
|
-
If the ENDING phrase is
specified explicitly or implicitly, the following actions are taken
during the execution of an applicable CLOSE statement:
Open Mode |
Action |
INPUT |
- Read trailer labels
- Execute ending declarative
|
OUTPUT |
- Execute ending declarative
- Write trailer labels
|
I/O |
- Read trailer labels
- Execute ending declarative
- Write trailer labels
|
EXTEND |
- Execute ending declaratives
- Write trailer labels
|
-
The statement GO TO
MORE-LABELS is treated as a simple jump to the start of the
declarative procedure in which it appears.
The
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 © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
| Procedure Division - PERFORM - ROLLBACK |
|
Object COBOL Language Extensions | |