IIapi_getQueryInfo() Function—Return Information about a Query
The IIapi_getQueryInfo() function returns data associated with a query statement. It is useful for applications that are updating the database to know if the update was successful. The information includes the following:
• Number of rows affected by a query
• Read-only status of a cursor
• Return status of a database procedure execution
• ID created when a procedure is executed
• ID created when a repeat query is defined
• Table key result of an SQL insert or update query
• Object key result of an SQL insert or update query
• Cursor attributes
• Row position and status
As a common practice, applications should call IIapi_getQueryInfo() after each query is completed to check if there are any additional errors or response data reported by the server.
The output of IIapi_getQueryInfo() is valid until the query statement is ended with the IIapi_close() function.
For query statement batches, IIapi_getQueryInfo() should be called once for each query statement in the batch. The query results for each statement in the batch will be returned in the order the query statements were submitted to the batch. IIapi_getQueryInfo() will return a status of IIAPI_ST_NO_DATA if it is called more times than the number of query statements in the batch.
If an error occurs during batch execution that terminates the execution, fewer query results will be returned. In this case, IIapi_getQueryInfo() will return a status of IIAPI_ST_NO_DATA once all the available query results have been returned.
This function has the following syntax:
II_VOID IIapi_getQueryInfo (IIAPI_GETQINFOPARM *getQInfoParm);
typedef struct _IIAPI_GETQINFOPARM
{
IIAPI_GENPARM gq_genParm;
II_PTR gq_stmtHandle;
II_ULONG gq_flags;
II_ULONG gq_mask;
II_LONG gq_rowCount;
II_BOOL gq_readonly
II_LONG gq_procedureReturn;
II_PTR gq_procedureHandle;
II_PTR gq_repeatQueryHandle;
II_CHAR gq_tableKey [TBL_KEY_SZ];
II_CHAR gq_objectKey [OBJ_KEY_SZ];
II_ULONG gq_cursorType
II_ULONG gq_rowStatus
II_LONG gq_rowPosition
II_LONG gq_rowCountEx
} IIAPI_GETQINFOPARM;
This function has the following parameters:
gq_genParm
Type: input and delayed output
gq_stmtHandle
Type: input
Specifies the statement handle identifying the query.
gq_flags
Type: delayed output
Provides status flags indicating result of the query. This parameter is 0 or a mask of the following values:
IIAPI_GQF_FAIL
IIAPI_GQF_ALL_UPDATED
IIAPI_GQF_NULLS_REMOVED
IIAPI_GQF_UNKNOWN_REPEAT_QUERY
IIAPI_GQF_END_OF_DATA
IIAPI_GQF_CONTINUE
IIAPI_GQF_INVALID_STATEMENT
IIAPI_GQF_TRANSACTION_INACTIVE
IIAPI_GQF_OBJECT_KEY
IIAPI_GQF_TABLE_KEY
IIAPI_GQF_NEW_EFFECTIVE_USER
IIAPI_GQF_FLUSH_QUERY_ID
IIAPI_GQF_ILLEGAL_XACT_STMT
gq_mask
Type: delayed output
Specifies the mask indicating the available response data. This parameter is 0 or a mask of the following values:
IIAPI_GQ_ROW_COUNT
IIAPI_GQ_CURSOR
IIAPI_GQ_PROCEDURE_RET
IIAPI_GQ_PROCEDURE_ID
IIAPI_GQ_REPEAT_QUERY_ID
IIAPI_GQ_TABLE_KEY
IIAPI_GQ_OBJECT_KEY
IIAPI_GQ_ROW_STATUS
IIAPI_GQ_ROW_COUNT_EX
This parameter is 0 if no response data is available.
gq_rowCount
Type: delayed output
Specifies the number of rows affected by the query. This parameter is valid only if the IIAPI_GQ_ROW_COUNT mask is set in gq_mask; otherwise, this parameter should be ignored.
gq_readonly
Type: delayed output
Indicates the type of cursor opened. Set to TRUE if the statement handle represents a cursor opened for READONLY; otherwise, FALSE. This information is available after IIapi_getDescriptor() or IIapi_getColumns() completes successfully.
This parameter is valid only if the IIAPI_GQ_CURSOR mask is set in gq_mask; otherwise, this parameter should be ignored.
gq_procedureReturn
Type: delayed output
Indicates the return status of an executed database procedure. This parameter is valid only if the IIAPI_GQ_PROCEDURE_RET mask is set in gq_mask; otherwise, this parameter should be ignored.
gq_procedureHandle
Type: delayed output
Specifies the procedure handle for a database procedure. This handle can be used for subsequent executions of the procedure. It is used as a parameter of a query when the query type is IIAPI_QT_EXEC_PROCEDURE.
This parameter is valid only if the IIAPI_GQ_PROCEDURE_ID mask is set in gq_mask; otherwise, this parameter should be ignored.
gq_repeatQueryHande
Type: delayed output
Specifies the repeat query handle for a repeat query. This handle is used for a future invocation of a repeat query. It is used as a parameter of a query when the query type is IIAPI_QT_EXEC_REPEAT_QUERY.
This parameter is valid only if the IIAPI_GQ_REPEAT_QUERY_ID mask is set in gq_mask; otherwise, this parameter should be ignored.
gq_tableKey
Type: delayed output
Specifies the table key value. This parameter is valid only if the IIAPI_GQ_TABLE_KEY mask is set in gq_mask; otherwise, this parameter should be ignored.
gq_objectKey
Type: delayed output
Specifies the object key value. This parameter is valid only if the IIAPI_GQ_OBJECT_KEY mask is set in gq_mask; otherwise, this parameter should be ignored.
gq_cursorType
Type: delayed output
Specifies the cursor attributes. This parameter is a mask of the following values:
IIAPI_CURSOR_UPDATE
IIAPI_CURSOR_SCROLL
This information is available after IIapi_getDescriptor() completes successfully.
This parameter is valid only if the IIAPI_GQ_CURSOR mask is set in gq_mask; otherwise, this parameter should be ignored.
gq_rowStatus
Type: delayed output
Specifies the cursor row status. This parameter is a mask of the following values:
IIAPI_ROW_BEFORE
IIAPI_ROW_FIRST
IIAPI_ROW_LAST
IIAPI_ROW_AFTER
IIAPI_ROW_INSERTED
IIAPI_ROW_UPDATED
IIAPI_ROW_DELETED
This information is available after IIapi_getColumns() completes successfully.
This parameter is valid only if the IIAPI_GQ_ROW_STATUS mask is set in gq_mask; otherwise, this parameter should be ignored.
gq_rowPosition
Type: delayed output
Specifies the row position of the cursor in the result set. This information is available after IIapi_getColumns() completes successfully. This parameter is valid only if the IIAPI_GQ_ROW_STATUS mask is set in gq_mask; otherwise, this parameter should be ignored.
gq_rowCountEx
Type: delayed output
Specifies the number of rows affected by the query. This parameter is valid only if the IIAPI_GQ_ROW_COUNT_EX mask is set in gq_mask; otherwise, this parameter should be ignored.