CA Culprit in the CA IDMS/DB Environment › KEY and KEYFILE Parameters › KEY Parameter

KEY Parameter

Purpose

The KEY parameter identifies either a field or column name and associated key values.

Syntax

    Col
    2
    ▼
►►─ KEY ─┬┬─────────────────────────────────────────────────────────────────┬─►
         │└ key-field-name ┬───────────────────────────────────────────────┬┘
         │                 └( database-record-name OF logical-record-name )┘
         └─ DBKEY ─┬─ database-key ────────────┬──────────────────────────────
                   └─ page-number line-number ─┘

 ►── key-value-expression  ─┬─────────────────────────────────────────────────►◄
                            │
                            │
  ──────────────────────────┘

Expansion of Key-value-expression

         ┌─────────────┐
►►─┬─ ( ─▼─ key-value ─┴─ ) ────────────────────────────────┬─────────────────►◄
   └─ ( ─┬─ start-key-value ─┬─ TO ─┬─ end-key-value ─┬─ ) ─┘
         └─ FIRST ───────────┘      └─ LAST ──────────┘

Syntax Rules

KEY

Specifies the type of parameter; it must be coded starting in column 2.

key-field-name

Specifies the name of the key field for the entry record. It is either a CALC-key field, index-key field, logical record key field, or a table column, as follows:

• The field is a CALC-key field if the entry record has a CALC location mode and is not accessed by using an index.
• The field is an index-key field if the entry record is accessed by using an index.
• The field is a logical record key field if the entry record is a logical record. A logical record key field can be the name of any field defined for the logical record.
• The field is a table column in a CA Culprit run that accesses one or more tables. Key-field-name must be the same as the column specified in the WHERE clause on the INPUT parameter.

database-record-name OF logical-record-name

Is required under the following conditions:

• If key-field-name occurs in more than one database record within a logical record.
• If key-field-name references a column that occurs more than once in a table view.

If specified, this expression must be enclosed in parentheses.

When the key field references a column in a table view, database-record-name exists in the form RFUR-nnnnnn-DATA where nnnnnn is the table definition number (TDN) of the source table. The TDN appears on ASF's Table Definition screen. It also appears as the numeric portion of the subschema value assigned to the source table in CA Culprit's Input Parameter Listing.

In addition, logical-record-name is the logical record name assigned to the table view. The name appears in ASF's Extended Table Definition screen. It also appears in the LR-NAME field in CA Culprit's Input Parameter Listing.

key-value-expression

See expanded syntax shown below:

key-value

Identifies a key value or a list of key values for entry record occurrences. Each value in a list must be separated by a space or a comma and the list must be enclosed in parentheses. Key values must be either CALC, index, logical record, or table column keys. When key-value refers to a logical record or a table column, CA Culprit automatically substitutes the value of key-value for KEY-VALUE on the PATH or INPUT parameter.

Key-value is either an alphanumeric, numeric, or hexadecimal value, depending on the definition of key-field-name:

• An alphanumeric value is a 1- to 64-character literal enclosed in single quotation marks. If the length of the literal (excluding the quotation marks) is longer than the field length defined for key-field-name, CA Culprit truncates excess characters on the right. If the length of the literal is shorter, CA Culprit pads the literal on the right with blanks.
• A numeric value is defined as either a 1- to 31-digit literal if the entry record is a database record, or a 1- to 15-digit literal if the entry record is a logical record. The literal can contain a trailing or an embedded decimal point but not a leading decimal point.

  CA Culprit automatically converts key-value to the numeric field format for key-field-name in the subschema. If the number of decimal places specified for key-field-name in the subschema differs from the number specified for the numeric literal, CA Culprit truncates or expands the literal value to correspond with the subschema definition. If the number of digits specified for the numeric literal is more than the number defined for key-field-name in the subschema, CA Culprit truncates the numeric literal on the left. If the number of digits is less, CA Culprit pads the literal value on the left with zeros.

• A hexadecimal value is preceded by an X and is enclosed in single quotation marks; for example, X '00104B1A'. The length of the literal must contain exactly the same number of bytes defined for key-field-name in the subschema.

start-key-value

Specifies the starting value for a range of indexed records. Coding specifications for start-key-value are the same as for key-value.

FIRST

A keyword that specifies the first value in the indexed set.

end-key-value

