Data Manipulation Language Statements › Logical Record Clauses › ON Clause

ON Clause

The ON clause tests for a specific path status returned to indicate the result of a logical record request. If LRF returns the specified path status, the imperative statement included in the ON clause is executed. The imperative statement usually consists of a GOTO statement. If the path status is not returned, the imperative statement included in the ON clause is ignored.

Note: Only one ON clause can be coded per logical record DML statement; only one specific path status can be tested for.

Standard Path Statuses

Path statuses are issued during execution of the path selected to service the request. The following standard path statuses can be returned:

• LR-FOUND is returned when the logical-record request has executed successfully. LR-FOUND can be returned as the result of:
  • Any @OBTAIN LRF statement
  • Any of the other LRF statements containing a WHERE clause

  When LR-FOUND is returned, the ERRSTAT field of the IDMS communications block contains 0000.

• LR-NOT-FOUND is returned when the specified logical record cannot be found, either because no such record exists or because all such occurrences have already been retrieved. LR-NOT-FOUND can be returned as the result of any of the four LRF DML statements, provided that the path to which LRF is directed includes retrieval logic. When LR-NOT-FOUND is returned, the ERRSTAT field of the IDMS communications block contains 0000.
• LR-ERROR is returned when a logical record request is issued incorrectly or when an error occurs in the processing of the path selected to service the request. When LR-ERROR is returned, the type of status code returned to the program in the ERRSTAT field of the IDMS communications block differs according to the type of error:
  • When the error occurs in the logical-record request, the ERRSTAT field contains a status code issued by LRF (with a major code of 20). For a list of these codes, see Logical-Record Status Codes.
  • When an error occurs in logical-record path processing, the ERRSTAT field contains a status code issued by the DBMS (with a major code from 00 to 19). For a list of these codes, see ERRSTAT Field and Codes.

When accessing ASF-defined data tables, you should always check for all of the following path statuses:

• INVALID-DATA is returned when the data violates the definition-time selection criteria. For example, INVALID-DATA is returned when the selection criteria is WHERE STATE = 'MA' and the program tries to replace the state with 'NY'. When INVALID-DATA is returned, the ERRSTAT field in the IDMS communications block is set to 0000.
• DEFN-MISSING is returned when the record definition cannot be found. When DEFN-MISSING is returned, the ERRSTAT field in the IDMS communications block is set to 0000.
• OOAK-MISSING is returned when a one-of-a-kind record cannot be found. When OOAK-MISSING is returned, the ERRSTAT field in the IDMS communications block is set to 0000.
• SYNC-ERROR is returned when the time stamp in the catalog and the table definition do not match. When SYNC-ERROR is returned, the ERRSTAT field in the IDMS communications block is set to 0000.

The return of one or more of these path statuses indicates a fatal error. For more information, consult your DBA.

Syntax

►─┬─────────────────────────────────────────────┬────────────────────────────►
  └─ ,ONLRSTS=path-status,GOTO=branch-location ─┘

Parameters

ONLRSTS=path-status

Tests for a path status returned as the result of the logical-record request issued by the program. Path-status must be a quoted literal (1 to 16 bytes under z/OS or 1 to 6 bytes under z/VSE) or a program variable.

Note: In addition to testing for a specific path status (using ONLRSTS), your program should check for standard path statuses (for example, LR-NOT-FOUND and LR-ERROR, and path statuses for ASF defined tables if applicable) whenever the program issues a logical record request.

GOTO=branch-location

Specifies the program action to be taken if the indicated path status results from the logical-record request.

Example

The following ON clause causes the program to branch to the NOFFICE label when the path status specified in the variable NOOFF is met. NOOFF indicates a path status indicating that there are no offices that meet the criteria specified in the WHERE clause. Standard LRF path statuses are checked as well.

@OBTAIN REC=EMPJOBLR,                                        *
      ONLRSTS=NOOFF,GOTO=NOFFICE,                            *
      WHERE OFFICE-CODE-0450 EQ '0980'
CLC   LRSTAT,=CL16'LR-FOUND'
BE    CRDITREF
CLC   LRSTAT,=CL16'LR-ERROR'
BE    LRERRTN
CLC   LRSTAT,=CL16'LR-NOT-FOUND'
BE    LRNTFND