Use DFHLS2WS to expose CICS applications as a Web service
DFHLS2WS is one of the Web services assistants that allows traditional CICS applications to provide or consume Web services without significant changes and without getting into the details of SOAP or XML coding.
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 interactively 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):
/*-------------------------------------------------------------------*/00010001
/* */00020000
/* REQUEST STRUCTURE */00030002
/* */00040000
/*-------------------------------------------------------------------*/00050000
DCL 1 REQUEST_PARMS, 00060002
3 REQUEST_TYPE CHAR(1), 00061002
3 CUST_NAME CHAR(20), 00070001
3 CUST_NUMBER FIXED BIN(31), 00080001
3 INVOICE_NUMBER FIX DEC(5), 00090001 /*-------------------------------------------------------------------*/00010000
/* */00020000
/* RESPONSE STRUCTURE */00030000
/* */00040000
/*-------------------------------------------------------------------*/00050000
DCL 1 INPUT_PARMS, 00060000
3 CUST_NAME CHAR(20), 00070000
3 CUST_NUMBER FIXED BIN(31), 00080000
3 INVOICE_PRICE FIX DEC(5), 00090001
3 INVOICE_DATE FIX DEC(7), 00091001
3 RETURN_CODE FIXED BIN(31); 00100000
If we want to expose HCUE as a web service we can run the above structures through DFHLS2WS with the JCL below.
//DFHLS2WS JOB (2433),'LS to WSDL',MSGCLASS=J,CLASS=X
//*
//* Convert a PL/1 language structure to WSDL
//*
//DFHLS2WS EXEC DFHLS2WS
//INPUT.SYSUT1 DD *
PDSLIB=//HCUE.SOURCE
REQMEM=PLIREQ
RESPMEM=PLIRESP
CONTID=PLICONT
LANG=PLI-ENTERPRISE
PGMINT=CHANNEL
PGMNAME=HCUEMAIN
WSBIND=/u/HCUE/pliBindfile.bind
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:
<xsd:element name="request_parms" nillable="false">
<xsd:complexType mixed="false">
<xsd:sequence>
<xsd:element name="request_type" nillable="false">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="1"/>
<xsd:whiteSpace value="preserve"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="cust_name" nillable="false">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:maxLength value="20"/>
<xsd:whiteSpace value="preserve"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="cust_number" nillable="false">
<xsd:simpleType>
<xsd:restriction base="xsd:int"/>
</xsd:simpleType>
</xsd:element>
<xsd:element name="invoice_number" nillable="false">
<xsd:simpleType>
<xsd:restriction base="xsd:decimal">
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.
