gtps1m3bSystem Macros

INDEX-Recoup Descriptor Record Structure

Use this system macro to do the following:

This macro is used both offline and online with the GROUP macro. INDEX macros are associated with the GROUP macro that immediately precedes them.

The offline process uses the INDEX and GROUP macros to create recoup descriptor container records.

The DSECT part of the GROUP and INDEX macros is used to access the different fields in the BKD record online.

See TPF Database Reference for more information about online recoup. See GROUP-Recoup Descriptor Record Access for more information about the GROUP macro.

The following table shows the specification of the TYPE parameter and the requirements of the remaining parameters used with the INDEX macro.

Table 6. Specification of the TYPE Parameter for the INDEX Macro and Parameter Requirements

Parameter TYP=F TYP=C TYP=V TYP=L TYP=M TYP=S
ACODE Optional Error Optional Error Optional Ignored
ALTID Optional Optional Optional Optional Optional Ignored
BCH Ignored Optional Ignored Ignored Ignored Ignored
CNT Ignored Ignored Optional Optional Optional Ignored
CODE Optional Optional Optional Optional Optional Optional
CREATE Ignored Ignored Optional Optional Optional Ignored
DSCR Optional Error Optional Optional Optional Ignored
DUPEELIM Optional Optional Optional Optional Optional Ignored
FA Required Optional Optional Ignored Optional Ignored
FAT Optional Optional Optional Ignored Optional Optional
FCOD Ignored Ignored Optional Optional Optional Ignored
FI Ignored Ignored Required Required Required Ignored
FII Ignored Ignored Optional Ignored Optional Ignored
FVN Ignored Ignored Ignored Ignored Ignored Optional
ID Optional Optional Optional Optional Optional Ignored
LI Ignored Ignored Required Required Required Ignored
LII Ignored Ignored Optional Ignored Optional Ignored
LSI Ignored Ignored Optional Optional Optional Ignored
MAC Optional Optional Optional Optional Optional Ignored
NAB Ignored Ignored Optional Optional Optional Ignored
ORD Ignored Ignored Ignored Required Ignored Ignored
RCC Optional Optional Optional Optional Optional Ignored
REG Ignored Ignored Ignored Ignored Ignored Ignored
SFA Ignored Ignored Optional Optional Optional Ignored
SI Ignored Ignored Optional Optional Optional Ignored
SIC Ignored Ignored Optional Optional Optional Ignored
SUFFIX Ignored Ignored Ignored Ignored Ignored Ignored

The following identifies the symbolic notation found in the previous table and also in the syntax information that follows.

Error
Parameter is not applicable and a message will be produced.

Ignored
Parameter is ignored (not required).

Required
Parameter is required.

Optional
Parameter is not required.

Format




label
is a symbolic name that can be assigned to the macro statement.

TYP
specifies the type of file.

C
specifies a standard forward chaining file, where the file address is contained in a standard header (at location 8). If the file address is not at location 8, code the FA parameter.

F
specifies a fixed address file, where the file address or persistent identifier (PID) is at a fixed location. (Do not use for forward chaining.)

S
specifies that the file is a TPF Database Facility (TPFDF) file described by DBDEF macro statements and chain chased by TPFDF recoup.

L
specifies an embedded ordinal number file, where a group of ordinal numbers are described.

M
specifies a variable item file, where file addresses are contained in variable-length items or subitems.

V
specifies a fixed item file, where file addresses or persistent identifiers (PIDs) are contained in fixed-length items, subitems, or PIDs.

ORD
specifies the ordinal description if chained records contain an ordinal number, where:

rectype
The file address compute (FACE) program record type used to convert the ordinal number to a file address.

length
The length of the field containing the ordinal number.

