gtpo1m1yOperations

ZBROW RECOUP-Manage Recoup Indexes

Use this command to manage recoup indexes, which describe the location of embedded file addresses and persistent identifiers (PIDs) in collections. With this command, you can:

Requirements and Restrictions

Format




ADD
adds an entry to an existing recoup index.

indexname
is the 8-byte character name of the recoup index being managed. If you specify a character name that is less than 8 bytes, the name will be padded on the right with spaces.

ETOKen
specifies a unique 8-byte identifier for the given entry in the specified recoup index. If you specify a character name that is less than 8 bytes, the name will be padded on the right with spaces. If you specify a hexadecimal string that is less than 8 bytes, the string will be padded on the right with zeros.

charstr
is a character string.

X%hexstr
is a hexadecimal string.

DISP-displ
specifies the displacement into the user collection element for the user-embedded PID or file address, where displ is the 0-based hexadecimal displacement.

ETYPe
specifies one of the following embedded recoup reference type indicators:

FA
indicates that the index entry being added describes a 16-byte area that contains a file address.

See TPF Database Reference for more information about the format of the file addresses embedded in collections.

PID
indicates that the index entry being added describes a PID.

INDEX-decval
specifies the index to access the user collection element that contains the embedded recoup reference, where decval is the 1-based decimal value of the index. Either this parameter or the KEY parameter is needed for a heterogeneous collection.

KEY
indicates the value of a character key to access the user collection element that contains the embedded recoup reference. Either this parameter or the INDEX-decval parameter is needed for a heterogeneous collection.

DEFine
creates a recoup index.

BLOB
indicates that the user collection is a binary large object (BLOB) and therefore not homogeneous or heterogeneous.

HOMogeneous
indicates that all elements in the collection have the same displacement to the PID or file address and can be recouped the same way.

HETerogeneous
indicates that not all elements contain an embedded file address or PID, or the displacements are different (that is, not all elements can be recouped the same way).

DESC-text
describes the recoup index, where text is up to 256 alphanumeric characters.

DELete
deletes a recoup index.

DISPlay
displays a specified recoup index or a list of all defined recoup indexes from the qualified data store.

ALL
displays a list of all defined recoup indexes from the qualified data store.

LINK
associates a recoup index with a specified existing collection. Each time a collection is linked, it will overwrite previous settings without error.

colname
is the 1- to 32-character alphanumeric name of the collection whose recoup index association is being changed.

REMove
deletes an entry from a recoup index.

UNLink
removes the association between the specified collection and its recoup index. If the collection is not associated with a recoup index, no error will be indicated.

Additional Information

None.

Examples

An entry is added to recoup index INDEX001 in data store TESTX.DS in the following example. The entry has a key of TOKEN001 and indicates that all user collections associated with this recoup index are either homogeneous or a BLOB. If the collection is homogeneous, there is a PID at displacement 0 of each element; if the collection is a BLOB, there is a PID at displacement 0.

In this example, the ZBROW QUALIFY command is shown only to make the example more complete. You only have to enter the ZBROW QUALIFY command once; you do not have to enter the command again until the target data store needs to change to another data store.

+--------------------------------------------------------------------------------+
|User:   ZBROW QUAL SET DS-TESTX.DS                                              |
|                                                                                |
|System: BROW0607I 10.56.31 QUALIFICATION PROCESSING COMPLETED                   |
|                                                                                |
|User:   ZBROW RECOUP ADD INDEX001 ETOK-TOKEN001 DISP-0 ETYPE-PID                |
|                                                                                |
|System: BROW0602I 10.56.43 BROWSER QUALIFIED FOR DSNAME TESTX.DS                |
|        BROW1011I 10.56.43 RECOUP INDEX ENTRY SUCCESSFULLY ADDED                |
|                                                                                |
+--------------------------------------------------------------------------------+

Recoup index INDEX001 is created in the following example to describe a homogeneous collection.

+--------------------------------------------------------------------------------+
|User:   ZBROW RECOUP DEFINE INDEX001 HOMOG DESC-PRIMARY_INDEX                   |
|                                                                                |
|System: BROW0602I 10.56.43 BROWSER QUALIFIED FOR DSNAME TESTX.DS                |
|        BROW1012I 10.56.43 RECOUP INDEX SUCCESSFULLY DEFINED                    |
|                                                                                |
+--------------------------------------------------------------------------------+

Recoup index INDEX001 is deleted in the following example.

+--------------------------------------------------------------------------------+
|User:   ZBROW RECOUP DELETE INDEX001                                            |
|                                                                                |
|System: BROW0602I 10.56.43 BROWSER QUALIFIED FOR DSNAME TESTX.DS                |
|        BROW1013I 10.56.43 RECOUP INDEX SUCCESSFULLY DELETED                    |
|                                                                                |
+--------------------------------------------------------------------------------+

The contents of recoup index INDEX001 in data store TPFDB are displayed in the example that follows. The display shows the recoup index header and each entry in the recoup index, where:

 NAME 
is the name of the recoup index.

 PID 
is the persistent identifier (PID) of the recoup index.

 DESC 
