Função SQLGetDescField

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

Summary
SQLGetDescField retorna a configuração ou valor atual de um único campo de um registro descritor.

Sintaxe

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

Argumentos

DescriptorHandle
[Entrada] Descritor de nome.

RecNumber
[Entrada] Indica o registro descritor do qual a solicitação busca informações. Os registros de descriptor são numerados a partir de 0, sendo o registro número 0 o registro de favoritos. Se o argumento FieldIdentifier indicar um campo de cabeçalho, RecNumber é ignorado. Se RecNumber for menor ou igual a SQL_DESC_COUNT mas a linha não contiver dados para uma coluna ou parâmetro, uma chamada para SQLGetDescField retornará 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 retornado. Para mais informações, veja a seção "FieldIdentifier Argument" no SQLSetDescField.

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

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

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

BufferLength
[Entrada] Se o FieldIdentifier for um campo definido por ODBC e o ValuePtr apontar para uma string de caracteres ou um buffer binário, esse argumento deve ser o 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 para o Driver Manager definindo o argumento BufferLength . BufferLength pode ter os seguintes valores:

  • Se *ValuePtr é um ponteiro para uma cadeia de caracteres, então BufferLength é o comprimento da string 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. Isso coloca um valor negativo no BufferLength.

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

  • Se *ValuePtr contém 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 no qual devolver o número total de bytes (excluindo o número de bytes necessários para o caractere de terminação nula) disponíveis para retornar em *ValuePtr.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA ou SQL_INVALID_HANDLE.

SQL_NO_DATA é retornado se RecNumber for maior que o número atual de registros de descritor.

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

Diagnostics

Quando SQLGetDescField retorna SQL_ERROR ou SQL_SUCCESS_WITH_INFO, um valor SQLSTATE associado pode ser obtido chamando SQLGetDiagRec com um HandleType de SQL_HANDLE_STMT e um Handle de StatementHandle. A tabela a seguir lista os valores de SQLSTATE comumente retornados pelo SQLGetDescField e explica cada um no contexto dessa função; a notação "(DM)" precede as descrições dos SQLSTATEs retornadas pelo Gerenciador de Drivers. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, a menos que indicado de outra forma.

SQLSTATE Erro DESCRIÇÃO
01000 Aviso geral Mensagem informativa específica do driver. (A função retorna SQL_SUCCESS_WITH_INFO.)
01004 Dados de cadeia de caracteres, truncados à direita O buffer *ValuePtr não era grande o suficiente para retornar todo o campo do descritor, então o campo foi truncado. O comprimento do campo descritor não arruncado é retornado em *StringLongPtr. (A função retorna 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. (Esse erro pode ser retornado para um descritor explicitamente alocado somente se o descritor estiver associado a um handle de instrução.)

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

O argumento do RecNumber era menor que 0.
08S01 Falha no link de comunicação O link de comunicação entre o driver e a fonte de dados à qual o driver estava conectado falhou antes que a função concluísse o processamento.
HY000 Erro geral Ocorreu um erro para o qual não havia SQLSTATE específico e para o qual nenhum SQLSTATE específico da implementação foi definido. A mensagem de erro retornada por SQLGetDiagRec no buffer *MessageText descreve o erro e sua causa.
HY001 Erro de alocação de memória O driver não pôde alocar a memória necessária para dar suporte à 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 de instrução associado não havia sido preparado ou executado.
HY010 Erro de sequência de função (DM) DescriptorHandle estava associado a um StatementHandle para o qual uma função que executava assíncronamente (não esta) era chamada e ainda estava executando quando essa função era chamada.

(DM) DescriptorHandle estava associado a um StatementHandle para o qual SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos eram chamados e retornados SQL_NEED_DATA. Essa função foi chamada antes que os dados fossem enviados para todos os parâmetros ou colunas de dados em execução.

(DM) Uma função de execução assíncrona era chamada para o handle de conexão associado ao DescriptorHandle. Essa função assíncrona ainda estava em execução quando a função SQLGetDescField foi chamada.
HY013 Erro de gerenciamento de memória A chamada de função não pôde ser processada porque os objetos de memória subjacentes não puderam ser acessados, possivelmente devido a condições de memória baixa.
HY021 Informações de descritores inconsistentes 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 de driver válido (para IPDs) ou um tipo válido ODBC C (para APDs ou ARDs).
HY090 Cadeia de caracteres ou comprimento de buffer inválido (DM) *ValuePtr era uma cadeia de caracteres, e BufferLength era menor que zero.
HY091 Identificador de campo descritor inválido FieldIdentifier não era um campo definido pelo ODBC nem era um valor definido pela implementação.

FieldIdentifier não estava definido para o DescriptorHandle.
HY117 A conexão está suspensa devido ao estado desconhecido da transação. Somente funções de desconexão e somente leitura são permitidas. (DM) Para mais informações sobre o estado suspenso, veja Função SQLEndTran.
HYT01 O tempo limite da conexão expirou O período de tempo limite da conexão expirou antes que a fonte de dados respondesse à solicitação. O período de tempo limite da conexão é definido por meio de SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 O driver não suporta esta função (DM) O driver associado ao DescriptorHandle não suporta essa função.

Comments

Uma aplicação pode chamar SQLGetDescField para retornar o valor de um único campo de um registro de descritor. Uma chamada para SQLGetDescField pode retornar a configuração de qualquer campo em qualquer tipo de descritor, incluindo campos de cabeçalho, campos de registro e campos de favoritos. Uma aplicação pode obter as configurações de múltiplos campos no mesmo ou em descritores diferentes, em ordem arbitrária, fazendo chamadas repetidas para SQLGetDescField. O SQLGetDescField também pode ser chamado para retornar campos de descrição 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 configuraçõ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 em uma única chamada para SQLGetDescRec. SQLGetStmtAttr pode ser chamado para retornar a configuraçã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 registro ou favorito.

Quando uma aplicação chama SQLGetDescField para recuperar o valor de um campo indefinido para um tipo específico de descritor, a função retorna SQL_SUCCESS mas o valor retornado para o campo é indefinido. Por exemplo, chamar SQLGetDescField para o campo SQL_DESC_NAME ou SQL_DESC_NULLABLE de um APD ou ARD retornará 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 tipo de descritor específico, mas que não tem valor padrão e ainda não foi definido, a função retorna SQL_SUCCESS mas o valor retornado 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 obter mais informações sobre descritores, consulte Descritores.

Para obter informações sobre Veja
Obtendo múltiplos campos de descritores Função SQLGetDescRec
Definindo um único campo de descritor Função SQLSetDescField
Definindo múltiplos campos de descritores Função SQLSetDescRec

Conteúdo relacionado

  • Last updated on