Algorithm descriptions

The z/TPFDF product provides several algorithms for distributing and accessing data.

Note: Unless otherwise specified, each algorithm is used with fixed file records.
Direct translation algorithms
z/TPFDF product provides eight algorithms to distribute LRECs to subfiles by using a direct relation between the algorithm argument and the subfile (ordinal) number.
Using your own distribution method
If you want to allocate LRECs over subfiles by using your own algorithm, there are two z/TPFDF algorithms that you can use for your own distribution method.
Hashing algorithms
Hashing algorithms distribute LRECs across any number of subfiles in a file. To get an even distribution, take the following actions:
  • Use a prime number for the number of subfiles.
  • Use a wide range of numbers or characters in the algorithm argument.
Algorithm for files that require no overflow
The z/TPFDF product provides the #TPFDB0D algorithm to distribute LRECs across only prime blocks. Use this algorithm to avoid chaining.

Because the z/TPFDF product does not have to search through a chain of overflow blocks, the #TPFDB0D algorithm provides one of the fastest ways of retrieving data, but it works only with fixed-length LRECs. You can access the data in this type of file by using the LRECNBR parameter.

Single-subfile algorithm
The z/TPFDF product provides the #TPFDB04 algorithm for files that have a single subfile.
Algorithm for basic index support
The z/TPFDF product provides the #TPFDBFF algorithm for basic index support. Use this algorithm with detail pool files.
Create your own algorithm
To create your own (user-defined) algorithm, complete the following tasks:
  • Specify an equate value in the range 256 - 511 in the ACPDBE macro.
  • Specify the user-defined algorithm in the z/TPFDF user exit in segment ubd0.asm.
  • Set the &SW00RBV symbol.
For a list of the previous algorithms, see Table 1.
Table 1. Algorithms
Algorithm name Description
Direct translation
#TPFDB01 Distributes LRECs across subfiles according to the first uppercase alphabetic character in the algorithm argument. Files that use this algorithm require 26 subfiles; one for each uppercase letter of the alphabet.
#TPFDB02 Distributes LRECs across subfiles according to the first 2 uppercase alphabetic characters in the algorithm argument. Files that use this algorithm require 676 subfiles, one for each combination of 2 uppercase alphabetic characters: 
AA, AB, AC,…ML, MM, MN,…ZX, ZY, ZZ
#TPFDB03 Distributes LRECs across subfiles according to the first 3 uppercase alphabetic characters in the algorithm argument. Files that use this algorithm require 17576 subfiles, one for each combination of 3 uppercase alphabetic characters: 
AAA, AAB, AAC,…MOL, MOM, MON,…ZZX, ZZY, ZZZ
#TPFDB06 Distributes LRECs across subfiles according to the first uppercase alphabetic or numeric character in the algorithm argument. Files that use this algorithm require 36 subfiles, one for each uppercase letter of the alphabet, and one for each numeric character (0 - 9).
#TPFDB07 Distributes LRECs across subfiles according to the first 2 uppercase alphabetic or numeric characters in the algorithm argument. Files that use this algorithm require 1296 subfiles, one for each combination of 2 uppercase alphabetic or numeric characters: 
AA,…A0,…A9,…ZA,…Z0,…Z9,…12,…5M,…99
#TPFDB08 Distributes LRECs across subfiles according to the first 3 uppercase alphabetic or numeric characters in the algorithm argument. Files that use this algorithm require 46656 subfiles, one for each combination of 3 uppercase alphabetic or numeric characters: 
AAA,…AAZ,…AA0,…AA9,…A00,…A09,…A99,…M56,…Z90,…123,…4T6,…999
#TPFDB0A Distributes LRECs across subfiles according to the first uppercase alphabetic, numeric, or special character in the algorithm argument. Files that use this algorithm require 43 subfiles, one for each uppercase letter of the alphabet, one for each numeric character, and one for each of the following special characters: 
  .  (X'4B')
  $  (X'5B')
  *  (X'5C')
  -  (X'60')
  ⁄  (X'61')
  #  (X'7B')
  @  (X'7C').
Note: The characters that these hexadecimal values represent might be different in some countries; therefore, the z/TPFDF product uses the hexadecimal value rather than the character value; for example, X'5B' is used instead of $.
#TPFDB0B Distributes LRECs across subfiles according to the first 2 uppercase alphabetic, numeric, or special characters in the algorithm argument. The special characters are as listed for #TPFDB0A. Files that use this algorithm require 1849 subfiles, one for each possible combination of 2 uppercase alphabetic, numeric, or special characters: 
..,.$,…AA,…BB,…B5,…B9,…#A,….M,…*Z,…$3,…⁄6,…99
Your own distribution method
#TPFDB05 Use #TPFDB05 if the ordinal number that you specify will be held in a 4-byte field.
#TPFDB0C Use #TPFDB0C if the ordinal number that you specify will be held in a 2-byte field.
Note: These 2 algorithms use absolute ordinal values, not ordinals relative to &SW00BOR.
Hashing
#TPFDB09 This hashing algorithm uses the first 8 bytes of data in the algorithm argument to determine the subfile that the LREC is placed in.

