gtpa2m34Application Programming

VSAM Database Support

The TPF system implements VSAM (called VSAM database support) through TPF general data set (GDS) support. This VSAM database support provides read-only access to VSAM KSDSs by using a macro interface and general processing protocol that is loosely modeled after IBM VSAM.

The VSAM database space is managed by an integrated catalog facility (ICF) entry that is set up on an MVS system at the time the VSAM data cluster is created. The catalog entry contains the physical characteristics of the cluster: the name of the data set, the extents, the number of volumes, the physical block size, the control interval size, and so on. In addition, the catalog entry contains the logical layout of the data and the type of organization. Because this information is required by the TPF system to decode VSAM requests, it is extracted from the MVS system by using the IDCAMS LISTCAT function (or other comparable function) and passed to the TPF system on the data set name. IDCAMS is an executable program in the MVS system that provides specialized VSAM support.

The actual management of space (that is, allocating data sets on DASD), multivolume control, populating disks with data, and performing index maintenance is performed by the MVS system. Each VSAM volume, therefore, is connected to the TPF system and MVS at the same time. Data is inserted into VSAM control intervals using the IDCAMS REPRO function on MVS; however, TPF applications cannot access a data set while it is being populated with data on the MVS system.

VSAM database support is grouped logically into four areas, as follows:

These areas are implemented in E-type programs called run-time routines that operate between application programs and the TPF system. Asynchronous control for I/O processing is not permitted; however, VSAM requests can be interleaved with application find and file requests to help database coexistence and migration.

Figure 35 identifies the major components that comprise the interface and shows the logical flow between the components to convert a sample flat file into a VSAM key-sequenced data cluster and move it online to the TPF system.

Figure 35. VSAM Database Logical Flow


Disk Mirroring

VSAM database support provides mirrored disks as well as the ability to balance disk queues to provide a high level of data availability for TPF applications. With disk mirroring, a disk failure remains transparent to the application as long as the mirror disk can manage the request. For example, if a volume of an index or data space is taken offline either manually or by the TPF system, VSAM database support switches active read operations off the failed volume to the alternate volume on the mirror data cluster. In the same way, any read operations that occur after the disk failure are switched to the alternate disk. When the disk volume or cluster is brought online again, VSAM database support incorporates the disk or cluster into the configuration again and uses it immediately.

Disks can be added or removed from the configuration at any time by using the ZDSMG DM or MT command with the ALL parameter specified (for an entire cluster) or the VOLUME parameter specified (for an individual disk). Note that the index and data portions must be handled separately for a KSDS; therefore, you must enter the ZDSMG command twice, each time with a separate data definition (DD) name reference.

Each VSAM cluster must be identical to the other (except for the volume serial numbers (VOLSERs)) for disk mirroring to work. An MVS database administrator must run two jobs to create two VSAM clusters on different sets of disk volumes to set up a mirrored VSAM group. The MVS DEFINE command in the VSAM CREATE function is identical for both clusters except for the VOLSERs, which must change. This ensures that VSAM arranges the files in exactly the same way on both sets of disks. Each disk then has a unique MVS data set name.

Data Set Naming Convention

MVS catalog information is passed to the TPF system by appending it to the end of the data set name. Each MVS VSAM data set name of each portion of the VSAM cluster must end with the following:

.R <SS RBA> <High Level Block Number> .P <Key Position> L <Key Length> <.INDEX | .DATA>

SS RBA
Specifies the hexadecimal value of the sequence set RBA that is displayed in the LISTCAT output on the MVS system, divided by the control interval (CI) size. SS RBA is the pointer to the start of the sequence set CI blocks in the index set. For example, an SS RBA of 1 474 560 and a CI size of 4096 would result in X'168'.

High-Level Block Number
Specifies the 4-digit hexadecimal value of 1 plus the value of the high-level RBA that is displayed in a LISTCAT output on the MVS system, divided by the CI size. The high-level RBA is the pointer to the first index block in the highest- level index; that is, the point where all index lookups begin. For example, a high-level RBA of 8192 and a CI size of 4096 would have a block number of X'0003' 1+(8192/4096).

Key Position and Key Length
Specifies the hexadecimal offset to the key in the record, counting from 0. For example, a key of 22 bytes at byte offset 33 would result in .P21L16. These are the values specified in the KEYS parameter on the define cluster command; they are also the RKP and KEYLEN values that are displayed in LISTCAT on the MVS system.

