bdfp1m0r | Programming Concepts and Reference |
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.
You can set up a key list in one of the following ways:
See Using a Key List with the DBSETK Macro for an example of how to use this method.
See Using a Key List with the df_setkey Function for an example of how to use this method.
See Processing Using a Key List for an example of how to do this.
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:
|
SW01SEA | 4 bytes | One of the following:
|
SW01ID1 | 1 byte | Option indicators |
SW01ID2 | 1 byte | One of the following:
|
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.
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.
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
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
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
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);
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);
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);
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:
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.
See dfred-Read a Logical Record and DBRED-Read a Logical Record for examples of using Boolean logic on read operations.
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.
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:
See dfmod-Perform or Indicate Logical Record Modifications and DBMOD-Perform or Indicate Logical Record Modifications for examples of using global modification.