Previous Page | Next Page

Syntax for the RSUBMIT Statement and Command

RSUBMIT Statement and Command


Marks the beginning of a block of statements that a client session submits to a server session for execution.
Valid In: client session
Syntax
Options
Difference between SUBMIT and RSUBMIT
Difference between the RSUBMIT Statement and Command
Difference between Synchronous and Asynchronous RSUBMITs
Executing Statements in the RSUBMIT Block
RSUBMIT and ENDRSUBMIT Parsing
User ID and Password Naming Conventions

Syntax

RSUBMIT <options>;
ENDRSUBMIT <CANCEL>;
RDISPLAY <CONNECTREMOTE=><server-ID;>
RGET <CONNECTREMOTE=><server-ID>;
%SYSRPUT macro-variable=value;
%SYSLPUT macro-variable=value </REMOTE=server-ID>;
WAITFOR <_ANY_ | _ALL_> task1...taskn <TIMEOUT=seconds>;
LISTTASK <_ALL_ | task>;
KILLTASK <_ALL_ | task1...taskn>;

Task Statement
Mark the end of a block of statements that a client session submits to a server session for execution ENDRSUBMIT
Create a Log window to display the lines from the Log and Output window to list the output generated from the execution of the statement within an asynchronous RSUBMIT block RDISPLAY
Retrieve the log and output that are created by an asynchronous RSUBMIT and merge them into the Log and Output windows of the client session RGET
Assign a value from the server session to a macro varible in the client session %SYSRPUT
Create a macro variable in the server session %SYSLPUT
Cause the client session to wait for the completion of one or more tasks (asynchronous RSUBMITs) that are in process WAITFOR
List all active connections or tasks and identify the execution status of each connection or task LISTTASK
For an asynchronous tasks, force one or more active tasks or server sessions to terminate immediately KILLTASK


Options

AUTHDOMAIN=auth-domain | "auth-domain"

specifies the name of an authentication domain, which is a metadata object that manages the credentials (user ID and password) that are associated with the specified domain. Specifying the authentication domain is a convenient way to obtain the metadata-based user credentials rather than having to explicitly supply them during server sign-on.

An administrator can define an authentication domain by using the User Manager in SAS Management Console.

Examples: 

authdomain=DefaultAuth
authdomain="SAS/CONNECT Auth Domain"
Restriction: Use the AUTHDOMAIN= option only when the AUTOSIGNON system option has been specified and a sign-on has not yet occurred.
Requirement: The authentication domain and the associated credentials must be stored in a metadata repository, and the metadata server must be running in order to resolve the metadata object specification.
Requirement: Enclose domain names that are not valid SAS names in double or single quotation marks.
Interaction: If you specify AUTHDOMAIN=, do not also specify USERNAME= and PASSWORD=. Otherwise, sign-on is canceled.
See Also: For complete details about creating and using authentication domains, see the SAS Intelligence Platform: Security Administration Guide.
See Also: SAS Management Console User's Guide and SAS Management Console online Help
CMACVAR=value

specifies the macro variable to associate with the current RSUBMIT block. Specifying CMACVAR= in an individual RSUBMIT restricts the macro variable to that RSUBMIT block. If multiple asynchronous RSUBMIT statements execute in the same server session, and each RSUBMIT contains a CMACVAR= specification, each macro variable will be restricted to the respective RSUBMIT block. The macro variable is set at the completion of the RSUBMIT block.

Note:   If RSUBMIT fails because of incorrect syntax, the macro variable is not set.   [cautionend]

Here are the values for the CMACVAR= option:

0

indicates that the RSUBMIT is complete.

1

indicates that the RSUBMIT failed to execute.

2

indicates that the RSUBMIT is still in progress.

Alias: MACVAR=
Interaction: If a synchronous RSUBMIT is specified while an asynchronous RSUBMIT is still in progress, all spooled log and output statements are merged into the client Log and Output windows. The asynchronous RSUBMIT will resume execution as if it were synchronous. Control returns to the client session after the synchronous RSUBMIT has completed.

To prevent a conversion from asynchronous to synchronous behavior, ensure that the CMACVAR= option is associated with a specific RSUBMIT block.
Interaction: The CMACVAR= option in the current RSUBMIT block can override the CMACVAR= that is specified at sign-on.
Featured in: Example 3: Using the CMACVAR= Option with MP CONNECT
See Also: CMACVAR= option in the SIGNON statement
CPERSIST=

CONNECTPERSIST=YES|NO

specifies whether a connection persists (continues) or is automatically terminated after an RSUBMIT has completed. A connection results from a sign-on to the server session.

Here are the values for this option:

YES|Y

specifies that a connection to the server session continues. A sign-off is not automatically performed after the RSUBMIT has completed. CONNECTPERSIST maintains the connection for subsequent RSUBMIT statements.

NO|N

