gtpm2m2mMigration Guide: Program Update Tapes

Loaders Enhancement for the TPF Assembler Debugger for VisualAge Client (APAR PJ27422)

The following section discusses the migration considerations for the loaders enhancement for the TPF Assembler Debugger for VisualAge Client (referred to as loaders enhancement for TPF Assembler Debugger in the remainder of this section).

Prerequisite APARs

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

Functional Overview

The loaders enhancement for TPF Assembler Debugger gives you the ability to load ADATA files used by the assembler debugger rather than using Trivial File Tranfer Protocol (TFTP) to transfer ADATA files to the online TPF 4.1 system. The loaders enhancement for TPF Assembler Debugger provides the following benefits:

Architecture

With the loaders enhancement for TPF Assembler Debugger, ADATA files are loaded to the online TPF 4.1 system with real-time programs. When loaded with programs by the E-type loader, ADATA files are first written to #OLDn records. If a loadset containing programs with ADATA files is accepted, ADATA files are written to a new program-base unique fixed file record type (#APRGn). #APRGn records are allocated to a given program and remain allocated to that program even if a new version of that program is loaded without ADATA files. The auxiliary loader (initiated by the ZTPLD command) also writes ADATA files to #APRGn records. Loadsets that include programs with ADATA files can be accepted even if #APRGn records are not allocated, in which case ADATA files are discarded during the accept process. This allows ADATA file support to be immediately used without requiring new records to be allocated.

The size of the online program allocation table (PAT) entry has been increased to add new fields related to the ADATA files. This requires reassembly of programs that use the PAT entry size to step through the table or to calculate an offset into the table.

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 907 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 907. Changes to Build Scripts for Loaders Enhancement for TPF Assembler Debugger

Build Script Type New, Changed, or No Longer Supported? Description of Change
CELABS DLM Changed Updated for commentary changes only.
CILOBS DLM New Added to file adata.
CILXBS DLM New Added to build adata.
COLOBS DLM Changed Updated to add crlz_accept_3_overlay_adata.

Dynamic Load Module (DLM) Stubs

Table 908 summarizes changes to the dynamic load module (DLM) stubs. This information is presented in alphabetic order by the name of the DLM stub. See TPF Application Programming for more information about the DLM stubs.

Table 908. Changes to Dynamic Load Module (DLM) Stubs for Loaders Enhancement for TPF Assembler Debugger

DLM Stub New, Changed, or No Longer Supported?
CILO New
CILX New

General Use C/C++ Language Header Files

Table 909 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 909. Changes to General Use C/C++ Language Header Files for Loaders Enhancement for TPF Assembler Debugger

C/C++ Language Header File New, Changed, or No Longer Supported? Do You Need to Recompile Segments?
c$fva0.h Changed Yes
c$icolr.h Changed Yes
c$idseld.h Changed Yes
c$idselv.h Changed Yes
c$idsepd.h Changed Yes
c$idsldr.h Changed Yes
c$idsmxp.h Changed Yes
c$idsold.h Changed No
c$idspat.h Changed Yes
c$idsprg.h Changed Yes
c$idspvr.h Changed Yes
c$idsuxt.h Changed No
c$tpldr.h Changed Yes
zimageq.h Changed No
zimagmsg.h Changed No
ztpld.h Changed No

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

Table 910 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 910. Changes to Implementation-Specific C/C++ Language Header Files (IBM Use Only) for Loaders Enhancement for TPF Assembler Debugger

C/C++ Language Header File (IBM Use Only) New, Changed, or No Longer Supported? Do You Need to Recompile Segments?
i$udcl.hpp Changed Yes

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)

Table 911 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 911. Changes to Members (Object Files) for Loaders Enhancement for TPF Assembler Debugger

