Função SQLGetDescField

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

Summary
O SQLGetDescField devolve a definição ou valor atual de um único campo de um registo descritor.

Syntax

  
SQLRETURN SQLGetDescField(  
     SQLHDESC        DescriptorHandle,  
     SQLSMALLINT     RecNumber,  
     SQLSMALLINT     FieldIdentifier,  
     SQLPOINTER      ValuePtr,  
     SQLINTEGER      BufferLength,  
     SQLINTEGER *    StringLengthPtr);

Arguments

DescriptorHandle
[Entrada] Identificador de descriptor.

RecNumber
[Entrada] Indica o registo descritor do qual a candidatura solicita informação. Os registos descritor são numerados a partir de 0, sendo o registo número 0 o registo de favoritos. Se o argumento FieldIdentifier indicar um campo de cabeçalho, RecNumber é ignorado. Se o RecNumber for menor ou igual a SQL_DESC_COUNT mas a linha não contiver dados para uma coluna ou parâmetro, uma chamada ao SQLGetDescField devolverá os valores padrão dos campos. (Para mais informações, veja "Inicialização de Campos Descritores" em SQLSetDescField.)

FieldIdentifier
[Entrada] Indica o campo do descritor cujo valor deve ser devolvido. Para mais informações, consulte a secção "FieldIdentifier Argument" em SQLSetDescField.

ValuePtr
[Saída] Apontador para um buffer onde deveria a informação do descritor. O tipo de dado depende do valor do FieldIdentifier.

Se o ValuePtr for do tipo inteiro, as aplicações devem usar um buffer de SQLULEN e inicializar o valor para 0 antes de chamar esta função, pois alguns drivers podem escrever apenas o buffer inferior de 32 ou 16 bits e deixar o bit de ordem superior inalterado.

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

BufferLength
[Entrada] Se o FieldIdentifier for um campo definido por ODBC e o ValuePtr apontar para uma cadeia de caracteres ou um buffer binário, este argumento deve corresponder ao comprimento de *ValuePtr. Se FieldIdentifier for um campo definido por ODBC e *ValuePtr for um inteiro, BufferLength é ignorado. Se o valor em *ValuePtr for de um tipo de dado Unicode (ao chamar SQLGetDescFieldW), o argumento BufferLength deve ser um número par.

Se o FieldIdentifier for um campo definido pelo driver, a aplicação indica a natureza do campo ao Driver Manager definindo o argumento BufferLength . BufferLength pode ter os seguintes valores:

  • Se *ValuePtr for um ponteiro para uma cadeia de caracteres, então BufferLength é o comprimento da cadeia ou SQL_NTS.

  • Se *ValuePtr for um ponteiro para um buffer binário, então a aplicação coloca o resultado da macro SQL_LEN_BINARY_ATTR(comprimento) em BufferLength. Isto coloca um valor negativo no BufferLength.

  • Se *ValuePtr for um ponteiro para um valor diferente de uma cadeia de caracteres ou binária, então BufferLength deve ter o valor SQL_IS_POINTER.

  • Se *ValuePtr contiver um tipo de dado de comprimento fixo, então BufferLength é SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT ou SQL_IS_USMALLINT, conforme apropriado.

StringLengthPtr
[Saída] Apontador para o buffer onde se deve devolver o número total de bytes (excluindo o número de bytes necessários para o carácter de terminação nula) disponíveis para devolver em *ValuePtr.

Devoluções

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA ou SQL_INVALID_HANDLE.

SQL_NO_DATA é devolvido se o RecNumber for superior ao número atual de registos de descritores.

SQL_NO_DATA é devolvido se o DescriptorHandle for um handle IRD e a instrução estiver no estado preparado ou executado, mas não houver cursor aberto associado a ele.

Diagnósticos

Quando o SQLGetDescField retorna SQL_ERROR ou SQL_SUCCESS_WITH_INFO, pode ser obtido um valor SQLSTATE associado chamando SQLGetDiagRec com um HandleType de SQL_HANDLE_STMT e um Handle de StatementHandle. A tabela seguinte lista os valores SQLSTATE normalmente devolvidos pelo SQLGetDescField e explica cada um no contexto desta função; a notação "(DM)" precede as descrições dos SQLSTATEs devolvidas pelo Gestor de Drivers. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, salvo indicação em contrário.

SQLSTATE Erro Descrição
01000 Aviso geral Mensagem informativa específica para o condutor. (Função devolve SQL_SUCCESS_WITH_INFO.)
01004 Dados de cadeia, truncados à direita O buffer *ValuePtr não era suficientemente grande para devolver todo o campo do descritor, pelo que o campo foi truncado. O comprimento do campo descritor não runcado é devolvido em *StringLengthPtr. (Função devolve SQL_SUCCESS_WITH_INFO.)
07009 Índice de descritores inválido (DM) O argumento RecNumber era igual a 0, o atributo da instrução SQL_ATTR_USE_BOOKMARK era SQL_UB_OFF, e o argumento DescriptorHandle era um handle IRD. (Este erro só pode ser devolvido para um descritor explicitamente alocado se o descritor estiver associado a um handle de instrução.)

