Função SQLGetDiagRec

Conformidade
Versão introduzida: Conformidade de padrões do ODBC 3.0: ISO 92

Resumo
SQLGetDiagRec retorna os valores atuais de vários campos de um registro de diagnóstico que contém informações de erro, aviso e status. Ao contrário de SQLGetDiagField, que retorna um campo de diagnóstico por chamada, SQLGetDiagRec retorna vários campos comumente usados de um registro de diagnóstico, incluindo o SQLSTATE, o código de erro nativo e o texto da mensagem de diagnóstico.

Sintaxe

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

Argumentos

Handletype
[Entrada] Um identificador de tipo de identificador que descreve o tipo de identificador para o qual o diagnóstico é necessário. Deve ser uma destas opções:

• SQL_HANDLE_DBC

• SQL_HANDLE_DBC_INFO_TOKEN

• SQL_HANDLE_DESC

• SQL_HANDLE_ENV

• SQL_HANDLE_STMT

SQL_HANDLE_DBC_INFO_TOKEN identificador é usado apenas pelo Driver Manager e pelo driver. Os aplicativos não devem usar esse tipo de identificador. Para obter mais informações sobre SQL_HANDLE_DBC_INFO_TOKEN, consulte Developing Connection-Pool Awareness in an ODBC Driver.

Handle
[Entrada] Um identificador para a estrutura de dados de diagnóstico, do tipo indicado por HandleType. Se HandleType for SQL_HANDLE_ENV, Handle poderá ser um identificador de ambiente compartilhado ou não compartilhado.

RecNumber
[Entrada] Indica o registro de status do qual o aplicativo busca informações. Os registros de status são numerados de 1.

SQLState
[Saída] Ponteiro para um buffer no qual retornar um código SQLSTATE de cinco caracteres (e encerrar NULL) para o recNumber do registro de diagnóstico. Os dois primeiros caracteres indicam a classe ; os três seguintes indicam a subclasse. Essas informações estão contidas no campo diagnóstico SQL_DIAG_SQLSTATE. Para obter mais informações, consulte SQLSTATEs.

NativeErrorPtr
[Saída] Ponteiro para um buffer no qual retornar o código de erro nativo, específico para a fonte de dados. Essas informações estão contidas no campo diagnóstico SQL_DIAG_NATIVE.

MessageText
[Saída] Ponteiro para um buffer no qual retornar a cadeia de caracteres de texto da mensagem de diagnóstico. Essas informações estão contidas no campo diagnóstico SQL_DIAG_MESSAGE_TEXT. Para o formato da cadeia de caracteres, consulte Mensagens de diagnóstico.

Se MessageText for NULL, TextLengthPtr ainda retornará o número total de caracteres (excluindo o caractere de terminação nula para dados de caractere) disponíveis para retornar no buffer apontado por MessageText.

BufferLength
[Entrada] Comprimento do buffer *MessageText em caracteres. Não há comprimento máximo do texto da mensagem de diagnóstico.

TextLengthPtr
[Saída] Ponteiro para um buffer no qual retornar o número total de caracteres (excluindo o número de caracteres necessários para o caractere de terminação nula) disponível para retornar em *MessageText. Se o número de caracteres disponíveis para retornar for maior que BufferLength, o texto da mensagem de diagnóstico em *MessageText será truncado para BufferLength menos o comprimento de um caractere de terminação nula.

Retornos

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA ou SQL_INVALID_HANDLE.

Diagnósticos

SQLGetDiagRec não publica registros de diagnóstico para si mesmo. Ele usa os seguintes valores retornados para relatar o resultado de sua própria execução:

• SQL_SUCCESS: a função retornou informações de diagnóstico com êxito.

• SQL_SUCCESS_WITH_INFO: o buffer *MessageText era muito pequeno para conter a mensagem de diagnóstico solicitada. Nenhum registro de diagnóstico foi gerado. Para determinar que ocorreu um truncamento, o aplicativo deve comparar BufferLength com o número real de bytes disponíveis, que é gravado em *TextLengthPtr.

• SQL_INVALID_HANDLE: o identificador indicado por HandleType e Handle não era um identificador válido.

