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

  • 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:

      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:

    • 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: