gtpm2m14Migration Guide: Program Update Tapes

Message Queue Interface (MQI) Client (APAR PJ22434)

The following section discusses the migration considerations for the Message Queue Interface (MQI) client.

Prerequisite APARs

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

Functional Overview

This new function implements an MQSeries client on the TPF 4.1 system. With this function, TPF applications can now interact with MQSeries applications running on several different platforms using a messaging and queuing model for communication services. The MQSeries client gives TPF applications access to the standard message queue interface (MQI), supported by other MQSeries product offerings. A complete description of the MQI is contained in the MQSeries Message Queue Interface Technical Reference. Specifics about MQI clients is found in MQSeries Clients and MQSeries Distributed Queue Management Guide.

Architecture

This MQSeries client implementation is based on the standard MQSeries client server interface used by other MQSeries product offerings. An ISO-C interface is provided for the 11 functions that make up the MQI. The MQI client function is shipped as a new ISO-C library, with the 11 functions implemented as external functions in this library. The MQI client uses LU 6.2 sessions, through Common Programming Interface for Communications (CPI-C), to connect with remote MQI queue managers that are capable of running the MQ series function, therefore, a systems network architecture (SNA) connection between the TPF 4.1 system and MQ series system is required.

To support the MQI client, 5 new commands are provided. The ZMQID ALTER, ZMQID DEFINE, ZMQID DELETE, and ZMQID DISPLAY commands, which are used to maintain the MQI channel directory, and the ZMQIT command, which is used to assist in debugging MQI application problems.

MQSeries clients use MQI channels to communicate with MQ seriess. A channel definition must be created at both the MQI client and server ends of the connection. The MQI channel directory is where the TPF 4.1 system maintains a maximum of 50 channel definitions.

You can configure the TPF 4.1 system to run with a variable size MQI trace table by specifying the MQITRC keyword on the SNAKEY macro when defining keypoint 2 (CTK2). When the MQI trace table is defined to the TPF 4.1 system, all MQI function call requests and responses are logged to the table by the MQI client. The ZMQIT command can then be used to display entries in this table.

Operating Environment Requirements and Planning Information

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

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 summarizes the communication changes.

Operating Environment for SNA-Based Communication

The MQI client requires LU 6.2 sessions to establish connections with an MQ series. SNA network definitions must be updated to define the TPF 4.1 system and remote MQI queue manager to each other, before the MQI client can be processed successfully on the TPF 4.1 system. See TPF ACF/SNA Network Generation and TPF ACF/SNA Data Communications Reference for more information about how to define and start LU 6.2 sessions.

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 202 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 202. Changes to Build Scripts for the MQI Client

Build Script Type New, Changed, or No Longer Supported? Description of Change
CMQIBS DLM New Build script for the MQI client library.
CMQ1BS DLM New Build script for the function to initialize the MQI trace table.
CMQ2BS DLM New Build script for all functions required to process the ZMQID commands.
CMQ3BS DLM New Build script for all functions required to process the ZMQIT command.

Dynamic Load Module (DLM) Stubs

There are no changes.

General Use C Language Header Files

Table 203 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 203. Changes to General Use C Language Header Files for the MQI Client

General Use C Language Header File TARGET (TPF) ISO-C New, Changed, or No Longer Supported? Do You Need to Recompile Segments?
amqcccha.h   X New Yes
amqcciha.h   X New Yes
amqccxha.h   X New Yes
amqrfpha.h   X New Yes
amqrrcha.h   X New Yes
amqrriha.h   X New Yes
amqrrxha.h   X New Yes
amqxdvha.h   X New Yes
amqxecha.h   X New Yes
amqxeeha.h   X New Yes
cmqc.h   X New Yes
cmqxc.h   X New Yes
c$ck2sn.h X X Changed No
c$imqt.h   X New Yes
c$mqcd.h   X New Yes
c$mqpr.h   X New Yes
tpfparse.h   X Changed No

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

