NAME

      mxtask - list, execute, remove, create tasks or change task ownership
      in Systems Insight Manager


SYNOPSIS

      mxtask
      mxtask -lt
      mxtask -ld taskname
      mxtask -lf taskname [-b encoding]
      mxtask -r taskname
      mxtask -e taskname
      mxtask -o taskname taskowner
      mxtask -c taskname -q queryname -t toolname -w schedule [ -A toolparms
      | -f toolparmsfile ] [ -o taskowner ] [ -i timefiltername ]
      mxtask -cf taskxmlfile
      mxtask -h


DESCRIPTION

      The mxtask command allows a Systems Insight Manager user to list all
      tasks, list details for a particular task, list task parameters in xml
      format, execute a task, remove a task, change ownership for a
      particular task, create a task from the command line, or create a task
      from an external xml file.

      The first and second form of this command (-lt) provides a tabular
      listing showing the major attributes of all Systems Insight Manager
      tasks currently registered in the repository. Information shown will
      include task name, associated query name, associated tool name and
      task type with associated schedule data.

      The third form of this command (-ld) allows the user to list the
      details for a specified task. Information listed will include task
      name, tool name, query name, task owner, last time task was run, next
      time task will run, last time task information was modified, type of
      task, and any possible tool user parameters (in xml format) that may
      be associated with the specified tool.

      The fourth form of this command (-lf) allows the user to list the
      specified task in task specific xml format. Output from this command
      writes to stdout, and may be redirected (via '>') to an external file.
      The file can then be modified and then used as the xml input file when
      creating a new task via the (-cf) command.  See the mxtask(4) man page
      for a detailed description of the task specific xml format.
      Optionally, the user may specify a character encoding for 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 fifth form of this command (-r) allows the user to remove the
      specified task. The task will be removed immediately. The user must
      specify the name of an existing task to be removed. The user must be
      authorized to remove the task. (see mxauth(1M))

      The sixth form of this command (-e) allows the user to execute (run)
      the specified task. The task will execute immediately.  The user must
      specify the name of an existing task to execute. The user must be
      authorized to execute the task against the managed systems that the
      associated query is targeted for. (see mxauth(1M))

      The seventh form of this command (-o) allows the user to change
      ownership for the specified task. The user must specify the name of an
      existing task and the desired new owner. The user must be authorized
      to change task ownership. (see mxauth(1M))

      The eighth form of this command (-c) allows the user to create a new
      task. The information regarding the new task is provided directly on
      the command line. To create a new task, the user must be a full rights
      user.

      The ninth form of this command (-cf) allows the user to create a new
      task. The information regarding the new task is provided by an
      external task specific XML definition file. To create a new task, the
      user must be a full rights user. See the mxtask(4) man page for a
      detailed description of the task specific xml format.

    Options
      mxtask recognizes the following options:

	   -l t		  Displays a tabular listing of all registered
			  Systems Insight Manager tasks along with
			  associated attributes.

	   -l d taskname  Displays a detailed attribute listing of a single
			  specified Systems Insight Manager task.

	   -l f taskname  Displays an xml file-formatted listing of a
			  specified Systems Insight Manager task (this
			  output may be redirected to a file and later used
			  as input to the -f option when creating a new
			  task).

	   -r taskname	  Indicates that a specified Systems Insight Manager
			  task is to be removed immediately.

	   -e taskname	  Indicates that a specified Systems Insight Manager
			  task is to be executed (run) immediately.

	   -o taskname taskowner
			  Indicates that a specified Systems Insight Manager
			  task is to be assigned a specified new owner.

	   -c taskname	  Indicates that a new Systems Insight Manager task
			  is to be created.  All required task configuration
			  information must be specified directly on the
			  command line and follow this option. Additional
			  required options include the following: -q, -t,
			  -w, (-A | -f)

	   -cf taskxmlfile
			  Indicates that a new Systems Insight Manager task
			  is to be created.  All required task configuration
			  information must be specified via an external file
			  containing task specific data in predefined xml
			  format. See the mxtask(4) man page for a detailed
			  description of the task specific xml format.

	   -h		  Displays extended help for mxtask.

	   -q queryname	  An option to specify name of an existing Systems
			  Insight Manager query.

	   -w scheduleinfo
			  An option to specify task schedule data.
			  'scheduleinfo' is a parameterized string which
			  defines the schedule data.  Details regarding the
			  format for this string is are given in a section
			  below.

	   -t toolname	  An option to specify name of an existing Systems
			  Insight Manager tool.	 Note that using the (-t)
			  option to specify a tool when creating a task from
			  the command line, one of the following two options
			  listed below are also required if the specified
			  tool does require additional user parameters.	 If
			  the specified tool does not require additional
			  user parameters, then neither of the following two
			  options (-A | -f) are required.

	   -A toolparms	  One of two available options that are required
			  with the create task (-c) command to specify the
			  parameter data for a specified tool that requires
			  user parameters (the other alternate option for
			  specifying user parameters is the (-f) option in
			  which an external file contains the user parameter
			  data in xml format - see below). The tool
			  parameter string that's provided on the command
			  line for the (-A) option must be enclosed in
			  double quotes. Also, if the tool parameter data
			  includes xml data, with embedded double quote
			  characters, each double quote character must be
			  preceded by the backslash escape character.

	   -f toolparmsfile
			  One of two available options that are required
			  with the create task (-c) command to specify the
			  parameter data for a specified tool that requires
			  user parameters (the other alternate option for
			  specifying user parameters is the (-A) option in
			  which the parameters are provided directly on the
			  command line. - see above). The tool parameters
			  for the (-f) option are provided in a specified
			  external file that contains the tool parameters in
			  proper xml format.

	   -o taskowner	  An optional option that may be used with the
			  create task (-c) command to specify a task owner
			  for the new task that will be created.  If no
			  owner is specified, the current logged in user
			  will be assigned as the task owner.

	   -i timefiltername
			  An optional option that may be used with the
			  create task (-c) command to specify that a an
			  already existing time filter be associated with
			  the new task that will be created.  If no time
			  filter name is specified, then the new task will
			  be created with no associated time filter.

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

    The 'schedule' parameterized string format:
      When creating a new task directly on the command line via the (-c)
      option, the task type/schedule information is required as a
      parameterized data string and is preceded by the (-w) option
      character.  The format for this parameterized string and valid
      assignment values are described below.

      The schedule parameterized string has the general format as shown
      below, and must begin with the 'T' (type) character. Note that the
      parameterized string must not contain any spaces and also note how the
      period character is used as a parameter separator.

      -w T<tasktype>.I<intervaltype>.P<periodic>.D<day|date>.M<time>

      The 'T' parameter signifies the task type and is required in all
      type/schedule parameterized strings. Valid <tasktype> values are
      "add", "remove", "manual" or "schedule". These task type values
      determine what type source triggers the task to run.


      Tadd -task runs when systems or events meet the list criteria

      Tremove -task runs when systems or events no longer meet the list
      criteria

      Tmanual -task only runs when manually invoked

      Tschedule -task runs based off a periodic/day/time schedule)

      The 'I' parameter signifies the Interval type and is required only
      when the 'T' task type value is "schedule". Valid <intervaltype>
      values are "minutes", "hours", "days", "weeks", "months", "daily" or
      "runonce".

      Tschedule.Iminutes - Task runs every x minutes.

      Tschedule.Ihours - Task runs every x hours.

      Tschedule.Iweeks - Task runs every x weeks at specified day/time.

      Tschedule.Imonths - Task runs every x months at specified day/time.

      Tschedule.Idaily - Task runs once a day at specified time.

      Tschedule.Irunonce - Task runs once at specified date/time.

      The 'P' parameter signifies the Periodic interval (how often the task
      will run) and is required only when the 'T' task type value is
      "schedule". Valid <periodic> values (n) are any numeric values greater
      than zero.

      Tschedule.Iminutes.Pn

      The 'D' parameter may signify a Day or Date value and is required only
      when the 'T' task type value is "schedule" and the 'I' Interval type
      is either "weeks", "months" or "runonce". Valid <day|date> values are
      dependant on the Interval type specified. If Interval type is "weeks",
      then the valid Day values are "sunday", "monday", etc. If Interval
      type is "months", then the valid Day value is a numeric value in the
      range of 1-31.  If Interval type is "runonce", then the valid Date
      value is mm/dd/yy.

      Tschedule.Iweeks.Pn.Dfriday

      Tschedule.Imonths.Pn.D1

      Tschedule.Irunonce.Dmm/dd/yy

      The 'M' parameter signifies a Time value and is required for all valid
      Interval types, except for "minutes" and "hours".	 This parameter
      defines the time at which the task will run and is specified in 24hr
      format as follows.

      Tschedule.Iweeks.P2.Dfriday.M1:00