is the description of a recoup index that was entered when the index was defined.

 TYPE 
is one of the following:

 HOMOGENEOUS 
indicates that all the elements of the collection that the recoup index is associated with have the same format.

 HETEROGENEOUS 
indicates that the elements of the collection with which the recoup index is associated have different formats.

 IGNORED (BLOB) 
indicates that the collection is a BLOB and the recoup index is not homogeneous or heterogeneous.

 CONTROL 
indicates which processing restrictions apply, where NONE indicates that no specific processing restrictions apply.

 TOKEN 
is the unique identifier for each entry in the recoup index, displayed in hexadecimal characters.

 TYPE 
is one of the following:

 PID 
indicates that the entry refers to an embedded PID in the collection elements.

 FA 
indicates that the entry refers to an embedded file address in the collection elements.

 DISPL 
is the displacement into the collection element for the embedded information. This is shown as a hexadecimal value.

The following fields, which are not shown in this example, are included with displays for heterogeneous recoup indexes:

 ACCESS 
is one of the following:

 INDEX 
indicates that the collection elements are accessed by a specified index.

 KEY 
indicates that the collection elements are accessed by a specified key.

 IDX 
is the index used to select the collection element for heterogeneous recoup indexes with ACCESS-INDEX. This is shown as a decimal value.

 LEN 
is the length of the key used to select the collection element for recoup indexes with ACCESS-KEY. This is shown as a decimal value.

 KEY 
is the key, displayed in hexadecimal character format, that is used to select the collection element for heterogeneous recoup indexes with ACCESS-KEY.
+--------------------------------------------------------------------------------+
|User:   ZBROW RECOUP DISPLAY INDEX001                                           |
|                                                                                |
|System: BROW0602I 10.56.43 BROWSER QUALIFIED FOR DSNAME TPFDB                   |
|        BROW1001I 10.56.43 RECOUP INDEX DISPLAY                                 |
|        NAME - INDEX001                                                         |
|        PID  - 0002FC16 AF798883 E3D7C6C4 C2404040                              |
|               18036D0B 18036D0C 00000000 00000000                              |
|        DESC - PRIMARY_INDEX                                                    |
|        TYPE - HOMOGENEOUS    CONTROL - NONE                                    |
|        TOKEN - C1C3E3F0F0F14040  TYPE-PID DISPL-40                             |
|        TOKEN - C1C3E3F0F0F24040  TYPE-PID DISPL-6F                             |
|        END OF DISPLAY                                                          |
|        BROW1014I 10.56.43 RECOUP INDEX DISPLAY SUCCESSFUL                      |
|                                                                                |
+--------------------------------------------------------------------------------+

The names of all recoup indexes defined in a data store are shown in the following example.

+--------------------------------------------------------------------------------+
|User:   ZBROW RECOUP DISPLAY ALL                                                |
|System: BROW0602I 10.56.43 BROWSER QUALIFIED FOR DSNAME TPFDB                   |
|        BROW1001I 10.56.43 RECOUP INDEX DISPLAY                                 |
|          INDEX001                                                              |
|          INDEX002                                                              |
|          INDEX003                                                              |
|          INDEX004                                                              |
|          INDEX005                                                              |
|          IT00000                                                               |
|          IT00002                                                               |
|          IT00003                                                               |
|          IT00004                                                               |
|        END OF DISPLAY                                                          |
|        BROW1014I 10.56.43 RECOUP INDEX DISPLAY SUCCESSFUL                      |
+--------------------------------------------------------------------------------+

Recoup index INDEX001 is associated with the MYCOLLECT collection in the following example.

+--------------------------------------------------------------------------------+
|User:   ZBROW RECOUP LINK MYCOLLECT INDEX001                                    |
|                                                                                |
|System: BROW0602I 10.56.43 BROWSER QUALIFIED FOR DSNAME TESTX.DS                |
|        BROW1015I 10.56.43 RECOUP INDEX SUCCESSFULLY LINKED                     |
|                                                                                |
+--------------------------------------------------------------------------------+

The index entry corresponding to a key of TOKEN001 in recoup index INDEX001 is removed in the following example.

+--------------------------------------------------------------------------------+
|User:   ZBROW RECOUP REMOVE INDEX001 ETOK-TOKEN001                              |
|                                                                                |
|System: BROW0602I 10.56.43 BROWSER QUALIFIED FOR DSNAME TESTX.DS                |
|        BROW1016I 10.56.43 RECOUP INDEX ENTRY SUCCESSFULLY REMOVED              |
|                                                                                |
+--------------------------------------------------------------------------------+

The recoup index associated with the MYCOLLECT collection is disassociated with the collection in the following example.

+--------------------------------------------------------------------------------+
|User:   ZBROW RECOUP UNLINK MYCOLLECT                                           |
|                                                                                |
|System: BROW0602I 10.56.43 BROWSER QUALIFIED FOR DSNAME TESTX.DS                |
|        BROW1017I 10.56.43 RECOUP INDEX SUCCESSFULLY UNLINKED                   |
|                                                                                |
+--------------------------------------------------------------------------------+

Related Information