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

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

## com.sas.services.storedprocess
Interface StoredProcess2Interface

All Superinterfaces:
  java.rmi.Remote, StoredProcessBaseInterface

    public interface StoredProcess2Interface

extends StoredProcessBaseInterface

This interface describes the second generation of the stored process service object. It extends `StoredProcessBaseInterface` which contains the methods common to both this interface and `StoredProcessInterface`. The interface supports stored processes in the Version 1 metadata format introduced in 9.2 as well as stored processes in the Version 2 metadata format introduced in 9.3.

Stored process objects are either created by the Information Service from metadata or manually by the user using methods provided by `StoredProcessServiceInterface`

If the stored process is created by the Information Service from metadata, setters cannot be used to modify most properties of the stored process. If a setter is invoked an IllegalStateException will be thrown - the doc on each setter describes whether this is applicable to the setter.

When this service object is constructed, the parameters of the Stored Process are deserialized into a `PromptGroupInterface` rooted hierarchy and a new `PromptValues` object is constructed using this PromptGroupInterface. This `PromptValuesInterface` is available via `getPromptValues()` and can be used for parameter manipulation. The PromptGroupInterface is available from the PromptValuesInterface. If there are required parameters their values must be supplied and the service enforces this requirement.

If manually created, setters to set the file name, directory and connection must be invoked. If there are required parameters their values should be supplied. However, the service has no way of enforcing this requirement.

This parameter model is based on the Prompting Framework and a good understanding of that framework is needed to to fully exploit it.

Since:
  9.2

Field Summary
`static int` | `RESULT_TYPE_NONE` No package or stream is delivered by the stored process service.
`static int` | `RESULT_TYPE_PACKAGE` A package is delivered by the stored process service via the `ExecutionBaseInterface.getResultPackage()` method.
`static int` | `RESULT_TYPE_STREAM` Results are delivered via one of more Streams.

Fields inherited from interface com.sas.services.storedprocess.StoredProcessBaseInterface
`SERVER_TYPE_STOREDPROCESS, SERVER_TYPE_WORKSPACE`

Method Summary
`boolean` | `addInputStream(java.lang.String streamKey)` Adds an input stream definition to the stored process.
`boolean` | `addOutputStream(java.lang.String streamKey, boolean isMultiPass)` Adds an output stream definition to the stored process.
`Execution2Interface` | `execute(boolean synchronous, ExecutionStatusListener2Interface listener, boolean createAlert, java.lang.Object connection)` Execute the stored process.
`Execution2Interface` | `executeAsynch(ExecutionStatusListener2Interface listener, boolean createAlert)` Execute the stored process asynchronously.
`java.lang.String` | `getClientName()` Returns the client name.
`ConnectionInterface` | `getConnection()` Get a connection for stored process execution.
`java.util.List<GenericStream>` | `getDataSources()` Returns a list of the stream data sources.
`java.util.List<GenericStream>` | `getDataTargets()` Returns a list of stream data targets.
`java.lang.String[]` | `getInputStreamNames()` Deprecated. Use `getDataTargets()`. Returns the fileref names of the `GenericStream` and `XMLStream` objects returned by getDataTargets().
`OutputParameterInterface` | `getOutputParameter(java.lang.String name)` Return the `OutputParameterInterface` object corresponding to the name requested.
`java.util.List<OutputParameterInterface>` | `getOutputParameters()` Return a list of output parameters defined in metadata as `OutputParameterInterface` objects.
`java.lang.String[]` | `getOutputStreamNames()` Deprecated. Use `getDataSources()`. Returns the fileref names of the `GenericStream` and `XMLStream` objects returned by getDataSources().
`com.sas.prompts.definitions.PromptDefinitionInterface[]` | `getParameters()` Gets parameter descriptions.
`java.lang.Object` | `getParameterValue(java.lang.String parameterName)` Gets the value of a parameter.
`com.sas.prompts.PromptValuesInterface` | `getPromptValues()` Returns the PromptValuesInterface associated with this Stored Process service object.
`int` | `getResultType()` Gets the type of result delivered by the service.
`LogicalServerInterface` | `getServer()` Get the the logical server the stored process runs on.
`int` | `getServerType()` Get the type of server that the stored process runs on.
`boolean` | `isPackageCapable()` Does the stored process have the result capability of package enabled.
`boolean` | `isStreamCapable()` Does the stored process have the result capability of stream enabled.
`void` | `setClientName(java.lang.String clientName)` Sets the client name.
`void` | `setInputDataTable(java.lang.String tableName, java.io.InputStream inputStream, java.lang.String memberName, java.lang.String xmlLibraryOptions)` Specifies client side input to be used for the table via the XML libname engine.
`void` | `setInputDataTable(java.lang.String tableName, java.lang.String libref, java.lang.String memberName)` Specifies the two level name for a server side input table.
`void` | `setInputFileref(java.lang.String fileref, java.io.InputStream inputStream)` Associates a client supplied binary file with the fileref.
`void` | `setInputFileref(java.lang.String fileref, java.io.Reader reader)` Associates a client supplied text file with the fileref.
`void` | `setInputFileref(java.lang.String fileref, java.lang.String engine, java.lang.String path, java.lang.String options)` Associates a path on the server with the fileref used for input.
`void` | `setLogicalServerType(com.sas.services.storedprocess.metadata.StoredProcessInterface.LogicalServerType logicalServerType)` Sets the type of logical server to be used for execution.
`void` | `setOutputDataTable(java.lang.String tableName, java.io.OutputStream outputStream, java.lang.String memberName, java.lang.String xmlLibraryOptions)` Specifies client side output to be used for the table via the XML libname engine.
`void` | `setOutputDataTable(java.lang.String tableName, java.lang.String libref, java.lang.String memberName)` Specifies the two level name for a server side output table.
`void` | `setOutputFileref(java.lang.String fileref, java.io.OutputStream outputStream)` Specifies the OutputStream to be used to write the output of the fileref to.
`void` | `setOutputFileref(java.lang.String fileref, java.lang.String engine, java.lang.String path, java.lang.String options)` Associates a path on the server with the fileref used for output.
`void` | `setOutputFileref(java.lang.String fileref, java.io.Writer writer)` Specifies the Writer to be used to write the output of the fileref to.
`com.sas.prompts.definitions.PromptDefinitionInterface` | `setParameterValue(java.lang.String name, java.lang.Object value)` Sets the value of the specified parameter on the PromptValues object associated with this stored process.
`java.util.Map` | `setParameterValues(java.util.Map map)` Sets the values of the specified parameters.
`java.util.List<com.sas.prompts.definitions.PromptDefinitionInterface>` | `setParameterValues(com.sas.prompts.PromptValuesInterface promptValues)` Sets values for the parameters of this Stored Process from the PromptValuesInterface supplied.
`void` | `setPromptValues(com.sas.prompts.PromptValuesInterface promptValues)` Sets the PromptValuesInterface associated with this Stored Process service object.
`void` | `setServerContext(ServerContextInterface serverContext)` Sets the server context to be used to execute the stored process.
`void` | `setSessionFreedOnDestroy(boolean sessionFreedOnDestroy)` Determines if the stored process server session is freed when `Execution2Interface.destroy()` is called.
`void` | `validatePromptValues()` Validates prompt values.