specifies that a connection to the server session terminates. A sign-off is automatically performed after the RSUBMIT has completed. Setting NO requires that you sign on to the server session again before you perform the next RSUBMIT.

Alias: CPERSIST=, PERSIST=
Default: YES
Interaction: If the CONNECTPERSIST system option is also specified, the CONNECTPERSIST= option that is specified in the RSUBMIT statement takes precedence over the system option.
See Also: CONNECTPERSIST System Option
CONNECTREMOTE=server-ID
server-ID

specifies the name of the server session that the RSUBMIT statements are executed in. If only one session is active, server-ID can be omitted. If multiple server sessions are active, omitting this option causes the program statements to be run in the most recently accessed server session. The current server session is identified by the value that is assigned to the CONNECTREMOTE system option.

You can specify server-ID using different formats:

[1] process-name

process-name is a descriptive name that you assign to the server session on a multi-processor computer when the SASCMD= option is used.

[2] computer-name

computer-name is the name of a computer that is running a Telnet daemon or that is running a spawner that is not specified as a service. If the computer name is longer than eight characters, a SAS macro variable name should be used.

[3] computer-name.port-name

computer-name is the name of a server, and port-name is the name of the port that the spawner service runs on. If the computer name is longer than eight characters, assign the computer name to a SAS macro variable and use the macro variable name as the server ID.

[4] computer-name.port-number

computer-name is the name of a server, and port-number is the port that the spawner service runs on.

CAUTION:
Specifying computer-name.port-number for the server ID will fail under these conditions:

  • when used in a WAITFOR statement that is used to wait for the completion of an asynchronous RSUBMIT.

    Instead, use a one-level name, such as the computer-with-port.

  • when used in a LIBNAME statement.

    Instead, use a one-level name or a two-level name, such as computer-name._ _port-number.

  [cautionend]
[5] computer-with-port

computer-with-port is a macro variable that contains the name of a server and the port that the spawner service runs on, separated by one or more spaces. This specification is appropriate in cases where the server-ID must be specified as a one-level name.

[6] computer-name._ _port-number

computer-name is the name of a server and port-number is the port that the spawner service runs on. This format can be used to specify the server-ID value for the SERVER= option in a LIBNAME statement.

These examples of specifying server-ID correspond to the preceding formats. 

1  rsubmit emp1 sascmd="!sascmd";

2  %let sashost=hrmach1.dorg.com;
   rsubmit sashost;

3  %let sashost=hrmach1.dorg.com;
   rsubmit sashost.sasport;

4  rsubmit hrmach1.2267;

5  %let sashost=hrmach1.dorg.com 2667;
   rsubmit sashost;

6  rsubmit hrmach1._ _2267;
Alias: CREMOTE=, PROCESS=, REMOTE=
See Also: CONNECTREMOTE= System Option
CONNECTSTATUS=YES|NO

specifies whether the Transfer Status window is displayed for file transfers within the current RSUBMIT.

Here are the values for this option:

YES|Y

specifies that the Transfer Status window is displayed for file transfers within the current RSUBMIT.

NO|N

specifies that the Transfer Status window is not displayed for file transfers within the current RSUBMIT.

Alias: CSTATUS=, STATUS=
Default: YES for synchronous RSUBMITs. NO for asynchronous RSUBMITs.
Interaction: If the CONNECTSTATUS= option is omitted from the RSUBMIT statement, its value is resolved as follows:

1

If the CONNECTSTATUS= option is specified in the SIGNON statement, the value for the CONNECTSTATUS= option in the SIGNON statement is used.

2

If the CONNECTSTATUS system option is specified, the value for the CONNECTSTATUS system option is used.

3

Otherwise, the default behavior occurs. The default for a synchronous RSUBMIT is YES, which displays the Transfer Status window. The default for an asynchronous RSUBMIT is NO, which does not display the Transfer Status window.
See Also: Transfer Status Window
See Also: CONNECTSTATUS System Option
CONNECTWAIT=YES|NO

specifies whether RSUBMIT blocks execute synchronously or asynchronously. Synchronous RSUBMIT statements are executed sequentially. An RSUBMIT must be completed in the server session before control is returned to the client session.

For asynchronous RSUBMIT statements, you can execute tasks in multiple server sessions in parallel. Control is returned to the client session immediately after an RSUBMIT begins execution to allow continued execution in the client session and in other server sessions.

Here are the values for this option:

YES|Y

specifies that the RSUBMIT blocks execute synchronously.

NO|N

specifies that the RSUBMIT blocks execute asynchronously.

Alias: CWAIT=, WAIT=
Default: YES
Interaction: If the CONNECTWAIT= option in RSUBMIT is omitted, the value for the CONNECTWAIT= option is resolved as follows:

1

If the CONNECTWAIT= option is specified in the SIGNON statement (or if the AUTOSIGNON system option has been specified because a sign-on has not yet occurred), the value for the CONNECTSTATUS= option in the SIGNON statement is used.

