Skip to content

High-level Tags in Serena XML

A few tags at the highest levels in the Serena XML document hierarchy are used consistently in all XML instance documents. These consistent usage patterns persist despite variations in the low-level service object called, the function requested of that object, or the scope of action requested. These high-level tags are documented below.

<service> Tag: The Root Data Element

The root data element in an XML Services message document is marked by the <service> tag. The <service> tag identifies the low-level service object that processes the message — such as the approver maintenance service (name=”approver”) or the package management service (name=”package”).

The <service> tag represents a complex data element with one attribute and one subordinate data element (or subtag). All attributes and subtags are required. The <service> tag data structure is summarized in Exhibit 3-4.

Exhibit 3-4. Data Structure for Serena XML <service> Tag

Attribute or Subtag Use Occurs Data Type & Length Description and Values
name Required 1 String (8), variable Attribute. XML service object name. Actual data length and value fixed for each service object. See Exhibit 3-10 for allowed values.
<scope> Required 1 Complex Element. See <scope> Tag tag.

<scope> Tag

The <scope> tag is the sole subtag of the <service> data element. It identifies the types of objects or class of services to be included in the scope of the service object’s operations. Example scopes include global records (name=”gbl”), application records (name=”apl”), package records (name=”pkg”), component records (name=”cmponent”), and service-wide functions (name=”service”). The chosen scope must be compatible with the requested service. Valid combinations are listed at the end of this chapter in Exhibit 3-10 and Exhibit 3-11.

The <scope> tag represents a complex data structure that has one attribute and one subtag. Both are required. The <scope> data structure is summarized in Exhibit 3-5.

Exhibit 3-5. Data Structure for Serena XML <scope> Tag

Attribute or Subtag Use Occurs Data Type & Length Description and Values
name Required 1 String (8), variable Attribute. XML scope name. Must be compatible with service name. Actual data length & value fixed for each service & function. See Exhibit 3-10 for values.
<message> Required 1 Complex Element. See <message> Tag.

...

<message> Tag

The XML Services <message> tag occurs as a subtag of <scope>. It identifies the task to be performed by the requested service within the requested scope of action. Example message names include create (name=”create”), delete (name=”delete”), update (name=”update”), list (name=”list”), and approve (name=”approve”). Message names must be consistent with the higher-level service and scope names. Valid combinations of service, scope, and message attribute names are listed at the end of this chapter in Exhibit 3-10 and Exhibit 3-11.

The <message> tag delimits a complex data element with one attribute and four optional subtags. Subtags must appear in sequence. The use and/or structure of each subtag depends on the service/scope/message combination in the XML document.

The <message> tag data structure is summarized in Exhibit 3-6.

Exhibit 3-6. Data Structure for Serena XML <message> Tag

Attribute or Subtag Use Occurs Data Type & Length Description & Values
name Required 1 String, variable Attribute. XML message type name for service and scope. Actual data length and value fixed for each service object and function. Allowed values appear in Exhibit 3-10.
<header> Required in mainframe batch jobs. 0 - 1 Complex Element. Consistent substructure whenever used. See <header> tag below.
<request> Required in requests. Not used in replies. 0 - 1 Complex Element. Structure varies with service, scope, and message. See particular <request> tag for desired user task elsewhere in this manual.
<result> Optional in replies. Not used in requests. 0 - ∞ Complex Element. Structure varies with service, scope, and message. See particular <result> tag for desired user task in XML Services User Guide.
<response> Required in replies. Not used in requests. 0 - 1 Complex Element. Consistent substructure whenever used. See <response> tag below.

...

<header> Tag

The <header> tag is a subtag within the <message> data structure. It contains routing and test options specific to the ChangeMan ZMF mainframe environment and is required only for TSO batch jobs. It does not appear in reply messages or in request messages submitted interactively.

Syntactically, the <header> tag takes the following general form:

<header>
    <subsys>P</subsys>
    <product>CMN</product>
    <test>T</test> 
</header>

Note the absence of a name attribute.

Data structure details for the <header> tag appear in Exhibit 3-7.

Exhibit 3-7. Data Structure for Serena XML <header> Tag

