gtpm2m2pMigration Guide: Program Update Tapes

TPF Data Event Control Block Support (APAR PJ27393)

The following section discusses the migration considerations for TPF data event control block (DECB) support.

Prerequisite APARs

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

Functional Overview

A data event control block (DECB) can logically be thought of as another data level in an entry control block (ECB). A DECB does not physically reside in an ECB, but it contains the same information as standard data levels. That information includes the following:

See TPF Application Programming for more information about DECB fields.

One major difference between an ECB data level and a DECB is that the field that contains the file address has been expanded to 8 bytes in the DECB. Because there is no room for that expansion in the ECB, the logical place for 8-byte file addresses to be stored is in a DECB. With the addition of TPF DECB support, 8-byte file addressing in 4x4 format is being provided. 4x4 format provides for standard 4-byte file addresses (FARF3, FARF4, or FARF5) to be stored in an 8-byte field. This is done by having the file address reside in the low-order 4 bytes of the field. The high-order 4 bytes of the field contain an indicator that classifies the address as a valid 4x4 format address.

Before the addition of TPF DECB support, there were only 16 data levels (D0-DF) available for use. Because DECBs can be acquired dynamically by a single ECB (through the use of the DECBC macro), the storage, which will hold the DECB, comes from the 1-MB private area of the ECB. Therefore, the number of DECBs that the ECB is restricted to is only limited by the amount of storage in the private area that is dedicated to the DECB. See TPF General Macros for more information about the DECBC macro.

Using TPF DECB support instead of ECB data levels allows you to associate symbolic names with each DECB. This allows different components of a program to easily pass information in core blocks attached to a DECB. Each component only needs to know the name of the DECB where the information is to be found to access it.

TPF DECB support can be used by all types of applications. New application programming interfaces (APIs) have been added to allow TPF programs to access file records with a DECB instead of a data level in an ECB. However, only a subset of the existing macros that currently reference ECB data levels have been updated to accept a DECB instead of a data level. Macros and C functions that use an 8-byte file address will first verify that it is a valid address in 4x4 format. If the address is not valid, a system error will occur. See Table 969 and Table 973 for a list of the general and system macros that were added or changed for TPF DECB support. See Application Programming Interface (API) Changes for more information about C functions.

Architecture

There are no changes.

Operating Environment Requirements and Planning Information

There are no changes.

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

Table 962 summarizes changes to the build scripts used by the build tool. This information is presented in alphabetic order by the name of the build script.

Table 962. Changes to Build Scripts for TPF DECB Support

Build Script Type New, Changed, or No Longer Supported? Description of Change
CTADBS DLL New Added a TPF application dynamic link library (DLL).

Dynamic Load Module (DLM) Stubs

There are no changes.

General Use C/C++ Language Header Files

Table 963 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 963. Changes to General Use C/C++ Language Header Files for TPF DECB Support

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

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

Table 964 summarizes the general use C/C++ language header file changes that are for IBM use only. This information is presented in alphabetic order by the name of the general use C/C++ language header file.

Table 964. Changes to Implementation-Specific C/C++ Language Header Files (IBM Use Only) for TPF DECB Support

C/C++ Language Header File (IBM Use Only) New, Changed, or No Longer Supported? Do You Need to Recompile Segments?
i$decb.h New Yes
i$ecb3.h Changed No
sysapi.h Changed Yes (CMQBLD, CMQCKQ, CMQMVM)

Library Interface Scripts

There are no changes.

Library Members (Object Files)

Table 965 summarizes the library member (object file) changes. This information is presented in alphabetic order by the name of the library member (object file).

Table 965. Changes to Library Members (Object Files) for TPF DECB Support

Library Member (Object File) Library Module Name New, Changed, or No Longer Supported? Type Description of Change
CFACZC CTAL Changed Assembler Updated the processing of the tpf_faczc function.
CSSDLL CISO Changed C Language Added the CTAD DLL to the list of subsystem-shared DLLs.

Link-Edited Modules

There are no changes.

