bdfp1m0rProgramming Concepts and Reference

Setting Up and Using a Key List

A key list contains information that allows the TPFDF product to search for logical records (LRECs) by comparing criteria supplied by the application program with specified data fields in the LREC. The criteria specified in a key list is the same criteria that you can specify with the KEYn parameters; that is:

As mentioned previously, there are certain operations that you can only use with key lists, as follows:

The following are the different types of key lists:

A selection key list is used to specify criteria used when searching a subfile. Only LRECs that match the criteria will be processed.

A default-key key list is used to specify which set of keys defined in the DBDEF should be used when searching a subfile. A prototype LREC with target values for the key fields is used to locate LRECs that match the criteria, and only those LRECs are processed.

A modification key list is used to define rules for updating LRECs in a subfile. Fields in LRECs in a subfile are updated based on values and modification operations specified in the key list.

A sort/merge key list is used to specify how to sort LRECs into the output file on a DBSRT or DBMRG macro, or a dfsrt or dfmrg function.

Setting Up a Key List

You can set up a key list in one of the following ways:

The first two bytes of a key list (field SW01NKY) specifies the number of keys in the key list. The maximum value for SW01NKY differs for each type of key list as follows:

Type of Key List Maximum Number of Keys
Selection key list 180 keys
Default-key key list 1 key
Modification key list 6 keys
Sort/merge key list 180 keys

Field SW01NKY is followed by the keys, each of which is 12 bytes, as follows:

Field Number of Bytes Description
SW01DIS 2 bytes Displacement into the LREC
SW01LEN 2 bytes Length of the key
SW01CON 1 byte Condition that must exist for the match to be successful
SW01MSK 1 byte One of the following:
  • 1-byte mask
  • Default key LREC ID, used with default-key key lists.
SW01SEA 4 bytes One of the following:
  • Search argument
  • Pointer to prototype LREC, used with default-key key lists.
SW01ID1 1 byte Option indicators
SW01ID2 1 byte One of the following:
  • Boolean connector
  • Modification operation, used with modification key lists.

See DBSETK-Setting Up a Key in a Key List and df_setkey-Setting Up a Key in a Key List for information about the values that you can specify for fields SW01CON, SW01ID1, and SW01ID2.

Using a Key List

The following example describes one possible use of a key list for the DBRED macro. Use the same coding techniques, as appropriate, for the other macros or functions that allow the use of key lists.

In many instances an application has to verify the database according to given conditions. The more options that are available, the more DBRED macros using KEYn parameters are necessary to handle the requests. Consequently, the program becomes unstructured and generates many bytes of object code for each DBRED macro.

The key list technique allows you to define active keys at run time according to specific needs. The following example shows the advantages of this technique.

Processing Using Keyn Parameters

If, for example, you want to compare field EBW000(4) with field IR73FLD at displacement 6 in an LREC without using a key list, you have to call a DBRED macro for each condition compared:

#IF CLC MI0ACC+10(2),EQ,=C'GT'
   DBRED REF=IR73DF,KEY1=(PKY=#IR73K80),                         *
         KEY2=(R=IR73FLD,S=EBW000,C=GT),UP
#ELIF CLC,M10ACC+10(2),EQ,=C'GE'
   DBRED REF=IR73DF,KEY1=(PKY=#IR73K80),                         *
         KEY2=(R=IR73FLD,S=EBW000,C=GE),UP
#ELIF CLC,M10ACC+10(2),EQ,=C'EQ'
   DBRED REF=IR73DF,KEY1=(PKY=#IR73K80),                         *
         KEY2=(R=IR73FLD,S=EBW000,C=EQ),UP
#ELIF CLC,M10ACC+10(2),EQ,=C'NE'
   DBRED REF=IR73DF,KEY1=(PKY=#IR73K80),                         *
         KEY2=(R=IR73FLD,S=EBW000,C=NE),UP
#ELIF CLC,M10ACC+10(2),EQ,=C'LT'
   DBRED REF=IR73DF,KEY1=(PKY=#IR73K80),                         *
         KEY2=(R=IR73FLD,S=EBW000,C=LT),UP
#ELIF CLC,M10ACC+10(2),EQ,=C'LE'
   DBRED REF=IR73DF,KEY1=(PKY=#IR73K80),                         *
         KEY2=(R=IR73FLD,S=EBW000,C=LE),UP
#EIF

Processing Using a Key List

If you set up a key list, the amount of object code generated is greatly reduced. As mentioned previously, you can set up the key list by manually coding the key list structure or by using the DBSETK macro or df_setkey function.

The following shows the DBRED example using the manual method:

SW01SR   REG=R5
LA   R5,EBX000                    LOAD BASE OF KEY LIST
XC   EBX000(L'SW01NKY+2*L'SW01KIT),EBX000  CLEAR KEY LIST AREA
MVC  SW01NKY,=H'2'                SET UP 2 KEYS
MVC  SW01DIS,=H'2'                DISPLACEMENT TO PRIMARY KEY
MVC  SW01LEN,=H'1'                PKY LENGTH=1
MVI  SW01CON,#DF_EQ               SET EQ MATCH
MVI  SW01MSK,#IR73K80             SET MASK=PKY
MVI  SW01ID1,#DF_UP+#DF_CONST     UP ORG + USE CLI WITH MASK
MVI  SW01ID2,#DF_AND              AND CONNECTOR
LA   R5,L'SW01KIT(,R5)            SET TO SECOND KEY
MVC  SW01DIS,=H'6'                DISPLACEMENT TO SECOND KEY
MVC  SW01LEN,=H'4'                LENGTH OF KEY
LA   R14,EBW000                   ADDR OF 2ND KEY SEARCH ARG
ST   R14,SW01SEA                  AND STORE
MVI  SW01ID1,#DF_UP               UP ORGANIZATION
#IF    MI0ACC+10(2),EQ,=C'GT'     INPUT = GREATER THAN?
  MVI    SW01CON,#DF_GT           SET UP CONDITION CODE
#ELIF  MI0ACC+10(2),EQ,=C'GE'     INPUT = GREATER OR EQUAL?
  MVI    SW01CON,#DF_GE           SET UP CONDITION CODE
#ELIF  MI0ACC+10(2),EQ,=C'EQ'     INPUT = EQUAL?
  MVI    SW01CON,#DF_EQ           SET UP CONDITION CODE
#ELIF  MI0ACC+10(2),EQ,=C'NE'     INPUT = NOT EQUAL?
  MVI    SW01CON,#DF_NE           SET UP CONDITION CODE
#ELIF  MI0ACC+10(2),EQ,=C'LT'     INPUT = LESS THAN?
  MVI    SW01CON,#DF_LT           SET UP CONDITION CODE
#ELIF  MI0ACC+10(2),EQ,=C'LE'     INPUT = LESS OR EQUAL?
  MVI    SW01CON,#DF_LE           SET UP CONDITION CODE
#EIF
DBKEY  REF=IR73DF,KEYLIST=EBX000  ACTIVATE THE KEY LIST
DBRED  REF=IR73DF

Using a Key List with the DBSETK Macro

The following shows the DBRED example using the DBSETK macro:

SW01SR REG=R5
LA     R5,EBX000                    LOAD BASE OF KEY LIST
XC     EBX000(L'SW01NKY+2*L'SW01KIT),EBX000   CLEAR KEY LIST AREA
MVC    SW01NKY,=H'2'                SET UP 2 KEYS
DBSETK BASE=R5,KEYNUM=1,DIS=I/2,LEN=I/1,CON=#DF_EQ,MSK=#IR73K80,  *
      ID1=#DF_UP+#DF_CONST,ID2=#DF_AND
DBSETK BASE=R5,KEYNUM=2,DIS=I/6,LEN=I/4,SEA=EBW000,ID1=#DF_UP
LA     R5,L'SW01KIT(,R5)            POINT TO SECOND KEY SET
#IF    MI0ACC+10(2),EQ,=C'GT'       INPUT = GREATER THAN?
  DBSETK CON=#DF_GT                 SET UP CONDITION CODE
#ELIF  MI0ACC+10(2),EQ,=C'GE'       INPUT = GREATER OR EQUAL?
  DBSETK CON=#DF_GE                 SET UP CONDITION CODE
#ELIF  MI0ACC+10(2),EQ,=C'EQ'       INPUT = EQUAL?
  DBSETK CON=#DF_EQ                 SET UP CONDITION CODE
#ELIF  MI0ACC+10(2),EQ,=C'NE'       INPUT = NOT EQUAL?
  DBSETK CON=#DF_NE                 SET UP CONDITION CODE
#ELIF  MI0ACC+10(2),EQ,=C'LT'       INPUT = LESS THAN?
  DBSETK CON=#DF_LT                 SET UP CONDITION CODE
#ELIF  MI0ACC+10(2),EQ,=C'LE'       INPUT = LESS OR EQUAL?
  DBSETK CON=#DF_LE                 SET UP CONDITION CODE
#EIF
DBKEY  REF=IR73DF,KEYLIST=EBX000    ACTIVATE KEY LIST
DBRED  REF=IR73DF

Using a Key List with the df_setkey Function

The following example uses the df_nbrkeys and df_setkey functions to create a key list. The first key is used for the LREC ID, and the second key searches field ir73fld for string 1234567890.

/* Set up the key list with 2 key                              */
df_nbrkeys(&keylist,2);
 
/* Define the two keys using the df_setkey function            */
df_setkey(&keylist,1,offsetof(struct ir73df,ir73key),1,DF_EQ,
         0,_IR73K80,DF_UPORG,DF_CONST);
 
df_setkey(&keylist,2,offsetof(struct ir73df,ir73fld),10,DF_EQ,
         "1234567890",0,DF_UPORG,0);
 
/* Activate the key list, and read the record from the subfile */
dfkey(ir73_ptr,&keylist);
dfred(ir73_ptr,DFRED_BEGIN);

Setting up a Key List with Less than Six Keys

The following example shows how to set up a key list with less than six keys. A key list containing one key (the primary key of the LREC) is set up and then reads an LREC.

/* set up one key only (primary key of LREC) */
 
dft_pky pky = 0x80;
dft_kyl keys;
dft_rec *lrec91;
 
df_nbrkeys(&keys, 1);
df_setkey(&keys, 1, offsetoff(struct gr95sr, gr95key),
          1, DF_EQ, &pky, 0, DF_NOORG, DF_CHAR);
 
/* activate the key list */
 
dfkey(file_ptr, &keys);
 
/* read an LREC with matching primary key */
/* (start at the beginning of the subfile) */
 
lrec91 = dfred(file_ptr, DFRED_BEGIN);

Setting up a Key List in the Range 1-180

The following example shows how to set up a key list in the range 1-180. A key list containing seven keys is set up and then reads an LREC.

 /* set up seven keys */
 
  dft_pky pky = 0x80;
  dft_kyl_ext keys;
  dft_rec *lrec91;
 
  df_setkey(&keys, 1, offsetoff(struct gr95sr, gr95key),
            1, DF_EQ, &pky, 0, DF_UPORG, DF_CHAR);
  df_setkey(&keys, 2, offsetoff(struct gr95sr, gr95f01),
            1, DF_EQ, &search_arg1, 0, DF_UPORG, DF_CHAR);
  df_setkey(&keys, 3, offsetoff(struct gr95sr, gr95f02),
            2, DF_EQ, &search_arg2, 0, DF_UPORG, DF_CHAR);
  df_setkey(&keys, 4, offsetoff(struct gr95sr, gr95f03),
            4, DF_EQ, &search_arg3, 0, DF_DOWNORG, DF_CHAR);
  df_setkey(&keys, 5, offsetoff(struct gr95sr, gr95f04),
            2, DF_EQ, &search_arg4, 0, DF_DOWNORG, DF_CHAR);
  df_setkey(&keys, 6, offsetoff(struct gr95sr, gr95f05),
            1, DF_NE, &search_arg5, 0, DF_NOORG, DF_CHAR);
  df_setkey(&keys, 7, offsetoff(struct gr95sr, gr95f06),
            1, DF_NE, &search_arg6, 0, DF_NOORG, DF_CHAR);
 
  /* activate the key list and set number of keys */
 
  dfkey_nbr(file_ptr, &keys, 7);
 
  /* read an LREC with matching keys */
  /* (start at the beginning of the subfile) */
 
  lrec91 = dfred(file_ptr, DFRED_BEGIN);

Using Boolean Logic in Key Lists

By default, each key specified in a key list or KEYn parameter is logically connected by AND Boolean logic. That is, each criteria must be satisfied for the LREC to be selected. Using key lists, additional Boolean logic can be specified that allows LRECs that meet some criteria but not necessarily other criteria to be selected. You can use any of the equates shown in Table 9 in SW01ID2 to control the connectivity between a key and the subsequent key:

Table 9. Boolean Equates

Assembler Connector C Language Connector Description
#DF_AND DF_AND Connects the current key to the next key using AND to form a group.
#DF_OR DF_OR Connects the current key to the next key using OR to form a group.
#DF_ANDIF DF_ANDIF Connects the current group to the next group using AND to form a complex expression.
#DF_ORIF DF_ORIF Connects the current group to the next group using OR to form a complex expression.

If any key specifies a Boolean connector value in field SW01ID2, all keys (except the last key in the key list) must specify Boolean values. Any Boolean connector value specified with the last key will be ignored. If none of these values are specified in field SW01ID2 of any key, all keys are connected using AND logic.

This support is not standard Boolean logic but is consistent with the implementation of the TPFDF structured programming macros (SPMs). See TPFDF and TPF Structured Programming Macros for more information.

Note:
Using any of the Boolean connector values listed in Table 9 in SW01ID2 has the following impact to LREC retrieval time (although the correct records will still be located):

See dfred-Read a Logical Record and DBRED-Read a Logical Record for examples of using Boolean logic on read operations.

Using Default-Key Key Lists

A default-key key list is used to make a set of default keys defined in the database definition (DBDEF) the active set of selection keys for read operations. The DBDEF keys specified can be either regular default keys or read-only default keys. Only the first key is filled in when using a default-key key list.

To use default keys on read operations, you must define a prototype LREC. The prototype LREC has the same layout as the LREC whose primary key is specified as the default key to be used. The prototype LREC must contain a search value in the fields corresponding to each key field in the default key.

The key list must be defined to have one key that must be set up with the specifications for default keys used on read operations:

See dfred-Read a Logical Record and DBRED-Read a Logical Record for examples of using default keys on read operations.

Using Modification Key Lists

Global modifications of LRECs require a modification key list to be defined. This modification key list contains the same information as a standard selection key list, including primary keys and field displacements, lengths, and values. It also contains an operation code that indicates the operation to be performed on the selected LRECs. This operation code is specified in SW01ID1. See DBSETK-Setting Up a Key in a Key List and df_setkey-Setting Up a Key in a Key List for information about the values for these operation codes.

You must do the following to perform a global modification of LRECs:

  1. If you want to specify a selection criteria to determine which LRECs will be modified, you must establish selection keys first. Do this by using a key list on a previous macro or function, or by using KEYn parameters on a previous macro.
  2. Define a modification key list with the following information:

    Note:
    Do not use a DBKEY macro or dfkey function with the modification key list.
  3. Do one of the following:
Note:
You can specify only 6 keys when using a modification key list.

See dfmod-Perform or Indicate Logical Record Modifications and DBMOD-Perform or Indicate Logical Record Modifications for examples of using global modification.