f90SQLGetDiagRec (SQLGetDiagRec)

Conformance

Version Introduced: ODBC 3.0

Standards Compliance: ISO 92

Summary

f90SQLGetDiagRec returns the current values of multiple fields of a diagnostic record that contains error, warning, and status information. Unlike f90SQLGetDiagField, which returns one diagnostic field per call, f90SQLGetDiagRec returns several commonly used fields of a diagnostic record, including the SQLSTATE, the native error code, and the diagnostic message text.

Syntax

f90SQLGetDiagRec

(HandleType, Handle, RecNumber, SQLState, NativeError, MessageText, MessageTextStrLength, iRet)

integer(SQLSMALLINT_KIND),intent(in)::	HandleType
integer(SQLHANDLE_KIND),intent(in)::	Handle
integer(SQLSMALLINT_KIND),intent(in)::	RecNumber
character(len=*)::	SQLState
integer(SQLINTEGER_KIND)::	NativeError
character(len=*)::	MessageText
integer(SQLSMALLINT_KIND)::	MessageTextStrLength
integer(SQLRETURN_KIND),intent(out)::	iRet

Arguments

HandleType [Input]

A handle type identifier that describes the type of handle for which diagnostics are required. Must be one of the following:

SQL_HANDLE_ENV

SQL_HANDLE_DBC

SQL_HANDLE_STMT

SQL_HANDLE_DESC

Handle [Input]

A handle for the diagnostic data structure, of the type indicated by HandleType. If HandleType is SQL_HANDLE_ENV, Handle can be either a shared or unshared environment handle.

RecNumber [Input]

Indicates the status record from which the application seeks information. Status records are numbered from 1.

SQLState [Output]

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. This information is contained in the SQL_DIAG_SQLSTATE diagnostic field. For more information, see "SQLSTATEs" in Chapter 9.

NativeError [Output]

Pointer to a buffer in which to return the native error code, specific to the data source. This information is contained in the SQL_DIAG_NATIVE diagnostic field.

MessageText [Output]

Buffer in which to return the diagnostic message text string. This information is contained in the SQL_DIAG_MESSAGE_TEXT diagnostic field. For the format of the string, see the "Diagnostic Messages" section of Chapter 9. . There is no maximum length of the diagnostic message text. If the value returned in MessageText is of a Unicode string (when calling SQLGetDiagRecW), Len(MessageText) must be an even number.

MessageTextStrLength [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 Len(MessageText), then the diagnostic message text in MessageText is truncated to Len(MessageText) minus the length of a null-termination character.

iRet [Output]

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.

Diagnostics

f90SQLGetDiagRec does not post diagnostic records 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 Len(MessageText) to the actual number of bytes available, which is written to MessageTextStrLength.
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.
MessageTextBufferLength 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.

Comments

An application typically calls f90SQLGetDiagRec 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 f90SQLGetDiagRec after any ODBC function call. An application can call f90SQLGetDiagRec 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.

f90SQLGetDiagRec 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 f90SQLGetDiagField for this purpose.

f90SQLGetDiagRec retrieves only the diagnostic information most recently associated with the handle specified in the Handle argument. If the application calls another ODBC function, except f90SQLGetDiagRec, f90SQLGetDiagField, 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 f90SQLGetDiagRec returns SQL_SUCCESS. Calls to f90SQLGetDiagRec are non-destructive to the header and record fields. The application can call f90SQLGetDiagRec again at a later time to retrieve a field from a record, as long as no other function, except f90SQLGetDiagRec, f90SQLGetDiagField, 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 f90SQLGetDiagField to retrieve the value of the SQL_DIAG_NUMBER field, and then call f90SQLGetDiagRec that many times.

For a description of the fields of the diagnostic data structure, see f90SQLGetDiagField. For more information, see "Using f90SQLGetDiagRec and f90SQLGetDiagField" in Chapter 9.

HandleType Argument

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 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 in f90SQLGetDiagField.

A call to f90SQLGetDiagRec 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 unshared environment handle.

Related Subroutines

For information about	See
Obtaining a field of a diagnostic record or a field of the diagnostic header	f90SQLGetDiagField