calling out from ims application programs · 2012-12-06 · calling out from ims application...

Issued: Dec 7, 2012

IBM® IMS®

Calling out from IMS application programs

Methods and best practices

Jack Yuan

Dave Cameron

Ken Blackman

Himakar Chennapragada

Ben Johnson

Calling Out from IMS application programs of 29


Table of contents Executive Summary............................................................................................. 4

Introduction .......................................................................................................... 5

Synchronous Callout using the ICAL DL/I call ............................................... 7

Synchronous Program Switch...................................................................... 8

Asynchronous Callout via OTMA................................................................... 10

Callout via ESAF ................................................................................................ 11

Synchronous callout to DB2 for z/OS via ESAF ...................................... 11

Synchronous callout to WebSphere MQ via ESAF ................................. 12

Asynchronous callout to WebSphere MQ via ESAF............................... 13

Callout using IMS-Managed ALTPCB............................................................ 14

IMS Callout Using APPC and CPI-C .............................................................. 15

Synchronous callout using the z/OS TCPIP protocol suite.......................... 17

Summary of all the IMS callout methods ....................................................... 19

Best practices for callout with the ICAL call .................................................. 20

Best practices for callout with IMS Enterprise Suite V2.2 SOAP Gateway 23

Best practices for synchronous program switch............................................ 26

Conclusion .......................................................................................................... 29


Executive Summary This article provides an overview and comparison of the various methods for configuring the IBM Information Management System (IMS) to enable IMS application programs to callout to other application programs or systems for data or services.

The article includes best practices for the more popular IMS callout methods, such as the ICAL call of the IMS Data Language/I (DL/I) interface.

The article also includes best practices for configuring the IMS Enterprise Suite SOAP Gateway to support callout requests.


Introduction

Today, enterprise IT architectures are made up of a variety of computer hardware and network configurations that support a wide variety of business applications and data repositories. To integrate and unlock the value of all of these different technologies and information sources, enterprises often turn to integration strategies such as Enterprise resource planning (ERP) systems and service oriented architectures (SOA).

In the context of ERP or SOA, IBM’s Information Management System (IMS), the premier enterprise transaction and hierarchical database management system, is both a platform for mission critical application programs as well as a repository of mission-critical data. With this dual role, IMS application programs can act as both providers and consumers of data and services.

IMS application programs consume data or services provided by other application programs or systems by issuing callout requests. These callout requests are critical to bridging the gap between the disparate platforms and systems in an ERP or SOA environment.

IMS supports a variety of different callout methods for both existing and new IMS application programs, allowing enterprises both to continue leveraging their significant existing IT investment and to meet new business requirements quickly and at lower costs.

This article provides an overview of 6 callout methods: • Synchronous callout using the new IMS DL/I ICAL call • Asynchronous callout using OTMA • Callout via external subsystem facility (ESAF) for WebSphere

MQSeries and DB2 • IMS program switch service using an alternate PCB • Callout with advanced program-to-program communications

(APPC) protocols and the open standards common programming interface for communication (CPI-C)

• Callout using the z/OS Communication Server TCP/IP protocol suite

Throughout the article, figures illustrate the callout methods to help you select the best method for your application programming environment.


A best practices section provides tips and guidance to improve throughput, failover implementation, application design, and redundancy, as well as to minimize resource contention. The best practices section also includes guidance for using IMS Enterprise Suite V2.2 SOAP Gateway for callout.


Synchronous Callout using the ICAL DL/I call IMS application programs can make a synchronous callout request by using the ICAL DL/I call. The ICAL call sends a callout request via OTMA, IMS Connect, and an IMS Connect client application. IMS Connect client applications that support synchronous callout include the IMS SOAP Gateway, the IMS TM Resource Adapter running in WebSphere Application Server, and user-written IMS Connect client applications.

The initiating IMS application program waits for the response in an IMS dependent region and sends the response back to the end-user client.

In this scenario that the IMS Connect client and the external data or service provider are outside of the IMS managed runtime environment. The exchange of data between these programs can occur within the IMS application program unit of work.

Figure 1. IMS Version 12 synchronous callout via OTMA and IMS Connect

