DBUKY-generate a unique key for use in logical records

Use this macro to generate a unique key in the SW00SR slot for the subfile.

Format

REF=dsectvv

specifies the file that you want to access, where dsectvv is the 6-character DSECT name and an optional 1- or 2-character suffix.

REF=refname

specifies the name associated with the file that you want to access, where refname is a label that references the name in one of the following formats:

refname: is the label of an 8-byte field that contains the reference name.
A/refname: is the label of a 4-byte field that contains the storage address of an 8-byte field that contains the reference name.

The reference name can be any 8-byte value that is unique for the current ECB.

FILE=dsect

specifies the file or subfile that you want to access, where dsect is the 6-character DSECT name.

NOPGM

specifies not to change the program stamp in a block when filing it.

SUFFIX=char

allows you to use the same DSECT to map two different areas of storage, where char is the suffix character.

Entry requirements

None.

Normal return

The new unique key value is returned in the 4-byte SW00UKY field of the SW00SR.

Error return

See Identifying Return Indicators and Errors for information about how to check the error indicators.
A zero value in the SW00UKY field of the SW00SR indicates an error.

Programming considerations

The optional 2-character version on the REF parameter allows you to access more than one subfile in the same file at the same time. For example, you can code REF=IR71DF01,ALG==C"A" to access subfile A and REF=IR71DF02,ALG==C"B" to access subfile B.
If you specify a label, the label must be more than 3 characters long.
The contents of register 14 (R14) and R15 cannot be predicted across a TPFDF macro call.
The contents of R3, which contains the storage address of the SW00SR slot, are used by TPFDF macro calls. Do not change the value of R3 between macro calls unless you save the value after each macro call and restore the value before each macro call.
The value that is returned in the SW00UKY field of the SW00SR is only valid immediately after the DBUKY macro is processed. Subsequent TPFDF macros reuse and overwrite this field.
In order to use the unique key feature, you need to add an additional 18-byte unique key extension after the standard TPF and TPFDF block headers. In addition, SW00OP3 #BIT7 must be set to 1 in the DSECT.
See Grouping LRECs Together Using the Unique Key Facility for more information about using unique keys.

Examples

The following example generates a unique key value for file GR34DF. The value is placed in the SW00UKY field in the SW00SR slot.

DBUKY REF=GR34DF

The following is an example of a header expanded by 18 bytes so that the unique key feature can be used.

IRXXHDR& DS  CL16         STANDARD FILE HEADER
         DS  CL10         STANDARD TPFDF HEADER
         DS  CL18         UNIQUE KEY HEADER EXTENSION

Related information

DBKEY-Activate a Key List.