NAME
mxquery - Systems Insight Manager query file format
SYNOPSIS
mxquery
DESCRIPTION
The mxquery command supports reading and writing query and query
category information in the eXtensible Markup Language (XML) format.
You may use this capability to add, modify, or remove multiple queries
or query categories in the Systems Insight Manager (ISM) environment.
Each file may contain the definitions of one or more queries or one or
more query categories or both.
Document Type Definition
The Document Type Definition (DTD) file defines the constraints for an
XML file. These constraints include the valid element tags,
attributes, and the cardinality of elements in an XML file. The query
DTD file is named querylist.dtd and is included in the following
paragraph. Note that due to man page formatting, the DTD contents may
not appear the same as in the file.
<?xml version="1.0" encoding="UTF-8" ?>
<!--
READ THIS FIRST! This file is intentionally formatted with a
right margin set at 70. This allows the DTD file to be pasted
directly into the mxquery(4) man page file. Please respect this
constraint when editing this file. After edits are final for
a given release, please paste the final DTD version in the
mxquery(4) man page to keep the documentation current.
-->
<!--
The query-list consists of 0 or more query elements or category
elements.
-->
<!ELEMENT query-list ( query | category )* >
<!--
The query element defines each query in the query list. The query
element contains attributes to define the query name, the query
type, the query category, and the query category type. The query
element is composed 0 or more criteria.
-->
<!ELEMENT query ( criteria* ) >
<!--
The query id attribute is optional. The query id must be a
numeric value. The query id is assigned by the system, so when
adding a query, this field is not specified. When modifying or
removing a query, this field is required and is generated by the
system when the system generates the XML file.
-->
<!ATTLIST query id CDATA #IMPLIED >
<!--
The query name attribute is required. The query name may contain
embedded blank characters.
-->
<!ATTLIST query name CDATA #REQUIRED >
<!--
The query type attribute is required. The query type must be one
of the specified query types.
-->
<!ATTLIST query type ( DeviceViews | ClusterViews | EventViews |
ToolsViews ) #REQUIRED >
<!--
The query access attribute specifies whether the query is public
or personal. By default, the query is personal. A person query is
associated with the query owner's personal category. A public
query is associated with a system category.
-->
<!ATTLIST query access ( public | personal ) "personal" >
<!--
The query category type attribute specifies the type of category
to associate with the query. If no category type is specified,
the query is associated with the same category type as the query
type. If a user wishes to associate the query with a category
different than the query type, the user must specify this field.
-->
<!ATTLIST query category-type ( DeviceViews | ClusterViews |
EventViews | ToolsViews ) #IMPLIED >
<!--
The query category name is required. A query category consists of
several layers of information. The query category name is the
last layer of that information. All queries must be associated
with a query category. The system determines the query category
using the query or category type, the query access, the query
owner, and the category name.
-->
<!ATTLIST query category-name CDATA #REQUIRED >
<!--
The query owner attribute specifies the owner of the query. The
query owner attribute is needed if the query is not public and
the query owner is different that the user under whose session
the query is added. The owner name must correspond to a valid
user in this system.
-->
<!ATTLIST query owner CDATA #IMPLIED >
<!--
A query may consist of 0 or more criteria elements. The criteria
must have a valid criteria name and zero or more value elements
or zero or more sw-fw-value elements. If the criteria type is a
software/firmware criteria, then the value elements must be the
sw-fw-value elements. For other criteria types, the value element
must be the plain value element.
-->
<!ELEMENT criteria ( value | sw-fw-value )* >
<!--
The criteria name attribute must be set to a known criteria
name.
-->
<!ATTLIST criteria name NMTOKEN #REQUIRED >
<!--
The criteria sense may be either "INCLUDE" or "EXCLUDE". By
default, criteria have an "INCLUDE" sense.
-->
<!ATTLIST criteria sense ( INCLUDE | EXCLUDE ) "INCLUDE" >
<!--
The criteria may have zero or more values. The legal values
vary for each kind of criteria.
-->
<!ELEMENT value ( #PCDATA ) >
<!ATTLIST value type CDATA #IMPLIED >
<!--
The value operator attribute specifies how to evaluate the
specified criteria value. The valid operators for a given
criteria name may be listed using the command
mxquery -lmode <criteria-name>.
If the criteria object's operators are "is" and "is not", use the
"include" and "exclude" sense attributes instead.
If the criteria object's operators are "contains", "starts with",
"ends with", or "equal to", then the system will evaluate the
criteria value using a string matching algorithm corresponding to
the specified operator.
If one of the criteria object's operators is the "between"
operator is chosen, the criteria value may be specified as either
one value or two values separated by a hyphen '-' character. In
the second case the system searches from and including the first
value to and including the second value. If only one value is
specified using the "between" operator, the value is evaluated as
if the "eq" operator was chosen.
Note that the mxquery -lmode <criteria-name> command does not
return "eq", "gt", "ge", "lt", and "le" operators. Rather the
command returns their mathematical symbol equivalents. The "eq"
operator equates to the "=" symbol. The "gt" operator equates to
the ">" symbol. The "ge" operator equates to the ">=" symbol.
The "lt" operator equates to the "<" symbol. The "le" operator
equates to the "<=" symbols. These operators were used instead of
the mathematical symbols, because the mathematical symbols are
also XML reserved tokens. Creating an XML file using these tokens
is very cumbersome for a user.
Note that the "equal to" and the "eq" operators are not
equivalent. Use the "equal to" operator when the
mxquery -lmode command returns that value as a valid operator.
The "equal to" operator is used for string comparisons. The "eq"
operator is used for other types of comparisons such as IP
addresses, memory ranges, or times. Use the "eq" operator when
the mxquery -lmode command returns the "=" symbol as a valid
operator. Unlike the "between" operator, the "eq", "gt", "ge",
"lt", and "le" operators evaluate only one value.
-->
<!ATTLIST value operator ( is | is-not | contains | starts-with |
ends-with | equal-to | between | eq |
gt | ge | lt | le ) "is" >
<!--
For software/firmware criteria types, the criteria may have zero
or more sw-fw-value elements. The sw-fw-value element is
specified by its attributes and may optionally have a description
element.
-->
<!ELEMENT sw-fw-value (description)? >
<!--
The software/firmware value may specify the division for the
criteria. The division comes from the populated list of values
for version control repository associated with the
software/firmware criteria. The division attribute is optional
and is not used to find the associated software/firmware criteria
in the system. When the system outputs software/firmware criteria
to an XML file, the system includes the division attribute for
informational purposes.
-->
<!ATTLIST sw-fw-value division CDATA #IMPLIED >
<!--
The software/firmware value must specify the operating system for
the criteria. The operating system comes from the populated list
of values for version control repository associated with the
software/firmware criteria.
-->
<!ATTLIST sw-fw-value operating-system CDATA #REQUIRED >
<!--
The software/firmware value must specify the package name for
the criteria. The package name may refer to either software/
firmware packages or bundles and comes from the populated list
of values for version control repository associated with the
software/firmware criteria.
-->
<!ATTLIST sw-fw-value package CDATA #REQUIRED >
<!--
The software/firmware value may specify an operation to perform
against the available versions during the query. By default, the
"any" operation is performed. The "any" operation indicates that
the query should return matches to any of the versions for the
specified software/firmware criteria. For the "any" operation,
the version attribute is not required and if it is specified, the
version attribute is ignored. The remaining operators require
a version attribute to be specified. The operators are "eq" for
equals, "gt" for greater than, "ge" for greater than or equal to,
"lt" for lesser than, and "le" for lesser than or equal to.
-->
<!ATTLIST sw-fw-value operator (any | eq | gt | ge | lt | le) "any" >
<!--
The version attribute specifies a version value to apply to the
query search. If the "any" operator is specified, the version
attribute is optional and is ignored.
-->
<!ATTLIST sw-fw-value version CDATA #IMPLIED >
<!--
The software/firmware value may specify the package description
for the criteria. The description comes from the populated list
of values for version control repository associated with the
software/firmware criteria. The description element is optional
and is not used to find the associated software/firmware criteria
in the system. When the system outputs software/firmware criteria
to an XML file, the system includes the description element for
informational purposes.
-->
<!ELEMENT description (#PCDATA) >
<!--
The category element defines each category in the query list.
The category element contains attributes to define the category
name, the category type, the category access, and the category
owner.
-->
<!ELEMENT category EMPTY >
<!--
The category must have a name attribute to specify the category
name.
-->
<!ATTLIST category name CDATA #REQUIRED >
<!--
The category access level may be either public or personal and is
personal by default.
-->
<!ATTLIST category access ( public | personal ) "personal" >
<!--
The category type may be associated with systems/devices,
clusters, events, or tools/tasks and is associated with devices/
systems by default.
-->
<!ATTLIST category type ( DeviceViews | ClusterViews | EventViews |
ToolsViews ) "DeviceViews" >
<!--
The category owner specifies the name of the user to own the
category, that is, the owner specifies the category under which
personal queries for the specified user would be associated. The
owner field is optional. If the owner field is not specified and
the category is personal, then the category is owned by the user
that adds the category to the system. If the category is public,
the owner field is ignored, and the systems assigns the default
administrative user as the category owner.
-->
<!ATTLIST category owner CDATA #IMPLIED >
Elements
As defined in the DTD, the query XML file may contain the following
elements.
The first line of a query XML file should be in the following format:
<?xml version="1.0" encoding="encoding-value" ?>
where the user substitutes a recognized encoding value for the
encoding-value parameter. The recognized encoding values may be found
at the following web site:
http://www.iana.org/assignments/character-sets
If no XML header line is specified, the system defaults encoding to
"UTF-8".
The "query-list" element must appear once in a query XML file and
wraps the list of query or query category information. The "query-
list" element may contain zero or more "query" elements or zero or
more "category" elements. Note if the "query-list" element contains
no "query" or "category" elements, the associated mxquery command will
have no effect.
The "query" element may appear zero or more times in a query XML file.
The "query" element has seven attributes.
The "id" attribute is optional and specifies the unique query ID. The
system always outputs the "id" attribute when listing an existing
query to an XML file. The user must specify the "id" attribute only if
the user wishes to change the name of an existing query. When adding a
new query the user must not specify the "id" attribute, because the
system assigns the id value to new queries.
The "name" attribute is mandatory and specifies the query name. The
user may change the name of an existing query by specifying the new
name in the "name" attribute with the id of the existing query in the
"id" attribute.
The "type" attribute is required and specifies the type of query.
When it is specified it must be specified using "DeviceViews" for
system type, "ClusterViews" for cluster type, "EventViews" for event
type, or "ToolsViews" for task or tool type. Note that a query defined
as a "ToolsViews" query type will not be available in the portal UI.
The "access" attribute is optional and specifies whether the query
will be a public query or a personal query. It defaults to "personal".
If the user specifies a public query, the user must have the privilege
to modify the public lists.
The "category-type" attribute is optional and is only required if the
user wishes the query to be associated with a category different than
the category associated with the query type. The values are the same
as the "type" attribute. For instance, the user may define a query
that is a "ClusterViews" query type, but assign the query to the
"DeviceViews" category type.
The "category-name" attribute is required and assigns the query to a
specific category. The category specified by the "category-name"
attribute must exist in the system.
The "owner" attribute is optional and specifies the owner of the
query. If the owner of the query is the current user, then the user
may omit this attribute. If the owner of the query is not the current
user, then the user must specify this field, and the user must have
the privilege to modify public lists. When the owner attribute is
specified, the value must represent a user that is recognized by the
system.
The "query" element may contain zero or more "criteria" elements. The
"criteria" elements specify the values for which the query must
interrogate the system. The "criteria" element may contain zero or
more "value" elements or zero or more "sw-fw-value" elements but not
both. The "sw-fw-value" element may be used only with the
software/firmware criteria which is currently named
"CriteriaBySoftwareComponent". All other criteria use the "value"
element to specify their criteria values. The criteria element has
two attributes.
The "name" attribute is required and specifies the criteria name. The
criteria name must be one of a list of criteria names that are
returned by the following command:
mxquery -lcrit
The "sense" attribute is optional and specifies whether the criteria
represents an inclusion criteria or an exclusion criteria. The
allowable values are "INCLUDE" or "EXCLUDE" and the default value is
"INCLUDE".
The "criteria" element may consist of one or more "value" elements for
all criteria except the software/firmware criteria. The "value"
element specifies the values and, in some cases, the operation, of the
criteria for the query. Some criteria have a list of predefined values
from which the user must select to form a valid query. The user can
get a list of the valid selection values for a criteria by using the
following command:
mxquery -lval <criteria-name>
For instance, to get the list of selection values for the criteria
that queries the system by system name, the user would use the
following command:
mxquery -lval CriteriaByName
If the user executes the mxquery command and the command does not
return a list of values, then the criteria may not have a list of
selection values. In this case, the criteria may accept a value with
an operation that is specified using the "operator" attribute. To
determine if the criteria has an operation mode, the user may enter
the following command:
mxquery -lmode <criteria-name>
If the command returns "is" or "is not" as the operation modes, then
the criteria has a selection list; otherwise, the criteria requires
that the user specify one of the listed operation modes with the
criteria value.
A special criteria type is the software/firmware criteria used to
query based on the Version Control Repository. To specify a
software/firmware criteria value, the user must specify a "sw-fw-
value" element. The "sw-fw-value" element contains attributes that are
unique to the software/firmware criteria specification.
The following command lists the values that correspond to the "sw-fw-
value" element attributes:
mxquery -lval CriteriaBySWComponent
From the command output, the "System Type:" field corresponds to the
"division" attribute. The "Operating System:" field corresponds to the
"operating-system" attribute. The "Package Name:" field corresponds to
the "package" attribute. The "Version:" field corresponds to the
"version" attribute. Note that the "division" attribute is optional
when specifying a "sw-fw-value" element.
In addition to "query" elements, the user may specify "category"
elements within the "query-list" elements. When executing an add
operation using a query XML file, the system processes the "category"
elements first, regardless of their position in the query XML file.
A "query-list" element may contain 0 or more "category" elements. The
"category" element is an empty element, which means the "category"
element is specified entirely by its attributes.
The "name" attribute specifies the category name and is required.
The "access" attribute specifies whether the category is "public" or
"personal". To add a "public" category, the user must have the public
list modification privilege.
The "type" attribute specifies the category type. The values for the
category type correspond to the query type.
The "owner" attribute specifies the category owner. The owner field is
only required if the category is a personal category, and the owner is
different from the current user processing the query XML file.
Commenting
Comments may be included in XML files. The comment must begin with
the characters "<!--" and end with the characters "-->". Comments may
span multiple lines within the beginning and ending character tags.
Examples
This section contains some examples of query XML files.
This example shows a file containing the definition of a query that
reports important events.
<?xml version="1.0" encoding="UTF-8"?>
<query-list>
<query name="Important Events" type="EventViews"
category-name="EventsBySeverity" access="public" >
<criteria name="CriteriaByEventSeverity" sense="INCLUDE">
<value>Critical</value>
<value>Major</value>
<value>Minor</value>
</criteria>
</query>
</query-list>
This example shows a file containing the definition of a query that
specifies two types of criteria to report important, uncleared events.
<?xml version="1.0" encoding="UTF-8"?>
<query-list>
<query name="Important Uncleared Events" type="EventViews"
category-name="EventsBySeverity" access="public" >
<criteria name="CriteriaByClearedStatus" sense="INCLUDE">
<value>Not Cleared</value>
<value>In Progress</value>
</criteria>
<criteria name="CriteriaByEventSeverity" sense="INCLUDE">
<value>Critical</value>
<value>Major</value>
<value>Minor</value>
</criteria>
</query>
</query-list>
This example shows a file containing the definition of a query that
reports on systems whose operating system names contain the string
"Windows".
<?xml version="1.0" encoding="UTF-8"?>
<query-list>
<query name="All Windows" type="DeviceViews"
category-name="myqueries" >
<criteria name="CriteriaByOSNameComparison" sense="INCLUDE">
<value operator="contains">Windows</value>
</criteria>
</query>
</query-list>
This example shows a file containing the definition of a query that
reports on systems whose IP address fall within a specified range.
<?xml version="1.0" encoding="UTF-8"?>
<query-list>
<query name="IP Range" type="DeviceViews"
category-name="myqueries" >
<criteria name="CriteriaByIPAddress" sense="INCLUDE">
<value operator="between">255.101.168.50-255.101.168.100</value>
</criteria>
</query>
</query-list>
This example shows a file containing the definition of a query that
reports on systems with the software bundle named "ProLiant Support
Pack for Microsoft Windows 2000 (English (US))".
<?xml version="1.0" encoding="UTF-8"?>
<query-list>
<query name="SW Bundle Query" type="DeviceViews"
category-name="myqueries" >
<criteria name="CriteriaBySWComponent" sense="INCLUDE">
<sw-fw-value division="System Software Baseline"
operating-system="Microsoft Windows 2000"
package="ProLiant Support Pack for Microsoft Windows 2000 (English (US))"
operator="any">
</sw-fw-value>
</criteria>
</query>
</query-list>
LIMITATIONS
This command may only be run on the CMS.
AUTHOR
mxquery was developed by the Hewlett-Packard Company.
SEE ALSO for HP-UX
mxquery(1M)
SEE ALSO for Linux
mxquery(8)