IMS SOAP Gateway

IBM® IMS™ SOAP Gateway is a Web services solution that enables IMS applications to inter-operate outside of the IMS environment through Simple Object Access Protocol (SOAP) to provide and request services independent of platform, environment, application language, or programming model.

The IMS SOAP Gateway can assist an organization in the following areas:
  • Enterprise modernization
  • Application development
  • Business-to-Business (B2B) integration
  • Service-oriented architecture (SOA) implementation

IMS SOAP Gateway allows you to enable your IMS application to become a Web service. Different types of client applications, such as Microsoft® .NET, Java™, and third-party applications, can submit SOAP requests into IMS to drive the business logic of the IMS applications. In conjunction with the IMS Connect XML Adapter, you can enable your IMS application to become a Web service without the need of changing the back-end IMS application.

IMS SOAP Gateway is compliant with the industry standards for Web services, including SOAP/HTTP 1.1 and WSDL 1.1. This allows your IMS assets to inter-operate openly with various types of applications.

IMS SOAP Gateway consists of the following components:

  • IMS SOAP Gateway Deployment Utility
    The IMS SOAP Gateway Deployment Utility allows you to set up properties and deploy and maintain IMS Web services.
  • IMS SOAP Gateway Administrative Console
    The IMS SOAP Gateway Administrative Console lists the deployed Web services when the server is started. Each item in the list is a link to the Web service's WSDL (Web service description language file) file.
  • IMS SOAP Gateway server
    The IMS SOAP Gateway server processes SOAP messages. It receives the SOAP message from the client application, converts it to an IMS input message, and sends it to IMS. It then receives the output message from IMS and converts it to a SOAP message to send back to the client.
  • Accessibility
Related reference
System requirements for IMS SOAP Gateway


IMS SOAP Gateway Deployment Utility

The IMS SOAP Gateway Deployment Utility allows you to set up properties and deploy and maintain IMS Web services.

With the IMS SOAP Gateway Deployment Utility, you can:
  • Enable your IMS applications to be accessible as Web services
  • Start and stop IMS SOAP Gateway
  • Set up the connection and correlation properties for a Web service
  • Generate Java client code to access a Web service
  • Configure properties for the IMS SOAP Gateway server
  • Undeploy Web services
You can use the IMS SOAP Gateway Deployment Utility in two ways:
  • Interactive mode: The IMS SOAP Gateway Deployment Utility in Interactive mode is an interactive user interface that walks you through each task you want to perform by prompting for input. It runs in the Windows DOS Command prompt.
  • Expert mode: The IMS SOAP Gateway Deployment Utility' in Expert mode allows you to perform tasks in one step by entering commands on the Windows command line with parameters.
Parent topic: IMS SOAP Gateway
Related reference
Deployment Utility Expert Mode
Deployment Utility in Interactive Mode


IMS SOAP Gateway Administrative Console

The IMS SOAP Gateway Administrative Console lists the deployed Web services when the server is started. Each item in the list is a link to the Web service's WSDL (Web service description language file) file.

Parent topic: IMS SOAP Gateway
Related tasks
Deploying the WSDL file
Starting the IMS SOAP Gateway Administrative Console


IMS SOAP Gateway server

The IMS SOAP Gateway server processes SOAP messages. It receives the SOAP message from the client application, converts it to an IMS input message, and sends it to IMS. It then receives the output message from IMS and converts it to a SOAP message to send back to the client.

The following figure shows the IMS SOAP Gateway runtime environment and includes processes related to the IMS Connect XML adapter. The numbers in the figure correspond to the description that follows.

Overview of the IMS SOAP Gateway runtime environment
  1. The Web service client application sends a SOAP message to IMS SOAP Gateway which contains input to the IMS application in an XML format.
  2. IMS SOAP Gateway processes the SOAP header (XML) and retrieves the appropriate correlation and connection information for the input request.
  3. IMS SOAP Gateway sends the input XML data to IMS Connect using TCP/IP after adding the appropriate IMS Connect header.
  4. IMS Connect calls the XML Adapter which in turn calls the XML Converter to perform the XML to IMS application format transformation.
  5. IMS Connect then sends the message for further processing. From this point on, the processing is the same as a normal transaction flow. The transaction gets executed and the output is queued.
  6. IMS Connect calls the XML Adapter in order to perform the transformation of the IMS application format to XML.
  7. IMS Connect sends the output XML message back to IMS SOAP Gateway using TCP/IP.
  8. IMS SOAP Gateway wraps a SOAP header on the output message and sends it back to the client application.

If you choose to handle the data transformation in your application without utilizing the IMS Connect XML Adapter, you obviously do not need to invoke the XML Adapter. In this case, the incoming XML message is sent directly to IMS Connect and then to the IMS application and the same is true in reverse. The IMS application creates an XML output message which is sent to IMS Connect, then directly to IMS SOAP Gateway and lastly to the Web service client.

Parent topic: IMS SOAP Gateway
Related tasks
Starting the IMS SOAP Gateway server


Accessibility

Accessibility features help users who have a physical disability, such as restricted mobility or limited vision, to use information technology products successfully. The IMS SOAP Gateway Administrative Console, documentation, and Deployment Utility are all accessible and include the following accessibility features:
  • Keyboard-only operation
  • Interfaces that are commonly used by screen readers
  • Keys that are tactilely discernible and do not activate just by touching them
  • Industry-standard devices for ports and connectors
  • The attachment of alternative input and output devices

Keyboard Input

You can use keys or key combinations to perform operations that can also be done using a mouse.

Interface information

IMS SOAP Gateway Administrative Console is in HTML format, all images have alternate text, all frames have appropriate titles, no information is conveyed by color only.

IMS SOAP Gateway Deployment Utility is a DOS command line interface. All text is provided through the DOS based command line interface.

Vendor software

Accessible IMS SOAP Gateway documentation is available in on the IMS SOAP Gateway Web site in a Microsoft Compressed HTML Help format (imssoap920.chm).

IBM and accessibility

See the IBM Accessibility Center at http://www.ibm.com/able for more information about the commitment that IBM has to accessibility.

Parent topic: IMS SOAP Gateway


Installing and verifying the installation

This section provides the following installation and installation verification information:

  • System requirements for IMS SOAP Gateway
    IMS SOAP Gateway Version 9 runs on Microsoft® Windows® XP, Windows 2000 and AIX. IMS SOAP Gateway requires IMS Version 9 integrated with IMS Connect Version 9.2.
  • Installing the IMS SOAP Gateway
    IBM IMS SOAP Gateway is easily installed and downloaded from the IMS SOAP Gateway Web site. Installation instructions for IMS SOAP Gateway are located on the IMS SOAP Gateway Web site.
  • Setting up IMS Connect and IMS OTMA
    IMS SOAP Gateway uses IMS Connect and IMS OTMA to invoke IMS transaction as a Web service. In order for IMS SOAP Gateway to access IMS transactions, you need to configure IMS OTMA and IMS Connect for IMS SOAP Gateway.
  • Verifying the installation of IMS SOAP Gateway
    To verify the installation of IMS SOAP Gateway, use the IMS SOAP Gateway Installation Verification Program (IVP).
  • Removing IMS SOAP Gateway
    IMS SOAP Gateway is easily removed on Windows and AIX.


System requirements for IMS SOAP Gateway

IMS SOAP Gateway Version 9 runs on Microsoft® Windows® XP, Windows 2000 and AIX. IMS SOAP Gateway requires IMS Version 9 integrated with IMS Connect Version 9.2.

Operating system requirements

IMS SOAP Gateway runs on Microsoft Windows XP, Windows 2000, and AIX.

IMS requirements

  • IMS SOAP Gateway requires IMS Version 9 integrated with IMS Connect.
  • For the IMS Connect XML Adapter function: Install the IMS Connect APAR for the Adapter Task Manager which includes the XML Adapter function (PK24912). Instructions on how to configure the IMS Connect XML Adapter are located in the ++ HOLD card data in the IMS Connect APAR and in the IMS Connect Guide and Reference.
Parent topic: Installing and verifying the installation
Related tasks
Installing the IMS SOAP Gateway
Verifying the installation of IMS SOAP Gateway
Setting up IMS Connect and IMS OTMA
Related information
IMS SOAP Gateway


Installing the IMS SOAP Gateway

IBM IMS SOAP Gateway is easily installed and downloaded from the IMS SOAP Gateway Web site. Installation instructions for IMS SOAP Gateway are located on the IMS SOAP Gateway Web site.

To install IMS SOAP Gateway for Windows and AIX:
  1. From the IMS SOAP Gateway Web site, download the following file into a temporary directory:
    • For Windows: imssoap920win.exe
    • For AIX: imssoap920aix.bin
  2. Run the imssoap920 file specific to your installation environment. The InstallShield Wizard opens and guides you though a series of installation steps.
  3. Follow the instructions in the InstallShield Wizard to complete the installation.

For Windows only: To access IMS SOAP Gateway navigate toStart -> All Programs -> IBM IMS SOAP Gateway Version 9.2.

Parent topic: Installing and verifying the installation
Related tasks
Verifying the installation of IMS SOAP Gateway
Related reference
System requirements for IMS SOAP Gateway


Setting up IMS Connect and IMS OTMA

IMS SOAP Gateway uses IMS Connect and IMS OTMA to invoke IMS transaction as a Web service. In order for IMS SOAP Gateway to access IMS transactions, you need to configure IMS OTMA and IMS Connect for IMS SOAP Gateway.

IMS Connect and IMS OTMA must have the following tasks complete in order for IMS SOAP Gateway to access IMS transactions:
  1. IMS Connect and IMS OTMA are installed, configured, enabled and running properly. For IMS Connect:
    • Configure IMS Connect with User Exit Routine HWSSOAP1. User Exit Routine HWSSOAP1 is available in the IMS Connect APAR for the Adapter Task Manager (PK24912).
    • Select the data transformation process. You can handle the conversion of XML messages between IMS SOAP Gateway and IMS with one of the following:
      • IMS Connect can be configured to convert the XML messages received from IMS SOAP Gateway into an IMS transaction format. If you use this method for data conversion, the IMS Connect XML Adapter must be configured. Instructions on how to configure the IMS Connect XML Adapter are located in the ++ HOLD card data in the IMS Connect APAR for the Adapter Task Manager (PK24912) and in the IMS Connect Guide and Reference.
      • XML messages can be sent directly to IMS and the IMS application must be modified to accept the XML input messages and to return an XML output message.
  2. IMS Connect and OTMA are set up with the correct level of security. For example, if you have security enabled for your IMS Connect and IMS OTMA, provide the valid security properties (like user ID and password) to IMS SOAP Gateway.
  3. IMS transaction and the program associated with the IMS transaction has been started and are running properly.
  4. Optional: Set up IMS Connect SSL ports:
    1. Refer to http://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/index.jsp?topic=/com.ibm.ims9.doc.connect/sslconnections.htm on how to setup the SSL configuration in IMS Connect.
    2. On your Os/390 system, verify that the SSL ports are active using the MVS Modify Command, Control Center, or MVS Reply-to number. For example, if you use MVS Reply-to number use the VIEWHWS command. This command displays a list of the SSL ports and details their status. Ensure that some of the ports have the suffix "s" and that are in the ACTIVE state.
      Note: For SSL support, set GSK_PROTOCOL_TLSV1 to ON. For more information, see the Version 9, IMS Connect User's Guide.
Parent topic: Installing and verifying the installation
Related tasks
Selecting the data transformation process and configuring the XML Adapter function
Verifying the installation of IMS SOAP Gateway
Related reference
System requirements for IMS SOAP Gateway


Verifying the installation of IMS SOAP Gateway

To verify the installation of IMS SOAP Gateway, use the IMS SOAP Gateway Installation Verification Program (IVP).

Prerequisite: You must complete the configuration steps in "Configuring IMS OTMA and IMS Connect for IMS SOAP Gateway" before running the IVP. For more information on configuring IMS Connect, see the IMS Version 9: IMS Connect Guide and Reference. IMS Connect is included with IMS Version 9.

The IMS SOAP Gateway Installation Verification Program (IVP) is a Web service that is installed with IMS SOAP Gateway. The IVP verifies the installation when you successfully access the target IMS environment.
Note: The IVP does not require a host IMS application.
To verify the installation:
  1. Configure the connection bundle properties for use by the IVP to connect to your target IMS:
    1. Start the IMS SOAP Gateway Deployment Utility in Interactive mode.
    2. Select Task 6: Create, Update, Delete or View connection bundle by entering 6on the command line.
    3. Enter c to create a new connection bundle.
    4. Enter the following values for each property of the connection bundle:
      • Connection Bundle name: imssoapivp
      • IMS Connect host name or IP Address: Specify the IP address or host name of the machine running the target IMS Connect.
      • IMS Connect port number: Specify the number of a port used by the target IMS Connect.
      • IMS datastore name: Specify the name of the target IMS datastore. It must match the ID parameter of the Datastore statement that is specified in the IMS Connect configuration member when IMS Connect is installed. It also serves as the XCF member name for IMS during internal XCF communications between IMS Connect and OTMA.
      • IMS user ID: If you have security enabled on your IMS environment, specify the user name that will be used for security checking.
      • IMS password: If you have security enabled on your IMS environment, specify the password that will be used for security checking.
      • IMS group name: Specify the IMS group name that will be used for security authorization is applicable.
  2. Start the IMS SOAP Gateway server. If the IMS SOAP Gateway server is already started, restart it.
  3. Run the IVP using the following steps:
    1. From a Web browser, type the following to invoke the IMS SOAP Gateway IVP Web client:
      http://hostname:port/imssoap/imssoapivp.html
      where hostname is the hostname and port is the port number where IMS SOAP Gateway is running.
      Tip: If you invoke the IVP from the same workstation where IMS SOAP Gateway is installed, then you can use the default port number and the URL is: http://localhost:8080/imssoap/ imssoapivp.html..
    2. Click Submit. The IVP is run successfully if you see one of the following messages:
      • DFS058I hh:mm:ss START COMMAND COMPLETED
      • DFS1292E SECURITY VIOLATION

      The objective of the IVP is to receive a message from IMS in reply to the /STA OTMA command. One of these messages is returned, depending on the level of security checking in place for your installation and whether or not the UserName/Password/GroupName is permitted to issue the /STA command. Either message indicates successful execution of the IVP, since it is IMS that issues the "DFS" message. The IVP does not run an IMS application program, therefore it does not verify that IMS transactions can run successfully. It only verifies that the path to IMS is available.

Parent topic: Installing and verifying the installation
Related tasks
Installing the IMS SOAP Gateway
Tips for diagnosing Installation Verification Program errors
Starting the IMS SOAP Gateway server
Setting up IMS Connect and IMS OTMA
Related reference
System requirements for IMS SOAP Gateway


Removing IMS SOAP Gateway

IMS SOAP Gateway is easily removed on Windows and AIX.

You can uninstall IMS SOAP Gateway in either of the following:

  • Run the uninstall file:
    1. For Windows: go to <installation directory>\_uninst and run uninstaller.exe.
    2. For AIX: go to <installation directory>\_uninst and run uninstaller.bin.
  • For Windows only: Use the Windows Add/Remove Programs located on the Control Panel.
Parent topic: Installing and verifying the installation


Enabling an IMS application as a Web service

This section gives an overview of the tasks required to enable an IMS application as a Web service using IMS SOAP Gateway. After you create the WSDL file, modify the IMS application, and deploy the IMS SOAP Gateway Web service; the IMS application is available as a Web service and the client application can send it SOAP messages.

Perform the following tasks to make an IMS application accessible to a Web service.
  • Creating the WSDL file
    To deploy an IMS application as a Web service, you need to create a WSDL (Web service description language) file.
  • Selecting the data transformation process and configuring the XML Adapter function
    In order to handle the XML data from the client, you can either modify the IMS application to accept the XML input message and to return an XML output message, or use the WebSphere Developer for zSeries XML converter drivers to transform the XML data in IMS Connect such that you do not need to modify your IMS application.
  • Deploying a Web service with IMS SOAP Gateway
    Use the deployment utility to deploy an application as a Web service. You can use the deployment utility in either Interactive or Expert mode.
Related tasks
Writing the client application


Creating the WSDL file

To deploy an IMS application as a Web service, you need to create a WSDL (Web service description language) file.

A WSDL file is an XML document that describes a Web service. WSDL files are used by others (for example, the client that invokes the service) to discover the service and to understand how to invoke the service. It specifies the location of the service and the operations that the service exposes.

To make your IMS application accessible as a Web service, you need to describe the functions provided by the IMS application and how the input and output messages should appear in order to invoke the function in a WSDL file. The WSDL file serves as the Web service interface for the IMS application.

There are three ways to create the WSDL file: generating the file by using IBM WebSphere Developer for zSeries, manually creating the file, or modifying an existing WSDL file that is generated by IBM® WebSphere® Application Developer Integration Edition V5.1.1. To prepare the WSDL file, you need a COBOL copybook that describes the input and output messages for the IMS™ application.

  • Generating a WSDL file using WebSphere Developer for zSeries
    Use WebSphere Developer for zSeries to generate a WSDL file. If you use the IMS Connect XML Adapter feature, this task will also generate the XML converter to transform the XML data in IMS Connect such that you do not need to modify your IMS application.
  • Manually creating the WSDL file
    To enable an application as a Web service, you must first create the Web service interface.
  • Modifying WSDL files that are generated by WebSphere Studio Application Developer
    If you have WSDL files generated by using WebSphere Studio Application Developer Integration Edition V5.1.x, you can modify them to use it with IMS SOAP Gateway.
Parent topic: Enabling an IMS application as a Web service
Related tasks
Deploying a Web service with IMS SOAP Gateway


Generating a WSDL file using WebSphere Developer for zSeries

Use WebSphere Developer for zSeries to generate a WSDL file. If you use the IMS Connect XML Adapter feature, this task will also generate the XML converter to transform the XML data in IMS Connect such that you do not need to modify your IMS application.

