NAME

      mxquery - add, list, modify, execute, or remove queries in Systems
      Insight Manager


SYNOPSIS

      mxquery -a -f filename [-x force] (add query)
      mxquery -m -f filename (modify query via xml file)
      mxquery -r queryname ... (remove query)
      mxquery -r -f filename (remove query via xml file)
      mxquery -e queryname (execute query and show results)
      mxquery [-l n|t] [ queryname ...] (list query)
      mxquery -lf [-b encoding] [-x query [ queryname ...] (list query to xml
      file)
      mxquery -l cat (list all query categories)
      mxquery -l crit (list all query criteria)
      mxquery -l mode criterianame (list criteria operators)
      mxquery -l val criterianame (list criteria values)


DESCRIPTION

      The mxquery command allows a Systems Insight Manager user to add,
      list, modify or remove queries in Systems Insight Manager.

      IMPORTANT NOTE: The use of category in mxquery has been deprecated in
      favor of mxcollection. While use of 'cat' will still work for mxquery
      in this release, users should move to mxcollection for creating and
      manipulating collections (previously known as categories.)

      The first form of mxquery (mxquery -a -f filename) allows the user to
      add queries.  The information regarding the query is provided in a
      query definition file (see mxquery(4)) and allows the user to add one
      or more Systems Insight Manager queries.

      During an add operation, Systems Insight Manager only adds queries
      whose names do not reference queries currently in the Systems Insight
      Manager repository. If Systems Insight Manager detects a duplicate
      query, Systems Insight Manager will skip the duplicate query, but
      continue to add all non-duplicate queries. Skipping duplicate queries
      in this case does not affect the exit code.

      Optionally, the user may specify the force flag. The force flag
      instructs the system to add a query's criteria even if there is not a
      database entry that corresponds to the criteria value. This only
      affects criteria values that are selected from a list of values stored
      in the database, such as system names.

      The second form of mxquery (mxquery -m -f filename) allows the user to
      modify the definition of one or more Systems Insight Manager queries.
      The information regarding the query is provided in a query definition
      file.  When modifying a query, the user must either be the query's
      owner or be a full rights user.

      The third and fourth forms of mxquery (mxquery -r queryname) and
      (mxquery -r -f filename) allows the user to remove Systems Insight
      Manager queries.	Only a full rights user or the query owner may
      remove a query.  If the user specifies a query name that does not
      correspond to a query in Systems Insight Manager, Systems Insight
      Manager notifies the user that it cannot remove the query and attempts
      to remove the next designated query. Skipping undefined queries in
      this case does not affect the exit code. The user may specify the
      queries as a list of query names, or a query definition file.

      The fifth form of mxquery (mxquery -e queryname) allows the user to
      execute the specified query and displays the results of the query. The
      user must specify the name of an existing query to execute. The user
      must be authorized to execute the query against the managed systems
      that the query targets. (see mxauth(1M))

      The sixth form of mxquery (mxquery -ln|t queryname) allows the user to
      list Systems Insight Manager queries or to view the definitions of
      specified Systems Insight Manager queries. With no qualifiers, mxquery
      lists the names of all registered Systems Insight Manager queries.
      With the n qualifier, mxquery provides a list of all Systems Insight
      Manager query names (the same as no qualifier). With the t qualifier,
      mxquery gives a tabular listing showing some of the attributes of all
      registered Systems Insight Manager queries. The user may limit the
      query information by specifying one or more query names.

      The seventh form of mxquery (mxquery -lf queryname) writes to stdout a
      complete Systems Insight Manager query definition (see mxquery(4)) for
      each Systems Insight Manager query. Optionally, the user may specify
      the character encoding for the XML output.  The value for the
      character encoding must match a valid character encoding. If no
      encoding is specified, the system attempts to write the file in the
      encoding currently defined for the given system. The list of valid
      character encodings is maintained at the following web site.
      http://www.iana.org/assignments/character-sets
      The user may specify individual queries by specifying the query name.
      Otherwise, all queries in the system are output.

      The eighth form of mxquery (mxquery -l cat) lists the names of all of
      the query categories that the user may add queries to. To add a query,
      the query definition must contain a category from this list.

      The ninth form of mxquery (mxquery -l crit) lists the names of
      criteria that may be specified for a query. Criteria specify the
      search values that Systems Insight Manager uses when executing a
      query. Some criteria have a list of defined values that must be used
      when specifying that given criteria. This command lists the criteria
      name and the query type in which the criteria may be specified.

      The tenth form of mxquery (mxquery -l mode criterianame) lists the
      operation modes or operators that are valid for a specified criteria.
      The eleventh form of mxquery (mxquery -l val criterianame) lists the
      defined criteria values for the specified criteria. If the specified
      criteria does not have defined values, then Systems Insight Manager
      does not list any data.

    Options
      mxquery recognizes the following options:

	   -a		  Indicates that one or more Systems Insight Manager
			  queries, specified in a query definition file, are
			  to be added.

	   -m		  Indicates that one or more Systems Insight Manager
			  query definitions are to be replaced by the
			  definition in the specified query definition file.

	   -r		  Indicates that one or more Systems Insight Manager
			  queries are to be removed.

	   queryname	  Specifies the name of the Systems Insight Manager
			  query to be removed or listed.  Specification of
			  an undefined query name results in mxquery
			  operating on zero queries and an exit code of
			  SUCCESS. Specification of an invalid query name,
			  i.e. one that violates the rules for query names
			  (see mxquery(4)), results in an invalid name exit
			  code.

	   -f filename	  Specifies the path and name of a file that
			  contains the definition of one or more Systems
			  Insight Manager queries to be added, modified, or
			  removed.

	   -l f		  Displays a file-formatted listing of Systems
			  Insight Manager queries (this output may be used
			  as input to the -f option).

	   -l n		  Displays the names of Systems Insight Manager
			  queries.

	   -l t		  Displays a tabular list of Systems Insight Manager
			  queries and query attributes.

	   -l cat	  Displays a list of query categories to which the
			  user may add queries.

	   -l crit	  Displays a list of criteria with which the user
			  may construct queries.

	   -l mode	  Diplays a list of operation modes or operators
			  that may be used in association with a specified
			  criteria.

	   -l val	  Displays a list of defined values associated with
			  a specified criteria

	   criterianame	  Is the name of an existing criteria for which the
			  user requests additional information, such as
			  operation modes or defined values.

	   -x		  Specifies an extended option value. This is used
			  in conjuction with the following keywords.

	   force	  Specifies to force a query into the system when
			  used in conjuction with the -af options.

	   cat		  Specifies to list only query categories when used
			  in conjuction with the -lf options.

	   query	  Specifies to list only queries when used in
			  conjunction with the -lf options.

	   -b encoding	  Specifies the character encoding for an XML file
			  when used in conjunction with the -lf option.

      Note: When duplicate options are specified (for example, -f file1 -
      f file2), the last instance of the option will be used by mxquery (in
      this example, file2).


EXTERNAL INFLUENCES

      For HP-UX or Linux, LANG determines the default encoding that the
      system will use to output XML data if no encoding is specified on the
      command line.  If LANG is not specified or null or LANG does not
      correspond to a recognized encoding, it defaults to C (see lang (5)).
      In this case, the user should use the -b option to specify the desired
      encoding of the XML data.


RETURN VALUE

      mxquery returns one of the following values:

	     0		  Successful completion.
	     1		  Command line syntax error.
	     2		  Error in a file operation or parsing a file.
	    21		  Invalid name.
	   102		  Systems Insight Manager Repository error.
	   222		  Central Management Server (CMS) is not
			  initialized.
	   249		  Unable to connect to the session manager.
	   250		  Remote exception.


EXAMPLES

      This command adds the queries defined in the Systems Insight Manager
      query definition file named "/home/user1/defs/myquerydef".

	   mxquery -a -f /home/user1/defs/myquerydef

      This command modifies queries based on the Systems Insight Manager
      query definition file named "/home/user1/defs/myquerymods".

	   mxquery -m -f /home/user1/defs/myquerymods

      This command removes the Systems Insight Manager query called
      "badquery".

	   mxquery -r badquery

      This command removes queries based on the Systems Insight Manager
      query definition file named "/home/user1/defs/myquerymods".

	   mxquery -r -f /home/user1/defs/myquerymods

      This command displays the list of Systems Insight Manager querynames.

	   mxquery -ln

      This command displays a tabular listing of the Systems Insight Manager
      queries with column headings.

	   mxquery -lt

      This command displays the Systems Insight Manager queries in XML file
      format.

	   mxquery -lf

      This command displays the categories to which the user may save
      queries.

	   mxquery -lcat

      This command displays the criteria names and their associated query
      type.

	   mxquery -lcrit

      This command displays the operation modes associated with the criteria
      named "CriteriaByIPAddress".

	   mxquery -lmode CriteriaByIPAddress

      This command displays the defined criteria values for the criteria
      named "CriteriaByProductType".

	   mxquery -lval CriteriaByProductType


LIMITATIONS

      This command may only be run on the CMS.


AUTHOR

      mxquery was developed by the Hewlett-Packard Company.


SEE ALSO for HP-UX

      mxauth(1M) mxquery(4).


SEE ALSO for Linux

      mxauth(8) mxquery(4).