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, XML TERMINATE should be called when the COBOL application is finished using XML Extensions statements. (If XML TERMINATE has not been called prior to program termination, there are no consequences.)
• Empty array occurrences. As an optimization, trailing empty occurrences of arrays (COBOL tables) are normally not generated by the statements, XML EXPORT FILE or XML EXPORT TEXT.

  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 of 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) to the output file. Using XML ENABLE ATTRIBUTES forces these attributes to be written to the output file, although the optional StyleSheetName parameter might specify an XSLT stylesheet transformation that removes some or all of the attributes from the final output file.

• 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.

• Data conversion flags. The data conversions performed by the statements, XML EXPORT FILE, XML EXPORT TEXT, XML IMPORT FILE, and XML IMPORT TEXT, may be modified from their defaults. By default, the following data conversion flags are set: PF-Trailing-Spaces, PF-Leading-Spaces, PF-Leading-Minus, and PF-Rounded. (However, PF-Trailing-Spaces and PF-Leading-Spaces are ignored in several instances as described in XML SET FLAGS.)

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

• 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 in exported documents. For more information, see COBOL and Character Encoding.

• Tracing. Trace information can be generated to a designated file using the XML TRACE statement. Trace information includes the status from each XML Extensions statement and can frequently be useful in analyzing errors in an application.
• Stylesheet parameters. The passing of parameters to stylesheets can be controlled by the XML SET XSL-PARAMETERS and XML CLEAR XSL-PARAMETERS statements.