Execution2Interface (SAS Foundation Services)

This interface describes various aspects associated with the execution of a stored process. See the package description documentation for usage information.

Since:: 9.2

Field Summary

static int STATUS_ABORTED
          The abort method has been called.

static int STATUS_WAITING_FOR_CONNECTION
          The stored process is waiting for a connection to become available.

Fields inherited from interface com.sas.services.storedprocess.ExecutionBaseInterface

LOG_ALL_LINES, LOG_FORMAT_HTML, LOG_FORMAT_TEXT, STATUS_COMPLETED_WITHOUT_EXCEPTION, STATUS_DESTROYED, STATUS_EXCEPTION_OCCURRED, STATUS_EXECUTING, STATUS_SAS_EXCEPTION_OCCURRED

Method Summary

void abort()
          Abort execution of the stored process.

void destroy()
          Free resources allocated by the service for this execution.

java.io.InputStream getInputStream(java.lang.Object streamKey)
          Get an input stream.

OutputParameterInterface getOutputParameter(java.lang.String name)
          Get the OutputParameterInterface object corresponding to the output parameter (SAS macro variable) name specified from the list returned by getOutputParameters().

java.util.List<OutputParameterInterface> getOutputParameters()
          Returns the list of output parameters as OutputParameterInterface objects.

java.io.OutputStream getOutputStream(java.lang.Object streamKey)
          Get 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.

SASLog getSASListing()
          Get the SAS listing associated with this execution.

SASLog getSASListing(int maxLines)
          Get the SAS listing associated with this execution.

