gtpd1m1nDatabase Reference

Recoup Functions by Phase

The following sections list the recoup functions by phase.

Recoup Pre-Phase 1 Functions

Phase 1 chain chasing is determined by information in the recoup descriptor container records and TPF collection support (TPFCS) recoup indexes. Create descriptor container records and recoup indexes describing all records and TPFCS collections that can reference long-term file pool addresses and TPFCS persistent identifiers (PIDs).

Recoup Descriptor Container Records

The descriptor container records are read and each record type in them is passed to the appropriate recoup chain chase program for processing. Several descriptor container records are provided with the recoup package. These records describe the processing to be done on record types which must be part of the TPF system and that can contain long-term file address and PID references. These descriptor container records can be used as an example when you are creating descriptor container records. See the GROUP and INDEX macros in TPF System Macros for additional examples and instructions.

Recoup currently supports the following types of record structure processing:

TPFCS Recoup Indexes

TPFCS collections created by user applications will not be recouped unless they are explicitly made known to the TPF system by establishing one or more TPFCS recoup indexes. A recoup index describes the location of persistent identifiers (PIDs) and file addresses embedded in all collections associated with that recoup index. A TPFCS database consists of automatically generated system collections as well as user collections. An anchor collection which is usually the application dictionary of the data store (named DS_USER_DICT), refers to user-created collections, which refer to other collections, and so on. Every user-created collection must be referred to or it will not be recouped. Several recoup indexes are provided with the recoup package to recoup the system collections. A recoup index must be created and associated with the anchor collection and any user collections that contain embedded references. This is done by running a user application or by entering the ZBROW RECOUP command. Furthermore, if the embedded reference is a file address, a TPF descriptor with the USE=TPFCS parameter on the GROUP macro must be created for that record.

If a TPF file contains an embedded PID, the TPF descriptor for that record is all that is needed to recoup the embedded PID. However, if the embedded PID contains additional embedded information, a recoup index will be needed to describe the embedded PID.

For more information about TPFCS recoup, see TPFCS Recoup. See the GROUP and INDEX macros in TPF System Macros for additional examples and instructions. See TPF Operations for more information about the ZBROW RECOUP command.

Recoup Considerations for TPF Internet Mail Server

Before you run recoup for the TPF Internet mail server database, ensure the mail server recoup descriptor (BKD1) is defined correctly and loaded on the TPF subsystem in which you plan to run the TPF Internet mail servers. You must also ensure that BKD1 contains a GROUP and INDEX macro pair associated with each #MAILxx record that you have defined.

See TPF Transmission Control Protocol/Internet Protocol for more information about recoup considerations for the TPF Internet mail server database and how to update BKD1.

Setup

Recoup setup must be done once from CRAS state or above for each subsystem by entering the ZRECP SETUP command. The recoup setup process will create the recoup scheduling control table (IRSCT) and one recoup active root table (IRART) for each defined processor.

Recoup Phase 1 Functions

Recoup phase 1 processing consists of the following:

Pre-Chain Chase Processing

Recoup phase 1 does the following before it begins to chase pool addresses:

Chain Chase Processing

Chain chase processing is controlled by the IRSCT. This table is built at the time the ZRECP RECALL command is entered, during a full recoup run. Each base group identified in the recoup descriptor container records (BKD) initialized during the pre-phase 1 stage is examined for validity and scheduling directives. These groups are added to the IRSCT along with all TPFCS data stores that reside on the current subsystem. Recoup uses this information to define the order, and in a loosely coupled complex; on which processor the chain chase will be run. With this information, every record on the subsystem that contains pointers to file pool records is accessed. Those file pool records and all file pool records subsequently chained from them are accessed until all pool-related chains in the subsystem have been traversed.

Recoup processing uses the FACSZ macro to simulate an environment so the records can be chased by the assigned processor on behalf of the owning environment.

When an item is recorded for every pool address in use in the system, the function of phase 1 recoup is complete.

Notes:

  1. It is possible to have a record type in the system that can be referenced from several sources (for example, a passenger name record, or PNR). Under this condition, phase 1 chain chasing can spend a great amount of time reprocessing these chains.

  2. In an MDBF environment, records will be chased starting with the first subsystem user (SSU) in a subsystem and ending with the last SSU for that subsystem. Subsystem common records will be chased only once, and subsystem unique records will be chased by the owning SSU.

  3. In a loosely coupled environment, all records of a given type will be chased from the processor assigned to that type in the IRSCT. Processor common records are chased only once. Processor unique records will be chased for each owning processor from a single assigned processor using the FACZ macro to access the file copy of the processor unique fixed file record. This approach is also used for records that are defined as processor or I-stream unique.

  4. Because it is difficult in a loosely-coupled environment to guarantee that all processors in the complex will be up and running in the recoup process, it is mandatory that pool file address pointers maintained in global fields, global records, and core resident records be chased from the file copy of the records. The only exception to this restriction is when the records or fields have been defined to the TPF system as synchronized data (for example, all processors and I-streams have exactly the same view of the data).

  5. Recoup phase 1 will also access all TPFCS data stores defined for the subsystem on which recoup is running and recoup the data store internal system collections. Recoup phase 1 will also recoup user-created collections by using the TPFCS recoup indexes to chain chase PIDs and extract embedded PIDs and file addresses. Recoup processing uses information in the base TPFCS data store (TPFDB), which resides on the basic subsystem (BSS). Only collections belonging to data stores on the subsystem where recoup is running will be recouped.

