gtpm2m26Migration Guide: Program Update Tapes

Mapping of Airline Traffic over Internet Protocol (MATIP) Enhancements (APAR PJ26693)

The following section discusses the migration considerations for Mapping of Airline Traffic over Internet Protocol (MATIP) enhancements.

Prerequisite APARs

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

Functional Overview

Mapping of Airline Traffic over Internet Protocol (MATIP) enhancements expands MATIP support that was previously shipped by providing a way to define a host descriptor table for Type-A and Type-B hosts. It does so by adding new parameters to the ZMATP command, new error messages, and a new user exit. See Mapping of Airline Traffic over Internet Protocol (MATIP) (APAR PJ26161) for information on MATIP support that was previously shipped.

If you are migrating from the original MATIP support on PUT 10 (APAR PJ26161) to these MATIP enhancements, you must define one or more host names in the new MATIP host name table by entering the ZMATP command to start MATIP client sessions with a remote host or workstation. Without an appropriate host name, the TPF 4.1 system is unable to obtain an Internet Protocol (IP) address that is needed to start the client session. In addition, you must modify the new MATIP host name user exit to locate the host name in the host name table that is used to start a specific MATIP client session.

Agent set control unit (ASCU) information was previously defined and changed through the MATIP ASCU user exit and the MATIP security user exit. Now you can also change and define ASCUs through the ZMATP command as well as associating ASCUs with a specific host name. The ASCU information is preserved on file so that it does not have to be specified again after the TPF 4.1 system is re-IPLed. The DISPLAY parameter of the ZMATP command has been enhanced to display various characteristics associated with a specific MATIP session.

Architecture

The architecture for MATIP enhancements is based on that for MATIP support, allowing for the management of Transmission Control Protocol/Internet Protocol (TCP/IP) wrappers around messages in legacy protocols. These wrappers allow the messages to be sent over TCP/IP networks. MATIP enhancements will continue to provide TPF server and TPF client capabilities in the three Societe Internationale de Telecommunications Aeronautiques (SITA) message types:

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 693 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 693. Changes to Build Scripts for Mapping of Airline Traffic over Internet Protocol (MATIP) Enhancements

Build Script Type New, Changed, or No Longer Supported? Description of Change
CMATBS DLL Changed Added the MATIP host name user exit, UMATCH, and the ZMATP TPF collection support (TPFCS) command handler.

Object Code Only (OCO) Stubs

There are no changes.

Dynamic Load Module (DLM) Stubs

There are no changes.

General Use C/C++ Language Header Files

Table 694 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 694. Changes to General Use C/C++ Language Header Files for Mapping of Airline Traffic over Internet Protocol (MATIP) Enhancements

C/C++ Language Header File New, Changed, or No Longer Supported? Do You Need to Recompile Segments?
c$iscfdt.h Changed No
c$trmeq.h Changed No

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

Table 695 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 695. Changes to Implementation-Specific C/C++ Language Header Files (IBM Use Only) for Mapping of Airline Traffic over Internet Protocol (MATIP) Enhancements

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

Library Interface Scripts

There are no changes.

Library Members (Object Files)

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

Table 696. Changes to Library Members (Object Files) for Mapping of Airline Traffic over Internet Protocol (MATIP) Enhancements

Library Member (Object File) Library Module Name New, Changed, or No Longer Supported? Type Description of Change
C511 COMX Changed C Language Updated to save the domain for child sockets.
C518 COMX Changed C Language Updated to bypass offload processing if information is available in the TPF 4.1 system.
C519 COMX Changed C Language Updated to bypass offload processing if information is available in the TPF 4.1 system.

Link-Edited Modules

There are no changes.

Members (Object Files)

Table 697 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 697. Changes to Members (Object Files) for Mapping of Airline Traffic over Internet Protocol (MATIP) Enhancements

