gtpm2m20Migration Guide: Program Update Tapes

Virtual Storage Access Method (VSAM) Database Support (APAR PJ26150)

The following section discusses the migration considerations for VSAM database support.

Prerequisite APARs

See the APEDIT for APAR PJ26150 for information about prerequisite APARs.

Functional Overview

VSAM database support for the TPF 4.1 system permits you to access a VSAM database from an IBM multiple virtual storage (MVS) environment in read-only format using TPF general data set (GDS) support. The most important benefit this offers is the ability for TPF applications to access VSAM data sets. Additionally, VSAM database support provides fast storage by retaining index records in virtual file access (VFA) and providing a mechanism for duplicate GDS volume access by mirroring a VSAM data set cluster. Application access is provided through a VSAM application programming interface (API) model that is similar to what is provided to applications in an MVS environment.

To retrieve a VSAM record in the TPF 4.1 system, the protocol for an entry control block (ECB) is as follows:

  1. Use the VGENC macro to create an access method control block (ACB) that describes the name of the data set.
  2. Use the VGENC macro to create a request parameter list (RPL) that describes the type of processing options, the location of the key that will be used to locate a record, the data level to use for input/output (I/O), and pointers to data attributes.
  3. Open the data set to assign either the prime or mirror VSAM cluster to the ECB.
  4. Use the VGETC macro to read the record. (This causes VSAM database support to issue the GDSNC and FINWC macros.)
  5. Use the VCHKC macro to wait for VGETC macro processing to be completed.
  6. Use the VENDC macro to end the request and free the RPL.
  7. Use the VCLSC macro to free the ACB and its associated RPLs and end the dialog.

Architecture

VSAM database support for the TPF 4.1 system recognizes only the VSAM key-sequenced data set (KSDS) structure. A KSDS is a type of VSAM data set in which logical records of varying length are stored in ascending sequence by a field called a key. A KSDS has the following two data set components:

Together, the data and index data sets comprise a VSAM cluster.

The TPF 4.1 system provides several levels of referencing for data sets. By convention, applications refer to a VSAM database by using an application data definition (DD) name, while the TPF 4.1 system uses a system DD name. The TPF 4.1 system can also refer to a single disk by its cluster data set name and volume sequence number.

Each KSDS cluster is then defined by two unique TPF DD names:

For this reason, there are two unique data set names. For a mirrored cluster, four unique DD names (and therefore four unique data set names) exist. A cluster group refers to the group of VSAM clusters that comprise a prime and mirror set. See TPF Application Programming for more information about how DD names are created and used.

Applications access VSAM data by using TPF macros such as VGENC and QGDSQ. See TPF General Macros and TPF System Macros for more information about these macros.

VSAM database space is managed by an intersystem communications function (ICF) catalog entry that is set in the MVS system when the VSAM cluster is created. The catalog entry contains the physical characteristics of the cluster such as: the name of the data set, the number of volumes, the control interval size, and so on. In addition, the catalog entry contains the logical layout of the data and the type of organization. The TPF 4.1 system requires a subset of the catalog information to navigate the VSAM database. As such, the TPF 4.1 system expects this information to be provided in the data set name that is mounted to the TPF 4.1 system. This is done in the MVS environment through the IDCAMS REPRO function, which renames the cluster data set components when preparing the cluster for use by the TPF 4.1 system. See DFSMS/MVS Version 1 Release 2 Access Method Services for VSAM Catalogs for more information about the IDCAMS REPRO function.

Note:
A COBOL utility is available, on request, that demonstrates how to derive the catalog information that is needed by the TPF 4.1 system as part of the data set name.

The MVS system then actually manages the VSAM database space, which includes performing tasks such as allocating data sets on DASD, multivolume control, populating disks with data, and index maintenance. This means that each VSAM volume is connected to both the MVS and TPF 4.1 systems. However, TPF applications cannot access a VSAM data set while it is being populated with data on the MVS system.

Operating Environment Requirements and Planning Information

To ensure that your TPF 4.1 system performs correctly with VSAM database support, you must establish the required operating environment. The following section describes hardware and software requirements specific to VSAM database support.

Operating Environment Requirements and Planning Information provides information about the minimum system configuration requirements that are necessary to operate the TPF 4.1 system. You may find it helpful to review that chapter along with the following information.

Hardware

There are no hardware requirements.

Software (Programming Requirements)

VSAM database support requires MVS/DFP Version 3 Release 3 or higher releases or MVS/ESA Version 4.2 or higher releases.

