RSUBMIT Command and RSUBMIT Statement

RSUBMIT Command and RSUBMIT Statement

Submit statements that are entered on the local host to a remote session for processing.

Local

Syntax
Syntax Description
Username and Password Naming Conventions
Example

Syntax

Syntax Description

The options characterize the environment in which statements are submitted to a remote session for processing.

Details

The RSUBMIT command and the RSUBMIT statement cause SAS programming statements that are entered in the local environment to execute on a remote SAS session. The RSUBMIT command differs from the standard SUBMIT command because statements execute on the remote host. Even though the statements execute in the remote environment, all results and output are available to your local SAS session log and output as they would be if you executed the program in the local SAS session. If the RSUBMIT is synchronous, then all results and output are displayed in your local SAS session. If the RSUBMIT is asynchronous, then you can use the RGET and RDISPLAY commands and statements to retrieve and view the results.

The primary difference between the command and the statement is that the command can be used only from a windowing environment session or within the DM statement. The RSUBMIT statement can be used in any type of SAS session on the local host.

Execute the RSUBMIT command from the command line of the local Program Editor window. Or you can embed the RSUBMIT command within a DM statement, which treats commands as if they were issued from a windowing environment command line. You can also use the KEYS window to assign the RSUBMIT command to a key. See the online help in the SAS windowing environment for details about the KEYS window.

RSUBMITs are processed in either synchronous or asynchronous modes.

synchronous: This means that you do not regain local control until the RSUBMIT has completed. Synchronous processing is the default processing mode.
asynchronous: This allows you to execute statements in a remote SAS session in parallel to your local session. You immediately regain control of your local session to continue with local processing or remote processing to another host.

The autosignon feature of RSUBMIT includes an implicit SIGNON in the absence of a current connection. The RSUBMIT command or statement automatically executes a SIGNON and uses any globally set SAS/CONNECT options along with any connection options that are specified with RSUBMIT. The autosignon first signs on to the remote session and then executes the RSUBMIT. All SIGNON options are also valid for RSUBMIT. Furthermore, a default automatic SIGNOFF occurs at the conclusion of RSUBMIT, but the SIGNOFF can be overridden by specifying PERSIST=YES.

Note: Any connection information that is specified in RSUBMIT for autosignon will be in effect for the entire connection. For example, if you specify WAIT=NO in an RSUBMIT that automatically signs on, then asynchronous RSUBMITs will be the default for the entire connection, but these RSUBMITS can be overridden in individual RSUBMITS. [cautionend]

The RSUBMIT command can be used to execute most types of SAS programs on the remote host.(footnote 1)

The RSUBMIT statement is particularly useful for running SAS/CONNECT from an interactive line-mode session or as a non-interactive job. The RSUBMIT and the ENDRSUBMIT statements enable you to include statements that should be processed by the local host in the same file as statements that are to be processed by the remote host. The statements for the remote host are enclosed between the RSUBMIT and the ENDRSUBMIT statements. All of the other statements in the program are processed by the local host when you execute the program.

The following template can be used to build a file that includes statements for both the remote and local hosts in the same program:

statements for local host
rsubmit;
   statements for remote host
endrsubmit;

Note: The DOWNLOAD and the UPLOAD procedures must be executed by using the RSUBMIT command or the RSUBMIT statement. You cannot execute them by using the SUBMIT command. [cautionend]

The following are optional in the RSUBMIT command/statement. Any combination of these options may be used:

remote-session-id
CONNECTREMOTE=remote-session-id
REMOTE=remote-session-id
PROCESS=remote-session-id

is the name of the session where you want to submit the statements when you have multiple SAS/CONNECT sessions that are active. If you have only one active session, remote-session-id is not needed. When you have multiple remote sessions that are active and you omit this option, the statements are remote-submitted to the current remote session. The current remote session is the one that is specified in the most recently successful CONNECTREMOTE= system option, SIGNON command/statement, RGET command/statement, or RSUBMIT command/statement.

