SQLInstallerError 函数

一致性
引入的版本：ODBC 3.0

摘要
SQLInstallerError 返回 ODBC 安装程序函数的错误或状态信息。

语法

  
RETCODE SQLInstallerError(  
     WORD      iError,  
     DWORD *   pfErrorCode,  
     LPSTR     lpszErrorMsg,  
     WORD      cbErrorMsgMax,  
     WORD *    pcbErrorMsg);  

参数

iError
[输入]错误记录编号。 有效数字介于 1 到 8。

pfErrorCode
[输出]安装程序错误代码。 (有关详细信息，请参阅“注释”。)

lpszErrorMsg
[输出]指向错误消息文本的存储的指针。

cbErrorMsgMax
[输入] szErrorMsg 缓冲区的最大长度。 此值必须小于或等于 SQL_MAX_MESSAGE_LENGTH 减去 null 终止字符。

cbErrorMsgMax
[输入] szErrorMsg 缓冲区的最大长度。 此值必须小于或等于 SQL_MAX_MESSAGE_LENGTH 减去 null 终止字符。

印制板ErrorMsg
[输出]指向总字节数的指针， (不包括可在 lpszErrorMsg 中返回的 null 终止字符) 。 如果可返回的字节数大于或等于 cbErrorMsgMax， 则 lpszErrorMsg 中的错误消息文本将被截断为 cbErrorMsgMax 减去 null 终止字符字节。 “oemErrorMsg”参数可以是 null 指针。

返回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA或SQL_ERROR。

诊断

SQLInstallerError 不会为自己发布错误值。 如果 SQLInstallerError 无法检索任何错误信息 () 未定义 pfErrorCode，SQLInstallerError 将返回SQL_NO_DATA。 如果 SQLInstallerError 由于任何通常返回SQL_ERROR原因而无法访问错误值， SQLInstallerError 将返回SQL_ERROR但不发布任何错误值。 如果不知道警告字符串 (lpszErrorMsg) 的长度，可以将 lpszErrorMsg 设置为 NULL 并调用 SQLInstallerError。 然后，SQLInstallerError 将返回 cbErrorMsgMax 中警告字符串的长度。 如果错误消息的缓冲区太短，SQLInstallerError 将返回SQL_SUCCESS_WITH_INFO并返回 SQLInstallerError 的正确 pfErrorCode 值。

若要确定错误消息中是否发生截断，应用程序可以将 cbErrorMsgMax 参数中的值与写入 到印刷板ErrorMsg 参数的消息文本的实际长度进行比较。 如果确实发生截断，则应为 lpszErrorMsg 分配正确的缓冲区长度，并且应使用相应的 iError 记录再次调用 SQLInstallerError。

注释

当对 ODBC 安装程序函数的上一次调用返回 FALSE 时，应用程序会调用 SQLInstallerError 。 ODBC 安装程序和驱动程序或翻译器安装程序函数仅当函数失败 (返回 FALSE) 时，才会发布零个或多个错误;因此，应用程序仅在 ODBC 安装程序函数失败后调用 SQLInstallerError 。

每次调用新的安装程序函数时，都会刷新 ODBC 安装程序错误队列。 因此，应用程序不能期望从上次安装程序函数调用中检索其他函数的错误。

若要检索函数调用的多个错误，应用程序多次调用 SQLInstallerError 。

如果没有其他信息，SQLInstallerError 将返回SQL_NO_DATA，pfErrorCode 参数未定义，pfErrorMsg 参数等于 0，lpszErrorMsg 参数包含单个 null 终止字符 (除非 cbErrorMsgMax 参数等于 0) 。