2

If the CONNECTWAIT system option is specified, the value for the CONNECTWAIT system option is used.

3

If the CONNECTWAIT= option is not specified in the SIGNON statement or if the CONNECTWAIT system option is not specified, the default for the CONNECTWAIT= option is used. The default is YES, which is to execute synchronously.
Interaction: If the AUTOSIGNON system option has been specified and a sign-on has not yet occurred, any options that are specified in RSUBMIT are in effect for the entire connection. For example, if you specify CONNECTWAIT=NO in RSUBMIT and the AUTOSIGNON system has been specified, asynchronous RSUBMIT statements will be the default for the entire connection. However, the CONNECTWAIT= value can be overridden in individual RSUBMIT blocks. A connection is terminated using the SIGNOFF statement.
Interaction: If CONNECTWAIT=NO is specified, you might also specify the CMACVAR= option. CMACVAR= enables you to programmatically test the status of the current asynchronous RSUBMIT to find out whether the task has completed or is still in progress.

When %SYSRPUT is executed within a synchronous RSUBMIT, the macro variable is defined in the client session as soon as it executes.

When %SYSRPUT is executed within an asynchronous RSUBMIT, the macro variable is defined in the client session when a synchronization point is encountered. To override this behavior, use the SYSRPUTSYNC system option.

Note:   If CONNECTWAIT=NO is specified and the AUTOSIGNON system option also has been specified (because a sign-on has not yet occurred), an automatic sign-off will occur only if CONNECTPERSIST=NO is also specified.   [cautionend]
See Also: SYSRPUTSYNC System Option
See Also: Synchronization Points
See Also: CONNECTWAIT System Option
Featured In: Example 5: Using MP CONNECT and the WAITFOR Statement
CREMOTE=

CSCRIPT=file-specification

specifies the script file to use in an RSUBMIT when the AUTOSIGNON system option has been specified and a sign-on has not yet occurred.

file-specification

specifies the location of the script file.

Here are the values for file-specification:

"filename"

is the physical location of the script file in the current working directory. Enclose the filename in double or single quotation marks.

fileref

is a SAS name that is associated with the physical location of the script file. A previously executed FILENAME statement must define the fileref.

If the fileref that you define for the script is the default fileref RLINK, you can omit this specification from RSUBMIT.

"fully-qualified-filename"

is the full path to the script file. Enclose the fully-qualified filename in double or single quotation marks.

"SASSCRIPT-specification"

is the physical location of the script file in the directory that is specified by the SASSCRIPT system option.

Alias: SCRIPT=
Restriction: Use the CSCRIPT= option only when the AUTOSIGNON system option has been specified and a sign-on has not yet occurred.
Interaction: If multiple CSCRIPT= options are specified, the last specification takes precedence.
Interaction: When you use the CSCRIPT= option, do not also use the NOCSCRIPT option. If you use NOCSCRIPT and CSCRIPT=, sign-on is canceled.
See Also: NOCSCRIPT= option
See Also: AUTOSIGNON System Option
See Also: SASSCRIPT= System Option
See Also: FILENAME statement in SAS Language Reference: Dictionary and the companion that is appropriate for your operating environment.
CSTATUS=

CSYSRPUTSYNC=YES|NO

specifies whether to synchronize the client session's macro variables when the client session receives results from the server session or when a synchronization point is encountered. Macro variables are updated in the client session using the %SYSRPUT macro in an asynchronous RSUBMIT.

Note:   The %SYSRPUT macro is executed in the server session.  [cautionend]

Here are the values for this option:

YES|Y

specifies that the client session's macro variables will be updated when the client session receives the results of the server session's execution of the %SYSRPUT macro. The results are delivered in the form of a packet. Specifying YES does not mean that the client's macro variables will be updated immediately after the server session's execution of the %SYSRPUT macro variable. YES means that the client's macro variables will be updated when the client receives the packet from the server session. Therefore, the exact time at which the client session's macro variables are updated will depend on the availability of the client session to receive the packet from the server session. If the client session is busy, the server session must wait until the client session is ready to receive the packet.

NO|N

specifies that the client session's macro variables will be updated when a synchronization point is encountered. This is the default.

Default: NO
Alias: SYSRPUTSYNC=
Interaction: If the SYSRPUTSYNC system option is specified, the CSYSRPUTSYNC= option in RSUBMIT takes precedence over the system option.
Interaction: If the SYSRPUTSYNC system option is specified and the CSYSRPUTSYNC= option in RSUBMIT is not specified, the system option will apply to the RSUBMIT statement.
Interaction: Changing the value assigned to the SYRPUTSYNC= option between consecutive asynchronous RSUBMIT statements causes unpredictable results. You are advised not to change the value between asynchronous RSUBMIT statements.
See Also: Synchronization Points
See Also: SYSRPUTSYNC System Option
Featured In: For an example of how to prevent SYSRPUTSYNC= option overrides, see Example 8: Forcing Macro Variables to Be Defined When %SYSRPUT Executes.
CWAIT=