Post-Chain Chase Processing

After all record IDs have been chain chased, recoup does the following:

Phase 2 Functions

When chain chase processing is completed on all processors, the primary processor automatically starts recoup phase 2 processing, which does the following:

Recoup Phase 3 Functions

Recoup phase 3 can be started when phase 2 is completed and recoup pseudo directory (#SONRPE) records have been created. Phase 3 functions are started by entering commands. Recoup phase 3 processing consists of the following:

Erroneously Available Processing

The ZRECP RESUME command starts erroneously available processing, which does the following:

Note:
When erroneously available processing ends, you can enter the ZRECP PROTECT command immediately to protect pool addresses that were found to be erroneously available from being used by the TPF system. If no pool addresses were found to be erroneously available, enter the ZRECP IGNORE command instead.

Lost Address Processing

The ZRECP PROTECT or ZRECP IGNORE command starts lost address processing, which does the following:

Note:
When lost address processing ends, you can enter the ZRECP ADD or ZRECP DEL command to create an exclusion or inclusion table. These tables are used by rebuild processing to adjust the lost addresses that are rolled in.

Rebuild Processing

The ZRECP REBUILD or ZRECP NOREBUILD command starts rebuild processing, which does the following:

Rollin Processing

The ZRECP PROCEED command starts rollin processing, which adds pool files to the online pool directory (#SONRI) by using the recoup rollin directory (#SONROLL).

Recoup Phase 4 Functions

Integrated online pool maintenance and recoup support merged the recoup phase 3 and phase 4 functions into what is now called phase 3. Recoup phase 4 no longer exists.

Recoup Phase 5-Phase 7 Functions

Recoup phase 5 is run as an optional phase to help programmers determine the cause of lost and erroneously available file pool addresses. Phase 5 is not considered to be part of the normal recoup run. It is started when you enter the ZRECP DUMP command when phase 3 is completed. Phase 5 reads an input tape (ADR) and, using selective file dump and trace (SFDT), causes all lost and erroneously available file pool records to be written to the (RTL) tape.

Recoup phase 6 and phase 7 then use the information gathered by phase 5 to create various summary listings. Phase 6 and phase 7 are run offline under MVS, and the summaries that they create are used to help recoup determine the causes of lost and erroneously available addresses. See Phase 6 JCL and Phase 7 JCL for sample JCL to run recoup phase 6 and phase 7.

Phase 6 JCL

****Replace library parameters with installation's library
   *LINK.LIBRARY* = library containing PPCP offline segment
//POST  EXEC  PGM=PPCP,REGION=512K,PARM=('TV,Y,TR.')
//* TV => STV OR NO PTV      RS => RTL CREATED BY PTV
//STEPLIB  DD DISP=SHR,DSN=*LINK.LIBRARY*
//SYSOUT   DD  SYSOUT=A
//SYSUDUMP DD  SYSOUT=A
//SYSABEND DD  SYSOUT=A
//PRDD     DD  SYSOUT=A
//DDSCTH   DD  DSN=&&SCRTH,DISP=(NEW,PASS),
//             UNIT=(SYSDA,,DEFER),SPACE=(TRK,(50,200))
//SYS000   DD  DSN=RTA.TAPE,UNIT=TAPE,LABEL=(,SL),DISP=(OLD,KEEP),
//             VOL=SER=XXXXXX
//

Phase 7 JCL

****Replace library parameters with installation's library.
   *LINK.LIBRARY* = library containing BPR0xx offline segment
//STEP1   EXEC PGM=BPR0xx,REGION=400K,PARM='SSID'
//*  The PARM specifies the Subsystem data required from the RTL tape.
//*  It is the 4-character subsystem name. If omitted, all data
//*  pertinent to BPR0 is reported upon.
//STEPLIB DD DSN=*LINK.LIBRARY*,DISP=SHR
//PRINT   DD SYSOUT=A
//TAPEIN  DD DSN=RTA.TAPE,DISP=(OLD,KEEP),UNIT=(TAPE,,DEFER),
//    LABEL=(,SL),VOL=SER=XXXXXX