Generating service interface files from the IMS application

Edit online

Use the Enterprise Service Tools to generate the artifacts that are needed to enable your existing IMS PL/I application or COBOL application to run as a Web service in the IMS Enterprise Suite SOAP Gateway runtime environment.

Before you begin

To generate the artifacts that are needed to enable an existing IMS PL/I application or COBOL application for the IMS Enterprise Suite SOAP Gateway environment, you must have a PL/I include file or a COBOL copybook that describes the format of the input and output messages for the IMS application.

About this task

Because artifacts generated by the Enterprise Service Tools wizard (the WSDL file, the correlator file, and either PL/I include file or the COBOL copybook file containing the Web service driver and the runtime XML conversion programs) must be transferred to a z/OS® system, you can use the z/OS Projects perspective and a local z/OS project in Developer for z/OS to assist with this task.

To generate Web services artifacts for the IMS Enterprise Suite SOAP Gateway runtime environment:
  1. To open the z/OS Projects perspective, click the Open Perspective Open Perspective toolbar button, and then double-click z/OS Projects.
  2. Create a local z/OS project:
    1. Right-click the z/OS Projects view and select New > Local z/OS Project. The New Local Project window opens.
    2. Type a name for the project.
    3. From the Property Group area, select one of these options:
      • Select a property group to associate with the project Select this option and then select a property group for the new project. You can sort the list by clicking the table headings. To reverse the sort order, click the table headings again.
      • Create a property group and associate it with the project. Click Finish to edit the property group. Select this option to create a property group for the project. Type a name for the group in the Name field.
      • Do not associate the project with a property group. Select this option to create the project without associating it with a property group.
    4. Click Finish. If you are creating a new property group, the property group editor opens.
  3. Verify that the Navigator view is open in the z/OS Projects perspective; a Navigator tab should be visible on the interface. If the Navigator view is not open, follow these steps to open the Navigator view:
    1. In the menu bar of the workbench, select Window > Show View > Other. The Show View wizard opens.
    2. In the Show View wizard, expand General, select Navigator, and click OK.
    The Navigator view opens.
  4. Import into your local project the file (either the PL/I include file or the COBOL copybook file), that contains the data structures which describe the input and output data structures of your IMS application. The imported file should also be visible in the Navigator view.
    The files that can be used to import into your local project are:
    • COBOL:.cbl, .cpy, .cob, and .ccp
    • PL/I: .pli, .inc, and .mac
  5. Start the Enterprise Service Tools Wizard Launchpad from the Navigator view:
    Note: The following steps are only for the Create New Service (bottom-up) wizard, see Contexts for starting the single-service wizards when you run the wizard outside the Enterprise Tools Perspective for additional information.
    1. In the Navigator view, right-click the imported source file (PL/I or COBOL) that contains the input and output data structures of the IMS application.
    2. Select Enable Enterprise Web Service.
    The Enterprise Service Tools Wizard Launchpad wizard opens.
  6. Launch the Create New Service Interface (bottom-up) wizard:
    1. In the Enterprise Service Tools Wizard Launchpad wizard, make these selections, and then click Start:
      • Runtime: IMS Enterprise Suite SOAP Gateway
      • Scenario: Create New Service Interface (bottom-up)
      • Conversion type: Compiled XML Conversion
      The Create New Service Interface (bottom-up) wizard opens.
  7. On the first page of the wizard (entitled Language structures):
    1. Click the button Change PL/I Preferences or Change COBOL Preferences. The Preferences window opens and displays the PL/I or COBOL preferences in the right pane.
    2. In the General tab of the PL/I or COBOL preferences page, expand the Platform list box, select z/OS, verify or change other entries that apply for your z/OS system and then click OK.
    3. In the Request Language Structure tab, select the high-level language structure (PL/I or COBOL) that is the input structure for your IMS application. By default, the first structure defined in the program source file is selected.
    4. In the Response Language Structure tab, select the high-level language structure (PL/I or COBOL) that is the input structure for your IMS application. By default, the first structure defined in the program source file is selected.
    5. Click Next.
  8. On the second page of the wizard (entitled Generation Options):
    1. In the XML Converters tab, make these selections:
      • Host code page: Select the code page that the host uses.
      • Request code page: 1208 Unicode, UTF-8
      • Response code page: 1208 Unicode, UTF-8
      Note: At this time the IMS Enterprise Suite SOAP Gateway runtime environment supports only UTF-8.
    2. In the Service Location (Endpoint URI) input field of the WSDL and XSD tab, change the host name and port name to the location of the IMS Enterprise Suite SOAP Gateway, verify or change other entries that apply for your z/OS system, and click Next.
      Note: This URI specifies the address of the Web service.
  9. On the third page of the wizard (entitled IMS Enterprise Suite SOAP Gateway Service Provider):
    1. In the IMS Correlator file tab, specify any correlator properties that need to be specified for your IMS Enterprise Suite SOAP Gateway environment. In particular, in the input field File container, specify the folder and subfolder in which you want the correlator file to be generated.
      Note: You can generate artifacts directly to the z/OS UNIX System Services file system (see Generating artifacts remotely).
    2. Click Next.
  10. On the fourth page of the wizard (titled File, data set, or member selection):
    1. In the XML Converters tab, specify these values:
      • Converter file container: The folder and subfolder in which you want the converter programs to be created.
      • Converter driver file name: The name of the file in which you want the converter programs to be generated.
      Note: Make sure that the checkbox Generate all to driver is selected. This causes all the generated Web service programs (driver, request converter, and response converter) to be placed in the same file. You can generate artifacts directly to MVS (see Generating artifacts remotely).
    2. In the WSDL and XSD tab, specify these settings:
      • WSDL file container: Specify the folder and subfolder in which you want the WSDL and XSD files to be generated.
      • WSDL file name: Select this checkbox and .type the name of the file in which you want the WSDL document to be created.
      • Request XSD file name: Clear this checkbox.
      • Response XSD file name: Clear this checkbox.
      Note: The XSD files are not required by IMS SOAP Access. However, as an option, you can select these two checkboxes to cause the two XSD files to be generated. You can generate artifacts directly to the z/OS UNIX System Services file system (see Generating artifacts remotely).
    3. Click Finish.
The following files are generated:
  • The WSDL file (.wsdl).
  • The correlator file (.xml).
  • The file containing the Web service driver and runtime XML conversion programs (.cbl).
  • The request and response XSD files (.xsd).

After you create the service interface files, the next step is to deploy the service interface files to the IMS Enterprise Suite SOAP Gateway using the IMS SOAP deployment tool (see Deploying the Web service files to the IMS Enterprise Suite SOAP Gateway).