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)