com.sas.net.connect
Class ConnectClient

com.sas.net.connect.ConnectClient

Direct Known Subclasses:

TelnetConnectClient, TunneledConnectClient

public class ConnectClient

This is the base class for TelnetConnectClient and TunneledConnectClient.

Field Summary

protected boolean	abort
protected com.sas.net.sharenet.Wqefcb	clientFcb
protected boolean	connected
static java.lang.Integer	LINE_TYPE_BYLINE Line type code for by LOG and LIST lines.
static java.lang.Integer	LINE_TYPE_ERROR Line type code for error LOG and LIST lines.
static java.lang.Integer	LINE_TYPE_FOOTNOTE Line type code for footnote LOG and LIST lines.
static java.lang.Integer	LINE_TYPE_HILIGHTED Line type code for highlighted LOG and LIST lines.
static java.lang.Integer	LINE_TYPE_MESSAGE Line type code for message LOG and LIST lines.
static java.lang.Integer	LINE_TYPE_NORMAL Line type code for normal LOG and LIST lines.
static java.lang.Integer	LINE_TYPE_NOTE Line type code for note LOG and LIST lines.
static java.lang.Integer	LINE_TYPE_SOURCE Line type code for program source code LOG and LIST lines.
static java.lang.Integer	LINE_TYPE_TITLE Line type code for title LOG and LIST lines.
static java.lang.Integer	LINE_TYPE_WARNING Line type code for warning LOG and LIST lines.

Constructor Summary

ConnectClient()
Constructs a SAS/CONNECT driver for Java ConnectClient object.

ConnectClient(java.util.Properties info)
Constructs a SAS/CONNECT driver for Java ConnectClient object.

Method Summary

protected void	addEditLine(java.lang.String editline) Add edit lines to the editLines buffer.
void	addExtension(java.lang.String name, java.lang.ClassLoader cl) Adds an extension to the Connect protocol; for future extensions only.
protected void	addRecords(com.sas.net.connect.ConnectRecord record, boolean must) This method adds a record to the buffer and sends the buffer if necessary.
protected void	checkDownloadRecno(int recno) Check final number of records.
protected boolean	checkOptions(int optionFlag) Check options.
void	clearEditLines() Clears the edit lines.
void	clearListLines() Clears output lines in the LIST file.
void	clearLogLines() Clears the LOG lines in the internal LOG line buffer.
protected void	connect(java.net.Socket socket, com.sas.net.crypto.CipherInterface cipher) Connects to the remote SAS session.
void	connect(java.lang.String host, int port) Connects to the remote SAS session.
protected void	createDownload(java.lang.String name, int lrecl, boolean text) Create download file object.
void	disconnect() Disconnects and shuts down the remote SAS session.
protected boolean	drain() Drain all messages from the the server.
protected void	finalize() The finalize method is called automatically when this class is garbage collected.
protected boolean	flush() Transmit the current buffer.
byte[]	getDownloadData(java.lang.String name) Gets the contents of a downloaded file.
java.lang.String	getDriverName() Gets the name and version number of the SAS/CONNECT driver for Java component.
java.lang.String	getEditLines() Gets edit lines.
int	getListLineCount() Get the number of lines in the internal LIST line buffer.
java.lang.String	getListLines() Gets the lines that SAS generated in the LIST file from the internal LIST line buffer as a single String.
int	getListLines(java.lang.String[] lines, java.lang.Integer[] types) Gets the lines that SAS generated in the LIST file from the internal LIST line buffer as an array of String with line types associated.
int	getLogLineCount() Get the number of lines in the internal LOG line buffer.
java.lang.String	getLogLines() Gets the lines that SAS generated in the LOG file from the internal LOG line buffer as a single String.
int	getLogLines(java.lang.String[] lines, java.lang.Integer[] types) Gets the lines that SAS generated in the LOG file from the internal LOG line buffer as an array of String with line types associated.
int	getMajorSasVersion() Gets the major release number of the remote SAS server.
int	getMinorSasVersion() Gets the minor release number of the remote SAS server.
protected int	getMver() Gets the remote SAS session version number.
protected int	getOptions() Get options.
protected boolean	getRecords() Receive a message from the server.
java.sql.Connection	getSharenet() Starts the Single User Server.
java.lang.String	getTextTransportFormat() Returns the name of the character encoding used to convert SAS programs to byte arrays before submitting them and to convert received byte arrays representing log and list lines to strings.
boolean	isConnected() Gets the value of the connected property.
protected void	mergeOptions(int masterOptions) Merge options.
void	rcancel() Cancels the statements that were sent to the remote SAS session.
void	rsubmit(java.lang.String lines) Submits SAS statements to the remote SAS session.
protected void	send(com.sas.net.sharenet.Wqefcb fcb) Send a message to the server.
void	setLogException(boolean logException) Sets the logException property.
protected void	setMver(int masterVersion) Save the version number of the remote SAS session.
protected void	setTextTransportFormat(java.lang.String s)

