SYSTASK Statement: Windows

Executes, lists, or terminates asynchronous tasks.

Valid in: anywhere in a SAS program
Windows specifics: all
Syntax
Syntax Description
Details
See Also

Syntax

SYSTASK COMMAND "operating system command"<WAIT | NOWAIT>
<TASKNAME=taskname> <MNAME=name-variable>
<STATUS=stat-variable>
<SHELL<="shell-command"> > ;
SYSTASK LIST <_ALL_ | taskname> <STATE> <STATVAR>;
SYSTASK KILL taskname <taskname...>;

Syntax Description

COMMAND

executes the operating system command

LIST

lists either a specific active task or all of the active tasks in the system.

KILL

forces the termination of the specified task(s).

operating system command

specifies the name of a Windows command (including any command-specific options). Enclose the command in either single or double quotation marks. If the command options require quotation marks, repeat the quotation marks. For example: 

systask command "find ""my text"" c:\mydir\myfile.sas"
The operating system 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 argument, you can use the WAITFOR statement when necessary to suspend execution of the SAS session until the task has finished.

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 automatically generates a name. If the task name contains a blank character, enclose the task name in quotation marks.

MNAME=name-variable

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-variable

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 operating system command should be executed with the operating system 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 quotation marks.

_ALL_

specifies all active tasks in the system.

STATE

specifies to display the status of the task, which can be Start Failed, Running, or Complete.

STATVAR

specifies to display 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 enables you to execute operating system-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 copy a SAS program, you might use this statement: 
systask command "copy myprog.sas myprog1.sas"
         taskname="copyfile" status=copystat;
The return code from the copy command is saved in the macro variable COPYSTAT.
Note: Windows command output is not written to the SAS log.
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 cause your SAS application to end.
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. To terminate tasks of type Task, use SYSTASK KILL.
SAS/CONNECT Process
Tasks started from SAS/CONNECT with the SIGNON statement or command, and RSUBMIT statement are of type SAS/CONNECT Process. To display SAS/CONNECT processes, use the LISTTASK statement to display the task name, type, and state. To terminate a SAS/CONNECT process, use the KILLTASK statement. For information about SAS/CONNECT processes, see SAS/CONNECT User’s Guide.
Note: The preferred method for displaying any task (not just SAS/CONNECT processes) is to use the LISTTASK statement instead of SYSTASK LIST. The preferred method for ending a task is using the KILLTASK statement in place of SYSTASK KILL.
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 contains a nonzero value. For example, there might be insufficient resources to complete a task, or the SYSTASK statement can contain syntax errors. With the SYSTASK KILL statement, if one or more of the processes cannot be terminated, SYSRC is set to a nonzero 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. 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.
Note: If you are using Microsoft Windows XP or later, the maximum length of the string that you can use at the command prompt is 8191 characters. For more information, see the article about restrictions on string length in command lines available at OS Limitation Workaround.

See Also

WAITFOR Statement: Windows
X Statement: Windows
Copyright © SAS Institute Inc. All Rights Reserved.