INHERITLIB=(client-libref1 <=server-libref1> ... client-librefn <=server-librefn>)

enables libraries that are defined in the client session to be inherited by the server session for read and write access. As an option, each client libref can be associated with a libref that is named differently in the server session. If the server libref is omitted, the client libref name is used in the server session. A space is used to separate each libref pair in a series, which is enclosed in parenthesis.

Note:   Because the SAS WORK library cannot be reassigned in any SAS session, you cannot reassign the SAS WORK library in the server session either.  [cautionend]

This example shows that the libref named LOCAL in the client session is inherited for use in the server session. 
rsubmit job1 inheritlib=(local work=remote);
   libname local list;
   libname remote list;
   data local.a; 
   x=1; 
   run;
endrsubmit;
Interaction: If you use the INHERITLIB= option and the SASCMD= option when signing on to a server session, the server session attempts to access the client library directly rather than to inherit access to the library via the client session. If the client session and the server session attempt to access the same file simultaneously, only one session is granted exclusive access to the file. The other session's access to the file is denied.

SAS/CONNECT does not support concurrent multi-user access to the same file. This functionality is supported by SAS/SHARE.
See Also: SASCMD=
See Also: SAS/SHARE User's Guide
LOG=KEEP | PURGE |file-specification
OUTPUT=KEEP | PURGE |file-specification

directs the SAS log or the SAS output that is generated by the current server session to the backing store or to the specified file. A backing store is a SAS utility file that is written to the client SAS WORK directory.

Here are the values for these options:

KEEP

spools log or output lines, as applicable, to the backing store or to the computer on which the client session is running. The log or output lines can be retrieved using the RGET, RDISPLAY, RSUBMIT CONNECTWAIT=YES, or SIGNOFF statements. This is the default.

PURGE

deletes all the log or output lines that are generated by the current server session. PURGE is used to save disk resources. Use PURGE if you anticipate a large volume of log data or output data to the backing store that you do not want to keep, and you want to preserve disk space.

file-specification

specifies a file as the destination for the log or output lines. The file is opened for output at the beginning of the asynchronous RSUBMIT and is closed at the end of the asynchronous RSUBMIT. After the current RSUBMIT has completed, subsequent RSUBMIT log or output lines can be appended to the preceding RSUBMIT destination file using the LOG= or OUTPUT= options to specify the appropriate filename.

Note:   Directing output to the same file for multiple concurrent asynchronous RSUBMIT statements is not recommended.  [cautionend]

Here are the values for this option:

"filename"

is the physical location of the SAS log file or the SAS output file. Enclose the filename in double or single quotation marks.

fileref

is a SAS name that is associated with the physical location of the SAS log file or the SAS output file.

Note:   Use the MOD option in the FILENAME statement to open the referenced file for an append. The MOD option is an external I/O statement option.  [cautionend]

Default: KEEP
Restriction: Use the LOG= and the OUTPUT= options only when executing an asynchronous RSUBMIT. Otherwise, this message is displayed: 
WARNING: LOG=/OUTPUT= options invalid with synchronous rsubmit. 
Options will be ignored.
Interaction: If you direct the log or output lines to a file and then use RGET or RDISPLAY to retrieve the contents of an empty backing store, this message is displayed: 
WARNING: The LOG option was used to file log lines for the current RSUBMIT.
There are no log lines for RGET to process.
CAUTION:
Do not simultaneously use an asynchronous RSUBMIT and the PROC PRINTTO statement in order to redirect output.

Results are unpredictable when you use a LOG= or an OUTPUT= option to redirect output in an asynchronous RSUBMIT and then use the PROC PRINTTO statement in the client session.  [cautionend]

If you use the RSUBMIT CONNECTWAIT=NO and the PROC PRINTTO statements, you might expect the PROC PRINTTO statement to cause data from the server session to be written to the file that is specified in the PROC PRINTTO statement. If this PROC PRINTO behavior occurs, the LOG= or the OUTPUT= option in the RSUBMIT statement is ignored, and no data is written to the backing store or to the specified file.

However, because the RSUBMIT CONNECTWAIT=NO and the PROC PRINTTO statements execute simultaneously, predicting which operation will complete first is impossible. The timing of the completions of these tasks determines whether the results are written to the RSUBMIT log or to the PROC PRINTTO log.
See Also: CONNECTWAIT= option
See Also: CONNECTWAIT System Option
See Also: MOD option in the FILENAME statement, which varies by operating environment. See the SAS Companion that is appropriate for your operating environment.
MACVAR=

NOCSCRIPT

specifies that no script file should be used for sign-on. NOCSCRIPT accelerates sign-on and conserves memory resources.