Prerequisite: To generate a WSDL file, you must have a COBOL copybook that describes the format of the input and output messages for the application.
To generate a WSDL file using WebSphere Developer for zSeries V6.0.1:
  1. Start WebSphere Developer for zSeries and open the z/OS Projects perspective.
  2. Select the z/OS Projects view.
  3. Create a local COBOL project.
    1. Select File -> New -> Project.
    2. Expand the Workstation COBOL or PL/I folder.
    3. Select Local Project and click Next.
    4. Type a name for the project. For example, MyProject.
    5. Click Finish. A new project called MyProject is now available in your workspace.
  4. Import the COBOL copybook that describes the format of the input and output messages of your IMS application into the project you created. For example, MyProject.
    1. Select your MyProject project.
    2. Select File -> Import to open the Import wizard.
    3. Select File system to import the resources from the local file system. Click Next.
    4. Click Browse beside the directory field to go to the directory that contains the COBOL copybook. Click OK.
    5. Ensure IMSPhoneBook is the name of the destination folder for the imported resource. Click Finish to import the file and close the wizard.
  5. Use the Web service Runtime and Scenario Selection dialog to start the appropriate XML services for the Enterprise wizard. To open the Web service Runtime and Scenario Selection dialog:
    1. Highlight and right-click the COBOL copybook and select Enable Enterprise Web service. A dialog opens where you can specify the options to start a Web service wizard.
    2. Select a Runtime, Scenario and Conversion:
      • Runtime: IMS SOAP Gateway
      • Scenario: Create New Service Interface (bottom-up)
      • Conversion type: Compiled XML Conversion
    3. Click Start.
  6. Select the data structures for the inbound and outbound converters:
    1. Click Change COBOL Options. The COBOL Import Properties panel displays.
    2. In the Platform field, select z/OS.
    3. Click Finish. The Data structures panel displays.
    4. For the inbound data structure, select the COBOL data structure that corresponds to the input message of the IMS application.
    5. Select the Outbound data structure tab.
    6. Select the COBOL data structure that corresponds to the output message of the IMS application.
    7. Click Next to continue.
  7. Specify generation options:
    1. In the Host code page field, select the code page that the host uses. IMS SOAP Gateway supports only UTF-8 encoding for the inbound and outbound code pages. Therefore, you cannot change these settings.
    2. Specify any additional properties.
    3. Select the WSDL and XSD Options tab.
    4. In the Endpoint URI field, change the host and port name to the location of IMS SOAP Gateway. This URI specifies the address of the Web service.
    5. Specify any additional properties.
    6. Click Next to continue.
  8. Specify the IMS SOAP Gateway correlator properties and click Next.
  9. Specify location and name of the WSDL file.
    1. Select the WSDL and XSD tab.
    2. If necessary, change the default location and names of the WSDL file.
    3. Ensure that WSDL file name is selected.
    4. Optionally, select the inbound and outbound XSD files to be generated. These files are not required by IMS SOAP Gateway.
    5. Click Finish.
    WebSphere Developer for zSeries generates the following files:
    • WSDL file
    • COBOL converters and driver file
    • Correlator file
    • Inbound and outbound XSD files (optional)
  10. Store the WSDL file generated by WebSphere Developer for zSeries in the IMS SOAP Gateway WSDL directory: installation_directory\server\webapps\imssoap\wsdl. For example: c:\Program Files\IBM\IMS SOAP Gateway\server\webapps\imssoap\wsdl. If you choose to store the WSDL file in a different location, you must specify the entire path when deploying the Web service in the IMS SOAP Gateway deployment utility.
  11. For the IMS Connect XML Adapter only: To setup the IMS Connect XML Adapter to work with IMS SOAP Gateway:
    1. Store the correlator file generated by WebSphere Developer for zSeries in the IMS SOAP Gateway XML directory: installation_directory\server\webapps\imssoap\xml. For example: c:\Program Files\IBM\IMS SOAP Gateway\server\webapps\imssoap\xml. If you choose to store the correlator file in a different location, you must specify the entire path when deploying the Web service in the IMS SOAP Gateway deployment utility.
    2. Upload the COBOL XML converter driver generated by WebSphere Developer for zSeries to a newly allocated data set on the mainframe host.
    3. Concatenate the new COBOL XML converter driver data set to the IMS data set which contains the startup JCL by adding the new data set name to the STEPLIB DD statement.
Parent topic: Creating the WSDL file


Manually creating the WSDL file

To enable an application as a Web service, you must first create the Web service interface.

To create the Web service interface:
  1. Create an XML schema that maps the COBOL copybook data structures for the input message and output message of the application. Do not include the LLZZ prefix and transaction code in the schema. If you have a COBOL copybook, you can use it to help you create the schema.
  2. Create a Document/Literal style WSDL file that defines a Web service operation that uses the input and output messages that are defined in the XML schema. Put the schema that you created in step 1 in the <wsdl:types> element.
  3. Create the rest of WSDL file with the following rules:
    • The soap:operation soapAction attribute value must match the correlator file name.
    • The soap:operation style attribute value must be "document".
    • The SOAP address must be:
       http://hostname:port/imssoap/services/WebServicePortname
      where hostname is the location of IMS SOAP Gateway, port is the port number of IMS SOAP Gateway, and WebServicePortname matches the name attribute value of the port element.
  4. Store the WSDL file in the IMS SOAP Gateway WSDL directory: installation_directory\server\webapps\imssoap\wsdl. For example: c:\Program Files\IBM\IMS SOAP Gateway\server\webapps\imssoap\wsdl\SOAPService.wsdl. You can store the WSDL anywhere, but you must then specify the entire path when you are deploying the Web service.
Parent topic: Creating the WSDL file
Related information
WSDL file example


Modifying WSDL files that are generated by WebSphere Studio Application Developer

If you have WSDL files generated by using WebSphere® Studio Application Developer Integration Edition V5.1.x, you can modify them to use it with IMS SOAP Gateway.

WebSphere Studio Application Developer Integration Edition allows you to create an Enterprise Service application from the COBOL copybook for use with IMS Connector for Java™. The following WSDL files are generated when the Enterprise Service application is created for the IMS environment: prefixService.wsdl, prefixSOAPService.wsdl, and prefixSOAPServiceBinding.wsdl. These files can be modified to use with IMS SOAP Gateway. prefixIMSService.wsdl and prefixIMSBindling.wsdl files are generated as well, but they are not required by IMS SOAP Gateway.

To use a generated WSDL file for IMS SOAP Gateway, make the following changes to the WSDL files:

  1. Modify the XML schema part of the prefixService.wsdl file:
    1. Optional: Remove the LL, ZZ, and trancode elements of the input message. LLZZ and the trancode are added by IMS SOAP Gateway when it sends the message to IMS, and so these elements are ignored by IMS SOAP Gateway. For example, remove the following elements:
                 <element name="in__ll">
               <simpleType>
                  <restriction base="short">
                     <minInclusive value="-999"/>
                     <maxInclusive value="999"/>
                  </restriction>
               </simpleType>
            </element>
            <element name="in__zz">
               <simpleType>
                  <restriction base="short">
                     <minInclusive value="-999"/>
                     <maxInclusive value="999"/>
                  </restriction>
               </simpleType>
            </element>
            <element name="in__trcd">
               <annotation>
                  <appinfo source="http://www.wsadie.com/appinfo">
                     <initialValue kind="SPACE"/>
                  </appinfo>
               </annotation>
               <simpleType>
                  <restriction base="string">
                     <maxLength value="10"/>
                  </restriction>
               </simpleType>
            </element>
    2. Optional: Remove the LL and ZZ elements of the output message. For example, remove the following elements:
                  <element name="out__ll">
               <annotation>
                  <appinfo source="http://www.wsadie.com/appinfo">
                     <initialValue kind="string_value" value="+0"/>
                  </appinfo>
               </annotation>
               <simpleType>
                  <restriction base="short">
                     <minInclusive value="-999"/>
                     <maxInclusive value="999"/>
                  </restriction>
               </simpleType>
            </element>
            <element name="out__zz">
               <annotation>
                  <appinfo source="http://www.wsadie.com/appinfo">
                     <initialValue kind="string_value" value="+0"/>
                  </appinfo>
               </annotation>
               <simpleType>
                  <restriction base="short">
                    <minInclusive value="-999"/>
                    <maxInclusive value="999"/>
                  </restriction>
               </simpleType>
    3. After the definitions of the complex types and before the end of the schema, add elements that reference the input and output complex type elements. The name attribute value must match the name attribute value of the complexType elements, and the type attribute value must match the type attribute value of the part element. For example, add the following elements:
           ....
     </complexType>
     <element name="INPUTMSG" type="tns:INPUTMSG"/>
     <element name="OUTPUTMSG" type="tns:OUTPUTMSG"/>
        </schema>
     ....
    4. In the part elements, change the type attribute name to "element" to reference the input and output message. For example, modify the following:
      ...
</types>
<message name="runPhoneBookRequest">
   <part name="iNPUTMSG" element="tns:INPUTMSG"/>
</message>
<message name="runPhoneBookResponse">
   <part name="OUTPUTMSGPart" element="tns:OUTPUTMSG"/>
</message>
  2. Modify the prefixSOAPBinding.wsdl file:
    1. Change the style attribute value of the soap:binding element and of the soap:operation element from "rpc” to “document” For example:
      <binding name="PhoneBookSOAPBinding" type="interface1:PhoneBook">
   <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
   <operation name="runPhoneBook">
      <soap:operation soapAction="urn:PhoneBook" style="document"/>
    2. In the two soap:body elements, which are nested inside the input and output elements, change the use attribute values from "encoded" to “literal.” For example:
            <input name="runPhoneBookRequest">
         <soap:body
            encodingStyle=http://schemas.xmlsoap.org/soap/encoding/
            namespace="urn:PhoneBook" parts="iNPUTMSG" use="literal"/>
      </input>
      <output name="runPhoneBookResponse">
         <soap:body
            encodingStyle=http://schemas.xmlsoap.org/soap/encoding/
            namespace="urn:PhoneBook" parts="OUTPUTMSGPart"
            use="literal"/>
      </output>
  3. Modify the prefixSOAPService.wsdl file by changing location attribute value of the soap:address element to match the location of the IMS SOAP Gateway server and the port name of the Web service that is being installed. The SOAP address must be http://hostname:port/imssoap/services/WebServicePortname, where WebServicePortname matches the name attribute value of the port element,hostname is the location of IMS SOAP Gateway, and port is the port number of IMS SOAP Gateway. For example:
    <service name="PhoneBookService">
   <port binding="binding1:PhoneBookSOAPBinding"
      name="PhoneBookSOAPPort">
      <soap:address
location="http://localhost:8080/imssoap/services/PhoneBookSOAPPort"/>
   </port>
</service>
  4. Store the three WSDL files in the IMS SOAP Gateway. WSDL directory: installation_directory\server\webapps\imssoap\wsdl. For example: c:\Program Files\IBM\IMS SOAP Gateway\server\webapps\imssoap\wsdl. When you are required to specify a WSDL file to the IMS SOAP Gateway deployment utility, specify the prefixSOAPService.wsdl file.
Parent topic: Creating the WSDL file
Related information
WSDL file example


WSDL file example

The example WSDL file is for the IMS™ phonebook sample application.

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tns="file://target.files" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsd1="http://www.IMSPHBKI.com/schemas/IMSPHBKIInterface" xmlns:xsd2="http://www.IMSPHBKO.com/schemas/IMSPHBKOInterface" name="IMSPHBK" targetNamespace="file://target.files">
  <wsdl:types>
    <schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:cbl="http://www.IMSPHBKI.com/schemas/IMSPHBKIInterface" attributeFormDefault="qualified" elementFormDefault="unqualified" targetNamespace="http://www.IMSPHBKI.com/schemas/IMSPHBKIInterface">
      <complexType name="INPUTMSG">
        <sequence>
          <element name="in_ll">
            <simpleType>
              <restriction base="short">
                <minInclusive value="-999"/>
                <maxInclusive value="999"/>
              </restriction>
            </simpleType>
          </element>
          <element name="in_zz">
            <simpleType>
              <restriction base="short">
                <minInclusive value="-999"/>
                <maxInclusive value="999"/>
              </restriction>
            </simpleType>
          </element>
          <element name="in_trcd">
            <annotation>
              <appinfo source="http://www.wsadie.com/appinfo">
                <initialValue kind="SPACE"/>
              </appinfo>
            </annotation>
            <simpleType>
              <restriction base="string">
                <maxLength value="10"/>
              </restriction>
            </simpleType>
          </element>
          <element name="in_cmd">
            <annotation>
              <appinfo source="http://www.wsadie.com/appinfo">
                <initialValue kind="SPACE"/>
              </appinfo>
            </annotation>
            <simpleType>
              <restriction base="string">
                <maxLength value="8"/>
              </restriction>
            </simpleType>
          </element>
          <element name="in_name1">
            <annotation>
              <appinfo source="http://www.wsadie.com/appinfo">
                <initialValue kind="SPACE"/>
              </appinfo>
            </annotation>
            <simpleType>
              <restriction base="string">
                <maxLength value="10"/>
              </restriction>
            </simpleType>
          </element>
          <element name="in_name2">
            <annotation>
              <appinfo source="http://www.wsadie.com/appinfo">
                <initialValue kind="SPACE"/>
              </appinfo>
            </annotation>
            <simpleType>
              <restriction base="string">
                <maxLength value="10"/>
              </restriction>
            </simpleType>
          </element>
          <element name="in_extn">
            <annotation>
              <appinfo source="http://www.wsadie.com/appinfo">
                <initialValue kind="SPACE"/>
              </appinfo>
            </annotation>
            <simpleType>
              <restriction base="string">
                <maxLength value="10"/>
              </restriction>
            </simpleType>
          </element>
          <element name="in_zip">
            <annotation>
              <appinfo source="http://www.wsadie.com/appinfo">
                <initialValue kind="SPACE"/>
              </appinfo>
            </annotation>
            <simpleType>
              <restriction base="string">
                <maxLength value="7"/>
              </restriction>
            </simpleType>
          </element>
        </sequence>
      </complexType>
      <element name="INPUTMSG" type="cbl:INPUTMSG"/>
    </schema>
    <schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:cbl="http://www.IMSPHBKO.com/schemas/IMSPHBKOInterface" attributeFormDefault="qualified" elementFormDefault="unqualified" targetNamespace="http://www.IMSPHBKO.com/schemas/IMSPHBKOInterface">
      <complexType name="OUTPUTMSG">
        <sequence>
          <element name="out_ll">
            <simpleType>
              <restriction base="short">
                <minInclusive value="-999"/>
                <maxInclusive value="999"/>
              </restriction>
            </simpleType>
          </element>
          <element name="out_zz">
            <simpleType>
              <restriction base="short">
                <minInclusive value="-999"/>
                <maxInclusive value="999"/>
              </restriction>
            </simpleType>
          </element>
          <element name="out_msg">
            <annotation>
              <appinfo source="http://www.wsadie.com/appinfo">
                <initialValue kind="SPACE"/>
              </appinfo>
            </annotation>
            <simpleType>
              <restriction base="string">
                <maxLength value="40"/>
              </restriction>
            </simpleType>
          </element>
          <element name="out_cmd">
            <annotation>
              <appinfo source="http://www.wsadie.com/appinfo">
                <initialValue kind="SPACE"/>
              </appinfo>
            </annotation>
            <simpleType>
              <restriction base="string">
                <maxLength value="8"/>
              </restriction>
            </simpleType>
          </element>
          <element name="out_name1">
            <annotation>
              <appinfo source="http://www.wsadie.com/appinfo">
                <initialValue kind="SPACE"/>
              </appinfo>
            </annotation>
            <simpleType>
              <restriction base="string">
                <maxLength value="10"/>
              </restriction>
            </simpleType>
          </element>
          <element name="out_name2">
            <annotation>
              <appinfo source="http://www.wsadie.com/appinfo">
                <initialValue kind="SPACE"/>
              </appinfo>
            </annotation>
            <simpleType>
              <restriction base="string">
                <maxLength value="10"/>
              </restriction>
            </simpleType>
          </element>
          <element name="out_extn">
            <annotation>
              <appinfo source="http://www.wsadie.com/appinfo">
                <initialValue kind="SPACE"/>
              </appinfo>
            </annotation>
            <simpleType>
              <restriction base="string">
                <maxLength value="10"/>
              </restriction>
            </simpleType>
          </element>
          <element name="out_zip">
            <annotation>
              <appinfo source="http://www.wsadie.com/appinfo">
                <initialValue kind="SPACE"/>
              </appinfo>
            </annotation>
            <simpleType>
              <restriction base="string">
                <maxLength value="7"/>
              </restriction>
            </simpleType>
          </element>
          <element name="out_segno">
            <annotation>
              <appinfo source="http://www.wsadie.com/appinfo">
                <initialValue kind="SPACE"/>
              </appinfo>
            </annotation>
            <simpleType>
              <restriction base="string">
                <maxLength value="4"/>
              </restriction>
            </simpleType>
          </element>
        </sequence>
      </complexType>
      <element name="OUTPUTMSG" type="cbl:OUTPUTMSG"/>
    </schema>
  </wsdl:types>
  <wsdl:message name="IMSPHBKOperationRequest">
    <wsdl:part element="xsd1:INPUTMSG" name="INPUT-MSGPart"/>
  </wsdl:message>
  <wsdl:message name="IMSPHBKOperationResponse">
    <wsdl:part element="xsd2:OUTPUTMSG" name="OUTPUT-MSGPart"/>
  </wsdl:message>
  <wsdl:portType name="IMSPHBKPortType">
    <wsdl:operation name="IMSPHBKOperation">
      <wsdl:input message="tns:IMSPHBKOperationRequest" name="IMSPHBKOperationRequest"/>
      <wsdl:output message="tns:IMSPHBKOperationResponse" name="IMSPHBKOperationResponse"/>
    </wsdl:operation>
  </wsdl:portType>
  <wsdl:binding name="IMSPHBKBinding" type="tns:IMSPHBKPortType">
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <wsdl:operation name="IMSPHBKOperation">
      <soap:operation soapAction="urn:IMSPHBK" style="document"/>
      <wsdl:input name="IMSPHBKOperationRequest">
        <soap:body encodingStyle="literal" use="literal"/>
      </wsdl:input>
      <wsdl:output name="IMSPHBKOperationResponse">
        <soap:body encodingStyle="literal" use="literal"/>
      </wsdl:output>
    </wsdl:operation>
  </wsdl:binding>
  <wsdl:service name="IMSPHBKService">
    <wsdl:port binding="tns:IMSPHBKBinding" name="IMSPHBKPort">
      <soap:address location="http://localhost:8080/imssoap/services/IMSPHBKPort"/>
    </wsdl:port>
  </wsdl:service>
</wsdl:definitions>
Related tasks
Manually creating the WSDL file
Modifying WSDL files that are generated by WebSphere Studio Application Developer


Selecting the data transformation process and configuring the XML Adapter function

In order to handle the XML data from the client, you can either modify the IMS application to accept the XML input message and to return an XML output message, or use the WebSphere Developer for zSeries XML converter drivers to transform the XML data in IMS Connect such that you do not need to modify your IMS application.

One of the attractive features of the IMS SOAP Gateway Version 9.2, is the ability to allow clients to send and receive IMS transaction input and output messages in XML format without the need of changing the back-end IMS application. This feature is made possible by the Adapter Task Manager and the XML Adapter processing enhancement in IMS Connect.

The IMS Connect XML Adapter function allows the XML Adapter to run inside IMS Connect to perform the XML transformation in the IMS Connect address space. To handle IMS transaction input and output messages in XML format from the SOAP client, the XML Adapter converts the XML-tagged data to the appropriate IMS application format that the IMS application accepts.

The following steps provide a high-level description of the steps involved in configuring the IMS Connect XML Adapter function with IMS SOAP Gateway. For detailed instructions on setting up the IMS Connect XML Adapter function, see the IMS SOAP Gateway Phone Book Sample (IMSPBSample.zip) which can be downloaded from the IMS SOAP Gateway Web site.
  1. Install the IMS Connect APAR for the Adapter Task Manager which includes the XML Adapter function (PK24912). Instructions on how to configure the IMS Connect XML Adapter are located in the ++ HOLD card data in the IMS Connect APAR and in the IMS Connect Guide and Reference.
  2. Use WebSphere Developer for zSeries to generate a WSDL file, a correlator file, and the COBOL XML converter driver program for your IMS application.
  3. Upload the COBOL XML converter driver which was generated by WebSphere Developer for zSeries to your host IMS machine. Compile and link edit the program file such that it can be accessed by IMS Connect.
  4. Deploy the WSDL and correlator file to IMS SOAP Gateway using the IMS SOAP Gateway deployment utility.