Methods inherited from interface com.sas.services.storedprocess.StoredProcessBaseInterface
`destroy, getDescription, getDirectory, getFileName, getName, hasParameters, setDescription, setName, setPrivilegedUser, setSourceFromFile`

Field Detail

### RESULT_TYPE_NONE

    static final int RESULT_TYPE_NONE

  No package or stream is delivered by the stored process service.

  See Also:
    `getResultType()`, Constant Field Values

### RESULT_TYPE_PACKAGE

    static final int RESULT_TYPE_PACKAGE

  A package is delivered by the stored process service via the `ExecutionBaseInterface.getResultPackage()` method.

  See Also:
    `getResultType()`, Constant Field Values

### RESULT_TYPE_STREAM

    static final int RESULT_TYPE_STREAM

  Results are delivered via one of more Streams.

  See Also:
    `getResultType()`, Constant Field Values

Method Detail

### execute

    Execution2Interface execute(boolean synchronous,
                                ExecutionStatusListener2Interface listener,
                                boolean createAlert,
                                java.lang.Object connection)
                                throws java.lang.IllegalStateException,
                                       ExecutionException,
                                       java.rmi.RemoteException

  Execute the stored process. A list of name-value pairs is created from the parameter list in the format expected by the server executing the stored process and is passed to the server. Results may be captured as an `alert` item in the Personal Repository.

  Execution of the stored process can be synchronous or asynchronous. In the synchronous case the method blocks until execution is complete. In the asynchronous case the method returns and the stored process is executed in a separate thread. Another alternative for asynchronous behavior is `executeAsynch(ExecutionStatusListener2Interface, boolean)`.

  A discussion of additional input parameters generated by the service can be found here.

  Depending on the type of parameter and the associated value, one or more name value pairs may be created to capture the value. Refer to the javadoc of the getMacroVariableValues method of the corresponding type in com.sas.datatypes for details.

  In both the synchronous and asynchronous cases this method does some preliminary processing synchronously and there is the potential for exceptions being thrown in this processing. These exceptions are listed in the throws clause and may occur when:

  - the parameter list is checked to ensure that all required parameters have values.
  - there is an inconsistency in the values of certain prompts or streams whose names can be considered "reserved".
  - there are two prompts with the same name.
  - the prompt is of a type which generates multiple prompt names which cause a conflict.
  - an attempt is made to obtain a connection to the server.
  - an `alert` is created (if requested).
  - there is a problem determining the WebDAV location to which results are published. This can only occur if _RESULT is set "PACKAGE_TO_WEBDAV".

  After the preliminary processing described above is done, an `Execution2Interface` is created to capture the state of execution and provide access to results, and then execution proceeds synchronously or asynchronously as requested. The created Execution2Interface is returned by this method. If there are any exceptions from this point onward, they can be obtained via `ExecutionBaseInterface.getExceptions()`. It is possible that multiple exceptions have occurred and the following is a list of specializations of `ExecutionException` that may be present in the list:

  - AlertProcessingException
  - ResultsBindingException
  - ExecutionStatusListenerException
  - SASServerException

  Note: the execute() method may be called multiple times with different sets of parameters. On invocation all relevant information is copied before the method returns. Once the method returns the StoredProcessInterface object may be modified and execute() invoked again. Or, if there is no further use for the stored process object it may be destroyed.

  Parameters:
    `synchronous` - true: execute synchronously; false: execute asynchronously.
    `listener` - specifies the listener that gets control when execution completes; can be null.
    `createAlert` - true: capture results by creating an `alert` item; false: do not capture results.
    `connection` - This argument should be null if the service is to obtain a connection. If a connection is supplied the following are valid argument types:
    - `String`: id of the session in which the stored process is to be executed. This argument is specific to stored prcesses executing on StoredProcess servers and is used to execute the stored process in an existing session. If execution of a previous stored process resulted in the creation of a session, a subsequent stored process can use this method to connect to that session by specifying the sessionID of that session.
    - `ConnectionInterface`: the underlying connection object should be appropriate to the type of server on which the stored process executes. Do note a ConnectionInterface is not serializable or remoteable.
    - `IWorkspace_1_1`: if the stored process executes on a Workspace server. For 9.2 stored processes, the StoredProcess Service obtains the ILanguageService object from the client supplied IWorkspace_1_1. The client should not use the ILanguageService associated with the supplied IWorkspace during the execution of the stored process.
    - `IStoredProcessServer_1_1`: if the stored process executes on a StoredProcess server.
  Returns:
    an `Execution2Interface` object describing the state and the results of the execution. `Execution2Interface.getStatus()` provides information about different completion codes generated by the execute() method.
  Throws:
    `java.rmi.RemoteException` - if a network anomaly is encountered.
    `java.lang.IllegalStateException` - if there is no session or user context or if destroy() has been called.
    `ExecutionException` - or one of its specializations. The following specializations can be thrown
    - AlertProcessingException - if there are problems creating and initializing the alert.
    - SASServerException - possible wrapped exceptions are:
      - com.sas.iom.SASStoredProcess.IStoredProcessContext2Package.InvalidFileref - if the stream was not created as the name does not conform to the SAS fileref naming rules.
      - com.sas.iom.SASStoredProcess.IStoredProcessContext2Package.StreamFilerefFail - if the stream was not created due to a fileref assignment failure.
      - com.sas.iom.SASStoredProcess.IStoredProcessServerPackage.BadSessionID - if a session id that is unknown to the stp server or has expired was used.
    - MissingParameterException - if a parameter that is required has not been assigned a value.
    - SessionNotFoundException - if the session was not found (additonal details in the `SessionNotFoundException javadoc`).
    - SessionNotAvailableException - if the session was not available (additonal details in the `SessionNotAvailableException javadoc`).
    If the super-class ExecutionException is thrown the following could be wrapped:
    - InvalidPromptValueException - thrown by the Prompting framework while validating prompt values.
    - ConnectionFactoryException - thrown by the Connection service, which manages connections.
    - IllegalServiceStateException - if there are various inconsistencies in the state of the Stored Process service.
    - ServiceException - if there are problems accessing the Personal Repository.
    In general, if a wrapped exception is present, it provides more specific information.

    Also see `Execution2Interface.getStatus()` and `#setLogicalServerType(LogicalServerType)`.

