Partilhar via

Função SQLInstallerError

  • Artigo

Conformidade
Versão introduzida: ODBC 3.0

Resumo
SQLInstallerError retorna informações de erro ou status para as funções do instalador ODBC.

Sintaxe

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

Argumentos

iError
[Entrada] Número do registro de erro. Os números válidos são de 1 a 8.

pfErrorCode
[Saída] Código de erro do instalador. (Para obter mais informações, confira "Comentários".)

lpszErrorMsg
[Saída] Ponteiro para o armazenamento do texto da mensagem de erro.

cbErrorMsgMax
[Entrada] Comprimento máximo do buffer szErrorMsg . Isso deve ser menor ou igual a SQL_MAX_MESSAGE_LENGTH menos o caractere de terminação nula.

cbErrorMsgMax
[Entrada] Comprimento máximo do buffer szErrorMsg . Isso deve ser menor ou igual a SQL_MAX_MESSAGE_LENGTH menos o caractere de terminação nula.

pcbErrorMsg
[Saída] Ponteiro para o número total de bytes (excluindo o caractere de terminação nula) disponível para retornar em lpszErrorMsg. Se o número de bytes disponíveis para retornar for maior ou igual a cbErrorMsgMax, o texto da mensagem de erro em lpszErrorMsg será truncado para cbErrorMsgMax menos os bytes de caracteres de terminação nula. O argumento pcbErrorMsg pode ser um ponteiro nulo.

Retornos

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA ou SQL_ERROR.

Diagnósticos

SQLInstallerError não posta valores de erro para si mesmo. SQLInstallerError retorna SQL_NO_DATA quando não é possível recuperar nenhuma informação de erro (nesse caso , pfErrorCode é indefinido). Se SQLInstallerError não puder acessar valores de erro por qualquer motivo que normalmente retorne SQL_ERROR, SQLInstallerError retornará SQL_ERROR mas não postará nenhum valor de erro. Se você não souber o comprimento da cadeia de caracteres de aviso (lpszErrorMsg), poderá definir lpszErrorMsg como NULL e chamar SQLInstallerError. SQLInstallerError retornará o comprimento da cadeia de caracteres de aviso em cbErrorMsgMax. Se o buffer da mensagem de erro for muito curto, SQLInstallerError retornará SQL_SUCCESS_WITH_INFO e retornará o valor pfErrorCode correto para SQLInstallerError.

Para determinar se ocorreu um truncamento na mensagem de erro, um aplicativo pode comparar o valor no argumento cbErrorMsgMax com o comprimento real do texto da mensagem gravado no argumento pcbErrorMsg . Se ocorrer truncamento, o comprimento correto do buffer deverá ser alocado para lpszErrorMsg e SQLInstallerError deverá ser chamado novamente com o registro iError correspondente.

Comentários

Um aplicativo chama SQLInstallerError quando uma chamada anterior para a função de instalador ODBC retorna FALSE. As funções de instalação do ODBC e do driver ou do tradutor postam zero ou mais erros somente quando a função falha (retorna FALSE); portanto, um aplicativo chama SQLInstallerError somente depois que uma função de instalador ODBC falha.

A fila de erros do instalador ODBC é liberada sempre que uma nova função de instalador é chamada. Portanto, um aplicativo não pode esperar recuperar erros para funções diferentes da última chamada de função do instalador.

Para recuperar vários erros para uma chamada de função, um aplicativo chama SQLInstallerError várias vezes.

Quando não há informações adicionais, SQLInstallerError retorna SQL_NO_DATA, o argumento pfErrorCode é indefinido, o argumento pcbErrorMsg é igual a 0 e o argumento lpszErrorMsg contém um único caractere de terminação nula (a menos que o argumento cbErrorMsgMax seja igual a 0).