Backward index path parameters

The definitions for the backward path are used to access the detail file.

Included with the backward index path parameters are descriptions of how the parameters work and some brief examples. For more complete examples of basic indexing, see Basic indexing.
Read syntax diagramSkip visual syntax diagram,(IID= dsnidx,PTH=0,PTH= path,IKY= indexpky,IMI=imibits#BIT0#BIT1#BIT2#BIT3(#BIT0,#BIT1,#BIT2,#BIT3#BIT1#BIT2,#BIT3,#BIT4#BIT3,#BIT4),IPA= offset,ILA=lengthVAR,IPK= offset,ILK=lengthVAR,MILK=253,MILK= maxlength,IPE= offset,KEY11=(PKY= indexpky,UP,DOWN,NOORG),KEY n1=(R= indexkey,S=0,S= offset,L=L' indexkey2,UP,DOWN,NOORG),ALG=algsizeVAR,DID= dataid,IFR=0,IFR= slot)
Notes:
  • 1 KEY parameters are only required when a search other than the default is required. If KEY parameters are not supplied, the default key fields are as follows: KEY1=(PKY=#dsniK80,UP) and KEY2=(R=dsniA80,S=0,L=L'dsniA80,UP)
  • 2 If you do not specify the L parameter, the L parameter defaults to the length of the R parameter.
IID=dsnidx
Identifies the backward path of the file whose index LRECs point to this file, where dsnidx is a 6-character file (and DSECT) name of the index file to which this detail or intermediate-index file is chained.
Note: If the index LRECs are extended, the DID parameter is used to specify the secondary key.
PTH=path
Specifies a path to an index file, where path is a nonnegative decimal number.
Note: All of the parameters that follow the PTH parameter define the characteristics of the specified path.
IMI
Specifies index method indicators, where the specific indicators are provided with one of the following values:
imibits
Specifies a bit mask that indicates a binary selection of indicators. For example, IMI=10100000 indicates that #BIT0 and #BIT2 are turned on. For additional descriptions, see the individual bit equates.
#BIT0
Specifies that a path is read only. Read-only paths cannot be used to add indexes.
#BIT1
Specifies FULLFILE processing from the ordinal defined by the BOR parameter to the ordinal defined by the EOR parameter.

If #BIT1 is specified, the addressing arguments (IPA and ILA) are ignored.

#BIT2
Specifies FULLFILE processing from the ordinal located using the addressing argument defined by the IPA and ILA parameters to the ordinal defined by the EOR parameter. #BIT2 is a system equate that can be specified in binary form.
#BIT3
Specifies that the top-level index reference contains an 8-byte file address reference. The file address might be a FARF6 file address or a FARF3/4/5 file address in 4x4 mode. If not specified, the default is a 4-byte file address reference.
#BIT4
Specifies that this path uses z/TPFDF recoup optimized chain chasing.
If this parameter is specified, ensure that ID1=(RCPOPTIDX) is specified on the DBDEF for the top-level index file.

If this parameter is specified for any backward index path, SW02OP6 #BIT1 is automatically set to 1 to indicate that at least one backward index path has IMI #BIT4 set.

For more information, see z/TPFDF recoup optimized chain chasing.

IKY=indexpky
Specifies the primary key (LREC ID) of the index file to which this detail or intermediate-index file is chained, where indexpky is one of the following values:
  • An equate that represents the primary key (for example, IKY=#GR00K80)
  • An explicit term that represents the primary key (for example, X'80').
Note: Set the IKY parameter value equal to the ITK parameter value of the index file to which this detail or intermediate-index file is chained. 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.
IPA=offset,ILA=length
Specifies the offset into and length to use of a string passed with the ALG parameter on a DBOPN or other z/TPFDF macro, where offset is a nonnegative decimal number and length is one of the following values:
  • A nonnegative decimal number.
  • The value VAR.
This string is used to extract an addressing argument that is used to locate a prime block of an index file.

Set the ILA parameter to VAR if the top-level index uses a variable-length hashing algorithm (such as #TPFDB12). If you specify ILA=VAR, you also must specify ALG=VAR.

The following example shows how the IPA and ILA parameter settings defined in a detail file, IR24DF, are used to locate an argument string in an index file, IR25DF. 
DBDEF FILE=IR24DF
(IID=IR25DF,
IPA=0,ILA=1,

DBOPN REF=IR24DF,ALG=C'SMITH'

In this example, when the DBOPN macro is processed, the z/TPFDF product accesses the S prime block in the first-level index file, IR25DF. The S prime block is determined by extracting, for a length of 1 byte (ILA=1), the value found at offset 0 (IPA=0) into SMITH (ALG='SMITH').

IPK=offset,ILK=length
Specifies the offset into and length of a string that is passed with the ALG parameter on a DBRED or other z/TPFDF macro, where offset is a nonnegative decimal number and length is one of the following values:
  • A nonnegative decimal number. The maximum length is 255.
  • The value VAR.
This string is used to extract an index key that is used to locate an index record in an index file.

Set the ILK parameter to VAR to use variable-length algorithm indexing. If you specify ILK=VAR, you also must specify ALG=VAR and enable bit 3 of the IMI parameter by specifying IMI=#BIT3. Additionally, the higher-level index file must use an 8-byte file address format for the index LRECs and must have FAL=8 specified.

In the following example, when the DBRED macro is processed, the z/TPFDF product reads the SM prime block in the first-level index file, IR20DF. 
DBDEF FILE=IR24DF
(IID=IR20DF,
IPA=0,ILA=2
IPK=0,ILK=5
KEY1=(PKY=#IR20K80,UP),   search keys for index
KEY2=(R=IR20NAM,DOWN))

DBRED REF=IR24DF,ALG=C'SMITH'

The SM prime block of the first-level index file (IR20DF) is determined by extracting, for a length of 2 bytes (ILA=2), the value found at offset 0 (IPA=0) into SMITH (ALG='SMITH'). The z/TPFDF product then reads the first index record in the IR20NAM field ((KEY2=(R=IR20NAM,DOWN)) that contains the name SMITH. SMITH is determined by extracting, for a length of 5 bytes (ILK=5) the value found at offset 0 (IPK=0) into SMITH. The z/TPFDF product then uses the SMITH index record to locate the SMITH detail subfile.

The following example defines a variable-length algorithm that supports the longest possible algorithm string (253 bytes) that can be used:
(IID=IR23DF,PTH=1,IPA=0,ILA=0,IPK=0,ILK=VAR,ALG=VAR,IMI=#BIT3)
MILK=maxlength
Specifies the maximum length of a variable-length algorithm string (key argument) in the file. The maximum length for a variable-length algorithm string is 253 bytes, but you can specify a smaller maximum for the file.
The following example defines a variable-length algorithm and restricts the maximum key length to 99:
(IID=IR23DF,PTH=1,IPA=0,ILA=0,IPK=0,ILK=VAR,MILK=99,ALG=VAR,IMI=#BIT3)
IPE=offset
Specifies an offset into a string passed with the ALG parameter on a DBRED or other z/TPFDF macro, where offset is a nonnegative decimal number. The IPE parameter is used with the IPA and ILA parameters to extract the addressing argument for the end ordinal used in FULLFILE processing. This end ordinal addressing argument starts at the first byte after the starting ordinal addressing argument for a length specified by the ILA parameter.
The following example shows how the IPA, ILA, and IPE parameter settings are used by the DBRED macro to read all of the detail subfiles indexed by ordinal 0 ("A") to ordinal 4 ("E"). The #DO loop is executed until all of the detail subfiles have been read. 
IPA=0,ILA=1
IPE=1

DBOPN REF=GR00SR,REG=R4
#DO INF
DBRED FULLFILE REF=GR00SR,REG=R4,ALG=C'AE'
#DOEX TM,SW00RTN,#BITA,NZ
#ELOP
#EDO

Beginning ordinal 0 ("A") is determined by extracting, for a length of 1 byte (ILA=1), the value found at offset 0 (IPA=0) into AE (ALG=C'AE'). Ending ordinal 4 ("E") is determined by extracting, for a length of 1 byte (ILA=1), the value found at offset 1 (IPE=1) into AE (ALG=C'AE').

KEYn
Specifies the position of the index keys in a string that is passed with the ALG parameter on a DBRED or other z/TPFDF macro, where n is a number in the range 1 - 6.
Note:
  • These keys override any IPK and ILK settings.
  • Keys are not valid for variable-length algorithm strings.
PKY
Specifies the primary key of the index LREC.
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.
R=indexkey
Specifies the position in the index LREC of the index key, where indexkey is field that contains the index key.
S=offset
Specifies the offset in the algorithm string of the data to compare with the index key located by the R parameter, where offset is a nonnegative decimal number.
L=L'indexkey
Specifies the length of the index key, where indexkey is field that contains the index key.
ALG
Specifies the size of the algorithm string for each index path. Specify one of the following values:
algsize
A decimal value. If the algorithm string size is not defined in the DSECT (by using the &BEG and &END statements) and you are not using variable-length algorithms, you must specify the length of the algorithm string with the ALG parameter. The maximum value is 255.
VAR
Specifies that you want to use variable-length algorithms. If you specify ALG=VAR, you must specify one or both of the following settings:
  • If you use a variable-length hashing algorithm, such as #TPFDB12, you also must specify ILA=VAR.
  • If you use variable-length algorithm indexing, you also must specify ILK=VAR and enable bit 3 of the IMI parameter by specifying IMI=#BIT3. Additionally, the higher-level index file must use an 8-byte file address format for the index LRECs and must have FAL=8 specified.
The following example defines an algorithm string as 4 bytes long: 
 (IID=IR23DF,PTH=1,IPA=0,ILA=0,IPK=0,ILK=4,ALG=4)
The following example defines a variable-length algorithm:
 (IID=IR23DF,PTH=1,IPA=0,ILA=0,IPK=0,ILK=VAR,ALG=VAR,IMI=#BIT3)
Note:
  1. The ALG parameter in the DBDEF macro does not have the same meaning as the ALG parameter in other z/TPFDF macros and functions.
  2. The ALG parameter cannot be used with a read-only path (IMI=#BIT0).
DID=dataid
For extended LRECs, specifies the 2-byte data identifier (secondary key) of the index file that refers to this detail or intermediate-index file, where dataid is one of the following values:
  • An equate that represents the 2-byte data identifier (for example, DID=#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 DIT=dataid value in the index file must be the same as the DID=dataid value in this detail or intermediate-index file. See the DIT parameter in Forward index path (recoup and CRUISE) parameters.
IFR=slot
specifies the index slot, where slot is the number of an index slot that contains a reference to the index file to which this detail or intermediate-index file is chained. This number must be the same as the index slot coded with the INDEX parameter in the index file. See the INDEX parameter in Forward index path (recoup and CRUISE) parameters.