bdfi1m0hInstallation and Customization

Customizing the TPFDF Code for Your Installation

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:

These macros are found in the data set with the trailing qualifer, 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. Table 9 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 9. Setting Symbols in DBLCL for ALCS

DBLCL Symbol Description and Setting
&ACPDBCB

0
GETCC clears blocks to zeros.

&DFMDBF Indicates if TPFDF is enabled for an MDBF environment.

0
Always 0 for ALCS (no MDBF)
&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).
&ACPDB4K

0
4-KB block support (pool files).

&ACPDBSY Specify online operating environment.

1
ALCS
&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.
&ACPDBST

0
Support for the ALCS trace facility.

&ACPDBOF Offline operating environment.

0
The initial setting is MVS.
&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.
&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.
&ACPDBRF

1
Use RLCHA to release files.

&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.
&TPFDBMP

0
No multiprocessor support required.

&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.
&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.
&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.

Notes:

  1. 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.

  2. 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.

&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.

&RECERR Does not apply to ALCS systems.
&DFREP Does not apply to ALCS systems.
&DFPAGE Does not apply to ALCS systems.
&DFRECAB 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.
&TPFOWN The initial setting is IBM (do not change).
&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.
&INHIDEF Does not apply to ALCS systems.
&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.

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. Table 10 describes the symbols defined in ACPDBE and provides information about the recommended settings.

Table 10. Setting Symbols in the ACPDBE Macro

Symbol Description and settings
#TPFDB01
to
#TPFDBFF
Used to define the TPFDF addressing algorithms (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.
#TPFDBTS Specifies the DBDEF table size. The initial setting is ((X'10000' - #TPFDBID) × 4) + 460 + 4 (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.

Notes:

  1. Where B+Tree_level_max equals the number of levels in the deepest B+Tree index structure.

  2. The default is 10; the minimum is 4.

  3. Too high a value can deplete memory, while too low a value can cause thrashing during updates to the B+Tree index.
#TPFDBFL Size (in bytes) of the fast-link table. The initial setting is 4096 (do not change).
#TPFDBTB Maximum number of blocks to be detached by a DBTRD macro or dftrd function.

The initial setting is 10.

#TPFDBSB Maximum number of blocks to be detached by a DBSRT macro or dfsrt function in sort batch.

The initial setting is 10.

#TPFDBOC GF OS control block. The initial setting is 0 (do not change).
#TPFDBAC GF ACP control block. The initial setting is 1 (do not change).
#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.
#TPFDBSW The size of the SW00SR block. The initial setting is L4 (4095 bytes), the smallest SW00SR block allowed. A 4095 byte block allows as many as five files to be opened without the TPFDF product having to get another block. If there are programs in your system which will have more than five files open at the same time, consider a larger block size to avoid the performance overhead of the GETCC for the additional block.

If you change the #TPFDBSW value, make sure the size is defined in the ALCS macro RECSIZE and CISIZE parameters (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 8KB and the SW00SR to use 4KB. Increasing the SW00SR value decreases the bytes that are available for the application.

#TPFDBGD General data set support tag names (do not change).
#DBDCNBR Maximum IDs for data collection. The initial setting is 1300.
#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.

#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.

#DBDET_MAX Maximum number of detached core blocks for all open files in the range 20-256 for an ECB. Blocks exceeding this number use short-term pool files. This number can be increased or decreased depending on system resources. The initial setting is 200.
#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 #DBDET_MAX set symbol.
#TPFDBG2 Does not apply to ALCS systems.
#TPFDBG3 Does not apply to ALCS systems.
#DB2LUFB The initial setting is OA (do not change).
#DB3LUFB The initial setting is OAEA (do not change).
#DB4LUFB The initial setting is OAEX (do not change).
#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.
#DBENUFB The initial setting is the character on your keyboard that is equivalent to X'4F'.
#DFUTI01 Creating ECBs in TPFDF recoup and 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 recoup and 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.
#TPFDBD0
to
#TPFDBDF
Specifies the data levels to which open files are attached internally. The TPFDF product is shipped to use 15 data levels by default with equates that are sequential from #TPFDBD1 to #TPFDBDF, and then wrapping to #TPFDBD0.
Note:
There is no reason to change the default values. Because the application data levels are preserved across TPFDF calls, the equates will only affect internal data level use in the TPFDF product.
#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.
#DBUIOC8 If your system versions of UIO and UIS do not support scrolling, set this symbol to X'C8'.

Setting Parameters in the C$ACPDBE Header File

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

Table 11. Setting Symbols In The C$ACPDBE Header File

Symbol Description and settings
_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 12. 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_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_STA Specifies if statistics are generated. The initial setting is N.

Y
YES

N
NO
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_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_V Specifies the amount of entries that must be available in theALCS 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, Figure 1 shows the BLKSZ macro with a user-defined block type of L5.

Figure 1. Block Sizes for ALCS

&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: