NAME

      mxtool - add, list, modify, or remove tools in Systems Insight Manager


SYNOPSIS

      mxtool -a -f filename
      mxtool -m [-i] -f filename [-x force]
      mxtool -s -f filename
      mxtool -r [-f filename |-c category | -t toolname ] [-x force]
      mxtool -l d|f|n|t [-c category ... | -t toolname ...]
      mxtool -lf [-b encoding] [-c category ... | -t toolname ...]
      mxtool


DESCRIPTION

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

      The first form of this command allows the user to add tools.  The
      information regarding the tool is provided in a tool definition file
      (see mxtool(4)) and allows the user to add one or more Systems Insight
      Manager tools.

      When adding a tool, if the user is a full rights user (see mxuser(1)),
      Systems Insight Manager will accept the owner value specified for a
      given tool in the tool definition file. If the owner field is not
      specified, then the tool's owner field is empty and this tool is
      enabled in all toolboxes that it is in. If the user is not a full
      rights user, however, Systems Insight Manager will ignore the owner
      specification for the given tool and set the tool's owner field to the
      user's id only. Additionally, if the user is not a full rights user,
      Systems Insight Manager only allows the "All Tools" toolbox to be
      defined in a tool definition. Systems Insight Manager ignores the
      value of the toolbox enabled flag and only enables the "All Tools"
      toolbox.

      When the owner field is specified, that is not empty, Systems Insight
      Manager ignores the toolbox enabled flag and disables the tool in all
      of the specified toolboxes with the exception of the "All Tools". To
      enable the tool in all of the specified toolboxes, a full rights user
      must modify the tool's definition. Specifically, a full rights user
      must remove the owner field from the tool. By default, when a full
      rights user removes the owner field, Systems Insight Manager sets the
      toolbox enabled flag to "true". A full rights user may set the toolbox
      enabled flag to "false" to explicitly disable the tool in all of the
      toolboxes except the "All Tools".

      During an add operation, Systems Insight Manager will only add tools
      whose names do not reference tools currently in Systems Insight
      Manager. If Systems Insight Manager detects a duplicate tool, Systems
      Insight Manager will inform the operator of the add operation, but
      will continue to add all non-duplicate tools. Skipping duplicate tools
      in this case does not affect the exit code. During the add operation,
      Systems Insight Manager assigns the "All Tools" toolbox to every tool
      by default.

      The second form of mxtool allows the user to modify the definition of
      one or more Systems Insight Manager tools.  The information regarding
      the tool is provided in a tool definition file.  When modifying a
      tool, the user must either be the tool's owner or be a full rights
      user. If the user is a full rights user, the user may modify the
      entire tool definition. If the user is the owner but is not a full
      rights user, the user may modify most attributes of the tool but may
      not modify the owner attribute or the tool's toolboxes. Systems
      Insight Manager ignores the value of the toolbox enabled flag in the
      input file and sets the toolbox enabled flag in the tool to "false".
      By specifying the -i option, the full rights user directs Systems
      Insight Manager to ignore changes to toolboxes in the modified tool
      definitions.

      If the owner field of the tool is not set and a non-full rights user
      wishes to modify the tool, a full rights user must modify the tool's
      definition to set the tool's owner field to the user name of the non-
      full rights user.	 Additionally, mxtool will ignore any changes to a
      tool's toolboxes made by a non-full rights user.

      Systems Insight Manager will not allow the user to add tools using the
      modify option. During the modify operation, if Systems Insight Manager
      finds a tool in the tool definition file that does not exist in
      Systems Insight Manager, Systems Insight Manager will notify the user
      of the modify operation, but will continue to modify the tools
      specified in the tool definition file that do exist in Systems Insight
      Manager. Skipping undefined tools in this case does not affect the
      exit code.

      During the modify operation, Systems Insight Manager will not permit
      the user to remove the "All Tools" toolbox from any tool.

      Only a full rights user is allowed to add or modify and tool which is
      multiple-system aware, such as Ignite.  Only a full rights user is
      allowed to delete a tool.

      All tools must contain the revision attribute.  The revision attribute
      is used to confirm that the tool defined in the tool definition file
      is of a greater revision than the one in Systems Insight Manager.	 The
      tool revision attribute is used while modifying a tool.  If it is not
      provided, then a revision of 1.0 is assigned to the tool in Systems
      Insight Manager when it is added. By specifying the -x force option,
      Systems Insight Manager is directed to ignore the tool revision
      attribute in the modified tool definitions.

      The third form of mxtool allows the user to scan a tool definition
      file without changing the Systems Insight Manager domain, i.e. adding
      or modifying an Systems Insight Manager tool.  This form allows the
      user to check a tool definition file for syntax errors.

      The fourth form of mxtool allows the user to remove Systems Insight
      Manager tools.  Only a full rights user may remove a tool.  If the
      user specifies a tool name that does not correspond to a tool in
      Systems Insight Manager, Systems Insight Manager will notify the user
      that it cannot find the tool and will attempt to remove the next
      designated tool. Skipping undefined tools in this case does not affect
      the exit code. If a task has been created using the tool, then
      attempts to remove it are not successful.	 By specifying the -x force
      option, Systems Insight Manager is directed to ignore the task
      dependencies of the tool and remove it.  The user may specify the
      tools as a list of tool names, a list of categories, or a tool
      definition file.

      The fifth form of mxtool allows the user to list Systems Insight
      Manager tools or to view the definitions of specific Systems Insight
      Manager tools. With no qualifiers, mxtool lists the names of all
      registered Systems Insight Manager tools. With the d qualifier, mxtool
      provides a detailed screen-viewable listing of Systems Insight Manager
      tools. With the f qualifier, mxtool writes to stdout a complete
      Systems Insight Manager tool definition (see mxtool(4)) for each
      Systems Insight Manager tool. With the n qualifier, mxtool provides a
      list of all Systems Insight Manager toolnames (the same as no
      qualifier). With the t qualifier, mxtool gives a tabular listing
      showing some of the attributes of all registered Systems Insight
      Manager tools. The -c option allows the Systems Insight Manager user
      to constrain the output to one  or more tool categories.	The -t
      option allows the Systems Insight Manager user to constrain the output
      to specific Systems Insight Manager tools.

      The sixth form of mxtool lists the Systems Insight Manager tools in an
      XML file format. Optionally, the user may specify the character
      encoding in the XML file. 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 last form of mxtool lists the names of all Systems Insight Manager
      tools currently configured in the Systems Insight Manager domain.

    Options
      mxtool recognizes the following options:

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


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

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

	   -i		  Directs Systems Insight Manager to ignore changes
			  to toolboxes in the tool definitions.	 This option
			  is only valid with the -m modify option.

	   -s		  Indicates that the specified tool definition file
			  should be scanned for syntax errors without
			  performing any other operations.

	   -c category	  Specifies a tool category.  Specification of an
			  undefined category name results in mxtool
			  returning an empty tool list and an exit code of
			  SUCCESS. Specification of an invalid category
			  name, i.e. one that violates the rules for
			  category names (see mxtool(4)), results in an
			  invalid name exit code.

	   -t toolname	  Specifies the name of the Systems Insight Manager
			  tool to be removed or listed.	 Specification of an
			  undefined tool name results in mxtool operating on
			  zero tools and an exit code of SUCCESS.
			  Specification of an invalid tool name, i.e. one
			  that violates the rules for tool names (see
			  mxtool(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 tools to be added or modified.
			  This option must also be specified with the scan
			  option, -s. See mxtool(4).

	   -l d		  Displays a detailed and screen-viewable listing of
			  Systems Insight Manager tools.

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

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

	   -l t		  Displays a tabular list of Systems Insight Manager
			  tools and tool attributes.


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

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

	   force	  Specifies to force a tool into the system when
			  used in conjuction with the -mf option. Or,
			  specifies the forced confjunction with the -rf
			  option.

      Note: When duplicate options are specified (for example, -f file1 -
      f file2), the last instance of the option will be used by mxtool (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

      mxtool 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 tools defined in the Systems Insight Manager
      tool definition file named "/home/user1/defs/mytooldef".

	   mxtool -a -f /home/user1/defs/mytooldef

      This command modifies tools based on the Systems Insight Manager tool
      definition file named "/home/user1/defs/mytoolmods".

	   mxtool -m -f /home/user1/defs/mytoolmods

      This command forcefully modifies the tools based on the Systems
      Insight Manager tool definition file named
      "/home/user1/defs/mytoolmods".

	   mxtool -m -f /home/user1/defs/mytoolmods -x force

      This command removes the Systems Insight Manager tool called
      "badtool".

	   mxtool -r -t badtool

      This command displays the list of Systems Insight Manager toolnames.

	   mxtool -ln

      This command displays a detailed, screen-viewable listing of the
      Systems Insight Manager tools.

	   mxtool -ld

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

	   mxtool -lt

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

	   mxtool -lf


LIMITATIONS

      This command may only be run on the CMS.


AUTHOR

      mxtool was developed by the Hewlett-Packard Company.


SEE ALSO for HP-UX

      mxexec(1M), mxtool(4).


SEE ALSO for Linux

      mxexec(8), mxtool(4).