Communications Blocks and Error Detection › Logical-Record Request Control (LRC) Block › Testing for the Logical-Record Path Status

Testing for the Logical-Record Path Status

Path statuses are issued during execution of the path selected to service a logical-record request. LRF returns a specific path status to the LRSTAT field of the program's LRC block to indicate the result of each logical-record request. You can examine this information to determine further processing.

Path Statuses

Path statuses are 1- to 16-byte character strings; they can either be standard or defined by the DBA in the subschema. The standard path statuses are:

• LR-FOUND—Indicates the logical-record request has been successfully executed. This status can be returned as the result of any LRF DML statement. When LR-FOUND is returned, the ERRSTAT field of the IDMS communications block contains 0000.
• LR-NOT-FOUND—Indicates the specified logical record cannot be found because either no such record exists or all such occurrences have already been retrieved. This status can be returned as the result of any LRF DML statement, 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—Indicates that either a logical-record request is issued incorrectly or an error occurs in the processing of the path selected to service the request.

Code Depends on Type of Error

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. If the error occurs in the logical-record path, the ERRSTAT field contains a status code issued by CA IDMS/DB with a major code from 00 to 19.

When the error occurs in the request itself, LRF returns the path status LR-ERROR to the LRSTAT field of the LRC block and places one of the following codes in the ERRSTAT field of the IDMS communications block:

Note: Any of these error-status codes can result from any of the logical-record DML statements. The only exception is code 2040, which applies only to the @OBTAIN NEXT DML statement.

2008

Either the named logical record is not defined in the subschema or the specified DML verb is not permitted with the named logical record.

2010

The program has attempted to access a logical record, but the subschema in use allows access to database records only.

2018

A path command has attempted to access a database record that has not been bound.

2040

The WHERE clause included in an @OBTAIN NEXT statement has directed LRF to a different path than did the WHERE clause in the preceding @OBTAIN statement for the same logical record. Either an @OBTAIN FIRST should have been issued instead of @OBTAIN NEXT or the WHERE clause is incorrect.

2041

LRF was unable to match the request's WHERE clause to a path to service the request.

2042

An ON clause included in the path by the DBA specified return of the LR-ERROR path status to the program.

2043

During evaluation of a WHERE clause, a program check has been recognized for one of the following reasons:

• A WHERE clause has specified that a packed decimal field be compared to a field that is not packed and that cannot be converted to a packed field due to the presence of nonnumeric data.
• Data in either variable storage or a database record does not conform to its description.

A path status of LR-ERROR is returned to the program unless the DBA has included an ON clause in the path to override this action.

2044

The WHERE clause in a logical-record request does not include a field of information required by the path.

2045

During evaluation of a WHERE clause, a program check has been recognized because a subscript value is either less than zero or greater than its maximum allowed value plus 1. A path status of LR-ERROR is returned to the program unless the DBA has included an ON clause in the path to override this action.

2046

A program check has been recognized during evaluation of a WHERE clause for one of the following reasons:

• An arithmetic overflow would occur (fixed point, decimal, or exponent).
• An arithmetic underflow would occur (exponent).
• A divide exception would occur (fixed point, decimal, or floating point).
• A significance exception has occurred.

A path status of LR-ERROR is returned to the program unless the DBA has included an ON clause in the path to override this action.

2063

A logical-record request's WHERE clause includes a keyword that is longer than the 32 characters allowed.

2064

A path command has attempted to access a CALC data item that has not been described properly in the subschema.

2072

Storage is not available for the work areas required to evaluate the logical-record request's WHERE clause.

Optional ONLRSTS Clause

In addition to directly testing the value of the LRSTAT field, you can include an ON clause that tests for a specific standard or DBA-defined path status for each DML statement; for example:

@OBTAIN NEXT,REC='EMPJOBLR',ONLRSTS='LR-NOT-FOUND',GOTO=RECERROR

The ONLRSTS clause tests for the standard path status of LR-NOT-FOUND. If LR-NOT-FOUND is returned, the branch imperative GOTO=RECERROR will be executed and the program will branch to the label RECERROR.

Syntax

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

Parameters

ONLRSTS=path-status

Tests the LRSTAT field 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-16 bytes under z/OS and OS/390 or 1-6 bytes under VSE) or program variable.

GOTO=branch-location

Specifies the program action to be taken if the specified path status is found in LRSTAT.

Note: For more information about LRF DML commands and clauses see Data Manipulation Language Statements.