SYSTASK Statement: UNIX

Executes asynchronous tasks.

Valid in:	anywhere
UNIX specifics:	all

Syntax

Details

Syntax

SYSTASK COMMAND “operating-environment-command” <WAIT | NOWAIT>
<TASKNAME=taskname> <MNAME=name-variable> <STATUS=status-variable>
<SHELL<=“shell-command”> > <CLEANUP> ;

SYSTASK LIST <_ALL_ | taskname> <STATE> <STATVAR> ;

SYSTASK KILL taskname <taskname...> ;

Required Arguments

COMMAND: executes the operating–environment-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 tasks.

operating-environment-command

specifies the name of a UNIX command (including any command-specific options) or the name of an X window system application. Enclose the command in either single or double quotation marks. If the command-specific options require quotation marks, repeat them for each option. For example:

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

Note: If the command name is a shell alias, or if you use the shell special characters tilde (~) and asterisk (*) in a pathname in a command, you need to specify the SHELL option so that the shell will process the alias or special characters:

SYSTASK COMMAND "mv ~usr/file.txt /tmp/file.txt" shell;

In this example, by using the SHELL option, the ~usr path is expanded on execution and is not executed directly.

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

Tip

If using a shell alias results in an error even though the SHELL option is used, then the shell is not processing your shell initialization files. Use the actual SHELL command instead of the SHELL alias.

Optional Arguments

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 start with the NOWAIT option, you can use the WAITFOR statement when necessary to suspend execution of the SAS session until the task has finished. For more information, see WAITFOR Statement: UNIX.

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 it in quotation marks.

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-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=status-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-environment-command should be executed with the operating system shell command. The shell will expand shell special characters that are contained in the operating-environment-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.

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 LISTTASK output when the task completes. Once the task is removed, you can reuse the task name without issuing the WAITFOR statement.

If you have long-running jobs that use the SYSTASK command multiple times, use the WAITFOR statement or the CLEANUP option in the SYSTASK command to clear the memory. The WAITFOR statement releases memory by removing the information for all completed processes that were started by the SYSTASK command. The CLEANUP option clears memory when a specific job completes, and releases memory for further use. If you use the WAITFOR statement after a job has completed, the statement is ineffective because the job has already been cleaned up by the CLEANUP option.

Details

The SYSTASK statement enables you to execute host-specific commands from within your SAS session or application. Unlike the X statement, the SYSTASK statement 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 return code from the cp command is saved in the macro variable COPYSTS1.

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

Because the syntax between UNIX and a PC can be different, converting PC SAS jobs to run on UNIX might result in an error in the conversion process. For example, entering the following command results in an error:

systask command "md directory-name" taskname="mytask";

An error occurs because md is a “make directory” command on a PC, but has no meaning in UNIX. In the conversion process, md becomes mkdir. You must use the SHELL option in the SYSTASK statement because mkdir is built into the UNIX shell, and it is not a separate command as it is on a PC.

SAS writes the error message to the 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 asynchronous processes that can be started from SAS:

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 SIGNON statement or command and RSUBMIT statement are of type SAS/CONNECT Process. To display SAS/CONNECT processes, use the LISTTASK statement to displays the task name, type, and state. To terminate a SAS/CONNECT process, use the KILLTASK statement. For information about SAS/CONNECT processes, see the 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 instead 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 will contain a nonzero value. For example, there might be insufficient resources to complete a task or the SYSTASK statement might contain syntax errors. With the SYSTASK KILL statement, if one or more of the processes cannot be killed, 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. If a task terminates abnormally, then its status variable will be set to –1. For more information about the status variables, see WAITFOR Statement: UNIX.

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

SYSTASK Statement: UNIX

Syntax

Required Arguments

Optional Arguments

Details

See Also