SASLog getSASLog()
          /** Get the SAS log associated with this execution.

SASLog getSASLog(int maxLines)
          Get the SAS log associated with this execution.

java.lang.String getSessionID()
          Get the session id associated with this execution.

int getStatus()
          Get the status of this execution.

java.lang.String readSASLog(int flag, int maxLines)
          Read the SAS log associated with this execution.

void setResultPackageLifeCycleBound(boolean boundToLifeCycle)
          Sets whether the life-cycle of the package is bound to the Execution2Interface.

int waitForConnection()
          Wait until a connection to the server is available.

int waitForConnection(long milliSecondTimeout)
          Wait until a connection to the server is available or until the time specified has elapsed.

Methods inherited from interface com.sas.services.storedprocess.ExecutionBaseInterface

getExceptions, getInputStreamHeader, getOutputStreamHeader, getStoredProcessAlert, isSynchronous, waitForCompletion, waitForCompletion

Field Summary
`static int`	`STATUS_ABORTED` The abort method has been called.
`static int`	`STATUS_WAITING_FOR_CONNECTION` The stored process is waiting for a connection to become available.

Fields inherited from interface com.sas.services.storedprocess.ExecutionBaseInterface
`LOG_ALL_LINES, LOG_FORMAT_HTML, LOG_FORMAT_TEXT, STATUS_COMPLETED_WITHOUT_EXCEPTION, STATUS_DESTROYED, STATUS_EXCEPTION_OCCURRED, STATUS_EXECUTING, STATUS_SAS_EXCEPTION_OCCURRED`

Method Summary
`void`	`abort()` Abort execution of the stored process.
`void`	`destroy()` Free resources allocated by the service for this execution.
`java.io.InputStream`	`getInputStream(java.lang.Object streamKey)` Get an input stream.
`OutputParameterInterface`	`getOutputParameter(java.lang.String name)` Get the `OutputParameterInterface` object corresponding to the output parameter (SAS macro variable) name specified from the list returned by `getOutputParameters()`.
`java.util.List<OutputParameterInterface>`	`getOutputParameters()` Returns the list of output parameters as `OutputParameterInterface` objects.
`java.io.OutputStream`	`getOutputStream(java.lang.Object streamKey)` Get 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.
`SASLog`	`getSASListing()` Get the SAS listing associated with this execution.
`SASLog`	`getSASListing(int maxLines)` Get the SAS listing associated with this execution.
`SASLog`	`getSASLog()` /** Get the SAS log associated with this execution.
`SASLog`	`getSASLog(int maxLines)` Get the SAS log associated with this execution.
`java.lang.String`	`getSessionID()` Get the session id associated with this execution.
`int`	`getStatus()` Get the status of this execution.
`java.lang.String`	`readSASLog(int flag, int maxLines)` Read the SAS log associated with this execution.
`void`	`setResultPackageLifeCycleBound(boolean boundToLifeCycle)` Sets whether the life-cycle of the package is bound to the `Execution2Interface`.
`int`	`waitForConnection()` Wait until a connection to the server is available.
`int`	`waitForConnection(long milliSecondTimeout)` Wait until a connection to the server is available or until the time specified has elapsed.

Methods inherited from interface com.sas.services.storedprocess.ExecutionBaseInterface
`getExceptions, getInputStreamHeader, getOutputStreamHeader, getStoredProcessAlert, isSynchronous, waitForCompletion, waitForCompletion`

Field Detail

STATUS_ABORTED

static final int STATUS_ABORTED

The abort method has been called. This is one of the values returned by getStatus().

See Also:: Constant Field Values

STATUS_WAITING_FOR_CONNECTION

static final int STATUS_WAITING_FOR_CONNECTION

The stored process is waiting for a connection to become available. This is one of the values returned by getStatus() and is returned if StoredProcess2Interface.executeAsynch(ExecutionStatusListener2Interface, boolean) is called and a server is not available.

See Also:: Constant Field Values

Method Detail

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 ExecutionBaseInterface.waitForCompletion() be called before the call to this method.

Specified by:: destroy in interface ExecutionBaseInterface

Throws:: ConnectionFactoryException - if thrown by the Connection Service when closing the connection; java.lang.IllegalStateException - if the status is STATUS_WAITING_FOR_CONNECTION, ExecutionBaseInterface.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.

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. Either the stream needs to be defined as a data target, or, in the case of _WEBOUT, streaming capability should be selected for execution.

If execution is via StoredProcess2Interface.executeAsynch(ExecutionStatusListener2Interface, boolean), this method blocks on waitForConnection() if a connection to the server is not available.

Specified by:: getInputStream in interface ExecutionBaseInterface

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.

If execution is via StoredProcess2Interface.executeAsynch(ExecutionStatusListener2Interface, boolean), this method blocks on waitForConnection() if a connection to the server is not available.

Specified by:: getOutputStream in interface ExecutionBaseInterface

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.

getOutputParameters

java.util.List<OutputParameterInterface> getOutputParameters()
                                                             throws TransportException,
                                                                    java.rmi.RemoteException

Returns the list of output parameters as OutputParameterInterface objects. All output parameters defined in metadata are automatically present in this list. However, the list may also contain items not defined in metadata as described in getOutputParameter(String).

For stored processes run on a Workspace server this functionality is unavailable and an IllegalStateException is thrown.

Throws:: java.lang.IllegalStateException - if the status is STATUS_WAITING_FOR_CONNECTION, ExecutionBaseInterface.STATUS_EXECUTING or ExecutionBaseInterface.STATUS_SAS_EXCEPTION_OCCURRED, or if destroy() has been called.; java.rmi.RemoteException - if a network anomaly is encountered.; TransportException

getOutputParameter

OutputParameterInterface getOutputParameter(java.lang.String name)
                                            throws TransportException,
                                                   java.rmi.RemoteException

Get the OutputParameterInterface object corresponding to the output parameter (SAS macro variable) name specified from the list returned by getOutputParameters().

If no output parameter with that name is found in the list, the server is queried to see if a value is associated with that SAS macro name. If there is no value, a null is returned. If there is a value, a OutputParameterInterface with type String for that name is created and returned; also, the newly created OutputParameterInterface is added to the list of output parameters returned by getOutputParameters().

For stored processes run on a Workspace server this functionality is unavailable and an IllegalStateException is thrown.

Parameters:: name - the name of the output parameter whose value is desired.
Returns:: the OutputParameterInterface for the name specified
Throws:: java.lang.IllegalStateException - if the status is STATUS_WAITING_FOR_CONNECTION, ExecutionBaseInterface.STATUS_EXECUTING, ExecutionBaseInterface.STATUS_SAS_EXCEPTION_OCCURRED, or if destroy() has been called.; TransportException - if there is a problem communicating with the SAS server.; java.rmi.RemoteException - if a network anomaly is encountered.

getResultPackage

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

Get the package produced by the execution of the stored process. Packages are only available for those stored processes which the service is aware are creating packages which are SAS server based or DAV server based.

Specified by:: getResultPackage in interface ExecutionBaseInterface

Returns:: the package or null if there is none.
Throws:: java.rmi.RemoteException - if a network anomaly is encountered.; java.lang.IllegalStateException - if the status is STATUS_WAITING_FOR_CONNECTION, ExecutionBaseInterface.STATUS_EXECUTING, ExecutionBaseInterface.STATUS_SAS_EXCEPTION_OCCURRED or STATUS_ABORTED, or if destroy() has been called.

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.

Specified by:: getSASConditionCode in interface ExecutionBaseInterface

Returns:: the SAS condition code.
Throws:: java.rmi.RemoteException - if a network anomaly is encountered.; java.lang.IllegalStateException - if the status is STATUS_WAITING_FOR_CONNECTION, ExecutionBaseInterface.STATUS_EXECUTING or ExecutionBaseInterface.STATUS_SAS_EXCEPTION_OCCURRED, or if destroy() has been called.

setResultPackageLifeCycleBound

void setResultPackageLifeCycleBound(boolean boundToLifeCycle)
                                    throws ResultsBindingException,
                                           java.rmi.RemoteException,
                                           java.lang.IllegalStateException

Sets whether the life-cycle of the package is bound to the Execution2Interface. By default, the life-cycle of the package is bound to the Execution2Interface. If it is, the package is closed when destroy() is called. This method is called before the result pacakge is accessed via getResultPackage().

Parameters:: boundToLifeCycle - true - package is closed by ExecutionInteface's destroy(); false - package life controlled by consumer.
Throws:: ResultsBindingException - if there is no result package or an exception occurs making a copy; java.lang.IllegalStateException - if called after getResultPackage() is accessed or if called a second time with a different argument; java.rmi.RemoteException - if a network anomaly is encountered.

getStatus

int getStatus()
              throws java.rmi.RemoteException

Get the status of this execution.

If the stored process is executing STATUS_EXECUTING is returned. If it has completed, one of STATUS_COMPLETED_WITHOUT_EXCEPTION, STATUS_SAS_EXCEPTION_OCCURRED or STATUS_EXCEPTION_OCCURRED is returned depending on how execution terminated. If stored process execution was aborted by using the abort() method, STATUS_ABORTED is returned unless execution was complete at the time of the abort.

Note: if the exception is due to the more specific reasons specified in STATUS_SAS_EXCEPTION_OCCURRED then STATUS_SAS_EXCEPTION_OCCURRED is returned over the more generic STATUS_EXCEPTION_OCCURRED.

Specified by:: getStatus in interface ExecutionBaseInterface

Throws:: java.lang.IllegalStateException - if destroy() has been called.; java.rmi.RemoteException - if a network anomaly is encountered.

abort

void abort()
           throws java.rmi.RemoteException,
                  TransportException

Abort execution of the stored process. This method can only be called to abort the stored process if the stored process is executed by invoking StoredProcess2Interface.executeAsynch(ExecutionStatusListener2Interface, boolean) or asynchronously via StoredProcess2Interface.execute(boolean, ExecutionStatusListener2Interface, boolean, Object); however, if execute() has been called synchronously this Execution2Interface object is not available until after execution is completed and no purpose would be served by calling abort.

If the stored process has not completed execution at the time this method is called, the stored process is interrupted (if execution has begun) and the status returned by getStatus() is STATUS_ABORTED. If the stored process has completed execution at the time this method is called there is no change in the value returned by the getStatus().

If executeAsynch() was used and execution of the stored process is waiting for a connection to become available, this method does not interrupt that process. However, once a connection does become available execution will not occur due to the pending abort().

The following items, if applicable, may be obtained from an aborted stored process:

the SAS log (see ExecutionBaseInterface.readSASLog(int, int))
output parameters (see getOutputParameter(String) or getOutputParameters())
the SAS condition code (see ExecutionBaseInterface.getSASConditionCode())

Throws:: java.lang.IllegalStateException - if destroy() has been called or if the stored process is being executed synchronously; java.rmi.RemoteException - if a network anomaly is encountered.; TransportException - if there is a problem communicating with the SAS server.

getSessionID

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

Get the session id associated with this execution. Session ids are unique to stored process executions under the StoredProcess server.

Specified by:: getSessionID in interface ExecutionBaseInterface

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 - if the status is STATUS_WAITING_FOR_CONNECTION, ExecutionBaseInterface.STATUS_EXECUTING, ExecutionBaseInterface.STATUS_SAS_EXCEPTION_OCCURRED or STATUS_ABORTED, or if destroy() has been called.

getSASLog

SASLog getSASLog()
                 throws java.rmi.RemoteException,
                        java.lang.IllegalStateException,
                        TransportException

/** Get the SAS log associated with this execution. The method returns all the lines of the log that are yet to be obtained - a specified number of lines can be obtained by invoking the getSASLog(int) method. Any subsequent calls to obtain the SAS log return an empty object.

The method should only be called after execution is complete.

Returns:: a SASLog object containing the log
Throws:: java.rmi.RemoteException - if a network anomaly is encountered.; java.lang.IllegalStateException - if the status is STATUS_WAITING_FOR_CONNECTION, ExecutionBaseInterface.STATUS_EXECUTING or if destroy() has been called.; TransportException - if there is a problem communicating with the SAS server.

getSASLog

SASLog getSASLog(int maxLines)
                 throws java.rmi.RemoteException,
                        java.lang.IllegalStateException,
                        TransportException

Get the SAS log associated with this execution. The parameter specifies the number of lines to be returned - all lines in the log can be requested by invoking the getSASLog() method. If a call does not return all lines available, subsequent calls to obtain remaining SAS log lines return lines in the log after those previously returned. Once all lines have been returned, any subsequent call returns an empty object.

The method should only be called after execution is complete.

Parameters:: maxLines - the maximum number of lines to get
Returns:: a SASLog object containing the log
Throws:: java.rmi.RemoteException - if a network anomaly is encountered.; java.lang.IllegalStateException - if the status is STATUS_WAITING_FOR_CONNECTION, ExecutionBaseInterface.STATUS_EXECUTING or if destroy() has been called.; TransportException - if there is a problem communicating with the SAS server.

getSASListing

SASLog getSASListing()
                     throws java.rmi.RemoteException,
                            java.lang.IllegalStateException,
                            TransportException

Get the SAS listing associated with this execution. The method returns all the lines of the listing that are yet to be obtained - a specified number of lines can be obtained by invoking the getSASListing(int) method. Any subsequent calls to this method or to getSASListing(int) return an empty object.

The method should only be called after execution is complete.

Returns:: a SASLog object containing the listing
Throws:: java.rmi.RemoteException - if a network anomaly is encountered.; java.lang.IllegalStateException - if the status is STATUS_WAITING_FOR_CONNECTION, ExecutionBaseInterface.STATUS_EXECUTING or if destroy() has been called.; TransportException - if there is a problem communicating with the SAS server.

getSASListing

SASLog getSASListing(int maxLines)
                     throws java.rmi.RemoteException,
                            java.lang.IllegalStateException,
                            TransportException

Get the SAS listing associated with this execution. The parameter specifies the number of lines to be returned - all lines in the listing can be requested by invoking the getSASListing() method. If a call does not return all lines available, subsequent calls to this method or to getSASListing() return lines in the listing after those previously returned. Once all lines have been returned, any subsequent calls will return an empty object.

The method should only be called after execution is complete.

Parameters:: maxLines - the maximum number of lines to get
Returns:: a SASLog object containing the listing
Throws:: java.rmi.RemoteException - if a network anomaly is encountered.; java.lang.IllegalStateException - if the status is STATUS_WAITING_FOR_CONNECTION, ExecutionBaseInterface.STATUS_EXECUTING or if destroy() has been called.; TransportException - if there is a problem communicating with the SAS server.

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. Once "read", subsequent calls to this method will return lines in the log after those previously returned. If a call requests all lines (ExecutionBaseInterface.LOG_ALL_LINES) or more lines than are present, that call returns the lines available but subsequent calls return an empty string unless there has been output to the log after that call. System.getProperty("line.separator") is used to obtain the newline character sequence that is inserted after each line in the returned string. If ExecutionBaseInterface.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.

Specified by:: readSASLog in interface ExecutionBaseInterface

Parameters:: flag - one of ExecutionBaseInterface.LOG_FORMAT_TEXT or ExecutionBaseInterface.LOG_FORMAT_HTML; maxLines - the maximum number of lines to get or ExecutionBaseInterface.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_WAITING_FOR_CONNECTION, ExecutionBaseInterface.STATUS_EXECUTING or if destroy() has been called.; TransportException - if there is a problem communicating with the SAS server.

waitForConnection

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

Wait until a connection to the server is available. Besides a server becoming available, the method also waits for streams, if defined, to be connected. If the connections are done it returns immediately; if not, it blocks (using Java's wait/notify mechanism) until the connections are made.

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.
See Also:: StoredProcess2Interface.executeAsynch(ExecutionStatusListener2Interface, boolean)

waitForConnection

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

Wait until a connection to the server is available or until the time specified has elapsed. Besides a server becoming available, the method also waits for streams, if defined, to be connected. If the connections are done it returns immediately; if not, it blocks (using Java's wait/notify mechanism) until the connections are made 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.
See Also:: StoredProcess2Interface.executeAsynch(ExecutionStatusListener2Interface, boolean)

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

All Libraries

This Library

Package

Class

Use

Tree

Deprecated

Index

Grand Index

Help

Foundation

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.sas.services.storedprocess Interface Execution2Interface

STATUS_ABORTED

STATUS_WAITING_FOR_CONNECTION

destroy

getInputStream

getOutputStream

getOutputParameters

getOutputParameter

getResultPackage

getSASConditionCode

setResultPackageLifeCycleBound

getStatus

abort

getSessionID

getSASLog

getSASLog

getSASListing

getSASListing

readSASLog

waitForConnection

waitForConnection

com.sas.services.storedprocess
Interface Execution2Interface