### executeAsynch

    Execution2Interface executeAsynch(ExecutionStatusListener2Interface listener,
                                      boolean createAlert)
                                      throws java.lang.IllegalStateException,
                                             ExecutionException,
                                             java.rmi.RemoteException

  Execute the stored process asynchronously. A list of name-value pairs is created from the parameter list in the format expected by the server executing the stored process and is passed to the server. Results may be captured as an `alert` item in the Personal Repository.

  If synchronous behavior is desired see `execute(boolean, ExecutionStatusListener2Interface, boolean, Object)`.

  A discussion of additional input parameters generated by the service can be found here.

  Depending on the type of parameter and the associated value, one or more name value pairs may be created to capture the value. Refer to the javadoc of the getMacroVariableValues method of the corresponding type in com.sas.datatypes for details.

  This method does some preliminary processing synchronously and there is the potential for exceptions being thrown in this processing. These exceptions are listed in the throws clause and may occur when:

  - the parameter list is checked to ensure that all required parameters have values.
  - there is an inconsistency in the values of certain prompts or streams whose names can be considered "reserved".
  - there are two prompts with the same name.
  - the prompt is of a type which generates multiple prompt names which cause a conflict.
  - an `alert` is created (if requested).
  - there is a problem determining the WebDAV location to which results are published. This can only occur if _RESULT is set "PACKAGE_TO_WEBDAV".

  After the preliminary processing described above is done, an `Execution2Interface` is created to capture the state of execution and provide access to results and, then, a new thread is created. The created Execution2Interface is returned by this method. In the newly created thread a connection is obtained and stored process execution occurs. Any exceptions that occur in this new thread can be obtained via `ExecutionBaseInterface.getExceptions()`. It is possible that multiple exceptions have occurred and the following is a list of specializations of `ExecutionException` that may be present in the list:

  - AlertProcessingException
  - ResultsBindingException
  - ExecutionStatusListenerException
  - SASServerException - possible wrapped exceptions are:
    - com.sas.iom.SASStoredProcess.IStoredProcessContext2Package.InvalidFileref - if the stream was not created as the name does not conform to the SAS fileref naming rules.
    - com.sas.iom.SASStoredProcess.IStoredProcessContext2Package.StreamFilerefFail - if the stream was not created due to a fileref assignment failure.
  - A wrapped ConnectionFactoryException, thrown by the Connection service, when an attempt to obtain a connection to the server was made.

  Note: the executeAysnch() method may be called multiple times with different sets of parameters. On invocation, all relevant information is copied before the method returns. Once the method returns the StoredProcessInterface object may be modified and executeAysnch() invoked again. Or, if there is no further use for the stored process object it may be destroyed.

  If this method is used to execute a stored process which streams input and / or output, stream handles via `Execution2Interface.getInputStream(Object)` or `Execution2Interface.getOutputStream(Object)` methods will not be available until after a connection to the server is made. If no connection is available, those method will block. The consumer can control blocking behavior by using `Execution2Interface.waitForConnection(long)` or `Execution2Interface.waitForConnection()` and not obtaining the streams until a connection has been made.

  Parameters:
    `listener` - specifies the listener that gets control when execution completes; can be null.
    `createAlert` - true: capture results by creating an `alert` item; false: do not capture results.
  Returns:
    an `Execution2Interface` object describing the state and the results of the execution. `Execution2Interface.getStatus()` provides information about different completion codes generated by the execute() method.
  Throws:
    `java.rmi.RemoteException` - if a network anomaly is encountered.
    `java.lang.IllegalStateException` - if there is no session or user context or if destroy() has been called.
    `ExecutionException` - or one of its specializations. The following specializations can be thrown
    - AlertProcessingException - if there are problems creating and initializing the alert.
    - MissingParameterException - if a parameter that is required has not been assigned a value.
    If the super-class ExecutionException is thrown the following could be wrapped:
    - InvalidPromptValueException - thrown by the Prompting framework while validating prompt values.
    - IllegalServiceStateException - if there are various inconsistencies in the state of the Stored Process service.
    - ServiceException - if there are problems accessing the Personal Repository.
    In general, if a wrapped exception is present, it provides more specific information.

    Also see `Execution2Interface.getStatus()` and `#setLogicalServerType(LogicalServerType)`.

### addInputStream

    boolean addInputStream(java.lang.String streamKey)
                           throws java.rmi.RemoteException,
                                  java.lang.IllegalStateException

  Adds an input stream definition to the stored process. The client reads from the input stream which provides a channel for the output of the stored process.

  Input streams and output streams use the same fileref name space.

  If successful, a `GenericStream` object is added to the list of data targets.

  Specified by:
    `addInputStream` in interface `StoredProcessBaseInterface`
  Parameters:
    `streamKey` - name of the input stream (must be a valid SAS fileref name) Stream names have the following restrictions:
    - The length of the name must be no greater than 8 characters.
    - The first character is either an English letter or an underscore.
    - Subsequent characters can be English letters, underscores or digits.
  Returns:
    true - if the name was not present; false - if it was with the same options.
  Throws:
    `java.rmi.RemoteException` - if a network anomaly is encountered.
    `java.lang.IllegalStateException` -
    - if the name is not a valid SAS fileref name
    - if the name has been specified before with a different set of options
    - if the name has already been defined as an output stream
    - if the server type is not `StoredProcessBaseInterface.SERVER_TYPE_STOREDPROCESS` for version 1 stored processes
    - if destroy() has been called