INDEX | DATA
For a KSDS, VSAM (on MVS) automatically appends the names INDEX or DATA to the data set name during the VSAM create process to identify the index and data spaces of the cluster. For a cluster with a high-level RBA of 1 474 560, CI size of 4096, and key length of 22 bytes at offset 33 in each record, the data set name for the index portion of the cluster would be .R1680003.P21L16.INDEX. The data portion of the cluster would be .R1680003.P21L16.DATA.

Referring to Data Definition (DD) Names and Clusters

The TPF system provides several levels of references for data sets to maintain a high level of flexibility in managing files. By convention, applications refer to the VSAM database by using an application DD name, while the TPF system refers to the VSAM database by using a system DD name, which is derived for the application DD name. The TPF system can also refer to a disk by its cluster data set name and volume sequence number. See Constructing the VSAM Cluster Data Set Names for more information about constructing cluster data set names.

Each key-sequenced data set cluster is then defined by two unique DD names: one to identify the index space and one to identify the data space. Therefore, there are two unique data set names. In a mirrored cluster, there are four unique DD names and four unique data set names. A cluster group refers to the entire group of VSAM clusters that comprise a prime and mirror set.

DD names are created by first assigning an 8-byte name to an application to identify the cluster group (prime and mirror) (for example, FREQFLYR). The application uses this name in the ACB to refer to the cluster group. The TPF system refers to this DD name (using the ZDSMG command) by appending INPR, INMI, DAPR, or DAMI when referring to discrete parts of the cluster group. Consider the following example.

FREQFLYRINPR
Specifies the prime index portion of the cluster group.

FREQFLYRDAPR
Specifies the prime data portion of the cluster group.

FREQFLYRINMI
Specifies the mirror index, a copy of INPR.

FREQFLYRDAMI
Specifies the mirror data, a copy of DAPR.

The disk volumes in a DD name can also be addressed by the ZDMSG command with the VOL parameter specified.

Table 18 shows how a cluster referencing scheme might look. Application programmers use the application DD name when writing programs. A TPF operator uses the TPF system DD name to mount and remove files, while an MVS database administrator uses the MVS data set names to create and copy VSAM data sets.

Table 18. VSAM Database Support Cluster Reference

Application DD Name TPF System DD Name MVS Data Set Name
CHECKING CHECKINGINPR TPF.CHECKING.PRIME.R1680003.P21L16.INDEX
CHECKING CHECKINGDAPR TPF.CHECKING.PRIME.R1680003.P21L16.DATA
CHECKING CHECKINGINMI TPF.CHECKING.MIRROR.R1680003.P21L16.INDEX
CHECKING CHECKINGDAMI TPF.CHECKING.MIRROR.R1680003.P21L16.DATA

I/O Interface and VFA

The I/O management scheme used by the interface uses several optimization options that include virtual file access (VFA) buffering for index blocks (CIs). All index blocks in the index data set are VFA candidates. Each time an index block is retrieved, the run-time program tries to get it from VFA. If it is not present, it is retrieved from disk and placed in VFA for later retrieval. The number of index blocks in the IMBED type of data cluster is typically small.

The run-time program uses the standard TPF macro interface to read data blocks and perform I/O. The GDSNC and FINWC macros are used to read index set, sequence set, and data set control intervals. Each call converts the index set vertical pointer to a relative record number that the TPF system can convert into a file address reference format (FARF) type of address.

For a typical direct key retrieval for an IMBED type of data cluster, this requires the TPF system to perform two VFA reads of the index set, followed by two disk I/Os: one to read the sequence set CI and one to read the data record CI. No head movement is required between the two physical I/Os because the sequence set CI is at the same seek cylinder address as the data record CI.

Scanning, or sequential processing, is highly optimized because the run-time program takes full advantage of the sequence set to data record relationship, including scanning within a CI that was already retrieved and then scanning the entire cylinder to read all the records in a CI. To take full advantage of this, an application may spawn many entry control blocks (ECBs) to consume an entire VSAM file in parallel.

VSAM Database Constraints

VSAM database support for the TPF system is read-only. This means that while a VSAM data set is being actively referenced by TPF applications, the MVS system will not try to modify the data set, and the TPF system will not write to or modify the VSAM data set in any way. The MVS system, however, can modify the database when the data cluster is logically or physically disconnected from the TPF application that is referring to it. Access to VSAM data sets between the MVS and TPF systems, therefore, is mutually exclusive.

The following VSAM database macros support this read-only interface:

Table 19. VSAM Database Support Macros

VSAM Database Macro Description MVS System Equivalent Macro
VOPNC Use this macro to connect to a VSAM database. OPEN
VGETC Use this macro to read a record. GET
VCHKC Use this macro to wait for a request to end. CHECK
VPNTC Use this macro to position for access. POINT
VENDC Use this macro to end a request. ENDREQ
VCLSC Use this macro to disconnect from a database. CLOSE
VGENC Use this macro to generate a control block. GENCB
VSHOC Use this macro to access a control block. SHOWCB

