gtpm2m18Migration Guide: Program Update Tapes

TPF Application Requester Enhancements (APAR PJ23931)

The following section discusses the migration considerations for TPF Application Requester Enhancements. Also see the TPF Application Requester User's Guide for migration information.

Prerequisite APARs

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

Functional Overview

TPF Application Requester Enhancements adds capabilities for TPF Application Requester (TPFAR) programs using databases on IBM RISC System/6000 (IBM RS/6000) and IBM Personal System/2 (IBM PS/2) platforms (or on other distributed relational database architecture (DRDA) level-1 compliant platforms). TPF Application Requester Enhancements implements:

Architecture

With TPF Application Requester Enhancements, TPF applications using SQL functions can connect with IBM DATABASE 2 (IBM DB2) on IBM RS/6000 and IBM PS/2 platforms. This is done by accounting for the byte order and numerical representations of the different platforms during flow interchanges (FD0CA).

Run-time binding of database resource management (DBRM) information occurs while an application is running. When an application containing SQL statements has not been bound, IBM DB2 does not have an execution package associated with the application. When the application tries to connect to IBM DB2, an error is returned indicating that there is no package. The TPF 4.1 system receives this error and tries to provide the application package information at run time. This involves reading DBRM information appended to the application segment and sending it to IBM DB2 with a request to bind. IBM DB2 binds the package; then, the TPF 4.1 system issues a new connect request, which is accepted because the package is now bound. Run-time binding is only available for programs written in ISO-C and not assembler.

The TPF support for coded character set IDs (CCSIDs) other than CCSID 500 involves the use of tools and data supplied by the IBM SAA AD/Cycle Language Environment (LE/370) C language function iconv and the GENXLT process. Code sets are defined by an offline process involving the GENXLT process. A table of defined code sets is loaded to the online TPF 4.1 system. The ZSQLD command is used to specify code sets to be used on the TPF 4.1 system and on the remote database. The TPF 4.1 system exchanges its requirements for character representation with the remote database server and, provided there is a translation mechanism available, translates from one character representation to another. The numerical representations and byte-order characteristics associated with standard platform architectures are also supported.

Dynamic SQL support enables preparation of SQL statements at run time instead of having prepared statements embedded in source programs. The following SQL verbs are supported:

Additional diagnostic fields have been added to the SQL trace table. The diagnostic information found in the SQLCA is saved in an expanded SQL trace entry and can be displayed by entering the ZSTTD command with the DET parameter specified.

Operating Environment Requirements and Planning Information

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

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)

The following section contains information about software requirements.

Communication

The following section summaries the communication changes.

Operating Environment for SNA-Based Communication

The TPF 4.1 system uses TPF Advanced Peer-to-Peer Networking (TPF/APPN) support to communicate with IBM RS/6000 and IBM PS/2 platforms.

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 232 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 232. Changes to Build Scripts for TPF Application Requester Enhancements

Build Script Type New, Changed, or No Longer Supported? Description of Change
CISOBS DLM Changed Added the iconv C language function.
CPGSBS DLM New Builds the coded character set support table.
CPG0BS DLM New Builds a coded character set, which is 819-500 initially.
CPG1BS DLM New Builds a coded character set, which is 819-500 initially.
CPG2BS DLM New Builds a coded character set, which is 819-500 initially.
CPG3BS DLM New Builds a coded character set, which is 819-500 initially.
CPG4BS DLM New Builds a coded character set, which is 819-500 initially.
CPG5BS DLM New Builds a coded character, which is 850-1047 initially.
CPG6BS DLM New Builds a coded character set, which is 850-500 initially.
CPG7BS DLM New Builds a coded character set, which is 932-290 initially.
CPG8BS DLM New Builds a coded character set, which is 932-300 initially.
CPG9BS DLM New Builds a coded character set, which is 932-930 initially.
CRDABS DLM New Added for run-time binding and dynamic SQL support, converted to ISO-C support and repackaged in a dynamic load module (DLM).
CREABS DLM New Added for run-time binding and dynamic SQL support, converted to ISO-C support and repackaged in a DLM.
CTBXBS DLM Changed Changed for more robust parsing of wildcard characters.
CRDQBS DLM New Added for the database support structure.
CRDRBS DLM New Added for the database support structure.
CRDUBS DLM New Added for command support.
CRDWBS DLM New Added for command support.