Members (Object Files)

Table 966 summarizes changes to members (object files). This information is presented in alphabetic order by the name of the member (object file).

Notes:

  1. You must recompile or reassemble a member (object file) if it has changed.

  2. You must prelink and link a dynamic load module (DLM) if it has changed.

Table 966. Changes to Members (Object Files) for TPF DECB Support

Member (Object File) DLM/DLL New, Changed, or No Longer Supported? Type Description of Change
CATTAD CTAD New Assembler Added to update the processing of the attac_ext function.
CCSOND CTAD New Assembler Added to update the processing of the csonc function.
CDECBC CTAD New Assembler Added to update the processing of the tpf_decb_-type functions.
CDETAD CTAD New Assembler Added to update the processing of the detac_ext function.
CESFAD CTAD New Assembler Added to update the processing of the tpf_esfac function.
CFAC8C CTAD New Assembler Added to update the processing of the tpf_fac8c function.
CFLDEC CTAD New Assembler Added to update the processing of the file_record_ext function.
CFNDEC CTAD New Assembler Added to update the processing of the find_record_ext function.
CGDSND CTAD New Assembler Added to update the processing of the gdsnc function.
CGDSRD CTAD New Assembler Added to update the processing of the gdsrc function.
CGETCD CTAD New Assembler Added to update the processing of the getcc function.
CGETFD CTAD New Assembler Added to update the processing of the getfc function.
CRELCD CTAD New Assembler Added to update the processing of the relcc function.
CRELFD CTAD New Assembler Added to update the processing of the relfc function.
CSONID CTAD New Assembler Added to update the processing of the sonic function.
CTADOV CTAD New C++ Language Added to process overloaded standard TPF APIs.
CUNFRD CTAD New Assembler Added to update the processing of the unfrc_ext function.
CVXSF4 CVXS Changed Assembler Updated the ZDECB command.
CVXSF6 CVXS Changed Assembler Updated the ZDECB command.

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 967 summarizes the copy member changes. This information is presented in alphabetic order by the name of the copy member.

Table 967. Changes to Copy Members for TPF DECB 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 release DECBs at entry control block (ECB) exit time.
CCEF Control Program CCENBK Not Applicable Changed Updated to use the new IDECB data macro.
CCEG Control Program CCENBK Not Applicable Changed Updated to use the new IDECB data macro.
CDEC Control Program CCNUCL Not Applicable New Added to process the DECBC macro.
CEDT Control Program CCCPSE Not Applicable Changed Updated to use the new IDECB data macro.
CEFI Control Program CCFADC Not Applicable Changed Updated to process DECBs for FIND or FILE requests.
CEFJ Control Program CCFADC Not Applicable Changed Updated to process DECBs for FIND or FILE requests.
CEFK Control Program CCFADC Not Applicable Changed Updated for general data set (GDS) support.
CEFL Control Program CCFADC Not Applicable Changed Updated to process DECBs for FIND or FILE requests.
CFAC Control Program CCDBAF Not Applicable Changed Updated the processing of the FACZC and FAC8C macros with 8-byte file addresses.
CHSZ Control Program CCNUCL Not Applicable Changed Updated to initialize ECB fields.
CICR Control Program CCNUCL Not Applicable Changed Updated to process DECBs for various TPF macro requests.
CJ321 Real-Time Assembler CJ005 CJ00 Changed Updated to use the new IDECB data macro.
CJ322 Real-Time Assembler CJ005 CJ00 Changed Updated to use the new IDECB data macro.
CJ327 Real-Time Assembler CJ005 CJ00 Changed Updated to use the new IDECB data macro.
CJ341 Real-Time Assembler CJ005 CJ00 Changed Updated to use the new IDECB data macro.
CJIL Control Program CCSONA Not Applicable Changed Updated to set up the SUD in the DECB (when DECB is used).
CPSF Control Program CCCPSF Not Applicable Changed Updated to use the new IDECB data macro.
CPSL Control Program CCCPSE Not Applicable Changed Updated to dump DECBs with the ECB.
CPSM Control Program CCCPSE Not Applicable Changed Updated to process DECBs on SNAPC requests.
CRTT Control Program CCUTIL Not Applicable Changed Updated real-time trace (RTT) to use the new IDECB data macro.
CTSF Control Program CCUTIL Not Applicable Changed Updated selective file trace (SFT) to use the new IDECB data macro.
CVF3 Control Program CCVFAC Not Applicable Changed Updated the FLVFC macro to process DECBs.
DBAC Control Program CCDBAF Not Applicable Changed Updated the CSONC macro to handle 8-byte file addresses.
DBAS Control Program CCDBAF Not Applicable Changed Updated the ESFAC and SONIC macros to handle 8-byte file addresses.
GRFS Control Program CCSONP Not Applicable Changed Updated to process DECBs on the GETFC and RELFC requests.
MPTV Control Program CCUTIL Not Applicable Changed Updated the program test vehicle (PTV) to process DECBs.

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 968 summarizes the data macro changes. This information is presented in alphabetic order by the name of the data macro.

