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.

MF The START statement initiates execution of a thread, either synchronously or asynchronously.

General Formats for Format 1 (Relative Files)


Syntax for General Format for Format 1 (Relative Files) for the START statement

General Formats for Format 2 (Indexed Files)


Syntax for General Format for Format 2 (Indexed Files) for the START statement
MF 

General Formats for Format 3 (Threads)


Syntax for General Format for Format 3 (Threads) for the START statement

Syntax Rules for All Formats (Relative and Indexed Files)

  1. File-name-1 must be the name of a relative or indexed file.
  2. File-name-1 must be the name of a file with sequential or dynamic access.
  3. Data-name-1 can be qualified.
  4. The INVALID KEY phrase must be specified if no applicable USE procedure is specified for file-name-1.

    OSVSVSC2MF This rule is not enforced.

  5. MF THEN may be used instead of THAN.

Syntax Rules for Format 1 (Relative Files)

  1. 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.

Syntax Rules for Format 2 (Indexed Files)

  1. 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.
  2. MF Split-key-name-1 can reference one or more data items, and is specified as a record key associated with file-name-1.
  3. MF WITH SIZE specifies the number of characters in the key to be used in the positioning process.
  4. MF Identifier-1 must be the name of an elementary integer data item when used with the WITH SIZE phrase.
  5. When the DIALECT"RM" or DIALECT"ACU" directives are in effect, the data-name-1 or split-key-name-1 specified in the KEY phrase is implicitly qualified by the file-name-1 specified in the START statement when file-name-1 is not already explicitly specified as the final qualifier of data-name-1 or split-key-name-1. For any other dialect, data-name-1 or split-key-name-1 may need to explicitly specify file-name-1 as the final qualifier to satisfy uniqueness of reference rules.
MF 

Syntax Rules for Format 3 (Threads)

  1. MF Literal-1 must be a nonnumeric literal and cannot be a figurative constant.
  2. MF Identifier-1 must be defined as an alphanumeric data item such that its value can be a COBOL or non-COBOL program-name.
  3. MF 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.
  4. MF Thread-pointer-1 must be defined as USAGE THREAD-POINTER.
  5. MF Identifier-4 must be defined as an integer data item that has a length of at least four digits.

General Rules for All Formats (All Files)

  1. 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.)
  2. If the KEY phrase is not specified, the relational operation IS EQUAL TO is implied.
  3. 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.)
  4. MF The START statement never acquires, detects or releases record locks.

General Rules for Format 1 (Relative Files)

  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 6.
    1. ANS85  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.

    2. MF  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.
    3. 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.)
  2. 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.

General Rules for Format 2 (Indexed Files)

  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.)
    1. ANS85 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.

    2. MF 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.
    3. 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.)
  2. If the KEY phrase is specified, the comparison described in General Rule 7 uses the data item referenced by data-name.
  3. 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.
  4. 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):
    1. If the KEY phrase is not specified, the prime record key specified for file-name-1 becomes the key of reference.
    2. If the KEY phrase is specified, and data-name-1

      MF or split-key-name-1

      is specified as a record key for file-name-1, that record key becomes the key of reference.

    3. If the KEY phrase is specified, and data-name-1

      MF 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

      MF or split-key-name-1

      becomes the key of reference.

  5. If execution of the START statement is not successful, the key of reference is undefined.
MF 

General Rules for Format 3 (Threads)

  1. MF 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.
  2. MF 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.
  3. MF 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.
  4. MF 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.
  5. MF 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.
  6. MF 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.
  7. MF 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.
  8. MF 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.
  9. MF 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:
    1. 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.
    2. 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.
    3. Otherwise, the run-unit terminates with a run-time system error.
  10. MF If the START statement is successful, the following occurs in the order specified:
    1. If the STATUS phrase is specified, ZERO is moved to identifier-4.
    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 START statement and the ON EXCEPTION phrase, if specified, is ignored.
Parent topic: Statements
Related information
The OPEN Statement
I-O Status
The INVALID KEY Condition
Relation Condition
The READ Statement