Interface Changes

The following section summarizes interface changes.

C/C++ Language

The following section summarizes C/C++ language changes. This information is presented in alphabetic order by the type of C/C++ language information. See the TPF C/C++ Language Support User's Guide and TPF Application Programming for more information about the C/C++ language.

Build Scripts

There are no changes.

Dynamic Load Module (DLM) Stubs

There are no changes.

General Use C/C++ Language Header Files

Table 607 summarizes the general use C/C++ language header file changes. This information is presented in alphabetic order by the name of the general use C/C++ language header file.

General use means these header files are available for your use.

Table 607. Changes to General Use C/C++ Language Header Files for VSAM Database Support

C/C++ Language Header File New, Changed, or No Longer Supported? Do You Need to Recompile Segments?
c$eb0eb.h Changed Yes
i$ecb3.h Changed Yes

Implementation-Specific C/C++ Language Header Files (IBM Use Only)

There are no changes.

Library Interface Scripts

There are no changes.

Library Members (Object Files)

There are no changes.

Link-Edited Modules

There are no changes.

Members (Object Files)

There are no changes.

Object Code Only (OCO) Stubs

There are no changes.

Configuration Constant (CONKC) Tags

There are no changes.

Control Program Interface (CINFC) Tags

There are no changes.

Copy Members

Table 608 summarizes the copy member changes. This information is presented in alphabetic order by the name of the copy member.

Table 608. Changes to Copy Members for VSAM Database Support

Copy Member Type CSECT Where Copy Member Is Located DLM Where CSECT Is Located New, Changed, or No Longer Supported? Description of Change
CCEB Control Program CCENBK Not Applicable Changed Updated to clear VSAM-related fields in the ECB exit processing.
CEFJ Control Program CCFADC Not Applicable Changed Updated to turn on the GDS attribute in the record ID attribute table (RIAT) for a GDS VSAM request.
CEFK Control Program CCFADC Not Applicable Changed Updated to permit the LOC parameter option of the GDSCC macro to be issued from any I-stream.
CEFL Control Program CCFADC Not Applicable Changed Updated so that the format flag is not set in the last byte of a 4-KB record read for VSAM ECBs.
CVF3 Control Program CCVFAC Not Applicable Changed Updated to permit virtual file access (VFA) caching of VSAM index records.

Fixed File Records

There are no changes.

Macros

The following section summarizes the macro changes. This information is presented in alphabetic order by the type of macro.

Advanced Program-to-Program Communications (APPC) Macros

There are no changes.

Communication Macros and Statements

There are no changes.

Data Macros

Table 609 summarizes the data macro changes. This information is presented in alphabetic order by the name of the data macro.

Table 609. Changes to Data Macros for VSAM Database Support

Data Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs Using This Data Macro?
EB0EB Changed Yes
IDSDSB Changed Yes
IDSFLV Changed Yes
IEQCE2 Changed Yes
IEQCE3 Changed Yes
IXREC New Yes
VSACB New Yes
VSCNT New Yes
VSRPL New Yes

General Macros

Table 610 summarizes the general macro changes. This information is presented in alphabetic order by the name of the general macro. See TPF General Macros for a complete description of all general macros.

Table 610. Changes to General Macros for VSAM Database Support

General Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs?
VCHKC New Yes
VCLSC New Yes
VENDC New Yes
VGENC New Yes
VGETC New Yes
VOPNC New Yes
VPNTC New Yes
VSHOC New Yes

Selected Equate Macros

Table 611 summarizes the selected equate macro changes. This information is presented in alphabetic order by the name of the selected equate macro.

Table 611. Changes to Selected Equate Macros for VSAM Database Support

Selected Equate Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs?
RITEQ Changed Yes
VSERR New Yes
VSMAC New Yes

Structured Programming Macros (SPMs)

There are no changes.

System Initialization Program (SIP) Skeleton and Internal Macros (Inner Macros)

Table 612 summarizes the system initialization program (SIP) skeleton and internal macro changes. This information is presented in alphabetic order by the name of the SIP skeleton and internal macro. If the SIP skeleton and internal macro (inner macro) is changed, you must reassemble the SIP Stage I deck and run the appropriate job control language (JCL) jobs from the SIP Stage II deck.

Table 612. Changes to SIP Skeleton and Internal Macros for VSAM Database Support

SIP Skeleton and Internal Macro New, Changed, or No Longer Supported?
SPPGML Changed

