Rational Developer for System z, Version 7.6

Step 5.5: Test the service flow

In this step you will verify that a TCPIPService is defined, verify that a PIPELINE is defined, and run the service flow using the workbench's Web Services Explorer.

If you encounter problems testing the service flow see Step 5.6: Troubleshooting.

Verify that a TCPIPService is defined

To invoke the new service flow as the application program component of a Web service running on Web Services for CICS®, you must have a TCPIPService defined on your z/OS® system. The TCPIPService must be defined for the same port that you specified in the End Point URI input field in CatalogOrderGP.sfgen.

In this tutorial the value specified in the End Point URI input field was http://system.company.com:6182/user25/sampcapn (see Edit the generation properties file for CatalogOrder.seqflow). Therefore, the new service flow assumes that a TCPIPService is defined on port 6182 of the remote z/OS system.

See your CICS system administrator for information on the following issues:

Configure a CICS PIPELINE

To invoke the new service flow as the application program component of a Web service running on Web Services for CICS, you must also have a CICS PIPELINE defined on the remote z/OS system.

The pipeline must have as its working directory the UNIX® System Services directory onto which you copied your Web service BIND file. This information is specified in the WSBind file input field on the second page of the Generate Runtime Code wizard.

In this tutorial the value specified for the WSBind file is /u/cicsts32/webservices/wsbind/cicssfrp (see Run the Generate Runtime Code wizard for CatalogOrderGP.sfgen).

This tutorial uses the pipeline CICSSFRP in the CICS group PIPELINE. Figure 1 shows the characteristics of this pipeline. Notice that the working directory (Wsdir) is /u/cicsts32/webservices/wsbind/cicssfrp.
Figure 1. Object characteristics
Object characteristics of the pipeline CICSSFRP

See your CICS administrator for information on how to set up a PIPELINE (see Required environment, materials, and assistance). One PIPELINE can be used by multiple programs, so you may be able to use an existing PIPELINE.

Install your programs into their PIPELINE group

Once the PIPELINE is defined you must install your programs into the group to which they belong. "Installing" means that the PIPELINE searches for programs belonging to a specified group and adds such programs to its list of files that belong to the group.

Important: In this tutorial the Generate Runtime Code wizard automatically installs the CICS resources, because you selected the check box Install the Program, Transaction, and ProcessType resources on the third page of the wizard.

If you do not select the check box Install the Program, Transaction, and ProcessType resources, then the group definition is specified in the resource definition JCL file #SAMPCAR.JCL (see JCL files). When the JCL is submitted, CICS generates the resources and specifies that they belong in group PIPELINE. Then when you install the programs into the CICS group PIPELINE, CICS searches for programs belonging to the group and adds them to the group.

To install your programs into a group, type the following command at the CICS command prompt and press Enter:
   ceda install group(your_group_name)
For example
   ceda install group(pipeline)

Make the PIPELINE aware of your WSBind file

Even though you have copied your Web services BIND file (in this tutorial sampcapn.wsbind) to the PIPELINE's working directory (in this tutorial /u/cicsts32/webservices/wsbind/cicssfrp) nevertheless the PIPELINE has not been told that the new Web service BIND file exists.

Important: In this tutorial the Generate Runtime Code wizard automatically makes the pipeline aware of the WSBind file, because you selected the check box Request Pipeline Scan(s) on the third page of the wizard.

If you do not select this check box, then to make the PIPELINE aware of the new WSBind file you must have the PIPELINE do a scan of its working directory to detect any new WSBind files.

To do this type the following command at the CICS command prompt and press Enter:
   cemt perform pipeline(your_pipeline_name) scan
For example
   cemt perform pipeline (cicssfrp) scan

Run the Web service

In this section you will run the Web service in the Web Services Explorer. To run the Web service you will use the information contained in the local copy of the WSDL file (sampcapn.wsdl) that was created when you generated the runtime code for the CatalogOrder flow.

To run the Web service:

Attention: You will see that some of the actions in step 3 and in step 4 can be different, depending on the value that you set for the check box Expose All CICS SFR Headers in Interface (ADVANCED) in the generation properties editor (the default value is cleared -- see Edit the generation properties file for CatalogOrder.seqflow).
  1. In the Remote Systems view, verify that your connection with the remote z/OS system is active (see Set up a connection to z/OS in the Remote Systems view).

  2. Start the Web Services Explorer:

    1. In the EST Project Explorer, right-click CatalogSample > Generation > CICS SFR L2.0 > CatalogOrder sampcapn.wsdl.

    2. Click Web Services > Test with Web Services Explorer. The Web Services Explorer opens.

  3. In the Navigator view of the Web Services Explorer:

    1. In the WSDL Main tree, find the file entry for sampcapn.wsdl, for example:

      file:/D:/Tutorial/CatalogSample/deployment/CICS SFR L2.0/CatalogOrder/sampcapn.wsdl

    2. Under the file entry, expand the tree and click the node for the operation.

      The names of the node for the WSDL service details, the node for the WSDL binding details, and the node for the WSDL operation can be different, depending on the value that you set for the check box Expose All CICS SFR Headers in Interface (ADVANCED) in the generation properties editor (see Attention):

      • If you cleared the check box (default setting) then click DFHMADPLService > DFHMADPLHTTPSoapBinding > DFHMADPLOperation.

      • If you selected the check box then click sampcapnService > sampcapnBinding > sampcapnOperation.

      The Actions view should now display the page Invoke a WSDL Operation.

  4. In the Actions view of the Web Services Explorer, you now need to specify values for two sets of input fields in the service input header, including:
    • Values for the request message header.
    • Values for the input data container.

    1. Specifying values for the request message header:

      Tip: The fields in the request message header are documented in the CICS Service Flow Runtime User's Guide (see Supported runtime environments for each project type).

      The names and the number of these input fields can be different, depending on the value that you set for the check box Expose All CICS SFR Headers in Interface (ADVANCED) in the generation properties editor (see Attention):

      • If you cleared the check box (this is the default setting):
        Note: Clearing the check box causes the Generate Runtime Code wizard to set all the data fields in the request message header to default values, except for the request name.
        1. Expand Body > DFHMADPLOperation > service_input_area > dfhmahr_requestv1.

        2. In the input field dfhmahr_requestname type SAMPCARN.
          Important: You must type SAMPCARN using uppercase!
          This is the request name of the service flow that you want to invoke and is the same string that you specified in the Request Name field of the generation properties editor (see Common generation properties).

      • If you selected the check box:

        Note: Selecting the check box in the generation properties editor causes the Generate Runtime Code wizard to reset all the data fields in the request message header.
        1. Expand Body > SERVICEINPUTAREA > dfhmah.

        2. Set the fields to the values shown in Table 1.
          Important: Table 1 does not list all of the input fields in dfhmah. If an input field is not listed in the table, then leave that input field blank.
          Table 1. Input fields in the data structure dfhmah
          Field name: Input value:
          dfhma_strucid MAH1
          dfhma_version 2
          dfhma_struclength 384
          dfhma_returncode 0
          dfhma_compcode 0
          dfhma_mode 0
          dfhma_suspstatus 0
          dfhma_abendcode 0
          dfhma_uowcontrol 0
          dfhma_processtype SAMPCARN1
          dfhma_requestname SAMPCARN1
          dfhma_datalength 7
          dfhma_linktype 1
          dfhma_more_data_ind 0
          dfhma_bridge_rc 0
          1You must type this input using uppercase!
          Note:

          Most of the values shown in this table are the same for any Web service that you have created.

          Three values in the table are specific to the Web service:
          • dfhma_processtype: Specify the same name that you specified in the Request name field of the Generation Properties editor. Here the request name is SAMPCARN
          • dfhma_requestname: Specify the same name that you specified in the Request name field of the Generation Properties editor. Here the request name is SAMPCARN.
          • dfhma_datalength: In a request to a Web server this field contains the total size (in terms of COBOL data representation) of the data area to be allocated for input parameters. (In contrast, in a response this field contains the size in terms of COBOL data representation of the data area for output parameters.)
            In this tutorial the total size of the input parameters is 7. This value is calculated by adding together the maximum possible data sizes of all the variables in the input message:
            • Maximum length of i_CatalogOrder.itemNumber: 4 digits
            • Maximum length of i_CatalogOrder.itemQuantity: 3 digits
            • Total length: 7
            To find the maximum possible size of an integer value or a short value:
            1. Open the message file (for example, i_CatalogOrder.mxsd) with the flow message editor.
            2. Click the Basic tab.
            3. In the left pane, select the variable (such as itemNumber).
            4. The maximum possible length of the variable is displayed in the right pane in the Total Digits field (4).
            To find the maximum possible size of a string:
            1. Open the message file (for example, o_CatalogOrder.mxsd) with the flow message editor.
            2. Click the Basic tab.
            3. In the left pane, select the variable (such as returnMessage).
            4. The maximum possible length of the variable is displayed in the right pane in the Maximum Length field.

    2. Specifying values for the input data container:

      1. In the Actions view, expand the input data container. The path of the input data container can be different, depending on the value that you set for the check box Expose All CICS SFR Headers in Interface (ADVANCED) in the generation properties editor (see Attention):

        • If you cleared the check box (default setting) then expand Body > DFHMADPLOperation > service_input_area > input_data_container > i_catalogorder.

        • If you selected the check box then expand Body > SERVICEINPUTAREA > input_data_container > i_catalogorder.

      2. In the itemnumber field type the item number that you want to test (for example 0010).

      3. In the itemquantity field type the number of items that you want to order (for example 25).

  5. To run the service flow, scroll to the end of the Actions view and click Go.

  6. Check the return information:

    1. In the Web Services Explorer, expand the Status view. The fields in this view can be different, depending on the value that you set for the check box Expose All CICS SFR Headers in Interface (ADVANCED) in the generation properties editor (see Attention):

      • If you cleared the check box (default setting) then expand DFHMADPLOperationResponse > service_output_area > navigator_output_area > o_catalogorder.

      • If you selected the check box then expand Body > SERVICEOUTPUTAREA > navigator_output_area > o_catalogorder.

    2. The results should be displayed in the returncode and returnmessage variables in o_catalogorder:
      Table 2. Results from running the Web service
      Scenario: returncode returnmessage
      If the item number was found and number of items requested are in stock: 0 ORDER SUCCESSFULLY PLACED
      If the number of items requested were not in stock: 97 INSUFFICIENT STOCK TO COMPLETE ORDER
      If the specified item was not in the catalog. 99 ITEM WAS NOT AVAILABLE IN CATALOG
If the request to the service flow is not successful:
  1. In the Status view click Source.
  2. Expand the SOAP Response Envelope.
  3. Find the return code in the element <faultstring> (for example, DFHMA08002E).

    The meanings of the return codes are documented in the CICS Service Flow Runtime User's Guide.


Terms of use | Feedback

This information center is powered by Eclipse technology. (http://www.eclipse.org)