*** This interface provides Binary Compatibility only, not Source Compatibility ***

com.sas.services.storedprocess
Interface ExecutionBaseInterface

All Superinterfaces:

java.rmi.Remote

All Known Subinterfaces:

Execution2Interface, ExecutionInterface

public interface ExecutionBaseInterface
extends java.rmi.Remote

This interface describes various common aspects associated with the execution of a stored process.

Since:

9.2

Field Summary

static int	LOG_ALL_LINES Get all lines of the log.
static int	LOG_FORMAT_HTML Format the log as "html".
static int	LOG_FORMAT_TEXT Format the log as "text".
static int	STATUS_COMPLETED_WITHOUT_EXCEPTION The stored process has completed execution without any exception.
static int	STATUS_DESTROYED The destroy method has been called.
static int	STATUS_EXCEPTION_OCCURRED The execution of the stored process resulted in an exception.
static int	STATUS_EXECUTING The stored process is executing.
static int	STATUS_SAS_EXCEPTION_OCCURRED An exception occurred during the setup or execution stage of the stored process.

Method Summary

void	destroy() Free resources allocated by the service for this execution.
ExecutionException[]	getExceptions() Get the exceptions which caused the stored process to complete with a status of STATUS_SAS_EXCEPTION_OCCURRED or STATUS_EXCEPTION_OCCURRED.
java.io.InputStream	getInputStream(java.lang.Object streamKey) Get an input stream.
com.sas.io.InputStreamHeaderInterface	getInputStreamHeader(java.lang.String streamKey) Get the stream header for an input stream.
java.io.OutputStream	getOutputStream(java.lang.Object streamKey) Get an output stream.
com.sas.io.OutputStreamHeaderInterface	getOutputStreamHeader(java.lang.String streamKey) Get the stream header for an output stream.
ResultPackageInterface	getResultPackage() Get the package produced by the execution of the stored process.
int	getSASConditionCode() Get the SAS condition code associated with the execution of the stored process.
java.lang.String	getSessionID() Get the session id associated with this execution.
int	getStatus() Get the status of this execution.
StoredProcessAlertItemInterface	getStoredProcessAlert() Get the stored process alert item associated with this execution.
boolean	isSynchronous() Is the stored process being executed synchronously?
java.lang.String	readSASLog(int flag, int maxLines) Read the SAS log associated with this execution.
int	waitForCompletion() Wait until the stored process completes execution.
int	waitForCompletion(long milliSecondTimeout) Wait until the stored process completes execution or until the time specified has elapsed.

Field Detail

STATUS_EXECUTING

static final int STATUS_EXECUTING

The stored process is executing. This is one of the values returned by getStatus().

See Also:

Constant Field Values

STATUS_SAS_EXCEPTION_OCCURRED

static final int STATUS_SAS_EXCEPTION_OCCURRED

An exception occurred during the setup or execution stage of the stored process. This is one of the values returned by getStatus(). Setting of this code implies the stored process did not complete execution. The exception can be obtained using getExceptions().

See Also:

Constant Field Values

STATUS_COMPLETED_WITHOUT_EXCEPTION

static final int STATUS_COMPLETED_WITHOUT_EXCEPTION

The stored process has completed execution without any exception. This is one of the values returned by getStatus().

See Also:

Constant Field Values

STATUS_EXCEPTION_OCCURRED

static final int STATUS_EXCEPTION_OCCURRED

The execution of the stored process resulted in an exception. This is one of the values returned by getStatus(). The exception can be obtained using getExceptions(). The SAS log can be be obtained by invoking readSASLog(int, int).

See Also:

Constant Field Values

STATUS_DESTROYED

static final int STATUS_DESTROYED

The destroy method has been called. This value can only returned by waitForCompletion() or waitForCompletion(long). This value is only returned if destroy() gets called before waitForCompletion returns.

See Also:

Constant Field Values

LOG_ALL_LINES

static final int LOG_ALL_LINES

Get all lines of the log. The log can be obtained by invoking readSASLog(int, int).

See Also:

Constant Field Values

LOG_FORMAT_TEXT

static final int LOG_FORMAT_TEXT

Format the log as "text". The log can be obtained by invoking readSASLog(int, int).

See Also:

Constant Field Values

LOG_FORMAT_HTML

static final int LOG_FORMAT_HTML

