GETKY - Get record with specified key

Macro type:

R for PARMOD=24 O for PARMOD=31

The GETKY macro retrieves the record whose primary or secondary key matches the value in the KEYARG field. The KEYARG field is addressed via the KEYARG operand of the FCB macro.

If no record with the specified key value is found, control is returned to the user program via the NOFIND address (see the EXLST macro, NOFIND operand, "EXLST - Define exit address list"). The pointer for the primary or secondary key is set to the value for which the search was made.

If a file contains several records with the same value for the primary or secondary key specified in the GETKY macro, either the first of these records (if the primary key is used) or the record to which the first pointer in the secondary index block refers (if a secondary key is used) is returned.

Format

Operation	Operands
GETKY	fcbadr / (1)    [,area / (0)]    [,LOCK / NOLOCK] [,AIX = NO /         YES,KEYNAME = name /          YES,KEYNMAD= adr] [,PARMOD = 24 / 31]

Operand descriptions

fcbaddr

Address of the FCB associated with the file to be processed.

If the file is to be read with the aid of a secondary key, the 31-bit interface of this FCB must be available.

(1)
The FCB address is stored in register 1.

area

Address of the area to which the record is to be transferred.; in locate mode, “area” is ignored.

(0)
The address of the area into which the record is to be transferred is stored in register 0.

LOCK

The block or record lock is to be retained after the macro has been executed (explicit lock).

NOLOCK
No explicit lock is set.

AIX

Specifies whether the record is to located via its primary key or via a secondary key.

= NO
The record is located via its primary key (default value).

= YES
This may be specified only if

• • • the 31-bit interface of the macro is generated (via the operand PARMOD=31 or the macro GPARMOD 31) and

    • the macro refers to a 31-bit FCB.

The record is located via the secondary key specified in the operand KEYNAME or KEYNMAD.

KEYNAME = name

Specifies the name of the secondary key via which the record is to be located.
“name” must be the name of a secondary key defined for the current file. The names of all secondary keys defined for a file can be determined by means of the SHOWAIX macro or the SHOW-INDEX-ATTRIBUTES command.

KEYNMAD = addr

Specifies the symbolic address (the name) of a field in which the user has stored the name of the secondary key via which the record is to be located.
When the macro is executed, the field with the symbolic address “addr” must contain the name of a secondary key defined for the current file.

PARMOD

Specifies the generation mode for the macro.

Default value:

the value predefined for the generation mode by means of the GPARMOD macro or preset by the assembler.

= 24
The object code generated can run only in the 16-Mb address space
(24-bit addressing only).

= 31
The object code generated can run in the 2-Gb address space
(24-bit or 31-bit addressing).

Programming note

The GETKY macro overwrites the contents of registers 0, 1, 14 and 15.