Enabling the catalog example for Web services using Developer for z/OS

Edit online

You can use Enterprise Service Tools to generate XML conversion artifacts that utilize the CICS® vendor interface to provide conversion services of request and response SOAP messages for the catalog manager COBOL application.

This section describes how to enable one of the functions of the base application as a Web service. This Web service, named inquireSingle, provides a Web service client with the ability to query individual items in the catalog.

Generating Web services artifacts for the inquireSingle Web service

Edit online

The copy book containing the combined interface definition for the catalog manager is located in the CICS samples dataset with member name DFH0XCP1. The inquireSingle Web service uses a subset of the interface definition which can be found in a separate copy book DFH0XCP4.

You can run the Create New Service Interface (bottom-up) wizard against either of these copy books, keeping in mind that if you choose to go with DFH0XCP1 you should make sure on the first page of the wizard (entitled Language structures) to select the redefinition CA-INQUIRE-SINGLE REDEFINES CA-REQUEST-SPECIFIC and all of its child elements.

Note: Filler items are not displayed.

One of the benefits of using Enterprise Service Tools is support for the REDEFINES modifier. You do not have to factor out your interface definition into separate copy books for each redefinition.

The Create New Service Interface (bottom-up) wizard expects that all imported COBOL language structures have a level 01 containing element declared. You must add the declaration 01 DFH0XCMN to the top of whichever copy book you decide to use. The name of the level 01 is important in this case so that the root element name used by the XML converters matches what is expected by the CICS Web client for the catalog application.

See Locating the CICS application source and copy books for how to access the copy books mentioned in the workspace.

After the source for the copy books is in the workspace, see Generating the Web services artifacts conversion artifacts for details on how to generate the XML converters, driver, and WSBind and WSDL files, using the following inputs to the Create New Service Interface (bottom-up) wizard.

Follow these steps to use the Create New Service Interface (bottom-up) wizard:

Verify that the Navigator view is open. 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.
Start the Enterprise Service Tools Wizard Launchpad:
1. In the Navigator view, right-click DFH0XCP1.cbl.
2. Select Enable Enterprise Web Service.
The Enterprise Service Tools Wizard Launchpad opens.
Launch the Create New Service Interface (bottom-up) wizard:
1. In the Enterprise Service Tools Wizard Launchpad, make these selections and click Start:
  - Runtime: Web Services for CICS
  - Scenario: Create New Service Interface (bottom-up)
  - Conversion type: Compiled XML Conversion
  The Create New Service Interface (bottom-up) wizard opens.
Enter the following values for each page of the wizard. If a value is not specified for a particular input field or list box selection, then use the default value already displayed for that field or list box.
1. On the Language structures page:
  - Request language structure: CA-INQUIRE-SINGLE
  - Response language structure: CA-INQUIRE-SINGLE
2. On the Generation Options XML Converters tab:
  - Service program name: DFH0XCMN
  - Request Codpage: Codepage of your CICS system
  - Host Codepage: Codepage of your CICS system
  - Response Codepage: Codepage of your CICS system
3. On the Generation Options WSDL and XSD tab Endpoint URI field, specify http://yourserver:yourport/exampleApp/inquireSingle.
4. On the Web Services for CICS Basic Options tab WSBind file name field, specify inquireSingle.
5. On the File, data set, or member selection XML Converters tab:
  - Converter driver file name: DFHXCP4D
  - Request Converter file name: DFHXCP4I
  - Response Converter file name: DFHXCP4O
6. On the File, data set, or member selection WSDL and XSD tab WSDL file name field, specify inquireSingle.

The Create New Service Interface (bottom-up) wizard generates the specified output.

Deploying and installing the inquireSingle Web service

Edit online

This topic describes how to deploy and install the inquireSingle Web service.

After generating the converters in Generating Web services artifacts for the inquireSingle Web service, refer to following sections to deploy and install the inquireSingle Web service:

To build the converters and deploy the load module to the host system, see Creating Web service artifacts for CICS.
To deploy the WSBind and WSDL files to the "EXPIPE01" PIPELINE WSDir (pickup directory), see Deploying the Web service artifacts to CICS.
To install the new Web service and check if it is in service, see Deploying the Web service artifacts to CICS.

You can now invoke the inquireSingle Web service from the web client.

Combined interface definition DFH0XCP1

Edit online

This topic contains a listing of the input and output interface definitions from the CICS samples dataset with the member name DFH0XCP1.




>>     01 DFH0XCMN.

     *    Catalogue COMMAREA structure
         03 CA-REQUEST-ID            PIC X(6).
           03 CA-RETURN-CODE           PIC 9(2).
           03 CA-RESPONSE-MESSAGE      PIC X(79).
           03 CA-REQUEST-SPECIFIC      PIC X(911).
      *    Fields used in Inquire Catalog
           03 CA-INQUIRE-REQUEST REDEFINES CA-REQUEST-SPECIFIC.
               05 CA-LIST-START-REF        PIC 9(4).
               05 CA-LAST-ITEM-REF         PIC 9(4).
               05 CA-ITEM-COUNT            PIC 9(3).
               05 CA-INQUIRY-RESPONSE-DATA PIC X(900).
               05 CA-CAT-ITEM  REDEFINES CA-INQUIRY-RESPONSE-DATA
                               OCCURS 15 TIMES.
                   07 CA-ITEM-REF          PIC 9(4).
                   07 CA-DESCRIPTION       PIC X(40).
                   07 CA-DEPARTMENT        PIC 9(3).
                   07 CA-COST              PIC X(6).
                   07 IN-STOCK             PIC 9(4).
                   07 ON-ORDER             PIC 9(3).
      *    Fields used in Inquire Single
           03 CA-INQUIRE-SINGLE REDEFINES CA-REQUEST-SPECIFIC.
               05 CA-ITEM-REF-REQ          PIC 9(4).
               05 FILLER                   PIC 9(4).
               05 FILLER                   PIC 9(3).
               05 CA-SINGLE-ITEM.
                   07 CA-SNGL-ITEM-REF     PIC 9(4).
                   07 CA-SNGL-DESCRIPTION  PIC X(40).
                   07 CA-SNGL-DEPARTMENT   PIC 9(3).
                   07 CA-SNGL-COST         PIC X(6).
                   07 IN-SNGL-STOCK        PIC 9(4).
                   07 ON-SNGL-ORDER        PIC 9(3).
               05 FILLER                   PIC X(840).
      *    Fields used in Place Order
           03 CA-ORDER-REQUEST REDEFINES CA-REQUEST-SPECIFIC.
               05 CA-USERID                PIC X(8).
               05 CA-CHARGE-DEPT           PIC X(8).
               05 CA-ITEM-REF-NUMBER       PIC 9(4).
               05 CA-QUANTITY-REQ          PIC 9(3).
               05 FILLER                   PIC X(888).