IMS solutions: Utilizing the IMS synchronous callout function to invoke a CICS Web service through IMS SOAP Gateway

This article uses a sample scenario to demonstrate how to use the synchronous callout function of IMS™ to invoke an existing CICS® Web service through the IMS SOAP Gateway. The scenario takes an existing IMS application written in COBOL and enhances it to request additional information from an existing CICS Web service. The article provides an overview of the sample configuration, code samples, and step-by-step instructions on how to generate necessary artifacts. The article also provides information on how to troubleshoot problems you may encounter while recreating the scenario.

Share:

Kevin Hite (khite@us.ibm.com), IMS Solution Test, IBM

Kevin Hite photoKevin Hite is a software engineer working on the IMS Performance Test team. He is involved in integrating, analyzing and tuning the performance of new IMS features in customer-like applications and environments which utilize a wide range of IBM tools and products.



Shavia Jones (jonesps@us.ibm.com), Problem Determination Tools Solution Test, IBM

Shavia Jones photoShavia Jones is a software engineer at IBM's Silicon Valley Laboratory in San Jose, California and works on the Problem Determination Tools Solution Test team. Her role is to develop and execute use cases that exploit the Problem Determination Tools to validate that they work well from a client perspective when used together in a client-like environment.



John Tao (zhong@us.ibm.com), Problem Determination Tools Solution Test, IBM

John Tao photJohn Tao is a software engineer at IBM's Silicon Valley Laboratory in San Jose, California and works on the Problem Determination Tools Solution Test team. His role is to develop and execute use cases that exploit the Problem Determination Tools to validate that they work well from a client perspective when used together in a client-like environment.



Alan Villarreal (alan@us.ibm.com), Problem Determination Tools Solution Test, IBM

Alan Villarreal photoAlan Villarreal is a software engineer at IBM's Silicon Valley Laboratory in San Jose, California and works on the Problem Determination Tools Solution Test team. His role is to develop and execute use cases that exploit the Problem Determination Tools to validate that they work well from a client perspective when used together in a client-like environment.



19 March 2009

Also available in Chinese

Introduction

This article describes how to implement synchronous callout in an IMS application to invoke an existing CICS Web service through the IMS SOAP Gateway.

IMS synchronous callout function

The IMS synchronous callout function enables an application program running in an IMS V10 dependent region to send outbound messages that request services or data from outside the region. The request for services or data is referred to as a callout request. For a synchronous callout request, an IMS application program that runs in an IMS dependent region issues an IMS DL/I call (ICAL call) and waits in the dependent region to process the response. The outbound messages can be sent to a Web service, a message-driven bean (MDB), or an Enterprise JavaBeans (EJB) component. The Resources section of this article contains links to additional background information about IMS V10 synchronous callout.

Scenario overview

The article uses a sample scenario that begins with an IMS application written in COBOL. The interface to the application is 3270 terminal-based and utilizes an IMS MFS screen titled Additional Customer Information. The requirement for the scenario is to enhance the application by requesting more customer information from an existing CICS Web service that retrieves customer and policy information.

Implementation approach

In order for the IMS application to leverage the CICS Web service, it utilizes the new IMS DLI ICAL call. The ICAL call enables IMS to synchronously call out to internal and external services.

There are several options to consider when implementing IMS synchronous callout. The implementation in the scenario use the IMS SOAP Gateway.

Figure 1 below illustrates the topology of an IMS synchronous callout implementation such as the one used in the sample scenario.

Figure 1. IMS synchronous callout implementation topology
IMS synchronous callout implementation topology

Application development

The sample code in Listing 1 below implements a synchronous callout. You need to create a COBOL copybook for the request and response in order to execute the synchronous callout. You use these later to generate the XML converters drivers.

Enhancing the COBOL application to use the ICAL call, produces a synchronous callout request. The AIBRSNM1 VALUE in Listing 1 is SOAPGWAY, which is defined in the OTMA descriptor name in DFSYDTx (see Define the OTMA destination descriptor for IMS). The CALLOUT-REQUEST contains the input to the Web service. The CALLOUT-RESPONSE contains the Web service output.

