ON Command

Database Access Commands › Logical Record Facility Commands › ON Command

ON Command

Purpose

Indicates additional processing to be performed when a specified path status is returned by the Logical Record Facility following the execution of an LRF command.

Syntax

                                   ┌────────────────────────┐
►►─── ON path-status ─┬─ REPEAT. ──▼── command-statement. ──┴── END. ─────────►
                      │
                      └─ THEN ───┬── command-statement. ───────────────────┬──
                                 │       ┌──────────────────────┐          │
                                 └─ DO. ─▼─ command-statement. ─┴── END. ──┘

 ►────────────────────────────────────────────────────────────────┬───────────►◄
  ──┬─────────────────────────────────────────────────────────┬───┘
    └── ELSE ───┬── command-statement. ───────────────────┬───┘
                │       ┌──────────────────────┐          │
                └─ DO. ─▼─ command-statement. ─┴── END. ──┘

Parameters

path-status

Tests whether Logical Record Facility returned the named path status. Path-status specifies a 1- to 16-character DBA-defined or standard path status defined for the path selected to service the previous logical record request.

REPEAT command-statement

Specifies the commands to be executed as long as LRF returns the named path status.

REPEAT begins a processing loop; END terminates the loop. Each command is executed sequentially before the path status is tested again.

Command-statement can be any valid CA ADS process command, including another logical record command.

THEN command-statement

Specifies the commands to be executed if LRF returns the named path status.

Note: Multiple command statements must be preceded by DO and followed by END.

Command-statement can be any valid CA ADS process command, including another logical command.

ELSE command-statement

Specifies the commands to be executed if LRF returns the named path status.

Command-statement can be any valid CA ADS process command, including another logical record command.

Note: Multiple command statements must be preceded by DO and followed by END.

A given ON command statement can include only one ELSE clause, and that ELSE clause must match the most recent ON command not associated with an ELSE clause.

Usage

Path Statuses

A path status, in the form of a 1- to 16-character unquoted string, indicates the result of an LRF request. LRF can return either a path status defined by the DBA in the subschema associated with the dialog or one of the standard path statuses. The standard path statuses are:

LR-FOUND indicates that the logical record request was executed successfully. When LR-FOUND is returned, the dialog's error-status field contains 0000.
LR-NOT-FOUND indicates that the object record cannot be found either because no such record exists or because all occurrences of the record have already been retrieved. When LR-NOT-FOUND is returned, the dialog's error-status field contains 0000.
LR-ERROR indicates that a logical record request was issued incorrectly or that an error occurred in the processing of the path selected to service the request. When LR-ERROR is returned, the dialog's error-status field contains one of the status codes listed below.

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 object record is not in the dialog's subschema, or the specified request is not permitted for the named record
2010	The dialog's subschema prohibits access to logical records
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 dialog's subschema
2042	The logical record path for the request specifies return of the LR-ERROR status to the process
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	One of the following conditions occurred during the evaluation of a WHERE clause: Arithmetic overflow (fixed point, decimal, or exponent) Arithmetic inflow (exponent) Divide exception (fixed point, decimal, or floating point) Significance exception
2063	The request's WHERE clause contains a keyword that exceeds the 16-character maximum
2072	The request's WHERE clause is too long to be evaluated in the available work area

Considerations

One or more process commands can be specified to be executed once or iteratively, based on the returned path status. If an iterative sequence is used, the path status must change during processing to prevent uncontrolled looping.
ON commands can be nested to any level and can be included in IF and WHILE command structures.
When coding ON commands, indentation should be used wherever possible to make the statement more readable and to ensure that the required clauses are properly matched.

Examples

The following examples test the path status before performing additional processing.

Example 1: Displaying messages when a record is not found

The statements in the following example display messages based on the path status returned after an attempt is made to retrieve a CUST-ORDER-LR logical record:

OBTAIN CUST-ORDER-LR
  WHERE CUST-NUMBER EQ '1234567890'.
ON NO-CUSTOMER
THEN
    DISPLAY MSG TEXT IS 'CUSTOMER NOT ON FILE'.
ON NO-ORDER
THEN
    DISPLAY MSG TEXT IS 'CUSTOMER HAS NO ORDERS'.
ON LR-NOT-FOUND
THEN
    DISPLAY MSG TEXT IS 'RECORD NOT FOUND'.

Example 2: Retrieving a record after a specified record

The statements in the following example retrieve VENDOR-LR logical records as long as the path status returned after the previous retrieval is VENDOR-CODE-010:

OBTAIN FIRST VENDOR-LR.
ON VENDOR-CODE-010
  REPEAT.
    OBTAIN NEXT VENDOR-LR.
    .
    .
    .

  END.
DISPLAY.

More information:

Conditional Commands