Função SQLGetDiagRec

Conformidade
Versão Introduzida: Conformidade com as Normas ODBC 3.0: ISO 92

Summary
SQLGetDiagRec retorna os valores atuais de múltiplos campos de um registro diagnóstico que contêm informações de erro, aviso e status. Diferente do SQLGetDiagField, que retorna um campo de diagnóstico por chamada, o SQLGetDiagRec retorna vários campos comumente usados de um registro 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 um dos seguintes:

  • 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 mais informações sobre SQL_HANDLE_DBC_INFO_TOKEN, veja Desenvolvimento de Conscientização Connection-Pool em um Driver ODBC.

Manejar
[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] Apontador para um buffer no qual retorna um código SQLSTATE de cinco caracteres (e terminando NULL) para o registro diagnóstico RecNumber. Os dois primeiros caracteres indicam a classe; os três seguintes indicam a subclasse. Essas informações estão contidas no campo SQL_DIAG_SQLSTATE diagnóstico. Para obter mais informações, consulte SQLSTATEs.

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

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

Se MessageText for NULL, TextLengthPtr ainda retornará o número total de caracteres (excluindo o caractere de término nulo para dados de caracteres) disponíveis para serem retornados no buffer apontado pelo 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] Apontador para um buffer no qual retorna o número total de caracteres (excluindo o número de caracteres necessários para o caractere de terminação nula) disponíveis para retorno em *MessageText. Se o número de caracteres disponíveis para retorno for maior que BufferLength, o texto da mensagem de diagnóstico em *MessageText é truncado para BufferLength menos o comprimento de um caractere de terminação nula.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA ou SQL_INVALID_HANDLE.

Diagnostics

O 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 com êxito as informações de diagnóstico.

  • SQL_SUCCESS_WITH_INFO: O buffer *MessageText era pequeno demais para armazenar a mensagem de diagnóstico solicitada. Nenhum registro diagnóstico foi gerado. Para determinar que ocorreu um truncamento, o aplicativo deve comparar o BufferLength com o número real de bytes disponíveis, que é escrito 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:

    • Número rec estava negativo ou 0.

    • BufferLength era menor que zero.

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

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

Comments

Uma aplicação normalmente chama SQLGetDiagRec quando uma chamada anterior para uma função ODBC retornou SQL_ERROR ou SQL_SUCCESS_WITH_INFO. No entanto, como qualquer função ODBC pode registrar registros diagnósticos zero ou mais a cada vez que é chamada, uma aplicação pode chamar SQLGetDiagRec após qualquer chamada de função ODBC. Uma aplicação 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 limite ao número de registros diagnósticos 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.) A aplicação deve chamar SQLGetDiagField para esse propósito.

SQLGetDiagRec recupera apenas as informações de diagnóstico mais recentemente associadas ao handle especificado no argumento Handle . Se a aplicação chamar outra função ODBC, exceto SQLGetDiagRec, SQLGetDiagField ou SQLError, qualquer informação de diagnóstico das chamadas anteriores no mesmo handle é perdida.

Uma aplicação pode escanear todos os registros de diagnóstico por meio de looping, incrementando o RecNumber, desde que o SQLGetDiagRec retorne SQL_SUCCESS. Chamadas para SQLGetDiagRec não são destrutivas para os campos de cabeçalho e registro. A aplicação pode chamar SQLGetDiagRec novamente em um momento posterior para recuperar um campo de um registro, desde que nenhuma outra função, exceto SQLGetDiagRec, SQLGetDiagField ou SQLError, tenha sido chamada nesse meio tempo. A aplicação também pode recuperar a contagem do número total de registros de diagnóstico disponíveis chamando SQLGetDiagField para recuperar o valor do campo SQL_DIAG_NUMBER, e então chamando SQLGetDiagRec tantas vezes.

Para uma descrição dos campos da estrutura de dados de diagnóstico, veja SQLGetDiagField. Para obter mais informações, consulte Using SQLGetDiagRec and SQLGetDiagField and Implementing SQLGetDiagRec and 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 denota o tipo de handle 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. Os handles para os quais um campo não é aplicável são indicados nas seções "Campos de Cabeçalho" e "Campos de Registro" no SQLGetDiagField.

Uma chamada para SQLGetDiagRec retornará SQL_INVALID_HANDLE se HandleType estiver SQL_HANDLE_SENV, o que denota um handle de ambiente compartilhado. No entanto, se o HandleType for SQL_HANDLE_ENV, o Handle pode ser um handle de ambiente compartilhado ou não compartilhado.

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

Conteúdo relacionado

  • Last updated on