SQLRETURN SQLGetDiagRec (
SQLSMALLINT HandleType, /* fHandleType */
SQLHANDLE Handle, /* hHandle */
SQLSMALLINT RecNumber, /* iRecNumber */
SQLCHAR *SQLState, /* *pszSqlState */
SQLINTEGER *NativeErrorPtr, /* *pfNativeError */
SQLCHAR *MessageText, /* *pszErrorMsg */
SQLSMALLINT BufferLength, /* cbErrorMsgMax */
SQLSMALLINT *TextLengthPtr); /* *pcbErrorMsg */
Data type | Argument | Use | Description |
---|---|---|---|
SQLSMALLINT | HandleType | input | A handle type identifier that describes the type of handle
for which diagnostics are desired. 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. |
SQLCHAR * | SQLState | output | Pointer to a buffer in which to return 5 characters plus a NULL terminator for the SQLSTATE code pertaining to the diagnostic record RecNumber. The first two characters indicate the class; the next three indicate the subclass. |
SQLINTEGER * | NativeErrorPtr | output | Pointer to a buffer in which to return the native error code, specific to the data source. |
SQLCHAR * | MessageText | output | Pointer to a buffer in which to return the error message text. The fields returned by SQLGetDiagRec() are contained in a text string. |
SQLINTEGER | BufferLength | input | Number of SQLCHAR elements (or SQLWCHAR elements for the Unicode variant of this function) needed to store the MessageText buffer. |
SQLSMALLINT * | TextLengthPtr | output | Pointer to a buffer in which to return the total number of SQLCHAR elements (or SQLWCHAR elements for the Unicode variant of this function), excluding the null-termination character, available to return in *MessageText. If the number of SQLCHAR or SQLWCHAR elements available to return is greater than BufferLength, then the error message text in *MessageText is truncated to BufferLength minus the length of a null-termination character. |
An application typically calls SQLGetDiagRec() when a previous call to a CLI function has returned anything other than SQL_SUCCESS. However, any function can post zero or more errors each time it is called, so an application can call SQLGetDiagRec() after any function call. An application can call SQLGetDiagRec() multiple times to return some or all of the records in the diagnostic data structure.
SQLGetDiagRec() cannot be used to return fields from the header of the diagnostic data structure (the RecNumber argument must be greater than 0). The application should call SQLGetDiagField() for this purpose.
SQLGetDiagRec() retrieves only the diagnostic information most recently associated with the handle specified in the Handle argument. If the application calls another function, except SQLGetDiagRec() or SQLGetDiagField(), any diagnostic information from the previous calls on the same handle is lost.
An application can scan all diagnostic records by looping, incrementing RecNumber, as long as SQLGetDiagRec() returns SQL_SUCCESS. Calls to SQLGetDiagRec() are non-destructive to the header and record fields. The application can call SQLGetDiagRec() again at a later time to retrieve a field from a record, as long as no other function, except SQLGetDiagRec() or SQLGetDiagField(), has been called in the interim. The application can call SQLGetDiagField() to retrieve the value of the SQL_DIAG_NUMBER field, which is the total number of diagnostic records available. SQLGetDiagRec() should then be called that many times.
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 list of header and record fields for the DiagIdentifier argument.
/* get multiple fields settings of diagnostic record */
SQLGetDiagRec(SQL_HANDLE_STMT,
hstmt,
1,
sqlstate,
&sqlcode,
message,
200,
&length);