ON Clause

Data Manipulation Language Statements › DC Status Codes › ON Clause

ON Clause

The ON clause tests for a specific path status returned to indicate the result of the statement. If LRF returns the specified path status, the imperative statement included in the ON clause is executed; if the specified path status is not returned, the imperative statement included in the ON clause is ignored and IDMS-STATUS is performed.

If the DML statement with the ON clause is the object of a PERFORM, then the user should avoid scope problems by using the THROUGH option of the PERFORM statement.

A logical-record DML statement can include an ON clause only if the AUTOSTATUS protocol is in effect for the program. AUTOSTATUS automatically invokes an error-checking routine after every DML statement except IF. For more details, see Error Detection.

The ON clause tests for a standard or DBA-defined path status, which is in the form of a 1- through 16-character unquoted string. Path statuses are issued during execution of the path selected to service the request. The standard path statuses are:

LR-FOUND is returned when the logical-record request has been successfully executed. This status can be returned as the result of any of the four LRF DML statements. When LR-FOUND is returned, the ERROR-STATUS field of the IDMS communications block contains 0000.
LR-NOT-FOUND is returned when the logical record specified cannot be found, either because no such record exists or because all such occurrences have already been retrieved. This status 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 ERROR-STATUS field of the IDMS communications block contains 0000.
Note: A successful STORE can return LR-NOT-FOUND if its WHERE clause references a logical-record field and the STORE path performs no OBTAINs.
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 ERROR-STATUS field of the IDMS communications block differs according to the type of error:
- When the error occurs in the logical-record request, the ERROR-STATUS field contains a status code issued by LRF (major code of 20).
- When an error occurs in the logical-record path processing, the ERROR-STATUS field contains a status code issued by the DBMS (major code from 00 to 19). For more information about status codes, see Chapter 4:.

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, WHERE STATE EQ 'MA' and the program tries to replace the state with 'NY'). When INVALID-DATA is returned, the ERROR-STATUS 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 ERROR-STATUS 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 ERROR-STATUS 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 ERROR-STATUS field in the IDMS communications block is set to 0000. This applies to ASF tables only.

The return of any of these statuses indicates a fatal error; for more information, consult your DBA.

Syntax

►─── ON path-status imperative-statement ────────────────────────────────────►

Parameters

ON parameter

Tests for a path status returned as the result of the logical-record request issued by the program.

path-status A 1 through 16 character alphanumeric value.

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

Examples

The following statements use the path status LR-NOT-FOUND in two different ways. If LR-NOT-FOUND occurs following the initial statement, a LR-MISSING message is output; if LR-NOT-FOUND occurs in subsequent statements, an END-OF-LR message is output.

OBTAIN-FIRST-LR.
  OBTAIN FIRST EMP-JOB-LR
    WHERE OFFICE-CODE-450 EQ OFFICE-CODE-IN
    ON LR-NOT-FOUND
      GO TO LR-MISSING.
   .
   .
   .
OBTAIN-REST-LR.
  OBTAIN NEXT EMP-JOB-LR
    WHERE OFFICE-CODE-0450 EQ OFFICE-CODE-IN
    ON LR-NOT-FOUND
      GO TO END-OF-LR.
   .
   .
   .
   .
   .
  GO TO OBTAIN-REST-LR.

Status Codes

The following codes are returned to the ERROR-STATUS field in the IDMS or IDMS-DC communications block when an LR-ERROR path status is returned to the LR-STATUS field in the LRC block:

Status code	Meaning
2001	The requested logical record was not found in the subschema. (The path DML statement, EVALUATE, returns 0000 if true, and 2001 if false.)
2008	The named record is not in the subschema, or the specified request is not permitted for the named record.
2010	The subschema prohibits access to logical records.
2018	A path command has attempted to access a database record that has not been bound.
2040	The WHERE clause in an OBTAIN NEXT command directed LRF to a different processing path than did the WHERE clause in the preceding OBTAIN command for the same logical record.
2041	The request's WHERE clause cannot be matched to a path in the subschema.
2042	The logical-record path for the request specifies return of the LR-ERROR status.
2043	Bad or inconsistent data was encountered in the logical-record buffer during evaluation of the request's WHERE clause.
2044	The request's WHERE clause does not include data required by the logical-record path.
2045	A subscript value in a WHERE clause is either less than zero or greater than its maximum allowed value.
2046	A program check has revealed an arithmetic exception (for example, overflow, underflow, significance, divide) during evaluation of a WHERE clause.
2063	The request's WHERE clause contains a keyword that exceeds the 16-character maximum.
2064	The path command has attempted to access a CALC data item that has not been defined properly in the subschema.
2072	The request's WHERE clause is too long to be evaluated in the available work area.