If you chose not to use the XML Adapter function, you'll need the following information to modify your IMS application to handle XML formats:
  • Modifying the IMS application for XML messages
    If you are not using the XML Adapter function for data transformation, you must modify the IMS application. Use the provided guidelines and samples to accomplish the task.
Parent topic: Enabling an IMS application as a Web service
Related tasks
Setting up IMS Connect and IMS OTMA


Modifying the IMS application for XML messages

If you are not using the XML Adapter function for data transformation, you must modify the IMS application. Use the provided guidelines and samples to accomplish the task.

Message prefix

The client and IMS application must send and receive messages in XML that matches the XML schema in the WSDL file. The message data does not need to include LL, ZZ, or trancode information.

IMS requires:
  • All transaction messages to be prefixed by a two-byte LL field and a two-byte ZZ field
  • That the length of the transaction code field must be eight bytes or less for the first input message of the IMS application
  • That the LL, ZZ and transaction code fields are not wrapped in XML tags

To allow your XML-formatted IMS message data to reach your IMS application, IMS SOAP Gateway allows you to specify the transaction code value by specifying a correlator property. At runtime, IMS SOAP Gateway adds the simple EBCDIC byte values of the transaction code and LL and ZZ fields to XML-formatted IMS data input message. In addition, IMS SOAP Gateway adds the XML declaration, <?xml version="1.0" encoding="utf-8"?> , at the beginning of the XML-formatted IMS data input message.

IMS SOAP Gateway supports XML messages encoded in UTF-8 only. Specifically, this means that the input XML transaction data inside the SOAP message must be encoded in UTF-8 and the output XML transaction data from the IMS application must be encoded as UTF-8 as well. In addition, the IMS application must be able to handle the XML transaction data from IMS SOAP Gateway in UTF-8.

In addition, only single segment messages are currently supported. The maximum size of the message is 32K For input message, this length includes the XML input data, as well as the prefix LL, ZZ, transaction code and the XML declaration added by IMS SOAP Gateway. For output message, this length includes LL, ZZ and the output XML data.
Note: The XML schema can contains the LL, ZZ, and trancode definitions, but the values will not be used by IMS if you specify the transaction code value by using the IMS SOAP Gateway correlator property.

Sample

The IMS application has the following COBOL copybook:

            01  INPUT-MSG.
            02  IN-LL          PICTURE S9(3) COMP.
            02  IN-ZZ          PICTURE S9(3) COMP.
            02  IN-TRCD        PICTURE X(10).
            02  IN-CMD         PICTURE X(8).
            02  IN-NAME1       PICTURE X(10).
            02  IN-NAME2       PICTURE X(10).
            02  IN-EXTN        PICTURE X(10).
            02  IN-ZIP         PICTURE X(7).

        01  OUTPUT-MSG.
            02  OUT-LL       PICTURE S9(3) COMP VALUE +0.
            02  OUT-ZZ       PICTURE S9(3) COMP VALUE +0.
            02  OUT-MSG      PICTURE X(40) VALUE SPACES.
            02  OUT-CMD      PICTURE X(8) VALUE SPACES.
            02  OUT-NAME1    PICTURE X(10) VALUE SPACES.
            02  OUT-NAME2    PICTURE X(10) VALUE SPACES.
            02  OUT-EXTN     PICTURE X(10) VALUE SPACES.
            02  OUT-ZIP      PICTURE X(7) VALUE SPACES.
            02  OUT-SEGNO    PICTURE X(4) VALUE SPACES.
The following schema, which maps to the COBOL copybook, is in the WSDL file:
         <schema attributeFormDefault="qualified"
            elementFormDefault="unqualified"
            targetNamespace="http://ims.sample/"
            xmlns="http://www.w3.org/2001/XMLSchema" xmlns:xsd1="http://ims.sample/">
            <complexType name="INPUTMSG">
                <sequence>
                    <element name="in__ll">
                        <simpleType>
                            <restriction base="short">
                                <minInclusive value="-999"/>
                                <maxInclusive value="999"/>
                            </restriction>
                        </simpleType>
                    </element>
                    <element name="in__zz">
                        <simpleType>
                            <restriction base="short">
                                <minInclusive value="-999"/>
                                <maxInclusive value="999"/>
                            </restriction>
                        </simpleType>
                    </element>
                    <element name="in__trcd">
                        <annotation>
                            <appinfo source="http://www.wsadie.com/appinfo">
                                <initialValue kind="SPACE"/>
                            </appinfo>
                        </annotation>
                        <simpleType>
                            <restriction base="string">
                                <maxLength value="10"/>
                            </restriction>
                        </simpleType>
                    </element>
                    <element name="in__cmd">
                        <annotation>
                            <appinfo source="http://www.wsadie.com/appinfo">
                                <initialValue kind="SPACE"/>
                            </appinfo>
                        </annotation>
                        <simpleType>
                            <restriction base="string">
                                <maxLength value="8"/>
                            </restriction>
                        </simpleType>
                    </element>
                    <element name="in__name1">
                        <annotation>
                            <appinfo source="http://www.wsadie.com/appinfo">
                                <initialValue kind="SPACE"/>
                            </appinfo>
                        </annotation>
                        <simpleType>
                            <restriction base="string">
                                <maxLength value="10"/>
                            </restriction>
                        </simpleType>
                    </element>
                    <element name="in__name2">
                        <annotation>
                            <appinfo source="http://www.wsadie.com/appinfo">
                                <initialValue kind="SPACE"/>
                            </appinfo>
                        </annotation>
                        <simpleType>
                            <restriction base="string">
                                <maxLength value="10"/>
                            </restriction>
                        </simpleType>
                    </element>
                    <element name="in__extn">
                        <annotation>
                            <appinfo source="http://www.wsadie.com/appinfo">
                                <initialValue kind="SPACE"/>
                            </appinfo>
                        </annotation>
                        <simpleType>
                            <restriction base="string">
                                <maxLength value="10"/>
                            </restriction>
                        </simpleType>
                    </element>
                    <element name="in__zip">
                        <annotation>
                            <appinfo source="http://www.wsadie.com/appinfo">
                                <initialValue kind="SPACE"/>
                            </appinfo>
                        </annotation>
                        <simpleType>
                            <restriction base="string">
                                <maxLength value="7"/>
                            </restriction>
                        </simpleType>
                    </element>
                </sequence>
            </complexType>
            <complexType name="OUTPUTMSG">
                <sequence>
                    <element name="out__ll">
                        <annotation>
                            <appinfo source="http://www.wsadie.com/appinfo">
                                <initialValue kind="string_value" value="+0"/>
                            </appinfo>
                        </annotation>
                        <simpleType>
                            <restriction base="short">
                                <minInclusive value="-999"/>
                                <maxInclusive value="999"/>
                            </restriction>
                        </simpleType>
                    </element>
                    <element name="out__zz">
                        <annotation>
                            <appinfo source="http://www.wsadie.com/appinfo">
                                <initialValue kind="string_value" value="+0"/>
                            </appinfo>
                        </annotation>
                        <simpleType>
                            <restriction base="short">
                                <minInclusive value="-999"/>
                                <maxInclusive value="999"/>
                            </restriction>
                        </simpleType>
                    </element>
                    <element name="out__msg">
                        <annotation>
                            <appinfo source="http://www.wsadie.com/appinfo">
                                <initialValue kind="SPACE"/>
                            </appinfo>
                        </annotation>
                        <simpleType>
                            <restriction base="string">
                                <maxLength value="40"/>
                            </restriction>
                        </simpleType>
                    </element>
                    <element name="out__cmd">
                        <annotation>
                            <appinfo source="http://www.wsadie.com/appinfo">
                                <initialValue kind="SPACE"/>
                            </appinfo>
                        </annotation>
                        <simpleType>
                            <restriction base="string">
                                <maxLength value="8"/>
                            </restriction>
                        </simpleType>
                    </element>
                    <element name="out__name1">
                        <annotation>
                            <appinfo source="http://www.wsadie.com/appinfo">
                                <initialValue kind="SPACE"/>
                            </appinfo>
                        </annotation>
                        <simpleType>
                            <restriction base="string">
                                <maxLength value="10"/>
                            </restriction>
                        </simpleType>
                    </element>
                    <element name="out__name2">
                        <annotation>
                            <appinfo source="http://www.wsadie.com/appinfo">
                                <initialValue kind="SPACE"/>
                            </appinfo>
                        </annotation>
                        <simpleType>
                            <restriction base="string">
                                <maxLength value="10"/>
                            </restriction>
                        </simpleType>
                    </element>
                    <element name="out__extn">
                        <annotation>
                            <appinfo source="http://www.wsadie.com/appinfo">
                                <initialValue kind="SPACE"/>
                            </appinfo>
                        </annotation>
                        <simpleType>
                            <restriction base="string">
                                <maxLength value="10"/>
                            </restriction>
                        </simpleType>
                    </element>
                    <element name="out__zip">
                        <annotation>
                            <appinfo source="http://www.wsadie.com/appinfo">
                                <initialValue kind="SPACE"/>
                            </appinfo>
                        </annotation>
                        <simpleType>
                            <restriction base="string">
                                <maxLength value="7"/>
                            </restriction>
                        </simpleType>
                    </element>
                    <element name="out__segno">
                        <annotation>
                            <appinfo source="http://www.wsadie.com/appinfo">
                                <initialValue kind="SPACE"/>
                            </appinfo>
                        </annotation>
                        <simpleType>
                            <restriction base="string">
                                <maxLength value="4"/>
                            </restriction>
                        </simpleType>
                    </element>
                </sequence>
            </complexType>
            <element name="INPUTMSG" type="tns:INPUTMSG"/>
            <element name="OUTPUTMSG" type="tns:OUTPUTMSG"/>
        </schema>
The message to the IMS application then has the following format based on this schema:
  <?xml version="1.0" encoding="UTF-8"?>
  <INPUTMSG xmlns="">
   <in__cmd>DISPLAY</in__cmd>
   <in__name1>LAST1</in__name1>
   <in__name2></in__name2>
   <in__extn></in__extn>
   <in__zip></in__zip>
  </INPUTMSG>
The message that the IMS application sends back to the client as the following format based on this schema:
   <OUTPUTMSG xmlns="">
    <out__msg>ENTRY WAS DISPLAYED</out__msg>
    <out__cmd>DISPLAY</out__cmd>
    <out__name1>LAST1</out__name1>
    <out__name2></out__name2>
    <out__extn></out__extn>
    <out__zip></out__zip>
    <out__segno>0001</out__segno>
   </OUTPUTMSG>
Parent topic: Selecting the data transformation process and configuring the XML Adapter function
Related tasks
Writing the client application


Deploying a Web service with IMS SOAP Gateway

Use the deployment utility to deploy an application as a Web service. You can use the deployment utility in either Interactive or Expert mode.

We recommend that you use the IMS SOAP Gateway Deployment Utility in Interactive mode to deploy an application as a Web service for the first time. Task 1 in Interactive mode provides an interactive user interface which walks you through each command needed to deploy your application from end to end.

Prerequisite:
  • You must have a Web service interface, which is in one or possibly more WSDL (Web service description language) files.
  • Start IMS SOAP Gateway before deploying the Web service.

The deployment process consists of the following steps:

  1. Specifying the connection properties of the connection bundle
    Creating a connection bundle consists of specifying the connection properties between IMS SOAP Gateway, IMS Connect, and IMS.
  2. Specifying the correlator properties for a Web service
    Correlator properties specify how to interact with the IMS application for the Web service. Each deployed application or Web service must have a correlator file associated with it.
  3. Deploying the WSDL file
    Deploying the WSDL is the last step for deploying a Web service to IMS SOAP Gateway.
Parent topic: Enabling an IMS application as a Web service
Related tasks
Creating the WSDL file
Starting the IMS SOAP Gateway server
Related reference
Enable your IMS application as a Web service (Interactive mode)
Task 1: Enable your IMS application as Web service from start to finish


Specifying the connection properties of the connection bundle

Creating a connection bundle consists of specifying the connection properties between IMS SOAP Gateway, IMS Connect, and IMS.

To create a connection bundle with the deployment utility:
  • For Interactive mode select Task 6: Create, Update, Delete or View the connection bundle for a Web service. Select option c to create a connection bundle.
  • For Expert mode use the -conn command. Use option c to create a connection bundle.
After you create a connection bundle:
  • Specify the name of the connection bundle in the correlator properties for the Web service. You must specify the connection bundle name to allow IMS SOAP Gateway to identify which set of connection properties should be used for its associated Web service.
  • Restart the IMS SOAP Gateway after you create or change the connection properties.
  • Connection bundle
    The connection bundle specifies the connection and security properties between IMS SOAP Gateway, IMS Connect, and IMS.
  • Configuring secure socket layer (SSL) support
    In order to use SSL, both the client (IMS SOAP Gateway) and the server (IMS Connect) must be configured.
Parent topic: Deploying a Web service with IMS SOAP Gateway
Next topic: Specifying the correlator properties for a Web service
Related reference
Create or update the correlator file (Interactive mode)
Create or update the correlator file (Expert mode)
Create or update the connection bundle (Interactive mode)
Create or update the connection bundle (Expert mode)
Deployment Utility Expert Mode
Deployment Utility in Interactive Mode


Connection bundle

The connection bundle specifies the connection and security properties between IMS SOAP Gateway, IMS Connect, and IMS.

The connection bundle properties refer to the location and other parameters required for creating a TCP/IP socket connection to IMS. These properties are in a connection bundle XML file. You can create as many connection bundles as needed. However, each Web service can be associated with only one connection bundle at a time and Web service name must be specified in the Correlator file for that Web service.

Each connection bundle consists of the following connection and security properties:
  • Connection bundle name: A name to identify this set of connection properties.
  • IMS Connect hostname: Specifies the name or IP address of the host system where IMS Connect is running.
  • IMS Connect port number: The port number of IMS Connect.
  • IMS Datastore ID: The name of the target IMS datastore. It must match the ID parameter of the Datastore statement that is specified in the IMS Connect configuration member. It also serves as the XCF member name for IMS during internal XCF communications between IMS Connect and IMS OTMA.
  • User ID: The security authorization facility (SAF) user name that will be used for the connection to IMS.
  • Password: The security authorization facility (SAF) password that will be used for the connection to IMS.
  • Groupname: The security authorization facility (SAF) group name that will be used for the connection to IMS.
  • SSL Keystore name: Specifies the fully-qualified path name of the Keystore in which trusted certificates and private keys are stored.
  • SSL Keystore password: Specifies the password for the keystore. The password length must be between 6 and 20 characters.
  • SSL Trustore name: Specifies the fully-qualified path name of the Truststore in which trusted certificates are stored.
  • SSL Trustore password: Specifies the password of the Truststore in which trusted certificates are stored. The password length must be between 6 and 20 characters.
  • SSL Encryption level: Select the encryption type. A value of Strong indicates that a strong cipher suite needs to be used. A value of Weak indicates that a weak cipher suite needs to be used. A value of None indicates that no encryption will be used. The None encryption level is used only for authentication.
Parent topic: Specifying the connection properties of the connection bundle


Configuring secure socket layer (SSL) support

In order to use SSL, both the client (IMS SOAP Gateway) and the server (IMS Connect) must be configured.

IMS SOAP Gateway supports HTTPs connections between the client and the IMS SOAP Gateway server. SSL connections are supported between IMS SOAP Gateway and IMS Connect. Both of these features require you to provide valid key information for proper functioning. HTTPs support requires a keystore and password to be provided. The keystore must contain the certificate generated for IMS SOAP Gateway that will be presented to the client application trying to access a Web service. The same keystore can be used to set up the SSL connection to IMS Connect provided that it contains the IMS Connect certificate. However, you can set up a separate keystore or truststore for the SSL connection and a different keystore for the HTTPs connection if you choose to do so.

The following table provides a high level description of the steps you should follow to configure IMS SOAP Gateway and IMS Connect for SSL.
SSL Client (IMS SOAP Gateway) | SSL Server (IMS Connect)
 | 1. Decide if client authentication is required. If client authentication is not required, skip to Step 5.
2. If client authentication is required, obtain signed certificates and private keys in order to establish your identity. |
3. If client authentication is required, create a keystore and insert the client's private key and certificate. For more details, see "Creating the keystore or truststore for IMS SOAP Gateway" located in this topic. |
 | 4. If client authentication is required, import the client's public key certificate into the keyring. For more information, see the Version 9 IMS Connect User's Guide.
5. Create a truststore and import the Server's certificate. Alternatively, insert the Server's certificate into the client's keystore if you want to store the clients private keys and trusted certificates in the same file. |
 | 6. Decide which IMS Connect SSL port to use. Set up the IMS Connect and SSL Configuration members with the appropriate values. For more information about setting up these configuration members, see the Version 9 IMS Connect User's Guide.
7. Set up the connection bundle with the appropriate SSL parameters, including the port number from step 6. For more details, see "SSL configuration" located in this topic. |

Creating the keystore or truststore for IMS SOAP Gateway

For the client and server to authenticate one another an SSL connection must be set up. To do so, you must provide a JKS keystore to IMS SOAP Gateway and a RACF keyring to IMS Connect. The JKS keystore must have a valid X.509 certificate from IMS Connect for authentication. If client authentication is required, the IMS SOAP Gateway certificate must be added to the keyring in IMS Connect. There are several tools available for managing the keystore. To provide a JKS keystore on the client end, you must perform the following steps:
  • To set up the client, IMS SOAP Gateway, and if client authentication is required you can create a certificate and have it signed by a Certificate Authority (for example, VeriSign), or create your own Certificate Authority (CA) using software such as OpenSSL to sign your own (self-signed) certificate.
  • To create a keystore, use a Key management tool such as Ikeyman or Keytool. After the keystore is created, import IMS SOAP Gateway's private keys into the keystore. If you do not want to maintain a truststore, you can also import IMS Connect's certificates into the keystore.
  • To create a truststore, create another keystore and import the server's (IMS Connect's) certificate.

SSL configuration

A secure SSL connection between IMS SOAP Gateway and IMS Connect is created by ensuring that the connection bundle used by the client application has the appropriate values for its SSL properties.

  • Secure socket layer (SSL)
    SSL provides security for your interactions by securing the TCP/IP connection between the IMS SOAP Gateway and IMS Connect.
Parent topic: Specifying the connection properties of the connection bundle


Secure socket layer (SSL)

SSL provides security for your interactions by securing the TCP/IP connection between the IMS SOAP Gateway and IMS Connect.

With the evolution of the Web and on-demand information, data security has become very important for Internet users. The Secure Socket Layer (SSL) protocol ensures that the transfer of sensitive information over the Internet is secure. SSL protects information from:
  • Internet eavesdropping
  • Data theft
  • Traffic analysis
  • Data modification
  • Trojan horse browser /server

