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

Package com.sas.services.storedprocess

# Interface ExecutionBaseInterface

All Superinterfaces:
  `Remote`

All Known Subinterfaces:
  `Execution2Interface`, `ExecutionInterface`

@SASScope("ALL") @BinaryCompatibilityOnly public interface ExecutionBaseInterface extends Remote
This interface describes various common aspects associated with the execution of a stored process.

Since:
  9.2

- ## Field Summary

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

- ## Method Summary

  Modifier and Type
  Method
  Description
  `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`.
  `InputStream`
  `getInputStream(Object streamKey)`
  Get an input stream.
  `com.sas.io.InputStreamHeaderInterface`
  `getInputStreamHeader(String streamKey)`
  Get the stream header for an input stream.
  `OutputStream`
  `getOutputStream(Object streamKey)`
  Get an output stream.
  `com.sas.io.OutputStreamHeaderInterface`
  `getOutputStreamHeader(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.
  `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?
  `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 Details

  - ### 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 Details

  - ### getResultPackage

    ResultPackageInterface getResultPackage() throws IllegalStateException, 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:
      `RemoteException` - if a network anomaly is encountered.
      `IllegalStateException`

  - ### getStatus

    int getStatus() throws RemoteException
    Get the status of this execution.

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

    Throws:
      `IllegalStateException` - if destroy() has been called.
      `RemoteException` - if a network anomaly is encountered.

  - ### isSynchronous

    boolean isSynchronous() throws RemoteException
    Is the stored process being executed synchronously?
    Throws:
      `IllegalStateException` - if destroy() has been called.
      `RemoteException` - if a network anomaly is encountered.

  - ### getExceptions

    ExecutionException[] getExceptions() throws RemoteException
    Get the exceptions which caused the stored process to complete with a status of `STATUS_SAS_EXCEPTION_OCCURRED` or `STATUS_EXCEPTION_OCCURRED`.
    Throws:
      `IllegalStateException` - if destroy() has been called.
      `RemoteException` - if a network anomaly is encountered.

  - ### readSASLog

    String readSASLog(int flag, int maxLines) throws RemoteException, 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:
      `RemoteException` - if a network anomaly is encountered.
      `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 InterruptedException, 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:
      `IllegalStateException` - if destroy() has been called.
      `InterruptedException` - if the thread executing the method is interrupted
      `RemoteException` - if a network anomaly is encountered.

  - ### waitForCompletion

    int waitForCompletion(long milliSecondTimeout) throws InterruptedException, 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:
      `IllegalStateException` - if destroy() has been called.
      `InterruptedException` - if the thread executing the method is interrupted
      `RemoteException` - if a network anomaly is encountered.

  - ### destroy

    void destroy() throws RemoteException, 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
      `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.
      `RemoteException` - if a network anomaly is encountered.

  - ### getSessionID

    String getSessionID() throws IllegalStateException, 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:
      `RemoteException` - if a network anomaly is encountered.
      `IllegalStateException`

  - ### getStoredProcessAlert

    StoredProcessAlertItemInterface getStoredProcessAlert() throws 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:
      `IllegalStateException` - if destroy() has been called.
      `RemoteException` - if a network anomaly is encountered.

  - ### getInputStream

    InputStream getInputStream(Object streamKey) throws IllegalStateException, 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:
      `IllegalStateException` - if destroy() has been called.
      `RemoteException` - if a network anomaly is encountered.

  - ### getOutputStream

    OutputStream getOutputStream(Object streamKey) throws IllegalStateException, 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:
      `IllegalStateException` - if destroy() has been called.
      `RemoteException` - if a network anomaly is encountered.

  - ### getInputStreamHeader

    com.sas.io.InputStreamHeaderInterface getInputStreamHeader(String streamKey) throws 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:
      `IllegalStateException` - if destroy() has been called.
      `RemoteException` - if a network anomaly is encountered.

  - ### getOutputStreamHeader

    com.sas.io.OutputStreamHeaderInterface getOutputStreamHeader(String streamKey) throws 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:
      `IllegalStateException` - if destroy() has been called.
      `RemoteException` - if a network anomaly is encountered.

  - ### getSASConditionCode

    int getSASConditionCode() throws 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:
      `RemoteException` - if a network anomaly is encountered.
      `IllegalStateException` - if the status is `STATUS_EXECUTING` or `STATUS_SAS_EXCEPTION_OCCURRED`, or if destroy() has been called.