Call Level Interface Guide and Reference

SQLGetDiagRec - Get Multiple Fields Settings of Diagnostic Record

Purpose

Specification: DB2 CLI 5.0 ODBC 3.0 ISO CLI

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 error message text.

Syntax

SQLRETURN   SQLGetDiagRec    (SQLSMALLINT       HandleType,
                              SQLHANDLE         Handle,
                              SQLSMALLINT       RecNumber,
                              SQLCHAR           *SQLState,
                              SQLINTEGER        *NativeErrorPtr,
                              SQLCHAR           *MessageText,
                              SQLSMALLINT       BufferLength,
                              SQLSMALLINT       *TextLengthPtr);

Function Arguments

Table 106. SQLGetDiagRec Arguments

Data Type Argument Use Description
SQLSMALLINT HandleType input A handle type identifier that describes the type of handle for which diagnostics are desired. Must be one of the following:

SQL_HANDLE_ENV
SQL_HANDLE_DBC
SQL_HANDLE_STMT
SQL_HANDLE_DESC

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 a five-character 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 Length (in bytes) of the *MessageText buffer.
SQLSMALLINT TextLengthPtr 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 *MessageText. If the number of bytes 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.

Data Type	Argument	Use	Description
SQLSMALLINT	`HandleType`	input	A handle type identifier that describes the type of handle for which diagnostics are desired. Must be one of the following: SQL_HANDLE_ENV SQL_HANDLE_DBC SQL_HANDLE_STMT SQL_HANDLE_DESC
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 a five-character 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	Length (in bytes) of the *`MessageText` buffer.
SQLSMALLINT	`TextLengthPtr`	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 `MessageText`. If the number of bytes 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.

Usage

An application typically calls SQLGetDiagRec() when a previous call to a DB2 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() returns a character string containing multiple fields of the diagnostic data structure record. More information about the data returned can be found in SQLGetDiagField - Get a Field of Diagnostic Data.

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 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, then call SQLGetDiagRec() that many times.

For a description of the fields of the diagnostic data structure, see SQLGetDiagField - Get a Field of Diagnostic Data.

HandleType Argument

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 Header Fields and Record Fields in the description of SQLGetDescField().

Return Codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

Diagnostics

SQLGetDiagRec() does not post error values for itself. It uses the following return values to report the outcome of its own execution:

SQL_SUCCESS: The function successfully returned diagnostic information.
SQL_SUCCESS_WITH_INFO: The *MessageText buffer was too small to hold the requested diagnostic message. No diagnostic records were generated. To determine that a truncation occurred, the application must compare BufferLength to the actual number of bytes available, which is written to *StringLengthPtr.
SQL_INVALID_HANDLE: The handle indicated by HandleType and Handle was not a valid handle.
SQL_ERROR: One of the following occurred:
- RecNumber was negative or 0.
- BufferLength was less than zero.
SQL_NO_DATA: RecNumber was greater than the number of diagnostic records that existed for the handle specified in Handle. The function also returns SQL_NO_DATA for any positive RecNumber if there are no diagnostic records for Handle.

CLI Sample utilcli.c

(The complete sample utilcli.c is also available here .)

 
/* From the CLI sample utilcli.c */
/* ... */
 
    while ( SQLGetDiagRec( htype,
                           hndl,
                           i,
                           sqlstate,
                           &sqlcode,
                           message,
                           SQL_MAX_MESSAGE_LENGTH + 1,
                           &length
                         ) == SQL_SUCCESS ) {
       printf( "\n  SQLSTATE          = %s\n", sqlstate ) ;
       printf( "  Native Error Code = %ld\n", sqlcode ) ;
       printf( "%s\n", message ) ;
       i++ ;
    }
                              &fileOption, 14, &fileInd);

References

SQLGetDiagField - Get a Field of Diagnostic Data

[ Top of Page | Previous Page | Next Page ]