The daily edition.

Scope and Architectural Overview

This article covers event-driven XML parsing, register flow control, and parser emulation options in Rocket Enterprise Developer / Enterprise Server 12.0 for Linux/UNIX.

In enterprise application modernization, programs migrated from IBM mainframe z/OS environments process inbound XML transactions using the native XML PARSE statement. Unlike DOM-style XML parsers that ingest the entire document into an in-memory object tree, The XML PARSE Statement interfaces with a SAX-style parser embedded in the COBOL run-time system.

The parser scans the XML document stream linearly, decomposes it into constituent lexical fragments, and repeatedly invokes a user-written processing procedure, passing event tags and payload data through runtime special registers.

The Event-Driven Model and Special Registers

A typical XML PARSE statement directs document fragments into a specified processing procedure:

XML PARSE xml-document-stream
     PROCESSING PROCEDURE handle-xml-events
     ON EXCEPTION
         DISPLAY "XML parsing failed: " XML-CODE
     NOT ON EXCEPTION
         DISPLAY "XML parsing completed successfully"
END-XML

During execution, communication between the runtime parser and the processing procedure is mediated by dedicated Special Registers:

• XML-EVENT: An 8-byte alphanumeric register populated with the event name for the current fragment, such as START-OF-DOCUMENT, START-OF-ELEMENT, ATTRIBUTE-NAME, ATTRIBUTE-CHARACTERS, CONTENT-CHARACTERS, END-OF-ELEMENT, END-OF-DOCUMENT, or EXCEPTION.
• XML-TEXT / XML-NTEXT: Contains the fragment text payload. Alphanumeric documents populate XML-TEXT (UTF-8 or EBCDIC), while national documents populate XML-NTEXT (UTF-16).
• XML-NAMESPACE and XML-NAMESPACE-PREFIX: Contains element/attribute namespace URIs and prefix aliases when XML namespaces are declared.
• XML-CODE: Contains parser status and error codes.

Controlling Parse Flow via XML-CODE

As detailed in User Routine, the processing procedure typically structures its logic around an EVALUATE XML-EVENT statement. Beyond inspecting data, the procedure actively directs parser execution using XML-CODE:

1. Non-Fatal Error Recovery: When the parser detects an exception, it sets XML-EVENT to 'EXCEPTION' and places a non-zero error code into XML-CODE. If the procedure can remediate or ignore the condition, it sets XML-CODE to 0 before returning. The runtime recognizes this as an exception resolution and resumes parsing.
2. Controlled Premature Abort: If the application locates the necessary data elements and does not need to parse the remainder of a large document, the procedure can set XML-CODE to -1 during any normal event. The parser immediately halts and transfers control to the ON EXCEPTION block without generating an EXCEPTION event.
3. Execution Exit Rules: The processing procedure must return control to the parser using normal flow through the end of the procedure. Attempting to return using GOBACK or EXIT PROGRAM is illegal and causes undefined behavior, though terminating the entire run unit with STOP RUN is permitted.

Compiler Emulation: XMLPARSE(XMLSS) vs. XMLPARSE(COMPAT)

The behavior of XML PARSE and its entity resolution is governed by the XMLPARSE compiler directive:

XMLPARSE"version"

• XMLPARSE"XMLSS" (Default): Emulates IBM Enterprise COBOL Version 4 XML System Services.
  • Supports enhanced namespace processing, RETURNING NATIONAL, ENCODING, and VALIDATING against XML schemas.
  • Single-Event Entity Resolution: Predefined XML entities (such as ', ", &) are converted to their represented character and merged seamlessly into surrounding text. For example, the string <item name="baker&apos;s dozen"/> produces a single CONTENT-CHARACTERS event containing "baker's dozen".
• XMLPARSE"COMPAT": Emulates legacy IBM Enterprise COBOL Version 3.
  • Character entities are split into fragmented events. The same string <item name="baker&apos;s dozen"/> triggers three distinct events: CONTENT-CHARACTERS with "baker", followed by CONTENT-CHARACTERS with "'" , followed by CONTENT-CHARACTERS with "dozen". Programs migrating from Version 3 must be aware of this event segmentation.

Operational Prerequisites and Nuances

• Dynamic-Length Data Prohibition: The XML document stream (identifier-1) must not be defined as a dynamic-length group or dynamic-length elementary item.
• National Document Encodings: If identifier-1 is defined as a national data item, it must use CCSID 1200 (UTF-16). Character entities represented by multiple encoding units are prohibited and must use numerical character references instead.
• Schema Validation Overhead: Specifying the VALIDATING phrase requires the schema to be provided in unparsed text format. When validation fails, XML-EVENT is set to 'EXCEPTION', with XML-CODE containing decimal return code 24 in the high-order halfword and a diagnostic reason code in the low-order halfword.

Documentation Takeaway

In Rocket Enterprise Developer 12.0 for Linux/UNIX, XML PARSE executes as a stream-oriented SAX parser transferring fragments to a processing procedure via XML-EVENT and XML-TEXT; applications can dynamically recover from exceptions by resetting XML-CODE to 0 or abort parsing cleanly by setting XML-CODE to -1, while the XMLPARSE compiler directive dictates whether XML entities are merged into a single event (XMLSS) or split into separate events (COMPAT).