bdfd1m10Database Administration

Modifying the Sample DSECT Macros

This section describes how to copy and modify one of the sample DSECTs to create a DSECT to match your own requirements.

Modifying the Beginning DSECT Macro Statements

Figure 33 shows the beginning macro statements in the sample code for SAM3SR. The beginning statements, before the Definitions for TPFDF section, are always required. Do not change or delete them, except to:

Figure 33. Instructions Always Required at the Start of a DSECT Macro Definition

         MACRO                     LIBR NAME = SAM3SR09
&LABEL   SAM3SR &REG=,&SUFFIX=,&ORG=,&ACPDB=
***********************************************************************
*                                                                     *
*   $TITLE$     SAMPLE DSECT FOR TPFDF W-TYPE BASIC                   *
*   CREATED EX: $CREATE$     DATE: $CDATE$                            *
*                                                                     *
*                                                                     *
*  CHANCE HISTORY  DATE      DESCRIPTION                              *
*                                                                     *
***********************************************************************
         GBLB  &SAM3SR1      1ST TIME CALLED SWITCH
         COPY  DBGBL         COPY TPFDF GLOBAL DEFINITIONS
         COPY  DBLCL         COPY TPFDF LOCAL DEFINITIONS
&NAM     SETC  '             '    DOC NAME
&DATE    SETC  '17DEC85'     UPDATE DATE
&VERS    SETC  '03'          VERSION NUMBER

Assigning Values to Global Set Symbols

As shown in Figure 34, after the Definitions for TPFDF section in the SAM3SR sample code, there are a series of instructions that assign values to several global set symbols. Assign values to each global set symbol that you need to define. For example:

Figure 34. Instructions to Assign Values to Global Set Symbols

&SW00WID SETC                FILE ID
&SW00WRS SETC                BLOCK SIZE
&SW00ARS SETC                ALTERNATE BLOCK SIZE
&SW02FIL SETC  'SAM3SR'      FILE DSECT NAME
&SW00OP1 SETC  '00000000'    OPT BYTE1
&SW00OP2 SETC  '00000110'    OPT BYTE2
&SW00OP3 SETC  '00000000'    OPT BYTE3
&SW00TQK SETC  '15'          HIGHEST TLREC

The global set symbols are described here in alphabetic order.

Notes:

  1. Do not assign a value to a particular global set symbol if it is not required. For example, do not assign values to &SW00BOR, &SW00EOR, and &SW00RCT for pool files.

  2. Do not change any values except &SW00WID and &SW00WRS in the B+Tree index file sample, SAMTSR.

  3. You can override some of the global set symbol values assigned in a DSECT macro by using a corresponding parameter in the DBDEF instructions or with a TPFDF macro or function.

&SW00ARS: Specify the Block Size of Overflow Blocks
&SW00ARS is optional. Use it to specify the size of any overflow blocks that are chained to the prime blocks of the file; for example:
&SW00ARS SETC  'L4'

Because overflow blocks are always pool blocks, &SW00ARS is the only definition of the overflow block size and does not have to correspond with any other value defined elsewhere (see the description for &SW00OP1 bit 5 on page ***).

If you do not specify &SW00ARS, the TPFDF product assigns a value equal to the value set for prime blocks, &SW00WRS.

For add current processing, when the number of chains (NOC) is greater than 0, &SW00ARS must be equal to the value defined for &SW00WRS.

For B+Tree index files, &SW00ARS is ignored. &SW00WRS supplies the block size of the nodes.

&SW00BOR: Specify the Begin Ordinal
&SW00BOR is required for fixed or miscellaneous files. Use &SW00BOR to specify the beginning ordinal for the file.

&SW00EOR: Specify the End Ordinal
&SW00EOR is required if this is a fixed or miscellaneous file. Use &SW00EOR to specify the end ordinal number for the fixed file.

&SW01EO#: Specify the End Ordinal for TPFDF Recoup
&SW01EO# specifies the FACE-type end ordinal (for TPFDF recoup).

Notes:

  1. If &SW01EO# is not specified in the DSECT or the DBDEF EO# parameter override, -1 is used for fixed file types.

  2. If &SW01EO# is not specified in the DSECT or the DBDEF EO# parameter override, the &SW00BOR value or the DBDEF BOR parameter override, is used for miscellaneous files.

  3. Miscellaneous file type prefixes are defined in the TPFDF product with the &MISTYPE(n) array in segment DBLCL. You can define as many as 20 prefixes (including those shipped with the TPFDF product). For more information about the DBLCL segment, see TPFDF Installation and Customization.