There are no changes.

Library Interface Scripts

Table 204 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 204. Changes to Library Interface Scripts for the MQI Client

Library Interface Script New, Changed, or No Longer Supported? Description of Change
CMQIXV New The library interface script for the MQI client library. An entry for each of the 11 MQI functions is contained in this library interface script.

Library Members (Object Files)

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

Table 205. Changes to Library Members (Object Files) for the MQI Client

Library Member (Object File) Library Module Name New, Changed, or No Longer Supported? Type Description of Change
CMCSLL CTAL Changed Assembler Added code to clear the LU 6.2 deallocation cleanup indicator field kept in the entry control block (ECB), before trying to allocate a conversation control block (CCB). This corrects a potential CTL-1 problem that can occur when a single ECB issues multiple CMINIT function calls.
CQCCCX CMQI New C Language The internal MQI client functions that interface with external communication services provided by the TPF 4.1 system.
CQCCIC CMQI New C Language The internal MQI client functions that interface with the TPF 4.1 system Common Programming Interface for Communications (CPI-C) functions.
CQCCMX CMQI New C Language The internal MQI client functions that manage memory allocations for communication services.
CQCLIB CMQI New C Language The internal MQI client functions that initialize communication services.
CQEXIT CMQI New Assembler The internal MQI client functions that activate the message channel agent (MCA) user exit functions.
CQREXT CMQI New C Language The internal MQI client functions that manage the MCA user exit interface.
CQRFPT CMQI New C Language The internal MQI client functions that implement the MQI client-server protocols.
CQRMSS CMQI New C Language The internal MQI client functions that initialize the MQI channel connection.
CQRREQ CMQI New C Language The MQI client external interface.

Link-Edited Modules

There are no changes.

Members (Object Files)

Table 206 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 206. Changes to Members (Object Files) for the MQI Client

Member (Object File) DLM/DLL New, Changed, or No Longer Supported? Type Description of Change
CMQI01 CMQ1 New C Language The function to initialize the MQI trace table.
CMQI03 CMQ3 New C Language All the functions required to process the ZMQIT command.
CNMQD CMQ2 New C Language Output message processing for the ZMQID commands.
CNMQI CMQ2 New C Language Input message processing for the ZMQID commands.
CNMQJ CMQ2 New C Language All the low level functions required to manage and display the MQI channel directory.

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

There are no changes.

Fixed File Records

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

Table 207. Changes to Fixed File Records for the MQI Client

Fixed File Record New, Changed, or No Longer Supported? Description of Change
#MQICD New The file storage required for the MQI channel directory. This fixed file record can be defined as either processor unique or processor shared.

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

Table 208 summarizes changes to the communication macros and statements. This information is presented in alphabetic order by the name of the communication macro or statement.

Table 208. Changes to Communication Macros and Statements for the MQI Client

Communication Macro or Statement New, Changed, or No Longer Supported? Do You Need to Reassemble Programs?
SNAKEY Changed Yes

Data Macros

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

Table 209. Changes to Data Macros for the MQI Client

Data Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs Using This Data Macro?
CK2SN Changed No

General Macros

There are no changes.

Selected Equate Macros

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

Table 210. Changes to Selected Equate Macros for the MQI Client

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 211 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 211. Changes to SIP Skeleton and Internal Macros for the MQI Client

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

System Initialization Program (SIP) Stage I Macros and Statements

Table 212 summarizes system initialization program (SIP) Stage I macro and statement changes. This information is presented in alphabetic order by the name of the SIP Stage I macro. See TPF System Generation for a complete description of the SIP Stage I macros. If the SIP Stage I macro is changed, you must run the appropriate job control language (JCL) jobs from the SIP Stage II deck.

See System Initialization Program (SIP) and System Generation Changes for a description of other system generation changes you must make.

Table 212. Changes to SIP Stage I Macros and Statements for the MQI Client

