f90SQLGetDiagField (SQLGetDiagField)

Conformance

Version Introduced: ODBC 3.0

Standards Compliance: ISO 92

Summary

f90SQLGetDiagField returns the current value of a field of a record of the diagnostic data structure (associated with a specified handle) that contains error, warning, and status information.

Syntax

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. If the DiagIdentifier argument indicates any field of the diagnostics header, RecNumber is ignored. If not, it should be greater than 0.

DiagIdentifier [Input]

Indicates the field of the diagnostic whose value is to be returned. For more information, see the "DiagIdentifier Argument" section in "Comments."

DiagInfo [Output]

Buffer in which to return the diagnostic information. The data type depends on the value of DiagIdentifier.

If the value in DiagInfo is a Unicode string (when calling SQLGetDiagFieldW), the Len(DiagInfo) argument must be an even number.

When f90SQL Point-Format version of this subroutine is used (See Appendix 2), and if DiagIdentifier is a driver-defined attribute, the application indicates the nature of the attribute to the Driver Manager by setting the DiagInfoBufferLength argument. DiagInfoBufferLength can have the following values

• If *DiagInfoPtr is a pointer to a character string, then Len(DiagInfo) is the length of the string or SQL_NTS.
• If *DiagInfoPtr is a pointer to a binary buffer, then the application places the result of the f90SQLLenBinaryAttr(length) function in DiagInfoBufferLength. This places a negative value in DiagInfoBufferLength.
• If *DiagInfoPtr is a pointer to a value other than a character string or binary string, then DiagInfoBufferLength should have the value SQL_IS_POINTER.
• If *DiagInfoPtr is contains a fixed-length data type, then DiagInfoBufferLength is either SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT, or SQL_IS_USMALLINT, as appropriate.

DiagInfoStrLength [Output]

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 DiagInfo, for character data. If the number of bytes available to return is greater than Len(DiagInfo), then the text in DiagInfo is truncated to Len(DiagInfo) minus the length of a null-termination character.

iRet [Output]

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE, or SQL_NO_DATA.

Diagnostics

f90SQLGetDiagField 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: DiagInfo was too small to hold the requested diagnostic field, so the data in the diagnostic field was truncated. To determine that a truncation occurred, the application must compare Len(DiagInfo) to the actual number of bytes available, which is written to DiagInfoStrLength.
  
  
• SQL_INVALID_HANDLE: The handle indicated by HandleType and Handle was not a valid handle.
  
  
• SQL_ERROR: One of the following occurred:
  
  

• The DiagIdentifier argument was not one of the valid values.
• The DiagIdentifier argument was SQL_DIAG_CURSOR_ROW_COUNT, SQL_DIAG_DYNAMIC_FUNCTION, SQL_DIAG_DYNAMIC_FUNCTION_CODE, or SQL_DIAG_ROW_COUNT, but Handle was not a statement handle. (The Driver Manager returns this diagnostic.)
• The RecNumber argument was negative or 0 when DiagIdentifier indicated a field from a diagnostic record. RecNumber is ignored for header fields.
• The value requested was a character string and DiagInfoBufferLength 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 f90SQLGetDiagField to accomplish one of three goals:

1. To obtain specific error or warning information when a function call has returned SQL_ERROR or SQL_SUCCESS_WITH_INFO (or SQL_NEED_DATA for the f90SQLBrowseConnect function).
   
   
2. To find out the number of rows in the data source that were affected when insert, delete, or update operations were performed with a call to f90SQLExecute, f90SQLExecDirect, f90SQLBulkOperations, or f90SQLSetPos (from the SQL_DIAG_ROW_COUNT header field), or to find out the number of rows that exist in the current open cursor, if the driver is able to provide this information (from the SQL_DIAG_CURSOR_ROW_COUNT header field).
   
   
3. To determine which function was executed by a call to f90SQLExecDirect or f90SQLExecute (from the SQL_DIAG_DYNAMIC_FUNCTION and SQL_DIAG_DYNAMIC_FUNCTION_CODE header fields).

Any ODBC function can post zero or more diagnostic records each time it is called, so an application can call f90SQLGetDiagField after any ODBC function call. There is no limit to the number of diagnostic records that can be stored at any one time. f90SQLGetDiagField retrieves only the diagnostic information most recently associated with the diagnostic data structure specified in the Handle argument. If the application calls an ODBC function other than f90SQLGetDiagField or f90SQLGetDiagRec, 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 f90SQLGetDiagField returns SQL_SUCCESS. The number of status records is indicated in the SQL_DIAG_NUMBER header field. Calls to f90SQLGetDiagField are non-destructive to the header and record fields. The application can call f90SQLGetDiagField again at a later time to retrieve a field from a record, as long as a function other than the diagnostic functions has not been called in the interim, which would post records on the same handle.