IMS SOAP Gateway communicates with IMS Connect through TCP/ IP sockets. If IMS SOAP Gateway uses TCP/ IP, SSL can be used to secure the TCP/ IP communication between the two entities. The SSL support provided by IMS SOAP Gateway and IMS Connect, uses a combination of public and private keys with symmetric key encryption schemes to achieve client and server authentication, data confidentiality, and integrity. SSL rests on top of TCP/ IP communication protocol and allows an SSL-enabled server to authenticate itself to an SSL-enabled client and vice versa. For an SSL connection between IMS SOAP Gateway and IMS Connect, IMS SOAP Gateway is considered to be the client and IMS Connect is considered to be the server. Once authentication is complete, the server and client can establish an encrypted connection that also preserves the integrity of the data.

SSL concepts

Certificate

A digital certificate is a digital document that validates the identity of the certificate's owner. A digital certificate contains information about the individual, such as their name, company, and public key. The certificate is signed with a digital signature by the Certificate Authority (CA), which is a trustworthy authority.
Certificate authority

A Certificate Authority (CA) is a trusted party that creates and issues digital certificates to users and systems. The CA, as a valid credential, establishes the foundation of trust in the certificates.
Certificate management

Certificates and private keys are stored in files called keystores. A keystore is a database of key material. Keystore information can be grouped into two categories: key entries and trusted certificate entries. The two entries can be stored in the same keystore or separately in a keystore and truststore for security purposes. Keystores and truststores are used by both the SSL client, IMS SOAP Gateway, and the SSL server, IMS Connect.
Keystore
A keystore holds key entries, such as the private key of the user. For example, the private key of IMS SOAP Gateway.
Truststore
A truststore is a keystore that holds only certificates that the user trusts. An entry should be added to a truststore only if the user makes a decision to trust that entity. An example of an IMS SOAP Gateway (client) truststore entry is the certificate of the target SSL server; IMS Connect.

SSL process

The SSL protocol consists of server authentication, client authentication (optional but strongly recommended) followed by an encrypted conversation. The following scenario steps through the SSL process.

Server authentication

SSL server authentication allows a client to confirm a server's identity. SSL-enabled client software uses standard techniques of public-key cryptography to ensure that a server's certificate and public ID is valid and that the certificate and ID was issued from one of the client's list of trusted certificate authorities (CA).
Client authentication

SSL client authentication allows a server to confirm a client's identity. Using the same techniques used for server authentication, SSL-enabled server software verifies that a client's certificate and public ID is valid and that the certificate and ID was issued by one of the server's list of trusted certificate authorities (CA).
SSL handshake

Both the client, IMS SOAP Gateway, and the server, IMS Connect, store their certificates and private keys in keystores. The actual SSL session between IMS SOAP Gateway and IMS Connect is established by following a handshake sequence between client and server. The sequence will vary depending on whether the server is configured to just provide a server certificate, or to provide a server certificate and request a client certificate, and which cipher suites are available to be used. A cipher is an encryption algorithm. The SSL protocol determines how the client and server negotiate the cipher suite to be use, authenticate one another, transmit certificates, establish session keys and transmit messages. Some of the algorithms used in cipher suites include:
  • DES - Data Encryption Standard
  • DSA - Digital Signature Algorithm
  • KEA - Key Exchange Algorithm
  • MD5 - Message Digest algorithm
  • RC2 and RC4 - Rivest encryption ciphers
  • RSA - A public key algorithm for both encryption and authentication
  • RSA key exchange - A key-exchange for SSL based on the RSA algorithm
  • SHA-1 - Secure Hash Algorithm
  • SKIPJACK - A classified symmetric-key algorithm implemented in FORTEZZA-compliant hardware
  • Triple-DES - DES applied three times.

SSL 2.0 and SSL 3.0 protocols support overlapping sets of cipher suites. Administrators can enable or disable any of the supported cipher suites for both clients and servers. When a particular client and server exchange information during the SSL handshake, the client and server identify the strongest enabled cipher suites that they have in common and use one of them for the SSL session.

Transport Layer Security, Version 1 (TLS V1) is the successor to SSL 3.0 protocol. IMS SOAP Gateway only supports TLS V1. There are no backward compatibility issues.

Parent topic: Configuring secure socket layer (SSL) support


Specifying the correlator properties for a Web service

Correlator properties specify how to interact with the IMS application for the Web service. Each deployed application or Web service must have a correlator file associated with it.

You can create the correlator properties for a new Web service using the IMS SOAP Gateway Deployment Utility in Interactive or Expert mode:
  • In Interactive mode use Task 5: Create, Update or View correlator properties for a Web service. Select option c to create a correlator file.
  • In Expert mode use the -corr command. Use option c to create a connection bundle.
  • Correlator file
    The correlator file specifies transaction, and runtime properties and the information that the IMS SOAP Gateway needs to match incoming requests to the appropriate back-end IMS application.
Parent topic: Deploying a Web service with IMS SOAP Gateway
Previous topic: Specifying the connection properties of the connection bundle
Next topic: Deploying the WSDL file
Related reference
Create or update the correlator file (Interactive mode)
Create or update the correlator file (Expert mode)
Create or update the connection bundle (Interactive mode)
Create or update the connection bundle (Expert mode)
Deployment Utility Expert Mode
Deployment Utility in Interactive Mode


Correlator file

The correlator file specifies transaction, and runtime properties and the information that the IMS SOAP Gateway needs to match incoming requests to the appropriate back-end IMS application.

These properties are stored in an XML file whose name must be the same as the SOAP Action URN of the Web service. The IMS SOAP Gateway Deployment Utility will obtain this information from the WSDL file for the Web service and follow this convention while creating this file. This file is also created by the WebSphere® Developer for Z series (WDz) tool. The correlator properties are as follows.

The correlation properties include:
  • Connection bundle name: The name of the connection bundle that contains the connection and security properties which will be used to connect with the IMS.
  • Socket Timeout: The timeout value for IMS SOAP Gateway to receive a response from IMS Connect.
  • Execution Timeout: The timeout value for IMS Connect to send a message to IMS and receive the response.
  • Lterm name: The name of the logical terminal.
  • IMS transaction code: The IMS transaction code is the transaction code of the IMS application that is invoked by the Web service. If you are using the XML adapter function, the transaction code value is part of the data that is handled by the XML Adapter. Therefore, if you are using the XML Adapter function do not specify the transaction code property.
  • COBOL XML converter driver program name: The COBOL XML converter driver program name generated by WebSphere Developer for zSeries. This driver program is used by the IMS Connect XML Adapter function to transform XML data into bytes for your IMS application. This parameter value is required if you are using the XML Adapter function.
  • XML Adapter type: The type of XML Adapter used by IMS Connect. The XML Adapter is the only adapter supported currently. If you are not using the XML Adapter function in IMS Connect, this value should set to blank.
Parent topic: Specifying the correlator properties for a Web service


Deploying the WSDL file

Deploying the WSDL is the last step for deploying a Web service to IMS SOAP Gateway.

Before you deploy the WSDL file, you must have a connection bundle and a correlator file.
To deploy the WSDL file:
Start the IMS SOAP Gateway Deployment Utility either in Interactive or Expert mode.
  • In Interactive mode, select task 7: Deploy the WSDL file
    • Follow the prompt instructions to provide the name and location of the WSDL file. For example, C:\IMSPHBK.wsdl.
    • Follow the instructions to provide the name and location of the correlator file. For example, C:\IMSPHBK.xml.
  • For Expert Mode, use the -deploy command.
After you deploy the WSDL file, you can view the newly deployed Web service in the IMS SOAP Gateway Administrative Console. The next step is to create a client application to access the IMS application as a Web service.
Note: You do not have to restart IMS SOAP Gateway unless you have created a new connection bundle or changed the connection bundle properties during the deployment process.
Parent topic: Deploying a Web service with IMS SOAP Gateway
Previous topic: Specifying the correlator properties for a Web service
Related concepts
IMS SOAP Gateway Administrative Console
Related tasks
Accessing the WSDL file of a deployed Web service
Related reference
-deploy :Deploy the WSDL file


Writing the client application

Write a client application which sends a SOAP message to invoke the IMS application as a Web service through IMS SOAP Gateway.

The way in which you write the client application depends on whether you use client proxy code. If you do not have proxy code, the client application itself is responsible for these tasks. The client proxy code is usually generated by a tool or utility and does the following:
  • Creates a connection to send and receive SOAP messages
  • Wraps the transaction data in a SOAP message

When building the client application, ensure that the transaction data inside the SOAP message is in an XML format that is understood by either IMS Connect or the IMS application designed to process XML. The client and either IMS Connect or the IMS application must adhere to the format of the input and output message as described in the schema definition of the WSDL file.

  • Generating the Java proxy code
    You can generate client proxy code in Java by using the IMS SOAP Gateway Deployment Utility.
Related tasks
Enabling an IMS application as a Web service
Generating the Java proxy code
Related reference
Modifying the IMS application for XML messages


Generating the Java proxy code

You can generate client proxy code in Java by using the IMS SOAP Gateway Deployment Utility.

Generating proxy code requires a WSDL file.

To generate the client proxy code:

  1. Start the deployment utility in Interactive or Expert mode.
    • For Interactive mode use Task 8: Generate Java client code.
    • For Expert mode use the -genclient command.
  2. Enter the location of the WSDL file and the path to where you want the generated code to be placed.
  3. Use the proxy code in your client application with the following steps:
    1. Create a Java application. The following example shows you how to create a Java application which uses the proxy client to invoke the Web service:
      import files.target.*;
import com.IMSPHBKI.www.schemas.IMSPHBKIInterface.*;
import com.IMSPHBKO.www.schemas.IMSPHBKOInterface.*;

public class IMSPHBKClient {
     public static void main(String[] args) {
          try {
       // Populate the input data
               INPUTMSG input = new INPUTMSG();
               input.setIn_cmd("DISPLAY");
               input.setIn_name1("LAST1");
               input.setIn_name2("");
               input.setIn_trcd("IVTNO");
               input.setIn_extn("");
               input.setIn_zip("");

               // Invoke the service
               IMSPHBKService phonebookservice = new IMSPHBKServiceLocator();
               IMSPHBKPortType phonebook = phonebookservice.getIMSPHBKPort();
               OUTPUTMSG output = phonebook.IMSPHBKOperation(input);

               // Display the output data
               System.out.println("Message: " + output.getOut_msg());
               System.out.println("Last name: " + output.getOut_name1());
               System.out.println("First name: " + output.getOut_name2());
               System.out.println("Extension: " + output.getOut_extn());
               System.out.println("Zip: " + output.getOut_zip());
          } catch (Exception exception) {
               exception.printStackTrace();
     }
}
     }
    2. Set up the classpath of the client application to include the <installation_dir>\server\webapps\imssoap\temp\client\wsclient.jar file.
    3. Compile and run the Java application.
Parent topic: Writing the client application
Related tasks
Writing the client application
Related reference
Task 8: Generate Java client code (Interactive mode)
Generate Java client code (Expert mode)


Administrating IMS SOAP Gateway

The administration of IMS SOAP Gateway is primarily performed through the IMS SOAP Gateway Deployment Utility which allows you to set up properties and create runtime code that IMS SOAP Gateway uses to enable IMS applications as Web services.

Use the IMS SOAP Gateway Deployment Utility in either Interactive or Expert mode to perform the following administrative tasks:

  • Starting the IMS SOAP Gateway server
    There are several ways to start the IMS SOAP Gateway server including using the deployment utility in either Interactive or Expert mode.
  • Stopping IMS SOAP Gateway server
    There are several ways to stop the IMS SOAP Gateway server using the deployment utility in either Interactive or Expert mode.
  • Starting the IMS SOAP Gateway Administrative Console
    The Administrative Console is opened easily for both Windows and AIX. Use the Administrative Console to view your deployed Web services.
  • Setting up the connections and correlator file properties for Web services
    You must set up the connection bundle and correlator file properties to ensure the proper functioning of the Web service. To set up these properties, use the IMS SOAP Gateway Deployment Utility in either Expert or Interactive mode.
  • Viewing Deployed Web services
    You can view the list of Web services being deployed by IMS SOAP Gateway. The IMS SOAP Gateway Administrative Console lists the deployed Web services when the server is started.
  • Accessing the WSDL file of a deployed Web service
    You can access the WSDL file for a web service after it has been deployed to IMS SOAP Gateway. For example, you may want to retrieve the WSDL file to create a client application to access the Web service. There are three ways to access the WSDL file: from the file system, from the Web, and with the SOAP Gateway Administrative Console.
  • Changing deployed Web services
    After you deploy a Web service, you can change interaction and connection properties by using the IMS SOAP Gateway Deployment Utility.
  • Undeploying a Web service
    Undeploying a Web service makes the IMS application unavailable as a Web service.
  • Changing port number for IMS SOAP Gateway server
    You can change the port number for IMS SOAP Gateway using the IMS SOAP Gateway Deployment Utility.


Starting the IMS SOAP Gateway server

There are several ways to start the IMS SOAP Gateway server including using the deployment utility in either Interactive or Expert mode.

To start the IMS SOAP Gateway server:
  • For Windows: From the Windows Start menu, select: Start > All Programs > IBM IMS SOAP Gateway Version 9.2 > Start Server.
  • For AIX: Run iogstart.sh in the <installation_dir>/bin directory.
  • For both Windows and AIX:
    • From the deployment utility in Interactive mode, select Task 2: Start IMS SOAP Gateway
    • From the deployment utility in Expert mode, use the -start command.
The IMS SOAP Gateway server starts. In Windows, the IMS SOAP Gateway windows opens and displays output messages from the server. In AIX, you can check the IMS SOAP Gateway log to verify that IMS SOAP Gateway is successfully started. The default location of the log file is <installation_dir>/server/logs/imssoap.log).
Parent topic: Administrating IMS SOAP Gateway
Related concepts
IMS SOAP Gateway server
Related tasks
Verifying the installation of IMS SOAP Gateway
Deploying a Web service with IMS SOAP Gateway
Related reference
Start IMS SOAP Gateway (Interactive mode)
Start an IMS SOAP Gateway server (Expert mode)


Stopping IMS SOAP Gateway server

There are several ways to stop the IMS SOAP Gateway server using the deployment utility in either Interactive or Expert mode.

To stop IMS SOAP Gateway server:
  • For Windows: From the Windows Start menu, select: Start > All Programs > IBM IMS SOAP Gateway Version 9.2 > Stop Server.
  • For AIX: Run iogstop.sh in the <installation_dir>/bin directory.
  • For both Windows and AIX using the deployment utility:
    • For Interactive mode, select Task 3: Stop the IMS SOAP Gateway.
    • For Expert mode, use the -stop command.
Parent topic: Administrating IMS SOAP Gateway
Related reference
Stop IMS SOAP Gateway (Interactive mode)
Stop IMS SOAP Gateway (Expert mode)


Starting the IMS SOAP Gateway Administrative Console

The Administrative Console is opened easily for both Windows and AIX. Use the Administrative Console to view your deployed Web services.

Prerequisite: The IMS SOAP Gateway server must be started.
  1. To start the IMS SOAP Gateway Administrative Console:
    • For Windows: Navigate to Start > All Programs > IBM IMS SOAP Gateway Version 9.2 > Administrative Console.
    • For AIX and Windows: From a Web browser, type http://hostname:port/imssoap

      where hostname is the hostname and port is the port number where IMS SOAP Gateway is running. .

    The console opens in a Web browser.
  2. Click View Deployed Web services. The list of the currently deployed Web services are displayed. Each item in the list is a link to the Web service's WSDL file.
    Note: If you start the Administrative Console from the same workstation where IMS SOAP Gateway is installed, then you can use the default port number and http://localhost:8080/imssoap as the URL.
Parent topic: Administrating IMS SOAP Gateway
Related concepts
IMS SOAP Gateway Administrative Console
Related tasks
Viewing Deployed Web services
Accessing the WSDL file of a deployed Web service
Related reference
Update IMS SOAP Gateway properties (Interactive mode)
Set IMS SOAP Gateway properties (Expert mode)


Setting up the connections and correlator file properties for Web services

You must set up the connection bundle and correlator file properties to ensure the proper functioning of the Web service. To set up these properties, use the IMS SOAP Gateway Deployment Utility in either Expert or Interactive mode.

Connection bundles contain the connection and security properties that IMS SOAP Gateway needs to communicate with IMS Connect and IMS. You should define one connection bundle for each IMS system that IMS SOAP Gateway will be communicating with in order to access an IMS application as a Web service. All the Web services can share the same connection bundle if they run in the same IMS instance.

The correlator file specifies the transaction, runtime, and correlation properties that IMS SOAP Gateway needs to match incoming requests to the appropriate back-end IMS application. Every Web service must have its own correlator file with the name of the connection bundle defined. Therefore, if you update the connection bundle, ensure that the correlator file is also updated as well.

Use either the Interactive or Expert mode of the deployment utility.
  • To change the interaction properties, which are in the correlator file:
    • For Interactive Mode, start the deployment utility and select Task 5: Create, Update or View correlator properties for a Web service.
    • For Expert Mode, use the -corr command.
  • To change the connection properties, which are in the connection bundle:
    1. For Interactive Mode, start the deployment utility and select Task 6: Create, Update, Delete or View the connection bundle for a Web service.
    2. For Expert Mode, use the -conn command.
Parent topic: Administrating IMS SOAP Gateway
Related reference
Create or update the correlator file (Interactive mode)
Create or update the correlator file (Expert mode)
Create or update the connection bundle (Interactive mode)
Create or update the connection bundle (Expert mode)
Deployment Utility Expert Mode
Deployment Utility in Interactive Mode


Viewing Deployed Web services

You can view the list of Web services being deployed by IMS SOAP Gateway. The IMS SOAP Gateway Administrative Console lists the deployed Web services when the server is started.

Prerequisite: The IMS SOAP Gateway server must be started.
To view the list of deployed Web services:
  1. Open the IMS SOAP Gateway Administrative Console:
    • For Windows: Select Start -> All Programs -> IBM IMS SOAP Gateway Version 9.2 -> Administrative Console.
    • For Unix and Windows: From a Web browser, type: http://hostname:port/imssoap, where hostname is the hostname and port is the port number where IMS SOAP Gateway is running.
  2. Click View Deployed Web services. A list of Web services that are currently deployed is listed. Each item in the list is a link to the Web service's WSDL file.
Parent topic: Administrating IMS SOAP Gateway
Related tasks
Starting the IMS SOAP Gateway Administrative Console


Accessing the WSDL file of a deployed Web service

You can access the WSDL file for a web service after it has been deployed to IMS SOAP Gateway. For example, you may want to retrieve the WSDL file to create a client application to access the Web service. There are three ways to access the WSDL file: from the file system, from the Web, and with the SOAP Gateway Administrative Console.

To retrieve the WSDL file for a deployed Web service:
  • From the file system, locate the WSDL file for the deployed Web services in the directory <installation_directory>\server\webapps\imssoap\wsdl (for Windows) and <installation_directory>/server/webapps/imssoap/wsdl (for AIX)
  • From the Web, locate the WSDL file for the deployed Web services using http://<hostname:port>/imssoap/services/<service_name>?WSDL, where <hostname> is IMS SOAP Gateway hostname, <port> is IMS SOAP Gateway port number, and <service_name> is the service name of the Web service being deployed to IMS SOAP Gateway.
  • From the Administrative Console, view the WSDL file of the deployed web services using the Administrative Console by clicking the service name of the deployed service in the View Deployed Services page.
