 |
Recoup - Warp Factor 9 - Engaged
Anita Cheung, Steven E. Roach, and Daniel Jacobs, IBM TPF Development, and John Thayer, IBM TPF ID
Core Team
Faster than a speeding schedule change! More powerful than a database reorganization! Able to clean large
pools in a single run! Look! Up in the sky! It's a
bird! It's a plane! No, it's Recoup 2000! Disguised as mild-mannered
APAR PJ27469 on TPF PUT 13, Integrated Online Pool Maintenance and Recoup Support fights a never-ending
battle against broken chains, erroneously available and lost addresses, and processing the offline
way.
Yes, it is finally here. The number one requirement from the TPF Users Group (TPFUG) Requirements List. The
IBM version of the TPFUG Task Force Pool Rewrite Project. First, a big "Thank You" to the members of the Task
Force for their contribution and effort to provide this rich functional enhancement to pool support for the TPF user
community. We especially thank representatives of Galileo and Sabre for their continued support and assistance to the
IBM team working on this project.
This will be the first of several TPF Newsletter articles that will address technical aspects of Recoup 2000.
This article concentrates on changes to the creation, loading, and scheduling of TPF descriptor records.
Creating TPF Descriptor Records
First, all of your current recoup descriptor records will have to be examined, possibly updated, and
definitely reassembled with the new GROUP and INDEX macros. This is caused by a couple of key changes. The
internal layout of the descriptor record has changed, so a reassemble must be done to place the generated data at
the correct location in the descriptor record. Next, descriptor containers have been changed to use 4-K programs
rather than 1-K data records. Finally, for record identification and scheduling purposes, all groups with USE=BASE
parameters must be identified by using a unique record ID and version number combination.
Changes in the GROUP Macro
Several parameters in the GROUP macro have become obsolete. With the inclusion of an online RCI process
that allows the elimination of duplicate data structure chases, two parameters for the MET= option have been
removed from the system. These parameters are MET=SWITCH and MET=TAPE. The new approach to this process
is explained later in this article.
Another parameter, IND=, also has a new look. Gone are the options related to fixed record unique attributes
(IND= S | T | B | M | T | ST | MST). In a TPF system, the online FACE table (FCTB) is the sole arbiter of a record
type's unique attributes. Therefore, when a processor participating in a recoup run on a loosely coupled complex is
assigned to chase a data structure, it will identify the owners of unique records and will initiate a chase for each based
on subsystem user (SSU), processor, and/or I-stream uniqueness. This normalization of unique attribute
information should reduce complexity and errors in coding descriptors. One impact of this change is that in a loosely or
tightly coupled complex, records should be chased from the file copies of the data. The only chases that should be
done out of memory are those that are in synchronized global fields and records (each processor has exactly the
same view of the data).
The GROUP macro also has some additional parameters. The first addition is
MET=DBREF. This parameter is only valid when coding a GROUP macro with the USE=DSCR parameter. It specifies that the record being chased
from a traditional TPF database is a TPF Database Facility (TPFDF) file, which should be handled by the TPFDF
software under the control of TPF recoup.
There are now two parameters used for versioning record structures. The VER= parameter, used with the
ID= parameter, allows you to define up to 255 different versions for records that share IDs but have different file
layouts. The FVN= parameter is similarly used with
the MET=DBREF parameter.
There are five new parameters on the GROUP macro that provide users some flexibility in scheduling where
and when a record structure will be chain chased by recoup. At the start of each recoup run, the TPF recoup
descriptors are examined and key information for each primary group (the ones coded with USE=BASE) is extracted and
stored in the IRSCT (IBM Recoup Scheduling Control Table). The order of chain chasing is determined by this
extracted information. The following new parameters on the GROUP macro provide the scheduling information:
IDFIRST=
Allows you to specify that this record ID/version will be scheduled for chain chase as soon as practical in
the beginning of the chain chase process.
IDNEXT=
Allows you to specify the record ID, or record ID and version, of the next primary group to be started by
the scheduling program when the current chain chase is
completed.
IDCOMP=
Allows you to specify that chain chasing of the
selected primary group cannot begin until the chase for the
primary group with the target record ID, or record ID and version, has completed it's chain chase
activity.
CPUID=
Can be used in a loosely coupled processing complex to provide scheduling information by directing which
processor is targeted to perform the chain chase of the primary RECID/VER group. If the specified CPU is not active,
the primary processor performs the chain chase at the end of recoup phase 1.
GRP=
Allows primary groups that have related database chases to be targeted for chain chasing on the same
processor. When the RCI option is coded, recoup will first check to see if a record has already been chased. If it has, it is
not chased again. An example of this occurs in a database where multiple fixed records point to a common pool
record. Chasing the common record multiple times would extend the run time for phase 1 recoup. Chasing these
record structures on a single processor in a given order will permit the elimination of multiple chases of records.
In the following example, the PNID chase will be one of the first chases started on the prime recoup
processor. Because the GRP= parameter is used, all other prime groups that have the
GRP=PR or GRP=(PR,RCI) parameter coded will be marked as targeted for the prime processor. Because the
RCI parameter is coded, each time a
PR is to be retrieved a check will be made in the pseudo directories to see if that address has already been
retrieved successfully. If so, the record will not be retrieved again and processing resumes with the next item in the
PD.
TESTPNID GROUP MAC=PD1PD,ID=PD,VER=01,NBR=1,TYP=#PNDRI,TIME=210, X
MET=(FON,28,8),OFL=(N,8),IDFIRST=YES,IDNEXT=(PG,01), X
ECB=20, GRP=(PR,RCI),USE=BASE,CPUID=PRIME
INDEX ID=PR,TYP=V,FI=PD1ITM,FA=PD1FA,LI=L'PD1ITM, X
CNT=(2,PD1CT), DUPEELIM=YES
TESTPNIG GROUP MAC=PG1PG,ID=PG,VER=01,NBR=1,TYP=#PNGRI,TIME=210, X
MET=(FON,1,8),OFL=(N,8),ECB=20,GRP=(PR,RCI),USE=BASE
INDEX ID=PR,TYP=V,FI=PG1ITM,FA=PG1FA,LI=L'PG1ITM, X
CNT=(2,PG1CT), DUPEELIM=YES
When the PNID records have been processed, recoup selects the PNIG records to process because the
PNID chase had an IDNEXT=(PG,01) coded. The
GRP=(PR,RCI) parameter signifies that both PNID and PNIG
records have embedded PR records.
New INDEX Macro Parameters
Like the GROUP macro, there have been several beneficial changes made to the INDEX macro. These
enhancements include an additional user exit point for code execution, the ability to navigate records with variable length
items, direct chasing of TPFDF records embedded in a traditional TPF file, reduced duplicate chain chasing of
embedded files, and specifying multiple record ID possibilities from a single location within a record. Following are the
new parameters with their explanations:
DUPEELIM=
DUPEELIM=YES is used to restrict duplicate chain chases
of selected records when
USE=BASE and
GRP=(grpid,RCI) are coded in the associated primary GROUP macro
statement.
ACODE=
This parameter provides an additional exit point for executing user-written code after an embedded pool record
is retrieved.
TYP=S
Specifies that the file is a TPFDF file described by a DBDEF and chain chased by TPFDF recoup.
FVN=fversionnbr
This parameter is only used with
TYP=S. It specifies the file version number used by the TPFDF product to
identify the file structure to be chased.
TYP=M
This parameter is used when embedded file addresses are contained in items or subitems that have a
variable-length format. For example, this might be used with a file in which each logical record starts with a 2-byte size
value followed by variable length data. The 2-byte size is used to index into the next logical record.
Another approach to variable-length items is to have a pointer of a known size and location in the item
referencing the location of an embedded file address also within the item.
SI=
When using variable items, this specifies the location of the first subitem in an item or a location of a pointer to
the first subitem in an item.
ALTID=altidtbl
Ever have one of those days when a programmer approaches you with an emergency? A database has
been designed without your review or concurrence and it has already been implemented into the system. So, you
must code the descriptor immediately! As you examine the database design you find that a field in a record has been
used twice (or more) to point to several different pool records, each with its own ID, size, and layout. This could
never happen? Think about it; how many different ways are file address reference fields described in your AAA
record? Well, recoup now provides a way around this dilemma. This allows recoup to chase multiple embedded pool
record types with different IDs from a single location in the parent record. Recoup compares the found record ID against
a list of possible record IDs. If a match is found, the correct chase is then
executed. If no match is found, the broken chain is reported against the first ID on the
list.
How does this work? The ALTID parameter references a label on a special index macro that is coded in the
descriptor, outside the GROUP/INDEX set that references
it. This INDEX statement uses the
TYP=AIDTBL parameter that expands to an alternate ID table. Because it is a special INDEX macro, it is not reflected in the NBR= parameter
on the GROUP macro and is handled in a way similar to user exit code. The alternate ID table INDEX
statement specifies sets of record IDs, record code checks, and descriptor locations.
The following snippet of descriptor code reflects an example of how this new function is used.
*------------------------------------------------------------
JWVER0 GROUP MAC=QW0JW,ID=JW,VER=01,NBR=1,TYP=#QW0JW, X
MET=(SEQ,0,1,2),GRP=(J2,RCI),ECB=20,USE=BASE
INDEX TYP=V,FI=QW0ENT,FA=QW0FIC,LI=L'QW0ENT,CNT=(4,QW0NET),X
ALTID=BKZBALT
*------------------------------------------------------------
JU1 GROUP MAC=QU0JU,ID=D1E4,NBR=1,USE=DSCR
INDEX TYP=F,ID=J2,FA=QU0J2P,DSCR=J21,DUPEELIM=YES
*------------------------------------------------------------
JVREC1 GROUP MAC=QV0JV,ID=JV,NBR=1,USE=DSCR
INDEX TYP=M,ID=J2,CNT=(4,QV0NET),FI=QV0ARR,LI=(4,QV0ITL), X
FA=QV0FAS,DSCR=J21,DUPEELIM=YES
*===================================
* ALTERNATE ID TABLE FOR JWVER0
*-----------------------------------
BKZBALT INDEX TYP=AIDTBL,(JU,,JU1),(JV,00,JVREC1),(JX,,)
In the previous example, the JW fixed record has a set of embedded items containing file addresses. These
records can be a JU, JV, or
JX record. The JU record, in turn, contains a single J2 record while the
JV record contains a set of variable-length items, each with a pointer to a J2 record. Finally, the
JX record contains no embedded records and no forward chaining.
FAT=
OK, here is a trick question. Why do I need to specify the
File Address Type for embedded file references?
Everyone knows a file address reference is 4 bytes,
right? Well, for one, if you were at the Fall 2000 TPFUG meeting in
Tucson, you got a peek at a new feature called Data Event Control Block (DECB) Support. A DECB permits the use of an
8-byte file address reference. This sounds like a future item type of thing. Something is coming so we need to
prepare for it now, so the FA4 parameter indicates a 4-byte file address! Additionally, recoup needs to be able to identify a
32-byte TPF collection support (TPFCS) persistent identifier (PID) to chase a TPFCS collection from a traditional
TPF file. This is done with the PID parameter.
Loading Recoup Descriptors
No more tapes! Descriptors will now be loaded as normal 4-K programs and then moved into a final staging
area using the ZRBKD functional message. See TPF Migration Guide: Program Update
Tapes for details about this procedure, but here is a general flow:
First, it is necessary to enter ZRBKD INIT
CTL to initialize the BKD load control
record.
Next, enter the ZRBKD DUMM functional message to insert dummy descriptor references in the descriptor
staging area. This functional message can also be used to change any active descriptor to a dummy
descriptor.
Once all descriptors have been updated, assembled, and then loaded to the system, you are ready to move
selected descriptors to the specific online descriptor ordinal numbers by using the ZRBKD MOVE functional message.
What if you change your mind and would like to restore a previous version of a
descriptor? The ZRBKD REST functional message will handle it for
you.
What if you are not sure which descriptors are active on your system? Enter the ZRBKD DISP functional
message to get the current status of all active descriptors you have loaded into the
system.
If you would like to get a history of the last 10 ZRBKD functional messages that you have entered, ZRBKD HIST
will do the trick. Too many ZRBKD commands to
remember? Let ZRBKD HELP remind you what the syntax is.
For more information, see TPF Migration Guide: Program Update
Tapes, TPF System Macros, and TPF
Operations.
Because a lot has changed for Recoup 2000, it is impossible to cover everything in one
article. Stay tuned.
Fourth Quarter 2000 - Table of Contents
|