System Initialization Program (SIP) Stage I Macros and Statements

There are no changes.

System Initialization Program (SIP) Stage II Macros

Table 613 summarizes system initialization program (SIP) Stage II macro changes. This information is presented in alphabetic order by the name of the SIP Stage II macro. If IBMPAL is changed, you must run the system allocator (SALO) and load the new program allocation table (PAT) to the TPF 4.1 system.

Table 613. Changes to SIP Stage II Macros for VSAM Database Support

SIP Stage II Macro New, Changed, or No Longer Supported?
IBMPAL Changed

System Communication Keypoint (SCK) Generation Macros

There are no changes.

System Macros

Table 614 summarizes system macro changes. This information is presented in alphabetic order by the name of the system macro. See TPF System Macros for a complete description of all system macros.

Table 614. Changes to System Macros for VSAM Database Support

System Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs?
FLVFC Changed Yes
QGDSQ New Yes

System Macros (IBM Use Only)

Table 615 summarizes system macro changes that are for IBM use only. This information is presented in alphabetic order by the name of the system macro.

Table 615. Changes to System Macros (IBM Use Only) for VSAM Database Support

System Macro (IBM Use Only) New, Changed, or No Longer Supported? Do You Need to Reassemble Programs?
VACBC New Yes
VRPLC New Yes
VSETC New Yes

Segments

Table 616 summarizes segment changes. This information is presented in alphabetic order by the name of the segment.

Table 616. Changes to Segments for VSAM Database Support

Segment Type Link-Edit Module (Where Offline Segment Is Linked) New, Changed, or No Longer Supported? Description of Change
CVGE Real-Time Assembler Not Applicable Changed Updated to flush all VFA records associated with a VSAM data set when removing the data set.
CVG5 Real-Time Assembler Not Applicable New Added VSAM database macro service routines.

System Equates

There are no changes.

User Exits

There are no changes.

Functional and Operational Changes

The following section summarizes functional and operational changes. This information is presented in alphabetic order by the functional or operational change.

See Appendix A, "PUT 2-15 Interface Changes by Authorized Program Analysis Report (APAR)" for a summary of functional and operational changes by APAR.

Commands

There are no changes.

Messages and System Errors

There are no changes.

Performance or Tuning Changes

There are no changes.

Storage Considerations and Changes

There are no changes.

System Initialization Program (SIP) and System Generation Changes

There are no changes.

Loading Process Changes

There are no changes.

Online System Load Changes

There are no changes.

Publication Changes

Table 617 summarizes changes to the publications in the TPF library. This information is presented in alphabetic order by the publication title. See the TPF Library Guide for more information about the TPF library.

Table 617. Changes to TPF Publications for VSAM Database Support

Publication Title Softcopy File Name Description of Change
TPF Application Programming GTPAPP09 Updated with an overview of VSAM database support, including information about accessing data in VSAM data sets, disk mirroring, data set naming conventions, and compatibility considerations.
TPF Database Reference GTPDBR08 Updated with information about VFA record selection for GDS records with VSAM database support.
TPF General Macros GTPGEN0A Updated with information about general macros that were added for VSAM database support.
TPF Migration Guide: Program Update Tapes GTPMG200 Updated with migration considerations for VSAM database support.
TPF System Macros GTPSYS0A Updated with information about system macros that were added and changed for VSAM database support.

Host System Changes

There are no changes.

Application Programming Interface (API) Changes

VSAM database support adds the following information to pages 2 and 3 of the ECB:

Database Changes

There are no changes.

Feature Changes

There are no changes.

Installation Validation

There are no changes.

Migration Scenarios

To add VSAM database support to your TPF 4.1 system, do the following:

  1. Install program update tape (PUT) 10.
  2. Run the system allocator program (SALO) using IBMPAL and SPPGML additions for newly created segments to create an updated IBM program allocation table (IPAT) and system allocator (SAL) table.
  3. Reassemble any existing VSAM database applications against the new macros.
  4. Load the new object code to your TPF 4.1 system.
  5. Run the MVS REPRO offline procedure to prepare the VSAM cluster for mounting to the TPF 4.1 system. See DFSMS/MVS Version 1 Release 2 Access Method Services for VSAM Catalogs for more information about the REPRO function.
  6. Enter the ZDSMG MT command to mount the VSAM cluster data sets to the TPF 4.1 system. See TPF Operations for more information about the ZDSMG MT command.
  7. Run your VSAM applications.