Version Introduced: ODBC 3.0
Standards Compliance: ISO 92
SQLGetDiagRec returns the current values of multiple fields of a diagnostic record that contains error, warning, and status information. Unlike SQLGetDiagField, which returns one diagnostic field per call, SQLGetDiagRec returns several commonly used fields of a diagnostic record, including the SQLSTATE, the native error code, and the diagnostic message text.
SQLRETURN SQLGetDiagRec( SQLSMALLINT HandleType, SQLHANDLE Handle, SQLSMALLINT RecNumber, SQLCHAR * Sqlstate, SQLINTEGER * NativeErrorPtr, SQLCHAR * MessageText, SQLSMALLINT BufferLength, SQLSMALLINT * TextLengthPtr);
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.
SQLGetDiagRec does not post diagnostic records for itself. It uses the following return values to report the outcome of its own execution:
An application typically calls SQLGetDiagRec when a previous call to an ODBC function has returned SQL_SUCCESS or SQL_SUCCESS_WITH_INFO. However, because any ODBC function can post zero or more diagnostic records each time it is called, an application can call SQLGetDiagRec after any ODBC function call. An application can call SQLGetDiagRec multiple times to return some or all of the records in the diagnostic data structure. ODBC imposes no limit to the number of diagnostic records that can be stored at any one time.
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 ODBC function, except SQLGetDiagRec, SQLGetDiagField, or SQLError, 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 nondestructive 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, SQLGetDiagField, or SQLError, has been called in the interim. The application can also retrieve a count of the total number of diagnostic records available by calling SQLGetDiagField to retrieve the value of the SQL_DIAG_NUMBER field, and then calling SQLGetDiagRec that many times.
For a description of the fields of the diagnostic data structure, see SQLGetDiagField. For more information, see "Using SQLGetDiagRec and SQLGetDiagField" and "Implementing SQLGetDiagRec and SQLGetDiagField" in Chapter 15: Diagnostics.
Each handle type can have diagnostic information associated with it. The HandleType argument denotes the handle type of the Handle argument.
Some header and record fields cannot be returned for environment, connection, statement, and descriptor handles. Those handles for which a field is not applicable are indicated in the "Header Fields" and "Record Fields" sections in SQLGetDiagField.
A call to SQLGetDiagRec will return SQL_INVALID_HANDLE if HandleType is SQL_HANDLE_SENV, which denotes a shared environment handle. However, if HandleType is SQL_HANDLE_ENV, Handle can be either a shared or an unshared environment handle.
|For information about||See|
|Obtaining a field of a diagnostic record or a field of the diagnostic header||SQLGetDiagField|