Listing 1. Sample COBOL code using ICAL call
01 AIB.
	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 'SOAPGWAY'.
	.
TO-DIS.
	MOVE IN-CUSTNUM TO SSA-KEY.
	MOVE '01ICUS' TO INCO-COMMAND
	MOVE IN-CUSTNUM TO INCO-CUSTNUM
	COMPUTE AIBOALEN = LENGTH OF CALLOUT-REQUEST
	COMPUTE AIBRLEN = LENGTH OF AIB
	COMPUTE AIBOAUSE = LENGTH OF CALLOUT-RESPONSE
	CALL 'AIBTDLI' USING DLI-ICAL AIB CALLOUT-REQUEST CALLOUT-RESPONSE

Environment setup

Define the OTMA destination descriptor for IMS

The OTMA destination descriptor is located in the DFSYDTx proclib member and is processed at IMS startup. Listing 2 below shows the descriptor you can use to implement the scenario.

Listing 2. DFSYDTx descriptor definitions
D SOAPGWAY TYPE=IMSCON TMEMBER=IMAFHWS TPIPE=HWS2SOAP 
D SOAPGWAY ADAPTER=HWSXMLA0 CONVERTR=CALLOUTD SYNTIMER=5000

The important parts of the descriptor for this implementation are the TPIPE name, the TMEMBER name, and the CONVERTR name. TPIPE is a unique name that is analogous to an LTERM. TMEMBER is the name of a client that connects to OTMA. For the scenario, the client is IMS Connect. CONVERTR is the name of the converter that translates COBOL to SOAP and SOAP to COBOL.

Once you have configured your descriptor, restart IMS and verify that you receive the following message:
DFS0578I - READ SUCCESSFUL FOR DDNAME PROCLIB MEMBER = DFSYDTI

Configure IMS Connect

Listing 3 below shows a sample IMS Connect HWSCFGxx configuration you can use to implement the scenario.

Listing 3. HWSCFGxxx - IMS Connect configuration parameters
HWS=(ID=IMAFHWS)
TCPIP=(EXIT=(HWSSMPL1,HWSSOAP1),HOSTNAME=TCPIP,IPV6=Y,PORTID=(9200))
DATASTORE=(GROUP=IMAFGRP,ID=IMAF,MEMBER=IMAFHWS,TMEMBER=IMAFOTMA,
DRU=DFSYDRU0)                                                       
ADAPTER=(XML=Y)

Use the TCPIP, PORTID, ADAPTER, DATASTORE MEMBER, DATASTORE ID, and DATASTORE GROUP parameters to set up IMS SOAP Gateway. By setting the ADAPTER parameter to (XML=Y), you enable the XML-to-COBOL data conversion function in IMS Connect.

Generate the correlator and XML converter driver using Rational Developer for System z

This section describes how to generate an XML converter driver from a CICS Web service and an IMS application's COBOL copybook. The XML converter driver is responsible for transforming the COBOL copybook structure into a SOAP structure that the Web service understands and vice versa. The converter is linked into IMS Connect and referenced by the OTMA descriptor to handle the incoming and outgoing message conversions.