address
The location relative to the first item (FI) of the ordinal number; for example:
ORD=(#PNDRI,1,TAGE)
Note:
If the FI parameter resolves to a value that cannot be relocated or pointer value, the ORD parameter must also be a value that cannot be relocated or pointer value.

ID=recordid
specifies the record ID used to retrieve the record; for example:
ID=AA
Note:
If omitted, no record ID check is done and a warning message is produced.

ALTID=altidlbl
specifies the label of a statement that expands to an alternate ID table that is used for recoup chain chase processing. Recoup processing chases the first record ID that matches the information supplied in the table. The statement at the specified label must have the following format:
altidlbl INDEX TYP=AIDTBL,(rid,rcc,dscrloc),(rid,rcc,dscrloc),....

Where;

rid
is a 2-character or 4-hexadecimal alternate record ID.

rcc
is a 1-character or 2-hexadecimal record code check (RCC) of the alternate record ID.

dscrloc
specifies the location of the GROUP macro statement that also describes the data record when retrieved (located in the same descriptor container record). If the record contains no more references to chain chasing (including overflow or forward chaining), dscrloc can be omitted, but the preceding comma must still be specified.

Recoup processing compares the record ID and RCC of a record to the information found in the alternate ID table. If the information matches an item, the record is chain chased using the GROUP macro statement at the descriptor location (dscrloc). In the following example, assume that recoup processing found the record ID of JJ with an RCC of 01 in the record that was at label JX0FAD. This matches the first ID in the alternate record table; therefore, the record is chain chased using the GROUP macro statement at label JUREC1.

          INDEX  TYP=F,ALTID=TEST,FA=JX0FAD)
 
TEST      INDEX TYP=AIDTBL,(JJ,01,JUREC1),(FC01,1,FCTAG),(BB,,)
 
JUREC1    GROUP  USE=DCSR,
 
Note:
You cannot specify the ALTID parameter with the ID, RCC, or DSCR parameter.

ACODE=acodeloc
specifies the label where there is code to run after finding the pool address; for example:
ACODE=PD3AR

BCH=backchn
specifies the label of the backward chain address from the last record in the chain; for example:
BCH=NC0BCH

CODE=codeloc
specifies the location within the descriptor container record of code to run prior to locating imbedded file addresses; for example:
CODE=PREFIND

This is useful in cases where certain fields in a data record can be tested to determine if the data record has no imbedded addresses.

DSCR=dscrloc
specifies the location of the GROUP macro statement that also describes the data record when retrieved (located in the same descriptor container record). The following example shows the DSCR parameter pointing to GROUP3, which is a GROUP macro statement that also describes the data record:
INDEX TYP=F, DSCR=GROUP3, ...
 
 
GROUP3   GROUP  USE=DCSR, ...

DUPEELIM
specifies whether or not to use the special recoup chain-chasing indicator (RCI) algorithm that eliminates duplicate chain chasing.

NO
does not check pseudo directories to prevent finding a pool that has already been chain chased.

YES
checks pseudo directories to prevent finding a pool that has already been chain chased.
Note:
DUPEELIM=YES can only be specified when USE=BASE and GRP=(grpid,RCI) are specified in the associated GROUP macro statement, where grpid is the group name that is assigned to a specific group of record IDs.

INDEX TYP=F,FA=AA0AG1,ID=CC,DUPEELIM=YES
 
INDEX TYP=V,ID=CA,FI=I80IFA,LI=L'I80IFA,
      CNT=(N,I80NENT),DSCR=XXXX,DUPEELIM=YES
 
INDEX TYP=M,ID=CA,FI=I80IFA,LI=L'I80IFA,
      NAB=(N,I80NENT),DSCR=YYYY,DUPEELIM=YES
 
INDEX TYP=C,ID=FC32,DUPEELIM=YES

FA
specifies the location of the file address, where:

faloc
is a displacement to the file address, where faloc is one of the following:
  • A DSECT tag representing the location of the file address; for example:
     FA=PD1IFA
    
  • An absolute displacement from the start of the first item, expressed as (alpha,disp), where alpha is any alphabetic character and disp is the displacement to the file address; for example:
    FA=(N,40)
    