Parent topic: Administrating IMS SOAP Gateway
Related tasks
Starting the IMS SOAP Gateway Administrative Console
Deploying the WSDL file


Changing deployed Web services

After you deploy a Web service, you can change interaction and connection properties by using the IMS SOAP Gateway Deployment Utility.

Use either the Interactive or Expert mode of the deployment utility.
To change the interaction properties, which are in the correlator file:
  • For Interactive mode, start the deployment utility and select Task 5: Create, Update or View correlator properties for a Web service and select the Update option.
  • For Expert Mode, use the -corr command with the -u option.
To change the connection properties, which are in the connection bundle:
  • For Interactive mode, start the deployment utility and select Task 6: Create, Update, Delete or View the connection bundle for a Web service and select the Update option.
  • For Expert mode, use the -conn command with the -u option.
To change the WSDL file, you have to make modifications to the WSDL file manually and then use one of the following to redeploy it:
  • For Interactive mode, start the deployment utility and select Task 7: Deploy the WSDL file .
  • For Expert mode, use the -deploy command.

Restart IMS SOAP Gateway after you change the connection properties.

Parent topic: Administrating IMS SOAP Gateway
Related reference
Create, Update or View correlator properties for a Web Service (Interactive mode)
Create or update the correlator file (Expert mode)
Create, Update, Delete or View the connection bundle (Interactive mode)
Create, update, or delete a connection bundle (Expert mode)
Deploy the WSDL file (Interactive mode)
Deploy the WSDL file (Expert mode)


Undeploying a Web service

Undeploying a Web service makes the IMS application unavailable as a Web service.

To undeploy a Web service:
Start the deployment utility either in Interactive or Expert mode.
  • For Interactive Mode, select Task 9: Undeploy a Web service.
  • For Expert Mode, use the -undeploy command.
Note: The WSDL and the correlator properties file do not get physically removed from the directory when the Web service is being undeployed. You can reuse these files if you need to redeploy the Web service in the future. If you do not remove the WSDL and the correlator properties file and choose to redeploy them, you can specify the file name without the fully-qualified path during deployment.
Parent topic: Administrating IMS SOAP Gateway
Related reference
Undeploy an application as a Web service (Interactive mode)
Undeploy an application as a Web service (Expert mode)


Changing port number for IMS SOAP Gateway server

You can change the port number for IMS SOAP Gateway using the IMS SOAP Gateway Deployment Utility.

The default port number for IMS SOAP Gateway is configured to run on port 8080 and to listen to the SOAP request over the HTTP communication protocol. If the HTTPSs port is enabled, the default is 8443. To change the default port number:
  • From the deployment utility in Interactive mode, select Task 4: Update IMS SOAP Gateway properties
  • From the deployment utility in Expert mode, use the -prop command.
After the port number changes, the URL used to access the Web services running on IMS SOAP Gateway is changed. Therefore, you must change the URL that is used to access the Web services in your client applications.
After the port number is changed, restart IMS SOAP Gateway server.
Parent topic: Administrating IMS SOAP Gateway
Related reference
Update IMS SOAP Gateway properties (Interactive mode)
Set IMS SOAP Gateway properties (Expert mode)


Troubleshooting

This section provides the following troubleshooting information:

  • Tips for diagnosing Installation Verification Program errors
    Running the IVP for IMS SOAP Gateway is usually trouble free. However, if you do experience an error this topic lists the possible errors and recommended solutions for these problems.
  • Diagnosing runtime errors
    The topics in this section provide information on how to log and trace information to diagnose problems, as well as listing the error messages for IMS SOAP Gateway.


Tips for diagnosing Installation Verification Program errors

Running the IVP for IMS SOAP Gateway is usually trouble free. However, if you do experience an error this topic lists the possible errors and recommended solutions for these problems.

If the IVP does not complete successfully, it may be due to one of the following errors:
  • A page not found error when accessing the IMS SOAP Gateway IVP Web client from the Web browser. Possible causes for this error are:
    • The IMS SOAP Gateway server may not be started.
    • The host name and port number you specified in the URL of the IVP Web client for IMS SOAP Gateway is not correct.
  • You receive the error message, com.ibm.ims.soap.xmlparser.XMLFileException: IOGS029E: Connection bundle name [imssoapivp] not found.
    • Possible cause of this error:
      • The connection bundle with the name imssoapivp has not been created.
      • IMS SOAP Gateway was not restarted after the connection bundle imssoapivp was created.
    • User action:
      • Follow the instructions in "Verifying the installation of IMS SOAP Gateway" to create a connection bundle named imssoapivp.
      • Ensure that you restart IMS SOAP Gateway after you create the connection bundle and before you run the IVP.
  • You receive the error message, com.ibm.ims.soap.server.IMSSOAPException: IOGC003E: Failed to send and receive messages from IMS Connect. Hostname [hostname], port [port]. [SocketException: Connection reset]
    • Possible cause of this error:
      • The User Message Exit HWSSOAP1 has not been properly installed with IMS Connect to handle the input message from IMS SOAP Gateway. If this happen, you will also see the following message on the z/OS® console for associated IMS Connect, HWSP1445E UNKNOWN EXIT NAME SPECIFIED IN MESSAGE PREFIX; MSGID=*HWSOA1*/ HWSSOA1 , M=SDRC.
    • User action: Follow the instructions in "Setting up the user exit routine for IMS Connect" to ensure that the User Message Exit HWSSOAP1 installed properly.
  • An error message returned when you invoke the IMS SOAP Gateway IVP Web client.
    • Possible cause of this error:
      • Invalid data was specified when configuring the connection bundle properties for the host IMS environment. For example:
        • The IMS host name is misspelled and is not sufficiently qualified (for TCP/IP communication).
          Attention: In some environments the IP address may be required.
        • An incorrect IMS Port Number was specified for the target IMS Connect (for TCP/IP communication).
        • IMS Datastore name is invalid for the target IMS or is misspelled. Datastore name must be in uppercase characters.
      • IMS is not running.
      • IMS Connect is not running. For more information IMS Connect, see the IMS Version 9: IMS Connect Guide and Reference .
      • The IMS Connect port is not active. Use the IMS Connect command VIEWHWS to determine if the port is active. Use the IMS Connect command OPENPORT to activate an IMS Connect port.
      • The target IMS datastore is not active. Use the IMS Connect command VIEWHWS to determine if the datastore is active. Use the IMS Connect command OPENDS to activate a IMS datastore.
      • TCP/IP failure. Always ensure a successful ping to your IMS environment prior to running the IVP.
    • User action: Check the IMS SOAP Gateway messages and codes for the error message to perform the appropriate user action.
Parent topic: Troubleshooting
Related tasks
Verifying the installation of IMS SOAP Gateway


Diagnosing runtime errors

The topics in this section provide information on how to log and trace information to diagnose problems, as well as listing the error messages for IMS SOAP Gateway.

IMS SOAP Gateway logs the error messages in the following two places:
  • For Windows only: IMS SOAP Gateway Server Window
  • IMS SOAP Gateway log file
  • Tips for diagnosing run-time errors
    This topic provides information on diagnosing run-time errors.
  • Tracing
    You can turn on internal tracing for IMS SOAP Gateway to help diagnosis problems. The trace level can be changed to control the amount of logging and tracing.
  • Changing the log file
    IMS SOAP Gateway logs all informational and error messages. By default the log file is located in <server_installdir>\server\logs\imssoap.log . You can change the log file by changing the log filename and location using the IMS SOAP Gateway deployment utility.
  • Messages for IMS SOAP Gateway
    IMS™ SOAP Gateway returns messages with the prefixes IOGC, IOGS, and IOGX.
Parent topic: Troubleshooting


Tips for diagnosing run-time errors

This topic provides information on diagnosing run-time errors.

  • When you start IMS SOAP Gateway, you receive the error, Error initializing endpoint java.net.BindException: The socket name is already in use.: port_number. This error appears in the IMS SOAP Gateway console window (for Windows only) or in the log file.
    • Explanation: IMS SOAP Gateway failed to start because the port number is already in use.
    • Possible causes of this error:
      • Another instance of IMS SOAP Gateway has been started.
      • If there is no other instance of IMS SOAP Gateway already started, then, there is some other program on the machine has already used the port number.
    • User Action:
      • Verify that another instance of IMS SOAP Gateway is not already started. You can verify whether another instance of IMS SOAP Gateway has already started by looking at the IMS SOAP Gateway log. You can also bring up the Administrative Console to see if IMS SOAP Gateway has already started. Note: The Administrative Console can only be started if IMS SOAP Gateway is up and running.
      • If several programs share the same port number, then you must change the port number value for IMS SOAP Gateway. Use the "Set IMS SOAP Gateway properties" task in IMS SOAP Gateway Deployment Utility to change the port number value.
  • You man receive a connection error when the client application submits a SOAP request to IMS SOAP Gateway. .
    • Explanation: The client is unable to communicate with IMS SOAP Gateway.
    • Possible cause of this error:
      • IMS SOAP Gateway has not been started.
      • The client application is using the wrong host name and port number for the URL that is used to access IMS SOAP Gateway. This error can occur when you change the host name and port number of IMS SOAP Gateway.
    • User action:
      • Verify that IMS SOAP Gateway is started. You can verify that IMS SOAP Gateway is started by viewing the IMS SOAP Gateway log. In addition, you can bring up the Administrative Console. Since you can only view the Administrative Console when IMS SOAP Gateway is started, this simple action serves as a good way to quickly test if IMS SOAP Gateway is up and running.
      • Ensure that your client application is using the correct host name and port number for the URL that is used to access IMS SOAP Gateway.
  • You may receive a keystore or keystore password error during server start up, that will prevent the IMS SOAP Gateway from running.
    • Explanation: The server is unable to initialize the HTTPs port as one of the properties is incorrect.
    • Possible cause of this error:
      • HTTPs keystore name is incorrect or the keystore specified doesn‘t exist.
      • HTTPs keystore password is incorrect, meaning it cannot open the specified keystore file.
      • HTTPs port number is not valid.
    • User action:
      • Ensure that the Keystore specified for HTTPs is valid and exists at the specified location. Ensure that the keystore name includes the full path to the keystore file.
      • Ensure that the keystore password specified is correct and can be used to open the keystore file.
      • Ensure that the HTTPs port specified is valid for the machine in which the IMS SOAP Gateway is running. Try a different port if the error persists.
      • Delete the HTTPs port (if it's not needed). Go to <Install_Dir>\server\conf\server.xml and delete the connector element. The connector element can be found under,<!--DONOT CHANGE : IMS SOAP Gateway Ports can be added below. -->. The following is an example of a connector element:
        <Connector port="8443"

maxThreads="150" minSpareThreads="25" maxSpareThreads="75"enableLookups="false"
disableUploadTimeout="true" acceptCount="100" debug="0" scheme="https"
secure="true clientAuth="false" sslProtocol="SSL"
keystoreFile="C:\Program Files\IBM\IMS SOAP Gateway\server\webapps\imssoap
\imssoap.ks" keystorePass="changeit algorithm="IbmX509"  />
        Note: This example contains properties that might differ from your connector element.
      • Restart the server.
Parent topic: Diagnosing runtime errors


Tracing

You can turn on internal tracing for IMS SOAP Gateway to help diagnosis problems. The trace level can be changed to control the amount of logging and tracing.

To set the trace levels for IMS SOAP Gateway:
  1. Start IMS SOAP Gateway Deployment Utility.
    • For Interactive mode, select Task 4: Update IMS SOAP Gateway properties.
    • For Expert mode, Use the-prop command.
  2. Change to the desired trace level using the following values:
    Table 1. Trace level values and description
    Trace level value | Trace level | Description
    1 | Fatal | Only errors and exceptions are logged. This is the default level.
    2 | Error | If the value is not divisible by 10, it is converted to the next greater increment of 10.
    3 | Warn | Errors and exceptions plus warning messages are logged.
    4 | Information | Errors and exceptions, information of important events are logged.
    5 | Debug | Errors and exceptions, the entry and exit of important events and functions, and the contents of buffers sent to and received from IMS Connect and IMS SOAP Gateway are logged.
  3. Restart IMS SOAP Gateway after the trace level is changed.
Parent topic: Diagnosing runtime errors
Related reference
Update IMS SOAP Gateway properties (Interactive mode)
Set IMS SOAP Gateway properties (Expert mode)


Changing the log file

IMS SOAP Gateway logs all informational and error messages. By default the log file is located in <server_installdir>\server\logs\imssoap.log . You can change the log file by changing the log filename and location using the IMS SOAP Gateway deployment utility.

To change the log file for IMS SOAP Gateway:
Start IMS SOAP Gateway Deployment Utility.
  • For Interactive mode, select Task 4: Update IMS SOAP Gateway properties.
  • For Expert mode, use the -prop command.
Parent topic: Diagnosing runtime errors
Related reference
Update IMS SOAP Gateway properties (Interactive mode)
Set IMS SOAP Gateway properties (Expert mode)


Messages for IMS SOAP Gateway

IMS™ SOAP Gateway returns messages with the prefixes IOGC, IOGS, and IOGX.

  • IOGC messages
    IOGC messages are messages that result from errors from IMS or IMS Connect.
  • IOGS messages
    IOGS messages are returned from the SOAP server.
  • IOGX messages
    IOGX messages are returned from the XML parser.
Parent topic: Diagnosing runtime errors


IOGC messages

IOGC messages are messages that result from errors from IMS™ or IMS Connect.

  • IOGC001E
    Failed to connect to IMS Connect. Hostname[hostname], port [portnumber]. [error_message].
  • IOGC002E
    Socket timeout value [socket_timeout] is invalid. [error_message].
  • IOGC003E
    Failed to send and receive messages from IMS Connect. Hostname [hostname], port [portnumber]. [error_message].
  • IOGC005E
    IMS SOAP Gateway internal error. [error_message]
  • IOGC006E
    IMS Connect XML Adapter returns an error. Return code: [returncode]. failure
  • IOGC007E
    IMS Connect had an internal error. Return code: [returncode], Reason code: [reasoncode].
  • IOGC008E
    IMS returned an error: [DFS_message]
  • IOGC009E
    The value [lterm] for the LTERM property exceeds 8 characters.
  • IOGC010E
    The value [password] of the Password property exceeds 8 characters.
  • IOGC011E
    The value [user ID] of the User ID property exceeds 8 characters.
  • IOGC012E
    The value [groupname] of the Group name property exceeds 8 characters.
  • IOGC013E
    The value [datastore] of the Datastore name property exceeds 8 characters.
  • IOGC014E
    The value [driver] of the XML converter driver name property exceeds 8 characters.]
  • IOGC020E
    The Execution timeout property value [executiontimeout] is invalid. The execution timeout value must either be -1 or in the range from 0 to 3 600 000 millseconds.
  • IOGC028E
    The IMS Connect RSM message is formatted incorrectly. Unable to retrieve the content.
  • IOGC029E
    The IMS Connect message is not formatted correctly.
  • IOGC030E
    The IMS Connect XML Adapter message is not formatted correctly.
  • IOGC031E
    The XML converter driver reports an error. [error_message].
  • IOGC034E
    Socket Timeout has occurred for this interaction. The Socket Timeout value specified was [sockettimeout] milliseconds. [error_message]
  • IOGC035E
    IMS Connect default timeout has occurred for this interaction.
  • IOGC036E
    Execution timeout has occurred for this interaction. The timeout value used was [exeuctiontimeout] milliseconds.
  • IOGC037E
    The specified XML Converter Driver name cannot be empty or all blanks.
  • IOGC040E
    IOGC040E: Bad output message.
  • IOGC041E
    IMS Connect returns an error. Return code: [returncode]. Reason code: [reasoncode]. [error_message]
  • IOGC042E
    The value [trancode] of the IMS Transaction code property exceeds 8 characters.
  • IOGC051E
    IMS Connect return an error. IMS Datastore is not available.
Parent topic: Messages for IMS SOAP Gateway


IOGC001E

Failed to connect to IMS Connect. Hostname[hostname], port [portnumber]. [error_message].

Explanation

IMS SOAP Gateway was unable to connect to the host and port combination. The error_message indicates the reason for the failure to connect.

User action

Examine the error message to determine the reason for the failure to connect to the host. Possible errors:
UnknownHostException: hostname
The hostname that you specified in the connection bundle is invalid. You might have to use the fully qualified path for host name or the IP address.
ConnectException: Connection refused
Possible reasons:
  • The port number is invalid. Ensure that you are using a valid port number for the IMS™ Connect indicated by hostname.
  • The specified port is stopped. You can determine whether the port is stopped by using the IMS Connect command VIEWHWS. If the port is stopped, its status is NOT ACTIVE. Use the IMS Connect command OPENPORT portnumber to start the port.
  • IMS Connect on the specified host is not running. Start IMS Connect on the host system.
  • TCP/IP was restarted without canceling and restarting IMS Connect or issuing the command STOPPORT followed by OPENPORT on the host.
SocketException: Network is unreachable: connect
Possible reasons:
  • The system with the specified host name is unreachable on the TCP/IP network. Ensure that the host system is accessible from the TCP/IP network by issuing the ping command to the specified host system from the system on which IMS SOAP Gateway is running. Start TCP/IP on the host if it is not started.
  • TCP/IP was restarted, but the status of the port that is used by the application was NOT ACTIVE. To fix the problem, you can do one of the following:
    • Use the IMS Connect command OPENPORT portnumber to start the port.
    • Restart IMS Connect.
Parent topic: IOGC messages


IOGC002E

Socket timeout value [socket_timeout] is invalid. [error_message].

Explanation

The value socket_timeout that was specified for the socket timeout property in the correlator file is not valid. error_message denotes the reason for the failure.

User action

One of possible errors is IllegalArgumentException: timeout can't be negative, which indicates that a negative value has been provide for the socket timeout value. Ensure a positive numerical value was given for the socket timeout in the correlator file.
Parent topic: IOGC messages


IOGC003E

Failed to send and receive messages from IMS Connect. Hostname [hostname], port [portnumber]. [error_message].

Explanation

IMS SOAP Gateway was unable to successfully complete a send and receive interaction with the target IMS Connect. error_message indicates the reason for the failure to complete the interaction.

User action

Possible values for error_message and their associated user actions:
EOFException
A possible reason for this exception is that IMS Connect has closed the connection because of an error occurred. See the z/OS® console for associated IMS Connect error messages. IMS Connect error messages begin with the characters " HWS." For more diagnostic information on the other return code and reason code values, and IMS Connect error messages, see the IMS Version 9: IMS Connect Guide and Reference.
SocketException: Connection reset by peer: socket write error
Possible reasons for the exception are:
  • The underlying socket connection that is used for the interaction is no longer connected to IMS Connect. This can happen if IMS Connect is restarted during the interaction.
  • TCP/IP on the host is shutting down.
SocketException: Connection reset

A possible reason for this exception is that IMS Connect has closed the connection because of an error occurred. See the z/OS® console for associated IMS Connect error messages. IMS Connect error messages begin with the characters " HWS." For more diagnostic information on the other return code and reason code values, and IMS Connect error messages, see the IMS Version 9: IMS Connect Guide and Reference.

