The START Statement
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



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
- 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.
- 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.
- 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.
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 four 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 four digits.
General Rules
- File-name-1 must be open in the INPUT or I/O mode at the time that the START
statement is executed. (See the topic The OPEN Statement.)
- 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 topic I-O Status in the chapter Procedure Division.)
The START statement never acquires, detects or releases record locks.
- The type of comparison specified by the relational operator in the KEY phrase
occurs between a key associated with a record in the file referenced by file-name-1
and a data item as specified in General Rule 6.
If the relational operator specifies that the
key must be equal to, greater than, or greater than or equal to the data item,
then
the file position indicator is positioned to the first logical record currently
existing in the file whose key satisfies the comparison.
If the relational operator specifies
that the key must be less than, or less than or equal to the data item, then
the file position indicator is positioned to the last logical record currently
existing in the file whose key satisfies the comparison.
- If the comparison is not satisfied by any record in the file, an INVALID
KEY condition exists. The execution of the START statement is unsuccessful,
and the position of the file position indicator is undefined. (See the topic
The INVALID KEY Condition in the chapter Procedure Division.)
- 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.
- 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 has no effect
on the comparison. (See the topic Comparison of Nonnumeric Operands in the
section Relation Condition in the chapter Procedure Division.)
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 topic
The INVALID KEY Condition in the chapter Procedure Division.)
- If the KEY phrase is specified, the comparison described in General Rule
7 uses the data item referenced by data-name.
- If the KEY phrase is not specified, the comparison described in General Rule
7 uses the data item referenced in the RECORD KEY clause associated with file-name-1.
-
After successful execution of the START statement,
a key of reference is established and used in subsequent Format 3 READ statements
as follows (see the topic The READ Statement):
- 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.
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 is 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 is passed to the starting point of the newly created thread. This work
area remains 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
you 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_ library routines.
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 are 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_ library
routines.
If the START statement fails, one of the return codes specified for the CBL_THREAD_
library routines 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 terminates with a run-time system 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.