Data Manipulation Language Statements › Logical-Record Clauses (WHERE and ON) › 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.

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

Standard Path Statuses

Standard path statuses are as follows:

• LR_FOUND—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 in the IDMS communications block contains 0000.
• LR_NOT_FOUND—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 in 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—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 error-status code returned to the program in the ERROR_STATUS field in the IDMS DB communications block differs according to the type of error:
  • When the error occurs in the logical-record request, the ERROR_STATUS field contains an error-status code issued by LRF (major code of 20).
  • When an error occurs in logical-record path processing, the ERROR_STATUS field contains an error-status code issued by the DBMS (major code from 00 to 19).

    Note: For more information about error-status codes, see Communications Blocks and Error Detection.

Syntax

►►─── ON LR_STATUS (path-status)  imperative-statement;───────────────────────►◄

Parameters

path-status

Names the path status that will be tested. Path-status must be a 1- to 16-character alphanumeric value.

imperative-statement

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

Example

The following statements use the path status LR_NOT_FOUND in two different ways. If LR_NOT_FOUND occurs following the initial statement, an LR_MISSING message is output; if LR_NOT_FOUND occurs in subsequent statements, an END_OF_LR message is output.

OBTAIN FIRST RECORD (EMP_JOB_LR)
  WHERE (OFFICE_CODE_0450 EQ OFFICE_CODE_IN);
  ON LR_STATUS (LR_NOT_FOUND)
   CALL LR_MISSING;
 .
 .
 .
OBTAIN NEXT RECORD (EMP_JOB_LR)
  WHERE (OFFICE_CODE_0450 EQ OFFICE_CODE_IN);
  ON LR_STATUS (LR_NOT_FOUND)
   CALL END_OF_LR;
 .
 .
 .
CALL OBTAIN_REST_LR;

Status Codes

The following codes are returned to the ERROR_STATUS field in the IDMS DB or IDMS DC communications block when an LR_ERROR path status is returned to the LR_STATUS field in the LRC block:

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.