The algorithm argument can contain any hexadecimal values. The z/TPFDF product divides the first half of the 8-byte string by the number of subfiles, and then divides the second half by the number of subfiles. The two remainders are added and then divided again by the number of subfiles. The remainder is the subfile to be retrieved. This process produces an even distribution of LRECs among the subfiles.

When the algorithm string contains a disproportionately high number of the same value for either the high-order or low-order 4 bytes of the algorithm string, #TPFDB9 can distribute LRECs across subfiles better than #TPFDB11. For example, if 8-byte file addresses are used and the high order 4 bytes are often X'00000000'. Run tests with different algorithms by using sample data to ensure the best distribution.
#TPFDB0F This algorithm is for partitioned files. It uses a 10-byte algorithm argument. The z/TPFDF product processes the first 8 bytes in the algorithm argument in the same way as #TPFDB09. It uses the next 2 bytes in the algorithm argument to distribute LRECs between partitions similarly.
Note: You also can use other algorithms for partitioned files, but then the partition number is not part of the algorithm string and must be specified with the PARTITN parameter or DFOPT_PARTITION option.
#TPFDB10 This hashing algorithm uses the first 8 bytes of data in the algorithm argument to determine the subfile that the LREC is placed in.

The calculated ordinal is the remainder of an 8-byte algorithm argument that is divided by a 4-byte number of subfiles. The algorithm argument can contain any hexadecimal value. The result is achieved as follows: The z/TPFDF product divides the 8-byte string by the number of subfiles. The remainder is the subfile to be retrieved. This process produces an even distribution of LRECs among the subfiles.
#TPFDB11 This hashing algorithm uses the first 8 bytes of data in the algorithm argument to determine the subfile that the LREC is placed in.

The algorithm argument can contain any hexadecimal values. The z/TPFDF product divides the first half of the 8-byte string by a large prime number. If the remainder is a multiple of the number of subfiles, the remainder is incremented by one. The second half is divided by a different large prime number. The two remainders are multiplied together and the resulting product is divided by the number of subfiles. The remainder is the subfile to be retrieved. This produces an even distribution of LRECs among the subfiles.

When the number of ordinals is large and the algorithm string passed uses only a small subset of the available hexadecimal values, #TPFDB11 might distribute LRECs across subfiles better than #TPFDB09. For example, if there are 200 possible 4-byte locations, the 8-byte algorithm string contains location pairs, and there are 1 million ordinals (hash slots). However, do not use #TPFDB11 if there are a disproportionately high number of algorithm strings with the low order 4 bytes being all zeros. Run tests with different algorithms by using sample data to ensure the best distribution.
#TPFDB12 This hashing algorithm uses a variable number of bytes of data in the algorithm argument to determine the subfile that the LREC is placed in.

The algorithm consists of a 2-byte length field followed by the algorithm key data. The length is limited to a range of 1 - 253.

The z/TPFDF product computes a 32-byte message digest value from the variable-length algorithm key data, which does not include the length field, by using SHA-256 support. The 32-byte message digest is split into 4 binary doubleword values that are added together. The result is divided by the number of subfiles. The remainder is the subfile that is retrieved.
Files that require no overflow
#TPFDB0D Use this algorithm for applications that process data sequentially by number or in circumstances where no pool storage is available. #TPFDB0D is not allowed for B+Tree data files and files with 8-byte headers (FARF6 support). #TPFDB0D uses 4 bytes of data from the LREC number to determine where to store the LREC. It divides the 4-byte value by the number of LRECs in each block. The result is the relative ordinal number of the subfile that the LREC is placed in. The remainder gives the LREC number in the block. An example of such a file is shown in the following:
Alternative text description not available.

You do not need to specify how many LRECs are in each block when you use this algorithm. The z/TPFDF product calculates the number of LRECs in each block by dividing the length of the fixed-length LRECs into the block size.

For more information about FARF6 support, see FARF6 support for z/TPFDF.
Single subfile
#TPFDB04 Use this algorithm with files that contain a single fixed subfile. The #TPFDB04 algorithm does not perform any calculations to obtain a block ordinal number because there is only 1 prime block.
Basic index support
#TPFDBFF For basic z/TPFDF-managed indexing, this algorithm is used to access detail files.