### addOutputStream

    boolean addOutputStream(java.lang.String streamKey,
                            boolean isMultiPass)
                            throws java.rmi.RemoteException,
                                   java.lang.IllegalStateException

  Adds an output stream definition to the stored process. The client writes to the output stream thereby providing input to the stored process.

  Input streams and output streams use the same fileref namespace.

  If successful, a `GenericStream` object is added to the list of data sources.

  Specified by:
    `addOutputStream` in interface `StoredProcessBaseInterface`
  Parameters:
    `streamKey` - name of the output stream (must be a valid SAS fileref name)
    `isMultiPass` - whether the stream supports multi-pass reads. Required when the stored process needs to make multiple passes over the data.
  Returns:
    true - if the name was not present; false - if it was with the same options.
  Throws:
    `java.rmi.RemoteException` - if a network anomaly is encountered.
    `java.lang.IllegalStateException` -
    - if the name is not a valid SAS fileref name
    - if the name has been specified before with a different set of options
    - if the name has already been defined as an input stream
    - if the server type is not `StoredProcessBaseInterface.SERVER_TYPE_STOREDPROCESS` for version 1 stored processes
    - if destroy() has been called

### isStreamCapable

    boolean isStreamCapable()
                            throws java.rmi.RemoteException

  Does the stored process have the result capability of stream enabled.

  Returns:
    true if the stored process is capable of streaming output; false, if not capable
  Throws:
    `java.rmi.RemoteException` - if a network anomaly is encountered.

### isPackageCapable

    boolean isPackageCapable()
                             throws java.rmi.RemoteException

  Does the stored process have the result capability of package enabled.

  Returns:
    true if the stored process is capable of package output; false, if not capable
  Throws:
    `java.rmi.RemoteException` - if a network anomaly is encountered.

### getParameters

    com.sas.prompts.definitions.PromptDefinitionInterface[] getParameters()
                                                                          throws java.rmi.RemoteException

  Gets parameter descriptions. Parameter descriptions from all groups are returned in a single array.

  Returns:
    a PromptDefinitionInterface array describing all parameters. Note: PromptDefinitionInterface is not remoteable
  Throws:
    `java.lang.IllegalStateException` - if destroy() has been called.
    `java.rmi.RemoteException` - if a network anomaly is encountered.

### getParameterValue

    java.lang.Object getParameterValue(java.lang.String parameterName)
                                       throws java.rmi.RemoteException

  Gets the value of a parameter. The parameter name supplied is compared with the prompt names in a case-insensitive way. For a properly defined stored process there should be at most one parameter with the same name which has a value. If there are multiple parameters with the same name which have values, the first one in visual order is returned. A null is returned if there is no value assigned to the parameter.

  Returns:
    the value of the parameter; null, if there's none
  Throws:
    `java.lang.IllegalStateException` - if destroy() has been called.
    `java.rmi.RemoteException` - if a network anomaly is encountered.

### setParameterValue

    com.sas.prompts.definitions.PromptDefinitionInterface setParameterValue(java.lang.String name,
                                                                            java.lang.Object value)
                                                                            throws java.rmi.RemoteException,
                                                                                   ServiceException,
                                                                                   com.sas.prompts.InvalidPromptValueException

  Sets the value of the specified parameter on the PromptValues object associated with this stored process. The parameter name may be a new name or an existing name. See the parameter section on case-sensitivity of the package description documentation for more information on case-sensitivity issues of parameter names.

  If new, the parameter is added in an implementation defined fashion and the only allowed values are of type String or String[] - supplying a value of any other type or a null value will result in a ServiceException.

  If it is desired that the parameter be added to a certain group or values of a type other than String or String[] be handled, a PromptDefinitionInterface should be appropriately created before this method is called.

  Parameters:
    `name` - name of the parameter. Parameter names have the following restrictions:
    - The length of the name must be no greater than 32 characters.
    - The first character is either an English letter or an underscore.
    - Subsequent characters can be English letters, underscores or digits.
    `value` - value of the parameter value.
  Returns:
    the PromptDefinitionInterface corresponding to the parameter. Note: PromptDefinitionInterface is not remoteable
  Throws:
    `java.rmi.RemoteException` - if a network anomaly is encountered.
    `com.sas.prompts.InvalidPromptValueException` - if thrown by the underlying Prompting Framework
    `ServiceException` - if the parameter name is not valid or if the value is not of type String or String[] for a new parameter
    `java.lang.IllegalStateException` - if destroy() has been called.

### setParameterValues

    java.util.Map setParameterValues(java.util.Map map)
                                     throws java.rmi.RemoteException,
                                            ServiceException

  Sets the values of the specified parameters. The map keys are new or existing parameter names. See the section on parameter name case-sensitivity in the package description documentation for more information on case-sensitivity issues of parameter names.

  The name is first validated. Next, the actual setting of values is delegated to the `setPromptValuesByNameValuePair` method of `PromptUtil`. That method ignores any prompt definition with a prompt name which does not exists in this Stored Process. Finally, new parameters (those ignored by the `PromptUtil` method) are added using `setParameterValue(String, Object)`.

  Parameters:
    `map` - the `Map` containing values - the key is a String representing the parameter name and the value is the Object representing the parameter value
  Returns:
    a `Map` of errors that occurred. The key is the prompt name and the value is the exception which occurred processing the prompt with that name.
  Throws:
    `java.rmi.RemoteException` - if a network anomaly is encountered.
    `ServiceException` - if there is an error in name validation
    `java.lang.IllegalArgumentException` - if any of the Map keys are not Strings.
    `java.lang.IllegalStateException` - if destroy() has been called.