Because VSAM database support for the TPF system is read-only, the MACRF and OPTCD parameters of the VGENC macro, which specify processing options and type of access, are restricted to the read-only set and exclude parameters that would change the database. The locate (LOC) and move (MVE) parameters are supported by VSAM database support for retrieving data. The VGENC macro is also used to generate ACBs and RPLs. The maximum number of ACBs that can be specified per ECB is 16; the maximum number of RPLs per ECB that can be specified is 32.

Three types of access to a VSAM data set were previously mentioned in describing VSAM:

The ICF catalog structure on the MVS system is the only catalog structure that is supported. The CI must be set to the maximum TPF block size of 4096 bytes and the physical block size on a track must be equal to the CI size. Alternate indexes and the specialized linear data set are not supported.

The prime and backup copies of each data cluster must be physical and logical mirror images of each other for applications that require backup. Each disk must be a physical mirror image of its alternate.

You must specify either the IMBED or the NOIMBED option for the DEFINE command when creating the VSAM database on the MVS system. The maximum size of a CI is 4096 bytes; spanning of CIs is not supported. The maximum record size, therefore, is 4089 bytes after taking into account the 4-byte control interval definition field (CIDF) at the end of the block and a 3-byte record definition field (RDF) field that follows it. The CIDF describes the free space, if there is any, in the control interval. The RDF describes the characteristics of each record.

The index component cannot span multiple volumes and can only be on one extent.

The following options are restricted for the DEFINE CLUSTER command on the MVS system when you are defining VSAM data sets that will be used by the TPF system:

VSAM Database Considerations

VSAM database support is compatible with certain levels of data facility product (DFP) VSAM, MVS/ESA, and TPF; see TPF Migration Guide: Program Update Tapes for more information about what levels are supported. VSAM database support coexists with all other TPF database support.

The VSHOC macro is a special version of the VSAM SHOWCB macro; this macro returns the first ACB and RPL in sequence. Subsequent control blocks of the same type are accessed by using the chain word in each block.

VSAM blocks do not use the format flag; therefore, you must review code that depends on format flags. The area that was occupied by the format flag is used to hold part of the CDF field at the end of the block.

Storage allocation for control blocks is managed by TPF VSAM database database support or by the application (by coding the WORKAREA parameter on the GENCB macro). Storage allocation for I/O buffers is managed exclusively by VSAM database support by using the GETCC macro. As a result, the buffer parameters that are usually coded on the GENCB macro in the MVS system are not required in the TPF system. Instead, a new parameter, LEVEL=Dx, is coded in generating the RPL to specify the TPF data level and core block reference word (CBRW) to use for I/O operations.

For performance reasons, all I/O requests in VSAM database support are synchronous, which means that the OPTCD=ASY parameter is not supported for the VGENC macro. Therefore, all VGETC, VENDC, and VPNTC requests do not need the corresponding VCHKC macro to get the results of the macro operation.

VSAM database support does not include the EXLST macro to generate an EXIT list.

VSAM Database Support with Other Utilities

VSAM data sets are mounted to the TPF system as 4-KB general data sets (GDSs). These data sets are managed by the TPF control program as GDSs and are mounted and removed using GDS commands and macros. By using the GDS interface, VSAM data sets inherit all of the reliability, availability, and serviceability characteristics that are provided by the GDS packaging, including I/O error recovery, environmental error record editing and printing program (EREP) analysis, and sustained connections across TPF system restarts. VSAM database support additionally enhances data availability through the use of disk mirroring, as mentioned previously.

TPF data collection tools, which measure I/O performance, storage use, and response times, are available with VSAM database support to use in capacity planning and performance measurement.

To extract the required ICF catalog information for the TPF system, a COBOL utility is available, on request, that demonstrates how to derive the catalog information that is needed by the TPF system as part of the data set name. A sample restructured extended executor language (REXX) program is provided in Constructing the VSAM Cluster Data Set Names, which can be used to construct the VSAM database support cluster data set names to be mounted to the TPF system.

VSAM Database Support Request Flow Control

An ECB communicates with VSAM database support through a set of macros to manage a VSAM database. The flow of control begins by running the VGENC macro to create an access method control block (ACB). Now that the data cluster to be opened is defined, as well as the processing options that are required, the ECB connects to the VSAM database by using the VOPNC macro. This prepares the data set for access. For VOPNC requests, the run-time routines internally issue the TPF GDSNC macro to connect the ECB to the database and save the output from that process.