EXTERNAL INFLUENCES ON XML DATA

      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.


EXTERNAL INFLUENCES ON TARGET EXECUTION ENVIRONMENT

      The language setting of the command shell in which you execute this
      command will be used as the preferred language that you want the
      command line tool contained within the task to execute with on the
      target node(s).  If creating a scheduled task, this language will be
      saved in the scheduled task and used each time it is executed.  The
      same is true if modifying an existing task.  If manually running a
      scheduled task, this language will be used to override the language
      stored in the task for this single execution.

      For Windows, the current Code Page setting of the Command Prompt
      window will be used to determine the preferred language.	For example,
      if the "chcp" command returns "932" the language is japanese.  The
      "chcp" command can be used to change the Code Page setting if the
      operating system has the language installed and is configured to allow
      its use.

      For Linux and HP-UX, the LANG environment variable describes the
      locale that will be used to determine the preferred language.  Valid
      settings for the LANG variable can be listed with the "locale -a"
      command.	However, in order to view the output, the terminal window
      running the command shell where you list the output of this command
      must support the language and encoding defined by the LANG variable.

      If the operating system on the target node does not support the
      language setting or encoding selected by the CMS, the command shell on
      the target node will use the default language and encoding for that
      target's operating system.

      (see lang (5)) (see environ (5)) (see local (1))