An application can call f90SQLGetDiagField to return any diagnostic field at any time, with the exception of SQL_DIAG_CURSOR_ROW_COUNT or SQL_DIAG_ROW_COUNT, which will return SQL_ERROR if Handle is not a statement handle. If any other diagnostic field is undefined, the call to f90SQLGetDiagField will return SQL_SUCCESS (provided no other diagnostic is encountered), and an undefined value is returned for the field.

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 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 following.

If HandleType is SQL_HANDLE_ENV, Handle can be either a shared or unshared environment handle.

No driver-specific header diagnostic fields should be associated with an environment handle.

The only diagnostic header fields that are defined for a descriptor handle are SQL_DIAG_NUMBER and SQL_DIAG_RETURNCODE.

DiagIdentifier Argument

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, and therefore contains data pertaining to the function call that returned the diagnostic information, not the specific information.

Drivers can define driver-specific header and record fields in the diagnostic data structure.

An ODBC 3.0 application working with an ODBC 2.x driver will only be able to call f90SQLGetDiagField with a DiagIdentifier argument of SQL_DIAG_CLASS_ORIGIN, SQL_DIAG_CLASS_SUBCLASS_ORIGIN, SQL_DIAG_CONNECTION_NAME, SQL_DIAG_MESSAGE_TEXT, SQL_DIAG_NATIVE, SQL_DIAG_NUMBER, SQL_DIAG_RETURNCODE, SQL_DIAG_SERVER_NAME, or SQL_DIAG_SQLSTATE. All other diagnostic fields will return SQL_ERROR.

Header Fields

The following header fields can be included in the DiagIdentifier argument.

Record Fields

The following record fields can be included in the DiagIdentifier argument:

Values of the Dynamic Function Fields

The following table describes the values of SQL_DIAG_DYNAMIC_FUNCTION and SQL_DIAG_DYNAMIC_FUNCTION_CODE that apply to each type of SQL statement executed by a call to f90SQLExecute or f90SQLExecDirect. The driver can add driver-defined values to those listed.

Sequence of Status Records

Status records are placed in a sequence based upon row number and the type of the diagnostic. The Driver Manager determines the final order in which to return status records that it generates. The driver determines the final order in which to return status records that it generates.

If diagnostic records are posted by both the Driver Manager and the driver, the Driver Manager is responsible for ordering them.

If there are two or more status records, the sequence of the records is determined first by row number. The following rules apply to determining the sequence of diagnostic records by row:

• Records that do not correspond to any row appear in front of records that correspond to a particular row, because SQL_NO_ROW_NUMBER is defined to be  - 1.
  
  
• Records for which the row number is unknown appear in front of all other records, because SQL_ROW_NUMBER_UNKNOWN is defined to be  - 2.
  
  
• For all records that pertain to specific rows, records are sorted by the value in the SQL_DIAG_ROW_NUMBER field. All errors and warnings of the first row affected are listed, then all errors and warnings of the next row affected, and so on.

Note: The ODBC 3.0 Driver Manager does not order status records in the diagnostic queue if SQLSTATE 01S01 (Error in row) is returned by an ODBC 2.x driver, or SQLSTATE 01S01 (Error in row) is returned by an ODBC 3.0 driver when SQLExtendedFetch is called or f90SQLSetPos is called on a cursor that has been positioned with SQLExtendedFetch.

Within each row, or for all those records that do not correspond to a row or for which the row number is unknown, or for all those records with a row number equal to SQL_NO_ROW_NUMBER, 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 on an unsuccessful call to a function.

The following rules are followed to determine the first record within a row. The record with the highest rank is the first record. The source of a record (Driver Manager, driver, gateway, and so on) is not considered when ranking records.

• Errors. Status records that describe errors have the highest rank. The following rules are followed to sort errors:
  
  
• Records that indicate a transaction failure or possible transaction failure outrank all other records.
  
  
• If two or more records describe the same error condition, then SQLSTATEs defined by the X/Open CLI specification (classes 03 through HZ) outrank ODBC- and driver-defined SQLSTATEs.
  
  
• Implementation-defined No Data values. Status records that describe driver-defined No Data values (class 02) have the second highest rank.
  
  
• Warnings. Status records that describe warnings (class 01) have the lowest rank. If two or more records describe the same warning condition, then warning SQLSTATEs defined by the X/Open CLI specification outrank ODBC- and driver-defined SQLSTATEs.

Related Subroutines