Specifies the ending value for a range of indexed records. Coding specifications for end-key-value are the same as for key-value.

LAST

A keyword that specifies the last value in the indexed set.

The range must be enclosed in parentheses and the values that specify the range must be separated by the keyword TO. The values specified for the start key and end key do not have to exist in the database; the values only serve to establish a range within the index.

DBKEY

A keyword indicating that database key values are used to access database entry records. DBKEY can be specified for database entry records stored in any location mode (that is, CALC, VIA, or DIRECT), but cannot be specified for an indexed database entry record or for a logical record.

database-key

Specifies the value of the db-key. It is an 8-character hexadecimal literal enclosed in single quotation marks and preceded by an X; for example, X'00104B1A'. The first six digits are the CA IDMS/DB page number of the database entry key; the last two digits are the line number. The hexadecimal value must include any leading zeros.

page-number/line-number

Specifies two numeric literals that, respectively, represent the page number and line number of the database key. The values must be separated by either a blank space or a comma.

Note: Users with schemas that employ a floating radix point must specify db-key values as hexadecimal literals.

Usage

The following considerations apply to the KEY parameter:

• Any number of KEY parameters can be entered in a CA Culprit run.
• KEY parameters should be coded after the INPUT parameter; otherwise, CA Culprit issues a warning (W-level) message.
• If more than one KEY parameter is entered, each KEY parameter must specify the same key field.

Examples

Sample KEY parameters are shown and described below.

Example 1: KEY Parameter with CALC-key Values

PATHAA DEPARTMENT EMPLOYEE
KEY DEPT-ID (0100 3200 5100)

The KEY parameter identifies DEPT-ID as the key field for the DEPARTMENT entry record. CA Culprit accesses only those department record occurrences that have a DEPT-ID value of 0100, 3200, or 5100. The key values must be CALC-key values because the entry record on the PATH parameter has a CALC location mode and is not followed by an index set name.

An alternative coding method appears below:

PATH DEPARTMENT EMPLOYEE
KEY DEPT-ID 0100
KEY DEPT-ID 3200
KEY DEPT-ID 5100

Example 2: KEY Parameter with Index-key Values

PATH EMPLOYEE(EMP-LNAME-NDX) COVERAGE
KEY  EMP-LAST-NAME (FIRST TO 'G')

The KEY parameter instructs CA Culprit to access all EMPLOYEE record occurrences with an EMP-LAST-NAME value within the specified range of index key values. EMP-LAST-NAME must be an index key field because the PATH parameter specifies an index set name after the entry record. The range expression, FIRST TO 'G', includes all records that begin with letters A through F, starting with the first record in the index. 'G' serves only to establish the range; it is not an actual value in the index.

Example 3: KEY Parameter with Logical Record Key Values

PATHAA DEPT-EMP-LR WHERE EMP-LAST-NAME EQ KEY-VALUE
KEY EMP-LAST-NAME (EMPLOYEE OF DEPT-EMP-LR) ('BREEZE' 'CRANE')

Occurrences of the DEPT-EMP-LR logical record are retrieved when the value of EMP-LAST-NAME in the EMPLOYEE database record of the logical record equals 'BREEZE ' or 'CRANE '. The field length of EMP-LAST-NAME is 15 bytes, so CA Culprit pads the values supplied on the KEY parameter with blanks. The information in parentheses following EMP-LAST-NAME on the KEY parameter implies that EMP-LAST-NAME is defined for more than one database record in the logical record.

Example 4: KEY Parameter and Data Table Columns

 INPUT TABLE=SALARY TYPE=COPY
*    WHERE DEPT-NAME EQ KEY-VALUE
 KEY DEPT-NAME ('PERSONNEL')

DEPT-NAME is the name of a column in table SALARY. In this example, CA Culprit accesses all rows in the table that specify 'PERSONNEL'.

Example 5: KEY Parameter with Db-key Values

KEY DBKEY 19035 02
KEY DBKEY 1245 36

CA Culprit retrieves two database record occurrences by their db-key page and line numbers. The first record occurs on page 19035, line 2, and the second is located on page 1245, line 36.

Alternatively, the db-keys can be coded as hexadecimal literals:

KEY DBKEY X'004A5B02'
KEY DBKEY X'0004DD24'

The first six digits of each literal represent the page number; the last two digits represent the line number. Both literals include leading zeros.