gtpm2m20 | Migration Guide: Program Update Tapes |
The following section discusses the migration considerations for VSAM database support.
See the APEDIT for APAR PJ26150 for information about prerequisite APARs.
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:
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.
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.
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.
There are no hardware requirements.
VSAM database support requires MVS/DFP Version 3 Release 3 or higher releases or MVS/ESA Version 4.2 or higher releases.
The following section summarizes interface changes.
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.
There are no changes.
There are no changes.
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 |
There are no changes.
There are no changes.
There are no changes.
There are no changes.
There are no changes.
There are no changes.
There are no changes.
There are no changes.
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. |
There are no changes.
The following section summarizes the macro changes. This information is presented in alphabetic order by the type of macro.
There are no changes.
There are no changes.
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 |
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 |
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 |
There are no changes.
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 |
There are no changes.
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 |
There are no changes.
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 |
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 |
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. |
There are no changes.
There are no 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.
There are no changes.
There are no changes.
There are no changes.
There are no changes.
There are no changes.
There are no changes.
There are no 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. |
There are no changes.
VSAM database support adds the following information to pages 2 and 3 of the ECB:
There are no changes.
There are no changes.
There are no changes.
To add VSAM database support to your TPF 4.1 system, do the following: