bdfi1m0aInstallation and Customization

Customizing the TPFDF Product for the TPF System

Some TPFDF macros require adjustment to suit individual installations. The following sections outline the changes required for TPFDF macros, programs, or utilities, including:

Setting Symbols in the DBLCL Macro

The DBLCL macro contains the SETB and SETC assembler instructions, which define installation options for the TPFDF product. Table 1 shows how to set the symbols for a TPF operating system. The TPFDF product must be reassembled to reflect any changes to the options.

Note:
The DBLCL macro replaces the ACPGBL macro. The ACPGBL macro is included in this shipment to support installations using DSECTs from previous versions of this product. Ensure that the global symbols in the ACPGBL macro for: are set to the same value as in the DBLCL macro.

Use the recommended settings specified in Table 1. Using settings other than those specified may produce unpredictable results.

Table 1. Setting Symbols in the DBLCL Macro for the TPF System

DBLCL Symbol Description and Settings
&ACPDBCB Specify block status in GETCC. TPF provides an option to clear all blocks to X'00'. The symbol &SBCLEAR in SYSET controls this action. If &SBCLEAR is set to clear all blocks, &ACPDBCB should be set to 0; if not, &ACPDBCB must be set to 1.

0
TPFDF assumes that all blocks obtained with a GETCC macro are cleared to X'00' using &SBCLEAR.

1
TPFDF has to clear the blocks.
&DFMDBF Indicates if TPFDF is enabled for a multiple database function (MDBF) environment.

0
Non-MDBF

1
MDBF
&DF31BIT Indicates if all customer-written TPFDF application programs are allocated in 31-bit addressing mode.

0
One or more customer-written TPFDF application programs are allocated in 24-bit addressing mode.

1
All customer-written TPFDF application programs are allocated in 31-bit addressing mode.
Note:
If you set &DF31BIT to 1, you must change all TPFDF fast link programs and programs that contain DBDEF macros to 31-bit addressing mode.
&ACPDB4K Specify block size (pool files).

0
4-KB pool blocks.

1
No 4-KB pool block support.
Set this to 0.
&ACPDBSY Specify operating system.

0
TPF
&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 Support for trace facility (supplied by a third party). This symbol defines whether an ENTRC to UFDA is required for ZUDFM OAS entries.

0
Trace interface support required. The user exit UFDA must be written to provide the address of the DBIFB in the traced ECB.

1
Trace interface support is not required, the message UNABLE TO PROCESS is given in response to ZUDFM OAS entries.
&ACPDBOF

0
MVS offline system.

&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 The initial setting is 1 (do not change). RLCHA is used 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 Indicates if TPFDF is enabled for multiprocessing in a loosely-coupled environment.

0
Non-multiprocessing

1
Multiprocessing
&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 Specifies if broken chains should be reported to the printer during recoup phase 1.

0
Print the message.

1
Do not print the message.
&DFREP Specifies if the TPFDF recoup activity report message (RECP9011I) should be displayed during TPFDF recoup.

0
Does not suppress the message.

1
Suppresses the message.
&DFPAGE

0
If the ZUDFC DISPLAY command displays more than one page of output, use the CLEAR key to display additional pages.

1
If the ZUDFC DISPLAY command displays more than one page of output, use the ZPAGE command to display additional pages.

See TPF Operations for more information.

&DFRECAB Specifies if TPFDF recoup should stop or continue if either system error 141302 (file ID found that does not have a DBDEF macro) or 141303 (file ID found that has no recoup information coded in the DBDEF macro):

0
Stop recoup if either system error 141302 or 141303 is issued.

1
Continue recoup if either system error 141302 or 141303 is issued.
&TPFDBDV A value that is compared to the TPF application timeout counter, which is defined in field PFXATMR in data macro DCTPFX. When processing in detac mode, if the TPF application timeout counter becomes less than or equal to this value, the TPFDF product will issue a TPF DLAYC macro. The TPF DLAYC macro causes the TPF application timeout counter to be reset.

You can set the value of &TPFDBDV to any decimal number from 0 to less than the initial setting of the TPF application timeout counter.

For example, assume the initial setting for PFXATMR is 50 (that is, fifty 10ms increments for a 500ms total) and &TPFDBDV is set to 10 in the DBLCL macro. The TPFDF product will issue a TPF DLAYC macro during detac processing once PFXATMR has been decremented to 10 or less (or 100ms or less).

The initial setting of &TPFDBDV is 0, which bypasses the comparison and prevents the DLAYC macro from being issued.

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 Specifies the default value for the PACKINHI parameter in the DBDEF macro.

COND
The PACKINHI parameter defaults to COND. Setting &INHIDEF to COND provides the highest level of protection from recoup missing index LRECs. However, this can increase pool usage and LREC access time during recoup phase 1.

NO
The PACKINHI parameter defaults to NO. Setting &INHIDEF to NO provides more flexibility, allowing customers to decide exactly which files will have packing inhibited. However, there is a risk that recoup can miss index LRECs in files that use the PACKINHI=NO default and which also have a forward index path and reuse old pool blocks during a pack operation.

See TPFDF Database Administration for more information about the PACKINHI parameter and DBDEF macro.

&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 assembler 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 2 lists the recommended settings for these symbols.

Table 2. Setting Symbols in the ACPDBE Macro

Symbol Description and settings
#TPFDB01
to
#TPFDBFF
These 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 TPF systems.

Notes:

  1. The lower the value of #TPFDBID, the higher the amount of memory required for TPFDF tables.

  2. Although this symbol allows the use of any record ID for a TPFDF file, other restrictions may still apply. For example, in the TPF system, the following IDs are reserved for IBM:
    • X'0000'-X'00FF'
    • X'FC00'-X'FFFF'
#TPFDBTS Specify the DBDEF index table size. The initial setting is ((X'10000' - #TPFDBID) × 4) + 460 + 4. Do not change this value.
#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 initial setting 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 TPFDF having to get another block.
#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 The initial setting is TPF (do not change).
#TPFDBG3 The initial setting is V24 (do not change).
#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 Set to 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
If your system versions of UIO and UIS do not support scrolling, set these symbols to X'C8'. 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 and you can set these fields to X'80'-X'85'.
#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 3. 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 TPF systems.

Notes:

  1. The lower the value of _TPFDBID, the higher the amount of memory required for TPFDF tables.

  2. Although this symbol allows the use of any record ID for a TPFDF file, other restrictions may still apply. For example, in the TPF system, the following IDs are reserved for IBM:
    • X'0000'-X'00FF'
    • X'FC00'-X'FFFF'

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_NLM Specifies the number of messages to log. The initial setting is -1.

-1
specifies that 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 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 Does not apply to the TPF system. The initial setting is 0.
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