Web Services & VSE: Fit Into a Modern Systems & Applications Infrastructure

by Rich Smrcina
June 1, 2005

** Read this article online at http://www.mainframezone.com/operating-systems/web-services-vse-fit-into-a-modern-systems-applications-infrastructure


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:

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:

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

This article had no comments at the time of this printout.