Member (Object File) DLM/DLL New, Changed, or No Longer Supported? Type Description of Change
CMACMD DLL  Changed C Language Updated to access new control block structures that contain host names and ASCU information.
CMADAT DLL  Changed C Language Updated to access new control block information.
CMAP DLM  Changed C Language Updated to add support for new parameters on the ZMATP command.
CMATAB DLL  Changed C Language Allocated control block structures for host names and ASCUs.
CMATO2 DLL  New C Language Saves host names and ASCUs in TPF collection support.
CMIC DLL  Changed C Language Updated to add an additional parameter to the session manager function call.
CMOA DLM  Changed C Language Updated to use new control block structures.
CMOB DLM  Changed C Language Updated to use new control block structures.
CRII DLM  Changed C Language Enabled to use TCP/IP native stack support.
UMATCH DLL  New C Language MATIP host name user exit.
UMATSE DLL  Changed C Language Updated the sample code.
UMATSS DLL  Changed C Language Updated to add a comment to the prolog.

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

Table 698. Changes to Copy Members for Mapping of Airline Traffic over Internet Protocol (MATIP) Enhancements

Copy Member Type CSECT Where Copy Member Is Located DLM Where CSECT Is Located New, Changed, or No Longer Supported? Description of Change
CLXA  Assembler  CCCCP1 Not Applicable Changed Updated processing of the ROUTC macro.

Fixed File Records

There are no changes.

Macros

The following section summarizes the macro changes. This information is presented in alphabetic order by the type of macro.

Advanced Program-to-Program Communications (APPC) Macros

There are no changes.

Communication Macros and Statements

There are no changes.

Data Macros

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

Table 699. Changes to Data Macros for Mapping of Airline Traffic over Internet Protocol (MATIP) Enhancements

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

General Macros

There are no changes.

Selected Equate Macros

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

Table 700. Changes to Selected Equate Macros for Mapping of Airline Traffic over Internet Protocol (MATIP) Enhancements

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

Structured Programming Macros (SPMs)

There are no changes.

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

Table 701 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 701. Changes to SIP Skeleton and Internal Macros for Mapping of Airline Traffic over Internet Protocol (MATIP) 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 702 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 702. Changes to SIP Stage II Macros for Mapping of Airline Traffic over Internet Protocol (MATIP) 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)

There are no changes.

Segments

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

Table 703. Changes to Segments for Mapping of Airline Traffic over Internet Protocol (MATIP) Enhancements

Segment Type Link-Edit Module (Where Offline Segment Is Linked) New, Changed, or No Longer Supported? Description of Change
CMID Real-Time Assembler Not Applicable New Issues the CINFC macro to obtain the number of line numbers, interchange addresses, and terminal addresses (LNIATAs) in the TPF 4.1 system.

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 704. Changes to ECB User Exits for Mapping of Airline Traffic over Internet Protocol (MATIP) Enhancements

Function User Exit Activated In User Exit Program New, Changed, or No Longer Supported? Description of Change
MATIP Host Name User Exit CMACMD UMATCH New Selects remote hosts or modifies host record data areas for inbound and outbound sessions.

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 705 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 705. Changes to Commands for Mapping of Airline Traffic over Internet Protocol (MATIP) Enhancements

Command New, Changed, or No Longer Supported? Description of Change
ZMATP  Changed  Updated to add new parameters.

Messages and System Errors

Table 706 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 706. Changes to Messages and System Errors for Mapping of Airline Traffic over Internet Protocol (MATIP) Enhancements

Message ID or System Error Number Message Type New, Changed, or No Longer Supported?
MATP0017I Online New
MATP0018I Online New
MATP0019W Online New
MATP0020I Online New
MATP0021I Online New
MATP0022E Online New
MATP0023E Online New
MATP0024E Online New
MATP0025E Online New
MATP0026I Online New
MATP0027I Online New
MATP0028E Online New
MATP0029E Online New
MATP0030E Online New
MATP0031E Online New
MATP0032E Online New
MATP0055E Online Changed

Performance or Tuning Changes

There are no changes.

Storage Considerations and Changes

A specific area of the system heap has been allocated for MATIP enhancements such as the host name table and the LNIATA chain. The number of LNIATAs used in the host name table is the same as the number of LNIATAs configured in keypoint C.

File storage has been allocated for host name and ASCU information. The number of hosts is determined by using the number of hosts defined in the TPF collection support MATIP_DS database with half the number of host names added.

