A previous article in z/Journal (June/ July 2005) discussed Web Services: what they are and how they fit into a modern systems and applications infrastructure. The article also introduced VSE implementation of Web Services, the VSE SOAP Connector, and demonstrated how a program running under CICS can access a SOAP service.

This article will fill in the rest of the picture by demonstrating how VSE/ESA can provide SOAP services. Any CICS program you can call with EXEC CICS LINK and pass a COMMAREA can become a SOAP service. A SOAP client written in any language or development framework that provides SOAP support can access a Web service on VSE. This includes Java, COBOL, WebSphere, C/ C++, PHP, Visual Basic, and the .NET framework.

Setting Up CICS

SOAP is based on HTTP. For VSE to provide Web Services, an HTTP service must be used, so you must configure a TCP/IP service in CICS. Figure 1 offers a definition we’ll use for demonstration purposes.

TCP/IP support is also required in CICS. You achieve that by specifying TCPIP=YES in the SIT. After the SIT is reassembled and the new definition added to the startup list, CICS can be recycled. When CICS comes back up, you issue “CEMT I TCPIPS” to verify that your new TCP/IP service definition is installed and open. The display should look like Figure 2.

Setting Up the SOAP Client

To see how the SOAP server on VSE works, you could use any SOAP client platform. We’ll write our demonstration application in Java running on Linux. It will access a CICS program running on a VSE system. To use Java as a SOAP client, there are a few prerequisite packages to install. If the VSE Connector client package is installed, the entire process is described in /vsecon/samples/ soap/instsoap.html. Similar steps should work on other platforms.

To get started, you’ll need to install a Java Development Kit (JDK). You can obtain the JDK from IBM at www.ibm.com/java. Click on “Downloads & products,” and scroll down to the IBM Developer Kits.

After Java is installed, install Apache SOAP, Sun Java Mail, and the Sun JavaBeans Activation Framework. Installation of these packages involves nothing more than unzipping the file that’s downloaded. Create a directory called “soap” and download the three packages into that directory. Expand the packages from the soap directory. At this point you should have three directories under the soap directory (the release numbers may be different): soap-2_3_1, jaf-1.0.2, and javamail-1.3.1.

All you really need from these packages is their primary jar files. In the soap-2_3_1/lib directory, find a file called soap.jar and copy it to your new soap directory (from the soap directory: cp soap-2_3_1/lib/soap.jar). Do the same for activation.jar in jaf-1.0.2 and mail.jar in javamail-1.3.1. When you complete this process, the soap directory should look similar to Figure 3.

Our SOAP Service

The demonstration application that runs on VSE is a program that looks up a state code in a VSAM file and returns the state name. This is simplistic, but it’s an easy way to show how the process works.

The CICS program is called LISTSTAD. It’s called with a 22-byte COMMAREA; the first two bytes are the state code, and the remainder is the state name that’s returned to the caller. A front-end program provides a screen to ask for the state code and display the returned state name. Figure 4 shows the screen with the state code entered and state name retrieved from the file by LISTSTAD.

This application is designed so the presentation logic (the 3270 screen display) is separated from the processing logic (the “business” side of the application). Given that separation, it’s simple to just replace the presentation layer. In this case, we physically separated the logic into different programs. Actually, it doesn’t need to be that drastic. It could be a logical separation where a parameter is passed to the program telling it to bypass any 3270-style presentation logic and just return a set of results.

The VSE implementation of SOAP is described well in Chapter 25 of the VSE/ESA e-Business Connectors User’s Guide (SC33-6719-06). There’s also information in the directory structure of the VSE Connector client in /vsecon/samples/soap. Additionally, Web pages that contain information about the SOAP Connector are provided with the VSE Connector client.

The COMMAREA passes a set of parameters that let a CICS program act as a SOAP service. These parameters contain the method name that’s to be executed and the transient data queue names used to pass the SOAP parameters. When a SOAP call occurs, the method is typically a subroutine name in the remote program that is to be executed. Two of the fields in the COMMAREA are the input and output queue names where SOAP parameters are stored. A CICS program will read the SOAP parameters from the input queue and write the results back on the output queue.

SOAP service support in VSE wouldn’t work well if it required modifying existing programs. Adding the items in the previous paragraph to an existing program may be difficult to justify. To get around this, you can use a wrapper program. It’s the program that’s actually called by the SOAP component of VSE when a SOAP request is received. The wrapper will read the SOAP parameters from the TS queue and reformat them into a COMMAREA. The method name that’s passed to the wrapper will be the name of your program to which the wrapper will use an EXEC CICS LINK command passing the COMMAREA. The results take the reverse path.