&SW02FIL: Specify the File Name
Set &SW002FIL to the DSECT macro name. For example:
&SW002FIL SETC 'dsname'

&SW00ILV: Specify the Number of Interleaves
&SW00ILV is optional. If you set this to a nonzero value, it implies that the file is interleaved. The number you assign defines the number of interleaves. For example:
&SW00ILV SETC '3'

&SW00NLR: Specify Number of Fixed-Length LRECs in Each Block
&SW00NLR is optional. Only assign a value to &SW00NLR when the file uses algorithm #TPFDB0D. With this algorithm, the file contains only prime blocks. All LRECs must be fixed-length. Set &SW00NLR to the maximum number of LRECs that can fit into each prime block of the file.

Notes:

  1. The global set symbol &SW00NLR is not allowed for B+Tree data files.

  2. Using the global set symbol &SW00NLR will result in an MNOTE being issued because the TPFDF product automatically calculates this value, and any value specified is ignored.

&SW00NOC: Specify the Number of Blocks to Use in Implementing Add Current Files
Only assign a value to &SW00NOC when bit 2 of &SW00OP1 is set on. Setting bit 2 of &SW00OP1 instructs the TPFDF product to limit the number of overflow blocks used when adding LRECs to the subfile. You can set the limit (using &SW00NOC) from zero to a maximum of 255 blocks. When this limit is reached in the subfile, the TPFDF product discards the contents of the oldest chain block and copies the LRECs from the first chain block to the prime block. The first (empty) chain block is moved to the last chain block with an initial next available byte (NAB) setting. A new LREC is added to the last (empty) chain block. For example:
&SW00NOC SETA 5

instructs the TPFDF product to use the prime block and 5 overflow blocks.

If global set symbol &SW00NOC is set to zero, the TPFDF product uses only the prime block of the subfile.

Note:
The &SW00NOC parameter is not allowed for B+Tree data files.

&SW00OP1: Specify Processing Options
&SW00OP1 contains 8 bits that specify TPFDF processing options.

Notes:

  1. In the TPFDF product, bit 0 is the most significant and bit 7 is the least significant.

  2. Bit fields labeled 'reserved' have no meaning in the system. Do not set them.

Bit 0: Implement Full Backward Chaining
Setting bit 0 of &SW00OP1 indicates that you want full backward chaining.

Backward chaining causes extra I/O overhead each time an overflow block is inserted or deleted. Backward chaining is required if the DBDEF DELEMPTY parameter is coded as YES. Backward chaining is recommended if an application program uses the DBRED macro with the BACKWARD parameter or the dfred function with the DFRED_BACKWARD option. If backward chaining is not defined, and an attempt is made to read the file backwards, the action taken by the TPFDF product is determined by the &DB013A symbol in the DBLCL macro.

Note:
The value of &SW00OP1 bit 0 has no meaning for files that use add current processing (&SW00OP1 bit 2 set to 1) with no chains (&SW00NOC equal to 0).

See TPFDF Programming Concepts and Reference for more information about reading backward. See TPFDF Installation and Customization for more information about the DBLCL macro.

Bit 1: Implement Automatic Chain Correction
If you set bit 1 of &SW00OP1, the TPFDF product performs automatic chain correction if it detects a broken chain when you use a macro or function to access an LREC.

If you have set this indicator and the TPFDF product detects an incorrect forward chain pointer, it truncates the chain. Data may be lost in these circumstances, so set bit 1 of &SW00OP1 only for files where missing data is not critical.

Bit 2: Implement Add Current Files (Discarding Old Chain Blocks)
Setting bit 2 of &SW00OP1 indicates that you want to limit the number of overflow blocks used when adding LRECs.

When this limit is reached, the TPFDF product discards the contents of the oldest chain block and copies the LRECs from the first chain block to the prime block. The empty first chain block is moved to the last chain block with an initial next available byte (NAB) setting. You can set the limit using the &SW00NOC global set symbol from zero to 255.

