The IMS TM Resource Adapter V10 callout IVP sample contains a message-driven bean that is designed to process both synchronous and asynchronous callout requests from sample IMS applications provided through IMS IVP APARs PK63661 and PK75824. These sample IMS applications and associated system setups for the required OTMA destination descriptors and the transaction pipes (tpipes) for queuing the request are provided through a series of IVP jobs and tasks.
IMS TM Resource Adapter V10 callout IVP samples
When an IMS application issues a request for data or services external to the IMS installation, the request is a callout request. If no response is expected or a response is expected to return as a different transaction, the request is an asynchronous callout request. If the request expects a response to return in the same transaction, the request is a synchronous callout request. From the perspective of WebSphere Application Server where the IMS TM resource adapter runs on to pull and process the request, a callout request from IMS is considered an inbound transaction.
To help the testing and demonstration of the IMS synchronous and asynchronous callout functions, a set of jobs and tasks in the installation verification program (IVP) are provided that you can run to quickly set up the required OTMA destination descriptors in the system definition. Two jobs are provided for you to run the provided IMS applications to issue callout requests.
Type of callout requests
OTMA destination descriptor
Part name for the COBOL application
Two simple IMS BMP applications are provided.
- One application uses the IMS DL/I testing program, DFSDDLT0, to issue a DL/I ICAL call for sending a synchronous callout request. This ICAL call specifies the tpipe for holding the callout request, the OTMA destination descriptor for routing of the callout message, and the request and response areas in the callout message.
- Another application uses the IMS DL/I testing program, DFSDDLT0, to issue an insert (ISRT) to an alternate PCB (program communication bolck) call to place the asynchronous callout request on the IVPPIPE3 tpipe.
The IMS TM Resource Adapter callout IVP sample is a simple message-driven bean that is installed with the IMS TM Resource Adapter V10.3 runtime installation and can be deployed to your WebSphere Application Server environment to verify that the MDB can receive either an asynchronous or synchronous callout request from an IMS application, and, in the case of a synchronous callout request, send a response back. This sample is designed to work with the IMS callout IVP samples, with the pre-defined tpipes and OTMA destination descriptors.
The general tasks involved to implement a callout solution for an IMS application are as follows:
|Task||Environment in which the task is performed||How the tasks are handled by the callout sample|
|Create or modify an IMS application to issue a callout request by using the DL/I ICAL call (synchronous) or ISRT altpcb call (asynchronous).||IMS host system||IMS callout sample IVP (APAR PK 63661 for the asynchronous callout IVP and PK 75824 for the synchronous callout IVP).|
|Define an OTMA destination descriptor||IMS host system|
|Restart IMS for the newly defined OTMA destination descriptor||IMS host system|
|Create a message-driven bean or J2C application to process the IMS inbound transaction.||Rational Application Developer (V7.5.2 or later recommended)
or other application development environments
|IMS TM resource adapter callout IVP sample (a pre-built message-driven bean in the IMS TM Resource Adapter V10.3 run time, available for download from this Web site.)
To create your own message-driven bean, IBM Rational Application Developer Version 7.5 information center has a tutorial that is designed to work with the IMS callout sample IVP.
|Deploy IMS TM Resource Adapter V10.3 runtime in WebSphere Application Server.||WebSphere Application Server||You must take these steps yourself in your WebSphere Application Server instance.|
|Configure a J2C activation specification in WebSphere Application Server to specify the connection information, such as the IMS host name, port number, data store name, and queue name (tpipe name) for IMS TM Resource Adapter to pull callout messages.||WebSphere Application Server|
|Deploy the message-driven bean or J2C application in WebSphere Application Server, and start the application.||WebSphere Application Server|
|Run the IMS application to issue the synchronous callout request or asynchronous callout request||IMS host system|
For more information about the synchronous callout function, see this document at http://www.ibm.com/support/docview.wss?rs=81&uid=swg27014351
Running the IMS TM resource adapter callout IVP sample
To run the IMS TM Resource Adapter Callout IVP, take the following steps:
1-5. Check the Prerequisites for running the IVP section that covers task 1 through task 5 that are described earlier.
Before you run the callout IVP, ensure that the following APARs are applied, and components are set up and running:
- Apply the required IMS and IMS Connect preconditioning APARs and activation APARs for the synchronous callout function:
- Preconditioning APARs: IMS APARs PK70078 and PK73224, and IMS Connect APAR PK70330.
- Activation APARs: IMS APAR PK71135 and IMS Connect APAR PK74168.
- Apply IMS APAR PK 63661 for the IVP jobs and tasks that verify the proper setup of asynchronous callout messages from IMS applications; apply IMS IVP APAR PK 75824 for the IVP jobs and tasks that verify the proper setup of synchronous callout messages from IMS applications.
- Ensure that WebSphere Application Server Version 6.1 with fixpack 188.8.131.52 or later is properly configured and running.
- Deploy the IMS TM resource adapter V10.3 RAR file in WebSphere Application Server. The instruction is available in the IMS TM Resource adapter documentation.
Tip: To create your own message-driven bean using IBM Rational Application Developer, Version 7.5.2 includes IMS TM Resource Adapter V10.3 and a tutorial. If you have an older version of Rational Application Developer Version 7, you must manually import the V10.3 RAR file in order to test the provided message-driven bean in its test environment.
You must set up the connection information for IMS TM Resource Adapter to pull callout messages and to reply with responses by configuring a J2C activation specification for the IMS TM resource adapter.
To use the IMS callout sample IVP that is provided with IMS V10 APAR 75824, the queue name (or tpipe) where synchronous callout requests are queued must be set to IVPPIPE4. You also need to obtain the IMS host name and port number where IMS Connect is running, and the data store name.
- Ensure that the WebSphere Application Server is started.
- On the welcome page's left panel, expand Resources > Resource Adapters. Click Resource adapters.
- Scroll to the bottom of the page and click the name of the IMS TM Resource Adapter V10.3 RAR file that you have installed. The General Properties page appears.
- In the General Properties page, in the right-hand column under Additional Properties, select J2C activation specifications.
- Click the New button and provide the following information:
- Name: Type in a name for the activation specification. For example, IMSICOCalloutIVP.
- JNDI Name: Type in a name, for example, eis/IMSICOCalloutIVP.
- Click Apply.
- At the top of the panel, click Save.
- Click the name of the activation specification that you just created, for example, IMSICOCalloutIVP. The configuration page opens.
- On the configuration page, in the right-hand column under Additional Properties, click J2C activation specification custom properties.
- Click each of the fields below to fill in the values to configure your activation specification.
- In the queueName row, click the existing value. In the configuration page that comes up, type:
IVPPIPE3,IVPPIPE4- if you want to verify both asynchronous and synchronous callout messages.
IVPPIPE3- if you want to verify asynchronous callout messages only
IVPPIPE4- if you want to verify synchronous callout messages only
- Click OK.
- In the HostName row, click the existing value. In the configuration page that comes up, type the hostname for your IMS Connect in the value field and then click OK.
- In the PortNumber row, click the existing value. In the configuration page that comes up, type 9999 in the Value field and then click OK.
- In the DataStoreName row, click on the existing value. In the configuration page that comes up, type your datastore name in the Value field and then click OK.
- In the queueName row, click the existing value. In the configuration page that comes up, type:
- Click Save at the top.
- Stop the server and then restart it to see the new activation specification. You now have created an activation specification for your RAR file.
Task 7. Deploy and start IMS TM Resource Adapter Callout IVP application
This section leads you to install the IMS TM Resource Adapter Callout IVP application EAR file and listen for IMS synchronous callout requests.
- On the welcome page of WebSphere Application Server, expand Applications and select Install New Application.
- Click Browse to navigate to the imsicocalloutivp.ear in the IMS TM Resource Adapter V10.3 zip or tar file that you have downloaded and then click Next.
- On the Select Installation options page, click Next.
- On the Map modules to Server page, click Next.
- On the last page, click Finish.
- To save your changes to the master configuration, click Save.
- On the welcome page's left panel, click Applications. Select Enterprise Applications.
- Select the checkbox of the new application (IMSICOCalloutIVPMDBEAR) that you just installed and click Start to run your application. You have now installed the IMS Callout IVP message-driven bean application on the WebSphere Application Server and ready to receive callout requests.
Task 8. Run the IMS host callout IVP application to issue a synchronous or asynchronous callout message
For asynchronous callout requests
Run the IV_S227J job as described in IV_S001T, which contains the introductory information asynchronous IMS Callout IVP application on the host. After the job executes, you should see the sample output as follows, which shows the request message as "HELLO FROM IMS":
SEGMENT =(0E00HELLO FROM IMS )
COMP RET CODE=OK
ALTPCB SOURCE/DEST=IVPDTOR3 RET CODE=
In addition, you can locate the following message in the WebSphere log or console to confirm that the IMS TM Resource Adapter Callout IVP MDB receives the asynchronous callout request from the host IMS Callout IVP application:
|SystemOut O Asynchronous callout request from IMS: HELLO FROM IMS
For synchronous callout requests
Run the IV_S228J job as described in the IMS Callout IVP application on the host. After the job executes, you should see a sample output as below which shows the request message "HELLO FROM IMS", and the response message "HELLO FROM WEBSPHERE MDB":
|CALL=ICAL SENDRECV IVPDTOR4 001000 00050 00050
0003 0003 0000
AIBOALEN = 0002, AIBOAUSE = 0002, AIBRSFLD = 003Y
SEGMENT =(HELLO FROM IMS )
CALL=ICAL SEGMENT = (HELLO FROM WEBSPHERE MDB )
COMP RET CODE=OK
In addition, you can locate the following messages in the WebSphere Application Server log or console to confirm that the IMS TM Resource Adapter callout IVP message-driven bean has received the synchronous callout request from the host IMS callout IVP application, and send a response message to the host IMS application:
|SystemOut O Synchronous callout request from IMS: HELLO FROM IMS
SystemOut O Synchronous callout response from WAS MDB: HELLO FROM WEBSPHERE MDB