SAS/CONNECT 9.2 Driver for Java

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 page describes the types of connection objects 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 you use to construct the connection object depends on whether your program uses HTTP tunneling or the SAS/CONNECT protocol. For HTTP tunneling, you will use the TunneledConnectClient class to create the connection object. Otherwise, you will use the TelnetConnectClient class to create the connection object.

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 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 you want to pass.

responsex

Where x is any number, and the value corresponds to the connection information you want to pass. If you want your program to prompt the user for a user name and password at startup, do not specify values for the responsex properties 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 will not be 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 the connection daemon you are using. Typically, you need only create 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 further explanation of 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.

Note: The routerUrl property applies to TunneledConnectClient objects only.

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

Timeout Properties

To determine whether the connection process is continuing properly, the connection client allows a certain amount of time to pass 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 timeout values. You can create as many Timeout properties as you need.

Note: Timeout properties apply only to TelnetConnectClient objects.

promptTimeoutx: Where x is a number that corresponds to the prompt you want to time. You will specify a number of seconds 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 you want to time. You will specify the number of seconds 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 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.

Encryption Properties

When communicating with a SAS server that is running the SAS System, Version 7 or later, 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.

Two properties control most of the encryption features in the SAS/CONNECT Driver for Java.

encryptionPolicy: This property controls whether the connection client will attempt to negotiate and use an encryption algorithm with the server and what to do if the negotiations are not successful. If the value of this property is none, then the connection client will not attempt to negotiate and use an encryption algorithm with the server. If the server requires encryption to be used, then the connection will fail. This is the default value. If the value of this property is optional, then the connection client will attempt to negotiate and use an encryption algorithm with the server. If the negotiations fail, then the connection client will try to continue with an unencrypted connection. However, that will also fail if the server requires encryption. If the value of this property is required, then the connection client will attempt 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 will use 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 you want to use for a particular connection. Also, if no algorithms are listed, then the server will choose one. Possible values for this property are sasproprietary, a stream cipher developed at SAS Institute, 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, and 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 above 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 will consider 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 will take 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 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 will throw 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 you want to pass, respectively. The userNameResponse and passwordResponse parameters are as described above. 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: You will use the getParameter method to pick up these values. Then, you 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.

Timeout 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 you want to time, and nnn is the number of seconds you want the connection client to wait.

Constructing the Connection Object

If you want to use 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 your using SAS/CONNECT protocol or HTTP tunneling.

If you're using 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 will end 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 will end the SAS session.

Top of Page