com.sas.net.connect
Class TelnetConnectClient

com.sas.net.connect.TelnetConnectClient

public class TelnetConnectClient

TelnetConnectClient extends ConnectClient. to use telnet (or spawner) protocol to start a remote SAS session and obtain the port number used by the SAS session for communication with a client.

Field Summary

Fields inherited from class com.sas.net.connect.ConnectClient

abort, clientFcb, connected, LINE_TYPE_BYLINE, LINE_TYPE_ERROR, LINE_TYPE_FOOTNOTE, LINE_TYPE_HILIGHTED, LINE_TYPE_MESSAGE, LINE_TYPE_NORMAL, LINE_TYPE_NOTE, LINE_TYPE_SOURCE, LINE_TYPE_TITLE, LINE_TYPE_WARNING

Constructor Summary

TelnetConnectClient(java.util.Properties info)
Constructs a TelnetConnectClient object using a Properties object.

Method Summary

void	connect(java.lang.String host) Connects to the server using the default Telnet port of 23.
void	connect(java.lang.String host, int telnetPort) Connects to the server.
void	disconnect() Disconnects from the server.

Methods inherited from class com.sas.net.connect.ConnectClient

addEditLine, addExtension, addRecords, checkDownloadRecno, checkOptions, clearEditLines, clearListLines, clearLogLines, connect, createDownload, drain, finalize, flush, getDownloadData, getDriverName, getEditLines, getListLineCount, getListLines, getListLines, getLogLineCount, getLogLines, getLogLines, getMajorSasVersion, getMinorSasVersion, getMver, getOptions, getRecords, getSharenet, getTextTransportFormat, isConnected, mergeOptions, rcancel, rsubmit, send, setLogException, setMver, setTextTransportFormat

Constructor Detail

TelnetConnectClient

public TelnetConnectClient(java.util.Properties info)
                    throws ConnectException

Constructs a TelnetConnectClient object using a Properties object. The Properties object must not be null. The properties that TelnetConnectClient uses are described below. Properties in info that are not used by TelnetConnectClient are passed through to the superclass and also to the telnet client. You should consult constructor documentation for ConnectClient and for SASTelnetClient to learn of more possible properties.

telnetClient is the name of the property that specifies the class name of the telnet client to use. The class must implement TelnetClientInterface. The default value is SASTelnetClient. If you plan to implement your own telnet client, please note that there is no guarantee that TelnetClientInterface will not change in future releases. This restriction is necessary to facilitate enhancements to SASTelnetClient.

Any properties needed by the telnet client should be included in the TelnetConnectClient properties list.

The following properties represent the prompts and responses necessary to establish a telnet (or spawner) session with the server and start a SAS session on that server:

promptN

A prompt from the remote connection daemon.

promptTimeoutN

The maximum number of seconds to wait for a prompt that contains promptN. The default is 0 seconds, which means wait forever.

responseN

The response to send to the remote connection daemon after a prompt containing promptN has been received.

For each property named above, N represents a positive integer that indicates the order in which the prompt/response pairs should be processed. The first value for N is always 1, and TelnetConnectClient will continue processing prompt/response pairs with increasing values for N until it encounters a value of N for which EITHER promptN OR responseN is not specified. All prompts must be non-empty, but empty responses are valid.

When all the prompt/response pairs have been processed, TelnetConnectClient will wait for an indication from the SAS System that it is ready to establish a SAS/CONNECT session with a client. You can specify a maximum time for TelnetConnectClient to wait for the indication that SAS is ready by specifying a value for the property sasPortTagTimeout. The default value is 0, which means wait forever.

Following is an example of typical property/value pairs for connections to telnet daemons running in the UNIX environment:

 (prompt1,login:)       // user name prompt from telnet daemon
 (response1,myUserName) // user name to send in reply
 (prompt2,Password:)    // password prompt from telnet daemon
 (response2,myPassword) // password to send in reply
 (responseBlot2,ON)     // blots out password in error messages and logs
 (prompt3,Command>)     // command prompt from telnet daemon
 (response3,sas -dmr)   // sas command to send in reply
 (promptTimeout3,30)    // time in seconds to wait before assuming telnet login failed
 (sasPortTagTimeout,45) // time in seconds to wait before assuming sas startup failed
 

Some server environments such as OS/390 TSO support session reconnection. If a telnet session connected to such a server disconnects before it issues a logoff command, subsequent telnet sessions started for the same user will reconnect to the previous session rather than begin a new session. While this feature is often useful, it presents problems for TelnetConnectClient because it is difficult to predict what actions must be taken in a reconnected session before it is safe to issue a command to start a SAS/CONNECT server. TelnetConnectClient has features to allow you to work around this problem. The first feature is the "prolog" session in which you can issue create a telnet session that merely cleans up any existing session before starting the "main" telnet session that will start a SAS/CONNECT server. The second feature is the "epilog" session which allows you to issue a logoff command after the SAS/CONNECT server has terminated. Finally, TelnetConnectClient supports conditional prompt/response pairs that allow you to script telnet sessions in which a prompt from the telnet daemon could be any one of a number of values.