Another possible reason is that the User Message Exit HWSSOAP1 has not been properly installed with IMS Connect to handle the input message from IMS SOAP Gateway. See the following message on the z/OS® console for associated IMS Connect:
HWSP1445E UNKNOWN EXIT NAME SPECIFIED IN MESSAGE PREFIX; MSGID=*HWSOA1*/ HWSSOA1 , M=SDRC
Follow the instructions in Setting up the user exit routine for IMS Connect to have your User Message Exit HWSSOAP1 installed properly to resolve the problem.
Parent topic: IOGC messages


IOGC005E

IMS SOAP Gateway internal error. [error_message]

Explanation

An internal error has occurred in IMS™ SOAP Gateway.

User action

Contact IBM® Software Support. Specify the error message when reporting the problem.
Parent topic: IOGC messages


IOGC006E

IMS Connect XML Adapter returns an error. Return code: [returncode]. failure

Explanation

IMS Connect XML Adapter returned an error. The error_message variable provides a brief description of the return code.

User action

Look at the error message to determine the reason for the failure. Possible errors are:
  • Return code: [108]. Inbound Error: The specified XML Converter Driver was not found or there was a load failure.
    Possible cause of this error:
    • The XML Converter Driver has not been compiled and link edit into load library. Ensure you have upload the XML Converter Driver program generated by WebSphere Developer for zSeries to your mainframe system. Make sure the driver program has been compiled and link edit into a data set or load library that is accessible by IMS Connect.
    • You have specified a wrong XML Converter Driver name in the correlator file for the Web service. Correct the driver name property value in the correlator file for the Web service.
    • The XML Converter Driver is bad and causes a load failure.
  • Return code: [208]. Outbound Error: The specified XML Converter Driver was not found or there was a load failure.
    Possible cause of this error:
    • The XML Converter Driver has not been compiled and link edit into load library. Ensure you have upload the XML Converter Driver program generated by WebSphere Developer for zSeries to your mainframe system. Make sure the driver program has been compiled and link edit into a data set or load library that is accessible by IMS Connect.
    • You have specified a wrong XML Converter Driver name in the correlator file for the Web service. Correct the driver name property value in the correlator file for the Web service.
    • The XML Converter Driver is bad and causes a load failure.
  • If you receive other return code values, contact IBM support.
Parent topic: IOGC messages


IOGC007E

IMS Connect had an internal error. Return code: [returncode], Reason code: [reasoncode].

Explanation

An internal error has occurred in IMS™ Connect.

User action

Contact IBM® Software Support. Specify the return code and reason code when reporting the problem.
Parent topic: IOGC messages


IOGC008E

IMS returned an error: [DFS_message]

Explanation

IMS returned the IMS™ message DFS_message instead of the transaction output message.

User action

See the message explanation in IMS Version 9: Messages and Codes Volume 2. Some of the possible messages are:
  • DFS065 hh:mm:ss TRAN/LTERM STOPPED

    The IMS transaction that the client wants to invoke is stopped. The transaction might have been stopped by the IMS /STOP command. Ensure that theIMS transaction is started. Use the IMS command /START to start the transaction if needed.

  • DFS1292E SECURITY VIOLATION

    IMS OTMA has rejected the IMS transaction request because it failed the security check. Ensure that the user ID and the optional group name value in the connection bundle properties valid.

  • DFS064 hh:mm:ss DESTINATION CAN NOT BE FOUND OR CREATED

    The transaction code value in the input request could not be recognized as a valid IMS transaction. Ensure that the transaction code property value in the
    correlator properties is valid.

Parent topic: IOGC messages


IOGC009E

The value [lterm] for the LTERM property exceeds 8 characters.

Explanation

The value of the LTERM property exceeds eight characters.

User action

Correct the length of the LTERM property value in the correlator properties for the Web service to be less than or equal to eight characters.
Parent topic: IOGC messages


IOGC010E

The value [password] of the Password property exceeds 8 characters.

Explanation

The value of the password property exceeds eight characters.

User action

Correct the length of the password property value in the connection bundle properties for the Web service to be less than or equals to eight.
Parent topic: IOGC messages


IOGC011E

The value [user ID] of the User ID property exceeds 8 characters.

Explanation

The value of the user name property exceeds eight characters.

User action

Correct the length of the user name property value in the connection bundle properties for the Web service to be less than or equal to eight characters.
Parent topic: IOGC messages


IOGC012E

The value [groupname] of the Group name property exceeds 8 characters.

Explanation

The value of the group name property exceeds eight characters.

User action

Correct the length of the group name property value in the connection bundle properties of the Web service to be less than or equal to eight characters.
Parent topic: IOGC messages


IOGC013E

The value [datastore] of the Datastore name property exceeds 8 characters.

Explanation

The value of the datastore name property exceeds eight characters.

User action

Correct the length of the datastore name property value in the correlator properties of the Web service to be less than or equal to eight characters.
Parent topic: IOGC messages


IOGC014E

The value [driver] of the XML converter driver name property exceeds 8 characters.]

Explanation

The value of the XML converter driver name property exceeds eight characters.

User action

The length of the XML converter driver name property value located in the correlator properties of the Web service should be less than or equal to eight characters.
Parent topic: IOGC messages


IOGC020E

The Execution timeout property value [executiontimeout] is invalid. The execution timeout value must either be -1 or in the range from 0 to 3 600 000 millseconds.

Explanation

The execution timeout property value [executiontimeout] is invalid.

User action

Change the execution timeout property to between -1 to 3 600 000 in the correlator properties of the Web service.
Parent topic: IOGC messages


IOGC028E

The IMS Connect RSM message is formatted incorrectly. Unable to retrieve the content.

Explanation

An internal error has occurred in IMS™ Connect.

User action

Contact IBM® Software Support.
Parent topic: IOGC messages


IOGC029E

The IMS Connect message is not formatted correctly.

Explanation

An internal error has occurred in IMS™ Connect.

User action

Contact IBM® Software Support.
Parent topic: IOGC messages


IOGC030E

The IMS Connect XML Adapter message is not formatted correctly.

Explanation

An internal error has occurred in IMS Connect.

User action

Contact IBM Software Support.
Parent topic: IOGC messages


IOGC031E

The XML converter driver reports an error. [error_message].

Explanation

The WebSphere Developer for zSeries converter driver program returns an error.

User action

Review the error message. For more diagnostic information on the error message, see the WebSphere Developer for zSeries documentation.
Parent topic: IOGC messages


IOGC034E

Socket Timeout has occurred for this interaction. The Socket Timeout value specified was [sockettimeout] milliseconds. [error_message]

Explanation

The time for IMS™ SOAP Gateway to receive a response from IMS Connect is greater than the time specified for the socket timeout.

The error_message explains the reason for the error. A common error is [SocketTimeoutException: Read timed out], which indicates that a timeout occurred when IMS SOAP Gateway was trying to read a message from IMS Connect from the TCP/IP socket.

User action

Review the error message. Ensure that the value of the socket timeout is sufficient for IMS SOAP Gateway to receive a response from IMS Connect. If it is not, increase the socket timeout value in the correlator properties for the Web service. If the value of the socket timeout given is sufficient, it is possible that network problems are causing delays. Contact your network administrator.
Parent topic: IOGC messages


IOGC035E

IMS Connect default timeout has occurred for this interaction.

Explanation

The IMS Connect timeout value that is specified in the IMS Connect configuration member has been expired. The IMS Connect timeout value has been used because the execution timeout property for this interaction was not specified in the correlator file or has been set to zero.

User action

If the IMS Connect TIMEOUT value is not what you expected, modify the timeout value in the IMS Connect configuration member. For more information abut changing the timeout value for IMS Connect, see IMS Version 9 IMS Connect Guide and Reference .

If you expect to use an execution timeout value instead of the IMS Connect timeout value, ensure that have a valid execution timeout specified in the correlator properties for the Web service.

Parent topic: IOGC messages


IOGC036E

Execution timeout has occurred for this interaction. The timeout value used was [exeuctiontimeout] milliseconds.

Explanation

The time it took for IMS™ Connect to send a message to IMS and receive the response was greater than the execution timeout value that was rounded to an appropriate execution timeout interval. IMS SOAP Gateway converts the value of the execution timeout property in the correlator file to a value that IMS Connect can use.

User action

If the rounded execution timeout value is not what you expected, see the following table of conversion rules and change the execution timeout value in the correlator file as appropriate.
Table 1. Execution timeout value conversion rules
Range of execution timeout values in the correlator file | Conversion rule
1 – 250 | If the value is not divisible by 10, it is converted to the next greater increment of 10.
251 – 1 000 | If the value is not divisible by 50, it is converted to the next greater increment of 50.
1 001 – 60 000 | If the value is not divisible by 1 000, it is converted to the next greater increment of 1 000. Values that are exactly between increments of 1 000 are converted to the next greater increment of 1 000.
60 001 – 3 600 000 | The value is converted to the nearest increment of 60 000. Values that are exactly between increments of 60 000 are converted to the next greater increment of 60 000.
Parent topic: IOGC messages


IOGC037E

The specified XML Converter Driver name cannot be empty or all blanks.

Explanation

The value of the driver name property cannot be empty or all blanks.

User action

Correct and specify the driver name property value in the correlator properties of the Web service. Ensure the value is not empty or all blanks.
Parent topic: IOGC messages


IOGC040E

IOGC040E: Bad output message.

Explanation

IMS SOAP Gateway is unable to process the output message.

This error can occur because the output message is encoded in a code page that is not supported by IMS SOAP Gateway. An output message is built in the following ways:
  • The output XML message is built and encoded by your IMS application. If the output message is built this way then this error occurrs when the IMS application uses an code page that is not supported by IMS SOAP Gateway to built the output XML message.
  • The output message is built and then transformed into XML format by the IMS Connect XML Adapter and the WebSphere Developer for zSeries converters. If the output message is built this way then the error occurs because the converter driver programs are created with a inbound and outbound code page value that is not supported by IMS SOAP Gateway.

User action

If the output XML message is built by your IMS application, correct your application and ensure that the output message is encoded in a code page value that is supported by IMS SOAP Gateway.

If the output XML message is built and transformed by the IMS Connect XML Adapter and the WebSphere Developer for zSeries converter driver program, correct the WebSphere Developer for zSeries converter driver program by regenerate the converter driver program with the code page values that is supported by IMS SOAP Gateway.

Parent topic: IOGC messages


IOGC041E

IMS Connect returns an error. Return code: [returncode]. Reason code: [reasoncode]. [error_message]

Explanation

IMS Connect returned an error. error_message provides a brief description of the reasoncode.

User response

Review the error message to determine the reason for the failure. Possible causes of the error include:
  • For Return code: [8]. Reason code:[40]. [Security violation. User ID [userid], Group ID[groupid]] , IMS Connect rejected the IMS transaction request because it failed the security check.
  • For Return code: [4]. Reason code:[72]. [IMS Datastore [datastore] not found] , the specified IMS datastore name cannot be found. Look at the IMS Connect configuration file and ensure that the IMS datastore name is specified and configured. Examine the IMS datastore name property value in the correlator properties of the Web service to ensure that it is specified and that it is valid.
  • For Return code: [4]. Reason code:[74]. IMS Datastore [datastore] in stop or close process, the IMS with the datastore name datastore is in stop and shut down process. Invoke the IMS transaction request again after IMS has been restarted.
  • For Return code: [8]. Reason code:[14]. Message not processed by an adapter., the message has not been processed by an adapter. Possible causes for this error include:
    • An invalid adapter type is specified. Ensure that IBM XML Adapter is specified in the adapter type property of the correlator file of the Web service.
    • The IBM XML COBOL adapter cannot be found. Ensure that XML Adapter has been configured correctly with IMS Connect.
    • The IBM XML Adapter or the COBOL XML converter driver has returns an error.
    • The IBM XML Adapter has return a zero length message after processing the XML message. This error can occur because the XML message cannot be processed by XML COBOL Converter Driver.
In addition, see the z/OS console for associated IMS Connect error messages. IMS Connect error messages begin with the characters " HWS." For more diagnostic information on the other return code and reason code values, and IMS Connect error messages, see the IMS Version 9: IMS Connect Guide and Reference.
Parent topic: IOGC messages


IOGC042E

The value [trancode] of the IMS Transaction code property exceeds 8 characters.

Explanation

The value of the transaction code property exceeds eight characters.

User action

Correct the length of the transaction code property value in the correlator properties of the Web service to be less than or equals to eight characters.
Parent topic: IOGC messages


IOGC051E

IMS Connect return an error. IMS Datastore is not available.

Explanation

This error message is returned from IMS Connect. The transaction failed because IMS Datastore is not available at this moment.

User action

Report the error to the IMS System Administrator to ensure the IMS Datastore you are using is in active status.
Parent topic: IOGC messages


IOGS messages

IOGS messages are returned from the SOAP server.

  • IOGS001E
    Invalid SOAP URN [urnname] in SOAP message.
  • IOGS023E
    The IMS Connect Port Number property value [value] is invalid.
  • IOGS024E
    The Socket Timeout property value [value] is invalid.
  • IOGS025E
    Error processing the output message from IMS. A null value was returned.
  • IOGS026E
    The Execution Timeout property value [value] is invalid.
  • IOGS027E
    Error processing output message. [error_message].
  • IOGS029E
    Connection bundle name [connbundle] not found in connbundle file.
  • IOGS030E
    Correlator file [correlator_filename] for SOAP URN [urn] cannot be found.
  • IOGS501E
    IMS SOAP Gateway could not find the Web Service to invoke. Target Web service is [service_name].
  • IOGS502E
    IMS SOAP Gateway cannot find the operation [operation_name].
  • IOGS503E
    The envelope namespace of the SOAP message is invalid: [namespace_name]
  • IOGS504E
    The envelope tag of the SOAP message is invalid: [tag_name]
  • IOGS505E
    The SOAP message does not contain a body element.
Parent topic: Messages for IMS SOAP Gateway


IOGS001E

Invalid SOAP URN [urnname] in SOAP message.

Explanation

The SOAP action URN in the client request does not match the SOAP action URNs of any of the deployed Web services. This could happen because the Web service has not been successfully deployed to the IMS™ SOAP Gateway. This could also happen if the correct WSDL file is not used for proxy code generation.

User action

The following actions can be taken to address the problem:
  1. Ensure that the Web Service has been successfully deployed to the IMS SOAP Gateway.
  2. Ensure that the correct WSDL file is used for proxy code generation. The SOAPAction element in the WSDL file must match the URN in the client request message and the name of the correlator file for the Web service.
Parent topic: IOGS messages


IOGS023E

The IMS Connect Port Number property value [value] is invalid.

Explanation

The value of the IMS Connect port number property is invalid. For example, the value is not an integer.

User response

Examine the IMS Connect port number property value in the connection bundle properties of the Web service and ensure that it is a valid integer value.
Parent topic: IOGS messages


IOGS024E

The Socket Timeout property value [value] is invalid.

Explanation

The value of the Socket Timeout property is invalid. For example, the value is not an integer.

User response

Examine the Socket Timeout property value in the correlator properties of the Web service and ensure that it is a valid integer value.
Parent topic: IOGS messages


IOGS025E

Error processing the output message from IMS. A null value was returned.

Explanation

IMS SOAP Gateway received an empty message from IMS™.

User response

Look at the IMS SOAP Gateway and IMS traces to determine the problem. Ensure that IMS returns an output message.
Parent topic: IOGS messages


IOGS026E

The Execution Timeout property value [value] is invalid.

Explanation

The value of the Execution Timeout property is invalid. For example, it is not an integer

User response

Examine the Execution Timeout property value in the correlator file of the Web service and ensure that it is a valid integer value.
Parent topic: IOGS messages


IOGS027E

Error processing output message. [error_message].

Explanation

An error occurred when processing the IMS™ output message. Possible reasons are as follows:
  • The output message that was returned from the IMS application is not a valid XML document.
  • The XML document that was returned from the IMS application does not match the schema definition of the output message that is defined in the WSDL document of the Web service.

User action

Examine the output message from the IMS application and verify the following:
  • Ensure that the output message is a valid XML document. For example, make sure that the output data is enclosed in the appropriate matching XML tags.
  • Ensure the output XML message is encoded with the code page supported by IMS SOAP Gateway.
  • Ensure that the output XML message matches the schema definition of the output message in the WSDL file. If it does not match, you can either correct the IMS application or correct the WSDL file. If you choose to correct the WSDL file, be sure to deploy the corrected WSDL file to IMS SOAP Gateway.
Parent topic: IOGS messages


IOGS029E

Connection bundle name [connbundle] not found in connbundle file.

Explanation

The value of the Connection Bundle name property specified in the correlator properties of the Web service is not found.

User response

Change the connection bundle name in the correlator properties for the Web Service to match one that is properly defined in the connection bundle properties for IMS SOAP Gateway.
Parent topic: IOGS messages


IOGS030E

Correlator file [correlator_filename] for SOAP URN [urn] cannot be found.

Explanation

The correlator file for the SOAP request is not found. Possible reasons are:
  • The correlator file has not been created successfully when the Web Service is deployed.
  • The correlator file has been removed from IMS SOAP Gateway.

User response

Recreate the correlator file for the Web Service using the IMS SOAP Gateway Deployment Utility.
Parent topic: IOGS messages


IOGS501E

IMS SOAP Gateway could not find the Web Service to invoke. Target Web service is [service_name].

Explanation

IMS SOAP Gateway could not find the Web service to invoke. The Web Service service_name is not deployed to IMS SOAP Gateway.

User response

Ensure the Web service service_name is deployed to IMS SOAP Gateway. Check the IMS SOAP Gateway server console to make sure that the Web service is deployed.

Also, verify that the client is sending the correct name of the Web service. The Web service name is the name attribute value of the port element in the WSDL file.

Parent topic: IOGS messages


IOGS502E

IMS SOAP Gateway cannot find the operation [operation_name].

Explanation

IMS SOAP Gateway could not find the operation operation_name for the Web service. Possible reasons are:
  • The Web service with the associated operation has not been successfully deployed to the IMS SOAP Gateway.
  • The client is not built correctly to invoke the Web service. For example, an incorrect WSDL file is used to build the client application.

User response

Ensure that the Web Service deployed to the IMS SOAP Gateway has the operation defined. This can be verified by looking at the WSDL file. Verify the client is sending the correct operation name.
Parent topic: IOGS messages


IOGS503E

The envelope namespace of the SOAP message is invalid: [namespace_name]

Explanation

The envelope namespace namespace_name of the SOAP message is not valid.

User response

Ensure that the client is sending a valid SOAP message to IMS™ SOAP Gateway.
Parent topic: IOGS messages


IOGS504E

The envelope tag of the SOAP message is invalid: [tag_name]

Explanation

The envelope tag name of the SOAP message is not valid.

User response

Ensure that the client is sending a valid SOAP message to IMS™ SOAP Gateway.
Parent topic: IOGS messages


IOGS505E

The SOAP message does not contain a body element.

Explanation

The body part is not found in the SOAP message.

User response

Ensure that the client is sending a valid SOAP message that contains the body element with the input data to IMS SOAP Gateway.
Parent topic: IOGS messages


IOGX messages

IOGX messages are returned from the XML parser.

  • IOGX002E
    Error encountered with the connection bundle properties [connbundle_file]: [error_message]
  • IOGX003E
    Error encountered with correlator properties [correlator_file]:[error message].
Parent topic: Messages for IMS SOAP Gateway