Note:
The application DD name is used to derive the TPF system DD name that is used when the cluster data set components are mounted to the TPF system. In this way, VSAM database support is able to make the connection to the prime and mirror cluster data sets.

Using an RPL, the ECB then manages records in the database by using the VGETC and VPNTC macros. Use the VCHKC macro to get the results of requests and the VENDC macro to end requests. When ECB processing is completed, it issues a VCLSC macro to break the connection. This flow of control is similar to a typical TPF database access where an ECB hashes a key to a fixed record slot, calls the FACS program to get the disk address of the slot followed by a find and wait to get the data block, and finally issues the RELCC macro to release it. The difference between that flow control and VSAM database support is that VSAM database support provides functions such as indexing and hashing in addition to the ability to locate specific records in blocks rather than having to write code for it. VSAM database support also performs complex, hierarchical data searches and full database scans. Figure 36 shows the interaction of VSAM macros and control blocks and how they are used during request processing.

Figure 36. VSAM Database Support Request Flow Example


As you see in Figure 36, data requests to VSAM database support are asynchronous and permit the interleaving of native I/O requests with VSAM database support requests. A VSAM database I/O request comprises the TPF GDSNC macro and a FINWC macro call. The RBA for input to the GDSNC macro is obtained inside run-time processing by searching the index set and the sequence set. The GDSNC macro converts the RBA to a TPF disk address and then issues the FINWC macro to read the data to the ECB data level (Dx) that was specified in the RPL.

Applications issue the VCHKC macro to get the results of an I/O request; the completion status of the request is placed in register 15. Detailed error information is placed in the feedback field of the RPL. The VCHKC macro causes the following to occur:

Because all I/O is synchronous, the VCHKC macro is not required to interrogate the status of the VGETC request. The same output is provided on a VGETC request as for a VCHKC request. The VCHKC macro is available for compatibility.

VSAM database support has no requirement for record locking. However, because a VSAM VGETC macro request results in a TPF FINWC macro request, the existing TPF page-level record hold feature may easily be added if locking is required at any point. Currently, all data records are shared by all ECBs. VSAM data sets are attached to the TPF system by using the ZDSMG command and the standard TPF mount data set procedure in the GDS.

Sample VSAM Database Support Program

Following is a sample program to show the VSAM database support macros.

     BEGIN NAME=xxxx,VERSION=41
     VSACB ,                                    ACB DSECT definition
     VSRPL ,                                    RPL DSECT definition
     VGENC        BLK=ACB,AM=VSAM,DDNAME=CUSTOMER,
                  MACRF=(KEY,DIR,IN)
     ST           R1,EBX000                     Save ACB address
 
     VGENC        BLK=RPL,AM=VSAM,ACB=EBX000,LEVEL=D2,AREA=EBX008,
                  ARG=EBW000, OPTCD=(LOC,SYN)
     IF CC0
     THEN,
            L     R1,EBX000                     Pick up ACB address
            VOPNC (R1)
            IF CC0                              If VOPNC ok
            THEN,
 
                  MVC       EBW000,=C'00'       Set up Arg fields.
                  MVC       EBW002,=C'12345678' Account Number.
                  VGETC     RPL=EBX008
                  IF CC0,
 
                  ... A sample TPF native I/O call is intermingled here.
 
                  MVC       CE1FA3,=C'PR'       Record ID.
                  MVC       CE1FM3(4),FARF3 Address
                  FINWC     D3,ERRLAB           Find a TPF record.
 
                  ... Now back to the VSAM call
                  VCHKC     RPL=EBX008
                  IF CC0,
                  THEN,
                        CE1CR2 now contains the VSAM record.
                        The data record in CE1CR2 is pointed to by EBX008.
                        CE1CR3 contains the TPF record.
                  ENDIF,
 
ERRLAB            DS    0H
                  VENDC RPL=EBX008
                  L     R1,EBX000
                  VCLSC EBX000
 
            ENDIF ,
     ENDIF ,

Managing Buffers

The application interface to VSAM database support is pointer-driven using the ACB and RPL control structures. The ACB is used as context to control the interaction between the ECB and VSAM database support. It is created by the VGENC macro and is used for all interactions. The ACB is released through the VCLSC macro. The RPL is used to control individual VSAM database data requests. It is also used to hold parameters and to provide the status of requests and responses. The VENDC macro is used to release the RPL.

