State management statements

Calls to the following XML statements control several states or conditions, including:

Initialization and termination. Before issuing a call to any other XML Extensions statement, XML INITIALIZE must be called. (If XML INITIALIZE has not been called, any subsequent calls, for example, XML EXPORT FILE, will fail.) Similarly,

An empty occurrence of an array is defined to be one where the numeric items have a zero value and the nonnumeric items have a value equivalent to all spaces. This is the default state and is equivalent to calling XML DISABLE ALL-OCCURRENCES. It is possible to force all occurrences to be output by calling XML ENABLE ALL-OCCURRENCES.

  • COBOL attributes. For each element generated by the statements, XML EXPORT FILE or XML EXPORT TEXT, there is a series of COBOL attributes that describe that element.

    The default state is not to output these attributes. However, it is sometimes necessary for a following activity (such as an XSLT stylesheet transformation) to have access to these attributes (specifically, length and subscript are often important to a follow-on activity). Using XML DISABLE ATTRIBUTES prevents attributes from being written (this is the default). Using XML ENABLE ATTRIBUTES forces these attributes to be written.

  • Document caching. XML documents, such as XSLT stylesheets, templates, and schemas, are normally considered to be static during the use of a production version of the application. That is, they are generated when the application is developed and are not modified until the application is modified.

    To optimize performance, when XML Extensions loads an XSLT stylesheet, a template, or a schema, the document is cached (that is, retained in memory) for an indefinite period of time. This is the default behavior. However, even with the default behavior, a document in the cache may be flushed from memory if the cache is full and an XSLT stylesheet, template, or schema document not already in the cache is required for the current operation.

    If XSLT stylesheets, templates, or schemas are being generated dynamically, the user may selectively enable or disable caching. Executing XML ENABLE CACHE, which sets the default behavior, enables caching of documents. Executing XML DISABLE CACHE disables caching, thus forcing all documents to be loaded each time they are referenced. Executing XML FLUSH CACHE flushes all documents and local memory from the cache without changing the state of caching (that is, if caching was enabled it remains enabled). Executing any of the following statements causes the contents of the cache to be flushed: XML INITIALIZE, XML ENABLE CACHE, XML DISABLE CACHE, XML FLUSH CACHE, and XML TERMINATE. Executing XML ENABLE CACHE, XML DISABLE CACHE, or XML FLUSH CACHE also causes local memory to be flushed.

    For more information, see Memory Management with XML Extensions.

  • Flags. The data conversions performed by the statements, XML EXPORT FILE, XML EXPORT TEXT, XML IMPORT FILE, and XML IMPORT TEXT, use the library (which is built into the XML Extensions runtime executable) to perform these conversions. By default, the following flags are set: PF_TRAILING_SPACES, PF_LEADING_SPACES, PF_LEADING_MINUS, and PF_ROUNDED.

    Note: The flags are C macros. They are case sensitive and require the use of the underscore character.

    XML GET FLAGS and XML SET FLAGS are available to alter these defaults.

  • Whitespace flags. The handling of whitespace by the statements XML IMPORT FILE and XML IMPORT TEXT use the whitespace handling flags built into XML Extensions. By default, the whitespace flags are set to

    WHITESPACE-DEFAULT-FLAGS (value 0).

    XML GET WHITESPACE-FLAGS and XML SET WHITESPACE-FLAGS are available to obtain or change, respectively, the setting of the whitespace flags. The XML Extensions handling of whitespace during import is explained in the topic Handling Spaces and Whitespace in XML.

  • Internal character encoding. Characters within alphanumeric data elements in a COBOL program are normally encoded using the conventions of underlying operating systems. Under some conditions, it may be desirable to encode these same data items using UTF-8 encoding. (UTF-8 is a format for representing Unicode.) XML SET ENCODING is provided to switch between the local encoding format and UTF-8.

    Note: Both the UNIX and Windows implementations of XML Extensions allow the in-memory representation of element content to use UTF-8 encoding. This may be useful for COBOL applications that wish to pass UTF-8-encoded data to other processes. XML documents are normally encoded using Unicode. XML Extensions always generates UTF-8 data. For more information, see COBOL and Character Encoding and XML and Character Encoding.
  • Tracing. Trace information can be generated to a designated file using the XML TRACE statement.
  • Stylesheet parameters. The passing of parameters to stylesheets can be controlled by the XML SET XSL-PARAMETERS and XML CLEAR XSL-PARAMETERS statements.