Dynamic Load Module (DLM) Stubs

Table 233 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 233. Changes to Dynamic Load Module (DLM) Stubs for TPF Application Requester Enhancements

DLM Stub New, Changed, or No Longer Supported?
CPGS New
CRDA New
CRDQ New
CRDR New
CREA New
CYYA New

General Use C Language Header Files

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

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

Table 234. Changes to General Use C Language Header Files for TPF Application Requester Enhancements

General Use C Language Header File New, Changed, or No Longer Supported? Do You Need to Recompile Segments?
c$ck2sn Changed Yes
c$dbrm.h New Yes
c$dbsac Changed Yes
c$dbsdc Changed Yes
c$icnv New Yes
c$icracb Changed Yes
c$iddmeq Changed Yes
c$idir Changed Yes
c$ifdo Changed Yes
c$irdicb Changed Yes
c$isddcb Changed Yes
c$ismtcb Changed Yes
c$isql Changed Yes
c$isqlmc Changed Yes
c$istpcb Changed Yes
c$tar0.h Changed Yes
timeinci Changed Yes
tpfar Changed Yes
tpfarapi Changed Yes

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

There are no changes.

Library Interface Scripts

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

Table 235. Changes to Library Interface Scripts for TPF Application Requester Enhancements

Library Interface Script New, Changed, or No Longer Supported? Description of Change
CISOXV Changed The CICONT, CSNAM, CCSIDC, and C390CN functions were added to support multiple CCSIDs.

Library Members (Object Files)

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

Table 236. Changes to Library Members (Object Files) for TPF Application Requester Enhancements

Library Member (Object File) Library Module Name New, Changed, or No Longer Supported? Type Description of Change
CCSIDC CISO New C Language Added support for iconv functional conversion of code pages.
CICONT CISO New C Language Added the iconv, iconv_open, iconv_close functions.
CRFB CTBX Changed C Language Added support for more robust wildcard character processing.
CRFG CTBX Changed C Language Added support for more robust wildcard character processing.
CSNAM CISO New C Language Added support for using multiple code pages at run time.
C390CN CISO New C Language Added support for byte conversions.

Link-Edited Modules

There are no changes.

Members (Object Files)

Table 237 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 237. Changes to Members (Object Files) for TPF Application Requester Enhancements

Member (Object File) DLM/DLL New, Changed, or No Longer Supported? Type Description of Change
CENTPT CPG0

CPG1

CPG2

CPG3

CPG4

CPG5

CPG6

CPG7

CPG8

CPG9

New C Language Changes made for NOVA/LEDT support.
CPGS CPGS New C Language Code added for code page list and tables.
CRDA CRDA Changed C Language Changes incorporating the set current package set; modifications for use with ISO-C support; implementation of dynamic SQL; updates for run-time binding.
CRDB CRDA Changed C Language Changes incorporating the set current package set; modifications for use with ISO-C support.
CRDC CRDA Changed C Language Changes incorporating the set current package set; modifications for use with ISO-C support; updates for run-time binding.
CRDE CRDA

CREA

Changed C Language Modifications for use with ISO-C support.
CRDF CRDA

CREA

Changed C Language Modifications for use with ISO-C support.
CRDG CRDA

CREA

Changed C Language Modifications for use with ISO-C support.
CRDH CRDA

CREA

Changed C Language Modifications for use with ISO-C support and support for multiple CCSIDs.
CRDI CRDA