Table 968. Changes to Data Macros for TPF DECB Support

Data Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs Using This Data Macro?
EB0EB Changed No
ECBEQ Changed No
IDDBT New Yes
IDECB New Yes
IDSDEC No Longer Supported Not Applicable
IDSDMP Changed Yes
IDSFCZ Changed Yes - BAM0, BCC0, BCC3, BDBC, BDBE, BDBF, BEWP, BHWP, BKA0, BKB0, BKC1, BKP4, BPM0, BRFM, BRPK, BRPT, BRSH, BRTO, BRTP, BRTV, BSSC, BSSW, BSSX, BWRA, BWRT, BXBL, CFD1, CIPZ, CYBD, UBDB, UBWR

Notes:

  1. If you are installing integrated online pool maintenance and recoup support (APAR PJ27469), you must also reassemble the following programs: B0P5, BCP1, BCPY, BOF2, BOFF, BOFK, BPDH, BRID, BRIE, BRPI, BRV0, BRV2, BRV3, BRV5, DYDN, DYD1, and DYD2.

    For more information about integrated online pool maintenance and recoup support, see Integrated Online Pool Maintenance and Recoup Support (APAR PJ27469).

  2. The IDSFCZ data macro increased the input size requirement from 19 bytes to 23 bytes, and the output size from 14 bytes to 22 bytes. Therefore, you should examine any program using the IDSFCZ data macro to make sure the output location defined by this data macro has enough room reserved for the macro call.
IDSFLV Changed No
IDSSNP Changed No
IDSTTR Changed Yes - CCCFLC, CCCLHR, CCCTIN, CCIISC, CCMCDC, CCSICF, CCSTOR, CCTLOG
IEQCE3 Changed Yes
IFAC8 New No

General Macros

Table 969 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 969. Changes to General Macros for TPF DECB Support

General Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs?
ATTAC Changed No
CRUSA Changed No
CSONC Changed No
DECBC New Yes
DETAC Changed No
FA4X4C New Yes
FAC8C New Yes
FILEC Changed No
FILNC Changed No
FILSC Changed No
FILUC Changed No
FINDC Changed No
FINHC Changed No
FINSC Changed No
FINWC Changed No
FIWHC Changed No
GDSNC Changed No
GDSRC Changed No
GETCC Changed No
GETFC Changed No
LEVTA Changed No
LISTC Changed No
RCRFC Changed No
RCUNC Changed No
RELCC Changed No
RELFC Changed No
SONIC Changed No
UNFRC Changed No

Selected Equate Macros

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

Table 970. Changes to Selected Equate Macros for TPF DECB Support

Selected Equate Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs?
CZOCP Changed No
CZ1SE Changed No

Structured Programming Macros (SPMs)

There are no changes.

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

Table 971 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 971. Changes to SIP Skeleton and Internal Macros for TPF DECB 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 972 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 972. Changes to SIP Stage II Macros for TPF DECB 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 973 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 973. Changes to System Macros for TPF DECB Support

System Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs?
$FINDC Changed No; publication updates only.
ESFAC Changed Yes - CCCTIN. Only reassemble control program (CP) segments that call this macro. You do not need to reassemble real-time assembler segments.
FACZC Changed Yes - BAM0, BCC3, BDBC, BDBE, BDBF, BKA0, BKC1, BSSC, BXBL, CFD1, CIPZ, CYBD, UBDB
FLSPC Changed No
FLVFC Changed No
FNSPC Changed No
FTSTC Changed No

System Macros (IBM Use Only)

Table 974 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 974. Changes to System Macros (IBM Use Only) for TPF DECB Support

System Macro (IBM Use Only) New, Changed, or No Longer Supported? Do You Need to Reassemble Programs?
CFMCC Changed Yes - ICDF
CFMDC Changed Yes - ICDF
IBMSVC Changed Yes - CCMCDC

Segments

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

Table 975. Changes to Segments for TPF DECB Support

Segment Type Link-Edit Module (Where Offline Segment Is Linked) New, Changed, or No Longer Supported? Description of Change
BMT3 Real-Time Assembler Not Applicable Changed Updated to fix the CTL-1 dump in the real-time trace (RTT) ZSTOP processing.
CCNUCL CSECT CPS0 Changed Updated to include the CDEC copy member.
CDE1 Real-Time Assembler Not Applicable Changed Updated processing of the ZFECB command.
CDE2 Real-Time Assembler Not Applicable Changed Updated processing of the ZFECB command.
CDE3 Real-Time Assembler Not Applicable Changed Updated processing of the ZFECB command.
CPSU Real-Time Assembler Not Applicable Changed Updated the prolog to include the new information passed to the Dump Data user exit.
STPP Offline Assembler PPCP Changed Updated offline dump formatting. 

System Equates

There are no changes.

User Exits

Control Program (CP) User Exits and ECB User Exits summarize the control program (CP) and ECB user exit changes. See TPF System Installation Support Reference for a complete description of all user exits.

Control Program (CP) User Exits

There are no changes.

ECB User Exits

This information is presented in alphabetic order by the name of the function.

Table 976. Changes to ECB User Exits for TPF DECB Support

Function User Exit Activated In User Exit Program New, Changed, or No Longer Supported? Description of Change
Dump Data CCCPSE CPSU Changed Updated to pass information about DECBs to the user exit.

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

Table 977 summarizes command changes. This information is presented in alphabetic order by the name of the command. See TPF Operations for a complete description of all commands.

Attention: Changes to commands can impact any automation programs you are using in your complex.

Table 977. Changes to Commands for TPF DECB Support

Command New, Changed, or No Longer Supported? Description of Change
ZDECB Changed Updated to process expanded ECB macro trace entries. This was a code change only.
ZFECB Changed Updated to provide DECB information in a formatted ECB display.

Messages and System Errors

Table 978 summarizes message (offline and online messages) and system error changes.

The message IDs or system error numbers are listed in numeric order preceded by their alphabetic prefix. Some offline and online messages do not have a standard message ID. For these, the messages are presented in alphabetic order based on the initial message text; or for those messages that begin with variable information, the initial message text that follows that variable information. See Messages (System Error and Offline) and Messages (Online) for a complete description of all messages and system errors.

Attention: Changes to offline messages, online messages, and system errors may impact any automation programs you are using in your complex.

Table 978. Changes to Messages and System Errors for TPF DECB Support

Message ID or System Error Number Message Type New, Changed, or No Longer Supported?
000006 System Error Changed
000007 System Error Changed
00000B System Error Changed
000022 System Error Changed
000023 System Error Changed
000027 System Error Changed
00002E System Error Changed
0000D1 System Error Changed
0000D2 System Error Changed
0006E3 System Error Changed
0006E8 System Error Changed
0DECB0 System Error New
0DECB1 System Error New
0DECB2 System Error New
0DECB3 System Error New
0DECB4 System Error New
0DECB5 System Error New
0DECB6 System Error New
0DECB7 System Error New
FECB0007I Online No Longer Supported
FECB0008I Online New

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 979 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 979. Changes to TPF Publications for TPF DECB Support

