Função SQLGetDiagField

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

Resumo
SQLGetDiagField retorna o valor atual de um campo de um registro da estrutura de dados de diagnóstico (associada a um identificador especificado) que contém informações de erro, aviso e status.

Sintaxe

SQLRETURN SQLGetDiagField(  
     SQLSMALLINT     HandleType,  
     SQLHANDLE       Handle,  
     SQLSMALLINT     RecNumber,  
     SQLSMALLINT     DiagIdentifier,  
     SQLPOINTER      DiagInfoPtr,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   StringLengthPtr);  

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. Se o argumento DiagIdentifier indicar qualquer campo do cabeçalho de diagnóstico, RecNumber será ignorado. Caso contrário, deve ser mais de 0.

DiagIdentifier
[Entrada] Indica o campo do diagnóstico cujo valor deve ser retornado. Para obter mais informações, consulte a seção "Argumento DiagIdentifier " em "Comentários".

DiagInfoPtr
[Saída] Ponteiro para um buffer no qual retornar as informações de diagnóstico. O tipo de dados depende do valor de DiagIdentifier. Se DiagInfoPtr for um tipo inteiro, os aplicativos deverão usar um buffer do SQLULEN e inicializar o valor como 0 antes de chamar essa função, pois alguns drivers podem gravar apenas os 32 bits inferiores ou 16 bits de um buffer e deixar o bit de ordem superior inalterado.

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

BufferLength
[Entrada] Se DiagIdentifier for um diagnóstico definido por ODBC e DiagInfoPtr apontar para uma cadeia de caracteres ou um buffer binário, esse argumento deverá ter o comprimento de *DiagInfoPtr. Se DiagIdentifier for um campo definido por ODBC e *DiagInfoPtr for um inteiro, BufferLength será ignorado. Se o valor em *DiagInfoPtr for uma cadeia de caracteres Unicode (ao chamar SQLGetDiagFieldW), o argumento BufferLength deverá ser um número par.

Se DiagIdentifier for um campo definido pelo driver, o aplicativo indicará a natureza do campo para o Gerenciador de Driver definindo o argumento BufferLength . BufferLength pode ter os seguintes valores:

• Se DiagInfoPtr for um ponteiro para uma cadeia de caracteres, BufferLength será o comprimento da cadeia de caracteres ou SQL_NTS.

• Se DiagInfoPtr for um ponteiro para um buffer binário, o aplicativo colocará o resultado da macro SQL_LEN_BINARY_ATTR(length) em BufferLength. Isso coloca um valor negativo em BufferLength.

• Se DiagInfoPtr for um ponteiro para um valor diferente de uma cadeia de caracteres ou cadeia de caracteres binária, BufferLength deverá ter o valor SQL_IS_POINTER.

• Se *DiagInfoPtr contiver um tipo de dados de comprimento fixo, BufferLength será SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT ou SQL_IS_USMALLINT, conforme apropriado.

StringLengthPtr
[Saída] Ponteiro para um buffer no qual retornar o número total de bytes (excluindo o número de bytes necessários para o caractere de terminação nula) disponível para retornar em *DiagInfoPtr, para dados de caracteres. Se o número de bytes disponíveis para retornar for maior ou igual a BufferLength, o texto em *DiagInfoPtr será truncado para BufferLength menos o comprimento de um caractere de terminação nula.

Retornos

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE ou SQL_NO_DATA.

Diagnósticos

SQLGetDiagField 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: *DiagInfoPtr era muito pequeno para manter o campo de diagnóstico solicitado. Portanto, os dados no campo de diagnóstico foram truncados. Para determinar que ocorreu um truncamento, o aplicativo deve comparar BufferLength com o número real de bytes disponíveis, que é gravado em *StringLengthPtr.

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

• SQL_ERROR: ocorreu um dos seguintes procedimentos:

  • O argumento DiagIdentifier não era um dos valores válidos.

  • O argumento DiagIdentifier era SQL_DIAG_CURSOR_ROW_COUNT, SQL_DIAG_DYNAMIC_FUNCTION, SQL_DIAG_DYNAMIC_FUNCTION_CODE ou SQL_DIAG_ROW_COUNT, mas Handle não era um identificador de instrução. (O Gerenciador de Driver retorna esse diagnóstico.)

  • O argumento RecNumber era negativo ou 0 quando DiagIdentifier indicava um campo de um registro de diagnóstico. RecNumber é ignorado para campos de cabeçalho.

  • O valor solicitado era uma cadeia de caracteres e 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 SQLGetDiagField para atingir uma das três metas:

1. Para obter informações específicas de erro ou aviso quando uma chamada de função tiver retornado SQL_ERROR ou SQL_SUCCESS_WITH_INFO (ou SQL_NEED_DATA para a função SQLBrowseConnect ).

2. Para determinar o número de linhas na fonte de dados que foram afetadas quando operações de inserção, exclusão ou atualização foram executadas com uma chamada para SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos (do campo de cabeçalho SQL_DIAG_ROW_COUNT), ou para determinar o número de linhas que existem no cursor aberto atual, se o driver puder fornecer essas informações (do campo de cabeçalho SQL_DIAG_CURSOR_ROW_COUNT).

3. Para determinar qual função foi executada por uma chamada para SQLExecDirect ou SQLExecute (dos campos de cabeçalho SQL_DIAG_DYNAMIC_FUNCTION e SQL_DIAG_DYNAMIC_FUNCTION_CODE).

Qualquer função ODBC pode postar zero ou mais registros de diagnóstico sempre que for chamada, para que um aplicativo possa chamar SQLGetDiagField após qualquer chamada de função ODBC. Não há limite para o número de registros de diagnóstico que podem ser armazenados ao mesmo tempo. SQLGetDiagField recupera apenas as informações de diagnóstico mais recentemente associadas à estrutura de dados de diagnóstico especificada no argumento Handle . Se o aplicativo chamar uma função ODBC diferente de SQLGetDiagField ou SQLGetDiagRec, todas as informações de diagnóstico de uma chamada anterior com o mesmo identificador serão perdidas.

Um aplicativo pode verificar todos os registros de diagnóstico incrementando RecNumber, desde que SQLGetDiagField retorne SQL_SUCCESS. O número de registros de status é indicado no campo de cabeçalho SQL_DIAG_NUMBER. As chamadas para SQLGetDiagField não são indestrutivas para os campos de cabeçalho e registro. O aplicativo pode chamar SQLGetDiagField novamente mais tarde para recuperar um campo de um registro, desde que uma função diferente das funções de diagnóstico não tenha sido chamada nesse ínterim, o que postaria registros no mesmo identificador.

Um aplicativo pode chamar SQLGetDiagField para retornar qualquer campo de diagnóstico a qualquer momento, exceto por SQL_DIAG_CURSOR_ROW_COUNT ou SQL_DIAG_ROW_COUNT, que retornará SQL_ERROR se Handle não for um identificador de instrução. Se qualquer outro campo de diagnóstico for indefinido, a chamada para SQLGetDiagField retornará SQL_SUCCESS (desde que nenhum outro diagnóstico seja encontrado) e um valor indefinido será retornado para o campo.

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 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" a seguir.

Se HandleType for SQL_HANDLE_ENV, Handle poderá ser um identificador de ambiente compartilhado ou não compartilhado.

Nenhum campo de diagnóstico de cabeçalho específico do driver deve ser associado a um identificador de ambiente.

Os únicos campos de cabeçalho de diagnóstico definidos para um identificador de descritor são SQL_DIAG_NUMBER e SQL_DIAG_RETURNCODE.

Argumento DiagIdentifier

Esse argumento indica o identificador do campo necessário da estrutura de dados de diagnóstico. Se RecNumber for maior ou igual a 1, os dados no campo descreverão as informações de diagnóstico retornadas por uma função. Se RecNumber for 0, o campo estará no cabeçalho da estrutura de dados de diagnóstico e, portanto, conterá dados relativos à chamada de função que retornou as informações de diagnóstico, não às informações específicas.

Os drivers podem definir campos de cabeçalho e registro específicos do driver na estrutura de dados de diagnóstico.

Um aplicativo ODBC 3*.x* que trabalha com um driver ODBC 2*.x* só poderá chamar SQLGetDiagField com um argumento DiagIdentifier de SQL_DIAG_CLASS_ORIGIN, SQL_DIAG_CLASS_SUBCLASS_ORIGIN, SQL_DIAG_CONNECTION_NAME, SQL_DIAG_MESSAGE_TEXT, SQL_DIAG_NATIVE, SQL_DIAG_NUMBER, SQL_DIAG_RETURNCODE, SQL_DIAG_SERVER_NAME ou SQL_DIAG_SQLSTATE. Todos os outros campos de diagnóstico retornarão SQL_ERROR.

Campos de cabeçalho

Os campos de cabeçalho listados na tabela a seguir podem ser incluídos no argumento DiagIdentifier .

Campos de registro

Os campos de registro listados na tabela a seguir podem ser incluídos no argumento DiagIdentifier .

Valores dos campos de função dinâmica

A tabela a seguir descreve os valores de SQL_DIAG_DYNAMIC_FUNCTION e SQL_DIAG_DYNAMIC_FUNCTION_CODE que se aplicam a cada tipo de instrução SQL executada por uma chamada para SQLExecute ou SQLExecDirect. O driver pode adicionar valores definidos pelo driver aos listados.

Sequência de registros de status

Os registros de status são posicionados em uma sequência com base no número da linha e no tipo do diagnóstico. O Gerenciador de Driver determina a ordem final na qual retornar registros de status que ele gera. O driver determina a ordem final na qual retornar registros de status que ele gera.

Se os registros de diagnóstico forem postados pelo Gerenciador de Driver e pelo driver, o Gerenciador de Driver será responsável por ordená-los.

Se houver dois ou mais registros de status, a sequência dos registros será determinada primeiro pelo número da linha. As seguintes regras se aplicam à determinação da sequência de registros de diagnóstico por linha:

• Os registros que não correspondem a nenhuma linha aparecem na frente dos registros que correspondem a uma linha específica, pois SQL_NO_ROW_NUMBER é definido como -1.

• Os registros para os quais o número de linha é desconhecido aparecem na frente de todos os outros registros, pois SQL_ROW_NUMBER_UNKNOWN é definido como -2.

• Para todos os registros que pertencem a linhas específicas, os registros são classificados pelo valor no campo SQL_DIAG_ROW_NUMBER. Todos os erros e avisos da primeira linha afetada são listados e, em seguida, todos os erros e avisos da próxima linha afetada e assim por diante.

Dentro de cada linha ou para todos os registros que não correspondem a uma linha ou para a qual o número de linha é desconhecido ou para todos esses registros com um número de linha igual a SQL_NO_ROW_NUMBER, o primeiro registro listado é determinado usando um conjunto de regras de classificação. Após o primeiro registro, a ordem dos outros registros que afetam uma linha é indefinida. Um aplicativo não pode assumir que os erros precedem avisos após o primeiro registro. Os aplicativos devem examinar a estrutura de dados de diagnóstico completa para obter informações completas sobre uma chamada malsucedida para uma função.

As regras a seguir são usadas para determinar o primeiro registro dentro de uma linha. O registro com a classificação mais alta é o primeiro registro. A origem de um registro (Driver Manager, driver, gateway e assim por diante) não é considerada ao classificar registros.

• Erros Os registros de status que descrevem erros têm a classificação mais alta. As seguintes regras são aplicadas a erros de classificação:

  • Registros que indicam uma falha de transação ou uma possível falha de transação superam todos os outros registros.

  • Se dois ou mais registros descreverem a mesma condição de erro, os SQLSTATEs definidos pela especificação da CLI do Grupo Aberto (classes 03 a HZ) superarão o ODBC e os SQLSTATEs definidos pelo driver.

• Sem valores de dados definidos pela implementação Os registros de status que descrevem valores Sem Dados definidos pelo driver (classe 02) têm a segunda classificação mais alta.

• Avisos Os registros de status que descrevem avisos (classe 01) têm a classificação mais baixa. Se dois ou mais registros descreverem a mesma condição de aviso, avisando SQLSTATEs definidos pela especificação da CLI do Grupo Aberto para além dos SQLSTATEs definidos pelo ODBC e definidos pelo driver.

Funções relacionadas

Consulte Também

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