First introduced in CICS TS 3.1, CICS Web Services support offers a powerful tool that lets CICS application programs access the Web as both consumers and providers of Web-based services. As with any new technology, Web services bring opportunity and confusion; initial implementation comes with a steep learning curve. To reduce this learning curve and encourage the use of Web services, IBM supplies the CICS Web Services Assistant.
IBM’s Web Service Assistant is a set of utilities designed to create COBOL or PL1 copybooks for CICS Web service requesters, Web Services Descriptor Language (WSDL) definitions for CICS Web service providers, and basic CICS infrastructure support for both providers and requesters. Use of the Web Services Assistant isn’t required, and has some limitations (such as the fact the Assistant only works with COBOL and PL1, and Assembler support isn’t provided) but it can significantly reduce the applications and systems programming effort required to build and implement a CICS Web service.
One of the least understood and most confusing of the Web Services Assistant’s features is the way in which it handles “variable array data”—that is, a data element that contains a table whose number of entries isn’t known at compile time. Variable array data is more commonly referred to in COBOL as the OCCURS DEPENDING ON feature. Support of variable array data becomes more complex if the variable arrays are “nested.” In COBOL terms, that means a table defined with OCCURS DEPENDING ON itself contains a table defined with OCCURS DEPENDING ON.
This article describes the processes the CICS Web Services Assistant uses when handling nested variable array data structures. (Note that while the WSDL to COBOL [DFHWS2LS] Web Services Assistant utility supports the use of nested variable arrays, the COBOL to WSDL Web Services Assistant utility lacks support for variable arrays. If a CICS Web services provider wishes to provide support for OCCURS DEPENDING ON, you must make a copy of the COBOL copybook, change all the OCCURS DEPENDING ON clauses to fixed [i.e., OCCURS 5 TIMES], manually modify the XML produced by the assistant to change the minOccurs and maxOccurs to their appropriate values, and run the DFHWS2LS utility to create a COBOL copybook that’s set up to support variable arrays in a manner the Web Services Assistant run-time support can handle.)
Support for Fixed Size Tables
Consider a straightforward example: a COBOL table with a fixed number of entries and no DEPENDING ON. The table field, MY-TABLE-ELEMENT, is defined in COBOL (see Figure 1). At compile time, the compiler recognizes there must be 25 bytes of storage reserved for this table (five entries multiplied by 5 bytes per entry) and builds the internal definitions accordingly. At run-time, the Web Services Assistant recognizes that the 25 bytes in question represent five MY-TABLE-ELEMENT table entries and parses the storage into five XML data definitions. This handling of fixed tables follows COBOL’s handling, so no special program code is required.
Variable Size Tables
When defining a Web service, using tables with a fixed number of entries will make data handling significantly simpler. In the real world, however, variable arrays are often required to fit the requirements of the functions being performed. Let’s enhance the previous example to a variable number of entries (see Figure 2).
At compile time, there’s no way for the compiler to determine how many entries will be in the table, so there’s no way for it to reserve the storage required for this table, making it difficult for the Assistant to handle the storage requirements at run-time. The Assistant does have a workaround to handle this situation using CICS channels; the table entries (MY-TABLE-ELEMENT in our example) are placed into a container. The naming convention of the containers is used to relate a container to a specific table, and includes a numeric counter to indicate the number of entries that have been placed in the container. The sample definition in Figure 3 shows what the MY-TABLE variable array would look like in XML.
The COBOL data definitions generated by the DFHWS2LS from the WSDL are much more complex than a normal OCCURS DEPENDING ON. First, in the COBOL copybook that describes all the data elements, the definitions of MY-TABLE and MY-TABLE-ELEMENT are removed and replaced with control information, resulting in something similar to Figure 4. Here, all the COBOL definitions referenced are formatted using the original definition. For several reasons (including, for example, XML data names don’t use a dash the way COBOL does), the data element names the Web Services Assistant produces from WSDL don’t follow common COBOL naming conventions.