Usage Notes

Where to Code It

Records that are to be retrieved by using the DB-EXIT facility appear on dummy PATH parameters. Dummy PATH parameters specify a primary path id of two hyphens (--). The following considerations apply to dummy PATH parameters:

Records on dummy paths do not have to participate in set relationships with one another because the user controls record retrieval.
Dummy paths can be the only paths included in the database access run. In such cases, no values are set in the input buffer the first time CA Culprit enters the report's procedure logic. When CA Culprit encounters a DB-EXIT call, it retrieves records from the database and fills areas of the input buffer that are reserved on the dummy paths. After each report in the run has issued a DROP or TAKE command, CA Culprit reenters the procedure logic of the first report.
Note: A STOP-RUN command must be coded on a type 7 parameter to terminate a CA Culprit run that specifies only a dummy path.
Each dummy path parameter can specify a different logical record; each logical record can specify a WHERE clause. CA Culprit evaluates the WHERE clause when it executes the DB-EXIT call.

Automatic Record Retrieval

The DB-EXIT facility can also be used to retrieve records that appear on automatic retrieval paths. When this occurs, currency for the automatic retrieval path can be affected as follows:

If the DB-EXIT call references the record level corresponding to a record on the dummy path, currencies on automatic retrieval paths are not affected.
If the DB-EXIT call references the record level corresponding to a record on an automatic retrieval path, currencies on the automatic retrieval path can be changed. Care must be applied in such cases.

Each DB-EXIT call requires from one to six argument values. This table lists the arguments required for each particular DB-EXIT call.

Values of Arguments Associated with DB-EXIT:

Values of Arguments

Notes:

* Code a literal value in quotes or refer to an alphanumeric field equal to the literal.

# Literal values must end in a space.

The following suffix conventions are used for variable items in the above table. A suffix comprises all entries appearing after the last hyphen in a variable item; multiple entries indicate acceptable alternatives.

Notation	Meaning
-a	User-supplied value
-n	Numeric literal
-q	Value enclosed in quotation marks
-v	Variable data field containing an appropriate value or targeted to receive data
-x	Hexadecimal literal denoted as X'variable'

When CA Culprit processes a DB-EXIT call, it sets values in the reserved input buffer fields, IDMS-STATUS and LR-STATUS, as follows:

Values assigned to the IDMS-STATUS field differ under the following circumstances:
- If one or more arguments listed for a call is invalid, CA Culprit sets IDMS-STATUS to *00n, where n is the number of the first argument in which an error was detected.
- If all the arguments are valid and CA Culprit retrieves database records using the DB-EXIT facility, the IDMS-STATUS field is set to the status code returned by CA IDMS/DB. The following table defines the status codes most frequently returned.
  Note: For more information about error status codes, see the CA IDMS Messages and Codes Guide.

Code	Description
0000	No run-time errors occurred.
0326	Record was not found by using a CALC key, sort key, or index key.
0307	Record was not returned due to an end-of-set (or an end-of-area) condition, which results from an attempt to find the next or prior record in the set (or area).

Values assigned to the LR-STATUS field are set when the dummy path specifies a logical record. The field is set to the logical record status returned to CA Culprit by CA IDMS/DB.

Note: It is the user's responsibility to check IDMS-STATUS and LR-STATUS after each DB-EXIT call and to specify appropriate action in the procedure logic, as shown in the following example:

017010 IDMS-STATUS EQ '0307' DROP

Each DB-EXIT argument is described below:

ARG1

ARG1 is an alphanumeric literal or work field that determines the type of CA IDMS/DB retrieval command issued. The following table lists the possible values for ARG1 and associated commands, except for SET-VALUE.

When CA Culprit encounters SET-VALUE, it does not access the database. SET-VALUE sets a value in an input buffer field. This value is generally referenced in a WHERE clause for a logical record obtained in a subsequent LR-FIRST or LR-NEXT DB-EXIT call.

If SET-VALUE is used to set a value in a logical record, the SET-VALUE call must be performed before each LR-FIRST or LR-NEXT call. Otherwise, the DBA-specified retrieval path may cause the value to be overlayed.

ARG1	Retrieval Command Generated
DBKEY	OBTAIN database-record-name DBKEY IS dbkey-field-name
FORMAT-6	OBTAIN database-record-name WITHIN ix-set-name USING key-value-va
CALC	OBTAIN CALC database-record-name
DUP	OBTAIN DUP database-record-name (This command must be preceded by a CALC DB-EXIT call.)
OWNER	OBTAIN OWNER WITHIN set-name (Database-record-name in ARG2 is the owner record.)
NEXT	OBTAIN NEXT database-record-name WITHIN set-name
PRIOR	OBTAIN PRIOR database-record-name WITHIN set-name
FIRST	OBTAIN FIRST database-record-name WITHIN set-name
LAST	OBTAIN LAST database-record-name WITHIN set-name
NTH	OBTAIN occurrence-vn database-record-name WITHIN set-name
NEXT-AREA	OBTAIN NEXT database-record-name WITHIN area-name
PRIOR-AREA	OBTAIN PRIOR database-record-name WITHIN area-name
FIRST-AREA	OBTAIN FIRST database-record-name WITHIN area-name
LAST-AREA	OBTAIN LAST database-record-name WITHIN area-name
NTH-AREA	OBTAIN occurrence-vn database-record-name WITHIN area-name
IF-MEMBER	FIND CURRENT database-record-name IF set-name MEMBER
LR-FIRST	OBTAIN FIRST logical-record-name WHERE lr-boolean-expression
LR-NEXT	OBTAIN NEXT logical-record-name WHERE lr-boolean-expression