Member (Object File) DLM/DLL New, Changed, or No Longer Supported? Type Description of Change
CEL8 CEL8 Changed C Language Updated for Loaders Enhancement for TPF Assembler Debugger.
CELL CELA Changed C Language Updated for Loaders Enhancement for TPF Assembler Debugger.
CIKD CIMA Changed C Language Updated for Loaders Enhancement for TPF Assembler Debugger.
CIKE CIMU Changed C Language Updated for Loaders Enhancement for TPF Assembler Debugger.
CIL0 CILA Changed C Language Updated for Loaders Enhancement for TPF Assembler Debugger.
CIL1 CILA Changed C Language Updated for Loaders Enhancement for TPF Assembler Debugger.
CIL6 CILA Changed C Language Updated for Loaders Enhancement for TPF Assembler Debugger.
CIL7 CILA Changed C Language Updated for Loaders Enhancement for TPF Assembler Debugger.
CILA CILA Changed C Language Updated for Loaders Enhancement for TPF Assembler Debugger.
CILB CILB Changed C Language Updated for Loaders Enhancement for TPF Assembler Debugger.
CILC CILA Changed C Language Updated for Loaders Enhancement for TPF Assembler Debugger.
CILE CILE Changed C Language Updated for Loaders Enhancement for TPF Assembler Debugger.
CILF CILF Changed C Language Updated for Loaders Enhancement for TPF Assembler Debugger.
CILG CILG Changed C Language Updated for Loaders Enhancement for TPF Assembler Debugger.
CILH CILH Changed C Language Updated for Loaders Enhancement for TPF Assembler Debugger.
CILO CILO New C Language Created for Loaders Enhancement for TPF Assembler Debugger.
CILX CILX New C Language Created for Loaders Enhancement for TPF Assembler Debugger.
CLDJ CEL2 Changed C Language Updated for Loaders Enhancement for TPF Assembler Debugger.
CLDZ CELA Changed C Language Updated for Loaders Enhancement for TPF Assembler Debugger.
CLEM CLEM Changed C Language Updated for Loaders Enhancement for TPF Assembler Debugger.
CLEW CLEW Changed C Language Updated for Loaders Enhancement for TPF Assembler Debugger.
COL2 COL1 Changed C Language Updated for Loaders Enhancement for TPF Assembler Debugger.
COLM COLM Changed C Language Updated for Loaders Enhancement for TPF Assembler Debugger.
COLO COLO Changed C Language Updated for Loaders Enhancement for TPF Assembler Debugger.
COLP COLH Changed C Language Updated for Loaders Enhancement for TPF Assembler Debugger.
COLV COLV Changed C Language Updated for Loaders Enhancement for TPF Assembler Debugger.
CRLB CRLB Changed C Language Updated for Loaders Enhancement for TPF Assembler Debugger.
CRLD CELA Changed C Language Updated for Loaders Enhancement for TPF Assembler Debugger.
CRLX COLM Changed C Language Updated for Loaders Enhancement for TPF Assembler Debugger.
CRLZ COLO Changed C Language Updated for Loaders Enhancement for TPF Assembler Debugger.
CUD2 CUD2 Changed C++ Language Updated for Loaders Enhancement for TPF Assembler Debugger.
CUD4 CUD2 Changed C++ Language Updated for Loaders Enhancement for TPF Assembler Debugger.
CUD5 CUD2 Changed C++ Language Updated for Loaders Enhancement for TPF Assembler Debugger.
CUDA CUDA Changed C++ Language Updated for Loaders Enhancement for TPF Assembler Debugger.
CUDAPV CUDA Changed C++ Language Updated for Loaders Enhancement for TPF Assembler Debugger.

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

Table 912. Changes to Copy Members for Loaders Enhancement for TPF Assembler Debugger

Copy Member Type CSECT Where Copy Member Is Located DLM Where CSECT Is Located New, Changed, or No Longer Supported? Description of Change
CCEG Control Program CCENBK Not Applicable Changed Updated for Loaders Enhancement for TPF Assembler Debugger.

Fixed File Records

Table 913 summarizes fixed file record changes. This information is presented in alphabetic order by the name of the fixed file record.

Table 913. Changes to Fixed File Records for Loaders Enhancement for TPF Assembler Debugger

Fixed File Record New, Changed, or No Longer Supported? Description of Change
#APRGn New Added for Loaders Enhancement for TPF Assembler Debugger.

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

Table 914. Changes to Data Macros for Loaders Enhancement for TPF Assembler Debugger

Data Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs Using This Data Macro?
IDSMXP Changed No
IDSPAT Changed No
IDSPRG Changed No
IDSPVR Changed No
TPLDR Changed No

General Macros

There are no changes.

Selected Equate Macros

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

Table 915. Changes to Selected Equate Macros for Loaders Enhancement for TPF Assembler Debugger

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

Structured Programming Macros (SPMs)

There are no changes.

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

Table 916 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 916. Changes to SIP Skeleton and Internal Macros for Loaders Enhancement for TPF Assembler Debugger

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 917 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 917. Changes to SIP Stage II Macros for Loaders Enhancement for TPF Assembler Debugger

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 918 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 918. Changes to System Macros for Loaders Enhancement for TPF Assembler Debugger

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

System Macros (IBM Use Only)

There are no changes.

Segments

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

Table 919. Changes to Segments for Loaders Enhancement for TPF Assembler Debugger