### getPromptValues

    com.sas.prompts.PromptValuesInterface getPromptValues()
                                                          throws java.rmi.RemoteException

  Returns the PromptValuesInterface associated with this Stored Process service object. When a stored process is instantiated from metadata, prompts are deserialized into a PromptGroup object. If the stored process has no parameters the deserialization process results in an empty PromptGroup object. A PromptValues object is constructed from the PromptGroup object and a reference to that PromptValues object is returned by this method.

  Returns:
    the PromptValuesInterface. Note: PromptValuesInterface is not remoteable
  Throws:
    `java.rmi.RemoteException` - if a network anomaly is encountered.
    `java.lang.IllegalStateException` - if destroy() has been called.

### setPromptValues

    void setPromptValues(com.sas.prompts.PromptValuesInterface promptValues)
                         throws java.rmi.RemoteException

  Sets the PromptValuesInterface associated with this Stored Process service object. When a stored process is instantiated from metadata, prompts are deserialized into a PromptGroup object and a PromptValues object is constructed from the PromptGroup object. This PromptValues is used to maintain values associated with stored process parameters. Calling this method replaces the PromptValues object used by stored process with the supplied parameter. The old PromptValues is discarded and the new one used - no merge of any kind is done.

  Parameters:
    `promptValues` - PromptValuesInterface that is to replace the PromptValuesInterface used by this Stored Process
  Throws:
    `java.rmi.RemoteException` - if a network anomaly is encountered.
    `java.lang.IllegalStateException` - if destroy() has been called.

### setParameterValues

    java.util.List<com.sas.prompts.definitions.PromptDefinitionInterface> setParameterValues(com.sas.prompts.PromptValuesInterface promptValues)
                                                                                             throws java.rmi.RemoteException,
                                                                                                    ServiceException

  Sets values for the parameters of this Stored Process from the PromptValuesInterface supplied. The intent is for the actual setting of values to be delegated to the `setPromptValuesByNameValuePair` method of `PromptUtil`. That method ignores any prompt definition with a prompt name which does not exists in this Stored Process - such PromptDefinitions are added to a list which is returned. If there are no values in this category an empty list is returned. If a PromptDefinition has its value cleared in the input PromptValuesInterface an existing prompt of the same name in the Stored Process is cleared except if it has default value different from that in the Stored Process in which case the incoming default value will be used.

  Fixed prompts are not affected by this method.

  If the PromptValuesInterface supplied is the same (identical reference) as the one used by the stored process (which is the one surfaced via `getPromptValues()`), this method is a no-op and returns an empty list.

  If an Exception occurs in setting the value, the exception is captured and a Info level message containing the exception written to the log.

  The intent of this method is for the stored process to be supplied with parameter values for execution. If prompt manipulation or maintenance of UI state is desired consumers should consider obtaining the prompts via `getPromptValues()`, doing needed manipulation and then setting them on the stored process via `setPromptValues(PromptValuesInterface)`.

  Parameters:
    `promptValues` - PromptValuesInterface containing parameter values that are to be set on this Stored Process
  Returns:
    the list of PromptDefinitionInterfaces as described above. Note: PromptDefinitionInterface is not remoteable
  Throws:
    `java.rmi.RemoteException`
    `ServiceException`

### getOutputParameters

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

  Return a list of output parameters defined in metadata as `OutputParameterInterface` objects.

  Throws:
    `java.rmi.RemoteException` - if a network anomaly is encountered.

### getOutputParameter

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

  Return the `OutputParameterInterface` object corresponding to the name requested. OutputParameterInterface objects are only available in this interface for output parameters defined in metadata.

  Parameters:
    `name` - of the output parameter requested
  Returns:
    null if a matching object cannot be found.
  Throws:
    `java.rmi.RemoteException` - if a network anomaly is encountered

### getInputStreamNames

    java.lang.String[] getInputStreamNames()
                                           throws java.rmi.RemoteException,
                                                  java.lang.IllegalStateException

  Deprecated. Use `getDataTargets()`. Returns the fileref names of the `GenericStream` and `XMLStream` objects returned by getDataTargets().

  Description copied from interface: `StoredProcessBaseInterface`
  Return an array of input stream names for this stored process.

  Specified by:
    `getInputStreamNames` in interface `StoredProcessBaseInterface`
  Throws:
    `java.rmi.RemoteException` - if a network anomaly is encountered.
    `java.lang.IllegalStateException` - if the stored process runs on a WorkspaceServer or if destroy() has been called.

### getOutputStreamNames

    java.lang.String[] getOutputStreamNames()
                                            throws java.rmi.RemoteException,
                                                   java.lang.IllegalStateException

  Deprecated. Use `getDataSources()`. Returns the fileref names of the `GenericStream` and `XMLStream` objects returned by getDataSources().

  Description copied from interface: `StoredProcessBaseInterface`
  Return an array of output stream names for this stored process.

  Specified by:
    `getOutputStreamNames` in interface `StoredProcessBaseInterface`
  Throws:
    `java.rmi.RemoteException` - if a network anomaly is encountered.
    `java.lang.IllegalStateException` - if the stored process runs on a WorkspaceServer or if destroy() has been called.

### getDataSources

    java.util.List<GenericStream> getDataSources()
                                                 throws java.rmi.RemoteException

  Returns a list of the stream data sources. Each object in the list is one of:
  - `GenericStream`
  - `XMLStream`
  The items are returned in the order defined at design time.

  This method returns the types of data sources that can be present in a 9.2 stored process and does not return the types of data sources introduced post 9.2.

  Returns:
    the list of data sources
  Throws:
    `java.rmi.RemoteException` - if a network anomaly is encountered.
    `java.lang.IllegalStateException` - if destroy() has been called.

### getDataTargets

    java.util.List<GenericStream> getDataTargets()
                                                 throws java.rmi.RemoteException

  Returns a list of stream data targets. Each object in the list is one of:
  - `GenericStream`
  - `XMLStream`
  The items are returned in the order defined at design time.

  This method returns the types of data sources that can be present in a 9.2 stored process and does not return the types of data sources introduced post 9.2.

  Returns:
    the list of data targets
  Throws:
    `java.rmi.RemoteException` - if a network anomaly is encountered.
    `java.lang.IllegalStateException` - if destroy() has been called.

### setClientName

    void setClientName(java.lang.String clientName)
                       throws java.rmi.RemoteException

  Sets the client name. Calling this method will overwrite the client name that a stored process obtains from the service (via `StoredProcessServiceInterface.getClientName()`) at construction time.

  Parameters:
    `clientName` - client name
  Throws:
    `java.rmi.RemoteException`

### getClientName

    java.lang.String getClientName()
                                   throws java.rmi.RemoteException

  Returns the client name. See `setClientName(String)` for more information.

  Returns:
    the client name
  Throws:
    `java.rmi.RemoteException`

### getResultType

    int getResultType()
                      throws ServiceException,
                             java.rmi.RemoteException

  Gets the type of result delivered by the service.

  Returns:
    one of `RESULT_TYPE_NONE`, `RESULT_TYPE_PACKAGE` or `RESULT_TYPE_STREAM`
  Throws:
    `java.lang.IllegalStateException` - if destroy() has been called.
    `java.rmi.RemoteException` - if a network anomaly is encountered.
    `ServiceException` - if there are inconsistencies among the capabilities of the stored process, the parameter values and the type of server the stored process is running on

### validatePromptValues

    void validatePromptValues()
                              throws java.lang.IllegalStateException,
                                     com.sas.prompts.InvalidPromptValueException,
                                     java.rmi.RemoteException

  Validates prompt values. The following is done:
  - for prompts which are required to have a value, checks to ensure a value is present.
  - checks the values against any constraints that are present.
  - checks that the value (or values) is (are) in the list of values from the corresponding static value provider, if present.
  - checks that the value (or values) is (are) in the list of values from the corresponding dynamic value provider, if present, provided the requirements for dynamic value validation are met.

  If there is a validation error the exception message contains the reason.

  Throws:
    `com.sas.prompts.InvalidPromptValueException` - if there is a validation error
    `java.lang.IllegalStateException` - if the object bound to the SessionContext using "com.sas.prompts.dataProviderKey" is not an instance of DataProviderInterface
    `java.rmi.RemoteException` - if a network anomaly is encountered.

### setInputFileref

    void setInputFileref(java.lang.String fileref,
                         java.io.InputStream inputStream)
                         throws ServiceException,
                                java.rmi.RemoteException

  Associates a client supplied binary file with the fileref. The consumer of the API supplies the InputStream that the service will read from. Before the stored process executes, bytes from the InputStream will be copied to a temporary file on the server and the service will associate that temporary file with the fileref. The service closes the supplied InputStream when it has completed reading from it.

  If this method is invoked on a remote object, a serializable extension of InputStream, e.g., `InputStreamAdapter` should be supplied.

  Parameters:
    `fileref` -
    `inputStream` -
  Throws:
    `ServiceException` - if the fileref is not defined or the fileref is used for output
    `java.rmi.RemoteException`
  Since:
    9.3

### setInputFileref

    void setInputFileref(java.lang.String fileref,
                         java.io.Reader reader)
                         throws ServiceException,
                                java.rmi.RemoteException

  Associates a client supplied text file with the fileref. The consumer of the API supplies the Reader that the service will read from. Before the stored process executes, characters from the Reader will be copied to a temporary file on the server and the service will associate that temporary file with the fileref. The service closes the supplied Reader when it has completed reading from it.

  If this method is invoked on a remote object, a serializable extension of Reader, e.g., `ReaderAdapter` should be supplied.

  Parameters:
    `fileref` -
    `inputStream` -
  Throws:
    `ServiceException` - if the fileref is not defined or the fileref is used for output
    `java.rmi.RemoteException`
  Since:
    9.3

### setInputFileref

    void setInputFileref(java.lang.String fileref,
                         java.lang.String engine,
                         java.lang.String path,
                         java.lang.String options)
                         throws ServiceException,
                                java.rmi.RemoteException

  Associates a path on the server with the fileref used for input. The consumer of the API may optionally specify the engine to be used to access the path and any options needed by the engine. Before the stored process executes, the path will be associated with the fileref using any engine specified.

  Parameters:
    `fileref` -
    `inputStream` -
  Throws:
    `ServiceException` - if the fileref is not defined or the fileref is used for output
    `java.rmi.RemoteException`
  Since:
    9.3

### setOutputFileref

    void setOutputFileref(java.lang.String fileref,
                          java.io.OutputStream outputStream)
                          throws ServiceException,
                                 java.rmi.RemoteException

  Specifies the OutputStream to be used to write the output of the fileref to. The consumer of the API supplies the OutputStream that the service will write to. Before the stored process executes, a temporary file on the server is associated with the fileref and after execution completes bytes from that temporary file are written to the supplied OutputStream. The service closes the supplied OutputStream when it has completed writing to it.

  If this method is invoked on a remote object, a serializable extension of OutputStream, e.g., `OutputStreamProxy` should be supplied.

  Parameters:
    `fileref` -
    `inputStream` -
  Throws:
    `ServiceException` - if the fileref is not defined or the fileref is used for input
    `java.rmi.RemoteException`
  Since:
    9.3

### setOutputFileref

    void setOutputFileref(java.lang.String fileref,
                          java.io.Writer writer)
                          throws ServiceException,
                                 java.rmi.RemoteException

  Specifies the Writer to be used to write the output of the fileref to. The consumer of the API supplies the Writer that the service will write to. Before the stored process executes, a temporary file on the server is associated with the fileref and after execution completes characters from that temporary file are written to the supplied Writer. The service closes the supplied Writer when it has completed writing to it.

  If this method is invoked on a remote object, a serializable extension of Writer, e.g., `WriterProxy` should be supplied.

  Parameters:
    `fileref` -
    `inputStream` -
  Throws:
    `ServiceException` - if the fileref is not defined or the fileref is used for input
    `java.rmi.RemoteException`
  Since:
    9.3

### setOutputFileref

    void setOutputFileref(java.lang.String fileref,
                          java.lang.String engine,
                          java.lang.String path,
                          java.lang.String options)
                          throws ServiceException,
                                 java.rmi.RemoteException

  Associates a path on the server with the fileref used for output. The consumer of the API may optionally specify the engine to be used to access the path and any options needed by the engine. Before the stored process executes, the path will be associated with the fileref using any engine specified.

  Parameters:
    `fileref` -
    `inputStream` -
  Throws:
    `ServiceException` - if the fileref is not defined or the fileref is used for input
    `java.rmi.RemoteException`
  Since:
    9.3