ARG2 Values

ARG2 values vary depending on the value of ARG1.

Note: See the explanation of suffix notation conventions above.

Database-record-name/logical-record-name level-n is an alphanumeric literal or work field that specifies the name of the database record or logical record to be obtained or tested. The following coding considerations apply to the record name:
- The record name must be defined to the subschema; record name synonyms are not allowed.
- If the record name is less than 16 characters, the name must be terminated by a space or followed immediately by a comma and level-n.
- The record name and record level, if specified, must be enclosed in single quotation marks.
Level-n is the level number of the database record or logical record to be obtained; the default is 1. If level-n is specified, it must be separated from the record name by a comma, with no intervening spaces, and must be terminated by a space. If ARG2 is a logical record, any WHERE clause associated with that record and level number is applied when an occurrence of that record is retrieved.
Field-name is the name of a field in the input buffer into which the value is to be moved by a SET-VALUE call. Field-name must be fully qualified if the field appears in more than one record or if multiple levels of a record are coded.

ARG3 Values

ARG3 values vary depending on the value of ARG1.

Note: See the explanation of suffix notation conventions above.

Dbkey-value-vx is either a 4-byte (8-digit) hexadecimal literal, denoted as X'variable', or a binary field that contains the db-key of the database record to be obtained.
Set-name/area-name is an alphanumeric literal or work field that contains the set name or area name of the database record to be accessed. The following coding considerations apply to set-name and area-name:
- If the name contains less than 16 characters, it must be terminated by a space.
- The name must be enclosed in single quotation marks.
Calc-key-field-name is the CALC-key field for the database record to be accessed. If the value of ARG2 contains a record-level qualifier, calc-key-field-name must be qualified with record-level-n also.
The CALC key can be a concatenated field that contains one or more noncontiguous database record fields; for example, FIELDA, FIELDB, FIELDC. CA Culprit can retrieve records with concatenated CALC keys by using the CALC DB-EXIT command and a CA Culprit module that performs variable-length moves (CULLUS43). CULLUS43 must be executed for each partial CALC key except the last; the module moves a value to each partial key field. The value for ARG3 in a CALC DB-EXIT call is the name of the last partial CALC-key field.

Note: For more information about procedure module CULLUS43, see the CA Culprit for CA IDMS User Modules Guide.
Field-value-qvnx is either an alphanumeric or numeric literal enclosed in single quotation marks or an alphanumeric or numeric work field. CA Culprit places the value of this argument in the input buffer field specified by field-name in ARG2 of a SET-VALUE call.
The following considerations apply depending on whether the field is alphanumeric or numeric:
- If the field is alphanumeric, field-value-qvnx must be the same length as the field identified by field-name.
- If the field is numeric, field-value-qvnx must have the same number of decimal positions as the field identified by field-name. Numeric fields with no decimal positions can be either 8- or 16-byte numeric work fields.

ARG4 Values

ARG4 values vary depending on the value of ARG1:

Key-field-name is the sort or index key field in the sorted or indexed set that contains the record to be accessed.
Calc-key-value-qvnx is either an alphanumeric or numeric literal enclosed in single quotation marks, an input field, or an alphanumeric work field that contains the value of the CALC key specified for ARG3. Calc-key-value-qvnx must be in exactly the same data format as the field in the record; that is, if the database field is a 6-byte packed decimal field, the supplied key value must be also.
Occurrence-vn is either a numeric literal or work field with no decimal places that contains the occurrence of the record to be accessed with the set or area.
Field-length-vn is either a numeric literal or work field with no decimal places that specifies the length of the field identified by field-name in a SET-VALUE call. The maximum value depends on field-data-type-qv, as described below and shown in the following table.

Specified Data Type
Maximum Field	Data Type	After Conversion
' '	Alphanumeric	256
'1'	Binary	4
'2'	Zoned	31
'3'	Packed signed	16

Note: Data types associated with a field specified in a SET-VALUE call must be enclosed in single quotation marks.

ARG5 Values

ARG5 values vary depending on the value of ARG1:

Key-value-qvnx is either an alphanumeric or numeric literal enclosed in single quotation marks, an input field, or a work field that contains the value of the indexed field of the record to be accessed. Key-value-qvnx must be in exactly the same data format as the indexed field in the record.
Calc-key-length-vn is a numeric literal or work field that contains the length of the CALC-key field specified for ARG3. This field must not contain or be defined with any decimal places.
Field-data-type-qv is a 1-byte alphanumeric literal or work field that specifies the data type of the field specified by field-name in a SET-VALUE call. Values for field-data-type-qv and corresponding maximum values for field-length-vn are shown in the earlier table.
CA Culprit converts numeric fields to the length and data type specified for field-length-vn and field-data-type-qv, respectively. To perform the conversion, the numeric field must have the following characteristics:
- The field must be either an 8- or 16-byte packed decimal value.
- The field must contain the same number of decimal positions as defined for field-name in ARG2 of a SET-VALUE call.

ARG6

ARG6 is the last argument when ARG1 specifies FORMAT-6. ARG6 is assigned key-length-vn, which is a numeric literal or work field that contains the length of the indexed field, as defined in IDD, for the set that contains the record to be accessed.