The format of the ICAL call for a synchronous callout request is as follows:

>>-ICAL--aib---request_area---response_area-----------------><

The aib (application interface block) is where the options, or sub-functions, of the ICAL call are specified, along with the name of an OTMA

IMS-Appl GU IOPCB ICAL OTMA

Descriptor TMEMBER TPIPE IMS Connect

Socket

Message TCP/IP-B Resume_TPIPE READ_DATA(COR_ID) ACK SEND_DATA(COR_ID)

CLIENT

ISRT IOPCB

UOW1

UOW2

SEND_DATA RECEIVE_DATA


destination descriptor, any timeout value, the length of the data, and more. The sub-function for this request is SENDRECV.

OTMA destination descriptor

The information in the aib field contains the message-specific routing information and can be considered as a first level of specification for the processing of the request. The OTMA destination descriptor defines general routing information that can be used by multiple message requests. The OTMA destination descriptor can be considered a second level of routing specification.

OTMA destination descriptors are defined to IMS in the DFSYDTx member of the IMS.PROCLIB data set. You can dynamically create, modify, delete, or display the destination descriptors that route synchronous callout requests by using the IMS commands CREATE OTMADESC, UPDATE OTMADESC, DELETE OTMADESC, and QUERY OTMADESC.

Retrieving lengthy responses with the RECEIVE sub-function of the ICAL call

If the size of the response data that is returned is larger than the size of the response data buffer of an ICAL call, IMS truncates the response message to fit the response buffer, but saves the entire response message for later retrieval in case the entire response message is needed. To obtain the entire response message later, issue the ICAL call with the new RECEIVE sub-function.

The format of the ICAL with the RECEIVE sub-function is as follows:

>>-ICAL--aib—response_area-----------------------------------------><

Synchronous Program Switch Prior to IMS 13, IMS application programs could only perform a program switch by issuing two calls through the IMS DL/I interface: a CHNG call to an ALTPCB destination and an ISRT call to actually send the message. If the target IMS application program generated a response message, the response was sent back asynchronously to a different application program.


In IMS 13, IMS application programs can perform program switches, which are essentially callout requests from one IMS application program to another, with a single ICAL DL/I call and receive a synchronous response all in a single unit-of-work (UOW). This enhancement of the ICAL call in IMS 13 is referred to as the “synchronous program switch” enhancement.

Applying the synchronous callout model of the ICAL DL/I call to program-to-program communication between IMS dependent regions, if an application program in IMS 13 needs to make a program-to-program switch to a second IMS application program, instead of issuing the CHNG and ISRT calls, it issues a single ICAL call. The second, destination IMS application program can be in the same IMS system, in a shared-queues, back-end IMS running in the same z/OS sysplex, or in a remote IMS system connected by an IMS Multiple Systems Coupling (MSC) link. The application program that issues the ICAL call then waits to receive the synchronous response for processing in the same UOW. See Figure 2.

Figure 2. Synchronous program-to-program communication


The format of the ICAL call for a synchronous callout request and a synchronous program switch request are the same.

The request area is for the message data. For a synchronous program switch message, the data must start with a four-byte field that defines the length of the data in the standard IMS LLZZ format, followed by an 8-byte transaction code. For multi-segment transactions, which are defined to IMS with the MULTSEG keyword, the entire length of all segments of the transaction must fit into the request area of the ICAL call. The LLZZ format is required for each segment. The transaction code is only required in the first segment.

The response data is returned to the calling application program in the response area of the ICAL call. The response area also must begin with an LLZZ field that defines the length of the response data segment. If a segment of response data is too long to fit in the response area, the response data is truncated in the synchronous response, but also saved in its entirety for later asynchronous retrieval by another ICAL call that is issued with the RECEIVE sub-function specified.

For synchronous program switch support, the OTMA destination descriptor must be defined with TYPE=IMSTRAN specified. When TYPE=IMSTRAN is specified, additional optional keywords can be specified to define processing options for late response message and to override the logical terminal (LTERM) name provided to the target application program.

