Skip to content

Filtering XML Services Messages

The ChangeMan ZMF XML Services API, like all text markup languages, is verbose. Occasionally, when large volumes of data are returned in response to a request, the verbosity of XML can overwhelm working storage capacity or severely degrade performance. To address this issue, Serena XML supports custom result filtering for XML services that accept <request> subtags in the request message and return <result> tags in the reply. This is accomplished by using the optional <includeInResult> tag in the <request> data structure.

<includeInResult> Tag

The <includeInResult> tag applies to all XML services with explicit <request> subtags in the request message and explicit <result> subtags in the reply.

The <includeInResult> tag explicitly identifies the subtags to include in the <result> tags returned in the XML reply message. The tag is repeatable to accommodate multiple <result> subtags. If used, only the subtags explicitly named in an instance of <includeInResult> will be returned. All other subtags normally returned in the <result> by the service are suppressed.

The <includeInResult> tag filters returned tags only. XML Services uses this tag to postprocess reply messages and strip out extraneous tags as it builds each <result> data element. The <includeInResult> tag has no effect on the filtering applied by a service when identifying which records to process or include in a report.

An example of the <includeInResult> tag in a package general search follows. This example requests a search for all packages in frozen status. But the full set of <result> tags is not desired in the reply; instead, only the <package> tag and <auditReturnCode> will be returned.

Data structure details for the <includeInResult> tag appear in Exhibit 3-9.

XML Example — Filtering a General Package Search with <includeInResult>

<?xml version="1.0" encoding="UTF-8"?>
<service name="PACKAGE">
    <scope name="GENERAL">
    <message name="SEARCH">
        <request>
            <searchForFrozenStatus>Y</searchForFrozenStatus>
            <includeInResult>package</IncludeInResult>
            <includeInResult>auditReturnCode</IncludeInResult>
        </request>
    </message>
    </scope>
</service>

...

Exhibit 3-9. <includeInResult> Data Structure

Subtag Use Occurs Data Type & Length Description & Values
<includeInResult> Optional in any <request> tag 0 - ∞ String (255), variable Contains desired <result> subtag name without angle brackets. Note: Value is case-sensitive.

...