Customizing the TPFDF code for your installation

Edit online

Some TPFDF macros and a TPFDF header file require adjustments for individual installations. The following sections outline the changes required for TPFDF macros, programs, utilities, or the header file, including:

Setting symbols in the DBLCL macro.
Setting symbols in the ACPDBE macro.
Setting parameters in the C$ACPDBE header file.
Setting parameters in the C$CRUUSR header file.
Setting symbols in the BLKSZ macro.

These macros are found in the data set with the trailing qualifier, BDFMAC1. The header file is found in the data set with the trailing qualifier, BDFHDR1. If they need to be changed, use a user modification (SMP/E USERMOD).

Setting symbols in the DBLCL macro

The DBLCL macro contains SETB and SETC instructions, which define installation options for the TPFDF product. The following table describes the symbols defined in the DBLCL macro and provides information about the recommended settings.

Note: The DBLCL macro replaces the ACPGBL macro. The ACPGBL macro is included in this shipment for those installations that have DSECTs that require it.

Table 1. Setting Symbols in DBLCL
DBLCL Symbol	Description and Setting
&ACPDBAA	Specify whether ECBs processing ZUDFM commands will use an Agent Assembly Area (AAA). 0 AAA attached on level 1 or RCB attached on level 3. 1 No AAA attached on level 1 or RCB attached on level 3.
&ACPDBCB	0 GETCC clears blocks to zeros.
&ACPDBFS	Enables TPFDF to create a block trailer and to stamp each block with the time, the command, and so on when a block is filed on DASD. You can display the stamped information using the ZUDFM OAF and ZUFDM OA*/D/HDR commands. 0 Do not create a block trailer. 1 Create a block trailer and stamp each block.
&ACPDBID	Used to specify the ID range formula. 0 Use the ID range of #TPFDBID to X'FFFF' (where the value of #TPFDBID is defined in ACPDBE). 1 Use the ID range formula in UWA2. Set this to 0. If you specify 1, you must also write an ID range formula in UWA2 because no ID range formula is provided as part of UWA2 in the TPFDF product.
&ACPDBIN	Determines if a `TRAPC START` should be generated at the beginning of each macro expansion, and `TRAPC COMPLETE` at the end. Note: You must provide the `TRAPC` macro. 0 Do not generate trace intercepts. 1 Generate trace intercepts.
&ACPDBOF	Offline operating environment. 0 The initial setting is MVS.
&ACPDBST	0 Support for the ALCS trace facility.
&ACPDBSY	Specify online operating environment. 1 ALCS
&ACPDB4K	0 4-KB block support (pool files).
&DB0138	Specifies when message DB0138 is issued to inform you that an application program attempted to access a pool file address that was previously released by another application program. The initial setting is 0. 0 DB0138 message is always issued. 1 DB0138 message is only issued if the file is in hold status.
&DB013A	Specifies if a DB013A system error is issued to inform you that a file was read backward without having full backward chaining defined. The initial and recommended setting is 0. 0 DB013A system error is issued when a file is read backward without full backward chaining defined. 1 DB013A system error is not issued when a file is read backward without full backward chaining defined. Note: Setting symbol &DB013A to 1 may impact overall system performance. If backward chains are not available, TPFDF may need to search forward from the prime block to locate the requested record. This will require a large number of I/Os if there are a large number of overflow blocks. Files that use add current processing (&SW00OP1 bit 2 set to 1) with no chains (&SW00NOC equal to 0) can always be read backwards even if symbol &DB013A is set to 0 and full backward chaining is not defined. See TPFDF Database Administration for information about backward chaining. See TPFDF Programming Concepts and Reference for more information about reading backward.
&DB013E	Specifies whether system error DB013E returns to the application program or exits the entry control block (ECB). The initial setting is 0. 0 After issuing the DB013E system error, the entry control block (ECB) is exited. 1 After issuing the DB013E system error, control returns to the application program.
&DFMDBF	Indicates if TPFDF is enabled for an MDBF environment. 0 Always 0 for ALCS (no MDBF)
&DFPAGE	Does not apply to ALCS systems.
&DFRECAB	Does not apply to ALCS systems.
&DFREP	Does not apply to ALCS systems.
&DF31BIT	Indicates if all customer-written TPFDF application programs are allocated in 31-bit addressing mode. 1 Always 1 for ALCS (all customer-written TPFDF application programs are allocated in 31-bit addressing mode).
&INHIDEF	Does not apply to ALCS systems.
&KMNVAL	Specifies the severity value for the following key organization MNOTEs: `KEYn ORG NOT ALLOWED IF GENERAL ORG GIVEN KEYn REQUIRES ORG IF NO GENERAL ORG GIVEN KEYn HAS ORG, BUT NO KEY1 ORG OR GENERAL ORG` The initial setting is 8. You can set a lower value but this may cause MNOTE errors to be overlooked when you assemble TPFDF programs.
&L3DBIFB	Specifies whether L3 blocks are being used for the database interface block (DBIFB) as defined by the #TPFDBSW value in the ACPDBE macro. The initial setting is NO. Do not change this value. A corresponding value must be set for variable _L3DBIFB in the C/C++ C$ACPDBE header file. NO Specifies that L3 blocks are not being used for the DBIFB (#TPFDBSW is not set to L3). Set _L3DBIFB to 0 in the C/C++ C$ACPDBE header file. YES Specifies that L3 blocks are being used for the DBIFB (#TPFDBSW is set to L3). Set _L3DBIFB to 1 in the C/C++ C$ACPDBE header file. When &L3DBIFB is set to YES, the maximum amount of space available to the DBSPA and DBOPN macros, and the `dfspa` and `dfopn` functions, is 3880 bytes. See TPFDF Programming Concepts and Reference for more information about these macros and C functions.
&L3ORL4	Set to the 4-K block size equate to be used by the TPFDF product for system databases and working storage. Allowed values are L3 or L4. The same value must be used for variable _L3ORL4 in the C/C++ C$ACPDBE header file. Additionally _L3ORL4S in the C/C++ C$ACPDBE header file should be set to 4000 when using L3 and 4095 when using L4.The initial setting is L4.
&MISTYPE	An array that allows you to declare as many as 20 record-type prefixes for miscellaneous record-type files. This array is used to identify miscellaneous record-type files for additional validation of the EO# value in a DBDEF macro statement and the &SW00EO# value in a DSECT macro statement. The initial setting is #MISC. Other miscellaneous record-type files can be added to the array as needed.
&MODCHECK	Performs additional checks with the DBMOD command and the `dfmod` function to check the LREC size for all LRECs in the current block. The initial setting is 0. 0 The additional size checks are not performed. 1 The additional size checks are performed. Note: Segment UWAM must be reassembled and loaded whenever this symbol is changed. If this additional check is activated, you must consider the increased path length. Activate this check in test environment only.
&NOTMC	Specifies whether the TPF Transaction Manager (TM) functions are enabled. The initial setting is 0. 0 The TM functions are enabled. 1 The TM functions are not enabled.
&READCHECK	Performs additional checks with the DBRED command and the `dfred` function to check the LREC size for each LREC that the DBRED command or `dfred` function needs to step over internally. 0 The additional size checks are not performed. 1 The additional size checks are performed. The initial setting is 0. Note: Segment UWAP must be reassembled and loaded whenever this symbol is changed. If this additional check is activated, you must consider the increased path length. Activate this check in a test environment only. The additional checks are not performed by the inline code that is generated when the INLINE parameter is specified.
&RECERR	Does not apply to ALCS systems.
&TPFDBDV	When processing in detac mode, this value indicates if a LODIC CONDITIONALDEFER macro is issued when a block is added or reomved from the detac list. The LODIC CONDITIONALDEFER macro will defer the ECB if it is approaching an application timeout (system error 000010). 0 The LODIC CONDITIONALDEFER macro will not be issued. 1 The LODIC CONDITIONALDEFER macro will be issued. The initial setting is 0. Note: Set this symbol to a nonzero value only if you are receiving TPF system error 000010 while processing in detac mode. Use this symbol with caution because it can affect ECB and system performance.
&TPFDBMP	0 No multiprocessor support required.
&TPFOWN	The initial setting is IBM (do not change).