IOGX002E

Error encountered with the connection bundle properties [connbundle_file]: [error_message]

Explanation

The connection bundle file is invalid and it does not conform to its schema definition. Possible reason is the connection bundle file has been modified manually instead of using IMS SOAP Gateway deployment utility.

User action

Recreate the connection bundle file using IMS SOAP Gateway deployment utility. You have to first remove the invalid connection bundle file located in [connbundle_file]. . You may need to note down the property values in the invalid connection bundle file before you create the new one.

Alternatively, you may modify the connection bundle file to be compliant with the schema installation_directory\server\webapps\imssoap\xml\connbundle.xsd.

Parent topic: IOGX messages


IOGX003E

Error encountered with correlator properties [correlator_file]:[error message].

Explanation

The correlator file is invalid and it does not conform to its schema definition. Possible reason is the correlator file has been modified manually instead of using IMS SOAP Gateway deployment utility.

User action

Recreate the correlator file using IMS SOAP Gateway deployment utility. You have to first remove the invalid correlator file located in [correlator_file]. You may need to note down the property values in invalid correlator file before you create the new one.

Alternatively, you may modify the correlator file to be compliant with the file installation_directoryserver\webapps\imssoap\xml\correlator.xsd.

Parent topic: IOGX messages


Reference for the deployment utility

This section provides the following reference information:

  • Deployment Utility in Interactive Mode
    The IMS SOAP Gateway Deployment Utility in Interactive mode is an interactive user interface that walks you through each task you want to perform by prompting for input. It runs in the Windows DOS Command prompt.
  • Deployment Utility Expert Mode
    The IMS SOAP Gateway Deployment Utility in Expert mode allows you to perform tasks in one step by entering commands on the Windows command line with parameters.


Deployment Utility in Interactive Mode

The IMS SOAP Gateway Deployment Utility in Interactive mode is an interactive user interface that walks you through each task you want to perform by prompting for input. It runs in the Windows DOS Command prompt.

To invoke a task in interactive mode:
  1. Start the IMS SOAP Gateway Deployment Utility.
    • For Windows: Select Start > All Programs > IBM IMS SOAP Gateway Version 9.2 > Deployment Utility.
    • For AIX: Run iogdeploy.sh in the <installation_dir>/deploy directory.
    The IMS SOAP Gateway Deployment Utility menu is opens.
  2. From the IMS SOAP Gateway Deployment Utility menu, choose the desired task and press Enter.
  3. Follow the instructions for each step to complete the task. Type cancel on the command line at any time during a task and return to the IMS SOAP Gateway Deployment Utility menu.

The deployment utility has options to perform different tasks.

  • Task 1: Enable your IMS application as Web service from start to finish
    Task 1 of the deployment utility allows you to deploy and set up properties to make your IMS application accessible as a Web service.
  • Task 2: Start IMS SOAP Gateway
    This task starts the IMS SOAP Gateway server.
  • Task 3: Stop IMS SOAP Gateway
    This task stops the IMS SOAP Gateway server .
  • Task 4: Update IMS SOAP Gateway properties
    This task allows you to set or view IMS SOAP Gateway properties.
  • Task 5: Create, Update or View correlator properties for a Web service
    This task creates or updates the correlator file by specifying the transaction and runtime correlator properties.
  • Task 6: Create, Update, Delete or View the connection bundle for a Web service
    With Task 6 you can Create, Update, Delete and View a connection bundle. The connection bundle contains all of the connection properties of the Web service.
  • Task 7: Deploy the WSDL file
    This task deploys the WSDL file to IMS SOAP Gateway, which allows an IMS application to be accessible as a Web service.
  • Task 8: Generate Java client code
    This task generates client proxy code for a Java client application.
  • Task 9: Undeploy a Web service
    This task undeploys an application as a Web service. In addition, this task generates client proxy code for a Java client application.
  • Task 10: Exit the IMS SOAP Gateway Deployment Utility
    Use this task to exit the deployment utility.
Parent topic: Reference for the deployment utility
Related concepts
IMS SOAP Gateway Deployment Utility
Related tasks
Specifying the correlator properties for a Web service
Specifying the connection properties of the connection bundle
Setting up the connections and correlator file properties for Web services


Task 1: Enable your IMS application as Web service from start to finish

Task 1 of the deployment utility allows you to deploy and set up properties to make your IMS application accessible as a Web service.

Tasks 1 overview

  1. From the IMS SOAP Gateway Deployment Utility menu, type 1 and press Enter.
  2. The deployment utility prompts you through the following tasks:
    1. Specifying which WSDL file to use for the deployment.
    2. Specifying the connection and security information for the Web service to create a connection bundle.
    3. Specifying the correlator file name or create a new correlator file.
    4. Deploying the Web service to IMS SOAP Gateway.

To verify that the Web service was deployed successfully, open the IMS SOAP Gateway Administrative Console and ensure that the deployed Web service is listed.

After you deploy the Web service, the next step is to generate the client code.

Parent topic: Deployment Utility in Interactive Mode
Related tasks
Deploying a Web service with IMS SOAP Gateway


Task 2: Start IMS SOAP Gateway

This task starts the IMS SOAP Gateway server.

Tasks 2 overview

  1. From the IMS SOAP Gateway Deployment Utility menu, type 2 and press Enter.
  2. IMS SOAP Gateway server starts. An additional window opens titled IMS SOAP Gateway. This window has information about the startup of the server. If the server started successfully, the following informational message is displayed at the end of the output:
INFO : IMS SOAP Gateway server is now up and running.
Parent topic: Deployment Utility in Interactive Mode
Related tasks
Starting the IMS SOAP Gateway server


Task 3: Stop IMS SOAP Gateway

This task stops the IMS SOAP Gateway server .

Tasks 3 overview

  1. From the IMS SOAP Gateway Deployment Utility menu, type 3 and press Enter.
  2. The IMS SOAP Gateway server stops. For Windows only: In addition, the informational window titled IMS SOAP Gateway which opened when the IMS SOAP Gateway server was started, is closed
Parent topic: Deployment Utility in Interactive Mode
Related tasks
Stopping IMS SOAP Gateway server


Task 4: Update IMS SOAP Gateway properties

This task allows you to set or view IMS SOAP Gateway properties.

Task 4 overview

  1. From the IMS SOAP Gateway Deployment Utility menu, type 4 and press Enter.
  2. You can modify and view the IMS SOAP Gateway properties:
  3. The IMS SOAP Gateway needs to be restarted after changing the properties for them to take effect.

Properties

Use the following parameters to modify the IMS SOAP Gateway properties.
IMS SOAP Gateway port number (non-HTTPs)
Specify the port number for the IMS SOAP Gateway server. IMS SOAP Gateway is configured to run and listen on the SOAP request over the HTTP communication protocol using port 8080 by default. The port number must be a non-negative number.
Trace level
Specify the trace level. The trace level controls the amount of logging and tracing with IMS SOAP Gateway. The trace level can be one of the following values:
Table 1. Trace level values
Trace level value | Trace level | Description
1 | Fatal | Only errors and exceptions are logged. This is the default level.
2 | Error | If the value is not divisible by 10, it is converted to the next greater increment of 10.
3 | Warn | Errors and exceptions plus warning messages are logged.
4 | Information | Errors and exceptions, information of important events are logged.
5 | Debug | Errors and exceptions, the entry and exit of important events and functions, and the contents of buffers sent to and received from IMS Connect and IMS SOAP Gateway are logged.
Log file
Specify the location and the filename for the log file. The log file name of the file which contains the logging and tracing messages. The default is /server/logs/imssoap.log
HTTPs port number
Specify the HTTPs port number. The default HTTPs port number is 8443. This must be a non-negative number. This property must be set in order to enable the HTTPs ports.
HTTPs keystore name
Specify the keystore name with the fully qualified path for use with the HTTPs connection. This can be the same as the SSL keystore as long as it has all the required key information.
HTTPs keystore pasword
Specify the HTTPs keystore password. This must be between 6 and 20 characters in length.
Parent topic: Deployment Utility in Interactive Mode
Related tasks
Tracing
Changing the log file
Changing port number for IMS SOAP Gateway server
Starting the IMS SOAP Gateway Administrative Console


Task 5: Create, Update or View correlator properties for a Web service

This task creates or updates the correlator file by specifying the transaction and runtime correlator properties.

Task 5 overview

  1. From the IMS SOAP Gateway Deployment Utility menu, type 5 and press Enter.
  2. Enter c to create a new correlator file, u to update an existing file and v to view the correlator.

    If you create or update a new correlator file, you must provide the WSDL file name of the Web service for which you create the correlator file. You can update multiple properties after choosing the Update option. Press Enter to save all your updates or type cancel to exit the update mode without committing the changes.

  3. Create, Update or View the correlator properties.

Properties

Connection bundle name
Specifies a connection bundle name. The name must be less than or equal to 20 characters. Ensure that the connection bundle exists before accessing the web Service. Required.
Socket timeout
Specifies the socket timeout in milliseconds. The timeout value for IMS SOAP Gateway to receive a response from IMS Connect before disconnecting the socket and returning an error. The value must be greater than or equal to zero. Optional.
Execution timeout

Specifies the execution timeout in milliseconds. The timeout value for IMS Connect to send a message to IMS and receive the response. The value must be between -1 and 3 600 000, inclusively. That is, the execution Timeout value must be greater than zero and less than or equal to one hour. The execution timeout value can also be -1 if you want an interaction to run without a time limit. The execution timeout value cannot contain non-numeric characters.

If you do not specify an execution timeout value or if the value that you specify is invalid, the timeout value in the IMS Connect configuration member is used and the interaction continues to run. If a valid execution timeout value is set, this value is converted into a value that IMS Connect can use. The following table describes how the values you specify are converted to the values that IMS Connect uses:
Table 1. Execution timeout value conversion rules
Range of execution timeout values in the correlator file | Conversion rule
1 – 250 | If the value is not divisible by 10, it is converted to the next greater increment of 10.
251 – 1 000 | If the value is not divisible by 50, it is converted to the next greater increment of 50.
1 001 – 60 000 | If the value is not divisible by 1 000, it is converted to the next greater increment of 1 000. Values that are exactly between increments of 1 000 are converted to the next greater increment of 1 000.
60 001 – 3 600 000 | The value is converted to the nearest increment of 60 000. Values that are exactly between increments of 60 000 are converted to the next greater increment of 60 000.

The default is zero. Optional.

Lterm name
Specifies the name used to override the value in the LTERM field of the IMS application program's I/O PCB. The name must be eight characters or less. Optional.
trancode
Specifies the IMS transaction code of the IMS application that is invoked by the Web service. If you use the XML Adapter function, leave it blank. Otherwise, you must specify a transaction code value. The transaction code value must be eight characters or less. If the transaction code is less than eight characters, IMS SOAP Gateway adds blanks to the end of the transaction code value. If you want to add trailing spaces to the transaction code value, enclosed the value with double quotes (for example, "MYTRCD" ). IMS SOAP Gateway removes the quotes at runtime. If you do not specify a transaction code, no transaction code will be added by IMS SOAP Gateway to the input message before it sends the message to IMS.
Program Name
Specifies the XML Converter Driver program name generated by WebSphere Developer for zSeries. This parameter value is required if you are using the XML Adapter function. If you do not use the XML Adapter function, leave this value blank.
Adapter Type
Specifies the XML Adapter type. This parameter value is required if you are using the XML Adapter function. Currently, the supported value is "IBM XML Adapter". If you do not use the XML Adapter function, leave this value blank.
Parent topic: Deployment Utility in Interactive Mode
Related tasks
Specifying the correlator properties for a Web service
Setting up the connections and correlator file properties for Web services
Specifying the connection properties of the connection bundle
Changing deployed Web services


Task 6: Create, Update, Delete or View the connection bundle for a Web service

With Task 6 you can Create, Update, Delete and View a connection bundle. The connection bundle contains all of the connection properties of the Web service.

Task 6 overview

  1. From the IMS SOAP Gateway Deployment Utility menu, type 6 and press Enter.
  2. Enter c to create a new connection bundle,u to update an existing one, v to view the connection bundle or d to delete an existing connection bundle.
  3. Enter the name of the connection bundle that you want to create, updated, view or deleted. If you create a new connection bundle file, this name must be twenty characters or less and contain no spaces. If you update an existing connection bundle, you need to provide the existing connection bundle name. You can update multiple properties after choosing the update option. press Enter to save all your updates or type cancel to exit the update mode without committing the changes.
  4. You can create, update or delete the connection properties.

Properties

Host name
Specifies the name or IP address of the host system where IMS Connect is running.
Port number
Specifies the port number of the host system where IMS Connect is running. The port number must be a nonnegative number. Default is 9999.
Datastore

Specifies the name of the target IMS datastore. The name must match the ID parameter of the Datastore statement that is specified in the IMS Connect configuration member. This name also serves as the XCF member name for IMS during internal XCF communications between IMS Connect and IMS OTMA. The name must be eight characters or less.

User ID
The default security authorization facility (SAF) user name that will be used for connections with IMS. The user ID must be eight characters or less.
Password
Specifies the password that will be used for connections with IMS. The password must be eight characters or less.
Groupname
Specifies the name of the group that will be used for connections with IMS. The name must be eight characters or less.
Keystore name

Specifies the fully-qualified path name of the Keystore in which client certificates or private keys are stored. A value for this parameter is mandatory if the server (IMS Connect) has been configured to require client authentication.

Private keys and their associated public key certificates are stored in password-protected databases called keystores. For convenience, trusted certificates can also be stored in the keystore and then the Truststore Name property can either be empty or could point to the keystore file. If the TrustStore Name and TrustStore Password property is left empty, an informational message is generated in the server log.

Keystore password
Specifies the password for the keystore. The password of the Keystore in which client certificates or private keys are stored. A value for this parameter is mandatory if a Keystore is specified.
Truestore name

The fully-qualified path name of the Truststore in which trusted certificates are stored. A value for this parameter is mandatory.

A truststore file is a key database file (keystore) intended to contain public keys or certificates.

Truststore password
The password of the Truststore in which trusted certificates are stored. A value for this parameter is mandatory.
Encryption type

Select the encryption type. A value of strong indicates that a strong cipher suite needs to be used. A value of weak indicates that a weak cipher suite needs to be used. A value of none indicates that authentication needs to be performed with no encryption of the messages exchanged. Strong and weak are related to the strength of the ciphers, that is, the key length. All those ciphers that can be used for export come under the weak category and the rest go into the strong category. The type of cipher suite varies depending on the JSSE provider and the version of the SSL package provided.

In the process of establishing the SSL session, during the handshake sequence, IMS SOAP Gateway selects the first cipher suite from the appropriate (strong or weak) list of cipher suites supported by the JSSE provider. IMS SOAP Gateway provides this cipher suite to the server (IMS Connect) so the server can determine if it supports the cipher suite chosen by the client. Subsequent cipher suites may be selected from the list as the client and server negotiate a cipher suite to be used for the session.

The following are examples of strong, weak and none cipher suites.

Strong cipher suites:
  • SSL_RSA_WITH_RC4_128_MD5
  • SSL_RSA_WITH_RC4_128_SHA
  • SSL_RSA_WITH_DES_CBC_SHA
  • SSL_RSA_WITH_3DES_EDE_CBC_SHA
  • SSL_DHE_RSA_WITH_DES_CBC_SHA
  • SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
  • SSL_DHE_DSS_WITH_RC4_128_SHA
  • SSL_DHE_DSS_WITH_DES_CBC_SHA
  • SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA
Weak cipher suites:
  • SSL_RSA_EXPORT1024_WITH_DES_CBC_SHA
  • SSL_RSA_EXPORT1024_WITH_RC4_56_SHA
  • SSL_RSA_EXPORT_WITH_RC4_40_MD5
  • SSL_RSA_EXPORT_WITH_DES40_CBC_SHA
  • SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5
  • SSL_DHE_DSS_EXPORT1024_WITH_RC4_56_SHA
  • SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA
  • SSL_DHE_DSS_EXPORT1024_WITH_DES_CBC_SHA
  • SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA
  • None cipher suites:
  • SSL_RSA_WITH_NULL_MD5 188 SSL_RSA_WITH_NULL_SHA
Parent topic: Deployment Utility in Interactive Mode
Related tasks
Specifying the correlator properties for a Web service
Setting up the connections and correlator file properties for Web services
Specifying the connection properties of the connection bundle
Changing deployed Web services


Task 7: Deploy the WSDL file

This task deploys the WSDL file to IMS SOAP Gateway, which allows an IMS application to be accessible as a Web service.

Task 7 overview

  1. From the IMS SOAP Gateway Deployment Utility menu, type 7 and press Enter.
  2. Specify the name of the WSDL file that you want to deploy. If the WSDL file is located in the IMS SOAP Gateway WSDL directory (installation_directory\server\webapps\imssoap\wsdl), simply specify the file name. If the WSDL is located in another location, you must specify the full path name of the file. If you have previously deployed or are redeploying the WSDL file, the file location is the IMS SOAP Gateway WSDL directory.
  3. Specify the correlator file to use. If the Correlator file is in the IMS SOAP Gateway XML directory (installation_directory\server\webapps\imssoap\xml), you only need to specify the file name. If the correlator file is anywhere else, you must specify the full path to the file as well. If you have previously deployed or are redeploying the WSDL file, the file is located in the IMS SOAP Gateway WSDL directory.
Parent topic: Deployment Utility in Interactive Mode
Related tasks
Changing deployed Web services


Task 8: Generate Java client code

This task generates client proxy code for a Java client application.

Task 8 overview

  1. From the IMS SOAP Gateway Deployment Utility menu, type 8 and press Enter.
  2. Specify which WSDL file to use. If the WSDL file is in the IMS SOAP Gateway WSDL directory (installation_directory\server\webapps\imssoap\wsdl), you only need to specify the file name. If the WSDL is located anywhere else, you must specify the full path to the file as well.
  3. Specifies the directory for the generated proxy code.
Parent topic: Deployment Utility in Interactive Mode
Related tasks
Generating the Java proxy code


Task 9: Undeploy a Web service

This task undeploys an application as a Web service. In addition, this task generates client proxy code for a Java client application.

Task 9 overview

  1. From the IMS SOAP Gateway Deployment Utility menu, type 9 and press Enter.
  2. Specify the name of the WSDL file associated with the Web service that you want to undeploy and press Enter.
The Web service is undeployed from IMS SOAP Gateway.
Parent topic: Deployment Utility in Interactive Mode
Related tasks
Undeploying a Web service


Task 10: Exit the IMS SOAP Gateway Deployment Utility

Use this task to exit the deployment utility.

Task 10 overview

From the IMS SOAP Gateway Deployment Utility menu, type 10 and press Enter. The IMS SOAP Gateway Deployment Utility exits. In addition, you can type exit on the command line for any task in the deployment utility to exit the tool.

Parent topic: Deployment Utility in Interactive Mode


Deployment Utility Expert Mode

The IMS SOAP Gateway Deployment Utility in Expert mode allows you to perform tasks in one step by entering commands on the Windows command line with parameters.

iogdeploy command

To use the deployment utility in Expert mode, enter the command iogdeploy (for AIX, type iogdeploy.sh) from the installation directory where the IMS SOAP Gateway is installed (<installation_dir>\deploy ). After you type the command, you can enter options depending on the task that you want to perform.