Follow these steps to generate the XML converter:

  1. Using Rational® Developer for System z® Version 7.1.1.3 or higher, create a new Workstation COBOL or PL/I: Local Project as shown below in Figure 2.
    Figure 2. Rational Developer for System z new project selection wizard
    New project selection wizard
  2. Import the COBOL copybook:
    1. Ensure there is a COBOL copybook on your local workstation. This copybook should define the callout-request and callout-response areas.
    2. Select the new Local Project you created in Step 1.
    3. Select File > Import….
    4. From the Import wizard, do the following:
      1. Select General > File System.
      2. Click Next.
      3. Browse to the location of your COBOL copybook and select the appropriate file as shown below in Figure 3.
        Figure 3. Import resources from the local file system
        Import resources from the local file system
  3. Repeat Step 2 to import the CICS Web service definition (*.wsdl).
  4. Right click on the *.wsdl, select Enable Enterprise Web Service, and do the following:
    1. Select the options in the Enterprise Service Tools Wizard Launchpad as shown below in Figure 4.
      Figure 4. Enterprise Service Tools Wizard Launchpad
      Enterprise Service Tools Wizard Launchpad
    2. Click Start.
    3. On the New XML to COBOL Mapping panel, do the following:
      1. Browse to the Mapping source, which is the Web service definition (*.wsdl).
      2. Browse to the Mapping target, which is the COBOL copybook.
        Figure 5. New XML to COBOL Mapping Session
        New XML to COBOL Mapping Session
      3. Click Next.
      4. Verify that the appropriate source XML elements are selected.
      5. Verify that the target language structure is set to CALLOUT-RESPONSE.
        Figure 6. Root XML Element and Language Structure Selection
        Root XML Element and Language Structure Selection
      6. Click Next.
      7. Verify that the Mapping file Folder is the same as the project name and that the Mapping file name is filled in (usually this is the name of the .wsdl file).
      8. Click Finish. A newly generated graphical mapping file should appear.
  5. Map the Web service output area to the callout-response area. Drag and drop from the Web service area to the COBOL copybook area to create the mapping connection and save the file.
    Figure 7. Sample mapping
    Sample mapping
  6. Right click on the COBOL copybook, select Enable Enterprise Web Service, and do the following:
    1. Fill in the Enterprise Service Tools Wizard Launchpad as shown below in Figure 8.
      Figure 8. Enterprise Service Tools Wizard Launchpad
      Enterprise Service Tools Wizard Launchpad
    2. Click Start.
    3. On the New XML to COBOL Mapping panel, do the following:
      1. Browse to the Mapping source, which is the COBOL copybook.
      2. Browse to the Mapping target, which is the Web service definition.
        Figure 9. New XML to COBOL Mapping
        New XML to COBOL Mapping
      3. Click Next.
      4. Verify that the Source language structure is set to the CALLOUT-REQUEST.
      5. Verify that the target XML elements from the Web service definition are correct.
        Figure 10. Root XML Element and Language Structure Selection
        Root XML Element and Language Structure Selection
      6. Verify that the Mapping file Folder is the same as the project name and verify Mapping file name is filled in (usually this is the name of the copybook).
      7. Click Finish. A newly generated graphical mapping file should appear.
  7. Map the callout-request area to the Web service input area. Drag and drop from the Web service area to the COBOL copybook area to create the mapping connection and save the file.
    Figure 11. Sample mapping
    Sample mapping
  8. Do the following to generate the XML Converter:
    1. Your project should now contain two .mapping files; one for the input mapping and one for the output mapping. Highlight both mapping files (use CTRL+click).
      Figure 12. Mapping file selections
      Mapping file selections
    2. Right click on either of the highlighted mapping files and select Generate Conversion Code.
    3. Fill in the Enterprise Service Tools Wizard Launchpad as shown below in Figure 13.
      Figure 13. Enterprise Service Tools Wizard Launchpad
      Enterprise Service Tools Wizard Launchpad
    4. Click Start.
    5. On the first panel of the IMS SOAP Gateway – Map an Existing Service Interface (meet-in-the-middle) wizard, click Next.
    6. On the Generation options panel, got to the Advanced Options tab and do the following:
      1. Expand the Specify Compiler-related preferences section and ensure that the COBOL compiler version is the compiler version used on your System z when compiling and linking the driver in IMS Connect (see Transfer and link the COBOL converter into IMS Connect).
        Figure 14. Generation options
        Generation options
    7. Fill in the IMS Connect interaction properties similar to what is shown below in Figure 15. You will also need to define some of these variables in IMS, IMS Connect, and IMS SOAP Gateway including the TPIPE, connection bundle, and Transaction Code.
      Figure 15. IMS SOAP Gateway Web Service Requestor
      IMS SOAP Gateway Web Service Requestor
    8. Click Next.
    9. Verify that the Converter driver file name matches the CONVERTR name specified in the OTIMA descriptor (see Define the OTMA destination descriptor for IMS).
    10. Click Finish.
    11. Verify that the project now contains the following:
      1. A correlator file that can be used for the IMS SOAP Gateway deployment.
      2. The XML converter driver that will be used to link into IMS Connect.

