In December 2008, IMS introduced a brand new DL I call, ICAL, to enable an IMS application program to send a callout request to an external, non-IMS application program for data or service, and synchronously receive the response back during the same unit of work. This external program or service can run in a z/OS or distributed environment.
The ICAL call uses the AIBTDLI interface in IMS TM environments for IFP, MPP, BMP, JMP, and JPB regions. Because the ICAL call does not use the IMS message queue, callout requests and response messages are not constrained to the 32K message segment restriction. That means an IMS application using the ICAL call can send out a single large request data, such as a 1MB message, and receive a single large response data, such as a 3MB message. Figure 1 illustrates an example of using the ICAL call. In the example, a client application initiates a transaction to be processed by an IMS application. After the IMS application processes the transaction, it issues a DL/I call, ICAL, to get data from an external TCP/IP application via IMS Connect.Syntax of the New DL I Call
The new ICAL call has the following syntax:
The parameter aib specifies the application interface block (AIB) that is used for the call. See Table 1 for the parameters in the AIB that need to be initialized for the call. The request_area specifies the request area to use for this call. This request area contains the request message data that is sent from the IMS application program to the external application. The response_area specifies the response area for this call.
COBOL Example of the ICAL Invocation
CALL 'AIBTDLI' USING ICAL, AIB, CALLOUT-DATA, CALLOUT-RESPONSE.
COBOL Example of AIB Declaration
02 AIBRID PIC x(8) VALUE 'DFSAIB '.
02 AIBRLEN PIC 9(9) USAGE BINARY.
02 AIBSFUNC PIC x(8) VALUE 'SENDRECV'.
02 AIBRSNM1 PIC x(8) VALUE 'IMSCONN1'.
02 AIBOALEN PIC 9(9) USAGE BINARY VALUE 100.
02 AIBOAUSE PIC 9(9) USAGE BINARY VALUE 200.
02 AIBRSFLD PIC 9(9) USAGE BINARY VALUE 800.
02 AIBRETRN PIC 9(9) USAGE BINARY.
02 AIBREASN PIC 9(9) USAGE BINARY.
02 AIBERRXT PIC 9(9) USAGE BINARY.
• Because the ICAL call bypasses the IMS message queue, the LLZZ fields in the request data and the response data are no longer needed.
• The OTMA descriptor is used to define the callout destination for ICAL. You can have many different OTMA descriptors defined in the DFSYDTx member of the IMS.PROCLIB data set. In the upcoming IMS V11 release, these descriptors with IMS Connect destinations can be dynamically updated or added by using the IMS type 2 commands.
• When the timeout value is defined in both the AIB for the ICAL call and the OTMA descriptor, IMS will select the lower of the two as the timeout value for the ICAL call.
• An ICAL call cannot be issued from IMS in a shared-queues environment that is not connected to IMS Connect.
• The /DISPLAY ACTIVE REGION command can be used to display if a region is waiting for the completion of an ICAL call. The IMS /PSTOP and /STOP REGION ABDUMP commands can be used to stop the callout processing.
• The ICAL call is supported via IMS Version 10 APARs PK71135 and PK74168. To issue the ICAL call from a Java Dependent region, you also need PK75209.
• There are Installation Verification Program (IVP) samples for using the ICAL call in PK75824. You can also visit IMS Version 10 library and the Information Management Software for z/OS Solutions Information Center at http://public.boulder.ibm.com/infocenter/imzic for more information.
Feel free to let us know if you have any question about the IMS synchronous callout using the ICAL call.