Partilhar via


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 .

DiagIdentifier Tipo de retorno Retornos
SQL_DIAG_CURSOR_ROW_COUNT SQLLEN Esse campo contém a contagem de linhas no cursor. Sua semântica depende dos tipos de informações SQLGetInfo SQL_DYNAMIC_CURSOR_ATTRIBUTES2, SQL_FORWARD_ONLY_CURSOR_ATTRIBUTES2, SQL_KEYSET_CURSOR_ATTRIBUTES2 e SQL_STATIC_CURSOR_ATTRIBUTES2, que indicam quais contagens de linhas estão disponíveis para cada tipo de cursor (nos bits SQL_CA2_CRC_EXACT e SQL_CA2_CRC_APPROXIMATE).

O conteúdo desse campo é definido apenas para identificadores de instrução e somente após SQLExecute, SQLExecDirect ou SQLMoreResults ter sido chamado. Chamar SQLGetDiagField com um DiagIdentifier de SQL_DIAG_CURSOR_ROW_COUNT em outro identificador de instrução retornará SQL_ERROR.
SQL_DIAG_DYNAMIC_FUNCTION SQLCHAR* Essa é uma cadeia de caracteres que descreve a instrução SQL que a função subjacente executou. (Confira "Valores dos campos de Função Dinâmica", mais adiante nesta seção, para obter valores específicos.) O conteúdo desse campo é definido apenas para identificadores de instrução e somente após uma chamada para SQLExecute, SQLExecDirect ou SQLMoreResults. Chamar SQLGetDiagField com um DiagIdentifier de SQL_DIAG_DYNAMIC_FUNCTION em outro identificador de instrução retornará SQL_ERROR. O valor desse campo é indefinido antes de uma chamada para SQLExecute ou SQLExecDirect.
SQL_DIAG_DYNAMIC_FUNCTION_CODE SQLINTEGER Esse é um código numérico que descreve a instrução SQL que foi executada pela função subjacente. (Confira "Valores dos Campos de Função Dinâmica", mais adiante nesta seção, para obter um valor específico.) O conteúdo desse campo é definido apenas para identificadores de instrução e somente após uma chamada para SQLExecute, SQLExecDirect ou SQLMoreResults. Chamar SQLGetDiagField com um DiagIdentifier de SQL_DIAG_DYNAMIC_FUNCTION_CODE em outro identificador de instrução retornará SQL_ERROR. O valor desse campo é indefinido antes de uma chamada para SQLExecute ou SQLExecDirect.
SQL_DIAG_NUMBER SQLINTEGER O número de registros de status disponíveis para o identificador especificado.
SQL_DIAG_RETURNCODE SQLRETURN Código de retorno retornado pela função . Para obter uma lista de códigos de retorno, consulte Códigos de retorno. O driver não precisa implementar SQL_DIAG_RETURNCODE; ele é sempre implementado pelo Gerenciador de Driver. Se nenhuma função ainda tiver sido chamada no Identificador, SQL_SUCCESS será retornado para SQL_DIAG_RETURNCODE.
SQL_DIAG_ROW_COUNT SQLLEN O número de linhas afetadas por uma inserção, exclusão ou atualização executada por SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos. Ele é definido pelo driver depois que uma especificação de cursor é executada. O conteúdo desse campo é definido apenas para identificadores de instrução. Chamar SQLGetDiagField com um DiagIdentifier de SQL_DIAG_ROW_COUNT em outro identificador de instrução retornará SQL_ERROR. Os dados nesse campo também são retornados no argumento RowCountPtr de SQLRowCount. Os dados nesse campo são redefinidos após cada chamada de função não independente, enquanto a contagem de linhas retornada por SQLRowCount permanece a mesma até que a instrução seja definida de volta para o estado preparado ou alocado.

Campos de registro

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

