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

Package com.sas.services.storedprocess

# Interface Execution2Interface

All Superinterfaces:
  `ExecutionBaseInterface`, `Remote`

@SASScope("ALL") @BinaryCompatibilityOnly public interface Execution2Interface extends ExecutionBaseInterface
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

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `STATUS_ABORTED`
  The abort method has been called.
  `static final 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

  Modifier and Type
  Method
  Description
  `void`
  `abort()`
  Abort execution of the stored process.
  `void`
  `destroy()`
  Free resources allocated by the service for this execution.
  `InputStream`
  `getInputStream(Object streamKey)`
  Get an input stream.
  `OutputParameterInterface`
  `getOutputParameter(String name)`
  Get the `OutputParameterInterface` object corresponding to the output parameter (SAS macro variable) name specified from the list returned by `getOutputParameters()`.
  `List<OutputParameterInterface>`
  `getOutputParameters()`
  Returns the list of output parameters as `OutputParameterInterface` objects.
  `OutputStream`
  `getOutputStream(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.
  `String`
  `getSessionID()`
  Get the session id associated with this execution.
  `int`
  `getStatus()`
  Get the status of this execution.
  `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 Details

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

  - ### 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 `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
      `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.
      `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`. 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:
      `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`.

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

  - ### getOutputParameters

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

  - ### getOutputParameter

    OutputParameterInterface getOutputParameter(String name) throws TransportException, 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:
      `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.
      `RemoteException` - if a network anomaly is encountered.

  - ### getResultPackage

    ResultPackageInterface getResultPackage() throws IllegalStateException, 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:
      `RemoteException` - if a network anomaly is encountered.
      `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 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:
      `RemoteException` - if a network anomaly is encountered.
      `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, RemoteException, 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
      `IllegalStateException` - if called after getResultPackage() is accessed or if called a second time with a different argument
      `RemoteException` - if a network anomaly is encountered.

  - ### getStatus

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

  - ### abort

    void abort() throws 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:
      `IllegalStateException` - if destroy() has been called or if the stored process is being executed synchronously
      `RemoteException` - if a network anomaly is encountered.
      `TransportException` - if there is a problem communicating with the SAS server.

  - ### getSessionID

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

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

  - ### waitForConnection

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