Segment Type Link-Edit Module (Where Offline Segment Is Linked) New, Changed, or No Longer Supported? Description of Change
ACPL Real-Time Assembler N/A Changed Updated for Loaders Enhancement for TPF Assembler Debugger
ALDR Offline Assembler TPFLDR Changed Updated for Loaders Enhancement for TPF Assembler Debugger
CVA6 BAL N/A Changed Updated for Loaders Enhancement for TPF Assembler Debugger
CVAW BAL N/A Changed Updated for Loaders Enhancement for TPF Assembler Debugger
COLR Offline Assember TPFLDR Changed Updated for Loaders Enhancement for TPF Assembler Debugger
FTVA03 Offline C Language FCTBG Changed Updated for Loaders Enhancement for TPF Assembler Debugger
OLDR Offline C Language TPFLDR Changed Updated for Loaders Enhancement for TPF Assembler Debugger
TLDR Offline Assember TPFLDR Changed Updated for Loaders Enhancement for TPF Assembler Debugger
TLDRMN Offline C Language TPFLDR Changed Updated for Loaders Enhancement for TPF Assembler Debugger

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 920. Changes to ECB User Exits for Loaders Enhancement for TPF Assembler Debugger

Function User Exit Activated In User Exit Program New, Changed, or No Longer Supported? Description of Change
Extra Program Record Report ACPL, CRLX, CIL1 UELI Changed Updated to add new parameters to the user exit interface for #APRGn record information.

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 921 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 commnds.

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

Table 921. Changes to Commands for Loaders Enhancement for TPF Assembler Debugger

Command New, Changed, or No Longer Supported? Description of Change
ZIMAG COPY Changed Updated to copy #APRGn records, if allocated, when the PROG parameter is specified.
ZDPAT Changed Updated to display ADATA file address information.

Messages and System Errors

Table 922 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 922. Changes to Messages and System Errors for Loaders Enhancement for TPF Assembler Debugger

Message ID or System Error Number Message Type New, Changed, or No Longer Supported?
000000000 Offline New
000000000 Offline New
000000000 Offline New
094320 System Error New
ALDR0401T Offline New
CILC0119W Online New
CILE0115W Online New
CILG0111E Online New
CILG0112E Online New
CILO0113E Online New
CILO0114W Online New
CILO0117W Online New
CILO0118W Online New
CILO0120E Online New
CILX0116W Online New
CILX0117W Online New
CIL60121W Online New
IMAG0084E Online New
OLDR0091T Offline New
OLDR0092W Offline New
OLDR0093W Offline New
OLDR0094W Offline New
OLDR0095W Offline New
OLDR3227W Online New
OLDR3228W Online New
OLDR3229W Online New
TLDR0402T Offline New
TPFL1001I Offline New

Performance or Tuning Changes

There are no changes.

Storage Considerations and Changes

The size of the online program allocation table (PAT) entry has increased from 96 bytes to 112 bytes, which is an increase of 17 %. This affects the file copy and the core copy of the PAT, so the number of #CIMRn records used by the PAT will increase as well as the amount of core memory used to hold the PAT.

If you plan to make use of loaders enhancement for TPF Assembler Debugger for debugging, you may need to allocate additional fixed file records as follows:

See TPF System Generation for information about how to determine how many additional #OLDn records or how many new #APRGn records to allocate.

If you do not allocate #APRGn records, you can still use OLDR to load programs with ADATA files. Furthermore, loadsets containing programs with ADATA files can be accepted even if #APRGn records are not allocated. As programs with ADATA files are accepted, ADATA files will simply be discarded.

System Initialization Program (SIP) and System Generation Changes

There are no changes.

Loading Process Changes

See the help information provided with the TPF Assembler Debugger for VisualAge Client for information about loading ADATA files. If you are not loading ADATA files, there are no changes to the load process.

Online System Load Changes

See the help information provided with the TPF Assembler Debugger for VisualAge Client for information about loading ADATA files. If you are not loading ADATA files, there are no changes to the online system load process.

Publication Changes

Table 923 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 923. Changes to TPF Publications for Loaders Enhancement for TPF Assembler Debugger

Publication Title Softcopy File Name Description of Change
TPF System Installation Support Reference GTPINR0D Updated with information about the ADATAIN card, the #APRGn record clear card, and the UELI user exit for Loaders Enhancement for TPF Assembler Debugger.
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 Loaders Enhancement for TPF Assembler Debugger.
TPF Migration Guide: Program Update Tapes GTPMG203 Updated with migration considerations for Loaders Enhancement for TPF Assembler Debugger.
TPF Operations GTPOPR0D Updated with information about the commands that were added and changed for Loaders Enhancement for TPF Assembler Debugger.
TPF System Generation GTPSYG0C Updated with information about the #APRGn fixed file records that were added for Loaders Enhancement for TPF Assembler Debugger.

Host System Changes

There are no changes.

Application Programming Interface (API) Changes

There are no changes.

