Header and record fields for the DiagIdentifier argument (CLI)
Header fields
You can specify the following header fields for the DiagIdentifier
argument. The only diagnostic header fields that you can define for a descriptor field are
SQL_DIAG_NUMBER and SQL_DIAG_RETURNCODE.
| Header field | Return type | Description |
|---|---|---|
|
SQL_DIAG_CURSOR_ROW_
COUNT |
SQLINTEGER | The count of rows in the cursor. The semantics of the field depend upon the
SQLGetInfo()
information types, which indicate which row counts are available for each cursor type (in the
SQL_CA2_CRC_EXACT and SQL_CA2_CRC_APPROXIMATE bits):
A value is defined in this field only for statement handles and only after a call to the SQLExecute(), SQLExecDirect(), or SQLMoreResults() function. Calling the SQLGetDiagField() function with a DiagIdentifier argument value of SQL_DIAG_CURSOR_ROW_COUNT on a handle other than a statement handle returns SQL_ERROR. |
|
SQL_DIAG_DYNAMIC_
FUNCTION |
CHAR * | A string that describes the SQL statement that the underlying function executed (for the values that CLI supports, see Dynamic function fields). A value is defined in this field only for statement handles, and only after a call to the SQLExecute(), SQLExecDirect(), or SQLMoreResults() function. |
|
SQL_DIAG_DYNAMIC_
FUNCTION_CODE |
SQLINTEGER | A numeric code that describes the SQL statement that was executed by the
underlying function (for the values that CLI supports, see Dynamic function fields). A value is defined in this field only for
statement handles, and only after a call to the SQLExecute(), SQLExecDirect(), or SQLMoreResults()
function. Calling the SQLGetDiagField() function with a DiagIdentifier argument value of SQL_DIAG_DYNAMIC_FUNCTION_CODE on a handle other than a statement handle returns SQL_ERROR. |
| SQL_DIAG_NETWORK_STATISTICS | SQL_NET_STATS Note: The SQL_NET_STATS structure is defined in the
sqlcli1.h file. |
A structure containing network statistics for a connection. The statistics include the following information:
CLI accumulates statistics for a connection when the SQL_ATTR_NETWORK_STATISTICS connection attribute is enabled. After an application calls the SQLGetDiagField() function to retrieve the statistics, CLI resets the internal counters that the connection uses to accumulate the statistics. A value is defined in this field only for connection handles, SQL_HANDLE_DBC.
|
| SQL_DIAG_NUMBER | SQLINTEGER | The number of status records that are available for the specified handle. |
|
SQL_DIAG_RELATIVE_
COST_ESTIMATE |
SQLINTEGER | A relative cost estimate of the resources that are required to process a statement if the SQLPrepare() function is invoked and successful. If deferred prepare is enabled, this field has the value 0 until the statement is executed. |
| SQL_DIAG_RETURNCODE | RETCODE | The return code of the last executed function that is associated with the specified handle. If a function has not been called on the Handle, SQL_SUCCESS is returned in the SQL_DIAG_RETURNCODE field. |
| SQL_DIAG_ROW_COUNT | SQLINTEGER | The number of rows that are affected by an insert, delete, or update performed by the SQLExecute(), SQLExecDirect(), or SQLSetPos() function. The value of this field is defined after a cursor specification has been executed and only for statement handles. The data in this field is returned in the RowCountPtr argument of the SQLRowCount() function. The data in this field is reset after every function call, whereas the row count returned by theSQLRowCount() function remains the same until the statement state is reset to the prepared or allocated state. |
| SQL_DIAG_TOLERATED_ERROR | Beginning with WebSphere® Federated
Server V9.1, you can specify an Error Tolerant Nested Table Expression (ETNTE). This allows you to
specify errors that can be tolerated and is of particular use when one or more data sources are
unavailable during a UNION ALL query. By tolerating the absence of one of the
unions (because the source is offline) a result set can still be processed and
SQLFetch can be called repeatedly until it returns
SQL_NO_DATA_FOUND(100).If tolerate errors are encountered then a CLI application can
discover this by doing one of two things:
|
|
|
SQL_DIAG_SQLCA |
STRUCT SQLCA * |
A structure containing SQLCA for the connection. The SQLCA defined in this field is only for connection handles, SQL_HANDLE_DBC, and immediately after a call to the SQLConnect(),SQLDriverConnect(), or SQLBrowseConnect() function. The SQLCA defined in this field belongs to the database connection. It is recommended that this header field is retrieved only after the connection is established successfully, although the value is available in this field even for a failed connection. The SQLCA for the connection can be retrieved using the SQLGetDiagField() API at any time during connection. The SQLCA is reset after the connection is disconnected. For all other cases, you should preferably use theSQLGetDiagField() API with identifiers other than SQL_DIAG_SQLCA, and theSQLGetDiagRec() API to retrieve diagnostic information. |
Note:
The SQL_DIAG_SQLCA identifier in the SQLGetDiagField() API specifies a value to the SQLCA structure for the connection handle at the time of connection. The SQLCA persists until the connection is disconnected, and then it is reset. It is recommended you use this identifier only for retrieving the SQLCA for the connection after the connection is established. For any other diagnostic information, use ODBC recommended API's and diagnostic identifiers as applicable.
.Record fields
You can specify the following record fields for the DiagIdentifier
argument.
| Record field | Return type | Description |
|---|---|---|
| SQL_DIAG_BAD_FILENAME | CHAR * | External
Table (ET) feature is supported. Remote external table LOADs work by sending the contents of a file
from the client system to the server where the data is then parsed and loaded into a DB2 table. Bad
rows are logged in a BAD file. After creating named ET, one can use INSERT INTO statements to load
data from the external file into a table, or locally SELECT FROM statements to query the external
table. Note: Direct SELECT query is not supported for remote ET file. Calling the
SQLGetDiagField() function with a DiagIdentifier argument value of
SQL_DIAG_BAD_FILENAME returns the BAD file name (absolute path name) in application memory buffer,
if previous LOAD/UNLOAD operation has generated any. This DiagIndentifier is
supported only for statement handle. |
| SQL_DIAG_CLASS_ORIGIN | CHAR * | A string that indicates the document that defines the class and subclass
portions of the SQLSTATE value in a record. CLI always returns an empty string in the SQL_DIAG_CLASS_ORIGIN field. |
| SQL_DIAG_COLUMN_NUMBER | SQLINTEGER | A value that represents the column number in a result set if the value of the SQL_DIAG_ROW_NUMBER field is a valid row number in a rowset or set of parameters. Result set column numbers always start at 1; if the status record pertains to a bookmark column, the value of the field can be zero. The field has the value SQL_NO_COLUMN_NUMBER if the status record is not associated with a column number. If CLI cannot determine the column number that a record is associated with, this field has the value SQL_COLUMN_NUMBER_UNKNOWN. A value is defined in this field only for statement handles. |
| SQL_DIAG_CONNECTION_NAME | CHAR * | A string that indicates the name of the connection that a diagnostic record
relates to. CLI always returns an empty string in the SQL_DIAG_CONNECTION_NAME field. |
| SQL_DIAG_DB2ZLOAD_LOAD_MSGS | SQLCHAR * | A string containing the load messages returned by the server. |
| SQL_DIAG_DB2ZLOAD_RETCODE | SQLINTEGER | A numeric value that represents the highest return code from the LOAD operation. If there is no return code from the LOAD, it will return -1. |
| SQL_DIAG_ERRMC | CHAR * | A string containing one or more message tokens that are separated by X'FF'. |
| SQL_DIAG_LOG_FILENAME | CHAR * | External
Table (ET) feature is supported. Remote external table LOADs work by sending the contents of a file
from the client system to the server where the data is then parsed and loaded into a DB2 table. Load
errors are logged in detail in a LOG file. After creating named ET, one can use INSERT INTO
statements to load data from the external file into a table, or locally SELECT FROM statements to
query the external table. Note: Direct SELECT query is not supported for remote ET file. Calling the
SQLGetDiagField() function with a DiagIdentifier argument value of
SQL_DIAG_LOG_FILENAME returns the LOG file name (absolute path name) in application memory buffer,
if previous LOAD/UNLOAD operation has generated any. This DiagIndentifier is
supported only for statement handle. |
| SQL_DIAG_MESSAGE_TEXT | CHAR * | An informational message about an error or warning. |
| SQL_DIAG_NATIVE | SQLINTEGER | A native error code that is specific to a driver or data source, if a code exists; otherwise, the driver returns 0. |
| SQL_DIAG_ROW_NUMBER | SQLINTEGER | The row number in the rowset, or the parameter number in the set of parameters, with which the status record is associated. This field has the value SQL_NO_ROW_NUMBER if the status record is not associated with a row number. If CLI cannot determine the row number that a record is associated with, this field has the value SQL_ROW_NUMBER_UNKNOWN. A value is defined in this field only for statement handles. |
| SQL_DIAG_SERVER_NAME | CHAR * | A string that indicates the server name that a diagnostic record relates to. The string is the same as the value returned for a call to the SQLGetInfo() function with an InfoType argument value of SQL_DATA_SOURCE_NAME. For diagnostic data structures associated with an environment handle and for diagnostics that do not relate to any server, this field is a 0-length string. |
| SQL_DIAG_SQLSTATE | CHAR * | A 5-character SQLSTATE diagnostic code. |
| SQL_DIAG_SUBCLASS_ORIGIN | CHAR * | A string, with the same format and valid values as the SQL_DIAG_CLASS_ORIGIN field, that identifies the defining portion of the subclass portion of the SQLSTATE code. |
Values of the dynamic function fields
The following table describes the values of SQL_DIAG_DYNAMIC_FUNCTION and
SQL_DIAG_DYNAMIC_FUNCTION_CODE that apply to each type of SQL statement that is executed by a call
to the SQLExecute() or SQLExecDirect() function. CLI uses the values in
this table; ODBC specifies other values.
| SQL statement executed | Value of SQL_DIAG_ DYNAMIC_FUNCTION | Value of SQL_DIAG_DYNAMIC_ FUNCTION_CODE |
|---|---|---|
| alter-table-statement | ALTER TABLE | SQL_DIAG_ALTER_TABLE |
| create-index-statement | CREATE INDEX | SQL_DIAG_CREATE_INDEX |
| create-table-statement | CREATE TABLE | SQL_DIAG_CREATE_TABLE |
| create-view-statement | CREATE VIEW | SQL_DIAG_CREATE_VIEW |
| cursor-specification | SELECT CURSOR | SQL_DIAG_SELECT_CURSOR |
| delete-statement-positioned | DYNAMIC DELETE CURSOR |
SQL_DIAG_DYNAMIC_DELETE_
CURSOR |
| delete-statement-searched | DELETE WHERE | SQL_DIAG_DELETE_WHERE |
| drop-index-statement | DROP INDEX | SQL_DIAG_DROP_INDEX |
| drop-table-statement | DROP TABLE | SQL_DIAG_DROP_TABLE |
| drop-view-statement | DROP VIEW | SQL_DIAG_DROP_VIEW |
| grant-statement | GRANT | SQL_DIAG_GRANT |
| insert-statement | INSERT | SQL_DIAG_INSERT |
| ODBC-procedure-extension | CALL | SQL_DIAG_PROCEDURE_CALL |
| revoke-statement | REVOKE | SQL_DIAG_REVOKE |
| update-statement-positioned | DYNAMIC UPDATE CURSOR |
SQL_DIAG_DYNAMIC_UPDATE_
CURSOR |
| update--statement-searched | UPDATE WHERE | SQL_DIAG_UPDATE_WHERE |
| merge-statement | MERGE | SQL_DIAG_MERGE |
| Unknown | empty string |
SQL_DIAG_UNKNOWN_
STATEMENT |