For a typical VGETC macro request, the application sets pointers in the RPL to the type of request to be performed in addition to any special processing options. The result of the VGETC macro is returned in the RPL by the run-time routines. Get and release macros (GETCC and RELCC), with the DETAC macro, acquire and release storage for ACBs and RPLs. For multiple, concurrent requests in a single ECB, the application specifies one unique RPL for each request. This is done by coding one VGENC macro for each request. VSAM database support also uses TPF working storage for output data buffers. Additionally, VFA is used to store and retrieve index CIs.

When an application calls its first VGENC macro to generate a VSAM control block, VSAM database support gets a 4-KB block and detaches it from the data level (DF). The block is used to hold a context data block and subsequent interface control blocks, ACBs, and RPLs. Space is optimized in the buffer by stacking blocks from the bottom up. Interface blocks are allocated in the buffer through VGENC macro calls; they are unallocated by using VENDC macro calls. The 4-KB block is released only when the ECB exits. This optimizes block management because subsequent calls of VSAM by the same ECB do not need to allocate the context block.

Sequence set CIs are the lowest-level index blocks; they reside on the same cylinder as the data records for performance reasons. These CI blocks are retrieved and detached on the data level specified in the RPL. They are kept for subsequent fast scan requests and then are released by using the VENDC macro. For a single direct key retrieval, the data level contains a private copy of the sequence set block (detached) and a private copy of the VSAM data record block (also detached). Applications that need to economize on storage would use the LOCate mode retrieval method to get access to a data record rather than MOVE mode, which moves the data record out of the VSAM data buffer into an application area. The VSAM data record block remains detached from that data level until a VENDC macro is issued for the RPL that owns the request. The run-time interface requires 12 KB of space for a typical direct key retrieval.

Reusing Data Levels

Applications can reuse the data level in the ECB that is used to perform VSAM I/O operations (as indicated in the RPL) after a VENDC macro is issued for the VSAM request that was using the data level. This avoids the necessity to repeatedly call the VOPNC macro in centralized application programming interface (API) routines. The rule for reusing a data level and core block is that the level is freed by the application before calling the first VGETC macro and that a VENDC macro request must be called before an application can reuse the level. The VENDC macro releases any positioning and context for the current VSAM database request.

Return Codes

Register 15 (R15) contains the return code for VSAM database support macro processing; the condition code is set on return from each macro call. The interface for VSAM database support return codes is the same as for the MVS system, as follows:

For performance reasons, VSAM database support provides these codes immediately following macro processing; you do not need to enter the VSHOC macro call. (This is different from the MVS system, where you would need to enter the SHOWCB macro call.) When a record is not found, the return code is set to not found instead of showing successful or null status. VSAM database does not support options for error message text and codes.

Table 20. VSAM Database Support Return Codes

Return Code Meaning
0 Macro processing was successful.
1 Request was not valid.
2 Block type was not valid.
3 Parameter was not valid.
8 VSAM database support internal work area is full.
9 VSAM database support internal work area is too small.
14 Combination of options is not valid.
15 Address not on a fullword boundary.
16 End of file.
17 Record not found.
18 Duplicate previous operation.
32 VSAM database support data set name is not valid.
33 VSAM database support data set open error.
34 VSAM database support data set error during read.
35 VSAM database support data set FINWC macro I/O error.
44 Short length record on MVE.
128 Mask for retry-type errors.
129 VSAM database support index error.

Error Recovery

Because VSAM database support consists primarily of E-type programs that run between application programs and the TPF control program (CP), all error recovery functions that are provided by the CP are available to applications using VSAM database support. These include DASD single-image I/O error handling, recovery from an abnormal ending of a program, exit processing, and system recovery.

Constructing the VSAM Cluster Data Set Names

