Code reuse is a key concept I learned in college-level programming classes. The technique initially was used when coding subroutines in programs. It evolved to using the inter-program communications feature of a programming language to write separate programs that could be used from the main program. The result was the ability to build a set of tools that could be used by any future program written. This practice remains prevalent today, and programmers usually have an arsenal of callable programs that perform some function that’s integral to their systems.

Web Services Background

As client/server systems became vogue, inter-program communications evolved to inter-systems communications over a network. This evolution took various forms, including:

-        The Open Group’s Distributed Computing Environment (DCE) architecture - Remote Procedure Call (RPC), which Sun developed as part of its Open Network Computing (ONC) architecture

-        Microsoft’s Component Object Model (COM) and Distributed COM (DCOM), modeled after the RPC in DCE

-        The Object Management Group’s Common Object Request Broker Architecture (CORBA).

DCOM and CORBA are somewhat limited in that the same implementation of each protocol is typically needed to communicate between systems. For DCOM, this means Windows; for CORBA, each system requires the same ORB broker.

Web Services is an implementation of an overall concept called Service-Oriented Architecture (SOA). Since Web Services is based on open standards, it compensates for some of the weaknesses in DCOM and CORBA. An SOA can be implemented in many ways; for instance, both MQ Series and CICS Transaction Gateway can be considered an SOA. An SOA is more commonly thought of as being tied to Web Services. In turn, Web Services is usually thought of in terms of the implementation called Simple Object Access Protocol (SOAP). (A full description of SOAs, Web Services, and SOAP is beyond the scope of this article. For more information, see the resources listed at the end of this article.)

In Web Services, the “service” (a.k.a. provider) provides a specific function. The consumer uses the service and requests it from the provider. The provider implements the service for any consumer that wishes to use it. The service implementation is transparent to the consumer; the consumer doesn’t care how the provider implements the service. The consumer and provider can be running any operating system and can implement their respective roles in any programming language. These details aren’t known, nor are they divulged each to the other. Service implementation can be a simple mathematical calculation or a complex operation involving file or database operations or even invoking other Web Services. The communications between the provider and consumer is through HTTP-based request and response messages.

The interface used for Web Services and SOAP, in particular, are standard HTTP messages (SMTP is also supported), the same HTTP used to communicate with Websites. The messages are entirely composed of XML. Two additional standards used with Web Services are Web Services Description Language (WSDL) and Universal Description, Discovery and Integration (UDDI). WSDL is used to describe a Web Service, what parameters it requires, and that responses should be expected. UDDI is used to advertise a Web Service.

The VSE Implementation

The VSE/ESA e-Business Connectors provide the SOAP server, SOAP client (including the HTTP communications client) and XML parser (used to translate messages between CICS and the Web Service). Designed to be used under CICS Transaction Server for VSE/ ESA 1.1.1, it’s available with VSE/ESA 2.6 +APAR PQ78973, VSE/ESA 2.7, and z/VSE 3.1. Regardless of the release of VSE you’re running, you should check with the support center to determine if any additional service is required.

The VSE e-Business Connectors’ Website provides a wealth of information on how each of the connectors works. The SOAP connector is no different. Unfortunately, all the code examples are in C. That shouldn’t be too intimidating, but nonetheless, you like to see examples that match as closely as possible the situation you’re going to try to re-create.

All the VSE-based examples for this article are translated to COBOL. They’ve all been written and tested using a Flex-ES-based system from Fundamental Software.

Accessing a SOAP Service From VSE

When you say “accessing a SOAP service,” you mean that you’ll call a function on a remote system, pass it zero or more parameters, and wait for a response. This works just like an RPC, except that CICS thinks it performed an EXEC CICS LINK. It has no idea the remote system may be a WebSphere-based Web Service running on the other side of the world, or it could be another VSE system running on the same physical machine.

Knowledge of the XML that’s being passed between systems isn’t required. The CICS SOAP client code and XML parser handle all the XML translation for your program.

Chapter 25 of the VSE/ESA e-Business Connectors User’s Guide (SC33-6719-06) describes how the SOAP client and server work. Although the VSE Connector client isn’t required to use the VSE/ ESA SOAP Connector, there are SOAP examples provided with it. If the default directory structure is used to install the connector client, the examples are in /vsecon/samples/soap. Web pages with additional information on the SOAP Connector in that directory are also provided.

Communication between the CICS program and SOAP service is handled through the COMMAREA and temporary storage queues. The CICS program initially sets up the parameters that are being passed to the SOAP converter. Two temporary storage queues are used to:

-        Pass parameters to the SOAP service

-        Get response data from the SOAP service.

The queues can have any name, but it’s good practice to use names that won’t clash with other transactions that may also be using the SOAP service. That’s why the convention is to use the current task number with an “I” or “O” appended to it (to indicate an input or output queue).

Writing the Program

Let’s code a CICS program to call an available Web Service on the Internet. An example of the program can be downloaded at ftp://ftp.software.ibm. com/eserver/zseries/zos/vse/download/ xmps/soap_cobol_r.zip. Refer to it when reading the following section, as it will examine parts of the program.

XMethods (www.xmethods.com) has several public Web Services anyone can use. Our program will call a Web Service hosted by XMethods to display the current temperature for a zip code passed as a parameter.

The parameter(s) passed to the Web Service are placed into the data area called SOAP_PARAM_HDR.

The information to fill in the parameter data area is moved into it and written out to the temporary storage queue. Each parameter passed to the Web Service uses one temporary storage queue record (if there are three parameters, three records are written out). Here:

-        The NAME field is the parameter name.

-        TYPENAME is the description of the field type.

-        LENGTH is the length in bytes of the entire structure, including the actual parameter.

-        TYPE is a code that describes the parameter type.

-        PARAMETER contains the value being passed to the Web Service.

The PARAMETER field needs to be large enough to hold the largest parameter being passed to the Web Service; in this case, 260 bytes is quite large for a zip code. You’ll use the same data area to get the response from the Web Service, so you need to account for any error message that may be returned.

Figure 1 presents the code types. Let’s move the appropriate values into the data area:

MOVE 'zipcode' TO NAME.

MOVE 'string' TO TYPENAME.

MOVE 45 TO LENGTH.

MOVE 10 TO TYPE.

Since you have a single parameter, you could easily just include the values for the parameter in the field definitions as VALUE clauses. You next set up the fields to contain the queue names, as shown in the fields OUTQUEUE and INQUEUE. Then you move the task number into the input and output queue name areas:

MOVE EIBTASKN TO CICS-TASKNUM-O, CICS-TASKNUM-I.

The SOAP encoder/decoder reads the queue and the queue direction is relative to it. Even though it’s output from our program, it’s input to the encoder/decoder, so you write to the input queue. When you get the response from the encoder/decoder, you’ll read from the output queue. EXEC CICS WRITEQ TS is used to write out the SOAP parameters.

Next, you must set up the COMMAREA to call the SOAP encoderdecoder. Translated to COBOL, it’s the data area called SOAP-DEC-PARAM:

-        URL is the Internet location of the Web Service (just like the URL in a Web browser).

-        URN is the name of the program on the remote system to use.

-        METHOD is the name of the subroutine inside the program that’s to be executed.

-        INQUEUE and OUTQUEUE are the same fields defined earlier and are actually part of this data structure.

You’ll need to fill in several fields inside PROXY if your site standards require that you access Websites through a proxy server. Refer to the e-Business Connectors User’s Guide for more detail. If you’re not using a proxy server, set the PROXYTYPE field to zero.

Normally, you’d automatically get the information you need to access a Web Service from WSDL. At this time, VSE doesn’t handle WSDL, so you have to collect the information manually. Luckily, XMethods provides it for you. If you click on “Weather-Temperature” service under “Demo Services,” you get a page where people have contributed sample clients for various platforms. At the top of the page is a link called “View RPC Profile” (see Figure 2). This page shows the URL, method name, URN, parameter name and type, and the return data type. With this information, you can fill in the fields of your data area as follows:

MOVE 'http://64.124.140.30/soap/service/rpcrouter' TO URL.

MOVE 'getTemp' TO METHOD.

MOVE 'urn:xmethods-Temperature-Demo' TO URN.

When the parameters are all set up, you can call the SOAP encoder. It will pass control to the SOAP client processor, the XML parser, and finally the HTTP client, which will send the SOAP envelope to the Web Service (via a LINK to IESSOAPE). The response from the Web Service takes the path in reverse. When control returns to your program, you need to read the response from the temporary storage queue that you set up. EXEC CICS READQ TS is used to read the SOAP response(s). Because the Web Service might return an error, you set up SOAP-PARAM-HDR to be large enough to handle it. You have to add code to check the response for a SOAP fault and then display the message that’s returned. Finally, you must delete the temporary storage queues.

Unfortunately, the temperature service on xmethods.com currently returns a hard coded temperature. They are looking for another provider for this function. When this happens, it’s possible that some of the parameters will change; watch the Website for more information.

Running the Program

Now that all the coding is done, it can be compiled as any other CICS program, and no additional sub-libraries or linkage are required.

Due to the transactional nature of Web Services, it may not seem practical to use them from a batch program. If a Web Service is required from batch, there are several ways to go about it. SOAP support provides a batch HTTP client. (For details, see ftp://ftp.software.ibm.com/eserver/zseries/zos/vse/download/vsecon/HTTPClient.pdf.) The drawback is that an XML parser isn’t available for batch. The other way is to use EXCI to call a CICS program that invokes the Web Service.

Using CICS, you can create a transaction definition “TEMP” that points to the program “GETTEMP,” and install the definitions. To run the program, invoke the transaction with a zip code as the parameter (e.g., “TEMP 53118”). A screen will come back that looks like Figure 3.

To see what happens when an error occurs, let’s purposely modify the program to refer to the wrong method name. Change the statement that moves “getTemp” to “getTerp.” After the program is recompiled and copied, run it again. An error message will be displayed (see Figure 4). As you can see, the message “Method “getTerp” isn’t supported” was returned.

Conclusion

Web Services are increasingly accessible on the Internet and packaged software also contains Web Services features. For VSE to participate in this world, it’s important to understand the SOAP client feature of VSE/ESA. A follow-up article will fill in the rest of the picture by demonstrating how VSE/ESA can provide SOAP Services.

References

- SOA and Web Services: http://www-130.ibm.com/developerworks/webservices/

- New to SOA and Web Services: http://www128.ibm.com/developerworks/webservices/newto/

- SOA and Web Services whitepapers: http://www.systinet.com/resources/whitepapers

- SOAP tutorial: http://www.w3schools.com/soap/default.asp

- Web Services architect: http://www-106.ibm.com/developerworks/webservices/library/ws-arc1/

- What is Service-Oriented Architecture?: http://webservices.xml.com/pub/a/ws/2003/09/30/soa.html