SIP Stage I Macro New, Changed, or No Longer Supported?
GENSIP Changed

System Initialization Program (SIP) Stage II Macros

Table 213 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 213. Changes to SIP Stage II Macros for the MQI Client

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

System Macros

There are no changes.

System Macros (IBM Use Only)

Table 214 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 214. Changes to System Macros (IBM Use Only) for MQI Client

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

System Communication Keypoint (SCK) Generation Macros

There are no changes.

Segments

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

Table 215. Changes to Segments for the MQI Client

Segment Type Link-Edit Module (Where Offline Segment Is Linked) New, Changed, or No Longer Supported? Description of Change
CSK0 Real-Time Assembler Not Applicable Changed Added code to display the MQITRC value from keypoint 2 (CTK2).
CTKS Real-Time Assembler Not Applicable Changed Added code to activate the MQI trace table initialization routine, which is CMQ1.
CVAB Real-Time Assembler Not Applicable Changed Added code to route the ZMQID and ZMQIT commands to CMQ2 and CMQ3 for processing.
FTVA03 Offline C Language FCTB Changed Check for the correct #MQICD RAMFIL definition.

System Equates

There are no changes.

User Exits

Standard MQSeries client support provides 3 user exits that allow you to customize the channel interface, security, send and receive. These exits are referred to as the message channel agent (MCA) exits. The TPF 4.1 system supports the MCA exits available to an MQI client.

The MCA exits are defined and enabled using the ZMQID ALTER or ZMQID DEFINE command. See TPF Operations for more information on how to define and enable the MCA exits on the TPF 4.1 system. See MQSeries Distributed Queue Management Guide and TPF System Installation Support Reference for more information about the MCA exit interface.

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 216 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 216. Changes to Commands for the MQI Client

Command New, Changed, or No Longer Supported? Description of Change
ZMQID ALTER New Alters the MQI channel directory entry.
ZMQID DEFINE New Defines the MQI channel directory entry.
ZMQID DELETE New Deletes the MQI channel directory entry.
ZMQID DISPLAY New Displays the MQI channel directory entries.
ZMQIT New Displays the MQI trace table entries.
ZNKEY Changed Added support to display the number of 4 KB pages defined for the MQI trace table (MQITRC keyword).

Messages and System Errors

Table 217 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 217. Changes to Messages and System Errors for the MQI Client

Message ID or System Error Number Message Type New, Changed, or No Longer Supported?
MQID0011I Online New
MQID0012I Online New
MQID0013I Online New
MQID0014I Online New
MQID0015I Online New
MQID0016I Online New
MQID0091E Online New
MQID0092E Online New
MQID0093E Online New
MQID0094E Online New
MQID0095E Online New
MQID0097E Online New
MQID0098E Online New
MQID0099E Online New
MQID0100E Online New
MQID0101E Online New
MQID0102E Online New
MQID0103E Online New
MQID0104E Online New
MQID0105E Online New
MQIT0001W Online New
MQIT0002W Online New
MQIT0003I Online New
MQIT0004I Online New
007600 System Error New
007601 System Error 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

The new CMQI library requires approximately 50 000 bytes in the core resident program area (CRPA) and 15 #XPRGn records. The three new ISO-C DLMs, which are CMQ1, CMQ2, and CMQ3, require approximately 36 000 bytes in the CRPA and 13 #XPRGn records. See TPF System Generation for more information on how to change the size of the CRPA or add #XPRGn records.

Loading Process Changes

There are no changes.

Online System Load Changes

There are no changes.

Publication Changes

Table 218 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 218. Changes to TPF Publications for the MQI Client