Alias: NOSCRIPT
Restriction: Use the NOCSCRIPT option only when the AUTOSIGNON system option has been specified and a sign-on has not yet occurred.
Interaction: When you use NOCSCRIPT, do not also use SASCMD=, SERVER=, or CSCRIPT=. If you use NOCSCRIPT with SASCMD=, NOCSCRIPT is ignored. If you use NOCSCRIPT with SERVER= or CSCRIPT=, sign-on is canceled.
See Also: AUTOSIGNON System Option
See Also: CSCRIPT= option
NOSCRIPT

NOTIFY=YES | NO | "e-mail-address"

specifies whether to notify the user that an asynchronous RSUBMIT has completed. The notification can be in the form of a message window or an e-mail message. The NOTIFY option is enabled only at sign-on and remains in effect for the duration of the server session.

Here are the values for this option:

YES|Y

enables notification via a message window. Here is the format of the default message: 

Asynchronous task TASK1 has completed.

TASK1 is the server ID.

The message window does not interfere with any other task executions in progress. To acknowledge the message and to close the window, click OK.

NO|N

disables notification. This is the default.

"e-mail-address"

enables notification via an e-mail message, and specifies the e-mail address of the recipient for the notification. E-mail addresses are limited to a maximum of 256 characters. Enclose the e-mail address in double or single quotation marks.

The message includes information about the total time that was used for the asynchronous RSUBMIT. If the LOG= and OUTPUT= options are also specified in an asynchronous RSUBMIT statement, the e-mail message identifies the locations of the log file and output file.

Here is an example of enabling notification for an asynchronous RSUBMIT: 

options autosignon sascmd="!sascmd";
rsubmit process1 wait=no notify=yes;
   %put should get notification window;
endrsubmit;

To disable notification, you must sign off the server session and then sign on to the server session again, and either omit the NOTIFY= option or specify NOTIFY=NO in the RSUBMIT statement.

Here is an example of disabling notification for the next asynchronous RSUBMIT: 

signoff process1;
options autosignon sascmd="!sascmd";
rsubmit process1 wait=no notify=no;
   code-to-be-executed-in-server-session
endrsubmit;
Default: NO
Restriction: Notification occurs only for asynchronous RSUBMIT statements.

If NOTIFY=YES or NOTIFY="e-mail-address" is specified in a synchronous RSUBMIT, notification fails. Notification is valid only for an asynchronous RSUBMIT.
Restriction: Use the NOTIFY= option in RSUBMIT only when the AUTOSIGNON system option has been specified (because a sign-on has not yet occurred).

If NOTIFY= is specified in RSUBMIT when the AUTOSIGNON system option has been specified, but a sign-on has previously occurred, NOTIFY= has no effect.

Interaction: When you specify the NOTIFY="e-mail-address" option, you can also specify the SUBJECT="subject-title" option.
Interaction: If NOTIFY=YES and the NOTERMINAL system option has been specified, the request for notification is ignored. This message is displayed: 
WARNING: The NOTIFY option is valid only if a TERMINAL is attached 
to this SAS session. Option will be ignored.

However, notification can be directed to an e-mail address, regardless of whether the TERMINAL or NOTERMINAL system option has been specified.
Interaction: If NOTIFY="e-mail address" is specified, but the e-mail message cannot be sent, notification will occur in the form of a message window, which is the action that occurs when NOTIFY=YES.

Note:   This behavior assumes that the NOTERMINAL system option has not been specified.  [cautionend]
Interaction: If NOTIFY="e-mail address" is specified, the SAS system and the operating environment that the SAS system runs under must be configured to support e-mail. Without appropriate configuration, your attempt to specify notification via e-mail might fail. Contact your system administrator for details.
Interaction: Notification fails if NOTIFY=YES or NOTIFY="e-mail address" and you specify statements or commands (such as RGET or SIGNOFF) during the asynchronous RSUBMIT that change execution from asynchronous to synchronous mode.
Interaction: This message is displayed when the NOTIFY= option is specified in the RSUBMIT statement: 
WARNING: The NOTIFY option is applied only during SIGNON, but remains 
in effect for the entire connection until SIGNOFF.
This message is also displayed for an RSUBMIT for which an automatic sign-on has occurred.
See Also: CONNECTWAIT=NO option
See Also: AUTOSIGNON System Option
See Also: LOG= and OUTPUT= options
See Also: SUBJECT= option
See Also: EMAILHOST, EMAILPORT, and EMAILSY system options in SAS Language Reference: Dictionary
PERSIST=

PROCESS=

REMOTE=

SASCMD="SAS-command" | "!sascmd" | "!sascmdv" | "host-command-file"

signs on to the server session on the same symmetric multiprocessing (SMP) computer that the client session is running on. This option is most useful when client and server sessions run on SMP hardware.