If you set the &SW00NOC global set symbol to zero, the TPFDF product restricts processing to the prime block only. This feature is useful if you want to keep a limited amount of current data; for example, a log of the last series of macros issued by the program.

Notes:

  1. Setting bit 2 of &SW00OP1 is not allowed with B+Tree data files.

  2. Do not set bit 2 of &SW00OP1 for a file that has index LRECs in a basic indexing structure.

Bit 3: Implement Pushdown Chaining
If you set bit 3 of &SW00OP1, this specifies pushdown chaining. This works as follows:
  1. When an application program uses the DBADD macro to add a new LREC, the TPFDF product stores the LREC starting at the next available byte in the prime block if there is room.
  2. If the prime block does not have enough room left for the new LREC, the TPFDF product gets a new overflow block. It copies the contents of the prime block into the new overflow block, initializes the prime block, and puts the next LREC into the start of the prime block which is now empty.

Notes:

  1. If you use this feature, the file cannot be UP or DOWN organized.

  2. Setting bit 3 of &SW00OP1 is not allowed with B+Tree data files.

Bit 4: Checkpoint after Each DBUKY Macro
If you set bit 4 of &SW00OP1, the TPFDF product performs a checkpoint automatically whenever the application program uses the DBUKY macro. A checkpoint after each DBUKY macro call is often useful because application programs typically call DBUKY as the first step of a sequence of related updates to a file.

Bit 5: Specify Variable Sizes of Overflow Block
If bit 5 of &SW00OP1 is not set, the TPFDF product uses the value you set in parameter &SW00ARS to determine the size of all overflow blocks.

If you set bit 5 of &SW00OP1, the TPFDF product uses the size you have specified for prime blocks (&SW00WRS) for the first overflow block and the size you have specified for overflow blocks (&SW00ARS) for all other overflow blocks.

You must have specified the size of overflow blocks (&SW00ARS) to be greater than the size of prime blocks (&SW00WRS) for this bit setting to be effective.

Bit 6: Check Whether Blocks Should Be Packed
If you set bit 6 of &SW00OP1, the TPFDF product always checks for the packing criteria specified by &SW00PIN in every block that has been modified, regardless of whether the DBDEL macro or dfdel function has been used to delete LRECs. For example, the DBREP macro or dfrep function may have been used to replace an LREC with a smaller LREC.

Notes:

  1. This bit setting creates processing overhead.

  2. Setting bit 6 of &SW00OP1 is not allowed with B+Tree data files.

Bit 7: Maintain a File Sequence Update Counter
If you set bit 7 of &SW00OP1, the TPFDF product maintain a file sequence update counter in the prime block of the file.

Use this option with the DBRST command or dfrst function and sequence parameters.

&SW00OP2: Specify Processing Options
&SW00OP2 contains 8 bits that specify TPFDF processing options.

Notes:

  1. In the TPFDF product, bit 0 is the most significant and bit 7 is the least significant.

  2. Bit fields labeled 'reserved' have no meaning in the system. Do not set them.

Bit 0: Validate Next Available Byte (NAB)
When this bit is on, the TPFDF product validates the next available byte (NAB) every time it files a block.
Note:
Using this feature creates processing overhead.

Bit 1: New Pool Option When a File Is Packed
By default, when the TPFDF product packs a file (when you close a file or use the ZUDFM OAP command, or a ZFCRU command with the pack function), it packs the file into the existing blocks, releasing any overflow blocks that are no longer required.

If you set bit 1 of &SW00OP2, new overflow blocks are used and old overflow blocks are released when a pack operation is completed successfully.

Bit 2: New Pool Option When a File Is Restored
By default, when the TPFDF product restores a file, it restores the file into existing blocks releasing any overflow blocks that are no longer required.

If you set bit 2 of &SW00OP2, new overflow blocks are used and old overflow blocks are released when a restore operation completes successfully.

Note:
A B+Tree index is always rebuilt using new pool records regardless of the bit setting.

Bit 3: New Pool Option When a File Is Loaded from Tape
By default, when the TPFDF product loads a file from tape (or for ALCS users, from sequential file), it loads the file into the existing blocks releasing any overflow blocks that are no longer required.

If you set bit 3 of &SW00OP2, new overflow blocks are used and old overflow blocks are released when a tape load operation completes successfully.