faptr
is the size and location of the 1- to 4-byte field that contains the pointer to the file address, where faptr is one of the following:
  • An absolute size and DSECT tag of the location of the file address pointer; for example:
     FA=(2,VR1FAP) 
    
  • A calculated size and DSECT tag of the location of the file address pointer; for example:
    FA=(L'VR1FAP,VR1FAP)
    
  • An absolute displacement from the start of the first item, expressed as (alpha,size,disp), where alpha is any alphabetic character, size is the size of the field that contains the pointer, and disp is the displacement to the pointer field. The absolute displacement to the 2-byte pointer field is 16 in the following example:
    FA=(N,2,16)
    
Note:
If the FI parameter is specified and resolves to a value that cannot be relocated or pointer value, the FA parameter must also resolve to a value that cannot be relocated or pointer value.

FVN=versionnbr
specifies the file version number used by the TPFDF product to identify file structures that have blocks with different layouts than the prime blocks; for example:
INDEX TYP=S,FVN=1

MAC=macro_name
specifies the name of the data macro describing the data record containing embedded addresses.

RCC
specifies the location of the record code check (RCC).

(P,dtag)
If the RCC is at a location in the prime record; for example:
RCC=(P,NC0RCC)

(I,dtag)
If the RCC is at a displacement in an item; for example:
RCC=(I,TAG1)

(C,x)
If the RCC is a constant (any number from 0 to 255); for example:
RCC=(C,246)

REG=reg
specifies the register to be used as the base for the DSECT specification; for example:
REG=R7
Note:
If the REG parameter is specified, the macro generation assumes that the request is to generate the DSECT only.

SUFFIX=suffix
specifies the suffix to be used on the DSECT definition, where suffix is an alphabetic character; for example:
SUFFIX=Q

CNT=itemcnt
specifies the item count, where itemcnt is specified as an absolute value or specified as a length and location that contains the item count value.

The following example shows an item count specified as an absolute value:

CNT=(N,20)

The following example shows an item count specified as a value specified for 2 bytes starting at location PD1TAG:

CNT=(2,PD1TAG)

CREATE
specifies whether an entry control block (ECB) is to be created with the retrieved record.

YES
specifies that an ECB is created with the retrieved record, which provides faster processing time and sometimes avoids single threading (usually where there is only one fixed level record with many embedded addresses that also may have many embedded addresses).

If you specify CREATE=YES, more ECBs are created than were specified with the ECB parameter in the primary GROUP macro.

NO
specifies that an ECB is not created with the retrieved record.

FAT
specifies the type of file address specified with the FA parameter.

FA4
specifies a 4-byte file address.

FA8
specifies an 8-byte file address.

PID
specifies a TPF collection support (TPFCS) persistent identifier (PID).

FCOD=fcodloc
specifies the location in the descriptor container record of code to be processed for every item in a data record; for example
FCOD=ITEMCODE

This is used for testing fields in items where the file addresses can be for different record types, or if item is inactive, but file address not cleared.

Notes:

  1. Register 1 (R1) contains the base of data record.

  2. R2 points to item.

  3. When TYP=L, R3 has the address of the current ordinal slot, and R2 points to the current item.

  4. When TYP=V or TYP=M, R7 has the address of the current subitem, and R2 points to the current item.

FI
specifies the location of the first item in a record, where:

filoc
is a displacement to the first item relative to the start of the record, where filoc is one of the following:
  • A DSECT tag representing the location of the first item; for example:
     FI=PD1ITM 
    
  • An absolute displacement from the start of the record, expressed as (alpha,disp), where alpha is any alphabetic character and disp is the displacement to the first item; for example:
    FI=(N,40)
    

fiptr
is the size and location of the 1- to 4-byte field that contains the pointer to the first item in the record, where fiptr is one of the following:
  • An absolute size and DSECT tag of the location of the first item pointer; for example:
     FI=(2,VR1IPT) 
    
  • A calculated size and DSECT tag of the location of the first item pointer; for example:
    FI=(L'VR1IPT,VR1IPT)
    
  • An absolute displacement from the start of the record, expressed as (alpha,size,disp), where alpha is any alphabetic character, size is the size of the field that contains the pointer, and disp is the displacement to the pointer field. The absolute displacement to the 2-byte pointer field is 16 in the following example:
    FI=(N,2,16)
    
Note:
If the FI parameter is specified and resolves to a value that cannot be relocated or pointer value, the FA, LI, ORD, SFA, SI, or SIC parameter must also resolve to a value that cannot be relocated or pointer value.

FII
specifies the first item index that is used to locate the first valid item in a record, where:

fiidisp
is a field that contains the absolute displacement from the start of the record to the first item in a record, expressed as (alpha, size, namefield), where alpha is any alphabetic character, size is the size of the field, and namefield is the name field that contains the displacement. In the following example, the 2-byte field, TAGB, contains the absolute displacement from the start of the record to the first item :
FII=(D,2,TAGB)

fiinbr
is a field that contains the item number of the first item in a record, expressed as (size, namefield), where size is the size of the field, and namefield is the name of the field that contains the item number of the first item. The first item is item number 0; therefore, the last item number is one less than the number of items. In the following example, the 2-byte field, TAGB, contains the number of the last item in a record:
FII=(2,TAGB)
Note:
The FII parameter is used only for fixed-length items.

LI
specifies the length of an item or the location of a field that contains the length of an item in a record, where:

li
is the length of an item in a record, where li is one of the following:
  • An assembler expression that resolves to an absolute value; for example:
     LI=L'PD1ITM 
    
  • An absolute value; for example:
    LI=32
    

liptr
is the size and location of the 1- to 4-byte field that contains the pointer to the length of an item, where liptr is one of the following:
  • An absolute size and DSECT tag of the location of the item length; for example:
     LI=(2,VR1IPT) 
    
  • A calculated size and DSECT tag of the location of the item length; for example:
    LI=(L'VR1IPT,VR1IPT)
    
  • An absolute displacement from the start of the record, expressed as (alpha,size,disp), where alpha is any alphabetic character, size is the size of the field that contains the pointer, and disp is the displacement to the pointer field. The absolute displacement to the 2-byte pointer field is 12 in the following example:
    LI=(N,2,12)
    
Note:
If the FI parameter is specified and resolves to a value that cannot be relocated or pointer value, the LI parameter must also resolve to a value that cannot be relocated or pointer value.

LII
specifies the last item index that is used to locate the last valid item in a record is in a field that contains the absolute displacement to the last item in a record or the location of a field that contains the item number of the last used item in a record, where:

liidisp
is a field that contains the absolute displacement from the start of the record to the last item in a record, expressed as (alpha,size,namefield), where alpha is any alphabetic character, size is the size of the field, and namefieldis the name field that contains the displacement. In the following example, the 2-byte field, TAGB, contains the absolute displacement from the start of the record to the last item :
LII=(D,2,TAGB)

liinbr
is a field that contains the item number of the last item in a record, expressed as (size,namefield), where size is the size of the field, and namefield is the name of the field that contains the item number of the last item. The first item is item number 0; therefore, the last item number is one less than the number of items. In the following example, the 2-byte field, TAGB, contains the number of the last item in a record:
LII=(2,TAGB)
Note:
The LII parameter is only used for fixed-length items.

LSI
specifies the length of a subitem or the location of a field that contains the length of a subitem in a record, where:

lsi
is the length of a subitem in a record, where lsi is one of the following:
  • An assembler expression that resolves to an absolute value; for example:
     LSI=L'PD1ITM 
    
  • An absolute value; for example:
    LSI=32
    

lsiptr
is the size and location of the 1- to 4-byte field that contains the pointer to the length of a subitem, where lsiptr is one of the following:
  • An absolute size and DSECT tag of the location of the subitem length; for example:
     LSI=(2,VR1IPT) 
    
  • A calculated size and DSECT tag of the location of the subitem length; for example:
    LSI=(L'VR1IPT,VR1IPT)
    
  • An absolute displacement from the start of the record, expressed as (alpha,size,disp), where alpha is any alphabetic character, size is the size of the field that contains the pointer, and disp is the displacement to the pointer field. The absolute displacement to the 2-byte pointer field is 12 in the following example:
    LSI=(N,2,12)
    
Note:
If the SFA parameter is specified and resolves to a value that cannot be relocated or pointer value, the LSI parameter must also resolve to a value that cannot be relocated or pointer value.

NAB
specifies the next available byte or the location of a field that contains the next available byte, where:

nab
is the next available byte in a record, where nab is an absolute value; for example:
NAB=(N,20)

nabptr
is the size and location of the 1- to 4-byte field that contains the pointer to the next available byte, where nabptr is one of the following:
  • An absolute size and DSECT tag of the location of the next available byte; for example:
     NAB=(2,VR1NAB) 
    
  • A calculated size and DSECT tag of the location of the next available byte; for example:
    NAB=(L'VR1NAB,VR1NAB)
    

SFA
specifies the location of the subitem file address, where:

sfaloc
is a displacement to the subitem file address, where sfaloc is one of the following:
  • A DSECT tag representing the location of the subitem file address; for example:
     SFA=TAGA
    
  • An absolute displacement to the subitem file address relative to the start of the first item, expressed as (alpha,disp), where alpha is any alphabetic character and disp is the displacement to the subitem file address; for example:
    SFA=(G,40)
    

sfaptr
is the size and location of the 1- to 4-byte field that contains the pointer to the subitem file address, where sfaptr is one of the following:
  • An absolute size and DSECT tag of the location of the subitem file address pointer; for example:
     SFA=(2,VR1IPT) 
    
  • A calculated size and DSECT tag of the location of the subitem file address pointer; for example:
    SFA=(L'VR1IPT,VR1IPT)
    
  • An absolute displacement from the start of the first item, expressed as (alpha,size,disp), where alpha is any alphabetic character, size is the size of the field that contains the pointer, and disp is the displacement to the pointer field. The absolute displacement to the 2-byte pointer field is 16 in the following example:
    SFA=(N,2,16)
    
Note:
If the FI or SI parameter is specified and resolves to a value that cannot be relocated or pointer value, the SFA parameter must also resolve to a value that cannot be relocated or pointer value.

SI
specifies the location of the first subitem in an item, where:

siloc
is a displacement to the first subitem, where siloc is one of the following:
  • A DSECT tag representing the location of the subitem file address; for example:
     SI=TAGA
    
  • An absolute displacement to the first subitem relative to the start of the first item, expressed as (alpha,disp), where alpha is any alphabetic character and disp is the displacement to the first subitem; for example:
    SI=(G,40)
    

siptr
is the size and location of the 1- to 4-byte field that contains the pointer to the first subitem, where siptr is one of the following:
  • An absolute size and DSECT tag of the location of the first subitem pointer; for example:
     SI=(2,VR1IPT) 
    
  • A calculated size and DSECT tag of the location of the first subitem pointer; for example:
    SI=(L'VR1IPT,VR1IPT)
    
  • An absolute displacement from the start of the first item, expressed as (alpha,size,disp), where alpha is any alphabetic character, size is the size of the field that contains the pointer, and disp is the displacement to the pointer field. The absolute displacement to the 2-byte pointer field is 16 in the following example:
    SI=(N,2,16)
    
Note:
If the FI or SFA parameter is specified and resolves to a value that cannot be relocated or pointer value, the SI parameter must also resolve to a value that cannot be relocated or pointer value.

SIC
specifies the subitem count (that is, the number of subitems), where:

sicnt
is the subitem count, where sicnt is an absolute value; for example:
SIC=(N,32)

sicntptr
is the size and location of the 1- to 4-byte field that contains the pointer to the subitem count, where sicnt is one of the following:
  • An absolute size and DSECT tag of the location of the subitem count; for example:
     LI=(2,VR1SIC) 
    
  • A calculated size and DSECT tag of the location of the subitem count; for example:
    LI=(L'VR1SIC,VR1SIC)
    
  • An absolute displacement from the start of the item, expressed as (alpha,size,disp), where alpha is any alphabetic character, size is the size of the field that contains the pointer, and disp is the displacement to the pointer field. The absolute displacement to the 2-byte pointer field is 12 in the following example:
    LI=(D,2,12)
    

Notes:

  1. When SIC is specified, the LSI parameter is required.

  2. If the FI parameter is specified and resolves to a value that cannot be relocated or pointer value, the SIC and LSI parameters must also resolve to values that cannot be relocated or pointer values.

Entry Requirements

Return Conditions

Programming Considerations

Examples