Función SQLInstallerError

Conformidad
Versión introducida: ODBC 3.0

Resumen
SQLInstallerError devuelve información de error o estado de las funciones del instalador odbc.

Sintaxis

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

Argumentos

iError
[Entrada] Número de registro de error. Los números válidos son de 1 a 8.

pfErrorCode
[Salida] Código de error del instalador. (Para obtener más información, vea "Comentarios").

lpszErrorMsg
[Salida] Puntero al almacenamiento del texto del mensaje de error.

cbErrorMsgMax
[Entrada] Longitud máxima del búfer szErrorMsg . Debe ser menor o igual que SQL_MAX_MESSAGE_LENGTH menos el carácter de terminación null.

cbErrorMsgMax
[Entrada] Longitud máxima del búfer szErrorMsg . Debe ser menor o igual que SQL_MAX_MESSAGE_LENGTH menos el carácter de terminación null.

pcbErrorMsg
[Salida] Puntero al número total de bytes (excepto el carácter de terminación NULL) disponible para devolver en lpszErrorMsg. Si el número de bytes disponibles para devolver es mayor o igual que cbErrorMsgMax, el texto del mensaje de error en lpszErrorMsgg se trunca a cbErrorMsgMax menos los bytes de carácter de terminación NULL. El argumento pcbErrorMsg puede ser un puntero nulo.

Devoluciones

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA o SQL_ERROR.

Diagnóstico

SQLInstallerError no publica valores de error por sí mismos. SQLInstallerError devuelve SQL_NO_DATA cuando no se puede recuperar ninguna información de error (en cuyo caso pfErrorCode no está definido). Si SQLInstallerError no puede acceder a los valores de error por cualquier motivo que normalmente devolverían SQL_ERROR, SQLInstallerError devuelve SQL_ERROR pero no publica ningún valor de error. Si no conoce la longitud de la cadena de advertencia (lpszErrorMsg), puede establecer lpszErrorMsg en NULL y llamar a SQLInstallerError. SQLInstallerError devolverá la longitud de la cadena de advertencia en cbErrorMsgMax. Si el búfer del mensaje de error es demasiado corto, SQLInstallerError devuelve SQL_SUCCESS_WITH_INFO y devuelve el valor pfErrorCode correcto para SQLInstallerError.

Para determinar si se produjo un truncamiento en el mensaje de error, una aplicación puede comparar el valor del argumento cbErrorMsgMax con la longitud real del texto del mensaje escrito en el argumento pcbErrorMsg . Si se produce un truncamiento, se debe asignar la longitud correcta del búfer para lpszErrorMsg y SQLInstallerError debe llamarse de nuevo con el registro iError correspondiente.

Comentarios

Una aplicación llama a SQLInstallerError cuando una llamada anterior a la función del instalador ODBC devuelve FALSE. Las funciones de instalación de controladores y controladores y controladores ODBC publican cero o más errores solo cuando se produce un error en la función (devuelve FALSE); por lo tanto, una aplicación llama a SQLInstallerError solo después de que se produzca un error en una función del instalador odbc.

La cola de errores del instalador odbc se vacía cada vez que se llama a una nueva función del instalador. Por lo tanto, una aplicación no puede esperar recuperar errores de funciones distintas de la última llamada de función del instalador.

Para recuperar varios errores de una llamada de función, una aplicación llama a SQLInstallerError varias veces.

Cuando no hay información adicional, SQLInstallerError devuelve SQL_NO_DATA, el argumento pfErrorCode no está definido, el argumento pcbErrorMsg es igual a 0 y el argumento lpszErrorMsg contiene un solo carácter de terminación NULL (a menos que el argumento cbErrorMsgMax sea igual a 0).