Attribute or Subtag Use Occurs Data Type & Length Description & Values
<subsys> Required 1 String (1) Element. One-byte identifier for ChangeMan ZMF instance or subsystem to which request is addressed.
<product> Optional 0 - 1 String (3) Element. Mnemonic for product to run under subsystem in <subsys> tag. Values:
CMN = ChangeMan ZMF (default)
XCH = Exchange (ZDD)
CLP (Client Pack) is a synonym for XCH and ZMF is a synonym for CMN.
<product>XCH</product> is functionally identical to <product>CLP</product>
and
<product>CMN</product> is functionally identical to <product>ZMF</product>
<test> Optional 0 - 1 String (1) Element. Used only at request of Serena Customer Support personnel for diagnostic purposes. Values: T = Enable test mode
<warn> Optional 0 - 1 String (1) Element. Used to enable XML WARN Facility for this XML request. See Warn - XML Tag Name Warning. This overrides the XML WARN Facility specification for the started task. Values: Y = Enable XML Warning

<request> Tag

The <request> tag is a subtag within the <message> data structure. It contains the actual content of a Serena XML request message and appears in all requests.

The syntax and structure of the <request> tag varies with the service/scope/message combination used in the XML message document. It takes no attributes, and on occasion it may even be empty (i.e., contain no subtags). Further information about specific <request> tag structures appears later in this manual.

<result> Tag

The <result> tag is a subtag within the <message> data structure. It appears only in reply messages and contains the output data, if any, generated by a low-level service object in response to a Serena XML request. It takes no attributes.

The <result> tag may be repeated 9,999 times to accommodate multiple result records. For reasons of performance and to minimize memory demands, ZMF limits the maximum number of occurrences of any tag -- including the <results> tag -- to 9999. Each <result> tag in a series may contain, for example, a line of code in a browsed component or an item in a list of search results. Alternatively, the tag may not appear at all.

All <result> tags in a Serena XML reply message appear before the final <response> tag, which contains the return code indicating whether or not the service completed successfully.

The syntax and structure of the <result> tag varies by the service/scope/message combination used in the document.

Further information about specific <result> tag structures appears later in this manual.

<response> Tag

The <response> tag is a subtag of the <message> data structure. It contains a mainframe return code, reason code, and/or message concerning the success or failure of your request. The <response> tag appears in every reply message issued by XML Services.

The structure of the <response> tag is consistent across all service objects and functions, all client environments, and all client products. It contains one required subtag and two optional subtags in a fixed sequence. It takes no attributes.

Syntactically, the <response> tag takes the following general form:

<response>
    <statusReturnCode>00</statusReturnCode>
    <statusReasonCode>0000</statusReasonCode>
    <statusMessage>Contents of message.</statusMessage> 
</response>

You should always monitor the contents of the <statusReturnCode> tag to trap error conditions. The value returned will be ‘00’ if your request executed successfully. Successively higher numeric values correspond to increasingly severe error conditions. System error codes and ABENDs may append an alphanumeric prefix to the code. You should familiarize yourself with ChangeMan ZMF return codes and messages before taking action on the <statusReturnCode> subtag or other elements of the <response> tag.

Data structure details for the <response> tag appear in Exhibit 3-8.

Exhibit 3-8. Data Structure for Serena XML <response> Tag

Subtag Use Occurs Data Type & Length Description & Values
<statusReturnCode> Required 1 String (4), variable Element. ChangeMan ZMF return code indicating successful completion or class and severity of error. Typical values: 00 - Execution successful 04 - Warning message 08 - Processing error (e.g., package does not exist) 16 - Syntax error (e.g., unrecognized tag, possibly because of incorrect case)
Note: Higher values indicate more severe errors. Abend or system error return codes may exceed 2 bytes & include alphanumerics. Note: Always check this tag to determine success of XML request.
<statusReasonCode> Optional 0 - 1 String (4), variable Element. ChangeMan ZMF reason code indicating type or cause of error, if any. Generally the status codes in XML replies are the same as the internal message numbers. For example, a status code of 8203 corresponds to SERNET message SER8203x
<statusMessage> Optional 0 - 1 String (255), variable Element. ChangeMan ZMF message text associated with the return code and reason code, if any.