CREA

Changed C Language Modifications for use with ISO-C support and support for multiple CCSIDs.
CRDJ CRDA

CREA

Changed C Language Modifications for use with ISO-C support; implementation of dynamic SQL; updates for run-time binding and support for multiple CCSIDs.
CRDK CRDA

CREA

Changed C Language Modifications for use with ISO-C support and support for multiple CCSIDs.
CRDL CRDA

CREA

Changed C Language Modifications for use with ISO-C support.
CRDM CRDA

CREA

Changed C Language Modifications for use with ISO-C support.
CRDN CRDA

CREA

Changed C Language Modifications for use with ISO-C support.
CRDO CRDU

CRDA

Changed C Language Added coding for expanded diagnostic support; modifications for use with ISO-C support.
CRDP CRDU

CRDA

Changed C Language Added coding for expanded diagnostic support; modifications for use with ISO-C support.
CRDQ CRDQ Changed C Language Modifications for use with ISO-C support.
CRDR CRDR Changed C Language Modifications for use with ISO-C support.
CRDS CRDA Changed C Language Implementation of run-time binding.
CRDT CRDA

CREA

Changed C Language Implementation of run-time binding.
CRDU CRDU Changed C Language Added coding for expanded diagnostic support.
CRDV CRDU Changed C Language Added coding for expanded diagnostic support.
CRDW CRDW Changed C Language Added coding for expanded diagnostic support.
CRDX CRDW Changed C Language Added coding for expanded diagnostic support.
CRDZ CRDA

CREA

Changed C Language Modifications for use with ISO-C support and support for multiple CCSIDs.
CREA CRDA

CREA

Changed C Language Modifications for use with ISO-C support; implementation of run-time binding; implementation of dynamic SQL.
CREB CRDA

CREA

Changed C Language Modifications for use with ISO-C support.
CREC CRDA

CREA

Changed C Language Modifications for use with ISO-C support.
CRED CRDA

CREA

Changed C Language Modifications for use with ISO-C support.
CREG CRDA

CREA

Changed C Language Modifications for use with ISO-C support.
CREH CRDA

CREA

Changed C Language Modifications for use with ISO-C support.
CREI CRDA

CREA

Changed C Language Modifications for use with ISO-C support and support for multiple CCSIDs.
CREJ CRDA

CREA

Changed C Language Modifications for use with ISO-C support; implementation of run-time binding; implementation of dynamic SQL.
CREK CRDA

CREA

Changed C Language Modifications for use with ISO-C support; implementation of run-time binding; implementation of dynamic SQL.
CREL CRDA

CREA

Changed C Language Modifications for use with ISO-C support.
CREM CRDA

CREA

Changed C Language Modifications for use with ISO-C support and support for multiple CCSIDs.
CREN CRDA

CREA

Changed C Language Modifications for use with ISO-C support and conversion of numeric representations.
CREO CRDA

CREA

Changed C Language Modifications for use with ISO-C support and implementation of dynamic SQL.
CREP CRDA

CREA

Changed C Language Modifications for use with ISO-C support and conversion of numeric representations.
CREQ CRDA

CREA

Changed C Language Modifications for use with ISO-C support and conversion of numeric representations.
CRER CRDA

CREA

Changed C Language Modifications for use with ISO-C support and conversion of numeric representations.
CRES CRDA

CREA

Changed C Language Modifications for use with ISO-C support and support for multiple CCSIDs.
CRET CRDA

CREA

Changed C Language Modifications for use with ISO-C support and conversion of numeric representations.
CREU CRDA

CREA

Changed C Language Modifications for use with ISO-C support.
CREV CRDA

CREA

Changed C Language Modifications for use with ISO-C support and conversion of numeric representations.
CREW CRDA

CREA

Changed C Language Modifications for use with ISO-C support and conversion of numeric representations.
CREX CRDA

CREA

