Error Handling and Problem Determination | DB2(R) Universal Database for OS/390 V7.1 Application Certification Guide (IBM DB2 Certification Guide Series)


Team-Fly

	DB2 Universal Database for OS/390 v7.1 Application Certification Guide By Susan Lawson
	Table of Contents

	Chapter 11. ODBC/CLI Programming

Error Handling and Problem Determination

DB2 ODBC functions return their status as an integer return code, indicated by the SQLRETURN data type. This return code can have several values, documented in Table 11-1.

Table 11-1. Status Return Codes of DB2 ODBC Functions

RETURN CODE	EXPLANATION
SQL_SUCCESS	The function completed successfully; no additional SQLSTATE information is available.
SQL_SUCCESS_WITH_INFO	The function completed successfully with a warning or other information. Call SQLGetDiagRec() to receive the SQLSTATE and any other informational messages or warnings.
SQL_NO_DATA_FOUND	The function returned successfully, but no relevant data was found. When this is returned after the execution of an SQL statement, additional information might be available, which can be obtained by calling SQLGetDiagRec().
SQL_NEED_DATA	The application tried to execute an SQL statement, but DB2 ODBC lacks parameter data that the application had indicated would be passed at execute time.
SQL_ERROR	The function failed. Call SQLGetDiagRec() to receive the SQLSTATE and any other error information.
SQL_INVALID_HANDLE	The function failed due to an invalid input handle (environment, connection, or statement handle). This is a programming error. No further information is available.

Retrieving Diagnostic Information

The SQLGetDiagRec() function is used to retrieve additional diagnostic information following an unsuccessful DB2 ODBC call or if the SQLRETURN value is SQL_SUCCESS_WITH_INFO. It may be called after any function call.

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

This returns the current values of multiple fields of a diagnostic record that contains error, warning, and status information. Information returned includes the SQLSTATE, the native error code, and the error message text.

If the application calls any function other than SQLGetDiagRec(), diagnostic information from the previous calls 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 diagnostic 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() has been called in the interim.

DB2 programmers are used to dealing with a diagnostic structure called the SQLCA. A DB2 extension to the ODBC and CLI specifications allows a DB2 ODBC program to retrieve this structure. SQLGetSQLCA() is used to return the SQLCA associated with preparing and executing a SQL statement, fetching data, or closing a cursor. The SQLCA can return information that supplements the information obtained by using SQLGetDiagRec().

 SQLRETURN SQLGetSQLCA (SQLHENV       EnvironmentHandle,                         SQLHDBC       ConnectionHandle,                        SQLHSTMT      StatementHandle,                        struct sqlca *pSqlca);

Application Trace

DB2 ODBC has two trace options, the diagnostic trace and the application trace. Traces are turned on by entries in the initialization file. The DB2 ODBC diagnostic trace captures information to use in DB2 ODBC problem determination. The trace is intended for use under the direction of the IBM Support Center.

The application trace is designed for diagnosis of application errors. When activated, every ODBC call is traced, and information about the call, including input parameters, is written to a trace file. In the following example, the trace is written to the file allocated to the APLTRACE DD statement.

 [COMMON]  APPLTRACE=1 APPLTRACEFILENAME="DD:APLTRACE"


Team-Fly

Top