gtpm2m14 | Migration Guide: Program Update Tapes |
The following section discusses the migration considerations for the Message Queue Interface (MQI) client.
See the APEDIT for APAR PJ22434 for information about prerequisite APARs.
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.
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.
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.
There are no hardware requirements.
The following section contains information about software requirements.
The following section summarizes the communication changes.
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.
The following section summarizes interface changes.
The following section summarizes C/C++ language changes. This information is presented in alphabetic order by the type of C/C++ language information. See the TPF C/C++ Language Support User's Guide and TPF Application Programming for more information about the C/C++ language.
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
There are no changes.
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 |
There are no changes.
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. |
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. |
There are no changes.
Table 206 summarizes changes to members (object files). This information is presented in alphabetic order by the name of the member (object file).
Notes:
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. |
There are no changes.
There are no changes.
There are no changes.
There are no changes.
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. |
The following section summarizes the macro changes. This information is presented in alphabetic order by the type of macro.
There are no changes.
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 |
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 |
There are no changes.
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 |
There are no changes.
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 |
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 |
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 |
There are no changes.
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 |
There are no changes.
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. |
There are no changes.
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.
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.
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). |
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 |
There are no changes.
There are no 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.
There are no changes.
There are no 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. |
There are no 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).
There are no changes.
There are no changes.
There are no changes.
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.
Migration is completed.