Changed C Language Modifications for use with ISO-C support.
CREY CRDA

CREA

Changed C Language Modifications for use with ISO-C support.
CREZ CRDA

CREA

Changed C Language Modifications for use with ISO-C support.
CTOD CRDA

CREA

Changed C Language Changed the #pragma map name.
UAR1 CRDA

CREA

Changed C Language Changed commentary.

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

Table 238. Changes to Copy Members for TPF Application Requester Enhancements

Copy Member Type CSECT Where Copy Member Is Located New, Changed, or No Longer Supported? Description of Change
CCEB Control Program CCENBK Changed Modifications for hot cons.
CDR0 CCNUCL Changed Added the relational database name to the distributed data manager flow.
CDR1 Control Program CCNUCL Changed Added non-S370 numeric data formats to the distributed data manager flow.
CICS Control Program CCNUCL Changed Added the CATRDB field to the functional support console.
CRD5 Control Program CCNUCL Changed Modifications for use with ISO-C support.
CT15 Control Program CCCTIN Changed Sets an indicator to show an expanded SQL directory is in use.

Fixed File Records

There are no changes.

Macros

The following section summarizes the macro changes.

Advanced Program-to-Program Communications (APPC) Macros

There are no changes.

Communication Macros and Statements

There are no changes.

Data Macros

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

Table 239. Changes to Data Macros for TPF Application Requester Enhancements

Data Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs That Use This Data Macro?
CK2SN Changed Yes
CR0AT Changed Yes
IRDICB Changed Yes
ISDDCB Changed Yes
ISMTCB Changed Yes
ISTPCB Changed Yes
WO0RK Changed Yes

General Macros

There are no changes.

Selected Equate Macros

There are no changes.

Structured Programming Macros (SPMs)

There are no changes.

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

Table 240 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. See TPF System Generation for a complete description of the SIP skeleton and internal macros. 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 240. Changes to SIP Skeleton and Internal Macros for TPF Application Requester Enhancements

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 241 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. See TPF System Generation for a complete description of the SIP Stage II macros. 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 241. Changes to SIP Stage II Macros for TPF Application Requester Enhancements

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

System Communication Keypoint (SCK) Generation Macros

There are no changes.

System Macros

There are no changes.

System Macros (IBM Use Only)

Table 242 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 242. Changes to System Macros (IBM Use Only) for TPF Application Requester Enhancements

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

Segments

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

Table 243. Changes to Segments for TPF Application Requester Enhancements

Segment Type Link-Edit Module (Where Offline Segment Is Linked) New, Changed, or No Longer Supported? Description of Change
CSNMC Offline Assembler Not Applicable Changed Added for code page support.

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

Table 244 summarizes commad 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 244. Changes to Commands for TPF Application Requester Enhancements

Commnd New, Changed, or No Longer Supported? Description of Change
ZSQLD Changed Added the TPFCCSID and SELECT parameters.
ZSTTD Changed Added the DETAIL TRACE parameter.

Messages and System Errors

Table 245 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 245. Changes to Messages and System Errors for TPF Application Requester Enhancements

Message ID or System Error Number Message Type New, Changed, or No Longer Supported?
DB2P0001E Offline Changed
DB2P0002E Offline Changed
DB2P0003E Offline Changed
DB2P0003W Offline No Longer Supported
DB2P0004W Offline Changed
DB2P0005W Offline Changed
DB2P0006E Offline Changed
DB2P0006W Offline No Longer Supported
DB2P0007E Offline Changed
DB2P0007W Offline No Longer Supported
DB2P0008E Offline Changed
DB2P0008W Offline No Longer Supported
DB2P0009E Offline New
DB2P0010E Offline New
DB2P0053W Offline New
SQLD0012I Online No Longer Supported
SQLD0013I Online No Longer Supported
SQLD0017I Online New
SQLD0018I Online New
SQLD0081I Online New
SQLD0082E Online New
SQLD0083E Online New
SQLD0084E Online New
SQLD0085E Online New
SQLD0086I Online New
SQLD0087I Online New
SQLD0088I Online New
SQLD0089E Online New
SQLD0098E Online New

