Integrated Web Services for i

For each program object to be deployed there should be a corresponding Program Call Markup Language (PCML) document. PCML is based upon the Extensible Markup Language (XML), and is a tag syntax that is used to fully describe the input and output parameters of the program object.

The wizard determines whether the program object has any PCML data stored in the object. If no PCML data is found, the wizard shows a prompt in which you can specify a path to a PCML document that describes the program object. The PCML document is then validated and processed so that only information for exported functions or procedures is shown.

The PCML information can be generated three ways:

1. Manually, using an editor.
2. Using a development tool such as WebSphere Development Studio Client for iSeries.
3. Recompiling ILE modules so that the PCML information is stored as part of the module (*MODULE) object.

The generation of PCML information is done by using the Program Interface Information (PGMINFO) parameter on the CRTRPGMOD and CRTCBLMOD commands. Since it is done on a per-module basis, you need to combine the generated PCML documents into one document so that the resultant document has the following format (not all elements and attributes are shown):

 <pcml version="4.0">
   <program name="p1" ... >  ...   </program>
   <program name="p2" ... >  ...   </program>
 </pcml>

The recommended approach for users not experienced with PCML, or users who do not need to customize the PCML document, is to store the PCML as part of the module object as follows:

• For V6R1 and higher, one is able to use the PGMINFO parameter as follows:

  CRTRPGMOD PGMINFO(*PCML *MODULE)
  CRTCBLMOD PGMINFO(*PCML *MODULE)

• For V5R4 (after PTFs are applied), the following codes must be in the source member.

• For RPG

  H PGMINFO(*PCML:*MODULE)

• For COBOL

  PROCESS OPTIONS PGMINFO(PCML MODULE)

Refer to the IBM Information Center for more information on PCML syntax.

In our example, we will deploy the service program QIWSSAMPLE in library QSYSDIR. This service program is shipped as part of integrated Web services server support and contains one exported procedure, CONVERTTEMP, that is written in the ILE RPG programming language. The procedure converts the temperature from Fahrenheit to Celsius. The source for the procedure can be found in:

/QIBM/ProdData/OS/WebServices/V1/server/samples/ConvertTemp/CNVRTTMP.RPGLE

Fill in library name QSYSDIR and ILE Object name of QIWSSAMPLE and click on the Next button at bottom of form.

The parameter attributes are modifiable. In most cases you want to modify the parameter attributes to control what data is to be sent by Web service clients and what data is to be returned in the responses to the client requests.

The table contains the following information:

• The Select column specifies which procedures are to be externalized as a service operation. You should select only those procedures that are to be exposed as Web service operations. At least one procedure must be selected. A procedure may not be selectable, that is, disabled, if the procedure definition contains parameter types that are not supported. To retrieve the most current information on restrictions, refer to the document located at /QIBM/ProdData/OS/WebServices/V1/server/docs/readme.txt.
• The Procedure name/Parameter name column identifies the program object's procedures and the parameters for each procedure.
• The Usage column indicates which of the procedure's parameters is input, output, or both input/output. The designation affects what a Web service client needs to specify on a request to the Web service. Designating a parameter as input or input/output means that a Web service client has to pass data corresponding to the parameter and the data is passed to the program object. Designating a parameter as output or input/output means that after the program object is invoked, data corresponding to the parameter is returned as part of the response to the Web service client request.
• The Data type column indicates the type of the data.
• The Count column indicates that the parameter is an array. If the Count value is a number, then the number identifies the number of entries in the array. If the Count value references another parameter, which must be an integer type, then the referenced variable is used at runtime to determine the actual number of elements in the array. There are performance ramifications to consider regarding parameters that are arrays. If the Count value is a number, and the usage of the parameter is output or input/output, then all the array elements are returned in the response to a client request, even if the valid elements in the array is less than the maximum. To improve the performance of Web service requests, it is a good idea for output or input/output arrays to have the Count value reference another parameter that contains the actual number of elements in the array if you know that the number of elements in the array is not constant. For nested arrays, such as arrays within structures, the Count value cannot be set. In order to change the nested array's count value, a manually constructed PCML document needs to be provided. Refer to the IBM Information Center for more information on PCML syntax.

In this example, the TEMPIN parameter is an input parameter, and the TEMPOUT parameter is the output parameter. We change the Usage parameter attribute to output (see Figure 6 above). This means that a Web service client will need to only pass data corresponding to the TEMPIN parameter, and the response to the client request will be returned in the TEMPOUT parameter.

Click on the Next button at bottom of form.

Congratulations, you have now successfully created a Web services server and deployed your first ILE program object as a Web service. Let us now look at the deployed service in more detail. Click on the Managed Deployed Services link that is to the left of the list of service names.

The deployed services table contains the following information:

• The Service name column indicates the unique name that represents the Web service.
• The Status column indicates the general status of the applications.
  • The current status of a service can be updated by clicking Refresh.
  • A deployed service might have a status of Running or Stopped. This indicates that the service has been made available as a Web service on the Web services server. For a faulty service, the property information is read-only. A faulty service is a service that may not run correctly due to an incorrect installation or a missing object that is needed for the service to run correctly for example a missing library in the library list.
  • A service that is being deployed has a status of Installing.
    • If the service is installed successfully, the status is changed to Running. Until the installation has completed successfully, the service's properties cannot be modified.
  • A service that is uninstalling has a transitional status of Uninstalling.
    • If the uninstall process completes successfully, the service is removed from the deployed services list.
• The Startup type column indicates the initial start state for the Web service. When the startup type is set to Automatic, the service is automatically started when the Web services server is started. When the startup type is set to Manual, the service is not started when the Web services server is restarted. It needs to be started manually whenever the Web services server is restarted.
• The WSDL - service definition column provides a link to the Web Services Description Language (WSDL) file that describes the service. The contents of the WSDL file contain all the input details along with what is returned from a call to this service. This link (or the actual WSDL file) can then be forwarded to various development organizations to build Web services clients to interact with the business logic that is externalized by this Web service. These Web services clients can be written in many different languages including; RPG, C, C++, COBOL, Java, PHP, and .NET. The link to the WSDL file is available only when the server is running. If the external http server is running, the visit to the WSDL file is through the port of external http server instead of the internal Web container port.

The options are as follows:

• To deploy a new service, click on the Deploy button to launch the Deploy New Service wizard.
• Click on the Stop button to stop a running service. The button will not be shown if the service is not running.
• Click on the Start button to start a stopped service. The button will not be shown if the service is running.
• Click on the Properties button to view or modify properties for the service. In most cases the server must be restarted in order for any changed properties to take effect.
• Click on the Uninstall button to remove a service. The Uninstall button is enabled only if the Web services server is in a stopped state.
• Click on the Refresh button to refresh the status of all deployed services.
• Use the Test Service button to briefly test the service deployed on the server.
  • The IBM i Web services test client is a subset list of plug-ins from the eclipse.org development tool called the Web Services Explorer. Refer to http://www.eclipse.org (link resides outside of ibm.com) for more information on the Web Services Explorer.
  • By clicking the Test Service button, a new window in the WSDL view is opened with the Web service client artifacts. The administrator can then select the operation or procedure to invoke, specify input variables and click Go. The service client invokes the deployed service and returns the result to the status frame. For detailed information on the response, select the Source view within the status frame to see details, warnings and error messages