Bit 4: Retrieve Prime Blocks
Bit 4 should normally be set to zero. When bit 4 is set to zero and a hold is specified on a TPFDF call (for example, with the HOLD parameter on the DBOPN macro or the DFRED_INDEX_HOLD value on the dfred function), the TPFDF product issues the FIWHC macro to find and hold the prime block. Because open file processing does not perform an I/O, the FIWHC macro is processed on the subsequent TPFDF call that accesses the subfile.

When bit 4 is set to 1, the TPFDF product issues the FINWC macro to find the prime block regardless of whether a hold is specified or not, and the prime block is not held.

Note:
Setting bit 4 to 1 allows two ECBs to update a file at the same time.

Bit 5: Retrieve Overflow Blocks
Bit 5 should normally be set to 1. When bit 5 is set to zero and a hold is specified on a TPFDF call (for example, with the HOLD parameter on the DBOPN macro or DFRED_INDEX_HOLD value on the dfred function), the TPFDF product issues the FIWHC macro to find and hold the overflow blocks. Because open file processing does not perform an I/O, the FIWHC macro is processed on the subsequent TPFDF call that accesses the subfile.

When bit 5 is set to 1, the TPFDF product issues the FINWC macro to find the overflow blocks regardless of whether a hold is specified or not, and the overflow blocks are not held.

Bit 6: Issue an OPR-DB010C System Error if the File is Modified without HOLD
Setting bit 6 to 1 causes the TPFDF product to issue an OPR-DB010C dump and return to the application program when a file that was opened without the HOLD parameter is modified and then closed. This prevents two ECBs from updating a file at the same time.
Note:
If a file is opened with the HOLD parameter and &SW00OP2 bit 4 is set to 1, setting bit 6 to 1 will not prevent two ECBs from updating the file at the same time.

Bit 7: Reserved
This bit is reserved for IBM use.

&SW00OP3: Specify Processing Options
&SW00OP3 contains 8 bits that specify TPFDF processing options.

Notes:

  1. In the TPFDF product, bit 0 is the most significant and bit 7 is the least significant.

  2. Bit fields labeled 'reserved' have no meaning in the system. Do not set them.

Bit 0: LRECs Are of Extended Type
If you set bit 0 of &SW00OP3, this indicates to the TPFDF product that all LRECs in the file are extended LRECs.

Bit 1: Reserved
This bit is reserved for IBM use.

Bit 2: Reserved
This bit is reserved for IBM use.

Bit 3: File Is an Indexed Fixed File
You must set bit 3 of &SW00OP3 if the file you are specifying is a fixed file and it has one or more index files referencing it. See Simple Indexing.

Bit 4: Checkpoint When an Index LREC Is Added or Deleted
When the TPFDF product updates index LRECs, the LRECs are updated in main storage only. The TPFDF product only writes the index file to disk when the detail file is closed.

If you set bit 4 of &SW00OP3, the TPFDF product performs a checkpoint automatically whenever an index LREC is added or deleted from an index file.

Bit 5: Implement B+Tree Indexing
Set bit 5 of &SW00OP3 for files using B+Tree indexing. See B+Tree Indexing.
Note:
Before you can implement B+Tree indexing in an ALCS environment, enable C language support. See TPFDF Installation and Customization for more information.

Bit 6: Default DETAC Mode
When this bit is set, each time you open a subfile, the TPFDF product opens it in DETAC mode (as if you had used the DETAC parameter with the DBOPN macro or dfopn function).

Bit 7: Unique Key Feature
Set this bit if you want to allow application programs to generate unique keys using the DBUKY macro or dfuky function.

&SW00PIN: Specify the Packing Threshold in a Block
When you close a subfile after deleting LRECs, the TPFDF product packs the subfile if the number of bytes used for LRECs in any block falls below the percentage (as indicated by &SW00PIN) of total bytes available for LRECs and the optional block trailer. If any block falls below the packing threshold, the subfile is packed to the level defined by the PLI value in the DBDEF. Always specify a PLI value greater than the &SW00PIN value; otherwise, the file is always below the packing threshold and is packed continuously.

For example:

&SW00PIN SETC '60'

For non-B+Tree files, the default setting is 75% if either &SW00WRS or &SW00ARS is set to L4. Otherwise the default is 50%. If the PLI parameter is not specified in the DBDEF, the blocks are packed to 100%.

Note:
B+Tree files have the following considerations:
  • For B+Tree index files, the &SW00PIN value (defined in the DBDEF statement of the data file) applies to node blocks. If a node block drops below the specified percentage, the node block is balanced or combined with an adjacent node. The default value, which is the maximum for a B+Tree index file, is 50%.
  • For B+Tree index files, the &SW00PIN value should be set to 0 in the DSECT or by using the PIN parameter on the DBDEF macro so node blocks are not accidentally packed by a utility.
  • B+Tree data files are only packed using a utility or when the file is closed, there are no nodes in the B+Tree structure, and there are overflow blocks in the data file.

&SW00PTN: Specify the Number of Partitions
&SW00PTN is required for partitioned files. It specifies the number of partitions. For example:
&SW00PTN SETC '4'

&SW00RBV: Specify the Addressing Algorithm
&SW00RBV defines the algorithm you want to use with this file.

If the file is a detail pool file, set it to '#TPFDBFF' as follows:

&SW00RBV SETC '#TPFDBFF'

Direct Translation Algorithms
There are eight TPFDF algorithms that distribute LRECs to subfiles 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 yourself, there are two TPFDF algorithms that let you use your own distribution method.

Hashing Algorithms
Hashing algorithms distribute LRECs across any number of subfiles in a file. To get an even distribution:
  • Use a prime number for the number of subfiles.
  • Use a wide a range of numbers or characters in the algorithm argument.

Algorithm for Files Requiring No Overflow
The TPFDF product provides one algorithm, #TPFDB0D, which distributes LRECs across prime blocks only. Use this algorithm if you want to avoid chaining.

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

Single-Subfile Algorithm
The TPFDF product provides the #TPFDB04 algorithm for files that have a single subfile.

Algorithm for Basic and B+Tree Index Support
The TPFDF product provides the #TPFDBFF algorithm for basic and B+Tree index support.

Create Your Own Algorithm
To create your own (user-defined) algorithm, do the following:
  • Specify an equate value in the range 256-511 in the ACPDBE macro
  • Specify the user-defined algorithm in user exit UWBD
  • Set the &SW00RBV symbol.
Note:
See Table 34 for a list of the previously mentioned algorithms.

Table 34. Algorithms

Direct Translation
#TPFDB01 Distributes LRECs across subfiles according to the first alphabetic character in the algorithm argument. It requires 26 subfiles; one for each letter of the alphabet.
#TPFDB02 Distributes LRECs among subfiles according to the first 2 alphabetic characters in the algorithm argument. It requires 676 subfiles, one for each combination of 2 alphabetic characters:
AA, AB, AC,...ML, MM, MN,...ZX, ZY, ZZ
#TPFDB03 Distributes LRECs across subfiles according to the first 3 alphabetic characters in the algorithm argument. It requires 17 576 subfiles, one for each combination of 3 alphabetic characters:
AAA, AAB, AAC,...MOL, MOM, MON,...ZZX, ZZY, ZZZ
#TPFDB06 Distributes LRECs across subfiles according to the first alphabetic or numeric character in the algorithm argument. It requires 36 subfiles, one for each letter of the alphabet and one for each numeric character (0-9).
#TPFDB07 Distributes LRECs across subfiles according to the first 2 alphabetic or numeric characters in the algorithm argument. It requires 1296 subfiles, one for each combination of 2 alphabetic or numeric characters:
AA,...A0,...A9,...ZA,...Z0,...Z9,...12,...5M,...99
#TPFDB08 Distributes LRECs across subfiles according to the first 3 alphabetic or numeric characters in the algorithm argument. It requires 46 656 subfiles, one for each combination of 3 alphabetic or numeric characters:
AAA,...AAZ,...AA0,...AA9,...A00,...A09,...A99,...M56,...Z90,...123,...4T6,...999
#TPFDB0A Distributes LRECs among subfiles according to the first alphabetic, numeric, or special character in the algorithm argument. It requires 43 subfiles, one for each 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').