### setInputDataTable

    void setInputDataTable(java.lang.String tableName,
                           java.lang.String libref,
                           java.lang.String memberName)
                           throws ServiceException,
                                  java.rmi.RemoteException

  Specifies the two level name for a server side input table. It is assumed that the libref has been defined outside of the stored process (e.g. preassigned). The service adds a macro name-value pair using as follows: the name is the value of the tableName parameter prefixed by "_SOURCE_" and the value is the value derived from the values of the libref and memberName parameters as in libref.memberName.

  If null or an empty string is specified for libref a one level name results.

  If null or an empty string is specified for memberName, a value is obtained from the template table if a template table was assigned. If there is no template table, then the table parameter name is used.

  Parameters:
    `tableName` - the table parameter name of a data table in metadata
    `libref` - name of the libref
    `memberName` - name of the dataset in the libref
  Throws:
    `ServiceException`
    `java.rmi.RemoteException`
  Since:
    9.3

### setInputDataTable

    void setInputDataTable(java.lang.String tableName,
                           java.io.InputStream inputStream,
                           java.lang.String memberName,
                           java.lang.String xmlLibraryOptions)
                           throws ServiceException,
                                  java.rmi.RemoteException

  Specifies client side input to be used for the table via the XML libname engine. This method results in the service issuing a LIBNAME statement and a FILENAME statement using a generated name of the form _STPnnnn (n is an upper case hex-digit). The LIBNAME statement specifies the XML engine with any options specified in the xmlLibraryOptions parameter. The FILENAME specifies a TEMP device and input are (binary) copied from the InputStream to the location of the fileref before the stored process executes. The service adds a macro name-value pair using the generated name and the input provided. The name is the value of the tableName parameter prefixed by "_SOURCE_" and the value is the value derived from the values of the generated name and the memberName parameter as in _STPnnnn.member.

  If null or an empty string is specified for memberName, a value is obtained from the template table if a template table was assigned. If there is no template table, then the table parameter name is used.

  Parameters:
    `tableName` - the table parameter name of a data table in metadata
    `inputStream` - which provides the (binary) input to the stored process
    `memberName` - name of the dataset in the libref
    `xmlLibraryOptions` - options to be used when the LIBNAME statement using the XML libname engine is issued
  Throws:
    `ServiceException`
    `java.rmi.RemoteException`
  Since:
    9.3

### setOutputDataTable

    void setOutputDataTable(java.lang.String tableName,
                            java.lang.String libref,
                            java.lang.String memberName)
                            throws ServiceException,
                                   java.rmi.RemoteException

  Specifies the two level name for a server side output table. It is assumed that the libref has been defined outside of the stored process (e.g. preassigned). The service adds a macro name-value pair using as follows: the name is the value of the tableName parameter prefixed by "_TARGET_" and the value is the value derived from the values of the libref and memberName parameters as in libref.memberName.

  If null or an empty string is specified for libref a one level name results.

  If null or an empty string is specified for memberName, a value is obtained from the template table if a template table was assigned. If there is no template table, then the table parameter name is used.

  Parameters:
    `tableName` - the table parameter name of a data table in metadata
    `libref` - name of the libref
    `memberName` - name of the dataset in the libref
  Throws:
    `ServiceException`
    `java.rmi.RemoteException`
  Since:
    9.3

### setOutputDataTable

    void setOutputDataTable(java.lang.String tableName,
                            java.io.OutputStream outputStream,
                            java.lang.String memberName,
                            java.lang.String xmlLibraryOptions)
                            throws ServiceException,
                                   java.rmi.RemoteException

  Specifies client side output to be used for the table via the XML libname engine. This method results in the service issuing a LIBNAME statement and a FILENAME statement using a generated name of the form _STPnnnn (n is an upper case hex-digit). The LIBNAME statement specifies the XML engine with any options specified in the xmlLibraryOptions parameter. The FILENAME specifies a TEMP device and output is (binary) copied to the OutputStream from the location of the fileref after the stored process executes. The service adds a macro name-value pair using the generated name and the input provided. The name is the value of the tableName parameter prefixed by "_TARGET_" and the value is the value derived from the values of the generated name and the memberName parameter as in _STPnnnn.member.

  If null or an empty string is specified for memberName, a value is obtained from the template table if a template table was assigned. If there is no template table, then the table parameter name is used.

  Parameters:
    `tableName` - the table parameter name of a data table in metadata
    `outputStream` - which provides the output from the stored process
    `memberName` - name of the dataset in the libref
    `xmlLibraryOptions` - options to be used when the LIBNAME statement using the XML libname engine is issued
  Throws:
    `ServiceException`
    `java.rmi.RemoteException`
  Since:
    9.3

### setServerContext

    void setServerContext(ServerContextInterface serverContext)
                          throws ServiceException,
                                 java.rmi.RemoteException

  Sets the server context to be used to execute the stored process. This method may only be called for stored processes created from metadata if the stored process is defined to permit execution on other server contexts. For such stored processes, `StoredProcessInterface.isOtherServerContextAllowed()` returns true.

  For stored process defined with a logical server type of `StoredProcessInterface.LogicalServerType.WORKSPACE` or `StoredProcessInterface.LogicalServerType.STORED_PROCESS`, this method checks to see if a server of that type exists and will throw a ServiceException if it does not.

  For stored process defined with a logical server type of `StoredProcessInterface.LogicalServerType.ANY` this method checks to see if a server of either supported type exists and will throw a ServiceException if one cannot be found.

  If both this method and `#setLogicalServerType(LogicalServerType)` are to be called, this method should be called first and then setLogicalServerType() should be called as setLogicalServerType() checks metadata to ensure that a server of the desired type is defined. If this method is called after setLogicalServerType() the value set by setLogicalServerType() will be ignored as this method uses the value defined in metadata. Calls to `getServer()` and `getServerType()` should not be made until calls to both this method and setLogicalServerType() are complete. This method is invalid for 9.2 stored processes or manually created stored processes and will throw an UnsupportedOperationException if invoked on one.

  Parameters:
    `serverContext` - to be used for execution
  Throws:
    `ServiceException` - if the stored process does not permit execution on other server contexts, if there is a metadata error, or for the reasons described above
    `java.rmi.RemoteException`
  Since:
    9.3

