Returns the current value of a field of a diagnostic data structure, associated with a specific handle, that contains error, warning, and status information.
SQLRETURN SQLGetDiagField (
SQLSMALLINT HandleType, /* fHandleType */
SQLHANDLE Handle, /* hHandle */
SQLSMALLINT RecNumber, /* iRecNumber */
SQLSMALLINT DiagIdentifier, /* fDiagIdentifier */
SQLPOINTER DiagInfoPtr, /* pDiagInfo */
SQLSMALLINT BufferLength, /* cbDiagInfoMax */
SQLSMALLINT *StringLengthPtr); /* *pcgDiagInfo */
Data type | Argument | Use | Description |
---|---|---|---|
SQLSMALLINT | HandleType | input | A handle type identifier that describes the type of handle
for which diagnostics are required. The handle type identifier include:
|
SQLHANDLE | Handle | input | A handle for the diagnostic data structure, of the type indicated by HandleType. |
SQLSMALLINT | RecNumber | input | Indicates the status record from which the application seeks information. Status records are numbered from 1. If the DiagIdentifier argument indicates any field of the diagnostics header record, RecNumber must be 0. If not, it should be greater than 0. |
SQLSMALLINT | DiagIdentifier | input | Indicates the field of the diagnostic data structure whose value is to be returned. For more information, see DiagIdentifier argument. |
SQLPOINTER | DiagInfoPtr | output | Pointer to a buffer in which to return the diagnostic information. The data type depends on the value of DiagIdentifier. |
SQLINTEGER | BufferLength | input | If DiagIdentifier is ODBC-defined
diagnostic:
|
SQLSMALLINT * | StringLengthPtr | output | Pointer to a buffer in which to return the total number of bytes, excluding the number of bytes required for the null-termination character, available to return in *DiagInfoPtr, for character data. If the number of bytes available to return is greater than or equal to BufferLength, then the text in *DiagInfoPtr is truncated to BufferLength minus the length of a null-termination character. This argument is ignored for non-character data. |
Any 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.
An application can scan all diagnostic records by incrementing RecNumber, as long as SQLGetDiagField() returns SQL_SUCCESS. The number of status records is indicated in the SQL_DIAG_NUMBER header field. Calls to SQLGetDiagField() are non-destructive as far as the header and status records are concerned. The application can call SQLGetDiagField() again at a later time to retrieve a field from a record, as long as another function other than SQLGetDiagField(), SQLGetDiagRec(), or SQLError() has not been called in the interim, which would post records on the same handle.
An application can call SQLGetDiagField() to return any diagnostic field at any time, with the exception of SQL_DIAG_ROW_COUNT, which will return SQL_ERROR if Handle was not a statement handle on which an SQL statement had been executed. If any other diagnostic field is undefined, the call to SQLGetDiagField() will return SQL_SUCCESS (provided no other error is encountered), and an undefined value is returned for the field.
Each handle type can have diagnostic information associated with it. The HandleType argument denotes the handle type of Handle.
Some header and record fields cannot be returned for all types of handles: environment, connection, statement, and descriptor. Those handles for which a field is not applicable are indicated in the Header Field and Record Fields sections.
No CLI-specific header diagnostic field should be associated with an environment handle.
This argument indicates the identifier of the field required from the diagnostic data structure. If RecNumber is greater than or equal to 1, the data in the field describes the diagnostic information returned by a function. If RecNumber is 0, the field is in the header of the diagnostic data structure, so it contains data pertaining to the function call that returned the diagnostic information, not the specific information. Refer to the list of header and record fields for the DiagIdentifier argument for further information.
Status records are placed in a sequence based upon row number and the type of the diagnostic.
Within each row, or for all those records that do not correspond to a row or for which the row number is unknown, the first record listed is determined using a set of sorting rules. After the first record, the order of the other records affecting a row is undefined. An application cannot assume that errors precede warnings after the first record. Applications should scan the entire diagnostic data structure to obtain complete information about an unsuccessful call to a function.
None.