Format the log as "html". The log can be obtained by invoking readSASLog(int, int). Log lines will be marked up with HTML tags to indicate the type of log line. NOTE, INFO, WARNING and ERROR messages are highlighted.

See Also:

Constant Field Values

Method Detail

getResultPackage

ResultPackageInterface getResultPackage()
                                        throws java.lang.IllegalStateException,
                                               java.rmi.RemoteException

Get the package produced by the execution of the stored process.

See the sub-interface method (Execution2Interface.getResultPackage() or ExecutionInterface.getResultPackage() for more details.

Returns:

the package or null if there is none.

Throws:

java.rmi.RemoteException - if a network anomaly is encountered.

java.lang.IllegalStateException

getStatus

int getStatus()
              throws java.rmi.RemoteException

Get the status of this execution.

See the sub-interface method (Execution2Interface.getStatus() or ExecutionInterface.getStatus() for more details.

Throws:

java.lang.IllegalStateException - if destroy() has been called.

java.rmi.RemoteException - if a network anomaly is encountered.

isSynchronous

boolean isSynchronous()
                      throws java.rmi.RemoteException

Is the stored process being executed synchronously?

Throws:

java.lang.IllegalStateException - if destroy() has been called.

java.rmi.RemoteException - if a network anomaly is encountered.

getExceptions

ExecutionException[] getExceptions()
                                   throws java.rmi.RemoteException

Get the exceptions which caused the stored process to complete with a status of STATUS_SAS_EXCEPTION_OCCURRED or STATUS_EXCEPTION_OCCURRED.

Throws:

java.lang.IllegalStateException - if destroy() has been called.

java.rmi.RemoteException - if a network anomaly is encountered.

readSASLog

java.lang.String readSASLog(int flag,
                            int maxLines)
                            throws java.rmi.RemoteException,
                                   java.lang.IllegalStateException,
                                   TransportException

Read the SAS log associated with this execution. The method should only be called after execution is complete. The second parameter specifies the number of lines to be returned - all lines can be requested by specifying LOG_ALL_LINES. If a call does not return all lines available, subsequent calls to this method return lines in the log after those previously returned. Once all lines have been returned, any subsequent calls will return an empty string. System.getProperty("line.separator") is used to obtain the newline character sequence that is inserted after each line in the returned string. If LOG_FORMAT_HTML type output is requested the returned string is enclosed by "PRE" tags and another newline character sequence appended after the closing "PRE" tag.

Parameters:

flag - one of LOG_FORMAT_TEXT or LOG_FORMAT_HTML

maxLines - the maximum number of lines to get or LOG_ALL_LINES if all lines are needed

Returns:

a String containing the formatted log

Throws:

java.rmi.RemoteException - if a network anomaly is encountered.

java.lang.IllegalStateException - if the status is STATUS_EXECUTING or if destroy() has been called.

TransportException - if there is a problem communicating with the SAS server.

waitForCompletion

int waitForCompletion()
                      throws java.lang.InterruptedException,
                             java.rmi.RemoteException

Wait until the stored process completes execution. If the execution has completed it returns immediately; if not, it blocks (using Java's wait/notify mechanism) until the stored process completes execution.

Returns:

the completion status - same return value as would be obtained by calling getStatus().

Throws:

java.lang.IllegalStateException - if destroy() has been called.

java.lang.InterruptedException - if the thread executing the method is interrupted

java.rmi.RemoteException - if a network anomaly is encountered.

waitForCompletion

int waitForCompletion(long milliSecondTimeout)
                      throws java.lang.InterruptedException,
                             java.rmi.RemoteException

Wait until the stored process completes execution or until the time specified has elapsed. If the execution has completed it returns it returns immediately; if not, it blocks (using Java's wait/notify mechanism) until the stored process completes execution or the time specified has elapsed.

Parameters:

milliSecondTimeout - - the maximum time to wait in milliseconds

Returns:

the completion status - same return value as would be obtained by calling getStatus().

Throws:

java.lang.IllegalStateException - if destroy() has been called.

java.lang.InterruptedException - if the thread executing the method is interrupted

java.rmi.RemoteException - if a network anomaly is encountered.

destroy

void destroy()
             throws java.rmi.RemoteException,
                    java.lang.IllegalStateException,
                    ConnectionFactoryException,
                    TransportException

Free resources allocated by the service for this execution. This method is called after the client has processed all output from the stored process to perform resource cleanup. The following is done:

• If the stored process delivers a package the package is closed unless the life cycle of the package is not bound to the execution interface.
• If a connection was obtained from the connection service by the stored process service the connection is released.
• Frees any logger associated with this object.

If the stored process is executed asynchronously and this method is called while the stored process is still executing an IllegalStateException will be thrown by this method. For such use cases, it's recommended that waitForCompletion() be called before the call to this method.

Throws:

ConnectionFactoryException - if thrown by the Connection Service when closing the connection

java.lang.IllegalStateException - if the status is STATUS_EXECUTING or this method is called a second time.

TransportException - if there is a problem communicating with the SAS server.

java.rmi.RemoteException - if a network anomaly is encountered.

getSessionID

java.lang.String getSessionID()
                              throws java.lang.IllegalStateException,
                                     java.rmi.RemoteException

Get the session id associated with this execution.

See the sub-interface method (Execution2Interface.getSessionID() or ExecutionInterface.getSessionID() for more details.

Returns:

the session id or null if there is no session id associated with the execution.

Throws:

java.rmi.RemoteException - if a network anomaly is encountered.

java.lang.IllegalStateException

getStoredProcessAlert

StoredProcessAlertItemInterface getStoredProcessAlert()
                                                      throws java.rmi.RemoteException

Get the stored process alert item associated with this execution. An alert is created if StoredProcessInterface's execute method was called with its createAlert parameter set to true.

Returns:

the alert item associated with this execution or null if there is none.

Throws:

java.lang.IllegalStateException - if destroy() has been called.

java.rmi.RemoteException - if a network anomaly is encountered.

getInputStream

java.io.InputStream getInputStream(java.lang.Object streamKey)
                                   throws java.lang.IllegalStateException,
                                          java.rmi.RemoteException

Get an input stream. Input streams are only available for stored processes with server type StoredProcessBaseInterface.SERVER_TYPE_STOREDPROCESS. See the sub-interface method (Execution2Interface.getInputStream(Object) or ExecutionInterface.getInputStream(Object) for more details.

Parameters:

streamKey - an object whose toString method provides the stream name.

Returns:

A serializable object which implements InputStream or null if not available

Throws:

java.lang.IllegalStateException - if destroy() has been called.

java.rmi.RemoteException - if a network anomaly is encountered.

getOutputStream

java.io.OutputStream getOutputStream(java.lang.Object streamKey)
                                     throws java.lang.IllegalStateException,
                                            java.rmi.RemoteException

Get an output stream. Output streams are only available for stored processes with server type StoredProcessBaseInterface.SERVER_TYPE_STOREDPROCESS.

Parameters:

streamKey - an object whose toString method provides the stream name.

Returns:

A serializable object which implements OutputStream or null if not available

Throws:

java.lang.IllegalStateException - if destroy() has been called.

java.rmi.RemoteException - if a network anomaly is encountered.

getInputStreamHeader

com.sas.io.InputStreamHeaderInterface getInputStreamHeader(java.lang.String streamKey)
                                                           throws java.rmi.RemoteException

Get the stream header for an input stream. An input stream header can only be obtained if the corresponding input stream is available.

Parameters:

streamKey - names the input stream.

Returns:

the stream header for the input stream specified or null if not available

Throws:

java.lang.IllegalStateException - if destroy() has been called.

java.rmi.RemoteException - if a network anomaly is encountered.

getOutputStreamHeader

com.sas.io.OutputStreamHeaderInterface getOutputStreamHeader(java.lang.String streamKey)
                                                             throws java.rmi.RemoteException

Get the stream header for an output stream. An output stream header can only be obtained if the corresponding output stream is available.

Parameters:

streamKey - names the output stream.

Returns:

the stream header for the output stream specified or null if not available

Throws:

java.lang.IllegalStateException - if destroy() has been called.

java.rmi.RemoteException - if a network anomaly is encountered.

getSASConditionCode

int getSASConditionCode()
                        throws java.rmi.RemoteException

Get the SAS condition code associated with the execution of the stored process. For stored processes run on a Workspace server the condition code is not available and a value of zero is returned.

Returns:

the SAS condition code.

Throws:

java.rmi.RemoteException - if a network anomaly is encountered.

java.lang.IllegalStateException - if the status is STATUS_EXECUTING or STATUS_SAS_EXCEPTION_OCCURRED, or if destroy() has been called.

*** This interface provides Binary Compatibility only, not Source Compatibility ***