Database Changes

There are no changes.

Feature Changes

There are no changes.

Installation Validation

There are no changes.

Migration Scenarios

You must consider the following when using the loaders enhancement for TPF Assembler Debugger:

  1. Install loaders enhancement for TPF Assembler Debugger (APAR PJ27422) to the TPF 4.1 system.
  2. Determine whether you need to allocate additional fixed file records. ADATA files can be loaded by using either OLDR or the auxiliary loader (TLDR). ADATA files loaded by using TLDR reside in new fixed file record type #APRGn. ADATA files loaded using OLDR reside in #OLDn fixed file records. When a loadset containing a program with an ADATA file is accepted, the ADATA file is written to #APRGn records if they are allocated. If #APRGn records are not allocated, the ADATA file is discarded but the loadset is accepted anyway. To determine if you need to allocate additional fixed file records, do one of the following:
    • If you want to load ADATA files with base versions of programs, it will then be necessary to allocate #APRGn fixed file records. It may also be necessary to allocate additional #OLDn fixed file records. See TPF System Generation for guidelines on how many fixed file records to allocate for ADATA files.
    • If you want to load ADATA files with OLDR, it may be necessary to allocate additional #OLDn fixed file records. See TPF System Generation for guidelines on how many fixed file records to allocate for ADATA files.
    • If you do not want to load ADATA files by using TPFLDR, additional fixed file records are not needed.
  3. Reassemble and recompile all required programs. This includes:
    • All programs changed by loaders enhancement for TPF Assembler Debugger.
    • All programs listed in the following table:
      Name of Program to Reassemble or Recompile Name of Load Module to Relink
      CCCTIN40 CPSO
      CCVAGE40 CPSO
      CDPLT CDPL
      CELL CELA
      CELP CELP
      CIL2 CILA
      CIL3 CILA
      CIL4 CILA
      CIL5 CILA
      CLIB N/A
      CLDG CELA
      CLDH CELA
      CLDL CEL2
      CLDM CEL2
      CLDO CLDO
      CLDW CELA
      CLDY CELA
      CLE2 CELA
      CLEL CEL2
      CLEJ CLEJ
      CLEV CEL2
      CLEX COLH
      CLEY CEL2
      COL3 COL3
      COL4 COL4
      COL5 COL5
      COLC COLC
      COLK COLH
      COLN COLH
      COLQ COLQ
      COLW COLW
      CRLF CELA
      CRLK CELA
      CRLM CELA
      CRLS CLEL
      CRLV COLH
      CRLX COLM
      CUDC CUDA
      CUDXDB CDBSBS, CDBPBS, CRL1BS, COLHBS, CLDFBS
      CVA8 Not Applicable
      CYB2 CYB2
      JCD4 Not Applicable
      LEDT TPFLDR
      NLDT TPFLDR
      QMPA Not Applicable
    • All applications containing code that references the size of a program allocation table (PAT) entry. It can be extremely difficult to identify all code that references the size of a PAT entry, so it is recommended that the following applications be reassembled or recompiled:
      • All assembler code that includes the IDSPAT or IDSXTP.
      • All C language code that includes the c$idspat.h header file or the c$idsxtp.h header file.
      Note:
      This applies only to customer application code. TPF system code that references the size of the PAT entry are listed in the preceding table.
  4. Create a new system allocator (SALO) by using the modified version of IBMPAL.
  5. Recompile and run SALO to create an updated online allocator (IPAT) and offline allocator.
  6. Relink all load modules that include programs that were reassembled or recompiled previously. For TPF code, the load modules to be relinked are listed in the preceding table.
  7. Relink the control program.
  8. Relink TPFLDR.
  9. Define a load deck for TLDR that includes the following:
    • All programs that were rebuilt in the previous steps
    • The control program
    • The updated IPAT
    • The face table (FCTB), if additional fixed file records are required.

    Note:
    Do not attempt to load ADATA files at this time.
  10. Run TLDR.
  11. Perform a load to a target image.
  12. Enable the target image.
  13. IPL the TPF 4.1 system and choose the target image as the active image.
  14. Repeat step 10 through step 13 to load changed programs to other images.
  15. If you plan to load ADATA files by using TLDR or if you plan to accept programs with ADATA files into the program base using OLDR, you then need to do the following:
    1. Define a load deck for TLDR that includes the LOADER APRG CLEAR card and any other component or real-time program. See TPF System Installation Support Reference for additional information about the LOADER APRG CLEAR card.
    2. Run TLDR from an image that has a new FCTB that allocates #APRGn records.
    3. Perform a load to each image where you will want to load ADATA files.
  16. Repeat this procedure for all subsystems in a multiple database function (MDBF) environment.