DiagIdentifier Tipo de retorno Retornos
SQL_DIAG_CLASS_ORIGIN SQLCHAR* Uma cadeia de caracteres que indica o documento que define a parte da classe do valor SQLSTATE nesse registro. Seu valor é "ISO 9075" para todos os SQLSTATEs definidos pelo Open Group e pela interface de nível de chamada ISO. Para SQLSTATEs específicos do ODBC (todos aqueles cuja classe SQLSTATE é "IM"), seu valor é "ODBC 3.0".
SQL_DIAG_COLUMN_NUMBER SQLINTEGER Se o campo SQL_DIAG_ROW_NUMBER for um número de linha válido em um conjunto de linhas ou um conjunto de parâmetros, esse campo conterá o valor que representa o número da coluna no conjunto de resultados ou o número do parâmetro no conjunto de parâmetros. Os números de coluna do conjunto de resultados sempre começam em 1; se esse registro de status pertencer a uma coluna de indicador, o campo poderá ser zero. Os números de parâmetro começam em 1. Ele terá o valor SQL_NO_COLUMN_NUMBER se o registro de status não estiver associado a um número de coluna ou número de parâmetro. Se o driver não puder determinar o número da coluna ou o número do parâmetro ao qual esse registro está associado, esse campo terá o valor SQL_COLUMN_NUMBER_UNKNOWN.

O conteúdo desse campo é definido apenas para identificadores de instrução.
SQL_DIAG_CONNECTION_NAME SQLCHAR* Uma cadeia de caracteres que indica o nome da conexão à qual o registro de diagnóstico está relacionado. Esse campo é definido pelo driver. Para estruturas de dados de diagnóstico associadas ao identificador de ambiente e para diagnósticos que não estão relacionados a nenhuma conexão, esse campo é uma cadeia de caracteres de comprimento zero.
SQL_DIAG_MESSAGE_TEXT SQLCHAR* Uma mensagem informativa sobre o erro ou aviso. Esse campo é formatado conforme descrito em Mensagens de Diagnóstico. Não há comprimento máximo para o texto da mensagem de diagnóstico.
SQL_DIAG_NATIVE SQLINTEGER Um código de erro nativo específico da fonte de dados/driver. Se não houver nenhum código de erro nativo, o driver retornará 0.
SQL_DIAG_ROW_NUMBER SQLLEN Esse campo contém o número da linha no conjunto de linhas ou o número do parâmetro no conjunto de parâmetros, com o qual o registro de status está associado. Números de linha e números de parâmetro começam com 1. Esse campo terá o valor SQL_NO_ROW_NUMBER se esse registro de status não estiver associado a um número de linha ou número de parâmetro. Se o driver não puder determinar o número da linha ou o número do parâmetro ao qual esse registro está associado, esse campo terá o valor SQL_ROW_NUMBER_UNKNOWN.

O conteúdo desse campo é definido apenas para identificadores de instrução.
SQL_DIAG_SERVER_NAME SQLCHAR* Uma cadeia de caracteres que indica o nome do servidor ao qual o registro de diagnóstico está relacionado. É o mesmo que o valor retornado para uma chamada para SQLGetInfo com a opção SQL_DATA_SOURCE_NAME. Para estruturas de dados de diagnóstico associadas ao identificador de ambiente e para diagnósticos que não estão relacionados a nenhum servidor, esse campo é uma cadeia de caracteres de comprimento zero.
SQL_DIAG_SQLSTATE SQLCHAR* Um código de diagnóstico SQLSTATE de cinco caracteres. Para obter mais informações, consulte SQLSTATEs.
SQL_DIAG_SUBCLASS_ORIGIN SQLCHAR* Uma cadeia de caracteres com o mesmo formato e valores válidos que SQL_DIAG_CLASS_ORIGIN, que identifica a parte definidora da parte de subclasse do código SQLSTATE. O SQLSTATES específico do ODBC para o qual "ODBC 3.0" é retornado inclui o seguinte:

01S00, 01S01, 01S02, 01S06, 01S07, 07S01, 08S01, 21S01, 21S02, 25S01, 25S02, 25S03, 42S01, 42S02, 42S11, 42S12, 42S21, 42S22, HY095, HY097, HY098, HY099, HY100, HY101, HY105, HY107, HY109, HY110, HY111, HYT00, HYT01, IM001, IM002, IM003, IM004, IM005, IM006, IM007, IM008, IM010, IM011, IM012.

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.

Instrução SQL

Executado
Valor de

SQL_DIAG_DYNAMIC_FUNCTION
Valor de

SQL_DIAG_DYNAMIC_FUNCTION_CODE
instrução alter-domain "ALTER DOMAIN" SQL_DIAG_ALTER_DOMAIN
instrução alter-table "ALTER TABLE" SQL_DIAG_ALTER_TABLE
assertion-definition "CREATE ASSERTION" SQL_DIAG_CREATE_ASSERTION
character-set-definition "CREATE CHARACTER SET" SQL_DIAG_CREATE_CHARACTER_SET
definição de ordenação "CRIAR ORDENAÇÃO" SQL_DIAG_CREATE_COLLATION
domainn-definition "CREATE DOMAIN" SQL_DIAG_CREATE_DOMAIN
create-index-statement "CREATE INDEX" SQL_DIAG_CREATE_INDEX
create-table-statement "CREATE TABLE" SQL_DIAG_CREATE_TABLE
create-view-statement "CREATE VIEW" SQL_DIAG_CREATE_VIEW
especificação de cursor "SELECIONAR CURSOR" SQL_DIAG_SELECT_CURSOR
delete-statement-positioned "CURSOR DE EXCLUSÃO DINÂMICA" SQL_DIAG_DYNAMIC_DELETE_CURSOR
delete-statement-searched "DELETE WHERE" SQL_DIAG_DELETE_WHERE
drop-assertion-statement "DROP ASSERTION" SQL_DIAG_DROP_ASSERTION
drop-character-set-stmt "DROP CHARACTER SET" SQL_DIAG_DROP_CHARACTER_SET
drop-collation-statement "DROP COLLATION" SQL_DIAG_DROP_COLLATION
drop-domain-statement "DROP DOMAIN" SQL_DIAG_DROP_DOMAIN
instrução drop-index "DROP INDEX" SQL_DIAG_DROP_INDEX
instrução drop-schema "DROP SCHEMA" SQL_DIAG_DROP_SCHEMA
drop-table-statement "DROP TABLE" SQL_DIAG_DROP_TABLE
drop-translation-statement "DROP TRANSLATION" SQL_DIAG_DROP_TRANSLATION
drop-view-statement "DROP VIEW" SQL_DIAG_DROP_VIEW
Grantstatement "GRANT" SQL_DIAG_GRANT
instrução insert "INSERT" SQL_DIAG_INSERT
ODBC-procedure-extension "CALL" SQL_DIAG_ CALL
revoke-statement "REVOKE" SQL_DIAG_REVOKE
definição de esquema "CREATE SCHEMA" SQL_DIAG_CREATE_SCHEMA
translation-definition "CREATE TRANSLATION" SQL_DIAG_CREATE_TRANSLATION
update-statement-positioned "CURSOR DE ATUALIZAÇÃO DINÂMICA" SQL_DIAG_DYNAMIC_UPDATE_CURSOR
update-statement-searched "ATUALIZAR ONDE" SQL_DIAG_UPDATE_WHERE
Unknown cadeia de caracteres vazia SQL_DIAG_UNKNOWN_STATEMENT

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.

Observação

O Gerenciador de Driver ODBC 3*.x* não ordenará registros de status na fila de diagnóstico se SQLSTATE 01S01 (erro em linha) for retornado por um driver ODBC 2*.x* ou se SQLSTATE 01 OS01 (erro em linha) é retornado por um driver ODBC 3*.x* quando SQLExtendedFetch é chamado ou SQLSetPos é chamado em um cursor que foi posicionado com SQLExtendedFetch.

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.

Para obter informações sobre Consulte
Obtendo vários campos de uma estrutura de dados de diagnóstico Função SQLGetDiagRec

Consulte Também

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