"SAS command"

  • For OpenVMS, UNIX, and Windows: specifies the SAS command that is used to sign on to a server session.

    Here is a typical example: 

    sascmd="sas"
    As another example, commands that contain spaces must be enclosed in double quotation marks. 
    sascmd='"c:\Program Files\SAS\SAS System\9.2\sas.exe"';

  • For z/OS: specifies a colon that is followed by any SAS invocation options.

    Here is an example: 

    sascmd=":ls=256"
!sascmd

For OpenVMS, UNIX, and Windows, signs on to a server session by using the same command that was used to start the client session.

!sascmdv

For OpenVMS, UNIX, and Windows, signs on to a server session by using the same command that was used to start the client session and writes the SAS invocation to the SAS log.

"host-command-file"

In order to execute additional commands before SAS is invoked, you can write a command file that is specific to your operating environment. Here are the filename extensions according to operating environment: Windows filenames use the .bat and .cmd extensions. UNIX extensions include .sh , .csh , and .ksh . OpenVMS uses the .com extension.

Note:   The SASCMD= option does not support z/OS command files.  [cautionend]

The TCP/IP access method adds options, such as -DMR, to the server session's SAS command.

For Windows, the TCP/IP access method also appends these options:

  • -COMAMID TCP

  • -ICON

  • -NOSPLASH

  • -NOTERMINAL

For all operating environments, you can also specify the NOSYNTAXCHECK option in the SAS invocation for the non-interactive server session. For details, see Starting SAS and Using Syntax Checking.

Restriction: For z/OS, a command file cannot be used. Therefore, use a semicolon followed by options for the server's SAS invocation.
Interaction: If the SASCMD= system option is already specified, the SASCMD= option that is specified in RSUBMIT takes precedence over the system option.
Interaction: When you use SASCMD=, do not also use NOCSCRIPT. Otherwise, NOCSCRIPT is ignored.
Requirement: SAS commands that contain spaces must be enclosed in double or single quotation marks.
See Also: SASCMD= System Option
See Also: SYNTAXCHECK= and NOSYNTAXCHECK= system options in SAS Language Reference: Dictionary
See Also: ICON, NOSPLASH, and NOTERMINAL system options in SAS Companion for Windows
See Also: COMAMID= System Option
See Also: NOCSCRIPT option
Restriction: OpenVMS only If the NODETACH system option is specified, and if multiple server sessions are running under OpenVMS and you observe degraded performance, this error message is displayed: 
ERROR: Process quota exceeded.
ERROR: Cannot spawn subprocess. Check process limit quotas and privileges.

NODETACH causes a sign-on to occur in a subprocess of the parent's process, which can use excessive resources. If NODETACH is specified, try setting the DETACH system option, which causes sign-ons to occur as detached processes rather than as subprocesses. For more information, see the NODETACH system option in the SAS Companion for OpenVMS on HP Integrity Servers.

To improve performance when using the NODETACH system option, ask your system administrator to set the following resources to the specified values for each sign-on to a server session:

OpenVMS Operating Environment Resource Values
User Account Resource Minimum Value
Paging file quota 40000
Buffered I/O byte count quota 13000
Open file quota 65
Subprocess limit 1
Timer queue entry limit 1 to 8

When SAS is invoked from a captive OpenVMS account, you cannot use SASCMD= to sign on to a server session. Typically, SASCMD= performs a sign-on to a server session either in a subprocess or in a detached process. Starting subprocesses is not allowed under a captive account. A detached process that runs under a captive account cannot invoke SAS because a captive OpenVMS account is under the control of the login command procedure. The command language interpreter will execute only the commands in your login command procedure and then the process will exit.

The !sascmdv value in the SASCMD= option causes the display of a symbol that specifies how the server session was started. You can print the symbol's value by using the getsym DATA step function. 

rsubmit;
   %put %bquote(
   %sysfunc (getsym(SASCMD_2042CF6B)));
endrsubmit;
SERVER="SAS-application-server"

specifies the name of a SAS Application Server that contains a SAS/CONNECT server component in its grouping. The SAS Application Server has been defined in the SAS Metadata Repository using SAS Management Console. The SAS Application Server is configured using a set of system resources, including a SAS/CONNECT server component and properties that start a SAS/CONNECT server session. The server properties are equivalent to the options that can be specified in the SIGNON statement.

"SAS-application-server"

specifies a SAS Application Server that contains a SAS/CONNECT server component, which has been defined in a SAS Metadata Repository.

Requirement: Enclose the name of the SAS Application Server in double or single quotation marks.
Requirement: When you use the SERVER= option, certain system resources must be configured before you can access a SAS Metadata Server. For details, see Sign On to a Server That Is Defined in the SAS Metadata Repository.
Requirement: If the specified SAS Application Server does not contain a SAS/CONNECT server component, the server sign-on fails.
Interaction: SERVER= is used in an RSUBMIT when an automatic sign-on is in effect via the AUTOSIGNON system option rather than when an explicit sign-on is specified via the SIGNON statement.
Interaction: When you use SERVER=, do not also use these RSUBMIT options: NOCSCRIPT, NOTIFY=, PASSWORD=, REMOTE=, SASCMD=, SCRIPT=, SIGNONWAIT=, or USERNAME=. Here is an example of a warning: 
WARNING: NOTIFY= and SERVER= are mutually exclusive. 
Please choose only one of them.