### setLogicalServerType

    void setLogicalServerType(com.sas.services.storedprocess.metadata.StoredProcessInterface.LogicalServerType logicalServerType)
                              throws ServiceException,
                                     java.rmi.RemoteException

  Sets the type of logical server to be used for execution. This method may only be called for stored processes created from metadata if the stored process is defined to permit execution on any type of logical server. For such stored processes, `StoredProcessInterface.getLogicalServerType()` returns `StoredProcessInterface.LogicalServerType.ANY`.

  If a stored process is defined with `StoredProcessInterface.LogicalServerType.ANY`, an attempt is made to first get a connection to a Stored Process server. If the attempt is successful that connection is used; if unsuccessful, an attempt is next made to obtain a connection to a Workspace server. Invoking this method restricts the connection attempt to the type of server specified; if no connection can be made to the specified type of server, no additional attempt is made to connect to a different type of server.

  The only valid arguments are `StoredProcessInterface.LogicalServerType.STORED_PROCESS` and `StoredProcessInterface.LogicalServerType.WORKSPACE`.

  If both this method and setServerContext() are to be called, setServerContext() should be called first and then this method should be called. See `setServerContext(ServerContextInterface)` for more information.

  This method checks metadata to ensure that a server of the desired type is defined for the server context in effect.

  This method is invalid for 9.2 stored processes or manually created stored processes and will throw an UnsupportedOperationException if invoked on one.

  Parameters:
    `logicalServerType` - the type of server to connect to
  Throws:
    `ServiceException` - if the stored process does not permit execution on any logical server type, if the argument is not valid, if a server of the type desired is not defined in metadata or if there is a metadata exception
    `java.rmi.RemoteException`
  Since:
    9.3

### getServer

    LogicalServerInterface getServer()
                                     throws java.rmi.RemoteException

  Get the the logical server the stored process runs on.

  For 9.2 stored processes this method returns the LogicalServer associated with the stored process.

  For other stored processes, the LogicalServer returned depends on the Logical Servers attached to the Server Context and the logical server type defined in metadata and any prior calls to `#setLogicalServerType(LogicalServerType)` and `setServerContext(ServerContextInterface)`. See `setServerContext(ServerContextInterface)` for additional information. The LogicalServer returned is based on metadata and the various settings previously described and not on whether the server is actually running.

  Specified by:
    `getServer` in interface `StoredProcessBaseInterface`
  Throws:
    `java.lang.IllegalStateException` - if destroy() has been called.
    `java.rmi.RemoteException` - if a network anomaly is encountered.

### getServerType

    int getServerType()
                      throws java.rmi.RemoteException

  Get the type of server that the stored process runs on.

  For other stored processes, the type returned depends on the Logical Servers attached to the Server Context and the logical server type defined in metadata and any prior calls to `#setLogicalServerType(LogicalServerType)` and `setServerContext(ServerContextInterface)`. See `setServerContext(ServerContextInterface)` for additional information. The type returned is based on metadata and the various settings previously described and not on whether the server is actually running.

  Specified by:
    `getServerType` in interface `StoredProcessBaseInterface`
  Returns:
    `StoredProcessBaseInterface.SERVER_TYPE_STOREDPROCESS` or `StoredProcessBaseInterface.SERVER_TYPE_WORKSPACE`
  Throws:
    `java.lang.IllegalStateException` - if destroy() has been called.
    `java.rmi.RemoteException` - if a network anomaly is encountered.

### getConnection

    ConnectionInterface getConnection()
                                      throws ServiceException,
                                             java.rmi.RemoteException

  Get a connection for stored process execution. This method is called if the consumer needs to use the connection that the stored process will use for purposes other than and including the execution of the stored process. The connection returned by this method can be used by the consumer before and / or after the execution of the stored process. Typically, it is also used in the call to execute the stored process, by supplying it as the last parameter to `execute(boolean, ExecutionStatusListener2Interface, boolean, Object)`.

  If the consumer calls this method, the consumer is responsible for managing the life-cycle of the connection. The returned connection can be closed using `ConnectionInterface.close()` and the returned connection should be closed after `Execution2Interface.destroy()` has been called.

  If the stored process supports it, the method will honor any prior call to `setServerContext(ServerContextInterface)` and `#setLogicalServerType(LogicalServerType)`. The method uses the same algorithm to obtain a connection as used by the stored process service when the execute method is called without a supplied connection.

  Do note that ConnectionInterface, the type returned by this method, is not serializable or remoteable.

  Returns:
    connection which can be used to execute the stored process
  Throws:
    `ServiceException` - if a connection could not be obtained
    `java.lang.UnsupportedOperationException` - if the method is called on a manually created stored process
    `java.rmi.RemoteException`

### setSessionFreedOnDestroy

    void setSessionFreedOnDestroy(boolean sessionFreedOnDestroy)
                                  throws java.rmi.RemoteException

  Determines if the stored process server session is freed when `Execution2Interface.destroy()` is called. This method should be called before calling `execute(boolean, ExecutionStatusListener2Interface, boolean, Object)` or `executeAsynch(ExecutionStatusListener2Interface, boolean)`.

  By default, created stored process server sessions are retained for the configured amount of time so there is no need to call this method with an argument of false. The default behavior enables the controlling application to use the session id created by the session to obtain artifacts created by the execution of the stored process. Invoking this method with an argument of true is done by the controlling application to indicate that it has no use for any created artifacts in the retained session and that the resources can be freed when `Execution2Interface.destroy()` is called.

  Calling this method with an argument of true also results in `Execution2Interface.getSessionID()` returning a null.

  Parameters:
    `sessionFreedOnDestroy` - see description
  Throws:
    `java.rmi.RemoteException`
  Since:
    9.4M3

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

Copyright © 2009 SAS Institute Inc. All Rights Reserved.