You can define the size of a core memory area (the MATIP Session Control Block (MSCB)) by using the ZNKEY command with the following parameters specified:

See TPF Operations for more information about the ZNKEY command.

System Initialization Program (SIP) and System Generation Changes

There are no changes.

Loading Process Changes

There are no changes.

Online System Load Changes

There are no changes.

Publication Changes

Table 707 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 707. Changes to TPF Publications for Mapping of Airline Traffic over Internet Protocol (MATIP) Enhancements

Publication Title Softcopy File Name Description of Change
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 MATIP enhancements.
TPF Migration Guide: Program Update Tapes GTPMG201 Updated with migration considerations for MATIP enhancements.
TPF Operations GTPOPR0B Updated with information about the commands that were added and changed for MATIP enhancements.
TPF System Installation Support Reference GTPINR0B Updated with information about the UMATCH user exit that was added for MATIP enhancements.

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

Before you can use MATIP enhancements you must complete the following two phases:

Analyzing Mapping of Airline Traffic over Internet Protocol (MATIP) Enhancements

To determine if you will be able to install MATIP enhancements in your TPF 4.1 system, do the following:

  1. If this is the first time that you have used MATIP, ensure that all the host names you are using are on the DNS nameserver before you install MATIP enhancements.

    If you have used MATIP addresses previously, see your network administrator to ensure that all host names are associated with the IP addresses in MATIP enhancements.

  2. Analyze your current available LNIATAs to determine which are used for MATIP devices and IP Bridge devices, and to create a list of these LNIATAs according to the following types:
    • Type-A conversational
    • Type-A conversational printer device
    • Type-A host-to-host
    • Type B
    • IP Bridge.
  3. Analyze your current applications that now send data across a non-IP network and will be used to send data across an IP network to a MATIP device or a IP Bridge device. Your applications will fall into one of the following categories:
    • Applications that use LNIATAs

      Applications that will be used to send data across an IP network issue a ROUTC macro with the LNIATA of the remote terminal or system in the RCPLDES3 destination field of the routing control parameter list (RCPL). The LNIATA used in the RCPL is classified as a MATIP or IP Bridge device by the ZMATP command when the TPF 4.1 system is started.

      The MATIP host name user exit, UMATCH, is used to associate LNIATAs with host names for MATIP sessions that do not have specified host names.

    • Applications that do not use LNIATAs

      Applications that do not use LNIATAs to send Type-A host-to-host or Type-B message traffic have the ability to set the RCPLORG destination field to contain a pointer to a host name of up to 255 alphanumeric characters that ends in a null character. The application enters the CMOA MATIP program for Type-A host-to-host traffic or the CMOB program for Type-B traffic. The host name is passed to an IP address when starting a Type-A host-to-host session or a Type-B session and a message is sent across the MATIP session. If MATIP is able to connect to the desired remote session, it returns the host ordinal (an index to the host name in the host name table) to the application after the session is started and the data is sent. The application passes that host ordinal number to RCPLDES on subsequent enters to the CMOA or CMOB programs when additional data is sent across the session.

  4. After analyzing your applications, make any changes necessary to enable them to run with MATIP enhancements.
  5. Continue with Installing Mapping of Airline Traffic over Internet Protocol (MATIP) Enhancements to install MATIP enhancements in your TPF 4.1 system.
  6. Note:
    The following configurations that were previously allowed in the original MATIP support on PUT 10 (APAR PJ26161) are not supported with MATIP enhancements:
    • Configurations that have a MATIP server communicating with a MATIP client on the same machine (LPAR).
    • Configurations where the server receives 2 connect requests from the remote client intended for multiple hosts on the same processor at the same time.

Installing Mapping of Airline Traffic over Internet Protocol (MATIP) Enhancements

