One important part of CICS Web services support is a couple of programs collectively known as the "Web Services Assistant." The assistant (ideally) allows traditional CICS applications to provide or consume Web services with as few changes as possible without getting into the details of simple object access protocol (SOAP) or extensible markup language (XML) processing. Here we'll focus on one of the assistants: DFHLS2WS.
Language structures to Web service
DFHLS2WS provides an ideal way to expose a CICS application as a Web service. As you might have guessed, it takes in language structures (LS) and produces a bind and a Web services description language (WSDL) file. As discussed before, the WSDL describes the Web service to be exposed, including the expected input and output fields. CICS uses the bind file to map the incoming SOAP to the structures and transactions expected by the CICS application.
DFHLS2WS itself is a Java class. To invoke it IBM provides a JCL procedure for DFHLS2WS in SDFHINST and a sample job in the Web services guide.
The procedure itself is fairly simple. The first step uses IEBGENER to copy the utility's input parameters into a temporary hierarchical file system (HFS) directory. The second step invokes the UNIX system services (USS) batch shell (BPXBATCH) to run a script that executes DFHLS2WS. The last step copies DFHLS2WS' STDERR and STDOUT output to SYSOUT.
There are six override parameters provided for in the sample procedure. At the very least you will have to specify your CICS/TS (parameter USSDIR) and Java (JAVADIR) directories. You may have to change others depending on how your shop works. Also note that the BPXBATCH step EXEC card contains a very long parameter string that may exceed the 100 byte maximum once you get all the variables set correctly. If that happens, you'll have to do some more customization to get it all to fit.
Lastly, programmers who are comfortable with USS can run DFHLS2WS interacti...
To continue reading for free, register below or login
To read more you must become a member of SearchDataCenter.com
vely in the TSO OMVS shell. He or she will probably want to write some sort of script to minimize the length of the command line.
An example
For our purposes we will use the following input and output PL1 structures for the Hopelessly Contrived and Useless Example (HCUE):
If we want to expose HCUE as a web service we can run the above structures through DFHLS2WS with the JCL below.
Some of the interesting parameters are:
PDSLIB
The partitioned dataset (PDS) containing the language structures. USS needs the leading slashes to understand it is opening a normal MVS dataset.
REQMEM
The web service request language structure
RESPMEM
The web service response language structure
CONTID
The name of the container holding the language structures passed to and from the server program.
LANG
The language the structures are in. Additional choices are COBOL, C and C++
PGMNAME
The program that CICS Web service links to passing the request language structure.
WSBIND
The directory and name of the bind file
WSDL
The directory and name of the WSDL file
Not shown in the example are other parameters allowing you to define a transaction ID along with the mapping level DFHLS2WS should use for the output WSDL and bind files.
As mentioned above, the output from this is a bind and WSDL file. The WSDL is an XML file defining how to reach the web service along with the input and output parameters. Believe it or not, HCUE's relatively simple structures generated over 180 lines of WSDL. Ultimately this WSDL ends up in a Web service registry or used to generate interfaces for processes that want to consume the web service.
Just for grins, this is the XML describing the request structure:
I'm not exactly sure what all those tags mean, but you and I can probably guess. This is also an object lesson on why we should let development tools generate this stuff.
The hex bind file is unreadable by humans but provides CICS with information for mapping web service messages to language structures as referenced in the pipeline definition.
The WSDL and bind files are just the first step in enabling an existing application as a Web service. Next month I'll talk about the CICS resource definitions necessary for the clients to find it.
ABOUT THE AUTHOR: For 24 years, Robert Crawford has worked off and on as a CICS systems programmer. He is experienced in debugging and tuning applications and has written in COBOL, Assembler and C++ using VSAM, DLI and DB2.