If any of these options is also specified, the entire RSUBMIT code block will be ignored. Although the AUTOSIGNON system option might be in effect, a server sign-on will fail.
Interaction: When you use SERVER=, you can also specify any of these options in RSUBMIT: CMACVAR=, CONNECTPERSIST=, CSTATUS=. CWAIT=, INHERITLIB=, LOG=, OUTPUT=, OUTPUT=, or SYSRPUTSYNC=. If you specify any of these options, the option that is specified in RSUBMIT takes precedence over the equivalent property for the SAS/CONNECT component that is contained in the SAS Application Server.
Interaction: If you use NOCSCRIPT and SERVER=, sign-on is canceled.
Interaction: The CONNECTPERSIST= and SYSRPUTSYNC= options are available only in the RSUBMIT statement. They cannot be specified as sign-on properties for the SAS/CONNECT component that is contained in the SAS Application Server.
Tip: Before you use the SERVER= option to sign-on, you can use SIGNON SERVERV= to view the properties that start a server session.
See Also: SERVERV= Option in SIGNON
See Also: AUTOSIGNON System Option
See Also: SAS Management Console User's Guide and SAS Management Console online Help
SIGNONWAIT=YES|NO

specifies whether a sign-on to a server session is to be executed synchronously or asynchronously. You can sign on using the SIGNON statement or the AUTOSIGNON system option.

Here are the values for this option:

YES|Y

specifies a synchronous sign-on. A synchronous sign-on causes the client session to wait until the sign-on to a server session has completed before control is returned to the client session for continued execution. YES is the default.

NO|N

specifies an asynchronous sign-on. An asynchronous sign-on to a server session begins execution and control is returned to the client session immediately for continued execution. Asynchronous sign-on allows multiple tasks (including other sign-ons) to be executed in parallel. Asynchronous sign-ons reduce the total amount of time that would be used to execute individual sign-ons to multiple server sessions. Using the saved time, the client session can execute more RSUBMIT statements.

Default: YES
Interaction: If the SIGNONWAIT system option is also specified, the SIGNONWAIT= option takes precedence over the system option.
Interaction: If SIGNONWAIT is specified as a system option and the SIGNONWAIT= option is not specified, the system option will apply to the RSUBMIT statement.
Interaction: If SIGNONWAIT=NO is specified, the USERID= and PASSWORD= options cannot be set to _PROMPT_.
See Also: SIGNONWAIT System Option
See Also: AUTOSIGNON System Option
See Also: SIGNON Statement and Command
STATUS=

SUBJECT="subject-title"

specifies the subject title for the e-mail notification message that is sent after an asynchronous RSUBMIT completes. A subject title is limited to a maximum of 256 characters.

Here is an example of specifying a subject using e-mail notification: 

options remote=myhost sascmd="!sascmd";
signon notify="joe.smith@apex.com";
rsubmit wait=no subject="First task completed on &SYSHOSTNAME";
   code-to-be-executed
endrsubmit;
Restriction: Use the SUBJECT= option only when the NOTIFY="e-mail-address" option is in effect.
Interaction: If the SUBJECT= option is not specified in the RSUBMIT statement, but SUBJECT= is specified at sign-on, the subject title that is specified at sign-on is used in the e-mail message for RSUBMIT. If no SUBJECT= is specified, the default subject title is used: 
SAS/CONNECT task TASK1 has completed.
TASK1 is the server ID.
See Also: NOTIFY= Option
See Also: Syntax for the SIGNON and the SIGNOFF Statements and Commands
See Also: SAS system options that support e-mail configuration: EMAILHOST, EMAILPORT, and EMAILSY in SAS Language Reference: Dictionary
UID=

USER=

USERID=

USERNAME=user-ID|_PROMPT_

specifies the user ID to use in order to sign on to a server session.

Here are the values for this option:

user-ID

For details about a valid user ID, see User ID and Password Naming Conventions.

_PROMPT_

specifies that SAS prompt the user for a valid user ID. This value enforces security.

Alias: USERID=, USER=, UID=
Restriction: Use the USERNAME= option only when the AUTOSIGNON system option has been specified (because a sign-on has not yet occurred).
See Also: AUTOSIGNON System Option
PASS=

PASSWD=

PW=

PWD=

PASSWORD=password | "encoded-password" |_PROMPT_

specifies the password to use in order to sign on to a server session. The operating environment that the server session runs under can affect password naming conventions. For details about password-naming conventions according to operating environment, see Communications Access Methods for SAS/CONNECT and SAS/SHARE.

Here are the values for this option:

password