The following is a sample REXX program that you can use to construct the VSAM database support cluster data set names to be mounted to the TPF system. The TPF system requires that a subset of the catalog information be passed to it in the data set name to be able to navigate the VSAM cluster in satisfying requests for data records made by TPF VSAM applications.

 /* REXX */
 /********************************************************************/
 /*                                                                  */
 /*       NAME: VSAMTPFX (SAMPLE CSI PROGRAM BASED ON IGGCSIRX)      */
 /*                                                                  */
 /*DESCRIPTION: THIS REXX EXEC CAN BE USED TO CALL THE CATALOG       */
 /*             SEARCH INTERFACE AND GENERATE THE NECESSARY          */
 /*             DATA SET NAME SUFFIX THAT CAN BE APPENDED TO THE     */
 /*             CLUSTER/COMPONENTS IN ORDER TO COMMUNICATE CATALOG   */
 /*             INFORMATION TO THE TPF/VSAM SUPPORT WHEN MOUNTING    */
 /*             THE CLUSTER TO TPF.                                  */
 /*                                                                  */
 /*      INPUT: FILTER KEY (KSDS CLUSTER NAME)                       */
 /*             IN THE FORM *.DDNAME.*                               */
 /*                 WHERE DDNAME IS 8 CHARACTERS IN LENGTH AND       */
 /*                 CAN REPRESENT THE FIRST 8 CHARACTERS OF THE 12   */
 /*                 CHARACTER SYSTEM DDNAMES USED BY TPF TO REFERENCE*/
 /*                 THE DATASET COMPONENTS OF THE PRIME/MIRROR       */
 /*                 CLUSTERS MOUNTED TO TPF.                         */
 /*                                                                  */
 /*     OUTPUT: ALTER DATA SET NAME INFORMATION                      */
 /*             CONSISTS OF THE NEW DATA SET NAME APPENDED WITH      */
 /*             ENCODED CATALOG INFORMATION DERIVED FROM THE INPUT   */
 /*             DATA SET NAME CLUSTER CATALOG ENTRY.                 */
 /*                                                                  */
 /* EXAMPLE:                                                         */
 /*                                                                  */
 /*    CLUSTER NAME     => *.CHECKING                                */
 /*    INDEX COMPONENT  => *.CHECKING.INDEX                          */
 /*    DATA  COMPONENT  => *.CHECKING.DATA                           */
 /*                                                                  */
 /*                              (values in hexadecimal)             */
 /*                                                                  */
 /*    CATALOG LIST ENCODING =>  R 168 0001 . P22 L16                */
 /*                              |   |    |     |   |                */
 /*                       marker |   |    |     |   | Key length     */
 /*                                  |    |     | Key Position       */
 /*                       SS RBA/4096|    |                          */
 /*                                       | 1+(HIGH LEVEL RBA/4096)  */
 /*                                                                  */
 /*                                                                  */
 /*                                                                  */
 /*    NEW CLUSTER NAME => *.CHECKING.R1680001.P22L16                */
 /*    INDEX COMPONENT  => *.CHECKING.R1680001.P22L16.INDEX          */
 /*    DATA  COMPONENT  => *.CHECKING.R1680001.P22L16.DATA           */
 /*                                                                  */
 /* TPF MOUNT INFORMATION:                                           */
 /*                                                                  */
 /* ZDSMG MT {SDA} CHECKINGINPR DSN-*.CHECKING.R1680001.P22L16.INDEX */
 /* ZDSMG MT {SDA} CHECKINGDAPR DSN-*.CHECKING.R1680001.P22L16.DATA  */
 /*                                                                  */
 /*                                                                  */
 /********************************************************************/
   SAY 'ENTER VSAM CLUSTER NAME'      /* ASK FOR FILTER KEY          */
   PULL KEY                           /* GET FILTER KEY              */
 /********************************************************************/
 /*                                                                  */
 /*  INITIALIZE THE PARM LIST                                        */
 /*                                                                  */
 /********************************************************************/
MODRSNRC = SUBSTR(' ',1,4)          /*   CLEAR MODULE/RETURN/REASON  */
CSIFILTK = SUBSTR(KEY,1,44)         /*   MOVE FILTER KEY INTO LIST   */
CSICATNM = SUBSTR(' ',1,44)         /*   CLEAR CATALOG NAME          */
CSIRESNM = SUBSTR(' ',1,44)         /*   CLEAR RESUME NAME           */
CSIDTYPS = SUBSTR(' ',1,16)         /*   CLEAR ENTRY TYPES           */
CSICLDI  = SUBSTR('Y',1,1)          /*   INDICATE DATA AND INDEX     */
CSIRESUM = SUBSTR(' ',1,1)          /*   CLEAR RESUME FLAG           */
CSIS1CAT = SUBSTR(' ',1,1)          /*   INDICATE SEARCH > 1 CATALOGS*/
CSIRESRV = SUBSTR(' ',1,1)          /*   CLEAR RESERVE CHARACTER     */
CSINUMEN = '0004'X                  /*   INIT NUMBER OF FIELDS       */
CSIFLD1    = SUBSTR('AMDKEY',1,8)              /* AMDKEY             */
CSIFLD1    = CSIFLD1 || SUBSTR('AMDCIREC',1,8) /* AMDCIREC           */
CSIFLD1    = CSIFLD1 || SUBSTR('HKRBA',1,8)    /* HKRBA              */
CSIFLD1    = CSIFLD1 || SUBSTR('HARBA',1,8)    /* HARBA              */
 /********************************************************************/
 /*                                                                  */
 /*  BUILD THE SELECTION CRITERIA FIELDS PART OF PARAMETER LIST      */
 /*                                                                  */
 /********************************************************************/
