lstask command

Description

If you do not specify a task name or ID, this command lists information about all defined tasks. If you do not specify any options, this command lists only the task names.

If this command targets systems, it displays all tasks that run on the specified systems. If the command targets tasks, it displays information about the tasks including on which systems the task runs.

Operands

This command uses a list of tasks as an operand. The list can optionally be preceded by the -T | --task option.

If you specify the -s| --task and -A | --instance options, this command optionally uses a list of systems as an operand. The list can optionally be preceded by the -n | --names option.

Options

-A | --instance instance_id

Displays the status of the specified task or subtask instance, identified by ID. The ID is an integer that is incremented each time the task or subtask is run.

Tips:

• If you omit this option, all task instances are listed.
• You can use the lstask -l command to get a list of all task instance IDs.
• If you specify this option, you must also specify the -s | --status option.

-f | --file {file_name | -}

Retrieves data either from the input file file_name or from input piped from another command.

To retrieve input piped from another command, specify a hyphen (-) instead of a file name (for example, smcli cmd1 | smcli cmd2 -f -). To retrieve input from a file, specify the full path. If the path contains spaces, enclose it in quotation marks.

If you do not specify the -s | --task option, the input data is the list of tasks, specified by name or ID. This list can be a mixture of task names and ID, separated by a comma or end-of-line character.

If you specify the -s | --task option, the input data is the list of systems on which the specified tasks run. This list can be a mixture of system names and IDs, separated by a comma or end-of-line character.

-h | -?

Displays the syntax and a brief description of the command.

Tip: If you specify additional options other than -h | -? | --help, the options are ignored.

--help

Displays detailed information about the command, including the syntax, a description of the command, a description of the options and operands, error codes, and examples.

Tips:

• If you specify additional options other than -h | -? | --help, the options are ignored.
• You can also display detailed help in the form of man pages using the man command_name command.

-i | --ipaddress {ip_address | host_name}[,{ip_address | host_name}...]

Targets one or more tasks that run on the specified systems, identified by IP address or host name. The list can be a mixture of IP addresses and host names, separated by a comma or end-of-line character.

ip_address

The IP address of the system.

Tips:

• You can enter lssys -A IP_address to list the IP address of each discovered system.
• You can use either the IPv4 or IPv6 format to specify the IP address.

host_name

Either the host name or the host name and Domain Name System (DNS) suffix of the system. If the host name contains spaces, enclose it in quotation marks. If it contains a comma, prefix the comma with a backslash (\).

Tips:

• You can enter lssys -A HostName to list the host name of each discovered system.
• The host names are not locale specific.
• A given IP address or host name might resolve multiple systems. For example, both the OperatingSystem and Server instance of a particular system will have the same host name. Use system Object ID (option -n) to target a system uniquely.

Tip: You can use this option only with the -s | --task and -A | --instance options.

-I | --id

Displays the unique task name or task ID string of the targeted task.

Tip: You cannot use this option with the -p | --pipe option.

-l | --long

Displays detailed information about each task with the specified name or ID string.

This option returns these attributes for each task:

• Task title
• Full parent structure
• Task interactive flag
• Task status
• ID and status of each task instance

Tip: Data is not displayed for interactive tasks.

-n | --names {system_oid | system_name}[,{system_oid | system_name}...]

Targets one or more tasks that run on the specified systems, identified by name or ID. The list can be a mixture of system names and IDs, separated by a comma.

system_oid

The unique ID of the system, specified as a hexadecimal value prefixed with 0x (for example, 0x37) or a decimal value (for example, 123).

Tip: Use the lssys -o command to list all system IDs.

system_name

The name of the system. If the system name contains a comma, prefix the comma with a backslash (\).

Tips:

• The system names might not be unique. This command acts on all systems with the specified name. Use the -v | --verbose option to generate a message when this command targets multiple systems with the same name. To target a particular system that has a name that is not unique, identify the system by specifying its unique, hexadecimal ID, or use additional target options to refine the selection.
• Use the lssys command without any options to list all system names.
• The system names are not locale specific.

Tip: You can use this option only with the -s | --task and -A | --instance options.

-N | --groups {group_oid | group_name}[,{group_oid | group_name}...]

Targets one or more tasks that run on members of the specified groups, identified by name or ID. The list can be a mixture of group names and IDs, separated by a comma.

Tips:

• If the same systems are members of more than one group, they are targeted only once.

• To target all systems, specify the "All Systems" group.

group_oid

The unique ID of the group, specified as a hexadecimal value prefixed with 0x (for example, 0x3e7).

