CA-Datamacs/II CA-DATACOM/DB Interface › CA-Datamacs/II CA-DATACOM/DB Interface Statements › LOCATE

LOCATE

The purpose of the LOCATE statement is to cause a keyed transfer from the database index into a unique table input work area. This LOCATE command

Only issues record-at-a-time commands and is functionally equivalent to CA-DATACOM/DB's LOCATE commands, with extensions unique to CA Datamacs.

LOCATE
        {BACK | GE | LE | EQ | RANGE |
         NEXT-SEQ-INDEX |  NEXT-EQ   | NEXT-RANGE | NEXT-UNIQUE}
 
         table-name
 
        [KEY NAME IS   key-occurrence-name]
 
       [{USING KEY         key-value1|
         USING KEY RANGE   key-value1,key-value2|
         USING {ddname|dtfname} AS INPUT}]
 
        [NOT-FOUND     GO TO {paragraph-name | GOBACK | FINISH}
         AT-END        GO TO {paragraph-name | GOBACK | FINISH}
         KEYS-AT-END   GO TO {paragraph-name | GOBACK | FINISH}
         ON-DB-ERROR  {EQ|GT|LT|NE}  'db-error-code'
                       GO TO {paragraph-name | GOBACK | FINISH}
 
         WHEN  field-name  operator {field-name | work-area | literal}].

BACK

Retrieves index entries backwards from a previously established index location.

GE

Retrieves an index entry with a key value greater than or equal to the key value specified.

LE

Retrieves an index entry with a key value less than or equal to the key value specified.

EQ

Retrieves an index entry with a key value equal to the key value specified.

RANGE

Retrieves the first index entry within a range of key values.

NEXT-RANGE

Retrieves the next index entry in a previously established range of key values.

NEXT-UNIQUE

Retrieves the next sequentially unique index entry.

NEXT-EQ

Retrieves the next index entry with a key value equal to the key value specified.

NEXT-SEQ-INDEX

Retrieves the next index entry based on the next sequential index entry.

table-name

Specify the 1-to-32 character table occurrence name which must match a table name on a COPY TABLE statement.

KEY NAME IS

This entry identifies the Datadictionary 1-to-32 character key occurrence name to be used. If this keyword is not entered, the key name from the COPY TABLE statement is used, or, if no KEY NAME is specified, it will default to the first master key name related to this table as defined in Datadictionary.

USING KEY xxxxxxxx and USING KEY RANGE xxxxxxxx,yyyyyyyy

Identifies a key literal to be used when a single index entry or a range of index entries is to be retrieved. The maximum length of an individual key literal is that which can be coded within area B of the COBOL statement. See the function logic MOVE statement for more syntax rules concerning literals.

Numeric literals should be entered without any periods or commas. A trailing minus sign can be used to indicate a negative number. Alphanumeric literals should be enclosed in quotes. Any trailing blanks should be included in quotes. A hex value can be entered by enclosing the value with X'value'. Only valid hexadecimal digits are allowed; 0 to 9 and A to F. Packed numeric values should be entered as hex values, insuring the same sign is used as that specified in Datadictionary.

When a second key value must be entered to identify the range of a command, add the identifying keyword RANGE.

USING ddname/dtfname

AS INPUT Multiple key values can be stored in a sequential input file (QSAM for MVS) with a minimum index entry size of 80 bytes and a maximum index entry size of 256 bytes. This allows room for the required delimiter characters (for example, apostrophes for alpha, and so forth). Each key literal in one index entry must be separated by at least 1 space. Any mix of alpha, numeric, and hex is allowed. This entry specifies the file name of the data set. Seventeen key data sets are allowed with file names of DMIKEYS and DMIKY01 to 16.

For a command requiring a key value range, the second key value should be placed in a second index entry immediately following the first index entry. Basically, two key index entries would be required for one LOCATE range command.

There is no requirement for the keys file index entry size to match the key occurrence length as specified in Datadictionary. Partial keys are supported but key values longer than the key occurrence length will be rejected.

Only one USING statement can be used per LOCATE command (except USING KEY RANGE).

NOT-FOUND

Specify a paragraph name to branch to when the key is not found, the end of a range of keys is reached, or the next equal key was not found. The CA-DATACOM/DB return code 14 activates this option. FINISH is an internal paragraph name which will cause the job to end. The GOBACK option is only used when a LOCATE command has been executed because it is in a paragraph PERFORM'd by the CA-Datamacs/II EQUI-JOIN command. If the key is not found, specifying GOBACK will cause a return to the EQUI-JOIN command (see the EQUI-JOIN command for a more detailed explanation).

AT-END

Specify the paragraph name to branch to when the end of a key range is reached, or the end of the table is reached.

KEYS-AT-END

Specify the paragraph name to branch to when the input keys file reaches end of file. This option can only be used in conjunction with the USING {ddname|dtfname} AS INPUT option.

WHEN

Can be used to further qualify an index entry for selection by testing any field in the index entry for specific criteria. The WHEN must be placed after all other keywords. If the WHEN is used with a LOCATE EQ and the WHEN test fails, the NOT-FOUND option will be activated. Otherwise, the WHEN test would be applied until a match occurs or the end of the process occurs, at which time the AT-END option will be activated.