Data Manipulation Language Statements › RETURN (DC/UCF)

RETURN (DC/UCF)

The RETURN statement retrieves the database key for an indexed record without retrieving the record itself, thus establishing currency in the indexed set. The record's symbolic key is moved into the data fields within the record in program variable storage. The contents of all non-key fields for the record are unpredictable after the execution of the RETURN verb. Optionally, the program can indicate that the symbolic key can be moved into some other specified variable storage location.

Current of index is established by:

• Successful execution of the RETURN statement, which sets current of index at the index entry from which the database key was retrieved.
• A status code of 1707 (end of index), which sets currency on the index owner. The DBMS returns the owner's database key.
• A status code of 1726 (index entry not found), which sets current of index as follows:
  • Between the two entries that are higher and lower than the specified value
  • After the highest entry, if the specified value is higher than all index entries
  • Before the lowest entry, if the specified value is lower than all index entries

You can use the RETURN statement in navigational and Logical Record Facility (LRF) environments.

Note: The DML precompiler views an incorrectly formatted RETURN statement as a PL/I RETURN function and does not flag the error. The incorrect RETURN DML statement is passed to the PL/I precompiler without expansion into a CALL statement, causing compile-time errors.

Syntax

►►─── RETURN CURRENCY SET (index-set-name) ─┬─────────┬───────────────────────►
                                            ├─ FIRST ─┤
                                            ├─ LAST ──┤
                                            ├─ NEXT ──┤
                                            └─ PRIOR ─┘

 ►─── INTO (db-key-field)─┬─────────────────────────────────┬──────────── ; ──►◄
                          └─ KEY INTO (symbolic-key-field) ─┘

Parameters

RETURN CURRENCY SET (index-set-name)

Identifies the indexed set from which the specified database key is to be returned.

FIRST

Retrieves the database key for the first index entry.

LAST

Retrieves the database key for the last index entry.

NEXT

Retrieves the database key for the index entry following current of index. If the current of index is the last entry, a status code of 1707 (end of index) is returned.

PRIOR

Retrieves the database key for the index entry preceding current of index. If the current of index is the first entry, a status code of 1707 (end of index) is returned.

INTO (db-key)

Identifies the field to which the database key is returned. Db-key is the symbolic name of a user-defined FIXED BINARY(31) field.

KEY INTO (symbolic-key)

Saves the symbolic key (CALC, sort, or index) of the specified record. Symbolic-key is the name of a user-defined alphanumeric field into which the symbolic key of the specified record will be returned. Symbolic-key must be large enough to contain the largest contiguous or noncontiguous symbolic key.

If the KEY INTO clause is not specified, the key will be moved into the corresponding fields in the user record's storage.

Syntax

►►─── RETURN USING (index-key-value) SET (index-set-name) ─────────────────────►

 ►─── INTO (db-key-field)─┬─────────────────────────────────┬───────────── ; ──►◄
                          └─ KEY INTO (symbolic-key-field) ─┘

Parameters

RETURN USING (index-key-value)

Retrieves the database key for the first index entry whose symbolic key equals index-key-value (If no such entry exists, a status of 1726 (index entry not found) is returned.):

SET (index-set-name)

Identifies the indexed set from which the specified database key is to be returned.

INTO (db-key)

Identifies the field to which the database key is returned. Db-key is the symbolic name of a user-defined FIXED BINARY (31) field.

KEY INTO (symbolic-key)

Saves the symbolic key (CALC, sort, or index) of the specified record. Symbolic-key is the name of a user-defined alphanumeric field into which the symbolic key of the specified record will be returned. Symbolic-key must be large enough to contain the largest contiguous or noncontiguous symbolic key.

If the KEY INTO clause is not specified, the key will be moved into the corresponding fields in the user record's storage.

Example

The following RETURN statement retrieves the database key for the first index entry in the EMP_LNAME_NDX set and moves the record's symbolic key into the INT_INDEX_KEY field.

RETURN CURRENCY SET (EMP-LNAME-NDX)
  FIRST INTO (INT-INDEX-KEY);

Status Codes

Upon completion of the RETURN function, the ERROR_STATUS field in the IDMS DB communications block indicates the outcome of the operation:

0000

The request has been serviced successfully.

0057

A retrieval-only run unit has detected an inconsistency in an index that should cause an 1143 abend, but optional APAR bit 216 has been turned on.

1701

The area in which the object record or its index owner participates has not been readied.

1707

Either the end of the indexed set has been reached or the indexed set is empty.

1725

Currency has not been established for the specified indexed set.

1726

Record not found.

1763

The indexed set has not been registered with IDMSIXUD for the subschema in use.