Asynchronous Callout via OTMA IMS application programs can make an asynchronous callout request via Open Transaction Manager Access (OTMA) by issuing an IMS DL/I ISRT call to an ALTPCB destination. The callout request is sent to an OTMA client, such as WebSphere MQ, that is defined in an OTMA destination resolution exit routine or an OTMA destination descriptor in IMS 13. The OTMA client passes the request to the external data or service provider.

The response to the callout request is processed as a new transaction by a different IMS application program that returns the response message to the end-user client. Because a different application program processes the callout response, the OTMA client or end-user application program needs


to handle the logic that is required correlate a response to its original callout request.

Figure 3. IMS Version 12 asynchronous callout via OTMA and IMS Connect

Callout via ESAF The IMS External Subsystem Attach Facility (ESAF) enables IMS application programs to access resources that are managed by other subsystems. ESAF can provide for synchronization of external subsystem data resources with IMS data resources. For synchronization processing, the IMS syncpoint manager is the coordinator and is responsible for directing commit or abort actions on behalf of the IMS application programs. When synchronization services are provided, external subsystems are participants in the process. As a participant, the subsystems commit or abort data updates by IMS application programs according to directions given by the IMS syncpoint manager.

Synchronous callout to DB2 for z/OS via ESAF An IMS application program can make synchronous callout requests to a DB2 for z/OS stored procedure by using ESAF. If IMS is the commit coordinator, IMS can coordinate the commit of the resources changed by the IMS application program and the called application program. Both

IMS-Appl GU IOPCB ISRT ALTPCB

OTMA Descriptor TMEMBER TPIPE IMS Connect

Socket

Message TCP/IP-B Resume_TPIPE READ_DATA ACK

CLIENT

ISRT IOPCB

UOW1

UOW2


application programs can participate in the same unit of work. In this scenario, because the response message to the end-user client is from the IMS application program in a single unit of work, the client does not know that two application programs were used to process the request. The client can obtain the results from the two application programs in the same unit of work.

The following figure shows an example of an IMS application program calling out to a DB2 stored procedure.

Figure 4. Synchronous callout using DB2 stored procedures via ESAF

Synchronous callout to WebSphere MQ via ESAF An IMS application program can use the WebSphere MQ application programming interface to establish synchronous callout processing with an external application program. The exchange of data between the two application programs can occur within the IMS application program unit of work. However changes to resources by both application programs cannot be coordinated. In this scenario, the client does not know that two application programs were used to process the request. The client can obtain the results from the two application programs in the IMS application program’s unit of work. The management of the UOW

The following figure shows an example of a synchronous callout to an external application program by using ESAF and WebSphere MQ.

Service

IMSA-PGMA GU IOPCB EXEC SQL:

