Receiving extensible markup language (XML) output data in the XML output buffer

Use the high-level language application programming interface to obtain output in XML format. The XML output may also return error messages and return and reason codes.

Figure 1 shows an example that issues an RMM SEARCHRACK subcommand and writes the XML output into the file named XMLFILE.

You can work with the output data in XML format by writing the output into a file or by parsing the output directly. You can define this file in the JCL, which you use to issue the command.

This example shows in C++ code how to:

Issue a DFSMSrmm TSO subcommand by using the method issueCommand() .
Use the method getBufferXml() to obtain access to the XML data.

Figure 1. C++ code example for writing XML output to a file

FILE*  xmlFp;                                  /* declare file pointer */
RmmApi* pApi;                                  /* declare an Api object */  
RmmCommand* pCom;                              /* declare a Command object */
pApi = new RmmApi();                           /* create an Api object */   
pApi->openApi();                               /* open Api */
pCom = new RmmCommand(pApi);                   /* create a Command object */
pCom->issueCmd("SR RACK(*)");                  /* issue a Command */
xmlFp = fopen("DD:XMLFILE","w")                /* open the file for writing */  
fprintf(xmlFp,"%s",pCom->getBufferXml());      /* print the data into the file */  
fclose(xmlFp);                                 /* close the file */

Figure 2 shows the content of the file XMLFILE.

Figure 2. XMLFILE output file

<?xml version="1.0" encoding="EBCDIC-CP-US" ?>
<document xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:noNamespaceSchemaLocation="/usr/lib/xml_schema/rmmxml.xsd">
<RACK>
<RCK>RACK  </RCK>
<VOL  xsi:nil="true"></VOL>
<RST>EMPTY</RST>
<LOC>SHELF</LOC>
<MEDN>3480</MEDN>
<PID>*</PID>
</RACK>
<INFO>
<RTNC>4</RTNC>
<RSNC>4</RSNC>
<MSGT>EDG3011I 1 ENTRY LISTED  </MSGT>
</INFO>
</document>

Most of the DFSMSrmm-produced XML tags use the SFI names described in Table 1. For example, the XML tag for volume is <VOL>, which corresponds to the SFI name VOL. The DFSMSrmm-produced XML tags that do not use the SFI names are these tags.

The XML tag <VOLINFO> for the volume resource group.
The XML tag <VRSINFO > for the VRS resource group.
The XML tags <JBN2>, <NME2>, <SCD2>, and <SCN2>, which represent the structured field introducers <2JBN>, <2NME>, <2SCD> and <2SCN>. XML does not allow tags to start with numeric characters.
The XML tags <DSS6> and <USE6> are structured using additional tags for factor ( <xxxxF> ) and value ( <xxxxS> ), where xxxx is the XML tag name.

The XML output structure is declared in the XML schema file RMMXML.XSD, that you find in your file system directory /usr/lib/xml_schema. The schema contains type definitions for all elements.

The XML data stream contains a Uniform Resource Identifier (URI) to reference the required schema. To change the schema location, use the XML parser setExternalnoNamespaceSchemaLocation method.

DFSMSrmm ensures it creates only well-formed and valid XML documents and ensures that any text within an element contains only valid characters. The special characters &, <, >, ", and ' are escaped using the entities:

&: &
<: <
>: >
": "
': '

Your XML parser will convert the entities back to the correct text character. Any code, such as CIM provider, that processes the XML document without a parser must consider that these entities might exist within the document and should be converted back to the correct character before use of the data.

Related reading: You can write your own application to parse the XML data by using the XML parser. IBM® provides an XML parser and sample applications in the XML Toolkit for z/OS® available at http://www.ibm.com/zseries/software/xml or from the IBM Software Delivery for System Modification Program Extended (SMP/E) installation.