Performance or Tuning Changes

Run-time binding of program packages takes longer than static binding on an online system because of the binding process. The time difference depends on the number of packages being bound and the load on both the TPF 4.1 system and the remote systems so specific time differences vary. Once the program packages are bound, packages bound at run time perform the same as program packages that were bound statically.

Storage Considerations and Changes

There are no changes.

System Initialization Program (SIP) and System Generation Changes

The CK2ARIALL indicator was added to the CK2ARI field for SNA keypoint 2 to show when global tracing is active.

Loading Process Changes

There are no changes.

Online System Load Changes

There are no changes.

Publication Changes

Table 246 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 246. Changes to TPF Publications for TPF Application Requester Enhancements

Publication Title Softcopy File Name Description of Change
TPF Application Programming GTPAPP06 Updated with editorial changes.
TPF Application Requester User's Guide GTPARU02 Updated with information about using TPF Application Requester Enhancements.
TPF Library Guide GTPDOC06 Updated with definitions for new terminology in the master glossary.
Messages (System Error and Offline) and Messages (Online) Not Applicable Updated with information about messages and system errors that were added or changed for TPF Application Requester Enhancements.
TPF Migration Guide: Program Update Tapes GTPMIG06 Updated with migration considerations for TPF Application Requester Enhancements.
TPF Operations GTPOPR06 Updated with information about the commands that were added or changed for TPF Application Requester Enhancements.

Host System Changes

Determine whether mixed-byte data is required. If it is required, the appropriate character sets must be identified. If translation table support is needed beyond what is supplied by TPF Application Requester Enhancements, identify the translation tables needed and develop procedures for incorporating them in CSNAM and CPGS.

Run-time binding of program packages provides more freedom to move programs. This allows more flexibility in the program management system.

Application Programming Interface (API) Changes

The application programming interface (API) has changed with the addition of the dynamic SQL verbs and the support of double-byte and mixed-byte character sets.

Database Changes

There are no changes.

Feature Changes

Changes described in this chapter on migration relate to the TPF Application Requester (TPFAR) feature.

Installation Validation

Recompile an ISO-C program that was previously statically bound but do not send the database request module (DBRM) information to the database. The preprocessor will add the DBRM information to the end of the source program and it will be compiled into the object file. Load and run this program on the online TPF 4.1 system. The program will run normally. There is no notification that run-time binding is taking place. Run-time binding is seen in the SQL trace table with entries resulting in an SQL state of -805 immediately followed by a BIND verb.

Migration Scenarios

Use the following procedure to install TPF Application Requester Enhancements in your TPF 4.1 system.

  1. Make the appropriate changes to IBMPAL and SPPGML.
  2. Generate a new allocator.
  3. Make the appropriate control program (CP) changes.
  4. Update the SNAKEY macro and update keypoint 2.
  5. Generate a new control program.
  6. Build the CISO and CTBX libraries. If code page support is to be used, see the TPF Application Requester User's Guide for additional migration information.
  7. Build the stub library.
  8. Build the real-time programs and link them into dynamic load modules (DLMs).
  9. Load the new control program and DLMs to the TPF 4.1 system.
  10. Load keypoint 2.
  11. IPL the TPF 4.1 system again and bring it to NORM state. If the TPF Application Requester (TPFAR) feature was installed previously, observe the migration message prior to 1052 state. This occurs because the new SQL directory is larger than the previous one.
  12. Enter the ZSQLD command with the INIT parameter specified to set up the SQL directory.
  13. Enter the ZSQLD command with the ADD, RDB-rdb_name, and LU-lu_name parameters specified to indicate that CCSID 500 is valid on the remote database and the TPF 4.1 system.