executePreparedSql
Execute a prepared statement within the Composite server. The sqlText is treated as the parameterized query, and the parameterList is used to fill in the parameters.
If "dataServiceName" is provided, then all resource references within "sqlText" must use dotted-path notation to specify resources; otherwise CIS slash-path notation should be used.
If "isBlocking" is set to TRUE, then execution of SQL will not return until the processing associated with the execution has completed and the "result" element is set.
If set to FALSE, then this operation will return when the processing associated with the execution has completed, but it will not wait to fill the "result" element with data.
If "includeMetadata" is "true", then the response will include the "metadata" element which describes the names and types of the column data which will be provided in the "result" either in this call or in a later call to
getTabularResult.
If "skipRows" is set, then that many number of rows will be skipped in the execution output before returning any results. If "skipRows" is greater than the total possible number of rows, then no rows will be returned.
If "maxRows" is set, then "result" will contain at most "maxRows" number of rows.
If "maxRows" is fewer than the total number of rows of data available, then additional calls to "getTabularResult" will need to be made to get the rest of the available data.
Use "hasMoreRows" element in "result" to determine if additional data is available. This is more accurate than comparing the number of rows returned with "maxRows" because the server might opt to return fewer than "maxRows".
If "consumeRemainingRows" is TRUE, then all remaining rows in excess of "maxRows" will be consumed.
If "users" or "groups" is set, then queries against system tables will return resources that are accessible by the users and groups in these lists. If they are not set, then system table queries will return resources that are accessible by the current user.
The current user must have the READ_ALL_RESOURCES privilege to set these parameters.
In the response, the "completed" element will return true if all of the results associated with the execution have been exhausted. 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:
• "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 will be set if it is known how many rows were affected by this execution. This includes a count of rows that were skipped (see “skipRows” element) or consumed (see "consumedRemainingRows" element).
The returned "resultId" returns a handle to the result in the server. This can be used with the
getTabularResult and
closeResult operations.
The "requestId" is the server request ID associated with execution.
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".
Request Elements
sqlText: The Parameterized SQL to be executed.
isBlocking (optional): If "true", do not return until the execution completes. Defaults to "true".
includeMetadata (optional): If "true", the response will contain information about the column names and their types. Defaults to "false".
skipRows (optional): The number of rows to skip in the execution output before generating results. If not set, then no rows will be skipped.
maxRows (optional): The maximum number of rows to return. If not set, then there all rows will be returned.
consumeRemainingRows (optional): If set to TRUE, then all remaining rows after "maxRows" will be consumed.
dataServiceName (optional): The name of the public data service.
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.
parameterList: The list of parameters to be used for the prepared Statement.
Response Elements:
completed: If "true", all processing associated with execution has completed.
metadata (optional): Table metadata describing the column names and types within the result.
rowsAffected (optional): If known, the number of rows affected by the execution;
otherwise unset.
result (optional): The result data.
resultId: The result ID.
requestId: The request ID.
Faults:
IllegalArgument: If any elements are malformed.
RuntimeError: If an error occurs during execution.
RuntimeError: If the user does not have appropriate privileges on any resources referred to by the "sqlText".
Security: If the user omitted the "dataServiceName" and does not have the ACCESS_TOOLS right.