• SQL_ERROR: ocorreu um dos seguintes procedimentos:

  • RecNumber foi negativo ou 0.

  • BufferLength era menor que zero.

  • Ao usar a notificação assíncrona, a operação assíncrona no identificador não foi concluída.

• SQL_NO_DATA: RecNumber foi maior que o número de registros de diagnóstico que existiam para o identificador especificado em Handle. A função também retornará SQL_NO_DATA para qualquer RecNumber positivo se não houver registros de diagnóstico para Handle.

Comentários

Um aplicativo normalmente chama SQLGetDiagRec quando uma chamada anterior para uma função ODBC retorna SQL_ERROR ou SQL_SUCCESS_WITH_INFO. No entanto, como qualquer função ODBC pode postar zero ou mais registros de diagnóstico sempre que for chamada, um aplicativo pode chamar SQLGetDiagRec após qualquer chamada de função ODBC. Um aplicativo pode chamar SQLGetDiagRec várias vezes para retornar alguns ou todos os registros na estrutura de dados de diagnóstico. O ODBC não impõe nenhum limite para o número de registros de diagnóstico que podem ser armazenados ao mesmo tempo.

SQLGetDiagRec não pode ser usado para retornar campos do cabeçalho da estrutura de dados de diagnóstico. (O argumento RecNumber deve ser maior que 0.) O aplicativo deve chamar SQLGetDiagField para essa finalidade.

SQLGetDiagRec recupera apenas as informações de diagnóstico mais recentemente associadas ao identificador especificado no argumento Handle . Se o aplicativo chamar outra função ODBC, exceto SQLGetDiagRec, SQLGetDiagField ou SQLError, todas as informações de diagnóstico das chamadas anteriores no mesmo identificador serão perdidas.

Um aplicativo pode verificar todos os registros de diagnóstico fazendo loop, incrementando RecNumber, desde que SQLGetDiagRec retorne SQL_SUCCESS. As chamadas para SQLGetDiagRec não são indestrutivas para os campos de cabeçalho e registro. O aplicativo pode chamar SQLGetDiagRec novamente mais tarde para recuperar um campo de um registro, desde que nenhuma outra função, exceto SQLGetDiagRec, SQLGetDiagField ou SQLError, tenha sido chamada nesse ínterim. O aplicativo também pode recuperar uma contagem do número total de registros de diagnóstico disponíveis chamando SQLGetDiagField para recuperar o valor do campo SQL_DIAG_NUMBER e, em seguida, chamando SQLGetDiagRec muitas vezes.

Para obter uma descrição dos campos da estrutura de dados de diagnóstico, consulte SQLGetDiagField. Para obter mais informações, consulte Usando SQLGetDiagRec e SQLGetDiagField e Implementando SQLGetDiagRec e SQLGetDiagField.

Chamar uma API diferente daquela que está sendo executada de forma assíncrona gerará HY010 "Erro de sequência de funções". No entanto, o registro de erro não pode ser recuperado antes da conclusão da operação assíncrona.

Argumento HandleType

Cada tipo de identificador pode ter informações de diagnóstico associadas a ele. O argumento HandleType indica o tipo de identificador do argumento Handle .

Alguns campos de cabeçalho e registro não podem ser retornados para identificadores de ambiente, conexão, instrução e descritor. Esses identificadores para os quais um campo não é aplicável são indicados nas seções "Campos de Cabeçalho" e "Campos de Registro" em SQLGetDiagField.

Uma chamada para SQLGetDiagRec retornará SQL_INVALID_HANDLE se HandleType for SQL_HANDLE_SENV, o que indica um identificador de ambiente compartilhado. No entanto, se HandleType for SQL_HANDLE_ENV, Handle poderá ser um identificador de ambiente compartilhado ou não compartilhado.

Funções relacionadas

Para obter informações sobre	Consulte
Obtendo um campo de um registro de diagnóstico ou um campo do cabeçalho de diagnóstico	Função SQLGetDiagField

Consulte Também

Referência de API do ODBC
Arquivos de cabeçalho ODBC
Programa ODBC de exemplo