must be a valid SAS name that is 1 to 8 characters in length. The value for this option is replaced by Xs in the log. To protect this password, you should use the security software at your site to limit access to the SAS program statements that create the server.

"encoded-password"

is an encoded version of a password. Using encoded passwords promotes security and enables you to store SAS programs that do not contain clear-text passwords.

To obtain an encoded password, specify the clear-text password as input to the PROC PWENCODE statement.

Here is an example of code for obtaining an encoded password: 

 proc PWENCODE in="srvmach";
run;
{sas001}c2Vydm1hY2g=
The clear-text password srvmach is specified in the PROC PWENCODE statement. The output is generated in the form {key}encoded-password . sas001 is the key, which is used to decode the encoded password to its clear-text form when the password is needed.

Note:   The encoded password is case-sensitive. Use the entire generated output string, including the key.  [cautionend]

Use the output from the PROC PWENCODE statement as the value for encoded-password in the appropriate statement.
_PROMPT_

specifies that SAS prompt the user for a valid password. This value enforces security.

Alias: PASSWD=, PASS=, PWD=, PW=
Restriction: Use the PASSWORD= option only when the AUTOSIGNON system option has been specified (because a sign-on has not yet occurred).
See Also: AUTOSIGNON System Option
SYSRPUTSYNC=

WAIT=

Details

Difference between SUBMIT and RSUBMIT

The RSUBMIT command and statement cause SAS programming statements that are entered in a client session to run in a server session. The difference between the RSUBMIT and the SUBMIT commands is the location of program execution (client session or server session). Although RSUBMIT executes tasks in a server session, results and output are delivered to the client session as if they were executed in the client session.

Difference between the RSUBMIT Statement and Command

The primary difference between the RSUBMIT command and the statement is that the command can be used only from a windowing environment session or in the DM statement. The RSUBMIT statement is used in a client session.

You can use the RSUBMIT command in these environments:

Difference between Synchronous and Asynchronous RSUBMITs

An RSUBMIT is executed either synchronously or asynchronously.

synchronous

Client session control is not returned until the RSUBMIT has completed. Synchronous execution is the default execution mode.

asynchronous

Client session control is returned immediately after an RSUBMIT is sent to a server session. Program execution can occur in a client session and in one or more server sessions in parallel.

A synchronous RSUBMIT displays results and output in the client session. If the RSUBMIT is asynchronous, you can use the RGET and RDISPLAY commands and statements and the LOG= and OUTPUT= options to retrieve and view the results.

Executing Statements in the RSUBMIT Block

The RSUBMIT command can be used to execute most types of SAS programs in the server session, except windowing procedures (such as SAS/FSP or SAS/AF procedures).

The RSUBMIT statement can be used to run SAS/CONNECT from the SAS windowing environment, an interactive line mode session, or a batch job. The RSUBMIT and the ENDRSUBMIT statements enable you to include the statements that should be executed in the server session in the same file as the statements that will be executed in the client session. The statements that are enclosed between the RSUBMIT and the ENDRSUBMIT statements, which constitute the RSUBMIT block, execute in the server session. All the other statements in the program are executed in the client session when you run the program.

The following template can be used to build a file that includes statements for both the client and the server sessions in the same program: 

statements for client session
rsubmit;
   statements for server session
endrsubmit;
  statements for client session

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

RSUBMIT and ENDRSUBMIT Parsing

When SAS encounters an RSUBMIT statement, it sends the SAS statements in the RSUBMIT block to SAS/CONNECT. SAS/CONNECT continues parsing the statements until it encounters the semicolon that follows the ENDRSUBMIT statement.

The SAS statements within an RSUBMIT block can contain the start of a quoted string. A second RSUBMIT block can contain the end of the quoted string. Here is an example of two RSUBMIT blocks in which a quoted string starts in the first RSUBMIT block and ends in the second RSUBMIT block: 

rsubmit;
data _null_;
newmacro='mend;
endrsubmit;
rsubmit;
endrsubmi' || 't; ' ;
put newmacro;
run;
endrsubmit;

If the preceding statements were changed to have "newmacro='mend; endrsubmit;';" (instead of it being broken between the two RSUBMIT blocks), parsing of the RSUBMIT block would end with "endrsubmit;" . RSUBMIT block processing ends after the ENDRSUBMIT statement, the second quotation mark is processed in the client SAS session, and another quotation mark will need to be entered before SAS reports an error. Here is an excerpt of the error message:

newmacro = 'mend; endrsubmit;'
                             -
ERROR : Statement is not valid or it is used out of proper order.

Avoid including the ENDRSUBMIT statement in a quoted string.

User ID and Password Naming Conventions

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

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' pass='2bornot2b' /* Windows user name */;
user='"happy joe"' pw=_prompt_;
user=_prompt_;
userid="myuserid" password="{sas001}MVNoYXJl";

Previous Page | Next Page | Top of Page

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