Transfer and link the COBOL converter into IMS Connect

Do the following to transfer and link the COBOL converter into IMS Connect:

  1. FTP the generated COBOL converter driver file in binary to the host system.
  2. Submit the job shown below in Listing 4 to compile the COBOL converter driver and link to IMS Connect. Ensure that your COBOL compiler level matches the COBOL version you selected on the Advanced Options tab of the On the Generation options panel in the IMS SOAP Gateway wizard (see Figure 14).
    Listing 4. Compile COBOL converter job
    //CMPCREET JOB '',MSGCLASS=H,REGION=0M,TIME=10,                      
    // MSGLEVEL=(1,1),NOTIFY=&SYSUID                                     
    //ORDER JCLLIB ORDER=(IGY.V3R4M0.SIGYPROC)                           
    //RDZXML EXEC IGYWCL,LNGPRFX='IGY.V3R4M0',                           
    //  LIBPRFX='CEEV1R8Z',PARM.COBOL='TEST(NONE,SYM,SEPARATE)'          
    //COBOL.SYSIN    DD DSN=ADTOOLS.MNA.S2U1F6.IMS.COBOL(GREETD),DISP=SHR
    //COBOL.SYSLIB   DD DSN=ADTOOLS.MNA.S2U1F6.COPY,DISP=SHR             
    //COBOL.SYSDEBUG DD DSN=ADTOOLS.MNA.S2U1F6.SYSDEBUG(GREETD),         
    //  DISP=SHR                                                         
    //COBOL.SYSLIN   DD DSN=ADTOOLS.MNA.S2U1F6.OBJ(GREETD),DISP=SHR      
    //LKED.SYSLIB    DD DISP=SHR,DSN=ADTOOLS.MNA.S2U1F6.LOADLIB          
    //               DD DISP=SHR,DSN=ADTOOLS.DT810.SEQAMOD               
    //               DD DISP=SHR,DSN=CEE.SCEERUN                         
    //               DD DISP=SHR,DSN=CEE.SCEELKED                        
    //LKED.SYSLIN    DD *                                                
         INCLUDE OBJECT(GREETD)                                          
         INCLUDE RESLIB(DFSLI000)                                        
         INCLUDE SYSLIB(CEEROPT)                                         
         ENTRY GREETD                                                    
         ALIAS GREETX                                                    
         NAME GREETD(R)                                                  
    /*                                                                   
    //LKED.SYSLMOD  DD  DISP=SHR,DSN=ADTOOLS.MNA.S2U1F6.LOADLIB(GREETD)  
    //LKED.OBJECT    DD DSN=ADTOOLS.MNA.S2U1F6.OBJ,DISP=SHR              
    //LKED.RESLIB    DD DISP=SHR,DSN=IMSVS.IMAF.SDFSRESL                 
    //LKED.SYSIN     DD DUMMY                                            
    /*
  3. Restart IMS Connect.

Enable the IMS application to access an external Web service using IMS Soap Gateway

Follow the steps in this section to deploy the Web service definition, correlator file, and connection bundle. The sample scenario environment uses IMS Soap Gateway for USS (OMVS).

  1. Follow these steps to create a connection bundle:
    1. From the deployment utility, select Task 10: Enable your IMS application to access an external Web Service.
    2. Select Task 12: Create, Update, Delete or View connection bundle for callout.
    3. Enter c to create a new connection bundle.
    4. Enter a name for the connection bundle. The name you use must match the name you specified for the Inbound and Outbound connection bundles on the IMS SOAP Gateway Web Service Requestor panel of the in the IMS SOAP Gateway wizard (see Figure 15).
    5. Enter the IMS host name or IP address for IMS Connect.
    6. Enter the IMS port number specified in Listing 3 as the TCPIP PORDID.
    7. Enter the IMS datastore name specified in Listing 3 as the DATASTORE ID.
    8. Enter your IMS userid (optional)
    9. Enter your IMS password (optional)
    10. Enter the IMS group name (optional) specified in Listing 3 as the DATASTORE GROUP.
    11. Enter the Callout TPipes specified in Listing 2 as the TPIPE.
    12. View the connection bundle to ensure everything is set correctly.
    Figure 16. Connection bundle settings
    Connection bundle settings
  2. Follow these steps to FTP the correlator file:
    1. FTP (in binary) the correlator file that you created earlier in Generate the correlator and XML converter driver using Rational Developer for System z to the following directory:
      SOAP Install Directory/server/webapps/imssoap/xml/
    2. Ensure that the file has Read Write permissions. The following command gives Owner, Group and Other read and write capability. Replace 666 with the appropriate permissions according to your company’s policy: Chmod 666 corr.xml
  3. Follow these steps to FTP the Web service definition file:
    1. FTP (in binary) the Web service definition file that you created earlier in Generate the correlator and XML converter driver using Rational Developer for System z to the following directory:
      SOAP Install Directory/server/webapps/imssoap/wsdl/
    2. Ensure that the file has Read Write permissions.
  4. Follow these steps to deploy a callout client:
    1. From the deployment utility select Task 10: Enable your IMS application to access an external Web Service.
    2. Select Task 13: Deploy a callout client.
    3. Enter the name of the Web service definition that you FTP’ed in step 3 of this section.
    4. Enter the name of the correlator file that you FTP’ed in step 2 of this section.
    5. Verify that you see the following message:
      Callout client was successfully deployed.
  5. Restart the IMS SOAP Gateway.

Problem determination

After setting up the environment and implementing the changes for the IMS application to produce a synchronous callout request, it is likely that not everything will work the first time. This section describes the symptoms of problems you may encounter and provides suggestions for debugging and troubleshooting the problems.

Synchronous Callout request and response flow

The illustration of the IMS synchronous callout implementation topology shown in Figure 17 includes labels that correspond to the parts of the request and response flow described in this section.

Figure 17. Request and response flow of IMS synchronous callout implementation topology
Request and response flow of IMS synchronous callout implementation topology
  1. IMS application sends a request.

    The first step to verifying the IMS application is to ensure that the appropriate parameters are set for the ICAL call. For example, use Rational Developer for System z and Debug Tool to view the values of the AIB (see Figure 18 below).

    Use the AIBSFUNC, AIBRSNM1, AIBRSFLD, and the request area as eye catchers to verify the AIB. For synchronous callout, the AIBSFUNC or sub function name must be SENDRECV. The AIBRSNM1 is the name of the OTMA descriptor. As shown in Figure 18, the AIBRSNM1 value of SOAPGWAY matches the descriptor defined in Listing 2. The AIBRSFLD parameter defines the time to wait for the synchronous call process to complete. While debugging the application you should increase this value to allow time to step through the code. The request area must match the request area used when generating the COBOL converter driver.

    Figure 18. Rational Developer for System z and Debug Tool
    Rational Developer for System z and Debug Tool
    Figure 18a. Rational Developer for System z and Debug Tool (continued)
    Rational Developer for System z and Debug Tool
  2. IMS queus the request to TPIPE.

    Once the request is sent from the application, issue the following command:

    /DISPLAY TMEMBER IMAFHWS TPIPE ALL SYNC

    Use the output from the command to verify that the ICAL request dynamically creates the TPIPE and queues the message. Listing 5 below shows a sample of the command output.

    The important parts to verify are the TPIPE, MODE, and SYNCOT. The TPIPE name in this example is HWS2SOAP and matches the descriptor in Listing 2. For possible callout status based on MODE and SYNCOT values, see Table 1.

    Listing 5. Sample command output
    REPLY TO 90 IS;/DIS TMEMBER IMAFHWS TPIPE ALL SYNC            
    MBR/TPIP  ENQCT  DEQCT    QCT  INPCT   OPT MODE  SYNCOT  NO-RSP STATUS SMEM    IMAF
    IMAFHWS
    -HWS2SOAP     0      0      0      0     W    B       0       0        IMAF
    *08352/142921*   IMAF
  3. IMS Connect receives, converts, and forwards the request.

    Before issuing the ICAL call, start the IMS Connect recorder trace. This allows you to see if IMS Connect receives the requests. To start the recorder trace, reply to IMS Connect with the following command:

    RECORDER OPEN

    Once the recorder is started, issue the ICAL call and stop the trace using:

    RECORDER CLOSE

    To format the RECORDER output, use IDCAMS as shown in Listing 6 below.

    Listing 6. IDCAMS example
    //IMAFRCRD JOB ,'BUILD PSMFSJB3',REGION=0M,
    // MSGLEVEL=(1,1),CLASS=A,MSGCLASS=H,NOTIFY=&SYSUID
    /*JOBPARM S=*
    //SELECT EXEC PGM=IDCAMS
    //DD1 DD DISP=SHR,DSN=IMSVS.IMAF.HWSRCDR
    //SYSPRINT DD DSN=ADTOOLS.SYNC1205.RECORDER,DISP=(,CATLG),
    // DCB=(RECFM=FBA,LRECL=133,BLKSIZE=13300),
    // VOL=SER=SMS000,SPACE=(CYL,(2,1),RLSE),UNIT=SYSDA
    //SYSIN DD *
      PRINT INFILE(DD1)

    Review the formatted RECORDER trace. If you see the eye-catchers CORTKN, CSMOKY, and the TPIPE name (as shown below in Figure 19), this verifies that the callout request was successfully received by IMS Connect.

    Figure 19. RECORDER trace example
    RECORDER trace example
  4. IMS SOAP Gateway receives the XML SOAP request.

    Turn on DEBUG trace to verify that IMS SOAP Gateway receives the XML formatted SOAP message. Follow these steips to enable tracing:

    1. Start IMS SOAP Gateway Deployment Utility.
    2. Select Task 4: Update IMS SOAP Gateway properties.
    3. Change the trace level to DEBUG (value 5).
    4. Restart IMS Soap Gateway.

    Once IMS SOAP Gateway is restarted, the trace output appears in the following file:
    SOAP Install Directory/server/logs/imssoap.log

    Check the trace to verify that the gateway is polling the TPIPE and getting back acknowledgements. The trace example in Figure 20 below shows that IMS SOAP Gateway is polling TPIPE HWS2SOAP and getting a response.

    Figure 20. IMS SOAP Gateway DEBUG trace example - polling
    IMS SOAP Gateway DEBUG trace example - polling

    The trace example in Figure 21 below shows an acknowledgement with request data from the ICAL call. If the COBOL converter driver was generated properly, the request data is XML formatted.

    Figure 21. IMS SOAP Gateway DEBUG trace example - acknowledgement
    MS SOAP Gateway DEBUG trace example - acknowledgement
  5. CICS Web Service is invoked.

    Optionally, use Rational Developer for System z and Debug Tool to verify that the CICS Web service is invoked.

  6. IMS SOAP Gateway receives and forwards XML SOAP response.

    Once the CICS Web service returns, the IMS SOAP Gateway trace should show the response data in XML format. The trace example in Figure 22 below shows the callout response data that was forwarded to IMS Connect. The RESP eye-catcher at offset x’60’ indicates that this is a response to the callout request.

    Figure 22. IMS SOAP Gateway DEBUG trace example - callout response
    IMS SOAP Gateway DEBUG trace example - callout response
  7. IMS Connect receives XML SOAP response and converts the response.

    To verify that IMS Connect receives the XML SOAP response, capture the IMS Connect RECORDER trace. In the trace, search for RESPHWSXML. The trace example in Figure 23 below shows a trace callout response message. The RESP eye-cather indicates that this is a response message. This is followed by the XML Adaptor, or COBOL converter driver name. In the example, the converter driver is named CALLOUTD. If the converter successfully converted the XML data, you should not see any HWS error messages on the console.

    Figure 23. Trace callout response message example
    Trace callout response message example
  8. IMS application receives the callout response.

    If the IMS application returns control in the Debug Session, verify the AIBRETRN, AIBREASN, and response area. If the return codes for AIBRETRN and AIBREASN are non-zero, see the Troubleshooting section or refer to the IMS Synchronous Callout documentation. If the AIBRETRN, and AIBREASN are zero, then use Rational Developer for System z and Debug Tool to check that the data you received is correct (see Figure 24 below).

    Figure 24. Rational Developer for System z and Debug Tool
    Rational Developer for System z and Debug Tool
    Figure 24a. Rational Developer for System z and Debug Tool (continued)
    Rational Developer for System z and Debug Tool
Table 1. Possible callout status based on MODE and SYNCOT values.
Mode SYNCOT Status
A Greater than one Callout request sent but waiting on RESUME TPIPE
A 0 Callout completed without Response (timeout or problem with external application)
B 0 Callout completed, with response
S Greater than one Callout request sent to external application and waiting for response

Troubleshooting

This section provides a quick reference for the meaning of AIBRETRN and AIBREASN non-zero return codes.

Descriptor name is invalid (0104/1020)

If the callout receives an AIBRETRN/AIBREASON of 0104/1020:

  • Ensure the application is setting the correct descriptor name in the ICAL AIB for AIBRSNM1.
  • Ensure your OTMA descriptor (DFSYDTx — see Figure 3) was loaded at IMS startup time. If it was loaded properly, you should see the following message:
    DFS0578I - READ SUCCESSFUL FOR DDNAME PROCLIB MEMBER = DFSYDTI

Unable to send the request message to the external application (0108/0580)

If the callout receives an AIBRETRN/AIBREASON of 0108/0580:

  • Ensure your DFSYDTx descriptor has the appropriate TMEMBER name. This name should match the MEMBER parameter in the IMS Connect configuration file (HWSCFGxx — see Listing 3).

Request is timed out (0100/0104)

If the callout receives an AIBRETRN/AIBREASON of 0100/0104:

  • Ensure IMS SOAP Gateway is actively polling (see Figure 20) the TPIPE.
  • Ensure the TPIPE specified in the OTMA descriptor (DFSYDTx — see Listing 2) matches the Callout TPipes specified in the IMS SOAP Gateway connector bundle that is associated with your callout correlator file.

Partial output response data is returned (0100/000C)

If the callout receives an AIBRETRN/AIBREASON of 0100/000C:

  • Ensure that the AIBOAUSE is set appropriately to match the response area size.
  • Check the IMS SOAP Gateway log file for any suspicious errors like the example shown in Figure 26 below. In the example, you can see that the IMS SOAP Gateway had a problem invoking the Web service.
Figure 26. IMS SOAP Gateway log file example
IMS SOAP Gateway log file example

Request message is rejected by the external application (0100/0108)

If the callout receives an AIBRETRN/AIBREASON of 0100/0108:

  • Ensure that IMS Connect is active and configured properly.
  • Ensure that the request area is not larger than what was specified in the request area length field.

Error message is returned in the output response data (0100/0100)

If the callout receives an AIBRETRN/AIBREASON of 0100/0100:

  • Ensure that the AIBOAUSE is set appropriately to match the response area size.

Conclusion

This article demonstrates one of the many ways to implement the IMS V10 Synchronous Callout function. The article describes how to implement synchronous callout ICAL call in an existing IMS TM COBOL application to invoke an existing CICS Web service through IMS SOAP Gateway. This article provides the necessary information for setup, problem determination, and troubleshooting to successfully make a synchronous callout from IMS through the IMS SOAP Gateway.

Resources

Learn

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Information management on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Information Management, SOA and web services
ArticleID=376470
ArticleTitle=IMS solutions: Utilizing the IMS synchronous callout function to invoke a CICS Web service through IMS SOAP Gateway
publish-date=03192009