Skip to content

Message Processing Cycle

The architectural building blocks of XML Services come together in the Serena XML message processing cycle. The message processing cycle flows through the following steps:

  • Serena XML request message issued from client to server

  • XML message parsed

  • XML data mapped to internal ChangeMan ZMF data formats

  • Requested task performed by low-level service object

  • Service object success/failure codes and output data mapped to XML data elements

  • Serena XML reply message sent by server to client

Every Serena XML request message that reaches the server triggers a Serena XML reply. At minimum, the reply includes a result code that informs the requesting program whether the requested task succeeded, generated a warning message, or failed. Successful requests may trigger several result messages as well — each result representing, for example, a record in a data set or a line in a report. All results generated by a single XML request document are returned in a single XML reply document.

Submitting a Serena XML Request

Serena XML service request messages are issued from the client to the server via a software developer’s “kit” (SDK) or environment optimized for a particular programming language. Batch XML is submitted via the SERXMLBC batch client. Interactive XML can be prototyped in XMLSERV with prompts for required tags and other ease-of-use features, then submitted for execution through SERXMLBC.

The SERXMLCC COBOL-to-XML batch execution client, together with a collection of COBOL copybooks, facilitates XML Services API requests using native COBOL data formats and program calls. Each copybook wraps the proper Serena XML syntax around the contents of predefined COBOL variables populated by your custom COBOL program. Your COBOL program then calls SERXMLCC to generate a true Serena XML request document and place it in the normal XML message processing stream.

The SERXMLRC REXX-to-XML batch execution client similarly facilitates XML Services API requests using native REXX stem data formats and program calls. Your REXX program populates an approximate REXX stem structure, then calls SERXMLRC to generate a Serena XML request document and place it in the normal XML message processing stream.

The SERXMLAC ASSEMBLER-to-XML batch execution client facilitates XML Services API requests using native ASSEMBLER data formats and program calls.

Service, Scope, and Message Syntax

Every Serena XML service request uses a high-level XML syntax that identifies the ChangeMan ZMF service, scope, and message names for the task requested. These values, in combination, uniquely identify the modular service object on the server that must process the request. They also identify the function to be performed and the category of information to perform it against. Their values also must be specified with CAPITAL letters. The batch execution client that submits your request first preprocesses it to ensure that the combination of service, scope, and message names is valid.

Message Routing

If the XML Services service, scope, and message names are valid, the execution client calls the appropriate client messaging program — either SERCLIEN on the mainframe or SERNET Connect on distributed platforms — to initiate a connection to ChangeMan ZMF. The preferred communications protocol for this connection is TCP/IP, but cross-memory services (XMS) is also supported if the client and server both reside on the same mainframe

LPAR. The messaging client performs any necessary data compression and packages the XML message with appropriate headers for network addressing, handshaking, and mainframe logon. It then requests a communications session to ChangeMan ZMF via the SERNET messaging server.

The SERNET messaging server resides on the host in the ChangeMan ZMF server address space, where it listens on one or more communication ports for incoming messages. When a message arrives, SERNET completes any network handshaking needed, processes the communications headers, and establishes a conversation. SERNET also decompresses messages and performs any needed data format conversions (e.g. from ASCII to EBCDIC).

If the inbound message contains Serena XML, the SERNET messaging server calls the XML Services input handler to transform that data into internally readable form. The XML input handler then returns the transformed data to the SERNET messaging server, which routes it to the appropriate low-level service object for action.

XML Parsing and Data Mapping

At the core of XML Services are its XML parsing and bidirectional data mapping processes. These interpret Serena XML message streams and map the identified XML data structures of a request to the internal assembler DSECT formats used by the low-level service objects in ChangeMan ZMF. In the reverse direction, the low-level service objects return results that are mapped from their internal assembler DSECT formats to Serena XML data elements, then marshalled into Serena XML reply messages. Serena uses proprietary parsing to achieve faster XML processing.

Generating the Serena XML Reply

After the XML input handler has parsed the Serena XML request message and mapped its data to an appropriate DSECT structure, SERNET queues that DSECT request block for input to the requested low-level service object. The service object receives the request block, performs the requested task, and generates (at minimum) a numeric return code. It may also generate an output message, a report listing, or a set of search results. This output data is stored in one or more output DSECTs populated by the low-level service object. The output is then returned to SERNET for routing to the XML output handler.

The XML output handler marshals a Serena XML reply document from one or more of these output DSECTs. Guided by the permanent object mapping table, the XML output handler maps each field in the DSECT to its corresponding XML tag and creates a document content model for the reply document in a temporary hashed tag pool. The output handler then transforms the document content model into well-formed XML and places the resulting document in a user response area known to the SERNET messaging server.

Control then returns to SERNET, which compresses the XML reply message, packages it with appropriate communications headers, and routes it to the requesting client. Note that, for distributed clients, the SERNET messaging server echoes the original XML request in the XML reply document. For ChangeMan ZMF clients, however, the original XML request is not echoed.