CSIOPTS  = CSICLDI || CSIRESUM || CSIS1CAT || CSIRESRV
CSIFIELD = CSIFILTK || CSICATNM || CSIRESNM || CSIDTYPS || CSIOPTS
CSIFIELD = CSIFIELD || CSINUMEN || CSIFLD1
 
 /********************************************************************/
 /*                                                                  */
 /*  INITIALIZE AND BUILD WORK AREA OUTPUT PART OF PARAMETER LIST    */
 /*                                                                  */
 /********************************************************************/
WORKLEN = 1024
DWORK = '00000400'X || COPIES('00'X,WORKLEN-4)
 
 /********************************************************************/
 /*                                                                  */
 /*  INITIALIZE WORK VARIABLES                                       */
 /*                                                                  */
 /********************************************************************/
RESUME = 'Y'
CATNAMET = SUBSTR(' ',1,44)
DNAMET = SUBSTR(' ',1,44)
 
 /********************************************************************/
 /*                                                                  */
 /*  SET UP LOOP FOR RESUME (IF A RESUME IS NECESSARY)               */
 /*                                                                  */
 /********************************************************************/
DO WHILE RESUME = 'Y'
 
 /********************************************************************/
 /*                                                                  */
 /*  ISSUE LINK TO CATALOG GENERIC FILTER INTERFACE                  */
 /*                                                                  */
 /********************************************************************/
 ADDRESS LINKPGM 'IGGCSI00  MODRSNRC  CSIFIELD  DWORK'
 
 RESUME = SUBSTR(CSIFIELD,150,1)    /* GET RESUME FLAG FOR NEXT LOOP */
 USEDLEN = C2D(SUBSTR(DWORK,9,4))   /* GET AMOUNT OF WORK AREA USED  */
 POS1=15                            /* STARTING POSITION             */
 
 /********************************************************************/
 /*                                                                  */
 /*  PROCESS DATA RETURNED IN WORK AREA                              */
 /*                                                                  */
 /********************************************************************/
 DO WHILE POS1 < USEDLEN            /* DO UNTIL ALL DATA IS PROCESSED*/
   IF SUBSTR(DWORK,POS1+1,1) = '0'  /* IF CATALOG, PRINT CATALOG HEAD*/
    THEN DO
         CATNAME=SUBSTR(DWORK,POS1+2,44)
         IF CATNAME ^= CATNAMET THEN /* IF RESUME NAME MAY ALREADY BE*/
          DO                         /*    PRINTED                   */
           SAY 'CATALOG ' CATNAME    /* IF NOT, PRINT IT             */
           SAY ' '
           CATNAMET = CATNAME
          END
         POS1 = POS1 + 50
         END
 
   DNAME = SUBSTR(DWORK,POS1+2,44)  /* GET ENTRY NAME                */
 
 /********************************************************************/
 /*                                                                  */
 /*  ASSIGN ENTRY TYPE NAME                                          */
 /*                                                                  */
 /********************************************************************/
   IF SUBSTR(DWORK,POS1+1,1) = 'C' THEN DTYPE = 'CLUSTER '
    ELSE
      IF SUBSTR(DWORK,POS1+1,1) = 'D' THEN DTYPE = 'DATA    '
     ELSE
      IF SUBSTR(DWORK,POS1+1,1) = 'I' THEN DTYPE = 'INDEX   '
     ELSE
      IF SUBSTR(DWORK,POS1+1,1) = 'A' THEN DTYPE = 'NONVSAM '
     ELSE
      IF SUBSTR(DWORK,POS1+1,1) = 'H' THEN DTYPE = 'GDS     '
     ELSE
      IF SUBSTR(DWORK,POS1+1,1) = 'B' THEN DTYPE = 'GDG     '
     ELSE
      IF SUBSTR(DWORK,POS1+1,1) = 'R' THEN DTYPE = 'PATH    '
     ELSE
      IF SUBSTR(DWORK,POS1+1,1) = 'G' THEN DTYPE = 'AIX     '
     ELSE
      IF SUBSTR(DWORK,POS1+1,1) = 'X' THEN DTYPE = 'ALIAS   '
     ELSE
      IF SUBSTR(DWORK,POS1+1,1) = 'U' THEN DTYPE = 'UCAT    '
     ELSE
      DTYPE = '        '
 /********************************************************************/
 /*                                                                  */
 /*  HAVE NAME AND TYPE, IF INDEX ENTRY CALCULATE MAGIC PARAMETERS   */
 /*                                                                  */
 /********************************************************************/
    POS1 = POS1 + 46
    IF DTYPE = 'INDEX'
     THEN DO
 
       POSLEN1 = POS1    + 4
       POSLEN2 = POSLEN1 + 2
       POSLEN3 = POSLEN2 + 2
       POSLEN4 = POSLEN3 + 2
 
       POSDAT1 = POSLEN4 + 2
       POSDAT2 = POSDAT1 + C2D(SUBSTR(DWORK,POSLEN1,2))
       POSDAT3 = POSDAT2 + C2D(SUBSTR(DWORK,POSLEN2,2))
       POSDAT4 = POSDAT3 + C2D(SUBSTR(DWORK,POSLEN3,2))
 
       SAY "KEY-POS      => X'"C2X(SUBSTR(DWORK,POSDAT1,2))"'"
       KEYPOS            =     C2X(SUBSTR(DWORK,POSDAT1,2))
 
       SAY "KEY-LEN      => X'"C2X(SUBSTR(DWORK,POSDAT1+2,2))"'"
       KEYLEN =                C2X(SUBSTR(DWORK,POSDAT1+2,2))
       SAY "CI-SIZE      => X'"C2X(SUBSTR(DWORK,POSDAT2,4))"'"
       CISIZE            =     C2D(SUBSTR(DWORK,POSDAT2,4))
 
       SAY "HI-LEVEL-RBA => X'"C2X(SUBSTR(DWORK,POSDAT3,4))"'"
       HLRBA             =     C2D(SUBSTR(DWORK,POSDAT3,4))
 
       SAY "SEQ-SET-RBA  => X'"C2X(SUBSTR(DWORK,POSDAT4,4))"'"
       SSRBA             =     C2D(SUBSTR(DWORK,POSDAT4,4))
 
       MAGIC =          'R' || D2X((SSRBA/CISIZE),3)
       MAGIC = MAGIC || D2X(((HLRBA/CISIZE)+1),4) || '.'
       MAGIC = MAGIC || 'P' || RIGHT(KEYPOS,2)
       MAGIC = MAGIC || 'L' || RIGHT(KEYLEN,2)
 
       SAY ''
       SAY 'INPUT CLUSTER NAME         <= ' KEY
 
       SAY ''
       SAY "CATALOG SUFFIX STRING      == '"MAGIC"'"
 
       ALTERDSN = TRANSLATE(KEY,' ','.')
       IF WORDS(ALTERDSN) >= '2'
        THEN DO
 
         NEWDSN = SUBWORD(ALTERDSN,1,1) || '.'
 
         DDNAME = SUBWORD(ALTERDSN,2,1)
         IF LENGTH(DDNAME) <8
         THEN DDNAME = DDNAME || '*'
 
         NEWDSN = NEWDSN || DDNAME || '.'
         NEWDSN = NEWDSN || MAGIC
 
         SAY ''
         SAY "NEW CLUSTER NAME           => '"NEWDSN"'"
         SAY "NEW DATA  COMPONENT NAME   => '"NEWDSN || .DATA"'"
         SAY "NEW INDEX COMPONENT NAME   => '"NEWDSN || .INDEX"'"
         SAY ''
 
         DAPRDDN = DDNAME || ' || DAPR'
         INPRDDN = DDNAME || ' || INPR'
         DAMIDDN = DDNAME || ' || DAMI'
         INMIDDN = DDNAME || ' || INMI'
 
         SAY 'TPF (SYSTEM) DDNAMES:'
         SAY ''
         SAY "  DATA  COMPONENT (PRIME)  => '"DAPRDDN"'"
         SAY "  INDEX COMPONENT (PRIME)  => '"INPRDDN"'"
         SAY ''
         SAY "  DATA  COMPONENT (MIRROR) => '"DAMIDDN"'"
         SAY "  INDEX COMPONENT (MIRROR) => '"INMIDDN"'"
         SAY ''
 
         SAY 'TPF (APPLICATION) DDNAME:'
         SAY ''
         SAY "  '"DDNAME"'"
 
         IF POS("*",DDNAME) \= 0
         THEN DO
           SAY ''
           SAY '* = MUST BE 8 CHARACTERS IN LENGTH FOR VSAM/TPF USE'
         END
     END
   END
 
 /********************************************************************/
 /*                                                                  */
 /*   GET POSITION OF NEXT ENTRY                                     */
 /*                                                                  */
 /********************************************************************/
    POS1 = POS1 + C2D(SUBSTR(DWORK,POS1,2))
  END
END
/* END  OF PROGRAM */