Mimer SQL Documentation PREV NEXT

Mimer Developer Site

www.mimer.com/developer


6.4 SQLInstallerError


The following specification of SQLInstallerError is from the Microsoft ODBC SDK Reference.

Summary

SQLInstallerError returns error or status information for the ODBC installer functions.

Syntax
RETCODE SQLInstallerError( 
WORD iError, 
DWORD* pfErrorCode, 
LPSTR lpszErrorMsg, 
WORD cbErrorMsgMax, 
WORD* pcbErrorMsg); 
Arguments
iError [Input] 

Error record number. Valid numbers are from 1 to 8.

pfErrorCode [Output] 

Installer error code. For more information, see Comments.

lpszErrorMsg [Output] 

Pointer to storage for the error message text.

cbErrorMsgMax [Input] 

Maximum length of the szErrorMsg buffer. This must be less than or equal to SQL_MAX_MESSAGE_LENGTH minus the null-termination character.

cbErrorMsgMax [Input] 

Maximum length of the szErrorMsg buffer. This must be less than or equal to SQL_MAX_MESSAGE_LENGTH minus the null-termination character.

pcbErrorMsg [Output] 

Pointer to the total number of bytes (excluding the null-termination character) available to return in lpszErrorMsg.

If the number of bytes available to return is greater than or equal to cbErrorMsgMax, the error message text in lpszErrorMsg is truncated to cbErrorMsgMax minus the null-termination character bytes. The pcbErrorMsg argument can be a null pointer.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, or SQL_ERROR.

Diagnostics

SQLInstallerError does not post error values for itself.

SQLInstallerError returns SQL_NO_DATA when it is unable to retrieve any error information (in which case pfErrorCode is undefined).

If SQLInstallerError cannot access error values for any reason that would normally return SQL_ERROR, it returns SQL_ERROR, but does not post any error values.

If either the lpszErrorMsg argument is NULL, or the cbErrorMsgMax is less than or equal to 0 then this function returns SQL_ERROR.

If the buffer for the error message is too short, SQLInstallerError returns SQL_SUCCESS_WITH_INFO, and returns the correct pfErrorCode value for SQLInstallerError.

To determine whether a truncation occurred in the error message, an application can compare the value in the cbErrorMsgMax argument to the actual length of the message text written to the pcbErrorMsg argument.

If truncation does occur, the correct buffer length should be allocated for lpszErrorMsg and SQLInstallerError should be called again with the corresponding iError record.

Comments

An application calls SQLInstallerError when a previous call to the ODBC installer function returns FALSE.

ODBC installer and driver or translator setup functions post zero or more errors only when the function fails (returns FALSE); therefore, an application calls SQLInstallerError only after an ODBC installer function fails.

The ODBC installer error queue is flushed each time a new installer function is called. Therefore, an application cannot expect to retrieve errors for functions other than from the last installer function call.

To retrieve multiple errors for a function call, an application calls SQLInstallerError multiple times.

When there is no additional information, SQLInstallerError returns SQL_NO_DATA, the pfErrorCode argument is undefined, the pcbErrorMsg argument equals 0, and the lpszErrorMsg argument contains a single null-termination character (unless the cbErrorMsgMax argument is equal to 0).


Upright
Mimer Information Technology AB
Voice: +46 18 780 92 00
Fax: +46 18 780 92 40
info@mimer.se
Mimer SQL Documentation PREV NEXT