bdfd1m10 | Database Administration |
This section describes how to copy and modify one of the sample DSECTs to
create a DSECT to match your own requirements.
Figure 33 shows the beginning macro statements in the sample code for
SAM3SR. The beginning statements, before the Definitions for
TPFDF section, are always required. Do not change or delete them,
except to:
- Change the name of the DSECT macro according to naming conventions
- Modify the &NAM, &DATE, and &VERS symbols as necessary.
Figure 33. Instructions Always Required at the Start of a DSECT Macro Definition
MACRO LIBR NAME = SAM3SR09
&LABEL SAM3SR ®=,&SUFFIX=,&ORG=,&ACPDB=
***********************************************************************
* *
* $TITLE$ SAMPLE DSECT FOR TPFDF W-TYPE BASIC *
* CREATED EX: $CREATE$ DATE: $CDATE$ *
* *
* *
* CHANCE HISTORY DATE DESCRIPTION *
* *
***********************************************************************
GBLB &SAM3SR1 1ST TIME CALLED SWITCH
COPY DBGBL COPY TPFDF GLOBAL DEFINITIONS
COPY DBLCL COPY TPFDF LOCAL DEFINITIONS
&NAM SETC ' ' DOC NAME
&DATE SETC '17DEC85' UPDATE DATE
&VERS SETC '03' VERSION NUMBER
As shown in Figure 34, after the Definitions for TPFDF section in the
SAM3SR sample code, there are a series of instructions that assign values to
several global set symbols. Assign values to each global set symbol
that you need to define. For example:
Figure 34. Instructions to Assign Values to Global Set Symbols
&SW00WID SETC FILE ID
&SW00WRS SETC BLOCK SIZE
&SW00ARS SETC ALTERNATE BLOCK SIZE
&SW02FIL SETC 'SAM3SR' FILE DSECT NAME
&SW00OP1 SETC '00000000' OPT BYTE1
&SW00OP2 SETC '00000110' OPT BYTE2
&SW00OP3 SETC '00000000' OPT BYTE3
&SW00TQK SETC '15' HIGHEST TLREC
The global set symbols are described here in alphabetic order.
Notes:
- Do not assign a value to a particular global set symbol if it is not
required. For example, do not assign values to &SW00BOR,
&SW00EOR, and &SW00RCT for pool files.
- Do not change any values except &SW00WID and &SW00WRS in the
B+Tree index file sample, SAMTSR.
- You can override some of the global set symbol values assigned in a DSECT
macro by using a corresponding parameter in the DBDEF instructions or with a
TPFDF macro or function.
- &SW00ARS: Specify the Block Size of Overflow Blocks
- &SW00ARS is optional. Use it to specify the size of any
overflow blocks that are chained to the prime blocks of the file; for
example:
&SW00ARS SETC 'L4'
Because overflow blocks are always pool blocks, &SW00ARS is the only
definition of the overflow block size and does not have to correspond with any
other value defined elsewhere (see the description for &SW00OP1 bit 5 on
page ***).
If you do not specify &SW00ARS, the TPFDF product assigns a value equal
to the value set for prime blocks, &SW00WRS.
For add current processing, when the number of chains (NOC) is greater than
0, &SW00ARS must be equal to the value defined for &SW00WRS.
For B+Tree index files, &SW00ARS is ignored.
&SW00WRS supplies the block size of the nodes.
- &SW00BOR: Specify the Begin Ordinal
- &SW00BOR is required for fixed or miscellaneous files. Use
&SW00BOR to specify the beginning ordinal for the file.
- &SW00EOR: Specify the End Ordinal
- &SW00EOR is required if this is a fixed or miscellaneous file.
Use &SW00EOR to specify the end ordinal number for the fixed file.
- &SW01EO#: Specify the End Ordinal for TPFDF Recoup
- &SW01EO# specifies the FACE-type end ordinal (for TPFDF
recoup).
- If this is a nonpartitioned, noninterleaved fixed file, set as
follows:
SW01EO# SETC '-1'
- If the file is partitioned, set SW01EO# to -1 or the total number of
prime blocks in all the partitions of the file.
- If the file is interleaved, set SW01EO# to -1 or the total number of
prime blocks in all the interleaves of the file.
- If the file is miscellaneous, specify the symbol (usually defined in
SYSEQ), which 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':
&SW01EO# SETC '#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.
- &SW02FIL: Specify the File Name
- Set &SW002FIL to the DSECT macro name. For example:
&SW002FIL SETC 'dsname'
- &SW00ILV: Specify the Number of Interleaves
- &SW00ILV is optional. If you set this to a nonzero value, it
implies that the file is interleaved. The number you assign defines the
number of interleaves. For example:
&SW00ILV SETC '3'
- &SW00NLR: Specify Number of Fixed-Length LRECs in Each Block
- &SW00NLR is optional. 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
&SW00NLR to the maximum number of LRECs that can fit into each prime block
of the file.
Notes:
- The global set symbol &SW00NLR is not allowed for B+Tree
data files.
- Using the global set symbol &SW00NLR will result in an MNOTE being
issued because the TPFDF product automatically calculates this value, and any
value specified is ignored.
- &SW00NOC: Specify the Number of Blocks to Use in Implementing
Add Current Files
- Only assign a value to &SW00NOC when bit 2 of &SW00OP1 is set
on. Setting bit 2 of &SW00OP1 instructs the TPFDF product to limit
the number of overflow blocks used when adding LRECs to the subfile.
You can set the limit (using &SW00NOC) 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:
&SW00NOC SETA 5
instructs the TPFDF product to use the prime block and 5 overflow
blocks.
If global set symbol &SW00NOC is set to zero, the TPFDF product uses
only the prime block of the subfile.
- Note:
- The &SW00NOC parameter is not allowed for B+Tree data
files.
- &SW00OP1: Specify Processing Options
- &SW00OP1 contains 8 bits that specify TPFDF processing options.
Notes:
- In the TPFDF product, bit 0 is the most significant and bit 7 is the least
significant.
- Bit fields labeled 'reserved' have no meaning in the
system. Do not set them.
- Bit 0: Implement Full Backward Chaining
- Setting bit 0 of &SW00OP1 indicates that you want full backward
chaining.
Backward chaining causes extra I/O overhead each time an overflow block is
inserted or deleted. Backward chaining is required if the DBDEF
DELEMPTY parameter is coded as YES. Backward chaining is recommended if
an application program uses the DBRED macro with the
BACKWARD parameter or the dfred function
with the DFRED_BACKWARD option. If backward chaining is not defined,
and an attempt is made to read the file backwards, the action taken by the
TPFDF product is determined by the &DB013A symbol in the DBLCL
macro.
- Note:
- The value of &SW00OP1 bit 0 has no meaning for files that use add current
processing (&SW00OP1 bit 2 set to 1) with no chains (&SW00NOC equal to
0).
See TPFDF Programming Concepts and Reference for
more information about reading backward. See TPFDF
Installation and Customization for more information about the DBLCL
macro.
- Bit 1: Implement Automatic Chain Correction
- If you set bit 1 of &SW00OP1, the TPFDF product performs automatic
chain correction if it detects a broken chain when you use a macro or function
to access an LREC.
If you have set this indicator and the TPFDF product detects an incorrect
forward chain pointer, it truncates the chain. Data may be lost in
these circumstances, so set bit 1 of &SW00OP1 only for files where missing
data is not critical.
- Bit 2: Implement Add Current Files (Discarding Old Chain Blocks)
- Setting bit 2 of &SW00OP1 indicates that you want to limit the number
of overflow blocks used when adding LRECs.
When this limit is reached, 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 empty first chain block is moved to the last chain
block with an initial next available byte (NAB) setting. You can set
the limit using the &SW00NOC global set symbol from zero to 255.
If you set the &SW00NOC global set symbol to zero, the TPFDF product
restricts processing to the prime block only. This feature is useful if
you want to keep a limited amount of current data; for example, a log of
the last series of macros issued by the program.
Notes:
- Setting bit 2 of &SW00OP1 is not allowed with B+Tree data
files.
- Do not set bit 2 of &SW00OP1 for a file that has index LRECs in a
basic indexing structure.
- Bit 3: Implement Pushdown Chaining
- If you set bit 3 of &SW00OP1, this specifies pushdown
chaining. This works as follows:
- When an application program uses the DBADD macro
to add a new LREC, the TPFDF product stores the LREC starting at the next
available byte in the prime block if there is room.
- If the prime block does not have enough room left for the new LREC, the
TPFDF product gets a new overflow block. It copies the contents of the
prime block into the new overflow block, initializes the prime block, and puts
the next LREC into the start of the prime block which is now empty.
Notes:
- If you use this feature, the file cannot be UP or DOWN organized.
- Setting bit 3 of &SW00OP1 is not allowed with B+Tree data
files.
- Bit 4: Checkpoint after Each DBUKY Macro
- If you set bit 4 of &SW00OP1, the TPFDF product performs a checkpoint
automatically whenever the application program uses the DBUKY macro. A checkpoint after each DBUKY macro call is often useful because application
programs typically call DBUKY as the first step of a
sequence of related updates to a file.
- Bit 5: Specify Variable Sizes of Overflow Block
- If bit 5 of &SW00OP1 is not set, the
TPFDF product uses the value you set in parameter &SW00ARS to determine
the size of all overflow blocks.
If you set bit 5 of &SW00OP1, the TPFDF product uses the size you have
specified for prime blocks (&SW00WRS) for the first overflow block and the
size you have specified for overflow blocks (&SW00ARS) for all other
overflow blocks.
You must have specified the size of overflow blocks (&SW00ARS) to be
greater than the size of prime blocks (&SW00WRS) for this bit setting to
be effective.
- Bit 6: Check Whether Blocks Should Be Packed
- If you set bit 6 of &SW00OP1, the TPFDF product always checks for the
packing criteria specified by &SW00PIN in every block that has been
modified, regardless of whether the DBDEL macro or
dfdel function has been used to delete
LRECs. For example, the DBREP macro or dfrep function may have been used to replace
an LREC with a smaller LREC.
Notes:
- This bit setting creates processing overhead.
- Setting bit 6 of &SW00OP1 is not allowed with B+Tree data
files.
- Bit 7: Maintain a File Sequence Update Counter
- If you set bit 7 of &SW00OP1, the TPFDF product maintain a file
sequence update counter in the prime block of the file.
Use this option with the DBRST command or dfrst function and sequence
parameters.
- &SW00OP2: Specify Processing Options
- &SW00OP2 contains 8 bits that specify TPFDF processing options.
Notes:
- In the TPFDF product, bit 0 is the most significant and bit 7 is the least
significant.
- Bit fields labeled 'reserved' have no meaning in the
system. Do not set them.
- Bit 0: Validate Next Available Byte (NAB)
- When this bit is on, the TPFDF product validates the next available byte
(NAB) every time it files a block.
- Note:
- Using this feature creates processing overhead.
- Bit 1: New Pool Option When a File Is Packed
- By default, when the TPFDF product packs a file (when you close a file or
use the ZUDFM OAP command, or a ZFCRU command with
the pack function), it packs the file into the existing blocks, releasing any
overflow blocks that are no longer required.
If you set bit 1 of &SW00OP2, new overflow blocks are used and old
overflow blocks are released when a pack operation is completed
successfully.
- Bit 2: New Pool Option When a File Is Restored
- By default, when the TPFDF product restores a file, it restores the file
into existing blocks releasing any overflow blocks that are no longer
required.
If you set bit 2 of &SW00OP2, new overflow blocks are used and old
overflow blocks are released when a restore operation completes
successfully.
- Note:
- A B+Tree index is always rebuilt using new pool records regardless
of the bit setting.
- Bit 3: New Pool Option When a File Is Loaded from Tape
- By default, when the TPFDF product loads a file from tape (or for ALCS
users, from sequential file), it loads the file into the existing blocks
releasing any overflow blocks that are no longer required.
If you set bit 3 of &SW00OP2, new overflow blocks are used and old
overflow blocks are released when a tape load operation completes
successfully.
- Bit 4: Retrieve Prime Blocks
- Bit 4 should normally be set to zero. When bit 4 is set to zero and
a hold is specified on a TPFDF call (for example, with the HOLD parameter on
the DBOPN macro or the DFRED_INDEX_HOLD value on the
dfred function), the TPFDF product issues
the FIWHC macro to find and hold the prime block. Because open file
processing does not perform an I/O, the FIWHC macro is processed on the
subsequent TPFDF call that accesses the subfile.
When bit 4 is set to 1, the TPFDF product issues the FINWC macro to find
the prime block regardless of whether a hold is specified or not, and the
prime block is not held.
- Note:
- Setting bit 4 to 1 allows two ECBs to update a file at the same time.
- Bit 5: Retrieve Overflow Blocks
- Bit 5 should normally be set to 1. When bit 5 is set to zero and a
hold is specified on a TPFDF call (for example, with the HOLD parameter on the
DBOPN macro or DFRED_INDEX_HOLD value on the dfred function), the TPFDF product issues the
FIWHC macro to find and hold the overflow blocks. Because open file
processing does not perform an I/O, the FIWHC macro is processed on the
subsequent TPFDF call that accesses the subfile.
When bit 5 is set to 1, the TPFDF product issues the FINWC macro to find
the overflow blocks regardless of whether a hold is specified or not, and the
overflow blocks are not held.
- Bit 6: Issue an OPR-DB010C System Error if the File is Modified
without HOLD
- Setting bit 6 to 1 causes the TPFDF product to issue an OPR-DB010C dump
and return to the application program when a file that was opened without the
HOLD parameter is modified and then closed. This prevents two ECBs from
updating a file at the same time.
- Note:
- If a file is opened with the HOLD parameter and &SW00OP2 bit 4 is set to
1, setting bit 6 to 1 will not prevent two ECBs from updating the file at the
same time.
- Bit 7: Reserved
- This bit is reserved for IBM use.
- &SW00OP3: Specify Processing Options
- &SW00OP3 contains 8 bits that specify TPFDF processing options.
Notes:
- In the TPFDF product, bit 0 is the most significant and bit 7 is the least
significant.
- Bit fields labeled 'reserved' have no meaning in the
system. Do not set them.
- Bit 0: LRECs Are of Extended Type
- If you set bit 0 of &SW00OP3, this indicates to the TPFDF product that
all LRECs in the file are extended LRECs.
- Bit 1: Reserved
- This bit is reserved for IBM use.
- Bit 2: Reserved
- This bit is reserved for IBM use.
- Bit 3: File Is an Indexed Fixed File
- You must set bit 3 of &SW00OP3 if the file you are specifying is a
fixed file and it has one or more index files referencing it. See Simple Indexing.
- Bit 4: Checkpoint When an Index LREC Is Added or Deleted
- When the TPFDF product updates index LRECs, the LRECs are updated in main
storage only. The TPFDF product only writes the index file to disk when
the detail file is closed.
If you set bit 4 of &SW00OP3, the TPFDF product performs a checkpoint
automatically whenever an index LREC is added or deleted from an index
file.
- Bit 5: Implement B+Tree Indexing
- Set bit 5 of &SW00OP3 for files using B+Tree
indexing. See B+Tree Indexing.
- Note:
- Before you can implement B+Tree indexing in an ALCS environment,
enable C language support. See TPFDF Installation
and Customization for more information.
- Bit 6: Default DETAC Mode
- When this bit is set, each time you open a subfile, the TPFDF product
opens it in DETAC mode (as if you had used the DETAC parameter with the DBOPN macro or dfopn function).
- Bit 7: Unique Key Feature
- Set this bit if you want to allow application programs to generate unique
keys using the DBUKY macro or dfuky function.
- &SW00PIN: Specify the Packing Threshold in a Block
- When you close a subfile after deleting LRECs, the TPFDF product packs the
subfile if the number of bytes used for LRECs in any block falls below the
percentage (as indicated by &SW00PIN) of total bytes available for LRECs
and the optional block trailer. If any block falls below the packing
threshold, the subfile is packed to the level defined by the PLI value in the
DBDEF. Always specify a PLI value greater than the &SW00PIN
value; otherwise, the file is always below the packing threshold and is
packed continuously.
For example:
&SW00PIN SETC '60'
For non-B+Tree files, the default setting is 75% if
either &SW00WRS or &SW00ARS is set to L4. Otherwise the default
is 50%. If the PLI parameter is not specified in the DBDEF, the
blocks are packed to 100%.
- Note:
- B+Tree files have the following considerations:
- For B+Tree index files, the &SW00PIN value (defined in the
DBDEF statement of the data file) applies to node blocks. If a node
block drops below the specified percentage, the node block is balanced or
combined with an adjacent node. The default value, which is the maximum
for a B+Tree index file, is 50%.
- For B+Tree index files, the &SW00PIN value should be set to
0 in the DSECT or by using the PIN parameter on the DBDEF macro so node blocks
are not accidentally packed by a utility.
- B+Tree data files are only packed using a utility or when the
file is closed, there are no nodes in the B+Tree structure, and
there are overflow blocks in the data file.
- &SW00PTN: Specify the Number of Partitions
- &SW00PTN is required for partitioned files. It specifies the
number of partitions. For example:
&SW00PTN SETC '4'
- &SW00RBV: Specify the
Addressing Algorithm
- &SW00RBV defines the algorithm you want to use with this file.
If the file is a detail pool file, set it to '#TPFDBFF'
as follows:
&SW00RBV SETC '#TPFDBFF'
- Direct Translation Algorithms
- There are eight TPFDF algorithms that distribute LRECs to subfiles using a
direct relation between the algorithm argument and the subfile (ordinal)
number.
- Using Your Own Distribution Method
- If you want to allocate LRECs over subfiles yourself, there are two TPFDF
algorithms that let you use your own distribution method.
- Hashing Algorithms
- Hashing algorithms distribute LRECs across any number of subfiles in a
file. To get an even distribution:
- Use a prime number for the number of subfiles.
- Use a wide a range of numbers or characters in the algorithm
argument.
- Algorithm for Files Requiring No Overflow
- The TPFDF product provides one algorithm, #TPFDB0D, which distributes
LRECs across prime blocks only. Use this algorithm if you want to avoid
chaining.
Because the TPFDF product does not have to search through a chain of
overflow blocks, this algorithm provides one of the fastest ways of retrieving
data, but only works with fixed-length LRECs. You access the data in
this type of file using the LRECNBR parameter.
- Single-Subfile Algorithm
- The TPFDF product provides the #TPFDB04 algorithm for files that have a
single subfile.
- Algorithm for Basic and B+Tree Index Support
- The TPFDF product provides the #TPFDBFF algorithm for basic and
B+Tree index support.
- Create Your Own Algorithm
- To create your own (user-defined) algorithm, do the following:
- Specify an equate value in the range 256-511 in the ACPDBE macro
- Specify the user-defined algorithm in user exit UWBD
- Set the &SW00RBV symbol.
- Note:
- See Table 34 for a list of the previously mentioned algorithms.
Table 34. Algorithms
Direct Translation
|
#TPFDB01
| Distributes LRECs across subfiles according to the first alphabetic
character in the algorithm argument. It requires 26 subfiles; one
for each letter of the alphabet.
|
#TPFDB02
| Distributes LRECs among subfiles according to the first 2 alphabetic
characters in the algorithm argument. It requires 676 subfiles, one for
each combination of 2 alphabetic characters:
AA, AB, AC,...ML, MM, MN,...ZX, ZY, ZZ
|
#TPFDB03
| Distributes LRECs across subfiles according to the first 3 alphabetic
characters in the algorithm argument. It requires 17 576
subfiles, one for each combination of 3 alphabetic characters:
AAA, AAB, AAC,...MOL, MOM, MON,...ZZX, ZZY, ZZZ
|
#TPFDB06
| Distributes LRECs across subfiles according to the first alphabetic or
numeric character in the algorithm argument. It requires 36 subfiles,
one for each letter of the alphabet and one for each numeric character
(0-9).
|
#TPFDB07
| Distributes LRECs across subfiles according to the first 2 alphabetic or
numeric characters in the algorithm argument. It requires 1296
subfiles, one for each combination of 2 alphabetic or numeric
characters:
AA,...A0,...A9,...ZA,...Z0,...Z9,...12,...5M,...99
|
#TPFDB08
| Distributes LRECs across subfiles according to the first 3 alphabetic or
numeric characters in the algorithm argument. It requires
46 656 subfiles, one for each combination of 3 alphabetic or numeric
characters:
AAA,...AAZ,...AA0,...AA9,...A00,...A09,...A99,...M56,...Z90,...123,...4T6,...999
|
#TPFDB0A
| Distributes LRECs among subfiles according to the first alphabetic,
numeric, or special character in the algorithm argument. It requires 43
subfiles, one for each letter of the alphabet, one for each numeric character,
and one for each of the following special characters:
. (X'4B')
$ (X'5B')
* (X'5C')
- (X'60')
/ (X'61')
# (X'7B')
@ (X'7C').
(The characters represented by these hexadecimal values can be different
in some countries, so the TPFDF product uses the hexadecimal value not the
character value (for example X'5B' not $).
|
#TPFDB0B
| Distributes LRECs among subfiles according to the first 2 alphabetic,
numeric, or special characters in the algorithm argument. The special
characters are as listed above for #TPFDB0A. It requires 1849 subfiles,
one for each possible combination of 2 alphabetic, numeric, or special
characters:
..,.$,...AA,...BB,...B5,...B9,...#A,....M,...*Z,...$3,.../6,...99
|
Your Own Distribution Method
|
#TPFDB05
| Use #TPFDB05 if the ordinal number that you specify will be held in a
4-byte field.
|
#TPFDB0C
| Use #TPFDB0C if the ordinal number that you specify will be held in a
2-byte field.
- Note:
- These two algorithms use absolute ordinal values, not ordinals relative to
&SW00BOR.
|
Hashing
|
#TPFDB09
| This hashing algorithm uses the first 8 bytes of data in the algorithm
argument to determine in which subfile the LREC should be placed.
The algorithm argument can contain any hexadecimal values. The TPFDF
product divides the first half of the 8-byte string by the number of subfiles,
then divides the second half by the number of subfiles. The two
remainders are added together and then divided again by the number of
subfiles. The remainder is the subfile to be retrieved. This
produces an even distribution of LRECs among the subfiles.
|
#TPFDB0F
| This algorithm is for partitioned files. It uses a 10-byte
algorithm argument. The TPFDF product processes the first 8 bytes in
the algorithm argument in the same way as #TPFDB09. It uses the next 2
bytes in the algorithm argument to distribute LRECs between partitions on a
similar basis.
|
#TPFDB10
| This hashing algorithm uses the first 8 bytes of data in the algorithm
argument to determine in which subfile the LREC should be placed.
The calculated ordinal is the remainder of an 8-byte algorithm argument
divided by a 4-byte number of subfiles. The algorithm argument can
contain any hexadecimal value. The result is achieved as follows:
The TPFDF product divides the first 4 bytes of the 8-byte string by the number
of subfiles. The second 4 bytes of the string are appended to the end
of the remainder of the first division, and the entire resulting number is
divided by 4 times the number of subfiles. The remainder of this
division is then divided by the number of subfiles. The remainder is
the subfile to be retrieved. This produces an even distribution of
LRECs among the subfiles.
|
Files Requiring No Overflow
|
#TPFDB0D
| #TPFDB0D is suitable for applications that process data
sequentially by number or in circumstances where no pool storage is
available. #TPFDB0D is not allowed for B+Tree data
files. #TPFDB0D uses 4 bytes of data from the LREC number to determine
where the LREC should be stored. It divides the 4-byte value by the
number of LRECs in each block. The result is the relative ordinal
number of the subfile in which the LREC is placed. The remainder gives
the LREC number in the block. An example of such a file is shown in the
following:
You do not need to specify how many LRECs are in each block when you use
this algorithm. The TPFDF product calculates the number of LRECs in
each block by dividing the length of the fixed-length LRECs into the block
size.
|
Single Subfile
|
#TPFDB04
| Use this algorithm with files consisting of a single fixed
subfile. #TPFDB04 does not perform any calculations to obtain a block
ordinal number because there is only 1 prime block.
|
Basic and B+Tree Index Support
|
#TPFDBFF
| For basic indexing, this algorithm is used to access detail files.
For B+Tree indexing, node files are defined using this
algorithm.
|
- &SW00RCT: Specify the Record Type for Fixed Files
- &SW00RCT is required for fixed or miscellaneous files. Use
&SW00RCT to specify the file's record type.
&SW00RCT SETC '#IDFCS'
- &SW00REF: Specify the Work Area Reference Name
- &SW00REF is valid for T-type files only. Use it to specify the
reference name of the W-type file that contains the T-type file. The
default is GW01SR.
&SW00REF SETC 'dsname'
Where dsname is the W-type file reference name.
- &SW00SKE: Specify Block Index Support
- To implement block index support, set &SW00SKE equal to 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
zzzzKEY field (the LREC ID). For example, if the last field in
the key is zzzzlabel, you would specify:
&SW00SKE SETC 'zzzzlabel-zzzzKEY+L''zzzzlabel'
Notes:
- Make &SW00SKE 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 &SW00SKE 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).
- &SW00SKE is not allowed for B+Tree data files.
- To set up a block indexed index file, set the length of &SW00SKE from
the LREC ID to the last key field; for example:
&SW00SKE SETC 'GR25E80-GR25KEY' EXTRACT FOR BLOCK INDEX
GR25REC&CG1 DS 0CL1
GR25SIZ&CG1 DS H
GR25KEY&CG1 DS XL1
GR25FAD&CG1 DS CL4
GR25RCC&CG1 DS XL1
GR25A80&CG1 DS 0XL6
GR25FID&CG1 DS XL2
GR25FVN&CG1 DS XL1
GR25IND&CG1 DS XL1
GR25SSU&CG1 DS XL2
GR25E80&CG1 EQU *
- &SW00TQK: Specify the Highest Technical LREC (TLREC) ID that the
TPFDF Product Can Use
- You can use &SW00TQK to set the value of the highest technical LREC ID
that the TPFDF product can use for this file. For block indexed files,
it must be set to a value greater than 2. For B+Tree data
files, it must be set to a value greater than 4. For B+Tree
index files, it must be set to a value less than 3.
&SW00TQK SETC '15'
- 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.
- &SW00TYP: Specify the File
Type
- &SW00TYP is optional. If you omit it, the TPFDF product takes
the file type from the second character of the DSECT macro name. These
characters are listed in File Names.
You can set &SW00TYP equal to 'R', 'W',
'T', or 'P'. B+Tree data files must be
R-type files, whether specified or taken from the second character of the
DSECT macro name.
If you are defining a DSECT macro to access a P-type file, set &SW00TYP
equal to 'P', as follows:
&SW00TYP SETC 'P'
- &SW00WID: Specify the File ID
- &SW00WID is always required. It specifies the file
ID, which is a 2-byte value in the standard header of every
block. Use a unique file ID for every DSECT macro. The range of
valid file IDs is from #TPFDBID to X'FFFF' (where the value of
#TPFDBID is defined in ACPDBE). For example:
&SW00WID SETC X'C000'
See TPFDF Installation and Customization for more
information about #TPFDBID values.
- &SW00WRS: Specify the Size of Prime Blocks
- &SW00WRS is required. Set it to the size of the prime blocks
used in the file. For example, to use a 1055-byte (L2) prime block, set
&SW00WRS as follows:
&SW00WRS SETC 'L2'
The Description of SAM3SR section of the SAM3SR sample DSECT
allows you to document your DSECT macro. Do not change the instructions
that immediately follow the Description of SAM3SR section except to
rename the DSECT to your new DSECT name. See Figure 35.
Figure 35. Instructions Always Required after Setting the Global Symbols in a DSECT Macro
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* *
* DESCRIPTION OF SAM3SR *
* *
* *
* A standard prolog follows that contains the following headings *
* which allow you to document information about the DSECT *
* *
* *
* 1. DATA AREA NAME *
* 2. MEMBER NAME *
* 3. INVOCATION *
* 4. GENERAL CONTENTS AND USE *
* 5. STORAGE FACTORS *
* 6. DATA CONTROL *
* 7. IMPLEMENTATION REQUIREMENTS *
* 8. REFERENCES *
* 9. COMMENTS *
* *
* *
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
EJECT
AIF ('&SW00WRS' EQ '').CHECKID
#SAM3SRS EQU &SW00WRS BLOCK SIZE
.CHECKID AIF ('&SW00WID' EQ '').NOT1ST
#SAM3SRI EQU C'&SW00WID' FILE ID
.NOT1ST ANOP
- Note:
- The #SAM3SRI equate in Figure 35 is set for a file ID that is in character format. If
the file ID is in hexadecimal format, change the equate to:
#SAM3SRI EQU X'&SW00WID' FILE ID
Do not change the instructions that define the block header unless you want
to put extra information in the extended header in each prime block (see Optimizing the Database Design). You can do this after the standard TPFDF header
field.
Figure 36 shows a block header for a DSECT that uses fixed-length or
variable-length LRECs.
Figure 36. Instructions to Define the File Header in a DSECT Macro
***********************************************************************
* STANDARD TPFDF HEADER *
***********************************************************************
SAM3HDR&CG1 DS CL16 STANDARD FILE HEADER
DS CL10 STANDARD TPFDF HEADER
SAM3VAR&CG1 EQU * START OF VARIABLE USER-AREA
SAM3HDL&CG1 EQU SAM3VAR&CG1-SAM3HDR&CG1 HEADER-LENGTH UP TO SAM3VAR
Figure 37 shows an example of the instructions needed to define the
logical record (LREC) size and the LREC ID fields for a file.
Figure 37. Instructions to Define the LREC Size and LREC ID Fields
ORG SAM3HDR&CG1
SAM3REC&CG1 DS 0CL1 1ST RECORD START (1=VARIABLE,ELSE SIZE)
SAM3SIZ&CG1 DS H SIZE OF LOGICAL RECORD
SAM3KEY&CG1 DS X LOGICAL RECORD IDENTIFIER
AIF ('&SAM3SR1' EQ '1').KEYEQ GO IF NOT FIRST ISSUE
The instructions are explained as follows:
- SAM3REC&CG1
- indicates the size of the LRECs for a file using fixed-length LRECs or it
indicates that the file is is using variable-length LRECs.
- SAM3SIZ&CG1
- creates a 2-byte field that is used in each LREC to hold the actual length
of the LREC (used for variable-length LRECs only). Make sure that you
include the length of the SIZ field (2 bytes) and the
KEY field (1 byte) when calculating the total length of the
LREC.
- SAM3KEY&CG1
- creates a 1-byte field that contains the LREC ID. Its meaning and
use are the same for fixed-length and variable-length LRECs.
- Note:
- Because the SAM3REC definition occurs only once in a DSECT, you
can define fixed-length or variable-length LRECs in a file, but not
both.
Every LREC contains an LREC ID, or primary key, that identifies it in the
file. More than one LREC in a file can have the same ID. (It is
possible for all LRECs in a file to have the same ID.) Different LREC
IDs are used in a file to differentiate between different types of
LREC.
Figure 38 shows how you can define two LREC IDs, X'80' and
X'90'. The two equates are used later in the DSECT to define
the two individual LREC IDs.
Figure 38. Defining Two Different LREC Types in a DSECT
***********************************************************************
* EQUATE OF LOGICAL RECORD KEYS (KEY AND LENGTH)
***********************************************************************
#SAM3K80 EQU X'80' LOGICAL RECORD KEY X'80'
#SAM3K90 EQU X'90' LOGICAL RECORD KEY X'90'
- 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.
Define user fields by using DSECT instructions similar to those shown in Figure 39. Figure 39 defines a member number field
that contains 10 characters of data and a surname field that
contains 20 characters of data.
Figure 39. Defining User Fields in a DSECT
SAM3ORG&CG1 EQU * START OF LOGICAL RECORD DESCRIPTION *****
***********************************************************************
* DESCRIPTION OF F I R S T LOGICAL RECORD TYPE *
***********************************************************************
SAM3A80&CG1 DS 0CL30 KEYAREA
SAM3NUM&CG1 DS CL10 member number
SAM3NAM&CG1 DS CL20 surname
SAM3E80&CG1 EQU * END OF LOGICAL RECORD WITH KEY = X'80'
- Note:
- For index files, the TPFDF product determines how much data to move into an
index LREC when a DBIDX macro or dfidx function is issued by calculating the
number of bytes between the beginning of the key area and the end of the key
area. In Figure 39, this would be 30 bytes (SAM3E80 minus SAM3A80).
The algorithm area size must be defined for each detail file and any
intermediate-index files, but is not required for top-level index files or
files that are not part of a basic indexing structure. The size of the
algorithm string is normally calculated using information in the DSECT of the
detail or intermediate-index file. The reserved labels
dsnd@nBEG&CG1 and dsnd@nEND&CG1 are used to
indicate the beginning and end of the algorithm string.
Notes:
- dsnd indicates the first 4 characters of the DSECT macro name
of a detail or intermediate-index file.
- n identifies the path number to which the definition
applies.
Figure 40 shows these labels used in the SAM5SR sample DSECT.
Figure 40. DSECT Code to Define the Algorithm String Size
***********************************************************************
* ALGORITHM DESCRIPTION *
***********************************************************************
ORG SAM5REC&CG1
SAM5@0BEG&CG1 EQU * PATH 0 DESCRIPTION
SAM5@0...&CG1 DS
SAM5@0...&CG1 DS
SAM5@0...&CG1 DS
SAM5@0END&CG1 EQU *
Notes:
- @0 indicates that this applies to path zero (0).
- The labels between the BEG and the END labels can be used to define parts
of the algorithm string.
See Figure 41 for the instructions required at the end of each sample
DSECT macro. Do not change them.
Figure 41. Instructions Always Required at the End of a DSECT Macro
.*
.**********************************************************************
AIF (&BG1).MACEXIT GO IF INTERNAL USAGE
&SYSECT CSECT
AIF ('®' EQ '').MACEXIT GO IF REG= NOT SPECIFIED
.GEUSING ANOP GENERATE USING
USING &DSN,®
.MACEXIT ANOP
SPACE 1
MEND