Example

c:\Program Files\IBM\IMS SOAP Gateway\deploy>iogdeploy -start
  • -start :Start an IMS SOAP Gateway server
    The -start command starts an IMS SOAP Gateway server.
  • -stop :Stop an IMS SOAP Gateway server
    The -stop command stops the IMS SOAP Gateway server.
  • -prop :Set IMS SOAP Gateway properties
    Use the -prop command to modify the IMS SOAP Gateway server properties.
  • -corr :Create or update the correlator file
    The -corr command creates or updates the correlator file by specifying transaction and runtime properties.
  • -conn :Create, update, or delete a connection bundle
    Use the -conn commad to create, update, or delete a connection bundle.
  • -deploy :Deploy the WSDL file
    The -deploy command deploys the WSDL file to IMS SOAP Gateway, which allows an IMS application to be enabled as a Web service.
  • -genclient :Generate Java client code
    Use the -genclient command to generate client proxy code for a client application.
  • -undeploy :Undeploy a Web service
    Use the -undeploy command to undeploy a Web service
Parent topic: Reference for the deployment utility
Related concepts
IMS SOAP Gateway Deployment Utility
Related tasks
Specifying the correlator properties for a Web service
Specifying the connection properties of the connection bundle
Setting up the connections and correlator file properties for Web services


-start :Start an IMS SOAP Gateway server

The -start command starts an IMS SOAP Gateway server.

Syntax

  Read syntax diagram   Skip visual syntax diagram
>>-iogdeploy-- -start------------------------------------------><

Parameters

-start
Specify the task to start the server

Example

iogdeploy -start
Parent topic: Deployment Utility Expert Mode
Related tasks
Starting the IMS SOAP Gateway server


-stop :Stop an IMS SOAP Gateway server

The -stop command stops the IMS SOAP Gateway server.

Syntax

  Read syntax diagram   Skip visual syntax diagram
>>-iogdeploy-- -stop-------------------------------------------><

Parameters

-stop
Specify the task to stop the server

Example

iogdeploy -stop
Parent topic: Deployment Utility Expert Mode
Related tasks
Stopping IMS SOAP Gateway server


-prop :Set IMS SOAP Gateway properties

Use the -prop command to modify the IMS SOAP Gateway server properties.

Syntax

  Read syntax diagram   Skip visual syntax diagram
>>-iogtool-- -prop-- -p--port_number-- -l--trace_level---------->

>-- -f--log_file-- -k--https keystore-- -w--keystore password--->

>-- -s--https port---------------------------------------------><

Parameters

Use the following parameters to modify the IMS SOAP Gateway properties.
-prop
Specify the task to change IMS SOAP Gateway server properties.
-p
Specify the port number for the IMS SOAP Gateway server. IMS SOAP Gateway is configured to run and listen on the SOAP request over the HTTP communication protocol using port 8080 by default. The port number must be a non-negative number.
-l
Specify the trace level. The trace level controls the amount of logging and tracing with IMS SOAP Gateway. The trace level can be one of the following values:
Table 1. Trace level values
Trace level value | Trace level | Description
1 | Fatal | Only errors and exceptions are logged. This is the default level.
2 | Error | If the value is not divisible by 10, it is converted to the next greater increment of 10.
3 | Warn | Errors and exceptions plus warning messages are logged.
4 | Information | Errors and exceptions, information of important events are logged.
5 | Debug | Errors and exceptions, the entry and exit of important events and functions, and the contents of buffers sent to and received from IMS Connect and IMS SOAP Gateway are logged.
-f
Specify the location and the filename for the log file. The log file name of the file which contains the logging and tracing messages. The default is /server/logs/imssoap.log.
-k
Specify the HTTPs address for the keystore.
-w
Specify the keystore password. This must be between 6 and 20 characters in length.
-s
Specify the HTTPs port number. The default HTTPs port number is 8443. This must be a non-negative number. This property must be set in order to enable the HTTPs ports.

Example

iogdeploy –prop –p 8081 –l 4 –f c:\log.txt -k c:\sg.ks -w changeit -s 8071
Parent topic: Deployment Utility Expert Mode
Related tasks
Tracing
Changing the log file
Changing port number for IMS SOAP Gateway server
Starting the IMS SOAP Gateway Administrative Console


-corr :Create or update the correlator file

The -corr command creates or updates the correlator file by specifying transaction and runtime properties.

Syntax

  Read syntax diagram   Skip visual syntax diagram
>>-iogdeploy-- -corr-------------------------------------------->

>--+- -c-- -w--wsdl_file-- -n--connection_bundle-+-------------->
   '- -u-- -r--correlator_name-------------------'

   .--------------------------------.
   V                                |
>----+----------------------------+-+--------------------------><
     +- -d--program_name----------+
     +- -a--adapter_type----------+
     |      .-0--------------.    |
     +- -s--+-socket_timeout-+----+
     |      .-0-----------------. |
     +- -e--+-execution_timeout-+-+
     +- -l--lterm_name------------+
     '- -t--trancode--------------'

Parameters

Use the following parameters to create an IMS correlator file which contains the correlation properties. When creating a correlator file, options -corr, -c, -w, and-n are required. When updating a correlator file, options -corr, -u, and -x are required. All other parameters are optional and can be listed in any order.
-corr
Specifies the correlator task
-c
Specifies that a correlator file is to be created. The correlator file name is the URN of the Web service. The URN is specified by the soapAction attribute of the soap:operation element in the WSDL file.
-w wsdl_file
Specifies which WSDL file to use. If the WSDL file is in the IMS SOAP Gateway WSDL directory (installation_directory\server\webapps\imssoap\wsdl), you only need to specify the file name. If the WSDL is anywhere else, you must specify the full path to the file as well.
-n connection_bundle
Specifies a connection bundle name. The name must be less than or equal to twenty characters. Ensure that the connection bundle exists before accessing the web Service. Required.
-u
Specified that a correlator file is to be updated.
-r correlator_name
Specifies the correlator name to be updated. The correlator name is the URN of the Web service. The URN is specified by the soapAction attribute of the soap:operation element in the WSDL file. If the correlator file is in the IMS™ SOAP Gateway XML directory (installation_directory\server\webapps\imssoap\xml), you only need to specify the file name. If the correlator file is anywhere else, you must specify the full path to the file as well.
-s socket_timeout
Specifies the socket timeout in milliseconds. The timeout value for IMS SOAP Gateway to receive a response from IMS Connect before disconnecting the socket and returning an error. The value must be greater than or equal to zero. Optional.
-e execution_timeout

Specifies the execution timeout in milliseconds. The timeout value for IMS Connect to send a message to IMS and receive the response. The value must be between -1 and 3 600 000, inclusively. That is, the executionTimeout value must be greater than zero and less than or equal to one hour. The execution timeout value can also be -1 if you want an interaction to run without a time limit. The execution timeout value cannot contain non-numeric characters.

If you do not specify an execution timeout value or if the value that you specify is invalid, the timeout value in the IMS Connect configuration member is used and the interaction continues to run. If a valid execution timeout value is set, this value is converted into a value that IMS Connect can use. The following table describes how the values you specify are converted to the values that IMS Connect uses:
Table 1. Execution timeout value conversion rules
Range of execution timeout values in the correlator file | Conversion rule
1 – 250 | If the value is not divisible by 10, it is converted to the next greater increment of 10.
251 – 1 000 | If the value is not divisible by 50, it is converted to the next greater increment of 50.
1 001 – 60 000 | If the value is not divisible by 1 000, it is converted to the next greater increment of 1 000. Values that are exactly between increments of 1 000 are converted to the next greater increment of 1 000.
60 001 – 3 600 000 | The value is converted to the nearest increment of 60 000. Values that are exactly between increments of 60 000 are converted to the next greater increment of 60 000.

The default is zero. Optional.

-l lterm_name
Specifies the name used to override the value in the LTERM field of the IMS application program's I/O PCB. The name must be eight characters or less. Optional.
-t trancode
Specifies the IMS transaction code of the IMS application that is invoked by the Web service. If you use the XML Adapter function, leave it blank. Otherwise, you must specify a transaction code value. The transaction code value must be eight characters or less. If the transaction code is less than eight characters, IMS SOAP Gateway adds blanks to the end of the transaction code value. If you want to add trailing spaces to the transaction code value, enclosed the value with double quotes (for example, "MYTRCD" ). IMS SOAP Gateway removes the quotes at runtime. If you do not specify a transaction code, no transaction code will be added by IMS SOAP Gateway to the input message before it sends the message to IMS.
-d program_name
Specifies the XML Converter Driver program name generated by WebSphere Developer for zSeries. This parameter value is required if you are using the XML Adapter function. If you do not use the XML Adapter function, leave this value blank.
-a adapter_type
Specifies the XML Adapter type. This parameter value is required if you are using the XML Adapter function. Currently the supported value is "IBM XML COBOL Adapter". If you do not use the XML Adapter function, leave this value blank.

Create example

This example creates a correlator file for MyWSDL.wsdl. This example specifies that the Web service is to use the connection bundle named bundle1, that the IMS transaction code is tran1, and that
iogdeploy -corr -c -w MyWSDL.wsdl -n bundle1 -t tran1 -d program1

Update example

iogdeploy -corr -u -r MyCorrelator.xml -s 1000 -d program2
Parent topic: Deployment Utility Expert Mode
Related tasks
Specifying the correlator properties for a Web service
Setting up the connections and correlator file properties for Web services
Specifying the connection properties of the connection bundle
Creating a correlator file
Changing deployed Web services


-conn :Create, update, or delete a connection bundle

Use the -conn commad to create, update, or delete a connection bundle.

Syntax

  Read syntax diagram   Skip visual syntax diagram
>>-iogdeploy-- -conn--+- -c-+-- -n--bundle_name----------------->
                      +- -u-+
                      '- -d-'

   .----------------------------.
   V                            |
>----+------------------------+-+------------------------------><
     +- -h--host_name---------+
     |      .-9999--------.   |
     +- -p--+-port_number-+---+
     +- -d--datastore---------+
     +- -u--user_ID-----------+
     +- -s--password----------+
     +- -g--group_name--------+
     +- -r--new_bundle_name---+
     +- -k--keystore name-----+
     +- -w--keystore password-+
     +- -t--trustore name-----+
     +- -o--trustore password-+
     '- -e--encryption types--'

Parameters

Use the following parameters to create or update a connection bundle. When creating a connection bundle, - conn, -c, and-n are required. When updating a connection bundle, - conn, -u, and -n are required. All other parameters are optional and can be listed in any order. When you are deleting a connection bundle, -conn, -d, and -n are required and no other parameters are valid.
-conn
Specifies the connection bundle option task.
-c
Specifies that you want to create a new connection bundle.
-u
Specifies that you want to update an existing connection bundle.
-d
Specifies that you want to delete an existing connection bundle.
-n bundle_name
Specifies the name of the connection bundle to create or update. The correlator file uses this name to specify which connection properties to use for its associated Web service. The name must be twenty characters or less and contain no spaces.
-h host_name
Specifies the name or IP address of the host system where IMS™ Connect is running.
-p port_number
Specifies the port number of the host system where IMS Connect is running. The port number must be a non-negative number. Default is 9999.
-d datastore
Specifies the name of the target IMS datastore. the name must match the ID parameter of the Datastore statement that is specified in the IMS Connect configuration member. This name also serves as the XCF member name for IMS during internal XCF communications between IMS Connect and IMS OTMA. The name must be eight characters or less.
-u user_ID
The default security authorization facility (SAF) user name that will be used for connections with IMS. The user ID must be eight characters or less.
-s password
Specifies the password that will be used for connections with IMS. The password must be eight characters or less.
-g group_name
Specifies the name of the group that will be used for connections with IMS. The name must be eight characters or less.
-r new_bundle_name
Specifies a new name for the connection bundle. The name must be twenty characters or less and contain no spaces.
-k keystore name
The fully-qualified path name of the Keystore in which client certificates or private keys are stored. A value for this parameter is mandatory if the server (IMS Connect) has been configured to require client authentication.
-w keystore password
The password of the Keystore in which client certificates or private keys are stored. A value for this parameter is mandatory if a Keystore is specified.
-t trustore name
The fully-qualified path name of the Truststore in which trusted certificates are stored. A value for this parameter is mandatory.
-o truststore password
The password of the Truststore in which trusted certificates are stored. A value for this parameter is mandatory.
-e encryption type

Select the encryption type. A value of strong indicates that a strong cipher suite needs to be used. A value of weak indicates that a weak cipher suite needs to be used. A value of none indicates that authentication needs to be performed with no encryption of the messages exchanged. Strong and weak are related to the strength of the ciphers, that is, the key length. All those ciphers that can be used for export come under the weak category and the rest go into the strong category. The type of cipher suite varies depending on the JSSE provider and the version of the SSL package provided.

In the process of establishing the SSL session, during the handshake sequence, IMS SOAP Gateway selects the first cipher suite from the appropriate (strong or weak) list of cipher suites supported by the JSSE provider. IMS SOAP Gateway provides this cipher suite to the server (IMS Connect) so the server can determine if it supports the cipher suite chosen by the client. Subsequent cipher suites may be selected from the list as the client and server negotiate a cipher suite to be used for the session.

Create example

This example creates a new connection bundle that is named MyBundle. It does not specify any properties.
iogdeploy -conn -c -n MyBundle

Update example

This example changes the name of the connection bundle from MyBundle to YourBundle. It also specifies a defaulr SAF user name of USER1.
iogdeploy -conn -u -n MyBundle -s USER1 -r YourBundle

Delete example

This example deletes the connection bundle that is named YourBundle.
iogdeploy -conn -d -n YourBundle
Parent topic: Deployment Utility Expert Mode
Related tasks
Specifying the correlator properties for a Web service
Setting up the connections and correlator file properties for Web services
Specifying the connection properties of the connection bundle
Creating a connection bundle
Changing deployed Web services


-deploy :Deploy the WSDL file

The -deploy command deploys the WSDL file to IMS SOAP Gateway, which allows an IMS application to be enabled as a Web service.

Syntax

  Read syntax diagram   Skip visual syntax diagram
>>-iogdeploy-- -deploy-- -w--wsdl_file-- -c--correlator_file---><

Parameters

Use the following parameters to deploy an application as a Web service. The -deploy command, -w, and -c are required.
-deploy
Specifies the deployment task option. Required.
-w wsdl_file
Specifies which WSDL file to use. If the WSDL file is in the IMS SOAP Gateway WSDL directory (installation_directory\server\webapps\imssoap\wsdl.), you only need to specify the file name. If the WSDL is anywhere else, you must specify the full path to the file as well.
-c correlator_file
Specifies the correlator file to use. If the Correlator file is in the IMS SOAP Gateway XML directory (installation_directory\server\webapps\imssoap\xml), you only need to specify the file name. If the correlator file is anywhere else, you must specify the full path to the file as well.

Example

This example deploys the file MyWSDL.wsdl, which is in installation_directory\server\webapps\imssoap\wsdl., and uses the correlator file MyCorrelator.xml.
iogdeploy -deploy -w MyWSDL.wsdl -c MyCorrelator.xml
Parent topic: Deployment Utility Expert Mode
Related tasks
Deploying the WSDL file
Changing deployed Web services


-genclient :Generate Java client code

Use the -genclient command to generate client proxy code for a client application.

Syntax

  Read syntax diagram   Skip visual syntax diagram
>>-iogdeploy-- -genclient-- -w--wsdl_file----------------------->

>-- -d--proxy_destination--------------------------------------><

Parameters

Use the following parameters to generate client proxy code for a client application. The -genclient command, -w, and -d are required.
-genclient
Specifies the proxy code task option.
-w wsdl_file
Specifies which WSDL file to use. If the WSDL file is in the IMS SOAP Gateway WSDL directory (installation_directory\server\webapps\imssoap\wsdl.), you only need to specify the file name. If the WSDL is anywhere else, you must specify the full path to the file as well.
-d proxy_destination
Specifies the directory for the generated proxy code.

Example

This example creates proxy code that is based on MyWSDL.wsdl, which is in installation_directory\server\webapps\imssoap\wsdl.. The generated code is stored in the directory c:\SOAP\proxy_code.
iogdeploy -genclient -w MyWSDL.wsdl -d c:\SOAP\proxy_code
Parent topic: Deployment Utility Expert Mode
Related tasks
Generating the Java proxy code


-undeploy :Undeploy a Web service

Use the -undeploy command to undeploy a Web service

Syntax

  Read syntax diagram   Skip visual syntax diagram
>>-iogdeploy-- -undeploy-- -w--wsdl_file-----------------------><

Parameters

Use the following parameters to undeploy a Web service. The -undeploy command and -w are required.
-undeploy
Specifies the undeployment task option
-w wsdl_file
Specifies which Web service to undeploy. If the corresponding WSDL file is in the IMS SOAP Gateway WSDL directory (installation_directory\server\webapps\imssoap\wsdl.), you only need to specify the file name. If the WSDL is anywhere else, you must specify the full path to the file as well.

Example

This example undeploys the MyWSDL.wsdl file from IMS™ SOAP Gateway.
iogdeploy -undeploy -w MyWSDL.wsdl
Parent topic: Deployment Utility Expert Mode
Related tasks
Undeploying a Web service


Notices

This information was developed for products and services offered in the U.S.A.

IBM® may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM® representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785 U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia Corporation
Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106-0032, Japan

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:

IBM Corporation
J46A/G4
555 Bailey Avenue
San Jose, CA 95141-1003 U.S.A.

Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.

The licensed program described in this information and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, or any equivalent agreement between us.

Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.

All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only.

This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs.

Each copy or any portion of these sample programs or any derivative work, must include a copyright notice as follows:

(your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs. Copyright IBM Corp. 2003, 2005. All rights reserved. Trademarks

Trademarks

IBM, IMS, WebSphere, and z/OS are trademarks of International Business Machines Corporation in the United States, other countries, or both.

Microsoft® and Windows® are trademarks of Microsoft Corporation in the United States, other countries, or both.

Java™ and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.


Creating a connection bundle

You must create a connection bundle by using the IMS SOAP Gateway Deployment Utility to specify the connection and security properties between IMS™ SOAP Gateway, IMS Connect, and IMS. You can create multiple connection bundles, but you can only use one connection bundle for each Web service.

To create a connection bundle:
  1. Start the deployment utility either in interactive mode or through the command line.
  2. Specify option 6.
  3. Specify the connection and security information for the Web service.
  4. Restart the IMS SOAP Gateway server.
After you create a connection bundle, you can create the correlator.
Related reference
-conn :Create, update, or delete a connection bundle


Creating a correlator file

Before you can deploy a Web service to IMS™ SOAP Gateway, you must first create a correlator by using the deployment utility. You do not need to edit the file directly. The utility creates and updates the file. The correlator specifies connection, transaction, and runtime properties.

Before you can create a correlator file, ensure that the connection bundle specified in the correlator file exists before accessing the Web service.
To create a correlator file:
  1. Start the deployment utility either in novice mode or through the command line.
  2. Specify option 5.
  3. Specify the connection, transaction, and runtime properties for the Web service.
After you have a correlator file, you can deploy the WSDL file.
Related reference
-corr :Create or update the correlator file