Publication Title Softcopy File Name Description of Change
TPF ACF/SNA Network Generation GTPACF05 Updated the description of the SNAKEY macro to include information about the new MQITRC parameter.
TPF Application Programming GTPAPP05 Updated with a high level description of the MQI client.
TPF C Language Support User's Guide GTPCLU05 Updated with list of the MQI functions and a pointer to the appropriate MQSeries publications.
TPF Library Guide GTPDOC05 Updated with definitions for new terminology in the master glossary.
Messages (System Error and Offline) and Messages (Online) Not Applicable Updated with information about the messages and system errors that were added for the MQI client.
TPF Migration Guide: Program Update Tapes GTPMIG05 Updated with migration considerations for the MQI client.
TPF Operations GTPOPR05 Updated with information about the commands that were added and changed for the MQI client.
TPF Programming Standards GTPPSM05 Updated with information about the C header files that were added for the MQI client and do not conform to TPF standards.
TPF System Generation GTPSYG05 Added information about the MQI channel directory.
TPF System Installation Support Reference GTPINR05 Updated with information about the ECB control program (CP) user exits that were added for the MQI client.

Host System Changes

There are no changes.

Application Programming Interface (API) Changes

The message queue interface (MQI) is now available to ISO-C programs. See MQSeries Message Queue Interface Technical Reference for a complete description of the message queue interface (MQI).

Database Changes

There are no changes.

Feature Changes

There are no changes.

Installation Validation

There are no changes.

Migration Scenarios

If TPF Advanced Program-to-Program Communications (TPF/APPC) is already installed on the TPF 4.1 system, you can install the MQI client by creating a new image and loading the new and changed programs to that image. See TPF ACF/SNA Network Generation and TPF ACF/SNA Data Communications Reference for information about how to install and configure TPF/APPC support.

  1. Enter the ZIMAG DEFINE command to define a new image using a new program base. See TPF Operations for more information about how to define a new image with the ZIMAG DEFINE command .
  2. Initialize the new image by doing one of the following:
    • Copy the old image to the new image using the ZIMAG COPY command. See TPF Operations for more information about how to copy an old image to a new image with the ZIMAG COPY command .
    • Perform a full load to the new image.
  3. Reassemble and recompile all required programs. (Required programs refers to the programs affected by changes discussed earlier in the description of the MQI client.)
    Note:
    The CRFA, CRFD, and CRFK C library source files must be recompiled to pick up the change made to the tpfparse.h C language header file, to increase the maximum size of the parsing grammar.
  4. Add the MQITRC parameter (valid values are 1 to 255 4 KB pages) to the SNAKEY macro definition in keypoint 2 (CTK2) and reassemble keypoint 2 (CTK2).
  5. Define space for the MQI channel directory by updating the SIP Stage I, defining a RAMFIL definition for 51 #MQICD records, using 4K spare records.
  6. Run the file address compute program (FACE) table generator and link the object module to create a new FCTB.
  7. Create a new system allocator (SALO) that includes the newly created CMQI, CMQ1, CMQ2, and CMQ3 segments.
  8. Recompile and run SALO to create an updated IPAT and SAL table.
  9. Run the library interface tool (LIBI) to create the function call stubs for the message queue interface (MQI).
  10. Link all the new and changed ISO-C libraries and DLMs, CMQI, CMQ1, CMQ2, CMQ3, CTAL, and CTBX.
  11. Define a load deck for the auxiliary loader (ALDR) that includes the following:
    • New or updated programs
    • Keypoint 2 (CTK2)
    • New FACE table (FCTB)
    • Updated IPAT.
  12. Run the auxiliary loader (ALDR).
  13. Perform a load to the new image using the ZTPLD command.
  14. Enable the new image by entering the ZIMAG ENABLE command.
  15. IPL the TPF 4.1 system and choose the new image as the active image.
  16. IPL any other TPF 4.1 systems that are defined in your complex using the new image as the active image.
  17. Define MQI channel directory entries for each MQI queue manager the MQI client will connect to with the ZMQID DEFINE and ZMQID ALTER commands. See TPF Operations and MQSeries Distributed Queue Management Guide for more information about defining MQI channel connections.

    Migration is completed.