DBKEY: Activate a key list

Use this general macro to activate a key list that is used by subsequent macros that access the specified file. See Specifying logical records (LRECs) using keys for more information about keys.

Last updated

  • Changed for PUT06.
  • Changed for PUT05.
  • Changed for PUT04.
  • Changed for PUT02.
  • Changed for PUT00.

Format

Read syntax diagramSkip visual syntax diagramDBKEY REF= dsectvvREF= refname,FILE= dsectFILE= dsect,R3= address,KEYLIST= keyloc,AMODE= amodedef,AMODE=3164,ERROR= spmlbl,ERRORA= asmlbl,NOPGM
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
The label of an 8-byte field that contains the reference name.
A/refname
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.
R3=address
Specifies the location of the SW00SR slot for this subfile, where address is the label of a field that contains the address of the SW00SR slot. Register 3 (R3) will be loaded with this address. If R3 already contains the address of the SW00SR slot before this macro is called, you do not need to specify the R3 parameter.
Note: Do not use this and the FILE parameter; they are provided only for migration purposes. Use the REF parameter to specify the file that you want to access.
KEYLIST=keyloc
Specifies a key list that you want to use with this macro, where keyloc is one of the following conditions:
  • A register that contains the address of the key list
  • A label in one of the following formats:
    keyloc
    A label indicating the address of the key list.
    A/keyloc
    The label of a 4-byte field that contains the storage address of the key list.

For information about how to set up a key list, see Setting up and using a key list.

AMODE
Specifies the addressing mode that is being used when the macro is called. Specify one of the following values:
amodedef
The value that is specified by the AMODE parameter on the BEGIN macro. If the AMODE parameter is not specified on the BEGIN macro, the default value is 31.
31
Indicates that 31-bit addressing mode is in use.
64
Indicates that 64-bit addressing mode is in use.
ERROR=spmlbl
Branches to the specified location if a serious error is detected when processing the macro, where spmlbl is a z/TPFDF structured program macro (SPM) label defined with the #LOCA macro. For more information about serious errors, see Identifying return indicators and errors. For more information about the #LOCA macro, see z/TPF and z/TPFDF Structured Programming Macros.
ERRORA=asmlbl
Branches to the specified location if a serious error is detected when processing the macro, where asmlbl is an assembler label. For more information about serious errors, see Identifying return indicators and errors.
NOPGM
Specifies not to change the program stamp in a block when filing it.

Entry requirements

None.

Return conditions

For information about how to check the error indicators, see Identifying return indicators and errors.

Programming considerations

  • For information about macro register conventions, see Assembler program register conventions.
  • The contents of R3, which contains the storage address of the SW00SR slot, are used by z/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.
  • If register R8 is not used as a base register, its contents are unknown upon return from this macro. If R8 is used as a base register, its contents are unchanged.
  • All data, address reference fields, and storage areas that are passed to the z/TPFDF product assembler macros must reside below 2 GB in storage unless otherwise noted.
  • 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 key list can define as many as 180 key parameters or it can indicate that default keys will be used. See Setting up and using a key list for more information about defining a key list.
  • Several macros provide a KEYLIST parameter, which generates an internal DBKEY macro.

Examples

See Using a key list with the DBSETK macro for an example of activating key list with the DBKEY macro.

Related information

See the following macros for more information: