Função SQLGetDiagRec

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

Summary
O SQLGetDiagRec devolve os valores atuais de múltiplos campos de um registo de diagnóstico que contêm informações de erro, aviso e estado. Ao contrário do SQLGetDiagField, que devolve um campo de diagnóstico por chamada, o SQLGetDiagRec devolve vários campos comuns de um registo de diagnóstico, incluindo o SQLSTATE, o código de erro nativo e o texto da mensagem de diagnóstico.

Syntax

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

Arguments

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 das seguintes opções:

  • SQL_HANDLE_DBC

  • SQL_HANDLE_DBC_INFO_TOKEN

  • SQL_HANDLE_DESC

  • SQL_HANDLE_ENV

  • SQL_HANDLE_STMT

SQL_HANDLE_DBC_INFO_TOKEN alça é usada apenas pelo Gerenciador de Driver e pelo driver. Os aplicativos não devem usar esse tipo de identificador. Para mais informações sobre SQL_HANDLE_DBC_INFO_TOKEN, consulte Desenvolvimento da Consciência Connection-Pool num Condutor ODBC.

Manípulo
[Entrada] Um identificador para a estrutura de dados de diagnóstico, do tipo indicado por HandleType. Se HandleType estiver 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 a partir de 1.

SQLState
[Saída] Apontador para um buffer onde deveria um código SQLSTATE de cinco caracteres (e terminando NULL) para o registo de diagnóstico RecNumber. Os dois primeiros caracteres indicam a classe; os três seguintes indicam a subclasse. Esta informação está contida no campo SQL_DIAG_SQLSTATE diagnóstico. Para obter mais informações, consulte SQLSTATEs.

NativeErrorPtr
[Saída] Aponta para um buffer onde deves devolver o código de erro nativo, específico da fonte de dados. Esta informação está contida no campo SQL_DIAG_NATIVE diagnóstico.

MessageText
[Saída] Apontador para um buffer onde devolver a cadeia de texto da mensagem de diagnóstico. Esta informação está contida no campo SQL_DIAG_MESSAGE_TEXT diagnóstico. Para o formato da cadeia, veja Mensagens de Diagnóstico.

Se o MessageText for NULL, o TextLengthPtr continuará a devolver o número total de caracteres (excluindo o carácter de terminação nula para os dados de caracteres) disponíveis para devolver no buffer apontado pelo MessageText.

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

TextLengthPtr
[Saída] Apontador para um buffer onde deveria o número total de caracteres (excluindo o número de caracteres necessários para o carácter de terminação nula) disponíveis para devolver em *MessageText. Se o número de caracteres disponíveis para devolver for maior que BufferLength, o texto da mensagem de diagnóstico em *MessageText é truncado para BufferLength menos o comprimento de um carácter de terminação nula.

Devoluções

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA ou SQL_INVALID_HANDLE.

Diagnósticos

O SQLGetDiagRec não publica registos de diagnóstico por si próprio. Ele usa os seguintes valores de retorno para relatar o resultado de sua própria execução:

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

  • SQL_SUCCESS_WITH_INFO: O buffer *MessageText era demasiado pequeno para conter a mensagem de diagnóstico solicitada. Não foram gerados registos de diagnóstico. Para determinar que ocorreu um truncamento, a aplicação deve comparar o BufferLength com o número real de bytes disponíveis, que é escrito em *TextLengthPtr.

  • SQL_INVALID_HANDLE: A alça indicada por HandleType e Handle não era uma alça válida.

  • SQL_ERROR: Ocorreu uma das seguintes situações:

    • O número recreativo foi negativo ou 0.

    • BufferLength era inferior a zero.

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

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

Comments

Uma aplicação normalmente chama SQLGetDiagRec quando uma chamada anterior a uma função ODBC devolveu SQL_ERROR ou SQL_SUCCESS_WITH_INFO. No entanto, como qualquer função ODBC pode publicar registos diagnósticos zero ou mais 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 devolver alguns ou todos os registos na estrutura de dados de diagnóstico. O ODBC não impõe limite ao número de registos de diagnóstico que podem ser armazenados em simultâneo.

O SQLGetDiagRec não pode ser usado para devolver 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 este propósito.

O SQLGetDiagRec recupera apenas a informação de diagnóstico mais recentemente associada 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 analisar todos os registos de diagnóstico por looping, incrementando o RecNumber, desde que o SQLGetDiagRec devolva SQL_SUCCESS. As chamadas ao SQLGetDiagRec não são destrutivas para os campos do cabeçalho e do registo. A aplicação pode chamar novamente SQLGetDiagRec mais tarde para recuperar um campo de um registo, desde que nenhuma outra função, exceto SQLGetDiagRec, SQLGetDiagField ou SQLError, tenha sido chamada entretanto. A aplicação também pode obter uma contagem do número total de registos de diagnóstico disponíveis chamando SQLGetDiagField para recuperar o valor do campo SQL_DIAG_NUMBER, e depois 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 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ção". No entanto, o registro de erro não pode ser recuperado antes que a operação assíncrona seja concluída.

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 estão indicados nas secções "Campos de Cabeçalho" e "Campos de Registo" no SQLGetDiagField.

Uma chamada ao SQLGetDiagRec devolverá SQL_INVALID_HANDLE se o HandleType for SQL_HANDLE_SENV, o que denota um handle de ambiente partilhado. No entanto, se o HandleType for SQL_HANDLE_ENV, o Handle pode ser um handle de ambiente partilhado ou não partilhado.

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

Conteúdo relacionado

  • Last updated on