bdfd1m13Database Administration

DBDEF Macro Parameter Syntax

This section describes DBDEF macro statements according to the following functions:

The description of each function provides a syntax (railroad track) diagram for the macro and a description of each parameter and variable. See How to Read the Syntax Diagrams for more information about syntax diagrams.



Global DSECT Override Parameters

These parameters override the equivalent SW00var statements found in the DSECT macro, where var equals the 3-digit global parameter (for example, ARS. See Assigning Values to Global Set Symbols for more information about these parameters.



ARS=blktype
specifies the overflow block size for the referenced file, where blktype is one of the following block types:

L0
specifies a 128-byte block size.

L1
specifies a 381-byte block size.

L2
specifies a 1055-byte block size.

L3
specifies a 4000-byte block size. This block type is available only in an ALCS environment.

L4
specifies a 4095-byte block size.

L5
specifies a user-defined size. This block type is available only in an ALCS environment.

L6
specifies a user-defined size. This block type is available only in an ALCS environment.

L7
specifies a user-defined size. This block type is available only in an ALCS environment.

L8
specifies a user-defined size. This block type is available only in an ALCS environment.

For example:

ARS=L4

BOR=baseord
specifies the base relative ordinal for the file, where the value of baseord is as follows:

EOR=endord
specifies the end ordinal for the file, where the value of endord is as follows:
Note:
For more information about partitioning and interleaving, see Partitioning and Interleaving.

EO#=faceendord
specifies the FACE-type end ordinal (for TPFDF recoup), where the value of faceendord is as follows:

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.

  4. For more information about partitioning and interleaving, see Partitioning and Interleaving.

ILV=ilvnum
specifies the interleaving number, where ilvnum is a nonnegative decimal number. If ilvnum is a nonzero value, it implies that the file is interleaved. The number you assign defines the number of interleaves. For example:
ILV=3
Note:
For more information about interleaving, see Interleaves.

NLR=maxlrecs
specifies the number of LRECs that can fit into each prime block of a file, where maxlrecs is a nonnegative decimal number. 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 NLR to the maximum number of LRECs that can fit into each prime block of the file.

Notes:

  1. The NLR parameter is not allowed for B+Tree data files.

  2. Using the NLR parameter will result in an MNOTE being issued because the TPFDF product calculates this value, and any value specified is ignored.

NOC=maxchains
specifies the number of overflow blocks to use in implementing add current files, where maxchains is a nonnegative decimal number. Only assign a value to NOC when bit 2 of &SW00OP1 is set on. Setting bit 2 of &SW00OP1 instructs the TPFDF product to limit the number of overflow blocks to use when adding LRECs to the subfile. You can set the limit (using NOC) 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:
NOC=5

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

If NOC is set to zero, the TPFDF product uses only the prime block of the subfile.

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

OP1=op1
specifies TPFDF processing options, where op1 is a bit setting that overrides the &SWOOOP1 bit setting. For example,
OP1=10000000

sets OP1 bit 0 to indicate the file uses backward chaining. See Assigning Values to Global Set Symbols for more information about &SW00OP1 processing options.

OP2=op2
specifies TPFDF processing options, where op2 is a bit setting that overrides the &SWOOOP2 bit setting. For example,
OP2=00010000

sets OP2 bit 3 so the file uses new overflow blocks and releases old overflow blocks when a tape load operation completes successfully. See Assigning Values to Global Set Symbols for more information about &SW00OP2 processing options.

OP3=op3
specifies TPFDF processing options, where op3 is a bit setting that overrides the &SWOOOP3 bit setting. For example,
OP2=00000100

sets OP3 bit 5 to indicate that the file uses B+Tree indexing. See Assigning Values to Global Set Symbols for more information about &SW00OP3 processing options.

PIN=packthresh
specifies the packing threshold, where packthresh is a decimal number from 0-100. For example:
PIN=60

PTN=ptnnum
specifies the number of partitions, where ptnnum is a nonnegative decimal number. If ptnnum is a nonzero value, it implies that the file is partitioned. The number you assign defines the number of partitions. For example:
PTN=4

Note:
For more information about partitioning, see Partitions.

RBV=algtype
specifies the algorithm you want to use with this file, where algtype is one of the following:

For example:

RBV=#TPFDB0C

You can also create a unique user-defined algorithm and specify it as algtype See the &SW00RBV description on page *** for more information about specifying an algorithm.

RCT=recordtype
specifies the record type for fixed or miscellaneous files, where recordtype is a defined record type. For example:
RCT=#USREC

SKE=ske
specifies the search key extract for block index support, where ske equals 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 primary key (the LREC ID). For example, if the last field in the key is GR21SRLAST, you would specify:
SKE='GR21SRLAST-GR21SRKEY+L'GR21SRLAST'

Notes:

  1. Make SKE 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 SKE 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. SKE is not allowed for B+Tree data files.

TQK=maxtlrec
specifies the highest technical LREC ID that the TPFDF product can use for this file, where maxtlrec is a decimal number from 1-15. For block indexed files, maxtlrec must be set to a value greater than 2. For B+Tree data files, maxtlrec must be set to a value greater than 4. For B+Tree index files, it must be set to a value less than 3. For example:
TQK=2
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.

TYP=filetype
specifies the file type, where filetype is R, W, T, or P. B+Tree data files must be R-type files. For example:
TYP=R
Note:
See File Names for more information about file types.

WID=fileid
specifies the file identifier, where fileid is a 2-character alphanumeric value (for example, WID=AB), or a 4-character hexadecimal value (for example, WID=B075). Use a unique file ID for every file.

WRS=blktype
specifies the size of the prime block, where blktype is one of the following block types:

L0
specifies a 128-byte block size.

L1
specifies a 381-byte block size.

L2
specifies a 1055-byte block size.

L3
specifies a 4000-byte block size. This block type is available only in an ALCS environment.

L4
specifies a 4095-byte block size.

L5
specifies a user-defined size. This block type is available only in an ALCS environment.

L6
specifies a user-defined size. This block type is available only in an ALCS environment.

L7
specifies a user-defined size. This block type is available only in an ALCS environment.

L8
specifies a user-defined size. This block type is available only in an ALCS environment.

For example:

WRS=L4

Default Key Parameters

Default keys are used by the TPFDF product to maintain file organization when adding LRECs to a subfile. They can also be used by application programs when reading LRECs from a subfile. Default keys are optional in a DBDEF macro for all TPFDF files except B+Tree data files. Default keys are required for B+Tree data files because they are used by the TPFDF product to organize the B+Tree index.

If a default key is defined for one LREC ID, all LREC IDs in that file must have default keys defined. If a file has the default keys subtable defined and the application tries to add an LREC of an LREC ID that is not defined, an OPR-DB0117 system error is issued and the ECB exits.

Default keys are only appropriate for files that have UP or DOWN organization and should not be defined for:




PKY=primarykey
specifies the characteristics of the primary key (LREC ID) of the LREC, where primarykey is one of the following:

Read-only default keys must be in the range X'01' to X'0F' and can be used only for read operations. Read-only default keys can be used to read any combination of keys in an LREC. Therefore, you do not have to read LRECs using the same default keys that you used to create the file. See TPFDF Programming Concepts and Reference for more information about using default keys to read LRECs.

Figure 43 shows a DBDEF that has two default keys defined. The first key, which has an LREC ID of X'80', is the default key that defines the layout and organization of the file that is created when records are added to the file. This key can also be used for read operations.

The second key has a primary key of X'06', which identifies it as a read-only default key. Primary key X'06' does not affect the layout or organization of the file.

Figure 43. Read-Only Default Keys in the DBDEF

* FILE ID X'B073'
         DBDEF FILE=IR73DF,                                            *
               (PKY=#IR73K80,ORG=UP,         READ/ADD DEFAULT KEY      *
               KEY1=(PKY=#IR73K80),                                    *
               KEY2=(R=IR73NAM),                                       *
               KEY3=(R=IR73CTY),                                       *
               KEY4=(R=IR73SAL)),                                      *
               (PKY=#IR73K06,ORG=UP,         READ-ONLY DEFAULT KEY     *
               KEY1=(PKY=#IR73K06),                                    *
               KEY2=(R=IR73NAM),                                       *
               KEY3=(R=IR73CTY))                                       *

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.

FLD=dataid
specifies the 2-byte data identifier (secondary key) of an extended LREC, where dataid is one of the following:

Notes:

  1. The dataid value must resolve to a value from X'0000'-X'FFFF'.

  2. The DID=dataid value in the detail or intermediate-index file must be the same as the FLD=dataid value in this index file.

ORG
specifies the default organization for all fields for the specified primary key (PKY) in an LREC. If you specify an organization for KEY1, that organization overrides the ORG value and becomes the default. If you specify an organization for any other KEYn value, that organization overrides any previous defaults for that field. If you specify a NOORG value for any key, all keys that follow must be NOORG. For example, you cannot specify the following:
KEY1=(PKY=#IR73DF,NOORG),
KEY2=(R=IR73NAM,UP)

UP
arranges the fields in ascending order.

DOWN
arranges the fields in descending order.

NOORG
does not arrange the fields in any order.

KEYn
specifies the organization of the specified key, where n is a number from 2-6.
Note:
Keys must be specified sequentially; that is, if KEY1 and KEY4 are specified, you must specify KEY2 and KEY3.

R=userfield
specifies the name of a user field, where userfield was previously defined in the DSECT macro. For example,
 KEY2=(R=GR00NAM,UP)

Basic Index Parameters

The following must be coded before index parameters are used in the DBDEF macro:

Forward Index Path Parameters

The definitions for the forward path are used by TPFDF recoup, the TPFDF capture/restore utility, information and statistics environment (CRUISE), and some TPFDF macros. Included with the forward index path parameters are descriptions of how the parameters work and some brief examples. For more complete examples of basic indexing, see Basic Indexing.


Notes:

  1. If one parenthesis is specified, both parentheses must be specified. If you do not specify any subparameters with the ID2 or ID3 parameter, parentheses () are not required. For example:
    ID2=,...
    

  2. If CHKF or CHK0 is not specified, the record code check (RCC) of the indexed file is in the RCP field of the index LREC.

  3. Commas are needed only between selected parameters. For example:
    ID3=(RCI,NORECOUP,ORD),...
    

ID1=(NORECOUP)
inhibits chain chasing during recoup, but allows TPFDF CRUISE to use the recoup subtable (assuming RECOUP=YES was specified to generate the subtable); that is, when ID1=(NORECOUP) is specified in a file DBDEF statement, the ZRECP command does not recoup the file.

#IT=-1
specifies that all primary keys (for example, LREC IDs X'80', X'90', and X'A0') forward index the same file with the same TPFDF recoup and TPFDF CRUISE processing attributes (specified by the ID2 parameter).

ITK=indexpky
specifies the primary key (LREC ID) of this index file, where indexpky is one of the following:

You need only one ITK parameter for each primary key. All records that follow with the same primary key (for example, all LREC IDs of X'80') forward index the same file with the same TPFDF recoup and TPFDF CRUISE processing attributes (specified by the ID2 parameter).

Notes:

  1. The attributes specified with the ITK parameter remain in effect for a specified primary key until a new ITK parameter with the same primary key is specified.

  2. The ITK parameter can forward index more than one file by entering address slot arguments with the INDEX parameter.

ID2
specifies options that affect TPFDF recoup and TPFDF CRUISE processing. ID2 is used to describe references held in items. The position of the references is defined only once because the same description applies to each item. ID2 references are defined using CBV=1, CBV=2, CBV=4, or CBV=5. If a block contains a mixture of ID2 and ID3 references, TPFDF recoup processes:
  1. All the ID2= references (specified in items)
  2. All the ID3= references (fixed position).

ID3
specifies options that affect TPFDF recoup and TPFDF CRUISE processing. ID3 is used to describe references held in fixed locations. Each reference is described separately because the reference is not held as a part of an item. If the block contains only ID3 references, CBV=3 is used to identify the structure. If a block contains a mixture of ID2 and ID3 references, they are defined using CBV=1, CBV=2, CBV=4, or CBV=5. In this case, TPFDF recoup processes:
  1. All the ID2= references (specified in items)
  2. All the ID3= references (fixed position).

CHKF
specifies that the record code check (RCC) of the indexed file is the same as the record code check of this index file.
Note:
The RCP parameter must be set to -1, or omitted.

CHK0
specifies that TPFDF recoup should use a record code check (RCC) of X'00'.
Note:
The RCP parameter must be set to -1, or omitted.

NORECOUP
allows the definition of the reference to be used by TPFDF CRUISE, but the reference is not chain chased by TPFDF recoup.

ORD
specifies that the reference is an ordinal number and not a file address.

RCI
specifies that this file contains a reference to a detail file and will use recoup chain-chasing indicator (RCI) processing to avoid unnecessary chain chasing.

RCI processing for a file is specified as follows:

SUB
indicates that there are subitems in items.

Notes:

  1. Subitems can be defined only in customer-format files. See Parameters for TPFDF Recoup and TPFDF CRUISE Processing for Customer-Format Files.

  2. SUB is not allowed with the ID3 parameter.

  3. SUB is not allowed if CBV=5 is specified or used as a default.

  4. Subitems must have a fixed size and start at a fixed location in the item.

  5. Each subitem contains a reference.

  6. Specify the number of subitems using the CNT parameter or specify the location of a count field using the CPT parameter.

  7. Specify the size of the subitem count field using the SSZ parameter.

INDEX=(dsndet,slot)
identifies the file you are forward indexing, where dsndet is a 6-character file (and DSECT) name of the detail or intermediate-index file to which this index file is chained, and slot is the number of an index slot that contains a reference to the detail or intermediate-index file to which this index file is chained. This number must be the same as the index slot coded with the IFR parameter in the detail or intermediate-index file. See the IFR parameter in Backward Index Path Parameters.

Use INDEX if the RID, ADR, and RCP definitions are in the standard positions in the index LRECs. For example, specifying:

  INDEX=(SAM5SR,0)

has the same effect as specifying:

  RID=SAM5SR,ADR=SAM4FAD-SAM4REC,RCP=SAM4RCC-SAM4REC

RID=dsndet
identifies the file you are forward indexing, where dsndet is one of the following:

ADR=addressloc
specifies the relative position of the address field, where addressloc is expressed as the location of the field that contains the file address (FAD) minus the location of the start of the first record (REC). For example,
  ADR=SAM4FAD-SAM4REC

RCP=rccloc
specifies the relative position of the record code check, where rccloc is expressed as the location of the field that contains the record code check (RCC) minus the location of the start of the first record (REC). For example,
  RCP=SAM4RCC-SAM4REC

Note:
When ID2=CHK0, ID2=CHKF, ID3=CHK0, or ID3=CHKF is specified, the RCP parameter must be set to -1, or omitted.

FAL
specifies the number of bytes used to hold the ordinal number when ID2=(ORD) or ID3=(ORD) is specified.

DIT=dataid
for extended LRECs, specifies the 2-byte data identifier (secondary key) of this index file, where dataid is one of the following:

Notes:

  1. The dataid value must resolve to a value from X'0000'-X'FFFF'.

  2. The DID=dataid value in the detail or intermediate-index file must be the same as the DIT=dataid value in this index file. See the DID parameter in Backward Index Path Parameters.

BASE=globalbase
specifies the global base for recoup chain chasing, where globalbase is the name of a global area. BASE, FIELD, and STP=1 are required together to specify that a subfile is referenced from a global field, for example:
STP=1,         * Special monitor
BASE=GLOBZ,    * Global area
FIELD=@KRPCA0  * Global field

Note:
BASE and BASECOD are not allowed together.

FIELD=globalfield
specifies the global field for recoup chain chasing, where globalfield is the name of a global field. BASE, FIELD, and STP=1 are required together to specify that a subfile is referenced from a global field, for example:
STP=1,         * Special monitor
BASE=GLOBZ,    * Global area
FIELD=@KRPCA0  * Global field

CORE
specifies whether the file is located in main storage or on DASD.

YES
specifies that TPFDF recoup and TPFDF CRUISE will retrieve a core block and copy the contents of the main storage file into the core block and pass it to the monitor.

The reference defined by the BASE parameter and the FIELD parameter (or defined by the BASECOD parameter) is a reference to a block in main storage, and not a file address.

NO
specifies that the file is located on DASD and uses normal TPFDF recoup and TPFDF CRUISE processing.

DIS=disloc
specifies the location of a displacement field, which contains a displacement to be added to the ADR value in any ID3 reference, where disloc is the label of an area, a register, or an immediate value. If this is a CNT-type file, the displacement is also added to the value specified by the PIT parameter.

INB=initnab
specifies the initial next available byte (NAB), where initnab is a numeric value.

Notes:

  1. INB can only be specified for P-type files.

  2. Although it cannot be specified for standard-format files (R-type, W-type, and T-type), the initial NAB value for standard-format files is X'1A' (the standard-format header is 26 bytes).

LEV=levval
specifies the ECB level control, where levval is a number in the range 0-7, which specifies the number of levels over which TPFDF recoup will distribute available ECBs.

TPFDF recoup does not recalculate the ECB distribution when the actual level count is less than the last recalculated level value. This may lead to less-effective ECB usage during chain chasing for some data structures. The use of LEV can help to prevent this.

When the LEV parameter value equals 0 (by default or if specified), the TPFDF product uses the following formula to distribute available ECBs over the levels (where actuallevels equals the actual number of levels at run time and maxecbs is the maximum number of ECBs you allow the TPFDF product to use):

for n = 0 to (actuallevels - 1)
 
   Level (actuallevels - n) = .8 * maxecbs * .5n

For example, if LEV=0 was specified and actuallevels equals 4 and maxecbs equals 200, the TPFDF product distributes ECBs as follows:

   Level 4  =  160    ***  Data level               ****
   Level 3  =   80    ***  Intermediate-index level ****
   Level 2  =   40    ***  Intermediate-index level ****
   Level 1  =   20    ***  Top-index level          ****

This distribution assumes that each level gets progressively larger. If your data structure progresses differently, use the LEV parameter to change the distribution.

When levval is less than the actual levels in the structure (for example, if levval equals 3 and the actual levels in the structure at run time equal 5 and maxecbs equals 200), the TPFDF product uses the following formula to distribute available ECBs over the levels.

for n = 0 to (levval - 1)
 
   Level (levval- n) = .8 * maxecbs * .5n
   Level 3  =  160    ***  Intermediate-index level ****
   Level 2  =   80    ***  Intermediate-index level ****
   Level 1  =   40    ***  Top-index level          ****
for n = 1 to (actuallevels - levval)
 
   Level (levval+ n) = 1.1n * Level levval ECBs

   Level 4  =  1.1 * 160
   Level 5  =  1.1 * 1.1 * 160
 
   Level 4  =  176    ***  Intermediate-index level ****
   Level 5  =  194    ***  Data level               ****

MPFSTD
specifies the priority for chain chasing a record.

YES
specifies that this record and any other records with MPFSTD=YES specified must be chain chased before other records are chased.

NO
specifies that this record will be chain chased after all records with MPFSTD=YES specified.

MPNXTD=nextid
specifies the ID of the record for which chain chasing will start when chain chasing is completed for this record, where nextid is a 2-character alphanumeric value (for example, MPNXTD=AB), or a 4-character hexadecimal value (for example, MPNXTD=B075).
Note:
If you specify the MPNXTD parameter, you must specify the MPPRCD parameter.

MPPRCD
specifies the ID of the processor that will chain chase this record. If the specified processor is not active, the primary processor chain chases the record at the end of recoup phase 1 processing.

cpuid
is a 1-character processor identifier.

PRIME
specifies that this record will be chain chased on the primary recoup processor.

MPRECD=previousid
specifies the ID of the record for which chain chasing must be completed before chain chasing can begin for this record, where previousid is a 2-character alphanumeric value (for example, MPRECD=AB), or a 4-character hexadecimal value (for example, MPRECD=B075).

PFC=fwdchain
specifies the position of forward chain, where fwdchain equals the address of the forward chain minus the address of the beginning of the file. For example:
PFC=dsniFCH-dsniBID

Notes:

  1. PFC or CPF is necessary if FCH is present.

  2. PFC is not allowed with CPF.

  3. PFC=-1 is used for a no forward chain file.

  4. The value can also be specified as an absolute displacement.

QUE
specifies whether the data structure is processed in recoup QUE-inhibited mode.

NO
specifies that the file is not recoup QUE-inhibited; that is, the file address can pass references between subfiles during recoup.

If a file is accessed by passing its file address from one subfile to another, the file can be missed during recoup processing. Figure 44 shows how access to the 'PR' file is controlled by passing its file address from one subfile to another (and setting the unused reference to X'0000'). If QUE=NO is specified, recoup is not QUE-inhibited and the 'PR' file is not chain chased as explained in the following:

(1) The subfile addressed by 'AAC' is chain chased.

(2) The subfile ('ZRH') has the file address of 'PR'.

(3) The file address of 'PR' is passed from 'ZRH' to 'AAC'.

(4) The subfile addressed by 'ZRH' is then chain chased.

Note:
The 'PR' file is not chain chased because the file address 'ZRH' no longer has the reference to 'PR'.

Figure 44. QUE=NO Parameter


YES
specifies that the file is recoup QUE-inhibited; that is, the file address cannot pass references between subfiles during recoup. Recoup QUE-inhibited mode is specific to the airline QUEUING function and assumes the application environment is using the @BRCPQ global as the queue control indicator. While TPFDF recoup is performing the queuing phase, BIT0 of the @BRCPQ global is set on. Applications should not pass references while this bit is set. The bit is turned off at the end of the queuing function.
Note:
QUE=YES is not valid for ALCS.

RCIDID=rcitag
specifies that this top-level index file will use recoup chain-chasing indicator (RCI) processing to avoid unnecessary chain chasing, where rcitag is a 4-character alphanumeric value (for example, RCIDID=AB12). The rcitag can be specified to identify top-level index files that are in the same structure.

RCI processing for a file is specified as follows:

RECOUP
specifies whether the table used by the recoup utility and TPFDF CRUISE is built for this data structure

YES
specifies that a recoup table is built for the data structure; therefore, the ZRECP commands and TPFDF CRUISE process this file.

NO
specifies that a recoup table is not built for the data structure; therefore the ZRECP commands and TPFDF CRUISE do not process this file. RECOUP=NO can be specified for ALCS and non-TPFDF files that do not contain embedded references or forward chaining.

RFC
specifies whether TPFDF recoup verifies that the record code check (RCC) in an overflow block is the same as the RCC in the prime block.

YES
specifies that TPFDF recoup checks the RCC of the prime block and overflow blocks.

NO
specifies that TPFDF recoup does not check the RCC of the prime block and that overflow blocks are retrieved with an RCC of zero.

STP=n
specifies the type of chain chasing monitor, where n is one of the following:

0
causes TPFDF recoup and TPFDF CRUISE to chain chase all the ordinals defined in the FACE file type for this file, starting with the lowest ordinal number (BOR) and ending with the highest ordinal number (EO#).

1
specifies that references to this subfile are in a global location or core field.

2-50
Reserved for IBM use.

51-255
Reserved for customer-specific chain chasing monitors.

Note:
BASE and BASECOD require STP=1.

TIMEOUT=seconds
specifies the time-out value for chain-chasing a file structure, where seconds is a number of seconds from 1-900.

Timeouts can be related to timing problems caused by a faulty structure that causes loops in forward chain processing or by too many embedded references at the lower levels of a file structure. If there are too many embedded references, not enough ECBs are allocated to the lower levels and a timeout can occur. The LEV parameter can be used to adjust the number or ECBs that are allocated for each level.

CT1=maxgrouprec
specifies the maximum number of records read for an ALCS group, where maxgrouprec is a nonnegative number.
Note:
The CT1 and CT2 parameters only affect ALCS recoup processing if the TPFDF sample ALCS recoup user exit code (ARD0, ARD1, and ARD2) has been installed. For more information about installing the TPFDF sample ALCS recoup user exit code, see TPFDF Installation and Customization.

CT2=maxstructrec
specifies the maximum number of records read for an ALCS structure that contains all groups chained from any one record in an ALCS prime group, where maxstructrec is a nonnegative number.
Note:
The CT1 and CT2 parameters only affect ALCS recoup processing if the TPFDF sample ALCS recoup user exit code (ARD0, ARD1, and ARD2) has been installed. For more information about installing the TPFDF sample ALCS recoup user exit code, see TPFDF Installation and Customization.

CBV=n
specifies the type of chain chasing monitor, where n is one of the following:

1
Fixed-length type items in NAB or ADD/DEL files.

2
CNT type file.

3
Fixed-position-only references.

4
Variable-length type items in NAB or ADD/DEL files.

5
Specifies that the file is a standard-format file with LRECs with embedded pointers and a logical record ID.

6-50
Reserved for IBM use.

>50
Reserved for customer-specific chain chasing monitors.
Note:
If CBV does not equal 5 (for example, CBV=4), see Parameters for TPFDF Recoup and TPFDF CRUISE Processing for Customer-Format Files to include parameters that specify the location of fields.

Backward Index Path Parameters

The definitions for the backward path are used to access the detail file. Included with the backward index path parameters are descriptions of how the parameters work and some brief examples. For more complete examples of basic indexing, see Basic Indexing.



Notes:

  1. KEY parameters are only required when a search other than the default is required. If KEY parameters are not supplied, the default key fields are as follows:
    KEY1=(PKY=#dsniK80,UP),
    KEY2=(R=dsniA80,S=0,L=L'dsniA80,UP)
    

  2. If you do not specify the L parameter, L defaults to the length of the R parameter.

IID=dsnidx
identifies the backward path of the file whose index LRECs point to this file, where dsnidx is a 6-character file (and DSECT) name of the index file to which this detail or intermediate-index file is chained.
Note:
If the index LRECs are extended, the DID parameter is used to specify the secondary key.

PTH
specifies a path to an index file, where path is a nonnegative decimal number.
Note:
All of the parameters that follow the PTH parameter define the characteristics of the specified path.

IMI
specifies one of the following:

#BIT0
specifies that a path is read only. Read-only paths cannot be used to add indexes. #BIT0 is a system equate that can be specified in binary form. For example:
IMI=10000000

#BIT1
specifies FULLFILE processing from the ordinal defined by BOR to the ordinal defined by EOR. #BIT1 is a system equate that can be specified in binary form. For example:
IMI=01000000

Note:
If #BIT1 is specified, the addressing arguments (IPA and ILA) are ignored.

#BIT2
specifies FULLFILE processing from the ordinal located using the addressing argument defined by IPA and ILA parameters to the ordinal defined by EOR. #BIT2 is a system equate that can be specified in binary form. For example:
IMI=00100000

IKY=indexpky
specifies the primary key (LREC ID) of the index file to which this detail or intermediate-index file is chained, where indexpky is one of the following:

Notes:

  1. Set the IKY parameter value equal to the ITK parameter value of the index file to which this detail or intermediate-index file is chained. 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.

IPA=offset,ILA=L'length
specifies the offset into and length to use of a string passed with the ALG parameter on a DBOPN or other TPFDF macro, where offset and length are nonnegative decimal numbers. This string is used to extract, according to the IPA and ILA parameter, an addressing argument that is used to locate a prime block of an index file.

The following example shows how the IPA and ILA parameter settings defined in a detail file, IR24DF, are used to locate an argument string in an index file, IR25DF.

DBDEF FILE=IR24DF
(IID=IR25DF,
IPA=0,ILA=1,
 
DBOPN REF=IR24DF,ALG=C'SMITH'

In this example, when the DBOPN macro is processed, the TPFDF product accesses the S prime block in the first-level index file, IR25DF. The S prime block is determined by extracting, for a length of 1 bytes (ILA=1), the value found at offset 0 (IPA=0) into SMITH (ALG='SMITH').

IPK=offset,ILK=length
specifies the offset into and length to use of a string passed with the ALG parameter on a DBRED or other TPFDF macro, where offset and length are nonnegative decimal numbers. This string is used to extract, according to the IPK and ILK parameters, an index key that is used to locate an index record in an index file.

In the following example, when the DBRED macro is processed, the TPFDF product reads the SM prime block in the first-level index file, IR20DF.

DBDEF FILE=IR24DF
(IID=IR20DF,
IPA=0,ILA=2
IPK=0,ILK=5
KEY1=(PKY=#IR20K80,UP),   search keys for index
KEY2=(R=IR20NAM,DOWN))
 
DBRED REF=IR24DF,ALG=C'SMITH'

The SM prime block of the first-level index file (IR20DF) is determined by extracting, for a length of 2 bytes (ILA=2), the value found at offset 0 (IPA=0) into SMITH (ALG='SMITH'). The TPFDF product then reads the first index record in the IR20NAM field ((KEY2=(R=IR20NAM,DOWN)) that contains the name SMITH. SMITH is determined by extracting, for a length of 5 bytes (ILK=5) the value found at offset 0 (IPK=0) into SMITH. The TPFDF product then uses the SMITH index record to locate the SMITH detail subfile.

IPE=offset
specifies an offset into a string passed with the ALG parameter on a DBRED or other TPFDF macro, where offset is a nonnegative decimal number. IPE is used with the IPA and ILA parameter, to extract the addressing argument for the end ordinal used in FULLFILE processing. This end ordinal addressing argument starts at the first byte after the starting ordinal addressing argument for a length specified by the ILA parameter.

The following shows how the IPA, ILA, and IPE parameter settings are used by the DBRED macro to read all of the detail subfiles indexed by ordinal 0 ('A') to ordinal 4 ('E'). The #DO loop is executed until all of the detail subfiles have been read.

IPA=0,ILA=1
IPE=1
 
DBOPN REF=GR00SR,REG=R4
#DO INF
   DBRED FULLFILE REF=GR00SR,REG=R4,ALG=C'AE'
#DOEX TM,SW00RTN,#BITA,NZ
#ELOP
#EDO

Beginning ordinal 0 ('A') is determined by extracting, for a length of 1 byte (ILA=1), the value found at offset 0 (IPA=0) into AE (ALG=C'AE'). Ending ordinal 4 ('E') is determined by extracting, for a length of 1 byte (ILA=1), the value found at offset 1 (IPE=1) into AE (ALG=C'AE').

Note:
The IPE parameter should not be used when the hashing algorithms (#TPFDB09, #TPFDB0F, and #TPFDB10) are used to address the top-level index file.

KEY
specifies the position of the index keys in a string passed with the ALG parameter on a DBRED or other TPFDF macro.
Note:
Default keys are not valid for T-type files.

PKY
specifies the primary key of the index LREC.
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.

R=indexkey
specifies the position in the index LREC of the index key, where indexkey is field that contains the index key.

S=offset
specifies the offset in the algorithm string of the data to compare with the index key located by the R parameter, where offset is a nonnegative decimal number.

L=L'indexkey
specifies the length of the index key, where indexkey is field that contains the index key.

ALG=n
For indexed detail files, but not top-level index files, n specifies the size of the algorithm string for each index path, where n is a decimal value. If the algorithm string size is not defined in the DSECT (using the &BEG and &END statements), the ALG parameter must be used to specify the length of the algorithm string.

The following example defines an algorithm string as 4 bytes long:

 (IID=IR23DF,PTH=1,IPA=0,ILA=0,IPK=0,ILK=4,ALG=4)

Notes:

  1. The ALG parameter in the DBDEF macro does not have the same meaning as the ALG parameter in other TPFDF macros and functions.

  2. The ALG parameter must be used in the DBDEF for any file that requires the area to be specified.

  3. The ALG parameter cannot be used with a read-only path (IMI=#BIT0).

DID=dataid
for extended LRECs, specifies the 2-byte data identifier (secondary key) of the index file that refers to this detail or intermediate-index file, where dataid is one of the following:

Notes:

  1. The dataid value must resolve to a value from X'0000'-X'FFFF'.

  2. The DIT=dataid value in the index file must be the same as the DID=dataid value in this detail or intermediate-index file. See the DIT parameter in Forward Index Path Parameters.

IFR=slot
specifies the index slot, where slot is the number of an index slot that contains a reference to the index file to which this detail or intermediate-index file is chained. This number must be the same as the index slot coded with the INDEX parameter in the index file. See the INDEX parameter in Forward Index Path Parameters.

Data Extraction Parameters




ADI=adival
specifies a displacement value, where adival is a decimal value.
Note:
The ADI displacement value is used by the AREA parameter in the DBRED macro to identify where to put an extracted data string.

LDI=ldival
The displacement (in an index LREC) of the start of the data to extract, where ldival is a decimal value.

LLE=adival
The number of bytes to extract, where lleval is a decimal value.

Parameters for TPFDF Recoup and TPFDF CRUISE Processing for Customer-Format Files

Besides support for TPFDF files used in recoup and CRUISE, the DBDEF parameters support the following type of customer-format files:

Note:
For more information and examples of customer-format files, see Using Customer-Format Files.



The following parameters are used with the CBV parameter to describe the basic characteristics of a customer-format file when CBV=1, CBV=2, CBV=3, or CBV=4 is specified. For more information about the CBV parameter, see Forward Index Path Parameters.

RCO
specifies the recoup concatenation value.

(FNR=versionref)
specifies the next file version to chain chase, where versionref is a number from 0-255.

(TYP=END,FNR=versionref)
specifies the last file version for this file and the file version where the chain chasing starts again, where versionref is a number from 0-255.

Complicated customer-format data structures such as a mixture of CNT (CBV=2) and fixed-position references (CBV=3) require different file versions for each structure. Each file version has a different recoup table associated with it. The recoup concatenation order (RCO) parameter avoids separate chain chasing for each of the tables, as shown in the following example:

        DBDEF FILE=GR21SR,FVN=0,     FILE VERSION 0                  X
              CBV=3,.....,           THE CBV=3 LAYOUT                X
              ......,                                                X
              RCO=(FNR=1)            CHAIN CHASE FILE VERSION 1 NEXT
        DBDEF FILE=GR21SR,FVN=1,     FILE VERSION 1                  X
              CBV=2,.....,           THE CBV=2 LAYOUT, NAB TYPE      X
              ......,                                                X
              RCO=(FNR=2)            CHAIN CHASE FILE VERSION 2 NEXT
        DBDEF FILE=GR21SR,FVN=2,     FILE VERSION 2                  X
              CBV=2,.....,           THE CBV=2 LAYOUT, CNT TYPE      X
              ......,                                                X
              RCO=(TYP=END,FNR=0)    END OF LIST, GO BACK TO FVN 0

RAD=addptr
specifies the location of the ADD field in an ADD/DEL type record, where addptr equals the address of the ADD field minus the address of the beginning of the file. For example:
RAD=GP01FLD-GP01BID

RDE=delptr
specifies the location of the DEL field in an ADD/DEL type record, where delptr equals the address of the DEL field minus the address of the beginning of the file. For example:
RAD=GP01FLD-GP01BID

Note:
The value can also be specified as an absolute displacement.

ITS=itemsize
specifies the item size for fixed length items in CBV=1 or CBV=2 type files. where itemsize equals the length of an item. For example:
ITS=L'GP01ITM

Notes:

  1. All items must be the same size.

  2. The value can also be specified as an absolute displacement.

NAB=firstitem
specifies the position of the first item in the block in a CBV=1 or CBV=4 type file, where firstitem equals the address of the first item minus the address of the beginning of the file. For example:
NAB=GP01ITM-GP01BID

PNB=nabfield
specifies the position of the NAB field in a CBV=1 or CBV=2 type file, where nabfield equals the address of the NAB field minus the address of the beginning of the file. For example:
PNB=GP01NAB-GP01BID
Note:
The value can also be specified as an absolute displacement.

FSZ=nabsize
for CBV=1, CBV=2, or CBV=3 type files, FSZ specifies the length in bytes of the CNT or NAB field, where nabsize equals 1, 2, 3, or 4. For example:
FSZ=1

PIS=itemsizeptr
specifies the location of the field in each item that contains the item size for CBV=4 type files, where itemsizeptr equals the address of the SIZ field minus the address of the beginning of the item. For example:
PIS=GP01SIZ-GP01ITM
Note:
The value can also be specified as an absolute displacement.

ISZ=itemsize
for CBV=4 type files, ISZ specifies the length (in bytes) of the item size field, where itemsize equals 1, 2, 3, or 4. For example:

ISZ=3

CNT=itemnbr
specifies the number of items in the record for a CBV=2 type file, where itemnbr is a decimal number. For example:
CNT=3

PIT=firstitem
for CBV=2 type files, PIT specifies the position of the first item, where firstitem equals the address of the first item minus the address of the beginning of the file. For example:
PIT=GP01ITM-GP01BID
Note:
The value can also be specified as an absolute displacement.

CPT=cntptr
specifies the location of the CNT field for CBV=2 type files, where cntptr equals the address of the CNT field minus the address of the beginning of the file. For example:
CPT=GP01CNT-GP01BID

SSZ=subsize
for CBV=1, CBV=2, CBV=3, or CBV=4 type files, SSZ specifies the length, in bytes, of the subitem count, where subsize equals 1, 2, 3, or 4. For example:
SSZ=1

TPFDF Recoup User Exits

The TPFDF product has recoup and CRUISE user exits that allow you to run user-defined code:




label
specifies a user-supplied name that identifies user-defined code that starts at the CDLBL parameter. A user exit label must match the label specified with the CDLBL parameter.

BASECOD
specifies the label of installation-wide exit code to determine the location of the file. The installation-wide exit code:

Notes:

  1. BASE and BASECOD are not allowed together.

  2. BASECOD requires STP=1.

  3. Ensure that register R15 contains the file address or core address of the user code.

  4. If the reference itself is a main storage address rather than a file address, specify CORE=YES.

CDE
specifies code to be used when the retrieval of the forward index pointer caused an error.

Notes about the user code:

  1. The CDE parameter is not valid for ALCS.

  2. The address of the block that contains the forward index pointer is contained in level D0 (field name EBCFA0) of the ECB.

  3. The address of the block that caused the retrieval error (forward index pointer) is in level D1 (field name EBCFA1) of the ECB.

  4. EBCFA1 might be changed for a second attempt of retrieval.

  5. The user code must include one of the following statements to return to TPFDF recoup:
    • To inhibit TPFDF recoup from continuing, use:
      B 0(,R6)
      

      (The current ECB exits, forcing a time-out in the main monitor.)

    • To allow the TPFDF product to retry the retrieval of this reference for a second time, use:
      B 4(,R6)
      

CDO
specifies code to be used before the forward index pointer is retrieved.

Notes about the user code:

  1. The address of the block that contains the forward index pointer is in level D0 (field name EBCFA0) of the ECB.

  2. Register 5 (R5) is pointing to the LREC where the forward index pointer is located.

  3. The user code must include one of the following statements to return to TPFDF recoup:
    • To inhibit TPFDF recoup from chain chasing all references, use:
      B 0(,R6)
      
    • To inhibit TPFDF recoup from chain chasing this reference, use:
      B 4(,R6)
      
    • To allow TPFDF recoup to continue with this reference, use:
      B 8(,R6)
      

CDR
User code to override the following values at run time:

You can use CDR to specify an exit to user code that overrides various values at run time.

Notes about the user code:
Table 35 shows how the installation-wide exit code should write values into fields in the ECB (EBW050 and EBW054), or into register 5 (R5) to override the values used by TPFDF recoup.

Table 35. Using CDR to Override the CNT, PNB, NAB, PIT Values at Run Time

CBV=1
or
CBV=4
  • The maximum NAB value is used for ADD/DEL-type files and NAB-type files.
  • The location of the NAB is determined using dsndNAB-dsndBID
  • EBW050 is used to override the maximum NAB value.
  • The value in R5 replaces the initial NAB value (INB) Use register 5 (R5) to change the INB. INB=X'1A' is for TPFDF files (The TPFDF header is 26 bytes).

CBV=2
  • The user code stores the position of the first item in register R5.
  • TPFDF recoup takes the value in R5 and adds it to the value specified by PIT= (for example, see Figure 45).
  • The user code can also put the number of items in the work area EBW054.
  • Because you can modify EBW054, the value is not added to the value in CNT field.

CBV=3 The user code places the number of references in R5.

Notes:

  1. The CDR parameter is not valid for ALCS.

  2. The address of the block that contains the reference is in level D0 (field name EBCCR0) of the ECB.

  3. EBCCR0 is the main storage reference word of level D0.

  4. CE1CC0 is the 2-byte area which contains the block size of D0.

  5. EBCFA0 is the file address of D0.

  6. The user code must use the following statement to return to TPFDF recoup:
    B 0(,R6)
    

Figure 45 shows an example of how the CDR parameter is used.

Figure 45. Using the CDR Parameter to Override PIT Parameter Value


Notes:

  1. The COA parameter is not valid for ALCS.

  2. Figure 45 shows a CNT-type file in which the position of the first item is not fixed and cannot be determined when the DBDEF is defined.

  3. Each block contains a displacement field (dsniDIS), which contains the position of the first item in the block.

  4. User code is required to override the PIT value.

  5. Register 5 (R5) points to the first item (based on the PIT parameter), so the PIT parameter is zero (0).

CEB
User code to be run before references in the block are processed.

Notes about the user code:

  1. The CDE parameter is not valid for ALCS.

  2. The address of the block about to be processed is in level D0 (field name EBCFA0) of the ECB.

  3. The user code must use one of the following statements to return to TPFDF recoup:
    • To inhibit TPFDF recoup from processing this block, use:
      B 0(,R6)
      
    • To allow TPFDF recoup to process this block, use:
      B 4(,R6)
      

CEE
User code to be run after references in the block are processed.

Notes about the user code:

  1. The address of the block to be processed is in level D0 (field name EBCFA0) of the ECB.

  2. The user code must use the following statement to return to TPFDF recoup:
    B 0(,R6)
    

COA
User code to be run just after a block is retrieved.

Notes about the user code:

  1. The COA parameter is not valid for ALCS.

  2. The address of the block that has just been retrieved is in level D0 (field name EBCCR0) of the ECB.

  3. The user code must include one of the following statements to return to TPFDF recoup:
    • To inhibit TPFDF recoup from chain chasing a block, use:
      B 0(,R6)
      
    • To allow TPFDF recoup to process this block, use:
      B 4(,R6)
      

COE
User code to be run if there is an error when retrieving a block.

Notes about the user code:

  1. The address of the block retrieved is in level D0 (field name EBCFA0) of the ECB.

  2. The user code must use one of the following statements to return to TPFDF recoup:
    • To inhibit TPFDF recoup from trying to retrieve the block again, use:
      B 0(,R6)
      
    • To retrieve this block again, use:
      B 4(,R6)
      

CPF
User code to determine the location of the forward chain field.

Notes about the user code:

  1. CPF is not allowed with PFC.

  2. PFC or CPF is necessary if FCH is present.

  3. The user code should write the location of the forward chain field into EBW030.

  4. The address of the block that contains the reference is in level D0 (field name EBCCR0) of the ECB.

  5. The user code must use the following statement to return to TPFDF recoup:
    B 0(,R6)
    

CDLBL
specifies an assembler label that defines the start of user code.

Notes:

  1. CDLBL must be the last DBDEF macro statement coded in a segment or the DBDEF table will be corrupted.

  2. If a work area is required, the following sequence is recommended:
    GETCC Dx,Lx
    DBDEF CDLBL=RAP
    

  3. If there is an SVC in the user code, it must be followed by a DBDEF CDLBL=RAP statement to reinstall the program base. For example:
    DBDEF CDLBL=label
           .          * User code
           .          * More user code
          GETCC DE,L1 *   (example of a macro that issues an SVC)
     
    DBDEF CDLBL=RAP
           .          * More user code (continued)
          B 0(,R6)    *   (return to TPFDF recoup)
    

  4. If the following registers that are used to return to TPFDF recoup have been modified, restore them:
    • R6, for all user code parameters except the BASECOD parameter
    • R7, for the BASECOD parameter.

  5. All TPFDF recoup user code is entered in 31-bit mode.

B+Tree File Parameters

The following describes DBDEF parameters that are used exclusively for B+Tree files. B+Tree indexing requires other DBDEF parameters and has other considerations than are listed here. For more information, see B+Tree Indexing.



NODE
specifies one of the following:

NO
specifies that this file is not a B+Tree index file.

YES
specifies that this file is a B+Tree index file.

NODEID=fileid
specifies the fileid, where fileid is the file ID of a B+Tree index file associated with this data file. You can find this value in the DSECT of the selected B+Tree index file.
Note:
NODE=YES and NODEID cannot be used in the same DBDEF statement.

Miscellaneous Parameters




Notes:

  1. MDBF parameter statements are only used if SSU=U.

ACPDB
specifies whether this is a TPFDF file.

NO
specifies that this a non-TPFDF file. The TPFDF product uses the DBDEF macro definitions for chain chasing during the processing of recoup and CRUISE, but cannot access or manipulate the file using other macros and functions.

YES
specifies that this is a TPFDF file. The TPFDF product uses the DBDEF macro definitions for chain chasing during the processing of recoup and CRUISE, and can access and manipulate the file using other macros and functions. The file type must be R, W, T, or P. See File Names for more information about file types.

APL=C'appl'
overrides any application type that was specified in the first character of the 6-character DSECT name, where appl is a one-character type of application. For example:
APL=C'G'

See File Names for more information about application types.

DDA
specifies the distributed data access support.
Note:
DDA is not allowed for P-type files.

DELEMPTY
specifies one of the following:

YES
specifies that the TPFDF product will delete empty blocks without packing the subfile. Setting DELEMPTY=YES requires the following:
  • The file must be R-type.
  • Backward chaining must be indicated by bit 0 of global set symbol &SW00OP1.
  • The DBDEF NODE parameter must be NO.
  • The DBDEF FVN parameter must be 0.

NO
specifies that the TPFDF product will delete empty blocks only when the subfile is packed.

DEV
specifies the device type used by CRUISE with the TPF GETFC macro. The DEV parameter has no effect on ALCS systems.
Note:
A, B, C, and D refer to different DASD types defined at system initialization. See TPF System Generation for more information.

FVN=versionnbr
identifies the version of a file, where versionnbr is a number from 0-255. For example,
FVN=3

identifies the file as version 3. Other versions of the file can be defined with a different block layout.

Note:
The DBDEF macro statements for the different versions of a file should be defined contiguously using increasing file version numbers. Only the first file version (FVN=0) is indexed in the DBDEF index table.

FNR=versionref
identifies the version of a file that this file refers to, where versionref is a number from 0-255. The FNR value equals the FVN value of the referenced file. For example,
FNR=3

refers to version 3 (FVN=3) of the referenced file.

GREG
specifies the register call for global base.

REGR
specifies that R14 is the base register for global area 1.

REGC
specifies that R14 is the base register for global area 3.

REGS
specifies that R14 is the base register for global area 3.

KEYCHECK
specify YES to validate the default keys before replacing or modifying an LREC, which will prevent corruption of the file organization.

Notes:

  1. If you use global modification when KEYCHECK=YES, and any of the fields being modified overlap any default key fields for that primary key in the file, the TPFDF product issues a system error (DB0139) and processing ends. All records that were changed before processing ended remain changed.

  2. Before you can use global modification with KEYCHECK=YES in an ALCS environment, enable C language support. See TPFDF Installation and Customization for more information.

  3. If you enter the DBREP macro with KEYCHECK=YES, any keys in effect from previous TPFDF macros become unpredictable.

  4. If you enter the DBMOD macro without the ALL parameter after you have entered the DBRED INLINE macro with KEYCHECK=YES, the TPFDF product may not check the keys.

PACKINHI
specifies if packing should be inhibited for this file during recoup phase 1:

COND
packing is inhibited only if this file includes a forward index path (see Forward Index Path Parameters) and bit 1 of &SW00OP2 is 0, indicating that pool blocks are reused during a pack operation. Packing is inhibited for these files because it is possible for recoup to miss index LRECs if they are moved to a block that has already been chain chased.

NO
packing is not inhibited for this file during recoup phase 1.

YES
packing is inhibited for this file during recoup phase 1.

Notes:

  1. The default for the PACKINHI parameter is specified by set symbol &INHIDEF in the DBLCL macro. See TPFDF Installation and Customization for more information about the DBLCL macro.

  2. This parameter has no affect in an ALCS environment.

PF0
specifies the type of pool blocks that are associated with pool file 0 (PF0). The pool block type associated with PF0 is used by a TPFDF macro or function when the POOLTYP=0 parameter is specified with that macro or function. For example, when PF0=SS:
DBOPN REF=IR00DFX,POOLTYP=0

opens a short-term pool block.

Note:
For W-type files, the default is always short-term (SS) and must not be changed.

LS
Long-term nonduplicated pool.

SS
Short-term pool.

LD
Long-term duplicate pool.

PF1
specifies the type of pool blocks that are associated with pool file 1 (PF1). The pool block type associated with PF1 is used by a TPFDF macro or function when the POOLTYP=1 parameter is specified with that macro or function. For example, when PF1=SS:
DBOPN REF=IR00DFX,POOLTYP=1

opens a short-term pool block.

PF2
specifies the type of pool blocks that are associated with pool file 2 (PF2). The pool block type associated with PF2 is used by a TPFDF macro or function when the POOLTYP=2 parameter is specified with that macro or function. For example, when PF2=SS:
DBOPN REF=IR00DFX,POOLTYP=2

opens a short-term pool block.

PLI=packlimit
specifies the packing limit in percentage, where packlimit is a decimal number from 50-100.

You can use PLI to specify the amount of space to which each block in the subfile should be packed. The value of PLI can be specified between 50% and 100%.

A value of 50% results in half of the space in each block being taken up. A value of 100% results in all of the space being taken up. The values for PLI are:

50-100, for L1 and L2 size blocks

75-100, for L4 size blocks.

Always specify a PLI value greater than the PIN value; otherwise, the file is always below the packing threshold and is packed continuously.

Note:
Using the PLI parameter does not ensure that B+Tree files are packed unless there are no nodes in the B+Tree index. To ensure that B+Tree files are packed, use one of the following:
  • The ZUDFM OAP command
  • A ZFCRU command with the pack option
  • The DBCLS macro with the pack option
  • The dfcls function with the pack option.

SIZECHK
specifies one of the following:

NO
specifies that TPFDF macros and functions that use search keys, search each LREC in the current core block.

YES
specifies that TPFDF macros and functions that use search keys, obtain a core block and copy the current LREC into that core block before searching the LREC in the copied core block. Specifying SIZECHK=YES prevents the TPFDF product from comparing a search key past the end of a data block, which could cause a TPF system error. Comparing a search key past the end of a data block could occur if any of the following are true:
  • The last field in an LREC of the data block has a variable length.
  • Short variable length LRECs are used in the data block.
  • A long variable length search key is specified with a TPFDF macro or function.
  • A search key that is longer than than the length of the searched LREC is specified with a TPFDF macro or function.
Note:
While specifying SIZECHK=YES prevents the unlikely possibility of a system error, it significantly impacts system performance and additional system resources are required.

SSU
specifies the subsystem user.

N
ignores MDBF parameter statements coded in the DBDEF.

C
The file is common; MDBF parameter statements cannot be coded.

U
The file is unique. The U parameter only applies for the TPF system.

To aid in migrating database definitions from an MDBF system to a non-MDBF system, the SSU parameter can be set to N to override any MDBF parameter statements that are coded in the DBDEF.

       DBDEF FILE=zzzzzz,   standard DBDEF
             .........,     additional DBDEF parameters
             SSU=N,         ignore any MDBF parameters
             (MDBF,SSU=(DF,LH,AE),WRS=L4),
             (MDBF,SSU=(RF),WRS=L1,EO#=99),
             (MDBF,SSU=(RT),WRS=L1,EO#=9)

(MDBF,EXCLUDE,SSU=(ssunames))
prevents the specified subsystem users from issuing TPFDF macros and functions, where ssunames is a list of valid SSUs such as AF,LH,BA,AA. For example,
       DBDEF FILE=zzzzzz,   standard DBDEF
             .........,     additional DBDEF parameters
             SSU=U,         file is not common
             (MDBF,SSU=(AA,BA,UA),RBV=#TPFDB03),
             (MDBF,EXCLUDE,SSU=(RF))

Notes:

  1. The MDBF parameter only applies for the TPF system.

  2. If an application program issues a TPFDF macro or functions from an excluded subsystem user, the application will end with a DB0137 system error.

    Therefore, in the previous example, if an application program issues a TPFDF macro when it is in SSU RF, the application will end with a DB0137 system error.

  3. It is important to code the EXCLUDE information so TPFDF utilities run only on the subsystem users that you select. The ZUDFM, ZFCRU, and ZRECP commands will not run on files in a subsystem user that has been excluded.

  4. The specified subsystem user must be defined in the SSUDEF copy member or the DBDEF macro will send an error when it is assembled.

(MDBF,SSU=(ssunames),overrides)
provides unique parameters for the specified subsystem users.

ssunames
specifies a list of valid SSUs such as AF,LH,BA,AA.

overrides
specifies a list of override values for the specified subsystem users (SSUs). The ARS, BOR, EO#, EOR, ILV, INB, NLR, NOC, OP1, OP2, OP3, PF0, PF1, PF2, PIN, PLI, PTN, RBV, RCT, and WRS DBDEF parameters are allowed.
Note:
Because of the different characteristics of algorithms, algorithms can only be overridden (using the RBV override parameter) by specific algorithms that share similar characteristics (are in the same group). For example, #TPFDB09 cannot override #TPFDB01 because the expected algorithm arguments are different. #TPFDB01 expects an alphabetic character while #TPFDB09 expects 8 bytes of data.

Table 36 shows the groups of algorithms that can override each other. The size of the algorithm string (defined by the DBDEF ALG parameter or in the DSECT macro for the file) must be large enough to allow the algorithm to be overridden. For example, if ALG=1 was specified in the detail file, you cannot override the #TPFDB01 algorithm with the #TPFDB02 algorithm in the index file (even though they are in the same group) because the file was defined to allow only a one-byte algorithm. To avoid this problem, define the algorithm to be as large as the maximum length of the algorithm group.


Table 36. Algorithm Groups for Overriding

Group       Maximum Length
1 #TPFDB01
#TPFDB06
#TPFDB02
#TPFDB07
#TPFDB03
#TPFDB08
3
2 #TPFDB0A #TPFDB0B   2
3 #TPFDB04     N/A
4 #TPFDB05     4
5 #TPFDB0C     2
6 #TPFDB0D     N/A
7 #TPFDB09 #TPFDB10   8
8 #TPFDB0F     10

More than one MDBF definition can be defined for a particular file. For example:

       DBDEF FILE=dsname,   standard DBDEF
             .........,     additional DBDEF parameters
             (MDBF,SSU=(AA,BA,UA),RBV=#TPFDB03),
             (MDBF,SSU=(DF,LH,AE),WRS=L4),
             (MDBF,SSU=(RF),WRS=L1,EO#=99),
             (MDBF,SSU=(RT),WRS=L1,EO#=9)

Each SSU takes one of the following values for the file (in order of precedence):

  1. The SSU override values (if they are specified)
  2. The standard DBDEF override values (if they are specified), RBV, WRS and so on.
  3. The &SW00... values specified in the file DSECT.

If you want to code a DBDEF subsystem user override, the name of the subsystem user must be listed in SSUDEF. The SSUDEF copy member is installation specific and lists the subsystem users that can be included in an override.

For each subsystem user, a variable is added to SSUDEF as follows:

  &SSUV(1)  SETC 'RED'     SSU mnemonic name        (MU0NAM in MS0UT)
  &SSUV(2)  SETC 'BLUE'    SSU mnemonic name        (MU0NAM in MS0UT)
  &SSUV(3)  SETC 'OR'      SSU mnemonic name        (MU0NAM in MS0UT)

  ·
  ·
  ·
&SSUV(n) SETC 'GOLD' SSU mnemonic name (MU0NAM in MS0UT)

If the variable to define a particular subsystem user is not set up, the DBDEF macro issues an MNOTE at assembly time.

Notes:

  1. The MDBF parameter only applies for the TPF system.

  2. A maximum of 128 subsystem users can be listed in SSUDEF.

  3. The DBDEF EXCLUDE parameter, which specifies subsystem users that cannot issue TPFDF macros on a particular file, is considered an override. Therefore, these subsystem users must also be listed in SSUDEF.

  4. SSUDEF can be updated to include subsystem users from systems with different MDBF configurations. This allows the DBDEFs to be assembled once against the common SSUDEF and loaded to the two different systems.

SUFFIX=suffix
specifies the suffix that can make a file unique, where suffix is an alphanumeric character or characters. Some P-type file definitions can generate the same symbols for different files or file versions. Use the SUFFIX parameter to add a suffix to the labels to make the labels exclusive to a file version.

If you code the SUFFIX parameter with a DBDEF macro statement, ensure that the DSECT for the P-type file also supports a SUFFIX parameter because the DSECT for the P-type file is invoked internally by the DBDEF macro with the supplied suffix. For example,

        DBDEF FILE=FRED1,FVN=0,
          generates
          FREDID   DS H
          FREDFCH  DS F
              ......
              ......
        DBDEF FILE=FRED1,FVN=1,SUFFIX=A,
          also generates FREDID and FREDFCH, but adds an 'A' to them
          FREDIDA  DS H
          FREDFCHA DS F
              ......

TM
specifies one of the following:

NO
specifies that commit scopes are not used during checkpoint and close processing.

YES
specifies that commit scopes are used during checkpoint and close processing. This option is valuable when many files are to be filed out during checkpoint and close processing (for example, detac mode, extensive B+Tree indexing updates, and requests to pack indexes). See TPFDF Programming Concepts and Reference for more information about commit scopes.
Note:
The application can override the DBDEF TM value by specifying a TM value with the DBCKP or DBCLS macros, or the dfckp or dfcls functions. See TPFDF Programming Concepts and Reference for more information about these macros and functions.

TRS=trailersize
specifies the trailer size at the bottom of each block, where trailersize is a nonnegative number.

Notes:

  1. Standard-format files that do not use algorithm #TPFDB0D have a default TRS value of TRS=36.

  2. Standard-format files that use algorithm #TPFDB0D have a default TRS value of TRS=0.

  3. For customer-format files, the TRS value has no meaning.

UNIQUE
specify YES to ensure that all LRECs added to a file are unique even if the UNIQUE parameter is not specified with a DBADD macro or dfadd function statement. See TPFDF Programming Concepts and Reference for more information about the UNIQUE parameter of the DBADD macro or dfadd function. The default for non-B+Tree data files is UNIQUE=NO. The default for B+Tree data files is UNIQUE=YES.
Note:
UNIQUE=NO is not allowed for B+Tree data files.