(The characters represented by these hexadecimal values can be different in some countries, so the TPFDF product uses the hexadecimal value not the character value (for example X'5B' not $).

#TPFDB0B Distributes LRECs among subfiles according to the first 2 alphabetic, numeric, or special characters in the algorithm argument. The special characters are as listed above for #TPFDB0A. It requires 1849 subfiles, one for each possible combination of 2 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 two 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 in which subfile the LREC should be placed.

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

#TPFDB0F This algorithm is for partitioned files. It uses a 10-byte algorithm argument. The 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 on a similar basis.
#TPFDB10 This hashing algorithm uses the first 8 bytes of data in the algorithm argument to determine in which subfile the LREC should be placed.

The calculated ordinal is the remainder of an 8-byte algorithm argument divided by a 4-byte number of subfiles. The algorithm argument can contain any hexadecimal value. The result is achieved as follows: The TPFDF product divides the first 4 bytes of the 8-byte string by the number of subfiles. The second 4 bytes of the string are appended to the end of the remainder of the first division, and the entire resulting number is divided by 4 times the number of subfiles. The remainder of this division is then divided by the number of subfiles. The remainder is the subfile to be retrieved. This produces an even distribution of LRECs among the subfiles.

Files Requiring No Overflow
#TPFDB0D #TPFDB0D is suitable 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. #TPFDB0D uses 4 bytes of data from the LREC number to determine where the LREC should be stored. It divides the 4-byte value by the number of LRECs in each block. The result is the relative ordinal number of the subfile in which the LREC is placed. The remainder gives the LREC number in the block. An example of such a file is shown in the following:

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

Single Subfile
#TPFDB04 Use this algorithm with files consisting of a single fixed subfile. #TPFDB04 does not perform any calculations to obtain a block ordinal number because there is only 1 prime block.
Basic and B+Tree Index Support
#TPFDBFF For basic indexing, this algorithm is used to access detail files. For B+Tree indexing, node files are defined using this algorithm.

&SW00RCT: Specify the Record Type for Fixed Files
&SW00RCT is required for fixed or miscellaneous files. Use &SW00RCT to specify the file's record type.
&SW00RCT SETC '#IDFCS'

&SW00REF: Specify the Work Area Reference Name
&SW00REF is valid for T-type files only. Use it to specify the reference name of the W-type file that contains the T-type file. The default is GW01SR.
&SW00REF SETC 'dsname'

Where dsname is the W-type file reference name.

&SW00SKE: Specify Block Index Support
To implement block index support, set &SW00SKE equal to the length in bytes of the key fields to be removed from the first LREC of each overflow block. The TPFDF product stores this in a TLREC (LREC ID = X'02'). The length you specify must include the zzzzKEY field (the LREC ID). For example, if the last field in the key is zzzzlabel, you would specify:
&SW00SKE SETC 'zzzzlabel-zzzzKEY+L''zzzzlabel'

Notes:

  1. Make &SW00SKE large enough to hold any field used as a key field by any application program that might use this file.

  2. If the file contains several different formats of LRECs, each identified by a separate LREC ID, set &SW00SKE equal to the size of the largest key that needs to be used.

  3. Do not use block index support with add current files (these are indicated by bit 2 of &SW00OP1 being set).

  4. &SW00SKE is not allowed for B+Tree data files.

  5. To set up a block indexed index file, set the length of &SW00SKE from the LREC ID to the last key field; for example:
    &SW00SKE SETC  'GR25E80-GR25KEY' EXTRACT FOR BLOCK INDEX
    GR25REC&CG1 DS  0CL1
    GR25SIZ&CG1 DS  H
    GR25KEY&CG1 DS  XL1
    GR25FAD&CG1 DS  CL4
    GR25RCC&CG1 DS  XL1
    GR25A80&CG1 DS  0XL6
    GR25FID&CG1 DS  XL2
    GR25FVN&CG1 DS  XL1
    GR25IND&CG1 DS  XL1
    GR25SSU&CG1 DS  XL2
    GR25E80&CG1 EQU * 
    

&SW00TQK: Specify the Highest Technical LREC (TLREC) ID that the TPFDF Product Can Use
You can use &SW00TQK to set the value of the highest technical LREC ID that the TPFDF product can use for this file. For block indexed files, it must be set to a value greater than 2. For B+Tree data files, it must be set to a value greater than 4. For B+Tree index files, it must be set to a value less than 3.
&SW00TQK SETC '15'

Note:
Technical LREC IDs 1-15 are reserved for IBM. Except for B+Tree index files, set TQK=15 to avoid conflicts with the TPFDF product.

&SW00TYP: Specify the File Type
&SW00TYP is optional. If you omit it, the TPFDF product takes the file type from the second character of the DSECT macro name. These characters are listed in File Names.

You can set &SW00TYP equal to 'R', 'W', 'T', or 'P'. B+Tree data files must be R-type files, whether specified or taken from the second character of the DSECT macro name.

If you are defining a DSECT macro to access a P-type file, set &SW00TYP equal to 'P', as follows:

&SW00TYP SETC 'P'

&SW00WID: Specify the File ID
&SW00WID is always required. It specifies the file ID, which is a 2-byte value in the standard header of every block. Use a unique file ID for every DSECT macro. The range of valid file IDs is from #TPFDBID to X'FFFF' (where the value of #TPFDBID is defined in ACPDBE). For example:
&SW00WID SETC X'C000'

See TPFDF Installation and Customization for more information about #TPFDBID values.

&SW00WRS: Specify the Size of Prime Blocks
&SW00WRS is required. Set it to the size of the prime blocks used in the file. For example, to use a 1055-byte (L2) prime block, set &SW00WRS as follows:
&SW00WRS SETC  'L2'

File Description

The Description of SAM3SR section of the SAM3SR sample DSECT allows you to document your DSECT macro. Do not change the instructions that immediately follow the Description of SAM3SR section except to rename the DSECT to your new DSECT name. See Figure 35.

Figure 35. Instructions Always Required after Setting the Global Symbols in a DSECT Macro

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
*                                                                     *
*  DESCRIPTION OF SAM3SR                                              *
*                                                                     *
*                                                                     *
*  A standard prolog follows that contains the following headings     *
*  which allow you to document information about the DSECT            *
*                                                                     *
*                                                                     *
*  1. DATA AREA NAME                                                  *
*  2. MEMBER NAME                                                     *
*  3. INVOCATION                                                      *
*  4. GENERAL CONTENTS AND USE                                        *
*  5. STORAGE FACTORS                                                 *
*  6. DATA CONTROL                                                    *
*  7. IMPLEMENTATION REQUIREMENTS                                     *
*  8. REFERENCES                                                      *
*  9. COMMENTS                                                        *
*                                                                     *
*                                                                     *
*                                                                     *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
         EJECT
         AIF   ('&SW00WRS' EQ '').CHECKID
#SAM3SRS EQU   &SW00WRS      BLOCK SIZE
.CHECKID AIF   ('&SW00WID' EQ '').NOT1ST
#SAM3SRI EQU   C'&SW00WID'   FILE ID
.NOT1ST  ANOP
Note:
The #SAM3SRI equate in Figure 35 is set for a file ID that is in character format. If the file ID is in hexadecimal format, change the equate to:
#SAM3SRI EQU   X'&SW00WID'   FILE ID

Block Header

Do not change the instructions that define the block header unless you want to put extra information in the extended header in each prime block (see Optimizing the Database Design). You can do this after the standard TPFDF header field.

Figure 36 shows a block header for a DSECT that uses fixed-length or variable-length LRECs.

Figure 36. Instructions to Define the File Header in a DSECT Macro

***********************************************************************
*        STANDARD TPFDF HEADER                                        *
***********************************************************************
SAM3HDR&CG1 DS  CL16         STANDARD FILE HEADER
            DS  CL10         STANDARD TPFDF HEADER
SAM3VAR&CG1 EQU *            START OF VARIABLE USER-AREA
SAM3HDL&CG1 EQU SAM3VAR&CG1-SAM3HDR&CG1  HEADER-LENGTH UP TO SAM3VAR

Defining the LREC Size and LREC ID Fields

Figure 37 shows an example of the instructions needed to define the logical record (LREC) size and the LREC ID fields for a file.

Figure 37. Instructions to Define the LREC Size and LREC ID Fields

            ORG SAM3HDR&CG1
SAM3REC&CG1 DS  0CL1         1ST RECORD START (1=VARIABLE,ELSE SIZE)
SAM3SIZ&CG1 DS  H            SIZE OF LOGICAL RECORD
SAM3KEY&CG1 DS  X            LOGICAL RECORD IDENTIFIER
         AIF   ('&SAM3SR1' EQ '1').KEYEQ  GO IF NOT FIRST ISSUE

The instructions are explained as follows:

SAM3REC&CG1
indicates the size of the LRECs for a file using fixed-length LRECs or it indicates that the file is is using variable-length LRECs.

SAM3SIZ&CG1
creates a 2-byte field that is used in each LREC to hold the actual length of the LREC (used for variable-length LRECs only). Make sure that you include the length of the SIZ field (2 bytes) and the KEY field (1 byte) when calculating the total length of the LREC.

SAM3KEY&CG1
creates a 1-byte field that contains the LREC ID. Its meaning and use are the same for fixed-length and variable-length LRECs.
Note:
Because the SAM3REC definition occurs only once in a DSECT, you can define fixed-length or variable-length LRECs in a file, but not both.

Defining Different LREC IDs in the Same File

Every LREC contains an LREC ID, or primary key, that identifies it in the file. More than one LREC in a file can have the same ID. (It is possible for all LRECs in a file to have the same ID.) Different LREC IDs are used in a file to differentiate between different types of LREC.

Figure 38 shows how you can define two LREC IDs, X'80' and X'90'. The two equates are used later in the DSECT to define the two individual LREC IDs.

Figure 38. Defining Two Different LREC Types in a DSECT

***********************************************************************
*        EQUATE OF LOGICAL RECORD KEYS (KEY AND LENGTH)
***********************************************************************
#SAM3K80 EQU   X'80'         LOGICAL RECORD KEY X'80'
#SAM3K90 EQU   X'90'         LOGICAL RECORD KEY X'90'
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 TPFDF product.

DSECT Instructions for Defining User Fields in LRECs

Define user fields by using DSECT instructions similar to those shown in Figure 39. Figure 39 defines a member number field that contains 10 characters of data and a surname field that contains 20 characters of data.

Figure 39. Defining User Fields in a DSECT

SAM3ORG&CG1 EQU *            START OF LOGICAL RECORD DESCRIPTION  *****
 
***********************************************************************
*        DESCRIPTION OF  F I R S T  LOGICAL RECORD TYPE               *
***********************************************************************
SAM3A80&CG1 DS  0CL30        KEYAREA
SAM3NUM&CG1 DS  CL10         member number
SAM3NAM&CG1 DS  CL20         surname
SAM3E80&CG1 EQU *            END OF LOGICAL RECORD WITH KEY = X'80'
Note:
For index files, the TPFDF product determines how much data to move into an index LREC when a DBIDX macro or dfidx function is issued by calculating the number of bytes between the beginning of the key area and the end of the key area. In Figure 39, this would be 30 bytes (SAM3E80 minus SAM3A80).

Algorithm DSECT Statements

The algorithm area size must be defined for each detail file and any intermediate-index files, but is not required for top-level index files or files that are not part of a basic indexing structure. The size of the algorithm string is normally calculated using information in the DSECT of the detail or intermediate-index file. The reserved labels dsnd@nBEG&CG1 and dsnd@nEND&CG1 are used to indicate the beginning and end of the algorithm string.

Notes:

  1. dsnd indicates the first 4 characters of the DSECT macro name of a detail or intermediate-index file.

  2. n identifies the path number to which the definition applies.

Figure 40 shows these labels used in the SAM5SR sample DSECT.

Figure 40. DSECT Code to Define the Algorithm String Size

***********************************************************************
*        ALGORITHM DESCRIPTION                                        *
***********************************************************************
         ORG SAM5REC&CG1
SAM5@0BEG&CG1 EQU *             PATH 0 DESCRIPTION
SAM5@0...&CG1 DS
SAM5@0...&CG1 DS
SAM5@0...&CG1 DS
SAM5@0END&CG1 EQU *

Notes:

  1. @0 indicates that this applies to path zero (0).

  2. The labels between the BEG and the END labels can be used to define parts of the algorithm string.

Ending DSECT Statements

See Figure 41 for the instructions required at the end of each sample DSECT macro. Do not change them.

Figure 41. Instructions Always Required at the End of a DSECT Macro

.*
.**********************************************************************
         AIF   (&BG1).MACEXIT          GO IF INTERNAL USAGE
&SYSECT  CSECT
         AIF   ('&REG' EQ '').MACEXIT  GO IF REG= NOT SPECIFIED
.GEUSING ANOP                          GENERATE USING
         USING &DSN,&REG
.MACEXIT ANOP
         SPACE 1
         MEND