Docs.bmc.com will undergo a brief maintenance outage 27 March 2025. The site will be unavailable for ten minutes starting at 6:30 AM CDT/5 PM IST.

Using the object XML functions

You can use the XML functions to transform XML documents to AR System structures, or AR System structures to XML documents. You can also use the ARGetListXMLObjects call to get a list of the AR System structures in an XML document.

Make sure that your program calls the ARInitialization call at the beginning of its execution. See AR-System-C-API-functions.

Transforming XML documents into AR System structures

Use the following AR System XML API functions and structures to transform XML documents into AR System structures:

ARXMLInputDoc

Supply this structure with the XML document to parse, in one of the following forms:

  • AR_XML_DOC_CHAR_ST — null-terminated character string (you must free the memory associated with this action)
  • AR_XML_DOC_FILE_NAME — file name
  • AR_XML_DOC_URL — URL
     See the ar.h file for definitions of this structure.

ARParseXMLDocument

This function parses the XML document and returns a parsed XML stream and a list of object names and types.
 The combination of object name and object type must be unique for each object in the XML document. For example, you cannot have two schemas named ABC in a single XML document. However, you can have a schema and a filter named ABC in one XML document, as these are different object types.

ARGetObjectFromXML

These functions retrieve the properties of the object from the parsed XML stream and places the properties into the output parameters. Supply NULL for any property that you do not want to retrieve.

FreeARXMLParsedStream

This function frees memory associated with the parsed stream. For more information, see arfree.h.

Transforming AR System structures into XML documents

Use the following AR System API functions and structures to transform AR System structures into XML documents:

ARXMLOutputDoc

This structure contains the XML document generated from calls to the Set functions in one of the following forms:

  • AR_XML_DOC_CHAR_STR — null-terminated character string
  • AR_XML_DOC_FILE_NAME — file name (A new file is created. If the file already exists, the new XML contents are appended to the end of the file.)
  • AR_XML_DOC_FILE_HANDLE — file handle
     See the ar.h file for definitions of this structure.

ARSetHeaderToXML

This function generates the XML declaration and start tag for the root element (such as <?xml...?>< root> ).
 The server sets the document encoding in the XML declaration to the encoding of your local machine.

ARSetStructureToXML

This function transforms AR System structures into XML.

ARSetFooterToXML

This function generates the XML footer, which is the ending tag for the root element (</root>).

FreeARXMLParsedStream

This function frees memory associated with parsed stream.

If you only have a single structure to transform to XML, you can set the xmlDocHdrFtrFlag flag to TRUE (T) to automatically generate the XML document header and footer, instead of calling the ARSetHeaderToXML and ARSetFooterToXML functions. If you transform multiple structures to XML and combine them together, set this flag to FALSE (F).

Listing AR System structures

Use the ARGetListXMLObjects call to list the AR System objects in an XML document and retrieve the following object characteristics:

  • The object name.
  • The object type, which is in the form AR_STRUCT_ITEM_XML_ objectType, where objectType is filter, schema, or other object types.
  • The object subtype. For container objects, the subtype is in the form ARCON_containerType, where containerType is a guide, application, packing list, or filter guide. Currently only containers have a valid subtype. The subtype value for non-container objects is -1.
     If you are only retrieving object names, use the object subtype to increase the retrieval speed.

    See the ar.h file for object values.