To install MATIP enhancements in your TPF 4.1 system, do the following:

  1. Complete the procedure for Analyzing Mapping of Airline Traffic over Internet Protocol (MATIP) Enhancements.
  2. Install program update tape (PUT) 11.
  3. Ensure that TPF collection support (TPFCS) is installed. See TPF Collection Support (APAR PJ25098) and TPF Collection Support Enhancements (APAR PJ25332) for information about installing TPFCS.
  4. Code the MATIP host name user exit, UMATCH, listed in ECB User Exits to associate LNIATAs and host names when establishing a session as a TPF client. Update the application programs associated with the user exit if necessary.
  5. Define the MAXASCU and MAXMATIP parameters on the SNAKEY macro in keypoint 2 (CTK2). See TPF ACF/SNA Network Generation for more information about the SNAKEY macro.
  6. Compile or reassemble all DLL and DLM members as necessary. See Table 697 for information about the DLL and DLM members.
  7. Run the system allocator to include all the new segments added by MATIP enhancements. See Table 703 for information about the segments.
  8. Reassemble the CMID segment.
  9. Reassemble the CCCCP1 CSECT.
  10. Run the CBLD program to create the link-edit decks to the DLLs and DLMs.
  11. Link the DLLs and DLMs.
  12. Link the control program (CP).
  13. Load the following to your TPF 4.1 system:
    • Updated CP segments
    • New and updated DLMs and DLLs
    • New and updated assembler segments
    • Updated applications.
  14. Perform an initial program load (IPL) of the TPF 4.1 system.
  15. Cycle the TPF 4.1 system to CRAS state or above.
  16. Enter the ZBROW QUALIFY command with the SET parameter specified to view the TPF collection support database of host names using TPFCS browsing.
  17. Enter the ZDTCP command with the DNS and PRIMARY parameters specified to define the primary name server, or the DNS and SECNDRY parameters specified to define the secondary name server.
  18. Enter the ZMATP command with the DEFINE or ALTER parameter specified to define the necessary LNIATAs as MATIP devices or IP Bridge devices. When you enter the ZMATP command, refer to the list of LNIATAs that you created in step 2.

    If you want to define a host name and a list of agent set control units (ASCUs) you can enter either the ZMATP command with the DEFINE parameter specified or the MATIP host name user exit.

    If you want to add additional ASCUs to a defined host, you can enter either the ZMATP command with the ALTER parameter specified or the MATIP host name user exit.

    See TPF Operations for more information about the ZMATP command.

  19. Define the Internet daemon (INETD) listeners for MATIP devices and IP Bridge devices by entering the following ZINET ADD commands. If you are using a combination of MATIP Type-A, MATIP Type-B and IP Bridge devices, enter all of the commands in any order. If you are using one or two device types but not all three types, enter the command for the type of device.
    • For MATIP Type-A devices:

      ZINET ADD S-MATIPA MODEL-AOR AORL-4 PGM-CMIA PROT-TCP PORT-350 STATE-CRAS

    • For MATIP Type-B devices:

      ZINET ADD S-MATIPB MODEL-AOR AORL-4 PGM-CMIB PROT-TCP PORT-351 STATE-CRAS

    • For IP Bridge devices:

      ZINET ADD S-IPBRIDGE MODEL-AOR PGM-CRII PROT-TCP PORT-userport

    See TPF Operations for more information about the ZINET ADD command.

  20. Enter the ZNKEY command to verify that the MAXASCU and MAXMATIP parameters are defined. See TPF Operations for more information about the ZNKEY command.
  21. Do one of the following to activate MATIP enhancements for client sessions that are started by the TPF 4.1 system:
    • If the TPF 4.1 system is in CRAS state or above, define an individual host name by entering the ZMATP command with the DEFINE and RHOSTN parameters specified. To start a host name, do one of the following:
      • To start an individual host name, enter the ZMATP command with the START and RHOSTN parameters specified.
      • To start multiple host names, do one of the following:
        • Start each defined host name individually by entering the ZMATP command with the START and RHOSTN parameters specified.
        • Start all defined host names at the same time by entering the ZMATP command with the STOP parameter specified and then entering the ZMATP command with the START parameter specified.

      See TPF Operations for more information about the ZMATP command.

    • If the TPF 4.1 system is in 1052 state, cycle the TPF 4.1 system to CRAS state or above.
    Note:
    You do not have to start MATIP enhancements to use an IP Bridge device.