Book Title Softcopy File Name Description of Change
TPF Application Programming GTPAPP0C Updated with information that was added and changed for TPF DECB support.
TPF C/C++ Language Support User's Guide GTPCLU0D Updated with C/C++ functions that were added and changed for TPF DECB support.
TPF Concepts and Structures GTPCON0A Updated with information that was added and changed for TPF DECB support.
TPF Database Reference GTPDBR0B Updated with information that was changed for TPF DECB support.
TPF Library Guide GTPDOC0D Updated with definitions for new terminology in the master glossary.
TPF General Macros GTPGEN0C Updated with information about general macros that were added and changed for TPF DECB support.
Messages (System Error and Offline) and Messages (Online) Not Applicable Updated with information about messages and system errors that were added, changed, and no longer supported for TPF DECB support.
TPF Migration Guide: Program Update Tapes GTPMG203 Updated with migration considerations for TPF DECB support.
TPF Operations GTPOPR0D Updated with information about the commands that were added and changed for TPF DECB support.
TPF Program Development Support Reference GTPPDR0D Updated with information that was added and changed for TPF DECB support.
TPF System Generation GTPSYG0D Updated with information that was added and changed for TPF DECB support.
TPF System Installation Support Reference GTPINR0D Updated the Dump Data user exit for TPF DECB support.
TPF System Macros GTPSYS0D Updated with information about system macros that were added and changed for TPF DECB support.

Host System Changes

There are no changes.

Application Programming Interface (API) Changes

Applications that call the following functions (using 8-byte file addresses or DECBs instead of ECB data levels) must be compiled with the C++ compiler:

See the TPF C/C++ Language Support User's Guide for more information about these functions.

Database Changes

There are no changes.

Feature Changes

There are no changes.

Installation Validation

There are no changes.

Migration Scenarios

To add TPF DECB support to your current TPF 4.1 system, do the following:

  1. Install program update tape (PUT) 13.
  2. Install the following:
  3. Reassemble or recompile the following:
    • DLM members listed in Table 966
    • CSECTS listed in Table 967
    • Macros listed in Table 968
    • Programs listed in Table 973
    • Programs listed in Table 974
    • Segments listed in Table 975.
      Note:
      Reassemble any CSECTs or programs you have modified that call the ESFAC, FACZC, or IDSFCZ macros.
  4. Link-edit CPS0.
  5. Run the system allocator (SALO) using IBMPAL and SPPGML additions for newly created segments to create an updated program allocation table (PAT) and SAL table. See Table 965 and Table 975 for more information about new segments.
  6. Run CBLD for build scripts listed in Table 962.
  7. Assemble the following offline and online TPF utility programs that were modified:
    • ICDF
    • IPLB
    • STPP.
  8. Link the PPCP offline program (include STPP).
  9. Compile the following C/C++ programs that have been created or modified:
    • CSSDLL
    • CTADOV.
  10. Compile the following C++ programs to pick up changes to the sysapi.h header file and the tpf_faczc function:
    • CMQBLD
    • CMQCKQ.
  11. Link-edit the following DLLs:
    • CTADBS
    • CMQKBS.
  12. Link-edit the following ISO-C Libraries (LIBs):
    • CJ00BS
    • CISOBS
    • CTALBS.
  13. Link-edit the CVXSBS DLM.
  14. Modify and assemble the Dump Data (CPSU) user exit, as needed.
  15. Load the updated object code to your TPF 4.1 system.
  16. Cycle the TPF 4.1 system to NORM state before running any application programs.

Fallback and Coexistence

If TPF DECB support is installed at your complex, system errors that occur on the online TPF system cannot be post-processed using a back-level version of the post-processor control program (PPCP). Both your online system and dump post-processor must have TPF DECB support installed.