RETURN VALUE

      mxtask 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 lists all scheduled tasks in tabular format.	 Listing
      includes task name, associated tool name, last run time and schedule
      information.

	   mxtask

      This command lists all scheduled tasks in tabular format.	 Listing
      includes task name, associated tool name, last run time and schedule
      information.

	   mxtask -lt


      This command lists the details for a specified task. The task
      specified (taskname) must already exist in the Systems Insight Manager
      repository.  The (-lt) command may be used to view the names of all
      current tasks residing in the repository.

	   mxtask -ld taskname

      This command lists the descriptive data for a specified task in task
      specific xml format.  Output from this command may be used to create a
      new task requiring the same tool with similar tool (user) parameters.
      The output could be redirected to an external file, which in turn
      could then be manually edited and then used as an input file to create
      a new task with the (-cf) command.  See the mxtask(4) man page for a
      detailed description of the task specific xml format.  The (-lt)
      command may be used to view the names of all current tasks residing in
      the repository.

	   mxtask -lf taskname

      This command removes the specified task. The task specified (taskname)
      must already exist in the Systems Insight Manager repository.

	   mxtask -r taskname

      This command executes (runs) the specified task. The task specified
      (taskname) must already exist in the Systems Insight Manager
      repository.  The (-lt) command may be used to view the names of all
      current tasks residing in the repository.

	   mxtask -e taskname

      This command changes task ownership for the specified task. The task
      specified (taskname) must already exist in the Systems Insight Manager
      repository. The specified task owner (newtaskowner) will have the
      format of: "MachineName/User".  To view the current owner of a
      particular task, use the -ld option to view task details, of which the
      task owner will be included in the listing.  The (-lt) command may be
      used to view the names of all current tasks residing in the
      repository.

	   mxtask -o taskname taskowner

      This command creates a task of specified task name with an associated
      query (queryname) and tool (toolname) that already exists in the
      Systems Insight Manager repository.  The task type is specified as of
      type "add".  In this example, there are no tool (user) parameters
      required for the tool being specified, thus the (-A) nor the (-f)
      option are not required.	The (-lt) command may be used to view the
      names of all current tasks residing in the repository.

	   mxtask -c taskname -q queryname -t

      This command creates a task of specified task name with an associated
      query (queryname) and tool (toolname) that already exists in the
      Systems Insight Manager repository. The task type is specified as of
      type "remove".  In this example, there are no tool (user) parameters
      required for the tool being specified, thus the (-A) nor the (-f)
      option are not required.

	   mxtask -c taskname -q queryname -t

      This command creates a task of specified task name with an associated
      query (queryname) and tool (toolname) that already exists in the
      Systems Insight Manager repository. The task type is specified as of
      type "manual".  In this example, there are no tool (user) parameters
      required for the tool being specified, thus the (-A) nor the (-f)
      option are not required.

	   mxtask -c taskname -q queryname -t

      This command creates a task of specified task name with an associated
      query (queryname) and tool (toolname) that already exists in the
      Systems Insight Manager repository. The task type is specified as of
      type "schedule". The task is scheduled to run every 30 minutes.  In
      this example, there are no tool (user) parameters required for the
      tool being specified, thus the (-A) nor the (-f) option are not
      required.

	   mxtask -c taskname -q queryname -t

      This command creates a task of specified task name with an associated
      query (queryname) and tool (toolname) that already exists in the
      Systems Insight Manager repository. The task type is specified as of
      type "schedule". The task is scheduled to run every 12 hours.  In this
      example, there are no tool (user) parameters required for the tool
      being specified, thus the (-A) nor the (-f) option are not required.

	   mxtask -c taskname -q queryname -t

      This command creates a task of specified task name with an associated
      query (queryname) and tool (toolname) that already exists in the
      Systems Insight Manager repository. The task type is specified as of
      type "schedule". The task is scheduled to run every 2 weeks on Sunday
      at 2:00 AM.  In this example, there are no tool (user) parameters
      required for the tool being specified, thus the (-A) nor the (-f)
      option are not required.

	   mxtask -c taskname -q queryname -t

      This command creates a task of specified task name with an associated
      query (queryname) and tool (toolname) that already exists in the
      Systems Insight Manager repository. The task type is specified as of
      type "schedule". The task is scheduled to run every month on the 15th
      at 5:00 AM.  In this example, there are no tool (user) parameters
      required for the tool being specified, thus the (-A) nor the (-f)
      option are not required.

	   mxtask -c taskname -q queryname -t

      This command creates a task of specified task name with an associated
      query (queryname) and tool (toolname) that already exists in the
      Systems Insight Manager repository. The task type is specified as of
      type "schedule". The task is scheduled to run every 7 days on Tuesday
      at 6:00 PM.  In this example, there are no tool (user) parameters
      required for the tool being specified, thus the (-A) nor the (-f)
      option are not required.

	   mxtask -c taskname -q queryname -t

      This command creates a task of specified task name with an associated
      query (queryname) and tool (toolname) that already exists in the
      Systems Insight Manager repository. The task type is specified as of
      type "schedule". The task is scheduled to run every day on Saturday at
      1:00 AM.	In this example, there are no tool (user) parameters
      required for the tool being specified, thus the (-A) or the (-f)
      option are not required.

	   mxtask -c taskname -q queryname -t

      This command creates a task of specified task name with an associated
      query (queryname) and tool (toolname) that already exists in the
      Systems Insight Manager repository. The task type is specified as of
      type "schedule". The task is scheduled to run once at the specfied
      date (mm/dd/yy) and time (hh:mm). In this example, there are no tool
      (user) parameters required for the tool being specified, thus the (-A)
      or the (-f) option are not required.

	   mxtask -c taskname -q queryname -t

      This command creates a task of specified task name with an associated
      query (queryname) and tool (toolname) that already exists in the
      Systems Insight Manager repository. The task type is specified as of
      type "add".  Tool (user) parameters are specified for this task via
      the (-A) option.	The tool parameter string that's provided on the
      command line must be enclosed in double quotes. Also, if the tool
      parameter data includes xml data with embedded double quote
      characters, each double quote character must be preceded by the
      backslash escape character.

	   mxtask -c taskname -q queryname -t

      This command creates a new scheduled task of specified task name with
      an associated query (queryname) and tool (toolname) that already
      exists in the Systems Insight Manager repository. The task type is
      specified as of type "add". Tool parameters are specified for this
      task via the (-f) option.	 'filename' specifies the path and name of a
      file that contains the tool (user) parameter data for the specified
      tool.  The tool parameter data contained in this file must be of the
      exact same xml format as stored in the Systems Insight Manager
      repository.

	   mxtask -c taskname -q queryname -t

      This command creates a new scheduled task of specified task name with
      an associated query (queryname) and tool (toolname) that already
      exists in the Systems Insight Manager repository. The task type is
      specified as of type "manual". The Task Owner is also specified on the
      command line via the -o option.  In this example, there are no tool
      (user) parameters required for the tool being specified, thus the (-A)
      nor the (-f) option are not required.

	   mxtask -c taskname -q queryname -t

      This command creates a new scheduled task of specified task name with
      an associated query (queryname) and tool (toolname) that already
      exists in the Systems Insight Manager repository. The task type is
      specified as of type "add". Tool parameters are specified for this
      task via the (-f) option.	 'filename' specifies the path and name of a
      file that contains the tool (user) parameter data for the specified
      tool.  The tool parameter data contained in this file must be of the
      exact same xml format as stored in the Systems Insight Manager
      repository.  The Task Owner is also specified on the command line via
      the -o option along with specifying the task be associated with a
      standard time filter called Business Hours. Note that command line
      option arguments that contain spaces, must be enclosed in double
      quotes.

	   mxtask -c taskname -q queryname -t

      This command creates a new task based off the XML contents of a
      specified external file. All required task configuration information
      is specified in a predefined task specific XML format. See the
      mxtask(4) man page for a detailed description of the task specific XML
      format. The general format is shown below.

	   mxtask -cf taskxmlfile

      General XML format for taskxmlfile:

      <?xml version="1.0" encoding="UTF-8"?>
      <task-list>
	<task name="task name" type="add|remove|manual|schedule" owner="taskowner" runmode="runnow|runatstartup">
	  <toolname>tool name</toolname>
	  <queryname>query name</queryname>
	  <scheduleinfo interval="x" periodic="x" time="x" day="x" date="x"/>
	  <timefilter />
	  <toolparams />
	</task>
      </task-list>


LIMITATIONS

      This command may only be run on the CMS.


AUTHOR

      mxtask was developed by the Hewlett-Packard Company.


SEE ALSO for HP-UX

      mxauth(1M) mxtask(4).


SEE ALSO for Linux

      mxauth(8) mxtask(4).

      * Note: Care must be taken when specifying passwords on the command-
      line. This makes them available in the command history, in the process
      list while executing, and in the audit log if executed as part of a
      task. Be sure to clear your command history, or use alternate methods
      for specifying passwords, e.g. prompt, input file.