Chapter Contents

Previous

Next

SYSTASK

Alias:	LISTTASK is an alias for SYSTASK LIST
Valid:	anywhere
UNIX specifics:	all

COMMAND

executes the host-command.

LIST

lists either a specific active task or all of the active tasks in the system. A task is active if it is running or if it has completed and has not been waited for using the WAITFOR statement.

KILL

forces the termination of the specified task(s).

host-command

specifies the name of a UNIX command (including any command-specific options) or the name of an X Windows or Motif application. Enclose the command in either single or double quotes. If the command options require quotes, repeat the quotes. For example:

SYSTASK COMMAND "xdialog -m ""There was an error."" -t ""Error"" -o";

Note:   The host-command that you specify cannot require input from the keyboard.  

WAIT | NOWAIT

determines whether SYSTASK COMMAND suspends execution of the current SAS session until the task has completed. NOWAIT is the default. For tasks that are started with the NOWAIT option, you can use the WAITFOR statement when necessary to suspend execution of the SAS session until the task has finished. See WAITFOR.

TASKNAME=taskname

specifies a name that identifies the task. Task names must be unique among all active tasks. A task is active if it is running or if it has completed and has not been waited for using the WAITFOR statement. Duplicate task names generate an error in the SAS log. If you do not specify a task name, SYSTASK will automatically generate a name. If the task name contains a blank character, enclose the task name in quotes.

Task names cannot be reused, even if the task has completed, unless you either issue the WAITFOR statement for the task or you specify the CLEANUP option.

MNAME=name-var

specifies a macro variable in which you want SYSTASK to store the task name that it automatically generated for the task. If you specify both the TASKNAME option and the MNAME option, SYSTASK copies the name that you specified with TASKNAME into the variable that you specified with MNAME.

STATUS=stat-var

specifies a macro variable in which you want SYSTASK to store the status of the task. Status variable names must be unique among all active tasks.

SHELL<="shell-command">

specifies that the host-command should be executed with the host shell command. If you specify a shell-command, SYSTASK uses the shell command that you specify to invoke the shell; otherwise, SYSTASK uses the default shell. Enclose the shell command in quotes.

Note:   The SHELL option assumes that the shell command that you specify uses the -i option to pass statements. Usually, your shell command will be sh, csh, ksh, or bash.   

CLEANUP

specifies that the task should be removed from the SYSTASK LIST output when the task completes. You can then reuse the task name without issuing the WAITFOR statement.

_ALL_

specifies all active tasks in the system.

STATE

displays the status of the task, which can be Start Failed, Running, or Complete.

STATVAR

displays the status variable associated with the task. The status variable is the variable that you assigned with the STATUS option in the SYSTASK COMMAND statement.

Details

SYSTASK allows you to execute host-specific commands from within your SAS session or application. Unlike the X statement, SYSTASK runs these commands as asynchronous tasks, which means that these tasks execute independently of all other tasks that are currently running. Asynchronous tasks run in the background, so you can perform additional tasks while the asynchronous task is still running.

For example, to start a new shell and execute the UNIX cp command in that shell, you might use this statement:

systask command "cp /tmp/sas* ~/archive/" taskname="copyjob1" 
                 status=copysts1 shell;

The output from the command is displayed in the SAS log.

Note:   Program steps that follow the SYSTASK statements in SAS applications usually depend on the successful execution of the SYSTASK statements. Therefore, syntax errors in some SYSTASK statements will cause your SAS application to abort.  

There are two types of tasks that can be run with SYSTASK:

Task

All tasks started with SYSTASK COMMAND are of type Task. For these tasks, if you do not specify STATVAR or STATE, then SYSTASK LIST displays the task name, type, and state, and the name of the status macro variable. You can use SYSTASK KILL to kill only tasks of type Task.

SAS/Connect Process

Tasks started from SAS/Connect with the RSUBMIT statement are of type SAS/Connect Process. For SAS/Connect processes, SYSTASK LIST displays the task name, type, and state. You cannot use SYSTASK KILL to kill a SAS/Connect process. For information on starting SAS/Connect processes with RSUBMIT, refer to SAS/CONNECT User's Guide.

The SYSRC macro variable contains the return code for the SYSTASK statement. The status variable that you specify with the STATUS option contains the return code of the process started with SYSTASK COMMAND. To ensure that a task executes successfully, you should monitor both the status of the SYSTASK statement and the status of the process that is started by the SYSTASK statement.

If a SYSTASK statement cannot execute successfully, the SYSRC macro variable will contain a non-zero value. For example, there may be insufficient resources to complete a task or the SYSTASK statement may contain syntax errors. With the SYSTASK KILL statement, if one or more of the processes cannot be killed, SYSRC is set to a non-zero value.

When a task is started, its status variable is set to NULL. You can use the status variables for each task to determine which tasks failed to complete. Any task whose status variable is NULL did not complete execution. If a task terminates abnormally, then its status variable will be set to -1. See WAITFOR for more information about the status variables.

Unlike the X statement, you cannot use the SYSTASK statement to start a new interactive session.

See Also

• WAITFOR

• X

• Executing Operating System Commands from Your SAS Session

Chapter Contents

Previous

Next

Top of Page

Copyright 1999 by SAS Institute Inc., Cary, NC, USA. All rights reserved.