PROCESS= was made an alias for REMOTE= in order to give you the option of differentiating between an RSUBMIT to a remote session on a local host (MP CONNECT) and an RSUBMIT to a remote session on a remote host. REMOTE= and PROCESS= can be used interchangeably.

CONNECTWAIT=YES|NO WAIT=YES|NO

specifies whether this particular RSUBMIT is to be executed synchronously or asynchronously. Synchronous processing indicates that you will wait for the remote processing to complete before regaining control in the local SAS session. WAIT=YES is the default processing technique for RSUBMIT.

In asynchronous processing, when the RSUBMIT begins to execute on the remote host, you regain control of your local SAS session to continue local processing or to use RSUBMIT to other remote sessions.

If the WAIT= option to RSUBMIT is omitted, the value assigned to WAIT=, if any, that is specified on SIGNON is used. Otherwise, the WAIT= global option is queried, and its value is used. The default is to execute synchronously.

The value for the WAIT= option must be either of these:

YES|Y indicates a synchronous RSUBMIT.

NO|N indicates an asynchronous RSUBMIT.

If WAIT=NO is specified, it will also be useful to specify the MACVAR= option. This will allow you to test the status of the current asynchronous RSUBMIT by determining whether it has completed or is still in progress.

When %SYSRPUT executes within a synchronous (WAIT=YES) remote submit, the macro variable is defined to the local SAS session as soon as it executes.

When %SYSRPUT is executed within an asynchronous (WAIT=NO) remote submit, the macro variable is not set in the local session until a synchronization point. This is the default. See %SYSRPUT Statement for more details about synchronization points.

If WAIT=NO is specified and an autosignon is performed, an automatic SIGNOFF will not occur unless PERSIST=NO is also specified.

MACVAR=value

specifies the name of the macro variable to associate with this remote session. If specified in the RSUBMIT command/statement, the MACVAR= option overrides any previous MACVAR= specifications for this remote session. The macro variable is NOT set if the RSUBMIT command fails due to incorrect syntax. Other than this one exception, the macro variable (value) is set at the completion of the RSUBMIT block. It will have one the following values:

0	indicates that the RSUBMIT is complete.
1	indicates that the RSUBMIT failed to execute.
2	indicates that the RSUBMIT is still in progress.

Note: If a synchronous RSUBMIT (WAIT=YES) is issued while an asynchronous RSUBMIT (WAIT=NO) is still in progress, all spooled log and output statements are merged into the local log and output windows. Then the RSUBMIT continues at whatever point it is at as if it were synchronous. That is, the user does not regain control until the RSUBMIT has completed. If you don't want this to happen, use the MACVAR= option in the SIGNON or the RSUBMIT statements so that you can check the progress of RSUBMIT without causing it to execute synchronously. [cautionend]

CONNECTSTATUS=YES|NO STATUS=YES|NO

specifies the setting for the display of the status window for this RSUBMIT only.

The value for this option must be one of the following:

YES|Y status window is displayed for file transfers within this RSUBMIT.

NO|N status window is NOT displayed for file transfers within this RSUBMIT.

If this option is omitted from the RSUBMIT statement, the value (if any) that is specified in the SIGNON statement is used. If not specified in either the RSUBMIT or the SIGNON statement, the CONNECTSTATUS= global option is queried, and its value is used. To display the Transfer Status window is the default. Again, the STATUS option in the RSUBMIT statement only affects transfers for that specific RSUBMIT.

SYSRPUTSYNC=value

allows you to override the default behavior so that you can force the %SYSRPUT macro variables to be set in the local SAS session when executed rather than waiting until the sync point. See the %SYSRPUT statement for more details about sync points.

Note: This option is useful only when an asynchronous (WAIT=NO) remote submit is executed; otherwise, it is ignored. [cautionend]

The value for this option must be one of the following:

YES the user is able to override the default asynchronous remote submit behavior, and forces the macro variables to be defined as soon as %SYSRPUT executes.

NO the macro variables are not set in the local session until a synchronization point.

USER|USERNAME|USERID|UID=username|_PROMPT_

