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).