Field Detail

LINE_TYPE_NORMAL

public static final java.lang.Integer LINE_TYPE_NORMAL

Line type code for normal LOG and LIST lines.

LINE_TYPE_HILIGHTED

public static final java.lang.Integer LINE_TYPE_HILIGHTED

Line type code for highlighted LOG and LIST lines.

LINE_TYPE_SOURCE

public static final java.lang.Integer LINE_TYPE_SOURCE

Line type code for program source code LOG and LIST lines.

LINE_TYPE_TITLE

public static final java.lang.Integer LINE_TYPE_TITLE

Line type code for title LOG and LIST lines.

LINE_TYPE_BYLINE

public static final java.lang.Integer LINE_TYPE_BYLINE

Line type code for by LOG and LIST lines.

LINE_TYPE_FOOTNOTE

public static final java.lang.Integer LINE_TYPE_FOOTNOTE

Line type code for footnote LOG and LIST lines.

LINE_TYPE_ERROR

public static final java.lang.Integer LINE_TYPE_ERROR

Line type code for error LOG and LIST lines.

LINE_TYPE_WARNING

public static final java.lang.Integer LINE_TYPE_WARNING

Line type code for warning LOG and LIST lines.

LINE_TYPE_NOTE

public static final java.lang.Integer LINE_TYPE_NOTE

Line type code for note LOG and LIST lines.

LINE_TYPE_MESSAGE

public static final java.lang.Integer LINE_TYPE_MESSAGE

Line type code for message LOG and LIST lines.

clientFcb

protected com.sas.net.sharenet.Wqefcb clientFcb

connected

protected boolean connected

abort

protected boolean abort

Constructor Detail

ConnectClient

public ConnectClient()

Constructs a SAS/CONNECT driver for Java ConnectClient object.

ConnectClient

public ConnectClient(java.util.Properties info)

Constructs a SAS/CONNECT driver for Java ConnectClient object.

Parameters:

info - java.util.Properties object which contains:

• logException - Throw an exception when error lines are detected in the log. Possible values are true and false. The default is false.
• compressionPolicy - Manipulate compression of data in messages exchanged with the server. Possible values are session and none. session means that all messages exchanged in a session will be examined and compressed if the compression would yield a smaller message. This is the default behavior. none means that no messages will 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 may be the case when the data exchanged are primarily binary.
• textTransportFormat - the name of the character encoding used when transmitting SAS programs and receiving log lines, list lines, and downloaded text files. This name will be used when converting between java.lang.String objects and the byte arrays that are transmitted to and received from the server. If no value is specified for this property, the default character conversion will be used. When connecting to a SAS/CONNECT server of version 8.1 or later, this information is determined automatically so the textTransportFormat property is ignored.

Method Detail

finalize

protected void finalize()
                 throws java.lang.Throwable

The finalize method is called automatically when this class is garbage collected.

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable - if an exception occurs during garbage collection

isConnected

public boolean isConnected()

Gets the value of the connected property. The connected property is initially false. It is set to true when connect() is called, and it is set back to false when disconnect() is called.

Returns:

The value of the connected property.

getDriverName

public java.lang.String getDriverName()

Gets the name and version number of the SAS/CONNECT driver for Java component.

Returns:

the name and version number of the SAS/CONNECT driver for Java component.

getMajorSasVersion

public int getMajorSasVersion()
                       throws ConnectException

Gets the major release number of the remote SAS server.

Returns:

The major release number of the remote SAS server or -1 if the release number is unknown to this version of the client.

Throws:

ConnectException - if there is no live connection to a SAS server.

getMinorSasVersion

public int getMinorSasVersion()
                       throws ConnectException

Gets the minor release number of the remote SAS server.

Returns:

The minor release number of the remote SAS server or -1 if the release number is unknown to this version of the client.

Throws:

ConnectException - if there is no live connection to a SAS server.

setLogException

public void setLogException(boolean logException)

Sets the logException property.

Parameters:

logException. - If True, the ConnectClient will throw a ConnectLogException when it detects a message in the SAS log indicating an error.

connect

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

Connects to the remote SAS session. This method assumes that the remote session has already been started using the -DMR SAS system option.

Parameters:

host - Host name or address of the machine on which the remote SAS session is running.

port - TCP/IP port number on which the SAS session is listening.

Throws:

ConnectException - if any exceptions are detected.

connect

protected void connect(java.net.Socket socket,
                       com.sas.net.crypto.CipherInterface cipher)
                throws ConnectException

Connects to the remote SAS session. This method is used when connecting to a spawner the supports socket inheritance (V8 or later).

Parameters:

socket - TCP socket to use for communications.

Throws:

ConnectException - if any exceptions are detected.

getSharenet

public java.sql.Connection getSharenet()
                                throws ConnectException

Starts the Single User Server. Without starting a Single User Server, you can submit lines to the remote session and retrieve the LOG and LIST files, but you cannot access data. To access SAS data, you must start the single user server.

Returns:

A java.sql.Connection object. This object is constructed using the properties that were passed as part of the ConnectClient constructor.

Throws:

ConnectException - if the Single User Server could not be started, or detected an error.

rsubmit

public void rsubmit(java.lang.String lines)
             throws ConnectException,
                    ConnectLogException

Submits SAS statements to the remote SAS session.

Parameters:

lines - The SAS statements that you want to submit.

Throws:

ConnectException - if an error is detected.

ConnectLogException

rcancel

public void rcancel()

Cancels the statements that were sent to the remote SAS session. The functionality of this method is extremely limited. Because SAS/CONNECT protocol is half-duplex, SAS/CONNECT Driver for Java cannot send the rcancel message to the server until the server responds to the previous rsubmit message. Only in rare situations does that happen before the server has completely finished processing the submitted statements. One such situation is the use of PROC DOWNLOAD. If you submit statements that include a PROC DOWNLOAD step, and you call this method before the PROC DOWNLOAD step executes, then the statements following the PROC DOWNLOAD step will be canceled.

disconnect

public void disconnect()
                throws ConnectException

Disconnects and shuts down the remote SAS session.

Throws:

ConnectException - if an error is detected.

getLogLines

public java.lang.String getLogLines()

Gets the lines that SAS generated in the LOG file from the internal LOG line buffer as a single String. Individual lines are separated with "\n".

Returns:

The LOG output from the remote SAS session.

getLogLines

public int getLogLines(java.lang.String[] lines,
                       java.lang.Integer[] types)

Gets the lines that SAS generated in the LOG file from the internal LOG line buffer as an array of String with line types associated. This method copies N lines from its buffer of LOG lines into lines and copies the associated line type for each line into types. N is the smallest of lines.length, types.length, and the size of the buffer of LOG lines. The size of the internal LOG line buffer can be determined in advance by calling getLogLineCount(). Each line type is one of the LINE_TYPE_* fields on this class.

Returns:

the number of lines copied.

getLogLineCount

public int getLogLineCount()

Get the number of lines in the internal LOG line buffer.

Returns:

the number of lines in the internal LOG line buffer.

clearLogLines

public void clearLogLines()

Clears the LOG lines in the internal LOG line buffer.

getListLines

public java.lang.String getListLines()

Gets the lines that SAS generated in the LIST file from the internal LIST line buffer as a single String. Individual lines are separated with "\n".

Returns:

The LIST output from the remote SAS session.

getListLines

public int getListLines(java.lang.String[] lines,
                        java.lang.Integer[] types)

Gets the lines that SAS generated in the LIST file from the internal LIST line buffer as an array of String with line types associated. This method copies N lines from its buffer of LIST lines into lines and copies the associated line type for each line into types. N is the smallest of lines.length, types.length, and the size of the buffer of LIST lines. The size of the internal LIST line buffer can be determined in advance by calling getListLineCount(). Each line type is one of the LINE_TYPE_* fields on this class.

Returns:

the number of lines copied.

getListLineCount

public int getListLineCount()

Get the number of lines in the internal LIST line buffer.

Returns:

the number of lines in the internal LIST line buffer.

clearListLines

public void clearListLines()

Clears output lines in the LIST file.

getEditLines

public java.lang.String getEditLines()

Gets edit lines.

Returns:

The edit lines sent to remote SAS session.

clearEditLines

public void clearEditLines()

Clears the edit lines.

getDownloadData

public byte[] getDownloadData(java.lang.String name)
                       throws ConnectException

Gets the contents of a downloaded file.

Parameters:

name - The name of the downloaded file.

Returns:

A byte array that represents the downloaded file.

Throws:

ConnectException - if an error is detected.

addExtension

public void addExtension(java.lang.String name,
                         java.lang.ClassLoader cl)
                  throws ConnectException

Adds an extension to the Connect protocol; for future extensions only.

Parameters:

name - The class name of the extension.

cl - The class loader to load the extension. If null, the class loader that loaded this class will be used.

Throws:

ConnectException - if the named extension cannot be instantiated or does not support the required interface.

getTextTransportFormat

public java.lang.String getTextTransportFormat()

Returns the name of the character encoding used to convert SAS programs to byte arrays before submitting them and to convert received byte arrays representing log and list lines to strings. This encoding should also be used when converting downloaded text files into strings. If null is returned, then the default character encoding should be used.

Returns:

the name of the character encoding used for transport format.

getRecords

protected boolean getRecords()
                      throws ConnectException

Receive a message from the server.

Returns:

True if the statements were cancelled.

Throws:

ConnectException - if an error is detected

addRecords

protected void addRecords(com.sas.net.connect.ConnectRecord record,
                          boolean must)
                   throws ConnectException

This method adds a record to the buffer and sends the buffer if necessary.

Parameters:

record - record to be sent to the remote SAS session

must - boolean true if message must be sent immediately

Throws:

ConnectException - if error is detected

drain

protected boolean drain()
                 throws ConnectException

Drain all messages from the the server.

Returns:

True if the statements were cancelled.

Throws:

ConnectException - if an error is detected.

flush

protected boolean flush()
                 throws ConnectException

Transmit the current buffer.

Returns:

True if the statements were cancelled.

Throws:

ConnectException - if an error is detected.

send

protected void send(com.sas.net.sharenet.Wqefcb fcb)
             throws ConnectException

Send a message to the server.

Parameters:

fcb - function control block that contains the message

Throws:

ConnectException - if an error is detected

addEditLine

protected void addEditLine(java.lang.String editline)

Add edit lines to the editLines buffer.

Parameters:

editLine - String to be added to editLines buffer.

createDownload

protected void createDownload(java.lang.String name,
                              int lrecl,
                              boolean text)
                       throws ConnectException

Create download file object.

Parameters:

name - String used to refer to the downloaded file

lrecl - int number of records for downloaded file

text - True if file is a text file, False if binary

Throws:

ConnectException - if an error is detected

checkDownloadRecno

protected void checkDownloadRecno(int recno)
                           throws ConnectException

Check final number of records.

Parameters:

recno - number of records in downloaded file.

Throws:

ConnectException - if an error is detected

setMver

protected void setMver(int masterVersion)

Save the version number of the remote SAS session.

Parameters:

masterVersion - int version number of remote SAS session.

getMver

protected int getMver()

Gets the remote SAS session version number.

Returns:

remote SAS session version number.

setTextTransportFormat

protected void setTextTransportFormat(java.lang.String s)

mergeOptions

protected void mergeOptions(int masterOptions)

Merge options.

Parameters:

masterOptions - int options set in remote SAS session.

checkOptions

protected boolean checkOptions(int optionFlag)

Check options.

Parameters:

optionFlag - ands the option flags with this objects options settings.

Returns:

True if any option in the option flag is True, otherwise False.

getOptions

protected int getOptions()

Get options.

Returns:

options int representing the options settings for this object.