Getting started with integrated Web services server
The Create Web Services Server wizard provides a convenient way to externalize programs running on i5/OS, such as RPG or COBOL ILE programs, as Web services. The goal of the wizard is to create a recommended production level server configuration while requiring minimal information from the user.
This article provides start-up instructions for the creation of a Web services server and the deployment of a Web service written in the ILE RPG programming language.
To launch the Web services server wizard you need to sign on to the Web Administration GUI for i5/OS and click on the Create Web Services Server wizard link. Point your browser to the Web Admin GUI for i5/OS by specifying the following URL: http:// hostname:2001/HTTPAdmin, where hostname is the host name of your server, and sign on (you must have *ALLOBJ authority to create a Web services server). Then launch the Create Web Services Server wizard by either clicking on the link in the navigation bar under the Common Tasks and Wizards heading, or on the main page of the Setup tab (see Figure 1 below).
Figure 1. Links to Create Web Services Server
Here are the steps to create a Web services server.
The initial Web page shown by the wizard (Figure 2 below) requests a user ID to run the jobs associated with the server. You have the option of specifying an existing user ID, creating a new user ID, or using the default user ID. We will use the default user ID, QWSERVICE.
Note: Any user ID specified for the server must be enabled and the password set to a value other than *NONE. Ensure this is true for the specified user ID.
Click on the Next button at the bottom of the form.
Figure 2. Specify User ID for Server
You can deploy an existing i5/OS program object as a Web service during the creation of the integrated Web services server, or you can do simply create the server and deploy a program object as a Web service later. If you do not select the option to deploy a new service, you will go to Step 8. We will leave the option to deploy a new service selected, which is the default as shown by Figure 3. Click on the Next button at the bottom of the form.
Figure 3. Deploy an i5/OS Program as a Web service
We now need to specify (see Figure 4) an ILE program object name from which the Web service is generated. There are two ways to locate the program object on the system. The default way is to specify the program and library names by selecting the option Specify i5/OS library and ILE object name (Recommended). Another way is to search for the program object by browsing the IFS, which could take a while if a directory is specified that contains a lot of objects, such as /QSYS.LIB.
Figure 4. Specify location of i5/OS program object
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:
- Manually, using an editor.
- Using a development tool such as WebSphere Development Studio Client for iSeries.
- 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:
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.
Now we need to give the Web service a meaningful service name and description. By default, the service name and description is set to the name of the selected program object (see Figure 5 below). It would make sense to set the name of the Web service to �ConvertTemp�, but that name is already being used for the sample service that is deployed on all newly created integrated Web services servers. So let us set the name to �ConvertTemp2�. You can also change the description if you so choose.
Click on the Next button at bottom of form.
Figure 5. Specify name for service
The wizard will show a list of exported procedures as shown in Figure 6 below. For service programs (object type of *SRVPGM), there may be one or more procedures. For programs (object type of *PGM), there is only one procedure, which is the main entry point to the program. Expanding the procedure row shows the parameters for the procedure and various parameter attributes.
Figure 6. Select Export Procedures to Externalize as a Web Service
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.
We now need to specify the user ID that the service will run under. As shown in Figure 7 below, you can run the service under the server�s user ID or you can specify an existing user ID that the service will run under.
In order for the Web service to run correctly, the user ID status must be set to *ENABLED and the password must be set to a value other than *NONE. If a user ID is specified that is disabled or has a password of *NONE, a warning message is displayed and the service may not run correctly. In addition, ensure that the specified user ID has the proper authorities to any resources and objects that the program object needs, such as libraries, databases and files.
In this example, we will accept the default. Click on the Next button of the form.
Figure 7. Specify user ID for this service
Specify any libraries that the program object needs to function properly (see Figure 8). The wizard retrieves the libraries specified in the user part of the library list (the libraries specified by the QUSRLIBL system value) and the library where the program object that is to be deployed as a service resides. Click on the Next button of the form.
Figure 8. Specify library list
The wizard shows you a summary page (see Figure 9 below), giving you the chance to see the details relating to the Web services server before it actually kicks off the task of creating the Web services server and deploying the service.
The Server tab on the summary page gives you details about the Web services server and the associated HTTP server (anytime a Web services server is created a corresponding HTTP server is also created). Here you will find information about ports, the location of the Web services server instance, etc.
Figure 9. Summary – Servers tab
If you click on the Services tab, you will see information about the services being deployed (see Figure 10 below). Here you will find the sample services being deployed, in addition to the service that we deployed.
Figure 10. Summary – Services tab
Finally, if you click on the Operations tab, you will see the Web service operations that correspond to the procedure that was selected to be deployed as a Web service operation (see Figure 11 below).
Figure 11. Summary – Operations tab
Clicking on the Finish button at the bottom of the summary page will result in the panel shown in Figure 12 being displayed by the wizard:
Figure 12. Server creating
After the server is created, the wizard will deploy the service and then start the Web services server and HTTP server. So if all goes well, you will eventually see the server in Running state and the deployed services active (green dot to the left of service name) as in Figure 13 below:
Figure 13. Server running
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 Manage Deployed Services form (figure 14 below) is used to view the list of deployed services, start or stop a service, deploy a new Web service, modify the properties of an existing service, view the WSDL definition, uninstall a Web service, or verify the function of the service by running a Web service test tool.
Figure 14. Manage deployed services
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.
If no service is selected, the only options you will see are the Deploy and Refresh buttons. However, if you choose a service, such as ConvertTemp2, by selecting the radio button next to the Web service name, more options will be displayed (see Figure 15 below).
Figure 15. Manage deployed services – service selected
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 button will be disabled if the service has a status of Running.
- 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 i5/OS 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 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
| 
