bdfd1m13 | Database Administration |
This section describes DBDEF macro statements according to the following
functions:
- Global DSECT overrides
- Default keys
- Indexing
- Data extraction
- Exits from TPFDF recoup to user code
- B+Tree files
- Miscellaneous.
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.
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:
- If this is a nonpartitioned fixed file, set endord to
-1 (minus 1). The TPFDF product resolves the correct
value when the file is opened.
- If this is a miscellaneous file, endord is a symbol (usually
defined in SYSEQ), that defines where the miscellaneous file ends in the
miscellaneous fixed file type. By convention, this symbol is
'#', followed by the DSECT macro name, followed by
'L':
EOR=#dsnameL
- If this is a partitioned file, specify the number of prime blocks in each
partition, not the total number of prime blocks in all partitions. For
example, if there are 10 ordinals in each partition, specify:
EOR=10
- 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:
- If this is a nonpartitioned, noninterleaved, fixed file, set
faceendord equal to -1.
- If the file is partitioned, set faceendord to -1 or the
total number of prime blocks in all the partitions of the file.
- If the file is interleaved, set faceendord to -1 or the
total number of prime blocks in all the interleaves of the file.
- If the file is miscellaneous, set faceendord equal to the symbol
(usually defined in SYSEQ) that defines where the miscellaneous file ends in
the miscellaneous fixed file type. By convention, this symbol is
'#', followed by the DSECT macro name, followed by
'L':
EO#=#dsnameL
Notes:
- If &SW01EO# is not specified in the DSECT or the DBDEF EO# parameter
override, -1 is used for fixed file types.
- 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.
- 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.
- 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:
- The NLR parameter is not allowed for B+Tree data files.
- 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:
- #TPFDB01
- #TPFDB02
- #TPFDB03
- #TPFDB04
- #TPFDB05
- #TPFDB06
- #TPFDB07
- #TPFDB08
- #TPFDB09
- #TPFDB10
- #TPFDB0A
- #TPFDB0B
- #TPFDB0C.
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:
- Make SKE large enough to hold any field used as a key field by any
application program that might use this file.
- 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.
- Do not use block index support with add current files (these are indicated
by bit 2 of &SW00OP1 being set).
- 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 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:
- P-type files
- T-type files
- Add current files
- Index files (including B+Tree index files)
- Pushdown chaining files.
- PKY=primarykey
- specifies the characteristics of the primary key (LREC ID) of the LREC,
where primarykey is one of the following:
- An equate that represents the primary key (for example,
PKY=#GR00K80)
- An explicit term that represents the primary key (for example,
X'80').
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:
- An equate that represents the 2-byte data identifier (for example,
FLD=#GR00D1000)
- An explicit term that represents the 2-byte data identifier (for example,
X'1000').
Notes:
- The dataid value must resolve to a value from
X'0000'-X'FFFF'.
- 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)
The following must be coded before index parameters are used in the DBDEF
macro:
- The DSECT macro to define the index file, which includes:
- Definitions of the fields in the index LRECs
- Global symbols that specify how the index file is contained in physical
records, including &SW00RBV to specify the algorithm used to access the
top level of the index file.
- The DSECT macro to define the indexed file, which includes:
- &SW00RBV set to '#TPFDBFF' for an indexed file
- Bit 3 of &SW00OP3 set to 1 for an indexed fixed file or
0 for an indexed pool file
- The statements that define the fields in the ALG string associated with
each indexing path (see Figure 40).
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:
- 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=,...
- 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.
- 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:
- An equate that represents the primary key (for example,
ITK=#GR00K80)
- An explicit term that represents the primary key (for example,
X'80').
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:
- 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.
- 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:
- All the ID2= references (specified in items)
- 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:
- All the ID2= references (specified in items)
- 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:
- For each top-level index file in the structure, specify
RCIDID=rcitag.
- For each file that contains a reference to a detail file, specify,
ID2=(RCI),...).
- SUB
- indicates that there are subitems in items.
Notes:
- Subitems can be defined only in customer-format files. See Parameters for TPFDF Recoup and TPFDF CRUISE Processing for Customer-Format Files.
- SUB is not allowed with the ID3 parameter.
- SUB is not allowed if CBV=5 is specified or used as a default.
- Subitems must have a fixed size and start at a fixed location in the
item.
- Each subitem contains a reference.
- Specify the number of subitems using the CNT parameter or specify the
location of a count field using the CPT parameter.
- 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:
- A 2-character decimal record ID of the detail or intermediate-index file
(for example, RID=10).
- A 4-character hexadecimal record ID of the detail or intermediate-index
file (for example, RID=FDFD).
- A 5 or 6-character DSECT name of the detail or intermediate-index file
(for example, RID=SAM5SR).
- The relative location of a field in the index file that contains the
record ID of the detail or intermediate-index file (for example,
RID=SAM4LAB-SAM4REC).
- 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:
- An equate that represents the 2-byte data identifier (for example,
DIT=#GR00D1000)
- An explicit term that represents the 2-byte data identifier (for example,
X'1000').
Notes:
- The dataid value must resolve to a value from
X'0000'-X'FFFF'.
- 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:
- INB can only be specified for P-type files.
- 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:
- PFC or CPF is necessary if FCH is present.
- PFC is not allowed with CPF.
- PFC=-1 is used for a no forward chain file.
- 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:
- For each top-level index file in the structure, specify
RCIDID=rcitag.
- For each file that contains a reference to a detail file, specify,
(ID2=(RCI),RID=....)).
- 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.
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:
- 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)
- 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:
- An equate that represents the primary key (for example,
IKY=#GR00K80)
- An explicit term that represents the primary key (for example,
X'80').
Notes:
- 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:
- The ALG parameter in the DBDEF macro does not have the same meaning as the
ALG parameter in other TPFDF macros and functions.
- The ALG parameter must be used in the DBDEF for any file that requires the
area to be specified.
- 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:
- An equate that represents the 2-byte data identifier (for example,
DID=#GR00D1000)
- An explicit term that represents the 2-byte data identifier (for example,
X'1000').
Notes:
- The dataid value must resolve to a value from
X'0000'-X'FFFF'.
- 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.
- 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.
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:
- All items must be the same size.
- 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
The TPFDF product has recoup and CRUISE user exits that allow you to run
user-defined code:
- If a forward index pointer causes an error (CDE)
- Before a forward index pointer is retrieved (CDO)
- To override the CNT, PNB, NAB, or PIT value at run time (CDR)
- Before a block is referenced (CEB)
- After a block is referenced (CEE)
- After a block is retrieved (COA)
- If there is an error when a block is retrieved (COE)
- To determine the location of the forward chain field (CPF).
- 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:
- Is coded in a corresponding DBDEF CDLBL=label
statement.
- Stores the location of the referenced file in register 15 (R15) before
returning.
- Uses the BR R7 statement to return to TPFDF recoup.
Notes:
- BASE and BASECOD are not allowed together.
- BASECOD requires STP=1.
- Ensure that register R15 contains the file address or core address of the
user code.
- 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:
- The CDE parameter is not valid for ALCS.
- The address of the block that contains the forward index pointer is
contained in level D0 (field name EBCFA0) of the ECB.
- The address of the block that caused the retrieval error (forward index
pointer) is in level D1 (field name EBCFA1) of the ECB.
- EBCFA1 might be changed for a second attempt of retrieval.
- The user code must include one of the following statements to return to
TPFDF recoup:
- CDO
- specifies code to be used before the forward index pointer is
retrieved.
Notes about the user code:
- The address of the block that contains the forward index pointer is in
level D0 (field name EBCFA0) of the ECB.
- Register 5 (R5) is pointing to the LREC where the forward index pointer is
located.
- 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:
- The CDR parameter is not valid for ALCS.
- The address of the block that contains the reference is in level D0 (field
name EBCCR0) of the ECB.
- EBCCR0 is the main storage reference word of level D0.
- CE1CC0 is the 2-byte area which contains the block size of D0.
- EBCFA0 is the file address of D0.
- 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:
- The COA parameter is not valid for ALCS.
- 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.
- Each block contains a displacement field (dsniDIS), which
contains the position of the first item in the block.
- User code is required to override the PIT value.
- 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:
- The CDE parameter is not valid for ALCS.
- The address of the block about to be processed is in level D0 (field name
EBCFA0) of the ECB.
- 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:
- The address of the block to be processed is in level D0 (field name
EBCFA0) of the ECB.
- 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:
- The COA parameter is not valid for ALCS.
- The address of the block that has just been retrieved is in level D0
(field name EBCCR0) of the ECB.
- 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:
- The address of the block retrieved is in level D0 (field name EBCFA0) of
the ECB.
- 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:
- CPF is not allowed with PFC.
- PFC or CPF is necessary if FCH is present.
- The user code should write the location of the forward chain field into
EBW030.
- The address of the block that contains the reference is in level D0 (field
name EBCCR0) of the ECB.
- 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:
- CDLBL must be the last DBDEF macro statement coded in a segment or the
DBDEF table will be corrupted.
- If a work area is required, the following sequence is recommended:
GETCC Dx,Lx
DBDEF CDLBL=RAP
- 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)
- 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.
- All TPFDF recoup user code is entered in 31-bit mode.
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.
Notes:
- 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:
- 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.
- 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.
- If you enter the DBREP macro with KEYCHECK=YES,
any keys in effect from previous TPFDF macros become unpredictable.
- 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:
- 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.
- 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:
- The MDBF parameter only applies for the TPF system.
- 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.
- 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.
- 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):
- The SSU override values (if they are specified)
- The standard DBDEF override values (if they are specified), RBV, WRS and
so on.
- 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:
- The MDBF parameter only applies for the TPF system.
- A maximum of 128 subsystem users can be listed in SSUDEF.
- 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.
- 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:
- Standard-format files that do not use algorithm #TPFDB0D have a default
TRS value of TRS=36.
- Standard-format files that use algorithm #TPFDB0D have a default TRS value
of TRS=0.
- 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.