Your wrapper program is called SOAPWRAP. The wrapper was adapted to COBOL from an Assembler version. The wrapper is called by the SOAP server (IESSOAPD) and is passed a COMMAREA. The COMMAREA is shown in Figure 5.

The method name is the name of your CICS program that will be linked to by the wrapper. The inqueue and outqueue are where the SOAP parameters are stored. The filler is for a namespace URL, which you won’t need. There’s a return code field that’s returned to the SOAP server (which ultimately is returned to the caller).

The flow of the wrapper program is to read the parameters from the temporary storage queue indicated in INQUEUE. It then builds a COMMAREA for the program indicated in the method parameter. EXEC CICS LINK is then used to execute the program. When control returns, it builds and writes temporary storage records to pass the results back to the caller and then exits.

Your wrapper is specifically written to handle calling a CICS program (LISTSTAD) and could quite easily be adapted for other programs. Short of having WSDL support for VSE (which should make this somewhat automatic), something much more usable would be a generic wrapper that reads a VSAM file or a database to know what the input and output parameters are for whatever “method” is called. It would then build the appropriate COMMAREA, make the call, and write the results for the values returned.

The concepts used in writing the wrapper program are similar to those used when writing the SOAP client program. To use the wrapper, you need to define it to CICS as a regular COBOL program.

The Java Client Code

Your Java client program is called getstate.java. The program source can be put in our soap directory (where the other packages were installed earlier). You have to use the Java compiler to create a Java class from the code. First, you have to tell the Java compiler where the prerequisite code libraries are (the .jar files, short for Java Archive). You do this with the CLASSPATH environment variable. In Linux, issue the following command:

export CLASSPATH=.:soap.jar:mail.jar:

activation.jar

This is similar to using the LIBDEF command in VSE to point the system to a particular set of sub-libraries. The first path is a single period that stands for the current directory. The Java archive file names are then listed. Next, execute the Java compiler:

javac getstate.java

If you receive messages about packages that can’t be found and symbols that can’t be resolved, chances are the CLASSPATH is set up incorrectly.

The Java program first checks to see if it received the correct number of parameters. It requires two parameters. The first is the URL used to access the SOAP service (in this case on VSE), and the second is the two-character state code that’s looked up by the SOAP service on VSE (LISTSTAD). This way, the Java program can generically access any SOAP server that provides this service and uses similar parameters (test system, production system, etc). It would be easy to hardcode the URL inside the program.

The program then assigns the second parameter to the variable name, “statecode.” It checks the length of statecode; anything other than a length of 2 bytes causes an error and the program to terminate. Next, the call to the SOAP server on VSE is processed. The next statements set up the call to the wrapper:

call.setTargetObjectURI (“urn:iessoapd:

soapwrap”);

call.setMethodName (“liststad”);

Here, “iessoapd” is the name of the SOAP server on VSE; “soapwrap” is the name of the program being called (wrapper); and the method name (liststad) is the name of the program the wrapper will ultimately call. The vector item (much like an array) is used to store the parameter that’s being passed (even though there’s only one parameter). The parameter vector is passed in the setParams method:

Vector params = new Vector ();

params.addElement (new Parameter(“statecode”, String.class, statecode, null));

call.setParams (params);

Then, the call is actually made with the URL as a parameter:

Response resp = call.invoke (/* router URL

   */ url, /* actionURI */ “” );

When the call comes back, we check for a SOAP fault. If there’s a fault, we print out the system generated messages associated with the fault. If the call succeeds, we print the information that came back from the COMMAREA, which is in the SOAP response (see Figure 6).

Putting It All Together

Once the Java program is compiled on Linux and all the VSE pieces are in place, we can run the program. The command is:

java getstate http://192.168.200.3:1080/

cics/CWBA/IESSOAPS WI

The Java command starts the Java Virtual Machine (JVM). Here, “getstate” is the name of the Java class (an executable Java program) that was created by the Java compiler. The URL contains the IP address of the VSE machine (192.168.200.3) and the port number that the CICS listener is listening on (1080). The remainder of the URL is the path to the SOAP server on VSE. The next parameter is a two-character state code that’s passed to the method of the SOAP service named in the Java program (LISTSTAD). The SOAP service will look up the code “WI” in the file and the response looks like this:

Response: WIWisconsin

If an invalid state code is passed, the following is returned:

Response: 99STATE CODE NOT FOUND

The programs are written to pass the state code as is, which means that if it was entered in lowercase, it’s sent to VSE in lowercase. The program described here wasn’t modified to change it to uppercase before the file look up. A perfectly good state code will get a “not found” response if it’s in lowercase.

Conclusion