Valid values that can be assigned to USER are:

username: For details about a valid username, see Username and Password Naming Conventions.
_PROMPT_: a secure method, specifies that SAS prompt the user for a valid username.

PASSWORD|PASSWD|PWD|PW=password|_PROMPT_

For the autosignon feature only, specifies the password of the remote host. The platform on which the remote host runs can also affect password naming conventions. For details about password naming conventions imposed by the host, see Communications Access Methods for SAS/CONNECT and SAS/SHARE Software.

Valid values for PASSWORD are:

password: For details about a valid password, see Username and Password Naming Conventions.
_PROMPT_: a secure method, specifies that SAS prompt the user for a valid password.

PERSIST = YES|NO

For the autosignon feature only, specifies whether a signoff is automatically executed after the SIGNON and RSUBMIT have completed.

YES	A connection to the remote session on the local host persists, which means that a signoff is not automatically performed after the SIGNON and RSUBMIT have completed. A YES setting eliminates the need to sign on for subsequent task processing. A persistent connection to the remote session on the local host terminates when you perform an explicit SIGNOFF.
NO	A connection to the remote session does not persist. A signoff is automatically performed after the SIGNON and RSUBMIT have completed. A NO setting requires that you explicitly sign on for subsequent task processing. The default is NO. If WAIT=NO is specified and an autosignon is performed, an automatic SIGNOFF will not occur unless PERSIST=NO is also specified.

SCRIPT=value

For the autosignon feature only, specifies the script file for use during an autosignon by means of RSUBMIT. It may either be a fileref or a quoted, fully-qualified pathname. If the fileref, the filespec, and the SCRIPT= option are specified, the last specification overrides and takes precedence over the others.

When the RSUBMIT command executes, the usual SAS log messages for the remote SAS System display in your local LOG window. When the link has been successfully established, the following message is displayed:

NOTE: REMOTE SIGNON TO remote-session-id 
COMPLETE.

Username and Password Naming Conventions

Each username and password is limited to 256 characters that follow these conventions:

Mixed case is allowed.
A null value, which is no value, that is delimited with quotation marks is allowed.
Quotation marks must surround values that contain one or more spaces.
Quotation marks must surround values that contain one or more special characters.
Quotation marks must surround values that contain one or more quotation marks.

Examples:

user=joe password=Born2run
user=joe password='' # null space specified by contiguous quotation marks
user='joe black' password='Born 2 run'
user='joe?black' password='Born 2 run'
user='apexdomain\joe' password=born2run # Win NT username
user='"crazy joe"' pw=_prompt_;
user=_prompt_;

Example

Suppose you want to use the remote system to execute a SAS program that calculates summary statistics from variables in a very large SAS data set and then download the summary statistics to your local session. You enter the following program in the Program Editor window of your local session:

libname remtdata 'external-file-name'; 
  proc summary data=remtdata.clinic;
     class diagnose;
     var age income visits;
     output out=sumstat 
        n= mean= mage mincome mvisits;
   run;

   proc download data=sumstat out=summary;
   run;

To execute the program on the remote system, enter RSUBMIT on the command line of the Program Editor window. Alternatively, you can press the RSUBMIT function key.

For an example of using compute sevices for MP CONNECT, see Example 6. Compute Services: Using MP CONNECT for Multi-Processing.

FOOTNOTE 1: You should not remote submit windowing procedures (such as SAS/FSP or SAS/AF procedures) or Version 5 full-screen procedures (such as the Version 5 DATASETS procedure).

Chapter Contents
Previous
Next
Top of Page

YES\|Y	indicates a synchronous RSUBMIT.
NO\|N	indicates an asynchronous RSUBMIT.

YES\|Y	status window is displayed for file transfers within this RSUBMIT.
NO\|N	status window is NOT displayed for file transfers within this RSUBMIT.

YES	the user is able to override the default asynchronous remote submit behavior, and forces the macro variables to be defined as soon as %SYSRPUT executes.
NO	the macro variables are not set in the local session until a synchronization point.