COBOL-to-XML Copybooks

Each XML service is shipped as a COBOL copybook. Note that the copybooks, as shipped, define all service combinations and all possible input and output XML.

To execute Serena XML Services calls, you need not work directly with XML and SERXMLBC. Instead, you can use COBOL copybooks in your custom COBOL programs.

ChangeMan ZMF provides a set of copybooks that enable COBOL programs to generate Serena XML message streams. The copybooks wrap literal strings containing XML tag names and other syntax around COBOL variables. Your COBOL program populates these variables with the values you want to submit to ChangeMan ZMF in your Serena XML request. The data values for these COBOL variables are identical to those you would use to populate their corresponding XML data elements.

If Serena XML Services returns one or more XML <result> tags, all tags are removed and the result is presented to the user program as a table of COBOL variables with one row for each <result>.

Using Temporary Data Sets

You can refine the copybooks to suit your needs and set up the COBOL program to optionally introduce a temporary data set to contain the results. See Solution S142060 for a description and example of this capability.

In addition, the temporary dataset may use a file of your choosing. The name of the file is passed in the parameters list and follows the naming convention CCXMLOnn, where nn is any number. This allows you to design Cobol programs that combine multiple services into one report. See Solution S131020 for an example of this feature.

Copybook Member Names

In many cases, there is one COBOL-to-XML copybook for each combination of <service>, <scope>, and <message> names supported by Serena XML Services. Some copybooks are used for more than one <scope> and <message> combination. Copybook member names have the following form:

XMLCxxxx

Where xxxx is a four-letter mnemonic for one or more service/scope/message combinations.

For example, XMLCPAPV is the COBOL copybook file that accesses the "package approval" function of the package management service object. It is associated with the following name attributes in the XML <service>, <scope>, and <message> tags:

<service name="package"> 
<scope name="service">
<message name="approve">

Cross reference tables showing COBOL copybook names for each of the XML services is provided in Exhibit 2-10 (for core ZMF functionality) and Exhibit 2-11 (for ERO services).

Caution

Do not modify the COBOL-to-XML copybooks. These code modules must remain synchronized with various XML-to-DSECT mapping files in order to work correctly. If you have a requirement that is not easily met using the COBOL-to-XML copybooks, you should use Serena XML Services directly.