Following is an example of typical property/value pairs for connections to telnet daemons running in the OS/390 TSO environment. In this example, conditional prompt/response pairs are used only in the prolog session, but they may also be used in the main session or the epilog session.

 (prologPrompt1,ENTER USERID)                // user name prompt from telnet daemon
 (prologResponse1,myUserName cancel)         // session cancel command to send in reply
 (prologPrompt2,ENTER PASSWORD)              // password prompt from telnet daemon
 (prologResponse2,myPassword)                // password to send in reply
 (prologResponseBlot2,ON)                    // blots out password in error messages and logs
 (prologPrompt3.0,CANCEL REQUEST DENIED)     // one possible result of session cancel command
 (prologPrompt3.1,SESSION CANCEL SUCCESSFUL) // another possible result of session cancel command
                                             // NOTE: no reply is sent to after prologPrompt3.x
 (prompt1,ENTER USERID)                      // user name prompt from telnet daemon
 (response1,myUserName)                      // user name to send in reply
 (prompt2,ENTER PASSWORD)                    // password prompt from telnet daemon
 (response2,myPassword)                      // password to send in reply
 (responseBlot2,ON)                          // blots out password in error messages and logs
 (prompt3,READY)                             // command prompt from telnet daemon
 (response3,sas opt('dmr'))                  // sas command to send in reply
 (sasPortTagTimeout,45)                      // time in seconds to wait before assuming sas startup failed
 (epilogPrompt1,READY)                       // command prompt after SAS/CONNECT server terminates
 (epilogResponse1,logoff)                    // logoff command to send in reply
 (epilogPrompt2,LOGGED OFF TSO)              // comfirmation of logoff command
                                             // NOTE: no reply is sent after epilogPrompt2
 

SAS/CONNECT sessions with The SAS System version 7 or later can support encryption. This means all messages passed between the client and server are encrypted. Also, telnet sessions between the default telnet client and the SAS Job Spawner version 7 or later can support encryption. This means that all messages passed between the telnet client and telnet daemon are encrypted including, if necessary, your user name and password.

Two properties control most of the encryption features. The first, encryptionPolicy, determines whether encryption is desired or not and, if it is desired, whether it is optional or required. The second, encryptionAlgorithms, specifies a list of the encryption algorithms that the client can support and wants to use in order of preference.

The possible values for encryptionPolicy are:

none

use no encryption. This is the default. If the server requires encryption, then the connection will fail.

optional

attempt to use encryption. If the client and server do not support any common algorithms, then use no encryption.

required

use encryption. If the client and server do not support any common algorithms, then the connection will fail.

The possible values for encryptionAlgorithms are:

sasproprietary

an encryption algorithm developed at SAS Institute.

rc2

a block cipher developed by RSA Data Security which supports variable key sizes. The largest key size legally allowed will always be chosen.

rc4

a stream cipher developed by RSA Data Security which supports variable key sizes. The largest key size legally allowed will always be chosen.

des

the Data Encryption Standard - a block cipher that supports 56-bit keys.

tripledes

the Data Encryption Standard run three times with three separate 56-bit keys (for an effective key size of 168 bits). This algorithm is typically only available in the United States and Canada.

More than one algorithm can be listed in the value for encryptionAlgorithms if each algorithm is separated by a comma. If this property is not specified, then the server's most prefered algorithm will be used. The last four algorithms, rc2, rc4, des, and tripledes are only available if SAS/SECURE is licensed on the server and the Java component of SAS/SECURE (sasecjav.zip) has been installed in the client code base.

Encryption options for the server are also required, and they can be specified on the SAS command line or the SAS Job Spawner command line, or both. To make a server require encryption, specify -NETENCRYPT. Otherwise, encryption on the server will be optional. To specify the list of supported algorithms, use -NETENCRALG. The client's order of preference takes precedence.

When encryption is supported for both the telnet session and the SAS/CONNECT session, a property is needed to determine whether or not the encryption properties 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.

For SAS version 8 and later, the SAS Job Spawner supports an option called -INHERITANCE. When this option is used, the SAS/CONNECT session will inherit the socket used by the telnet session along with any encryption functionality. Therefore, in this case, the encryptionTarget property will be ignored, and it will be assumed that any encryption properties specified will be applied to the telnet session and inherited by the SAS/CONNECT session. This is the default value for the spawner shipped with SAS version 8.1 and later.

Following is an example of typical property/value pairs for connections to SAS spawners. In this example, the connection must use RC2 encryption, and it is expected that the spawner supports socket inheritance.

 (prompt1,Username:)         // user name prompt from telnet daemon
 (response1,myUserName)      // user name to send in reply
 (prompt2,Password:)         // password prompt from telnet daemon
 (response2,myPassword)      // password to send in reply
 (responseBlot2,ON)          // blots out password in error messages and logs
 (prompt3,Hello>)            // command prompt from telnet daemon
 (response3,sas)             // sas command to send in reply
 (sasPortTagTimeout,45)      // time in seconds to wait before assuming sas startup failed
 (encryptionPolicy,required) // TelnetConnectClient option making encryption required
 (encryptionAlgorithms,RC2)  // TelnetConnectClient option specifying which algorithm to use
 

Here is an example showing the command that could start a SAS spawner that would support connections from TelnetConnectClient started with the options above.

 spawner -comamid tcp -security -authserver MY_SECURITY_DOMAIN -netencrypt -netencralg RC2 -inheritance
 

Parameters:

info - The list of properties.

Throws:

ConnectException - if the properties object is null.

Method Detail

connect

public void connect(java.lang.String host,
                    int telnetPort)
             throws ConnectException

Connects to the server.

Overrides:

connect in class ConnectClient

Parameters:

host - The host name or address of the remote machine.

telnetPort - TCP/IP port number for your connection daemon.

Throws:

ConnectException - if an exception is detected.

connect

public void connect(java.lang.String host)
             throws ConnectException

Connects to the server using the default Telnet port of 23.

Parameters:

host - The host name or address of the remote machine.

Throws:

ConnectException - if an exception is detected.

disconnect

public void disconnect()
                throws ConnectException

Disconnects from the server. Do not make any calls except connect after this.

Overrides:

disconnect in class ConnectClient

Throws:

ConnectException - if an exception is detected.