O argumento FieldIdentifier era um campo de registo, o argumento RecNumber era 0, e o argumento DescriptorHandle era um handle IPD.

O argumento do RecNumber era inferior a 0.
08S01 Falha da ligação de comunicação A ligação de comunicação entre o driver e a fonte de dados à qual o driver estava ligado falhou antes de a função concluir o processamento.
HY000 Erro geral Ocorreu um erro para o qual não existia um SQLSTATE específico e para o qual não estava definido nenhum SQLSTATE específico da implementação. A mensagem de erro devolvida pelo SQLGetDiagRec no buffer *MessageText descreve o erro e a sua causa.
HY001 Erro de alocação de memória O driver não conseguia alocar a memória necessária para suportar a execução ou conclusão da função.
HY007 A declaração associada não está preparada DescriptorHandle estava associado a um StatementHandle como IRD, e o handle associado não tinha sido preparado nem executado.
HY010 Erro de sequência de funções (DM) DescriptorHandle estava associado a um StatementHandle para o qual uma função em execução assíncrona (não esta) era chamada e continuava a ser executada quando esta função era chamada.

(DM) DescriptorHandle estava associado a um StatementHandle para o qual o SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos era chamado e devolvido SQL_NEED_DATA. Esta função era chamada antes de os dados serem enviados para todos os parâmetros ou colunas de dados na execução.

(DM) Foi chamada uma função de execução assíncrona para o handle de ligação associado ao DescriptorHandle. Esta função assíncrona ainda estava a ser executada quando a função SQLGetDescField foi chamada.
HY013 Erro de gestão de memória A chamada de função não podia ser processada porque os objetos de memória subjacentes não podiam ser acedidos, possivelmente devido a condições de baixa memória.
HY021 Informação inconsistente do descritor Os campos SQL_DESC_TYPE e SQL_DESC_DATETIME_INTERVAL_CODE não formam um tipo válido de SQL ODBC, um tipo SQL específico do driver válido (para IPDs) ou um tipo válido ODBC C (para APDs ou ARDs).
HY090 Comprimento inválido da corda ou do buffer (DM) *ValuePtr era uma cadeia de caracteres, e BufferLength era inferior a zero.
HY091 Identificador de campo descritor inválido FieldIdentifier não era um campo definido por ODBC nem era um valor definido pela implementação.

O FieldIdentifier não estava definido para o DescriptorHandle.
HY117 A ligação é suspensa devido ao estado desconhecido da transação. Apenas funções de desconexão e de leitura são permitidas. (DM) Para mais informações sobre o estado suspenso, veja Função SQLEndTran.
HYT01 Expirou o tempo limite de ligação O período de timeout da ligação expirou antes de a fonte de dados responder ao pedido. O período de tempo de expiração da ligação é definido através do SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 O driver não suporta esta função (DM) O driver associado ao DescriptorHandle não suporta a função.

Comments

Uma aplicação pode chamar SQLGetDescField para devolver o valor de um único campo de um registo descritor. Uma chamada ao SQLGetDescField pode devolver a definição de qualquer campo em qualquer tipo de descritor, incluindo campos de cabeçalho, campos de registo e campos de favoritos. Uma aplicação pode obter as definições de múltiplos campos no mesmo ou em descritores diferentes, por ordem arbitrária, ao fazer chamadas repetidas ao SQLGetDescField. O SQLGetDescField também pode ser chamado para devolver campos de descritores definidos pelo driver.

Por razões de desempenho, uma aplicação não deve chamar SQLGetDescField para um IRD antes de executar uma instrução.

As definições de múltiplos campos que descrevem o nome, tipo de dado e armazenamento de dados de colunas ou parâmetros também podem ser recuperadas numa única chamada ao SQLGetDescRec. O SQLGetStmtAttr pode ser chamado para devolver a definição de um único campo no cabeçalho do descritor que também é um atributo de instrução. SQLColAttribute, SQLDescribeCol e SQLDescribeParam retornam campos de registo ou favoritos.

Quando uma aplicação chama SQLGetDescField para recuperar o valor de um campo indefinido para um determinado tipo de descritor, a função devolve SQL_SUCCESS mas o valor devolvido para o campo permanece indefinido. Por exemplo, chamar SQLGetDescField para o campo SQL_DESC_NAME ou SQL_DESC_NULLABLE de um APD ou ARD devolverá SQL_SUCCESS mas um valor indefinido para o campo.

Quando uma aplicação chama SQLGetDescField para recuperar o valor de um campo definido para um determinado tipo de descritor mas que não tem valor padrão e ainda não foi definido, a função devolve SQL_SUCCESS mas o valor devolvido para o campo não está definido. Para mais informações sobre a inicialização de campos de descrição e descrições dos campos, veja "Inicialização de Campos de Descritores" em SQLSetDescField. Para mais informações sobre descritores, veja Descritores.

Para obter informações sobre Veja
Obtenção de múltiplos campos de descrição Função SQLGetDescRec
Definir um único campo descritor Função SQLSetDescField
Definição de múltiplos campos de descrição Função SQLSetDescRec

Conteúdo relacionado

  • Last updated on