Connecting to a Remote SAS Session

Overview of Connecting to a Remote SAS Session

A SAS/CONNECT driver for Java program communicates with the SAS/CONNECT server using a connection daemon (either the SAS spawner program or a Telnet daemon). A tunneled SAS/CONNECT driver for Java program communicates with the tunnel feature's server programs, which in turn communicate with the SAS/CONNECT server using either the spawner program or a Telnet daemon. This section describes the types of connection objects that you can use, how to construct a connection object, and other topics related to managing the connection to a remote SAS server.

The SAS/CONNECT driver for Java class that you use to construct the connection object depends on whether your program uses HTTP tunneling or the SAS/CONNECT protocol. For HTTP tunneling, use the TunneledConnectClient class to create the connection object. Otherwise, use the TelnetConnectClient class to create the connection object.

Connection Properties

General Connection Properties

Connection objects are constructed using a set of properties that specify information that is required by the connection daemon. The properties represent the prompts and responses that are passed when the connection is established. The connection object waits for certain prompts from the connection daemon (or from the tunnel feature's server programs) and then responds. The properties are set from the values in a Properties object that is passed as an argument to the constructor of the connection object class that you use.

For TelnetConnectClient and TunneledConnectClient, you must specify at least one property. If the property list is null, an exception is returned. The connection properties that you can specify for TelnetConnectClient and TunneledConnectClient objects are as follows:

promptx

Where x is any number, and the value corresponds to the prompt that you want to pass.

responsex

Where x is any number, and the value corresponds to the connection information that you want to pass. If you want your program to prompt the user for a user name and password at start-up, do not specify values for the responsex properties that you define for user name and password information.

userNameResponse

passwordResponse

These properties specify which responsex properties contain the user name and password information. For example, if you use response1 for the user name and response2 for the password, you would specify response1 as the value for the userNameResponse property and response2 as the value for the passwordResponse property. For non-tunneled programs, you need to use the userNameResponse and passwordResponse properties only if you want the program to prompt for the user name and password. If you want to specify the user name and password as values for responsex properties instead of having the user enter the information, do not use the userNameResponse and passwordResponse properties.

For tunneled programs, the userNameResponse and passwordResponse properties specify which responses are the user name and password so the responses can be encrypted before they are sent to the tunnel feature's server programs. If you do not use the userNameResponse and passwordResponse properties, the user name and password are not encrypted when they are sent to the server.

sasPortTag

The tag in the message from SAS software indicating the port at which the SAS server is listening.

The prompt/response pairs required for a successful connection might differ depending on which connection daemon you are using. Typically, you need to create only three prompt/response pairs to pass the user name, password, and command information, but you can create additional parameters to pass prompts and responses that your connection daemon requires. For more information about how the prompt/response properties relate to the connection information that is passed when manually establishing a connection, see Connection Properties and Telnet Connection Information.

The Tunneling Property

Connection objects that use HTTP tunneling use the routerUrl property, which enables the Web server to locate the Message Router (shrcgi.exe), one of the tunnel feature's server programs.

routerUrl

The URL of the Message Router (shrcgi.exe).

Note: The routerUrl property applies to TunneledConnectClient objects only.

Timeout Properties

To determine whether the connection process is continuing properly, the connection client allows a certain amount of time to pass while waiting for a particular prompt. If the prompt is not received within the allotted time, the connection client assumes that an error has occurred and throws a ConnectException. The connection client supports properties that enable a user to override the default time-out values. You can create as many Timeout properties as you need.

promptTimeoutx

Where x is a number that corresponds to the prompt that you want to time. Specify a number of seconds that you want the connection client to wait from the time it begins listening for the prompt to the time it receives the prompt.

responseTimeoutx

Where x is a number that corresponds to the response that you want to time. Specify the number of seconds that you want the connection client to wait from the time it sends the response to the time the connection daemon receives the response.

sasPortTagTimeout

The sasPortTagTimeout property specifies the number of seconds that you want the connection client to wait from the time it begins listening for the port tag to the time it receives the port tag.

Note: Timeout properties apply only to TelnetConnectClient objects.

Encryption Properties

When communicating with a SAS server, messages passed to and received from both the SAS spawner and the SAS/CONNECT server can be encrypted using a variety of encryption algorithms. The tunnel feature server programs do not support this level of encryption. The only supported encryption in the tunnel server programs is to encrypt user name and password.

The following two properties control most of the encryption features in the SAS/CONNECT driver for Java:

encryptionPolicy

This property controls whether the connection client attempts to negotiate and use an encryption algorithm with the server, and controls what to do if the negotiations are not successful. Possible values for this property are

none	the connection client does not attempt to negotiate and use an encryption algorithm with the server. If the server requires encryption, then the connection fails. This is the default value.
optional	the connection client attempts to negotiate and use an encryption algorithm with the server. If the negotiations fail, then the connection client tries to continue with an unencrypted connection. However, that also fails if the server requires encryption.
required	the connection client attempts to negotiate and use an encryption algorithm with the server. If the negotiations fail, then the connection fails.

encryptionAlgorithms

This property specifies a comma-separated list of encryption algorithms in order of preference. The connection client uses this list when negotiating encryption algorithms with the server. It is not necessary to list all the algorithms that the connection client can support, only the ones that you want to use for a particular connection. Also, if no algorithms are listed, then the server chooses one. Possible values for this property are

sasproprietary	a stream cipher developed at SAS
RC2	a block cipher developed by RSA Data Security
RC4	a stream cipher developed by RSA Data Security
des	a block cipher known as Data Encryption Standard
TRIPLEDES	DES applied three times with separate keys

To use RC2, RC4, DES, or TRIPLEDES, you must license SAS/SECURE on the server and install the Java component of SAS/SECURE (sasecjav.zip) in your code base. TRIPLEDES can generally only be used in the United States and Canada due to export restrictions.

Because encryption is supported for connections to both the SAS spawner and the SAS/CONNECT server, a property is sometimes needed to determine whether the encryption properties listed here apply to the Telnet session or the SAS/CONNECT session. This property is named encryptionTarget. Its possible values are:

telnet	encryption properties apply only to the Telnet session.
sas	encryption properties apply only to the SAS/CONNECT session. This is the default.
both	encryption properties apply to both the Telnet session and the SAS/CONNECT session.

If the SAS spawner was started with the -INHERITANCE option, then, in effect, the only possible value for this property is both. Therefore, this property is ignored when the -INHERITANCE option is used.

Encryption Properties for the Server

The SAS server and SAS spawner both require similar properties to control encryption. These properties can be specified as command-line options when starting the SAS spawner or when specifying the responsex property that corresponds to the SAS command for TelnetConnectClient.

-NETENCRYPT

Specify this option to make the SAS server or SAS spawner require encryption when clients connect. If you do not specify this option, then the SAS server or SAS spawner considers encryption to be optional.

-NETENCRALG

Specify this option and follow it with a comma-separated list of encryption algorithms. The list specifies the order of preference for use in algorithm negotiation. However, if you specify a list of encryption algorithms as a value to the encryptionAlgorithms property for the connection client, that list takes precedence. If this option is not specified, then encryption might not function properly. The values that you can use in the list of encryption algorithms are the same as the values that you can use for the encryptionAlgorithms property for the connection client.

Other Useful Properties

You might also want to use the following properties:

compressionPolicy

Specify this option to manipulate compression of data in messages exchanged with the server. Possible values are:

session	specifies that all messages exchanged in a session are examined and compressed if the compression would yield a smaller message. This is the default behavior.
none	specifies that no messages should be compressed. This behavior is useful in SAS/CONNECT sessions in which the time used to compress and decompress data does not justify the amount of space saved by compression. This might be the case when the data exchanged is primarily binary.

textTransportFormat

Specifies the name of the character encoding used when moving text between the SAS/CONNECT driver for Java and a SAS/CONNECT server. When you set this property, the driver transcodes SAS programs to this encoding before submitting them to the server. Transcoding from the specified encoding is automatically applied to log lines and list lines when they are received from the server. Note that downloaded files are not automatically transcoded when they are received from the server because the SAS/CONNECT driver for Java does not distinguish between text and binary files. However, when you download a text file, you can transcode it using any transcoding mechanism in the JDK along with the name of the encoding. You can fetch the name of the encoding using the getTextTransportFormat method.

If you do not specify a value for this property, the default character encoding of the Java virtual machine is used. If the specified character encoding cannot be supported by the Java virtual machine, then the SAS/CONNECT driver for Java throws an exception the first time it attempts a character conversion.

Notes:

Support for the Cp1047 code page is built into the SAS/CONNECT driver for Java because many current Java virtual machines do not provide support for this common character encoding.
If you use the textTransportFormat property, you might need to reconfigure your SAS/CONNECT server as well.
The SAS/SHARE driver for JDBC, which is included with the SAS/CONNECT driver for Java, transcodes character data, column names, column descriptions, and format names from this encoding when processing an SQL query.

logException

Specify this option so that your program throws an exception when an error line appears in the SAS log. Possible values are TRUE and FALSE. The default behavior is FALSE, which does not attempt to determine whether an error condition exists.

Using Applet Parameters to Pass Connection Information

An applet passes connection information through parameters, using the following format:

<param name=promptx value="prompt">
<param name=responsex value="response">
<param name=userNameResponse value="response1">
<param name=passwordResponse value="response2">
<param name=sasPortTag value="port_tag">

where x is any number, and prompt and response are the values associated with the prompt and connection information that you want to pass, respectively. The userNameResponse and passwordResponse parameters are as described previously, and port_tag uniquely identifies that the SAS session has completed initialization and allows the connection client to parse the port value from the response.

Note: Use the getParameter method to get these values. Then, construct a new Properties object and put these values into the object.

Tunneling information is passed through a parameter using the following format:

<param name=routerURLx value="http://your_server/cgi-bin/shrcgi">

where http://your_server/cgi-bin/shrcgi is a URL that corresponds to the location of the tunnel feature's server programs.

Time-out information is passed through parameters, using the following format:

<param name=promptTimeoutx value="nnn">
<param name=responseTimeoutx value="nnn">
<param name=sasPortTagTimeout value="nnn">

where x is a number that corresponds to the prompt or response that you want to time, and nnn is the number of seconds that you want the connection client to wait.

Constructing the Connection Object

If you want to use the SAS/CONNECT protocol, instantiate the connection object using the TelnetConnectClient constructor, as follows:

import com.sas.net.connect.TelnetConnectClient;
TelnetConnectClient tconnection = new TelnetConnectClient(info);

If you want to use HTTP tunneling, instantiate the connection object using the TunneledConnectClient constructor, as follows:

import com.sas.net.connect.TunneledConnectClient;
info.put("routerUrl","http://your_server/cgi-bin/shrcgi");
TunneledConnectClient tconnection = new TunneledConnectClient(info);

The TunneledConnectClient sends a request to the tunnel feature's server programs to start a SAS/CONNECT session and return the port number for communication with the Java client. Then, it passes connection properties to the Message Router.

Ending the Remote SAS Session

The session ends differently depending on whether you are using the SAS/CONNECT protocol or HTTP tunneling.

If you're using the SAS/CONNECT protocol, the connection client class (TelnetConnectClient) overrides the base class disconnect method, so it can destroy the Telnet or spawner session in addition to ending the remote SAS session. The class first calls the base class disconnect method, which sends a shutdown message to SAS and receives a response that the SAS session has successfully shut down. The subclass disconnect method then closes the socket connection to the Telnet or spawner session, which effectively ends the Telnet or spawner session. The Telnet or spawner session cannot be destroyed before ending the SAS session. The SAS session is started as a subprocess of the Telnet or spawner session, and ending the Telnet or spawner session prematurely ends the SAS session.

If you're using HTTP tunneling, the base class disconnect method requests that the tunnel feature's server programs end the remote SAS session. When the base class disconnect method is called, a shutdown message is sent to the SAS session and a response is returned indicating that the SAS session has successfully shut down. Then, the tunnel feature's server programs end the Telnet or spawner session. The Telnet or spawner session cannot be destroyed before ending the SAS session. The SAS session is started as a subprocess of the Telnet or spawner session, and ending the Telnet or spawner session prematurely ends the SAS session.