Tip: Use the lsgp -o command to list all group IDs.

group_name

The name of the group. If the group name contains spaces, enclose it in quotation marks. If it contains a comma, prefix the comma with a backslash (\) and enclose the name in quotation marks.

Tips:

• Group names are unique.
• Use the lsgp command without any options to list all group names.
• The group names are not locale specific.

Tip: You can use this option only with the -s | --task and -A | --instance options.

-o | --oid

Displays the names and unique IDs for the targeted tasks and for the systems on which the tasks run. IDs are displayed as hexadecimal values, prefixed with 0x (for example, 0x3e). A task job ID of 0x0 indicates an interactive task.

Tip: You cannot use this option with the -p | --pipe option.

-p | --pipe

Displays the unique ID of the task. IDs are displayed as hexadecimal values, prefixed with 0x (for example, 0x3e7). No other information is displayed.

Tip:

• When used alone, this option enables the output to be piped to other smcli commands.
• This option cannot be used with the -o | oid option.

-r | --runnable

Lists the noninteractive tasks that can run on the targeted system.

-s | --status {task_ oid | task_string_id | task_title}

Displays the status for a noninteractive task, specified by name, ID or string ID.

Tips:

• This option cannot be used with the -T | --tasks option.
• An error is displayed if the specified task name or task string ID does not uniquely identify the task.
• An error is displayed if the specified task is not a noninteractive task.

task_oid

The unique ID of the task, specified as a hexadecimal value prefixed with 0x (for example, 0x37).

Tip: You can use the lstask -o -r command to list all task IDs that are valid for the targeted system.

task_id_string

The unique ID string of the task, prefixed with a percent sign (%) (for example, %ServerCfgTask). If the string ID contains a comma, prefix the comma with a backslash (\).

Tip: You can use the lstask -I command to list all task ID strings that are valid for the targeted system.

task_title

The title of the task. The task title must be fully qualified with the parent task (for example, grandparent_task_title/parent_task_title/task_title). If the task name contains a comma, prefix the comma with a backslash (\). Enclose the task title in quotation marks if it contains a space character.

Tips:

• Task names might not be unique. This command acts on all tasks with the specified name. Use the -v | --verbose option to generate a message when this command targets multiple tasks with the same name. To target a task that has a name that is not unique, identify the task by specifying its unique, hexadecimal task ID, or use additional target options to refine the selection.
• Locale-specific task names might not exist for every noninteractive task. The name specified must match the locale being used by the command line interface.
• Use the lstask -r command to list all tasks that are valid for the targeted system.

-t | --type system_type

Targets tasks that run on systems of the specified type.

The system types are organized in a hierarchy in which child subtypes extend parent types. When you specify a parent type (for example, Platforms), its children (in this case, PhysicalPlatforms) are also targeted.

Tips:

• This options is not a targeting option by itself. It must be used with another targeting option, such as -n | --names or -i | --ipaddress.
• You can use this option in conjunction with other targeting options; however, this targeting option acts before all other targeting options.
• Use the lssys -T command to obtain a list of valid system types.
• The system types are not locale specific.

-T | --tasks {task_oid | task_id_string | task_title}[,{task_oid | task_id_string | task_title}...]

Targets one or more tasks, specified by title, unique ID, or ID string.

The list can be a mixture of titles, IDs, and ID strings, separated by a comma. The list is delimited by the end-of-line character when read from a file.

task_oid

The unique ID of the task, specified as a hexadecimal value prefixed with 0x (for example, 0x37).

Tip: You can use the lstask -o -r command to list all task IDs that are valid for the targeted system.

task_id_string

The unique ID string of the task, prefixed with a percent sign (%) (for example, %ServerCfgTask). If the string ID contains a comma, prefix the comma with a backslash (\).

Tip: You can use the lstask -I command to list all task ID strings that are valid for the targeted system.

task_title

The title of the task. The task title must be fully qualified with the parent task (for example, grandparent_task_title/parent_task_title/task_title). If the task name contains a comma, prefix the comma with a backslash (\). Enclose the task title in quotation marks if it contains a space character.

Tips:

• Task names might not be unique. This command acts on all tasks with the specified name. Use the -v | --verbose option to generate a message when this command targets multiple tasks with the same name. To target a task that has a name that is not unique, identify the task by specifying its unique, hexadecimal task ID, or use additional target options to refine the selection.
• Locale-specific task names might not exist for every noninteractive task. The name specified must match the locale being used by the command line interface.
• Use the lstask -r command to list all tasks that are valid for the targeted system.

