Default key parameters

Default keys are used by the z/TPFDF product to maintain file organization when LRECs are added to a subfile. They also can be used by application programs when reading LRECs from a subfile.

Default keys are optional in a DBDEF macro for all z/TPFDF files except B+Tree data files. Default keys are required for B+Tree data files because they are used by the z/TPFDF product to organize the B+Tree index.

If a default key is defined for one LREC ID, all LREC IDs in that file must have default keys defined. If a file has the default keys subtable defined and the application tries to add an LREC of an LREC ID that is not defined, an OPR-DB0117 system error is issued and the ECB exits.

Default keys are only appropriate for files that have UP or DOWN organization and should not be defined for:
  • P-type files
  • W-type files containing T-type LRECs (T-type DSECTs)
  • Add current files
  • Index files (including B+Tree index files)
  • Pushdown chaining files.
Read syntax diagramSkip visual syntax diagram,(PKY= primarykey,FLD= dataid,ORG=UPDOWNNOORG,KEY1=(PKY= primarykey,ORG=UPDOWN),,KEY n=(R= userfield,UPDOWNNOORG))
PKY=primarykey
Specifies the characteristics of the primary key (LREC ID) of the LREC, where primarykey is one of the following:
  • An equate that represents the primary key (for example, PKY=#GR00K80)
  • An explicit term that represents the primary key (for example, X'80').

Read-only default keys must be in the range X'01' - X'0F' and can be used only for read operations. Read-only default keys can be used to read any combination of keys in an LREC. Therefore, you do not have to read LRECs using the same default keys that you used to create the file. See z/TPFDF Programming Concepts and Reference for more information about using default keys to read LRECs.

Figure 1 shows a DBDEF that has two default keys defined. The first key, which has an LREC ID of X'80', is the default key that defines the layout and organization of the file that is created when records are added to the file. This key can also be used for read operations.

The second key has a primary key of X'06', which identifies it as a read-only default key. Primary key X'06' does not affect the layout or organization of the file.
Figure 1. Read-only default keys in the DBDEF
* FILE ID X'B073'
         DBDEF FILE=IR73DF,                                            *
               (PKY=#IR73K80,ORG=UP,         READ/ADD DEFAULT KEY      *
               KEY1=(PKY=#IR73K80),                                    *
               KEY2=(R=IR73NAM),                                       *
               KEY3=(R=IR73CTY),                                       *
               KEY4=(R=IR73SAL)),                                      *
               (PKY=#IR73K06,ORG=UP,         READ-ONLY DEFAULT KEY     *
               KEY1=(PKY=#IR73K06),                                    *
               KEY2=(R=IR73NAM),                                       *
               KEY3=(R=IR73CTY))                                       *
Note: Do not use LREC IDs X'00'–X'0F' and X'F0'–X'FF'. LREC ID X'00' cannot be used and the other LREC IDs are reserved by the z/TPFDF product.
FLD=dataid
Specifies the 2-byte data identifier (secondary key) of an extended LREC, where dataid is one of the following:
  • An equate that represents the 2-byte data identifier (for example, FLD=#GR00D1000)
  • An explicit term that represents the 2-byte data identifier (for example, X'1000').
Note:
  1. The dataid value must resolve to a value from X'0000'–X'FFFF'.
  2. The DID=dataid value in the detail or intermediate-index file must be the same as the FLD=dataid value in this index file.
ORG
Specifies the default organization for all fields for the specified primary key (PKY) in an LREC. If you specify an organization for KEY1, that organization overrides the ORG value and becomes the default. If you specify an organization for any other KEYn value, that organization overrides any previous defaults for that field. If you specify a NOORG value for any key, all keys that follow must be NOORG. For example, you cannot specify the following: 
KEY1=(PKY=#IR73DF,NOORG),
KEY2=(R=IR73NAM,UP)
UP
Arranges the fields in ascending order.
DOWN
Arranges the fields in descending order.
NOORG
Does not arrange the fields in any order.
KEYn
Specifies the organization of the specified key, where n is a number in the range 2 - 6.
Notes:
  • Keys must be specified sequentially; that is, if KEY1 and KEY4 are specified, you must specify KEY2 and KEY3.
  • Depending on the types of keys that are specified, you might be able to specify a total of 7 keys. If you try to specify a key that exceeds the maximum number of keys that are supported, an MNOTE is generated when the code is assembled.
R=userfield
Specifies the name of a user field, where userfield was previously defined in the DSECT macro. For example, 
 KEY2=(R=GR00NAM,UP)