executeProcedure
Execute the resource located at the given path and type. Only PROCEDURE and TABLE resources can be executed. If dataServiceName is provided, the path must use dotted-path notation to specify a resource relative to the published data service. If not, the path must use absolute TDV slash-path notation.
If isBlocking is TRUE, this operation does not return until the processing associated with the execution has completed; the outputs element is set. Otherwise, this operation returns immediately and the outputs element is unset.
If includeMetadata is TRUE, the response includes the metadata element which describes the names and types of the output parameter data which is provided in the result either in this call or in a later call to
getProceduralResult.
The inputs element contains a set of parameters to be inputs to the execution. Each parameter has two elements:
• definition: SQL language type for this parameter value. For example, VARCHAR(40) or BIGINT.
• value: The value of this parameter.
Inputs cannot be provided for a TABLE resource. Executing a TABLE resource is akin to showing the contents of that TABLE (SELECT * FROM <path>).
The outputs element, if set, contains exactly one output parameter, which contains a tabular resultId. Additional calls to
getTabularResult may be needed to retrieve data produced by this query.
The dataServiceName is the name of the public data service containing the resource to be executed. If dataServiceName is included, use dotted-path notation within sqlText for all resource references. If dataServiceName is not included, use TDV slash-path notation.
If users or groups is set, queries against system tables return resources that are accessible by the users and groups in these lists. If they are not set, system table queries return resources that are accessible by the current user. The current user must have the READ_ALL_RESOURCES privilege to set these parameters.
The completed element reports whether all possible results have been retrieved.
The requestStatus element reports the status of the server request associated with the execution. The request status can be one of the following:
• STARTED: The request has started. The request has been created, but is not yet running.
• WAITING: The request is waiting in a queue for the server to process the request.
• RUNNING: The request is currently being executed by the server.
• COMPLETED: The execution associated with the request has completed. Results can now be acquired.
• CLOSING: The request is closing.
• SUCCESS: The request closed with success.
• FAILURE: The request closed with failure.
• TERMINATED: The request was terminated.
The rowsAffected element is set if it is known how many rows were affected by this execution.
The outputs element contains a set of ProcValue instance. If the output type is cursor, you should get a resultId that is a handle to the result in server. You can use it with getTabularResult and
closeResult. If the out type is not cursor, you should get a real output value.
The returned resultId is a handle to the result in the server. This can be used with
getProceduralResult and closeResult. Output parameters which are cursors have a value returned which is a tabular resultId. This can be used with getTabularResult and closeResult. Closing a tabular resultId closes only that cursor, while closing a procedural resultId closes the procedure and all cursors associated with the procedure.
All system resources associated with this operation are closed when the transaction containing the call completes. This means that resultId is not valid if it is used outside of the same transaction that called this execute operation. If you want to use resultId, you must surround the calls to this execute operation and any operations using resultId with an explicit transaction.
All users can call this operation, but only users with the ACCESS_TOOLS right can omit the dataServiceName.
Location
/services/webservices/system/admin/execute/operations/
Request Elements
isBlocking (optional): If TRUE (the default), do not return until the execution completes.
includeMetadata (optional): If TRUE, the response contains information about the output parameter names and their types. Defaults to FALSE.
inputs (optional): List of parameter values to use as input for the execution.
dataServiceName (optional): The name of the public data service.
path: The path to the resource.
type: The type of the resource.
users: (optional) For system table queries, returns results that are accessible by the users included in this list.
groups: (optional) For system table queries, returns results that are accessible by the groups included in this list.
Response Elements
completed: If TRUE, all processing associated with execution has completed.
requestStatus: Status of the server request performing the execution.
metadata (optional): Table metadata listing the column names and types within the result.
rowsAffected (optional): If known, the number of rows affected by the execution; otherwise unset.
outputs (optional): List of parameter values returned as output from the execution.
resultId: The result ID.
requestId: The server request ID associated with execution.
Faults
IllegalArgument: If any elements are malformed.
IllegalArgument: If any required parameters in the inputs element are missing.
IllegalArgument: If unexpected parameters are provided in the inputs element.
NotAllowed: If an attempt is made to execute a SQL script procedure with an insufficient license.
RuntimeError: If an error occurs during execution.
Security: If the user omitted the dataServiceName and does not have the ACCESS_TOOLS right.
Security: If the user does not have appropriate privileges on the resource referred to by path and type.