![[Note]](images.admon/note.gif) | |
| |
SQLGetDiagField function (CLI)
SQLGetDiagField() returns the current value of a field of a diagnostic data structure, associated with a specific handle, that contains error, warning, and status information.
Syntax:
SQLRETURN SQLGetDiagField ( SQLSMALLINT HandleType, /* fHandleType */ SQLHANDLE Handle, /* hHandle */ SQLSMALLINT RecNumber, /* iRecNumber */ SQLSMALLINT DiagIdentifier, /* fDiagIdentifier */ SQLPOINTER DiagInfoPtr, /* pDiagInfo */ SQLSMALLINT BufferLength, /* cbDiagInfoMax */ SQLSMALLINT *StringLengthPtr); /* *pcgDiagInfo */ )
An application typically calls SQLGetDiagField() to accomplish one of three goals:
To obtain specific error or warning information when a function call has returned the SQL_ERROR or SQL_SUCCESS_WITH_INFO (or SQL_NEED_DATA for the SQLBrowseConnect() function) return codes.
To find out the number of rows in the data source that were affected when insert, delete, or update operations were performed with a call to SQLExecute(), SQLExecDirect(), SQLBulkOperations(), or SQLSetPos() (from the SQL_DIAG_ROW_COUNT header field), or to find out the number of rows that exist in the current open static scrollable cursor (from the SQL_DIAG_CURSOR_ROW_COUNT header field).
To determine which function was executed by a call to SQLExecDirect() or SQLExecute() (from the SQL_DIAG_DYNAMIC_FUNCTION and SQL_DIAG_DYNAMIC_FUNCTION_CODE header fields).
Any DB2 CLI function can post zero or more errors each time it is called, so an application can call SQLGetDiagField() after any function call. SQLGetDiagField() retrieves only the diagnostic information most recently associated with the diagnostic data structure specified in the Handle argument. If the application calls another function, any diagnostic information from a previous call with the same handle is lost.
Example. How to retrieve SQLCA-equivalent information:
SQLHANDLE hstmt; /* statement handle */
SQLCHAR *stmt1 = (SQLCHAR *)"SELECT * FROM org";
SQLINTEGER diagPtr;
SQLSMALLINT strLenPtr;
...
/* prepare the statement */
cliRC = SQLPrepare(hstmt, stmt1, SQL_NTS);
/* execute the statement */
cliRC = SQLExecute(hstmt);
/* get the SQLCA-equivalent information - sqlerrd(3)*/
cliRC = SQLGetDiagField (SQL_HANDLE_STMT,
hstmt,
0,
SQL_DIAG_CURSOR_ROW_COUNT,
&diagPtr,
SQL_IS_INTEGER,
&strLenPtr);
printf(" Estimated number of rows that are returned: %d\n", diagPtr);
/* get the SQLCA-equivalent information - sqlerrd(4)*/
cliRC = SQLGetDiagField (SQL_HANDLE_STMT,
hstmt,
0,
SQL_DIAG_RELATIVE_COST_ESTIMATE,
&diagPtr,
SQL_IS_INTEGER,
&strLenPtr);
printf(" Estimated cost of prepare: %d\n", diagPtr);
SQLCA (SQL communications area)
An SQLCA is a collection of variables that is updated at the end of the execution of every SQL statement. A program that contains executable SQL statements and is precompiled with option LANGLEVEL SAA1 (the default) or MIA must provide exactly one SQLCA, though more than one SQLCA is possible by having one SQLCA per thread in a multi-threaded application.
SQLCA field descriptions:
sqlcaid
An "eye catcher" for storage dumps containing 'SQLCA'. The sixth byte is 'L' if line number information is returned from parsing an SQL procedure body.
sqlerrp
Begins with a three-letter identifier indicating the product, followed by five alphanumeric characters indicating the version, release, and modification level of the product. The characters A-Z indicate a modification level higher than 9. A indicates modification level 10, B indicates modification level 11, and so on. For example, SQL0901C means DB2® Version 9, release 1, modification level 12).
If SQLCODE indicates an error condition, this field identifies the module that returned the error.
This field is also used when a successful connection is completed.