Setting symbols in the ACPDBE macro

The ACPDBE macro contains instructions (EQU) that define symbols. Some of the symbols are installation options for the TPFDF product. Many of the equates used in ACPDBE have synonyms (for example, #ACPDBTS is a synonym for #TPFDBTS). Ensure that the same value is coded for both symbols. The following table describes the symbols defined in ACPDBE and provides information about the recommended settings.

Table 2. Setting Symbols in the ACPDBE Macro
Symbol	Description and settings
#DBCOLL	Used to calculate the space required for data collection. The initial setting is the sum of #DBCOL1 and #DBCOL2, rounded up to a 4-KB boundary; that is, (((#DBCOL1 + #DBCOL2 + 4095) ÷ 4096) × 4096). Do not change this value.
#DBCOL1	Size of the record ID index for data collection. The initial setting is ((X'10000' - #TPFDBID) × 4). Do not change this value.
#DBCOL2	Size of the data area for data collection. The initial setting is (#DBDCNBR × 236). Do not change this value.
#DBDCNBR	Maximum IDs for data collection. The initial setting is 1300.
#DBENUFB	The initial setting is the character on your keyboard that is equivalent to X'4F'.
#DBUIOC8	If your system versions of UIO and UIS do not support scrolling, set this symbol to X'C8'.
#DBUIO80 to #DBUIO85	Used to support special scrolling. If your UIO and UIS programs support special scrolling, TPFDF programs use these symbols to set the UI2MG2 field in the UIO parameter block to UI2PF.
#DFDET_MAX	Maximum number of detached core blocks for all open TPFDF files in the range 20-240 for an ECB. Blocks exceeding this number use short-term pool files. This number can be increased or decreased depending on system resources. This setting does not limit the total number of storage blocks available to the ECB. The initial setting is 200.
#DF_MAX_DSP	Maximum number of lines that are displayed by the DBDSP macro or `dfdsp` function. The initial setting is 0, indicating that there is no limit.
#DFOALOD	Number of lines to be displayed by the ZUDFM OA* command before a LODIC macro is issued, forcing the entry control block (ECB) to relinquish control and potentially avoiding a timeout (system error 000010). The default is 1000.
#DFOATOV	Specifies the frequency value for displaying the UDFM0191I message during ZUDFM entry processing. The default frequency value is 5 seconds. See TPFDF Commands for information about the ZUDFM commands.
#DFUTI01	Creating ECBs in the TPFDF capture/restore utility, information and statistics environment (CRUISE) recalculates the distribution of ECBs over the different levels for every so many ordinals as specified. The #DFUTI01 equate determines how often this is done. The initial setting is 500.
#DFUTI02	Creating ECBs in TPFDF CRUISE recalculates the distribution of ECBs over the different levels depending on the ratio of overflows to prime blocks. The #DFUTI02 equate defines this ratio. The initial setting is 50.
#LLRMLR	Specifies the maximum length allowed a large logical record (LLR). The default value is X'1FFFFF' (2 MB). If this value is changed, program segments UWAQ and UWBM must be assembled.
#L3ORL4	Set to the 4-K block size equate to be used by the TPFDF product for system databases and working storage. Allowed values are L3 or L4. The same value must be used for variable _L3ORL4 in the C/C++ C$ACPDBE header file and for symbol &L3ORL4 in the DBLCL macro. This value also corresponds to the value set for variable #L3ORL4S. The initial setting is L4.
#L3ORL4S	Set to the number of bytes corresponding to the 4-K block size equate specified by the #L3ORL4 equate. Allowed values are 4000 or 4095. The same value must be used for variable _L3ORL4S in the C/C++ C$ACPDBE header file. The initial setting is 4095.
#TO_RELEASE	Percentage of unmodified detached core blocks in the range 1-100 that are released by the system maintenance routine before a pending buffered block in detac mode is moved to a short-term pool file. The default is 10%. The number of unmodified detached blocks is specified by the #DFDET_MAX set symbol.
#TPFCRUQ	Does not apply to ALCS systems.
#TPFDBAC	GF ACP control block. The initial setting is 1 (do not change). This setting is used by third party software packages for general data set support.
#TPFDBD0 to #TPFDBDF	Specifies the data levels used by TPFDF. Even though an application cannot specify a data level when opening a file and most internal operations use data event control blocks (DECBs), some internal TPFDF operations do require the use of data levles. Note: There is no reason to change the default values. Because the application data levels are unchanged across TPFDF calls, the equates will only affect internal processing in the TPFDF product.
#TPFDBFL	Size (in bytes) of the fast-link table. The initial setting is 4096 (do not change).
#TPFDBID	Specifies the lowest record ID that can be used for TPFDF files. For example, if #TPFDBID is set to X'8000', record IDs X'8000'-X'FFFF' can be used. The initial setting is X'0000' for ALCS environments. Note: The lower the value of #TPFDBID, the higher the amount of memory required.
#TPFDBMO	Specifies the maximum number of files that an application program can have open at the same time. A value between 5 and 25 will suit most systems. The initial setting is 25.
#TPFDBOC	GF OS control block. The initial setting is 0 (do not change). This setting is used by third party software packages for general data set support.
#TPFDBSB	Maximum number of blocks to be detached by a DBSRT macro or `dfsrt` function in sort batch. The initial setting is 10.
#TPFDBSW	The size of the SW00SR block. The initial setting is L4 (4095 bytes). The smallest SW00SR block size allowed is L3 (4000 bytes). A 4000-byte block or a 4095-byte block allows as many as three files to be opened without the TPFDF product having to get another block. If you change the #TPFDBSW value, make sure that the size is defined in the RECSIZE and CISIZE parameters of the ALCS macro (see Modifying the ALCS Generation Macro), the BLKSZ macro as described in Updating the BLKS Macro, and the SCTGEN macro SUSIZE and NBRSU parameter values. The default setting of SUSIZE (12 KB) allows the application to use 8 KB and the SW00SR to use 4 KB. Increasing the SW00SR block value decreases the bytes that are available for the application.
#TPFDBTB	Maximum number of blocks to be detached by a DBTRD macro or `dftrd` function. The initial setting is 10.
#TPFDBTS	Specifies the DBDEF table size. The initial setting is ((X'10000' - #TPFDBID) × 4) + 460 + 4 (do not change).
#TPFDB01 to #TPFDBFF	Used to define the TPFDF addressing algorithms (do not change).
#TPFNODE	The number of B⁺Tree nodes buffered in memory. For best performance, set this value equal to (2 * B⁺Tree_level_max) + 1. Note: Where B⁺Tree_level_max equals the number of levels in the deepest B⁺Tree index structure. The default is 10; the minimum is 4. Too high a value can deplete memory, while too low a value can cause thrashing during updates to the B⁺Tree index.

Setting parameters in the C$ACPDBE header file

The C$ACPDBE header file defines the value for the _TPFDBID symbol.

Table 3. Setting Symbols In The C$ACPDBE Header File
Symbol	Description and settings
_L3DBIFB	Specifies whether L3 blocks are being used for the database interface block (DBIFB) as defined by the #TPFDBSW value in the ACPDBE macro. The initial setting is 0. A corresponding value must be set for variable &L3DBIFB in the DBLCL macro. 0 Specifies that L3 blocks are not being used for the DBIFB (#TPFDBSW is not set to L3). Set &L3DBIFB to NO in the DBLCL macro. 1 Specifies that L3 blocks are not being used for the DBIFB (#TPFDBSW is set to L3). Set &L3DBIFB to YES in the DBLCL macro.
_L3ORL4	Set to the 4-K block size equate to be used by the TPFDF product for system databases and working storage. Allowed values are L3 or L4. The same value must be used for variable #L3ORL4 in assembler macro ACPDBE. The initial setting is L4.
_L3ORL4S	Set to the number of bytes corresponding to the 4-K block size equate specified by the _L3ORL4 equate. Allowed values are 4000 or 4095. The same value must be used for variable #L3ORL4S in assembler macro ACPDBE. The initial setting is 4095.
_TPFDBID	Specifies the lowest record ID that can be used for TPFDF files. For example, if _TPFDBID is set to X'8000', record IDs X'8000'-X'FFFF' can be used. The initial setting is X'0000' for ALCS environments. Note: The lower the value of _TPFDBID, the higher the amount of memory required.

Setting parameters in the C$CRUUSR header file

The C$CRUUSR header file contains user-specific settings that you must set before you compile the capture/restore utility, information and statistics environment (CRUISE). The C$CRUUSR header file also defines parameter table default values. These default values are a primary set of values that you can modify when CRUISE is installed. After you have set these values, see Creating a Parameter Table Index for more information.

Table 4. Parameter Table Defaults
Parameter	Description and settings
CRU_DEF_ECB	The entry control block (ECB) start value as specified by a percent in the range 1-100. The initial setting is 10%.
CRU_DEF_IMB	Indicates if combinations used with parameters WID and ADR select embedded references. The initial setting is Y. Y YES N NO
CRU_DEF_MSG_INIT	Indicates if start and complete messages are issued when cross reference files are initialized at the beginning of a CRUISE RESTORE function. The initial setting is 1. 1 specifies that the messages are issued. 0 specifies that the messages are suppressed.
CRU_DEF_NLM	Specifies the number of messages to log. The initial setting is -1. -1 specifies all messages are logged. log specifies the number of messages to be logged, where log is a number in the range 0-100.
CRU_DEF_NPM	Specifies the number of messages to print. The initial setting is -1. -1 specifies that all messages are to be printed. prt specifies the number of messages to be printed, where prt is a number in the range 0-100.
CRU_DEF_RST	Specifies the restore option. The initial setting is R. N specifies that the captured fixed and pool files are restored to new pool file addresses where the data structure is rebuilt. O specifies that the database is restored to the same fixed and pool file addresses that were captured. R specifies that the captured fixed files are restored to the same ordinals that were captured. The captured pool files are restored to new pool file addresses and the database structure is rebuilt. The old pool file addresses are not released when the structure is rebuilt. Z specifies that the captured fixed files are restored to the same ordinals that were captured. The captured pool files are restored to new pool file addresses and the database structure is rebuilt. The old pool file addresses are released when the data structure is rebuilt. X specifies that the captured fixed and pool files are restored to new pool file addresses and the data structure is not rebuilt.
CRU_DEF_SET	Indicates if all pool addresses found are set in use in the pool directory. The initial setting is N. Y YES N NO
CRU_DEF_STA	Specifies if statistics are generated. The initial setting is N. Y YES N NO
CRU_DEF_TAP	Specifies the default tape name. The initial setting is BFA.
CRU_DEF_TAR	Specifies the target system for a capture. The initial setting is T. T TPF M MVS
CRU_LOD_VAL	Specifies the amount of entries that must be available in the ALCS environment to run CRUISE. The initial and minimum setting is 5.
CRU_PFA_X_REF	Indicates if all CRUISE functions create an IRCFDF cross-reference prime file while chain chasing. The initial setting is 0. 1 YES 0 NO

Updating the BLKS macro

The block size (BLKSZ) macro contains information about storage block and record sizes. It is shipped with L0-L4 predefined. Do not change this information. Update the macro to provide additional block types (L5-L8) that your ALCS environment supports. For example, The following code shows the BLKSZ macro with a user-defined block type of L5.

&BT(1)   SETC  'L0'                ONLY VALID FOR MODE 0
&BS(1)   SETA  128
&BN(1)   SETA  0                   NAB NOT VALID FOR L0 BLOCK
&BC(1)   SETA  0
&BT(2)   SETC  'L1'
&BS(2)   SETA  381
&BN(2)   SETA  &BS(2)-36
&BC(2)   SETA  0*16
&BT(3)   SETC  'L2'
&BS(3)   SETA  1055
&BN(3)   SETA  &BS(3)-36
&BC(3)   SETA  1*16
&BT(4)   SETC  'L3'
&BS(4)   SETA  4000
&BN(4)   SETA  &BS(4)-36
&BC(4)   SETA  2*16
&BT(5)   SETC  'L4'
&BS(5)   SETA  4095
&BN(5)   SETA  &BS(5)-36
&BC(5)   SETA  3*16
&BT(6)   SETC  'L5'                BLOCK TYPE CODE

&BS(6) SETA 8192 BLOCK SIZE &BN(6) SETA &BS(6)-36 MAXIMUM NAB &BC(6) SETA 4*16 CTL BITS · · ·

For each additional block that is defined, specify the following:

Block type code (L5-L8)
Block size (in bytes)
Maximum next available byte (NAB). The maximum NAB is 36 bytes less than the block size.
CTL bits, as follows:

L5

Set to 4*16

L6

Set to 5*16

L7

Set to 6*16

L8

Set to 7*16