CALL PROC ( :aaa : bbb … DB2 Stored Procedure User Defined Function (UDF)

Data

CLIENT

ISRT IOPCB

IMS Managed UOW1


Figure 5. Synchronous callout using WebSphere MQ via ESAF

Asynchronous callout to WebSphere MQ via ESAF An IMS application program can use ESAF and the WebSphere MQ application programming interface to send an asynchronous callout message to an external application program. The message is sent within the IMS application program unit of work during IMS syncpoint processing. However, changes to resources by both application programs cannot be coordinated. The response to the callout request is processed as a new transaction by a different IMS application program that returns the response message to the end-user client. Because a different IMS application program processes the callout response, the client or end-user application program needs to handle the logic that is required correlate a response to its original callout request. In this scenario, the UOW management is the same as IMS application program inserting to ALTPCB for program to program message switch or doing an asynchronous callout.

The following figure is an example of an asynchronous callout to an external application program by using ESAF and WebSphere MQ.

IMSA-PGMA GU IOPCB

MQCONN MQ-B MQPUT NO-SYNCPOINT

WAIT MQGET NO-SYNCPOINT

MB MQGET MQPUT MQDISC

WMQ Queue

Callout message

CLIENT

MQDISC ISRT IOPCB

WMQ-managed UOW2

IMS managed UOW1


IMSA-PGMAGU IOPCB

MQCONN MQ-BMQPUT –MQPMO_Syncpoint

MQDISC

MBMQGETMQDISC

Queue

WMQ

CLIENT

ISRT IOPCB

WMQUOW2

IMS SyncpointUOW1

CalloutMessage

Figure 6. Aynchronous callout using WebSphere MQ via ESAF

Callout using IMS-Managed ALTPCB The alternate program control block (ALTPCB) concept of IMS transaction manager (IMS TM) supports asynchronous callout requests to communication devices and application programs that are managed by IMS. An ALTPCB describes message destinations other than the terminal that originated the input message and provides transparency for the IMS application program and security for end-user messages. The IMS application program does not have to know the characteristics of the communication device or the network protocol when sending data.


Figure 7. IMS-managed ALTPCB callout

Figure 7 is an example of a two-stage, IMS-managed request where the IMS application program A (PGMA) uses the IMS DL/I ISRT call to the ALTPCB. This call invokes IMS application program B (PGMB). PGMB can be in the same IMS system or can be in another IMS system. Both PGMA and PGMB are independent units of work. In this scenario, even though the response message to the end-user client is from PGMB, the client does not know that two IMS application programs were used to process the request. The ALTPCB method of callout is used to provide an IMS-managed process flow of work.

IMS Callout Using APPC and CPI-C This method supports callout processing where IMS does not manage both application programs. IMS TM supports cooperative application processing using the IBM SNA LU 6.2 Advanced Program-to-Program Communications (APPC) protocol and the open standards Common Programming Interface for Communication (CPI-C). IMS preserves the existing application program interface to the ALTPCB via LU 6.2 descriptors. The descriptor associates the ALTPCB with an APPC application program to provide APPC asynchronous callout support. The IMS application program can also use the CPI-C interface for synchronous callout processing.

IMSA-PGMA GU IOPCB ISRT ALTPCB

IMSA/IMSB(MSC) PGMB

TRANCODE – Dynamic Resource Descriptor/DFSINSX0 CRE TRANDESC NAME(TRANB) PGM(PGMB)

GU IOPCB ISRT IOPCB

CLIENT

UOW1

UOW2


Figure 8. Asynchronous callout processing using SNA LU 6.2

Figure 8 is an example of a two-part APPC protocol using asynchronous callout processing. For an asynchronous callout request, the IMS application program does an ISRT to the ALTPCB to send data to an application program that is defined in the IMS managed LU6.2 descriptor. The APPC/IMS function allocates a conversation to the partner program (for example, TP-A), sends the data, and deallocates the conversation.

Each of these programs is an independent unit of work. IMS PGMA is not able to process any results from the partner program in the same IMS unit of work. In this scenario, because the response message to the end-user client from PGMA occurs in the first unit of work, the client cannot obtain the results from the two application programs in the same unit of work.

IMSA-PGMA GU IOPCB

ISRT ALTPCB

APPC/IMS CMALLC Allocate TP-A Type=NONE/CONFIRM CMSEND SEND_DATA CMDEAL DeAllocate

ConversationA

APPC/IMS asynchronous callout

CLIENT

UOW1

IMS LU6.2 Descriptor

UOW2

CPI-C TP-A CMRCV CMSEND CMDEAL


Figure 9. Synchronous callout processing using SNA LU 6.2

For a synchronous callout request the IMS application program can use the open standard CPI-C interface to establish connectivity to an application program and exchange data. Both application programs can participate in the same unit of work. In this scenario, since the response message to the end-user client is from PGMA, the client does not know that two application programs were used to process the request. The client can obtain the results from the two application programs in the same unit of work.

Synchronous callout using the z/OS TCPIP protocol suite Users can write IMS application programs that interface directly with the TCP/IP protocol suite that is provided by the z/OS Communication Server to make synchronous callout requests. This user-written callout method is outside of the scope of the IMS-managed runtime environment. The exchange of data between the two application programs can occur within the IMS application program unit of work. However, changes to resources by both application programs cannot be coordinated. The following figure shows an example of this user-written technique.

IMSA-PGMA GU IOPCB

ISRT ALTPCB

CLIENT

ISRT IOPCB

CPI-C/APPC synchronous calloutCMALLC Allocate TP-B Type=NONE/CONFIRM/SYNCPT CMSEND SEND_DATA CMRCV RECEIVE_and_WAIT CMDEAL DeAllocate

ConversationB

UOW1

CPI-C TP-B CMRCV CMSEND CMDEAL


Figure 10. Synchronous callout with user-written client that uses the z/OS TCP/IP sockets interface

READ_DATA WRITE_DATA CLOSE

Socket Connect - TCP/IP-B WRITE_DATA READ_DATA CLOSE

TCP/IP-B READ_DATA Socket Connect -TCP/IP-C

Connection

datagrams

CLIENT IMSA-PGMA GU IOPCB

ISRT IOPCB

UOW1

UOW2


Summary of all the IMS callout methods Among the variety of callout methods that are supported by IMS, some support only asynchronous callout, some support only synchronous callout, and one method, APPC and CPIC, can be configured to support either asynchronous or synchronous callout.

Callout using the ESAF interface to DB2 is the only callout method that supports coordinated commits or backouts.

The following table shows the key functionalities supported by each callout method.

Function Method

Asynchronous Communication

Synchronous Communication

Coordinated Commit and rollback

IMS program switch

APPC/ CPI-C

z/OS TCP/IP stack

ESAF to MQ

ESAF to DB2 for z/OS ALTPCB OTMA

ICAL call

Table 1. Key functionalities supported by each callout method

Similar to the functionalities that they support, each callout method supports different service providers depending on the protocols, components, or products that they used.

The ICAL call of the IMS DL/I interface supports the widest variety of callout service providers.

The following table shows which service providers are supported by each callout method.


Target Method

IMS Appl.

APPC/ CPI-C Appl.

DB2 for z/OS Appl.

MQ Series Appl.

Websphere Appl. with TMRA

TCP/IP Appl.

SOAP Appl. with Soap Gateway

Datapower Appl.

IMS program switch

* * *

APPC/ CPI-C

z/OS TCP/IP stack

ESAF to MQ

ESAF to DB2 for z/OS

ALTPCB OTMA

ICAL call * * *

* The IMS application calls the service provider indirectly. Table 2. Some of the supported service providers and environments

Best practices for callout with the ICAL call

Maximize throughput When IMS application programs use the ICAL DL/I call to make callout requests, the target data or service provider must retrieve the callout requests from IMS by using the OTMA Resume TPIPE protocol. After retrieving the callout request, the service provider must acknowledge the receipt of the callout request before another callout request can be sent for that destination. This provides integrity for the callout requests but also serializes their delivery. To maximize the throughput of callout processing, the service provider can implement a dedicated thread for request retrieval that will then spawn processing threads to service the request and send the callout response on separate sockets. This allows for concurrent processing of the requests and sending the responses. IMS


SOAP Gateway and a message-driven bean (MDB) that uses the IMS TM Resource Adapter are both designed this way.

Implement failover protection for the IMS callout service provider IMS synchronous callout requests are highly time sensitive as they tie up an IMS dependent region and its associated resources. If the currently active service provider fails, waiting for a restart will delay callout requests and can seriously impact IMS processing.

The ICAL DL/I call method of synchronous callout uses the OTMA Resume TPIPE protocol to retrieve the callout requests for a specific callout destination, which is represented in IMS by a TPIPE. Only one Resume TPIPE can be active for a given destination; however, IMS supports failover by allowing Resume TPIPE requests for a specific destination to be queued. After the active Resume TPIPE is satisfied or fails, a queued Resume TPIPE becomes active and can immediately be send callout requests. This minimizes the delay in sending callout requests.

Design synchronous callout applications to minimize resource contention IMS applications can send callout requests to external service providers using either asynchronous or synchronous callout. Asynchronous callout requests are queued by IMS and forwarded independently of the application processing. Synchronous callout requests however are processed immediately and the IMS application waits for the callout response before proceeding. This means the application remains in the IMS dependent region and will be holding any resources that it has acquired to that point. The impact of these locked resources can be minimized by issuing any synchronous callout requests as early as possible in the transaction processing. The synchronous callout request also allows for setting a timeout value so if the callout response is delayed the IMS application will receive return and reason codes indicating the timeout and the application can decide whether to proceed without the callout information or to retry the callout request. The timeout value must be balanced between allowing sufficient time for the callout request to be processed and protecting the IMS dependent region from being held up. When many IMS applications use synchronous callout, especially with slow external service providers, it may become necessary to increase the


number of IMS dependent regions. This comes with the concerns of more resources and greater chances for resource contention.

Implement redundancy in your ICAL callout configurations IMS callout service providers can be configured to provide failover so that if one instance of the service provider fails, another instance can immediately continue processing callout requests. Only one instance of the service provider will be sent callout requests and the others will be idle waiting for failover. This redundancy is particularly important for synchronous callout requests, which are very time sensitive. The multiple instances of the service provider can use Sysplex Distributor to connect to multiple instances of IMS Connect. All of the IMS Connect instances must be configured to have the same DataStore names resulting in the same IMS systems. The service providers need to make retrieval requests (using Resume TPIPE) to each IMS that will be issuing callout requests. Synchronous callout requires that the callout response be routed back to the same IMS system that issued the callout request although a separate socket and IMS Connect can be used.

Manage high volume and multiple destinations with OTMA destination descriptors OTMA destination descriptors are optional for OTMA asynchronous callout and are mandatory for synchronous callout with the ICAL DL/I call. The descriptors determine the destination for the callout requests, which must match the destination the service provider sets on the retrieval request (Resume TPIPE).

When there are many callout requests being processed by a single service provider, they can all be routed to a single destination by coding the same TMEMBER and TPIPE on multiple descriptors. If the destination names are similar, application programs can use a wild card character when specifying the descriptor name so that its callout request can be routed to any destination that matches the portion of the name that is not masked by the wildcard character.

If high volumes of callout requests are anticipated then the service provider should make retrieval requests to different destinations and separate descriptors can be used to route callout requests to these separate destinations. This can improve throughput, but might add complexity to the IMS applications.


Best practices for callout with IMS Enterprise Suite V2.2 SOAP Gateway SOAP Gateway supports both inbound traffic to and outbound traffic from IMS via IMS Connect and OTMA. In the inbound scenario, IMS transactions are exposed as SOAP Gateway web services. In the outbound scenario, SOAP Gateway supports callout requests from IMS applications to external web services. This section provides some best practices that can help you get the most out of your callout usage with SOAP Gateway.

SOAP Gateway supports both synchronous and asynchronous callout requests from IMS.

Figure 11. Callout configurations with IMS Enterprise Suite SOAP Gateway

Here are a few best practices and tips to consider when implementing a callout solution with SOAP Gateway.

Use the one-way notification option for asynchronous callout when a response is not required If the IMS application program does not need the response from an external web service provider, you can use the asynchronous one-way notification option, which does not return a response to IMS. A usage

Web service provider

(E.g. Microsoft .Net)

IMS Enterprise

Suite SOAP

Gateway

IMS

Sync: ICAL IMS Application 1

Async: ISRT ALTPCB

Callout Request

Sync Callout Response

IMS Application 2 IMS Connect

Async Callout Response (optional)

OTMA

Send Flow

Receive Flow

SOAP Gateway Asynchronous and Synchronous Callout

SOAP Request

SOAP Response


scenario would be when the IMS application sends a broadcast message to an external web service and doesn't necessarily care or expect any response. In this case, manually delete the “output” element from the “operation” element from your WSDL followed by the use of the "meet-in-middle" wizard in Rational Developer for System zTM to generate the artifacts.

Use One Thread Per Tpipe For better performance, use the "One Thread Per Tpipe" thread policy to establish a dedicated callout thread for each Tpipe (OTMA Hold Queue) to listen for and process callout messages. This policy reduces network traffic by sending only a single Resume Tpipe request at start when the callout thread is started and receives and acknowledges new callout requests repeatedly without needing to issue a Resume Tpipe request for each new request. This thread policy enhances performance and prevents callout messages from sitting on the Tpipe without being processed. It also reduces the chance of the IMS application programs timing out while it waits for a response.

Use separate instances of SOAP Gateway for inbound and outbound traffic If you are considering using SOAP Gateway for both outbound callout requests and inbound IMS transactions, use a separate instance of the SOAP Gateway server for each purpose. This setup creates a clean separation of inbound and outbound traffic and improves server manageability.

Configure multiple connection bundles per callout service Starting IMS Enterprise Suite V2.2 SOAP Gateway, you can configure multiple connection bundles per callout service. SOAP Gateway can be configured to talk to multiple data stores or multiple IMS Connect instances. This feature lets you reuse IMS callout applications, converters, or destination routing descriptors among different IMS instances without having to make cumbersome, duplicate deployments across different systems.

Avoid frequent or unnecessary polling for callout requests When using the "One Thread Per Tpipe" thread policy, to avoid frequent polling and to reduce the amount of errors that might occur when IMS


Connect or IMS is down, you can configure the SOAP Gateway “should_stop_on_error callout” property to stop the callout threads when an error occurs, or change the “callout_tpipe_poll_interval callout” property to be a higher value (for example, once in 60 minutes). The poll interval kicks in when errors occur on the callout thread with the "One Thread Per Tpipe" thread policy. It controls how long to pause the callout thread before polling for messages on the Tpipe again. These callout properties can be configured using the SOAP Gateway management utility.

Use different Tpipes for secured and unsecured callout requests If you will be calling out to both secured and unsecured external web services, you must ensure that the secured and unsecured callout requests are sent on different Tpipes.

If debug logs are not available, create a file of diagnostic information In production, if problems occur and debug logs are not available, you can dump the diagnostic information to a file that can then be provided to IBM support for further investigation when you open a PMR. The number of entries in the file is set by “thread_pool_cache_capacity” callout property and the location of the file is controlled by the “thread_pool_cache_dump_location” callout property. These properties can be configured using the SOAP Gateway management utility.

Balance threads for throughput against resource consumption You can increase the number of worker threads to up to 32 threads (default is 5) for faster callout message processing. You must carefully consider the impact this configuration could have on system resources. More threads may not always mean faster throughput under all circumstances.

Use multiple instances with Sysplex Distributor for failover protection To support failover, you can add a Sysplex Distributor between SOAP Gateway and IMS Connect and also between SOAP Gateway and the external web servers. Of course, you can have multiple SOAP Gateway instances talking to multiple IMS Connect instances that in turn talk to multiple IMS instances. If one system fails, the others can take over while


the Sysplex Distributor continues to distribute requests over to the remaining active systems. When the failed system recovers and becomes active, normal operations will resume.

Define timeout intervals for web services based on response times SOAP Gateway callout services have a timeout property that can be adjusted to suit the various response speeds of different web services. This property provides a very granular setting for timeout processing per service. When configuring timeouts, analyze the overall time it might take for a request to go from IMS to the external web service and receive the response from the external web service to IMS. The callout web service timeout is set by the “callout_web_service_timeout” property in the correlator for each callout service and can be configured by using the SOAP Gateway management utility. The default is 7500 ms.

Best practices for synchronous program switch The following series of best practices are for IMS application programs that callout to other IMS application programs by using the ICAL DL/I call to initiate a synchronous program switch. These best practices can help you get the peak performance out of your synchronous program switches.

Monitor synchronous program switch processing To check on the number of ICAL synchronous program switch requests that are currently active and waiting for a response in an IMS system, use the /DISPLAY OTMA command. A large number of active synchronous program switch requests might indicate a problem and an excessive use of IMS dependent regions.

The active synchronous program switches are displayed in the command output as DFSYICAL information. The number of synchronous program switches that are currently active in the IMS system is displayed in the TIB column. If DFSYICAL rows are not included in the command output, the IMS system has not processed any ICAL synchronous program switch requests.

Minimize resource contention After an IMS application issues an ICAL call for a synchronous program switch, it waits in the IMS dependent region until either the response is received from the target transaction or the timeout interval expires. While


waiting, all of the resources that the application program has accumulated during the current unit of work are held.

To avoid excessive resource contention, have the application program issue the ICAL synchronous program switch as early as possible, before too many resources are obtained. The target transactions are commonly related to the originating transaction and therefore are likely to access the same customer data, which can lead to lock contention. If lock contention occurs, the ICAL call that issued the synchronous program switch can time out. The originating transaction can choose to rollback the changes, which would free the resources for the target transaction; however, any updates by the target transaction will still be committed.

Define an appropriate number of IMS dependent regions Both the initiating application program and the target application program of the synchronous program switch run in separate IMS dependent regions. The target application program can even initiate its own program switch, which would require another IMS dependent region. Be sure to start an adequate number of dependent regions for the appropriate transaction classes so that the target transactions can be processed without having to wait for a dependent region to free up. If a target transaction must wait to be processed, it increases the chance that the ICAL call will timeout before the response is received. Also, if the target transactions are running in an IMS shared queues or Multiple Systems Coupling (MSC) environment, be sure that the additional dependent regions are defined in the IMS systems where the target transactions will run.

Define appropriate timeout values on the ICAL call The timeout value that you specify on an ICAL call for a synchronous program switch should be large enough to allow for the scheduling and processing of the target transaction(s) and the return of the response, particularly in IMS shared queues, MSC, or multiple program switch configurations; however, timeout values should not be so large that that they allow the dependent region resources of the issuing application program to be tied up for an excessive amount of time. On the other hand, a timeout value that is too small can lead to a scenario in which the initiating transaction times out, but the target transaction is still processed.


A timeout value that is specified on the ICAL call does not apply to the target transaction after the target application program receives it or if the target transaction is queued to an MSC link.

Manage the commits, backouts, and timeouts of the independently executing caller and target application programs The work performed by an application program that initiates a synchronous program switch is processed as a separate unit-of-work from the work performed by the target transaction. The target transaction runs “during" the originating transaction's unit-of-work, but is not part of it. The originating transaction can be part of a protected conversation (RRS) but the target transaction will be executed outside of that. If the ICAL times out, the target transaction may still run successfully and commit updates.

After the response from the target transaction has been returned to the ICAL call, any subsequent abend or rollback of the originating transaction will back out only the updates made by the originating transaction, but not the updates made by the target transaction, which have already been committed. If the originating transaction is rescheduled, then the target transaction will be run again unless the application accounts for this.

In the event that the updates by a target transaction are committed when the updates by the original transaction are backed out, you can reroute the late response to an alternative destination for any required corrective processing.

You can route late responses by using the Message Control/Error exit routine (DFSCMUX0) or, if you are routing late responses through IMS Connect, you can set the alternative destination by using the TMEMBER and TPIPE parameters of an OTMA destination descriptor.

Manage response messages from multiple program switches The target application program of an ICAL call can in turn initiate its own synchronous or asynchronous program switch. When this happens, multiple response messages can be returned to the application program that issued the ICAL call. If the initiating transaction can be satisfied by a response from any one of the switched-to application programs, you can configure IMS to return only the first response message with the ICAL call


and to either discard or reroute the rest by specifying REPLYCHK=NO the OTMA destination descriptor.

If necessary, build OTMA message headers with the DFSYIOE0 routine If an OTMA destination descriptor is configured to route late response messages to an OTMA client, but the original transaction that initiated the synchronous program switch was not submitted by an OTMA client, you can build the required OTMA user data prefix in the late response message when the message is about to be sent to the OTMA client by using the OTMA Input and Output Edit user exit routine (DFSYIOE0). IMS initializes the 1024-byte user data prefix with zeroes so that DFSYIOE0 exit routine can override it with the client-specific user data. In IMS 13, DFSYIOE0 includes sample code for this purpose.

Conclusion One of the things that makes IMS so powerful and long-lived is the many options that it provides for customizing IMS to your unique business needs and IT architectures. IMS provides so many options, in fact, that knowing what the relative merits of each are and when to use one option over another can be a daunting challenge.

This article presented the various callout options that IMS provides so that you can make informed decisions about the best and most efficient way to integrate IMS with the many disparate application platforms and data and service providers that make up the enterprise IT architectures of today.

calling out from ims application programs · 2012-12-06 · calling out from ims application...

Documents