1. Generate the artifacts by using IBM Rational Developer for System z
IBM Rational Developer for System z is an application development tool that helps in the development of traditional mainframe applications. You can generate the Web service artifacts shown in Table 2 by using the Enterprise Service Tools (EST) wizard provided.
Table 2. Web service artifacts
|WSDL file||The WSDL file is the Web service interface for the IMS application. It
describes where the Web service is located and what the input and output
message format is when the IMS application is invoked.|
You can create a WSDL file by hand or by using an application development tool (such as IBM Rational Developer for System z) and then customize it to be used with IMS SOAP Gateway.
Based on the language structures from your application, the Enterprise Service Tools wizard needs to know which data structure is the input to invoke the application.
|XML converter driver file||IMS Connect has an XML adapter function that, based on this converter driver, transforms XML messages from the client into COBOL bytes for the IMS application and then from bytes back to XML for the response. This file needs to be deployed to IMS Connect.|
|Correlator file||This file contains information that enables the IMS SOAP Gateway to set IMS properties and call the IMS application.|
- Start Rational Developer for System z if not already started: Start > Programs > IBM Software Development Platform > IBM Rational Developer for System z > IBM Rational Developer for System z.
Be sure that you are using the right workspace. For this tutorial, it is the C:\Workspaces\RDZv7 directory.
Figure 4. Rational Developer for System z Workspace Launcher
- On the Welcome screen, click the Workbench icon (Figure 5).
Figure 5. Workbench icon on the Welcome screen
- Open the Enterprise Service Tools perspective (Figure 6): Window > Open Perspective > Other.
Figure 6. Opening the Enterprise Service Tools perspective
- When the Open Perspective window opens, select Enterprise Service Tools and then click OK (Figure 7).
Figure 7. The Open Perspective window for choosing a perspective
Next, you will see the EST Project Explorer tab (Figure 8).
Figure 8. The EST Project Explorer in Rational Developer for System z
- Right-click in the EST Project Explorer window (Figure 9), and select New > IMS SOAP Gateway Project.
Figure 9. Creating an IMS SOAP Gateway project
- When the New IMS SOAP Gateway Project wizard opens (Figure 10), enter a
project name (use
IMSPhoneBookfor this example), and then click Next.
Figure 10. Specifying a project name
Import the COBOL copybook.
- Click File System to import the COBOL copybook that describes the format of the input and output messages of your IMS application into the project that you created.
- Navigate to C:\IMS PhoneBook (Figure 11). This directory contains the PhoneBook COBOL copybook and other files that you will need later.
- Select the IMSPHBK.cpy file, and click Open.
Figure 11. Specifying the IMS application source file
- Make sure that the content of the "Source files to import" field is pointing to the correct file (Figure 12), and then click Finish.
Figure 12. Importing the copybook from the File System
A new project called IMSPhoneBook is now available in your EST Project Explorer.
- Right-click the COBOL copybook file, IMSPHBK.cpy, in the EST Project Explorer and then select Generate IMS SOAP Gateway Resources (Figure 13).
Figure 13. Generating IMS SOAP Gateway resources
The Enterprise Service Tools Wizard Launchpad for the IMS SOAP Gateway host runtime opens (Figure 14).
Figure 14. The Enterprise Service Tools Wizard Launchpad
To start, the Enterprise Service Tools wizard needs to gather the host runtime, development scenario, application mode, and XML conversion type.
These are the default selections. Ensure that the following options are selected:
- Host runtime: IMS SOAP Gateway
- Development scenario: Create New Service Interface (bottom-up)
- Application mode: Service Provider
- Conversion type: Compiled XML Conversion
- Click Start to open the dialog box for inbound and outbound data structures.
What you have done so far
You have created an IMS SOAP Gateway project in Rational Developer for System z by using the Enterprise Service Tools wizard. You imported the COBOL copybook for the IMS phonebook application, the type of project, the host runtime, the development scenario, the application mode, and the conversion type so that the wizard can proceed to gather specific data based on your selections so far.
Specify the input and output data structure.
Based on the phonebook COBOL copybook, the Enterprise Service Tools needs to gather the information that Table 3 shows
Table 3. Information the Enterprise Service Tools wizard gathers
|The inbound language structure in your application||Based on the language structures from your application, the Enterprise Service Tools wizard needs to know which data structure is the input to invoke the application.|
|The outbound language structure in your application||Based on the language structures from your application, the Enterprise Service Tools wizard needs to know which data structure is the output from the application.|
|The prefix for the converter name||The Enterprise Service Tools wizard generates the converters based on the prefix. The wizard lets users choose to generate either separate converter files for inbound and outbound messages or one driver for all converters. If users choose the former, the wizard appends a different character to the prefix to create different converter files. If users choose the latter, the wizard appends a D to the prefix.|
|Character encodings||This is the code page to use for encoding the inbound and outbound XML messages and the code page that is used by the z/OS host system.|
|Transaction code for your IMS application||The transaction code is required to run the IMS application.|
|Socket timeout and execution timeout values||The time that the IMS SOAP Gateway should wait for a response from IMS Connect and for IMS Connect to send a message to IMS and receive a response before a timeout.|
- In the Inbound Language Structure tab, select the COBOL data structure that corresponds to the input message of the IMS application. For this phonebook sample application, select INPUT-MSG as the input language data structure (see Figure 15).
Figure 15. Specifying the inbound language structure
- Click the Outbound Language Structure tab, and select the COBOL data structure that corresponds to the output message of the IMS application. For this phonebook sample application, select OUTPUT-MSG for the output message data structure.
Figure 16. Specifying the outbound language structure
- Click Next to display the Generation options page.
Set the IMS SOAP Gateway host name and port number.
- In the Generation options page, under the XML Converters tab (for this tutorial), ensure that the converter program prefix IMSPHBK is unchanged. You can leave other default options as they are (see Figure 17).
Figure 17. Specifying the converter generation options
You must use this IMSPHBK prefix for this tutorial so that you do not need to manually deploy the XML converters to IMS Connect. A converter driver with that name is already deployed for this tutorial.
- Select the WSDL and XSD tab.
- In the Service location field, change the hostname and port number to the location of IMS SOAP Gateway: http://localhost:8080/imssoap/services/IMSPHBKPort. This URL specifies the address of the Web service.
Figure 18. Specifying the Web service properties
- Click Next to continue.
Set the IMS transaction code and connection information.
- In the IMS SOAP Gateway Correlator file tab, enter the following values (shown
in Figure 19):
- Transaction code:
- Inbound connection bundle:
- Socket timeout:
- Transaction code:
- Use the default values for the other IMS Connect interaction properties and click Next.
Figure 19. Specifying IMS Connect interaction properties
- The inbound connection bundle name must match the name of the connection bundle that you will specify later in the IMS SOAP Gateway deployment utility.
- The socket timeout value should be larger than the execution timeout value. For this tutorial, 6000 is arbitrarily selected.
- Under the XML Converters tab (Figure 20), use the default value for the converter driver file name. The inbound and outbound converter file names are automatically filled in based on the converter driver file name.
For this tutorial, you must use the default converter file names to use the XML converters that are already set up for you in IMS Connect. This setting ensures that the demo system can function properly for everyone.
- Make sure that the "Generate all to driver" check box is checked.
- Click Finish.
Figure 20. Specifying XML converters options
The following files are generated in your Rational Developer for System z workspace (see Figure 21):
- IMSPHBK.wsdl: WSDL file
- IMSPHBK.xml: Correlator file
- IMSPHBKD.cbl: COBOL converters in one driver file
- IMSPHBKI.xsd: Inbound XSD file (not used by the IMS SOAP Gateway)
- IMSPHBKO.xsd: Outbound XSD file (not used by the IMS SOAP Gateway)
Figure 21. The generated files in the EST Project Explorer view
What you have done so far
You specified the input and output data structures in the phonebook COBOL copybook, XML conversion options, and IMS Connect interaction properties in the Enterprise Service Tools wizard. The wizard generated the WSDL file, the correlator file (an XML file), and an XML converter driver. These files are located in your Rational Developer for System z workspace.