Skip to content

Syntax Conventions for Search, Summary, and Analysis

Serena XML adopts certain syntax conventions that apply in all search, summary, and analysis contexts. For example, a few commonly used tags support alternate uses or alternate data type conventions in a search, summary, or analysis context. Other conventions involve data dependencies and default value interactions among multiple, related tags.

Semicolon-Delimited Lists

The allowed contents of commonly used tags may be different in search contexts than in nonsearch contexts. For example, many user ID and security entity tags, which elsewhere permit only a single value, may accept a semicolon-delimited list of TSO user IDs or RACF security entities in a search context. Similar lists may be allowed in package or component name tags as well. For the services discussed in this chapter, the following tags support such lists:

  • <component>

  • <package>

  • <creator>

  • <stager>

  • <workRequest>

Yes/No Flag Tags

All search, summary, and analysis services in Serena XML follow common default value conventions for yes/no flag tags. They also share common conventions for Boolean relationships among flag tag values.

The key to these conventions is the flag tag group. The values of all flag tags within a group are considered together; in fact, such mutual processing is the basis for identifying such tags as a group. Many flag tag groups may be supported by a single service. For example, all package status flag tags are treated as a group, as are all package type tags, and package level tags. Flag tag groups, however, are evaluated independently of each other.

Default Values Within a Group

All yes/no flag tags in a group default to the value "Y" if no tag in the group has an explicitly assigned value. But if any flag tag in the group is explicitly assigned a value, all other tags in the group change their default values to "N."

This is actually the behavior you would expect if you weren’t thinking too hard about it. For example, if your XML request says nothing about which package types to include, the package type flag tags all default to "Y" values, and you will get all package types in your reply. But if your XML request explicitly states you want all planned permanent packages, the assumption is made that you don’t want any other package types. The flag tag value that you have set to "Y" retains that value, but the defaults for all other flag tags in the group default to "N". To request multiple package types, you would set the yes/no flags for each desired package type to an explicit "Y" value.

Tip

If you explicitly set flag tag values, always include at least one "Y" value in each flag tag group. This is necessary because Serena XML does not fully support Boolean NOT operations. You can include an item in a given state, and you can exclude an item in a given state, but you cannot include in your search results an item that is not in a given state. If you explicitly set just one flag tag in a group to a value of "N" and take the defaults for the rest, no results will be returned.

Boolean Relationships Within a Group

The "Y" values of all tags within a yes/no flag tag group are related by Boolean OR in search, summary, or analysis contexts. Any item in any state requested by a "Y" flag is returned in the results.

Tags with a value of "N" in a group are related by Boolean AND to the other tags in the group. Any item in any state identified by a flag with a value of "N" is excluded from the results.