Tip: This option cannot be used with the -s | --status option.

-v | --verbose

Writes verbose messages to standard output.

If this option is not specified, this command suppresses noncritical messages.

-w | --where "query"

Targets one or more tasks that run on systems that are based on attribute values specified by query.

The query operand is a string, enclosed in quotation marks, that defines a simple SELECT query using the following format:

"attribute_key=value [{AND | OR} attribute_key=value...]"

where attribute_key can be any valid attribute, and value is the value of the attribute. The value must match the expected type for the associated attribute. For example, if the attribute is of type integer, an integer must be specified.

Tips:

• Use logical operators AND or OR to combine attributes.
• Use parentheses to create nested logical constructs.
• The query operand must be enclosed in quotation marks. Do not use double quotation marks in the query.
• If the value contains spaces, enclose it in single quotation marks.
• Only system attributes can be specified. Use the lssys -l command to list the available system attributes.

Exit status

• 0: The operation completed.
• 1: A usage error occurred.
• 2: The command or bundle was not found.
• 3: The command was not performed because either authentication failed or you are not authorized to perform the action.
• 10: The file was not found.
• 20: A specified system is not valid.
• 22: A specified task is not valid.
• 25: A number-formatting error occurred.
• 26: A specified system type is not valid.
• 29: The specified locale is not valid or not supported.
• 51: The task name or ID is not unique or valid.
• 52: The task or subtask is interactive.
• 53: The task ID was not found.

Examples

1. List all defined tasks

   This example illustrates how to list all define tasks.

   smcli lstask

2. List the task ID for a specific task

   This example illustrates how to list the name and ID for the task named Assistant/Configuration.

   smcli lstask -oT "Assistant/Configuration"
   
   Assistant/Configuration, 0x3D

3. List a task with a specific ID

   This example illustrates how to list detailed information about a task with the task ID 0x40.

   smcli lstask -olT 0x40
   
   Power management/ShutDown, 0x40:
      ST.1.name = Power management/ShutDown, 0x40
      ST.1.targeted = true
      ST.1.interactive = false
      ST.1.exec.1.stat = Active
      ST.1.exec.1.stat.client.0 = {Sys1, 0x1A} Pending
      ST.1.exec.1.stat.client.1 = {Sys2, 0x2B} Failed
      ST.1.exec.2.stat = Complete
      ST.1.exec.2.stat.client.0 = {ServerA, 0x5F}, Complete
      ST.1.exec.2.stat.client.1 = {ServerB, 0x6B}, Failed

4. List job status for a subtask

   This example illustrates how to list the job-instance status for the subtask with the ID string %com.ibm.sysmgt.powerapi.ShutDown.

   smcli lstask -os "%com.ibm.sysmgt.powerapi.ShutDown"
   
   Power management/ShutDown, 0x40:
       ST.targeted = true
       ST.interactive = false
       ST.1.exec.1.stat = Active
       ST.1.exec.1.stat.client.0 = {Sys1, 0x1A}, Pending
       ST.1.exec.1.stat.client.1 = {Sys2, 0x2B}, Failed
       ST.1.exec.2.stat = Complete
       ST.1.exec.2.stat.client.0 = (ServerA, 0x5F}, Complete
       ST.1.exec.2.stat.client.1 = (ServerB, 0x6B}, Failed

5. Display the status of a job using its job ID and instance

   This example illustrates how to display the status of job using the job ID 0x15 and instance 1.

   smcli lstask -s 0x15 -A 1
   
   ST.1.exec.1.stat = Active
   ST.1.exec.1.stat.client.0 = system1, Pending 
   ST.1.exec.1.stat.client.1 = system2, Failed

6. Display the status of a job using its job ID string and instance

   This example illustrates how to displays the status of a job with the ID string com.ibm.sysmgt.powerapi.ShutDown/com.ibm.sysmgt.powerapi.PowerOn and instance 1. Notice that the task ID and subtask ID strings match.

   smcli lstask -s %com.ibm.sysmgt.powerapi.PowerOn/com.ibm.sysmgt.powerapi.PowerOn
   -A 1
   
   ST.1.exec.1.stat = Active
   ST.1.exec.1.stat.client.0 = system1, Pending 
   ST.1.exec.1.stat.client.1 = system2, Failed

7. Display the status of a job, using its job ID string and execution ID, that is running on a specific system

   This example illustrates how to display the status of a job with the job ID 0x15, job instance ID 1, running on the system named system1.

   smcli lstask -s 0x15 -A 1 -n system1
   
   Sys1, Pending