Função SQLGetDescRec

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

Summary
SQLGetDescRec devolve as definições ou valores atuais de múltiplos campos de um registo descritor. Os campos devolvidos descrevem o nome, o tipo de dados e o armazenamento dos dados das colunas ou parâmetros.

Syntax

  
SQLRETURN SQLGetDescRec(  
      SQLHDESC        DescriptorHandle,  
      SQLSMALLINT     RecNumber,  
      SQLCHAR *       Name,  
      SQLSMALLINT     BufferLength,  
      SQLSMALLINT *   StringLengthPtr,  
      SQLSMALLINT *   TypePtr,  
      SQLSMALLINT *   SubTypePtr,  
      SQLLEN *        LengthPtr,  
      SQLSMALLINT *   PrecisionPtr,  
      SQLSMALLINT *   ScalePtr,  
      SQLSMALLINT *   NullablePtr);

Arguments

DescriptorHandle
[Entrada] Identificador de descriptor.

RecNumber
[Entrada] Indica o registo descritor do qual a candidatura solicita informação. Os registos de descriptor são numerados a partir de 1, sendo o registo número 0 o registo de favoritos. O argumento RecNumber deve ser menor ou igual ao valor de SQL_DESC_COUNT. 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 SQLGetDescRec devolverá os valores padrão dos campos. (Para mais informações, veja "Inicialização de Campos Descritores" em SQLSetDescField.)

Nome
[Saída] Um apontador para um buffer onde se deve devolver o campo SQL_DESC_NAME para o registo descritor.

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

BufferLength
[Entrada] Comprimento do *Name buffer, em caracteres.

StringLengthPtr
[Saída] Um apontador para um buffer onde se deve devolver o número de caracteres de dados disponíveis para devolver no buffer *Name , excluindo o carácter de terminação nula. Se o número de caracteres for maior ou igual a BufferLength, os dados em *Name são truncados para BufferLength menos o comprimento de um carácter de terminação nula, e são null-terminados pelo driver.

TypePtr
[Saída] Um apontador para um buffer onde se deve devolver o valor do campo SQL_DESC_TYPE para o registo descritor.

SubTypePtr
[Saída] Para registos cujo tipo é SQL_DATETIME ou SQL_INTERVAL, isto é um apontador para um buffer onde se deve devolver o valor do campo SQL_DESC_DATETIME_INTERVAL_CODE.

LengthPtr
[Saída] Um apontador para um buffer onde deveria devolver o valor do campo SQL_DESC_OCTET_LENGTH para o registo descritor.

PrecisionPtr
[Saída] Um apontador para um buffer onde se deve devolver o valor do campo SQL_DESC_PRECISION para o registo do descritor.

ScalePtr
[Saída] Um apontador para um buffer onde deveria o valor do campo SQL_DESC_SCALE para o registo descritor.

NullablePtr
[Saída] Um apontador para um buffer onde se deve devolver o valor do campo SQL_DESC_NULLABLE para o registo descritor.

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 SQLGetDescRec devolve SQL_ERROR ou SQL_SUCCESS_WITH_INFO, um valor SQLSTATE associado pode ser obtido chamando SQLGetDiagRec com um HandleType de SQL_HANDLE_DESC e um Handle de DescriptorHandle. A tabela seguinte lista os valores SQLSTATE normalmente devolvidos pelo SQLGetDescRec 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 *Name não era suficientemente grande para devolver todo o campo do descritor. Por isso, 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 O argumento FieldIdentifier era um campo de registo, o argumento RecNumber era definido para 0, e o argumento DescriptorHandle era um handle IPD.

(DM) O argumento RecNumber foi definido para 0, e o atributo da instrução SQL_ATTR_USE_BOOKMARKS foi definido para SQL_UB_OFF, e o argumento DescriptorHandle foi um handle IRD.

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 conseguiu 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 IRD, e o handle da instrução associado não estava no estado preparado ou 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 o SQLGetDescRec foi chamado.
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.
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 SQLGetDescRec para recuperar os valores dos seguintes campos descritores para uma única coluna ou parâmetro:

  • SQL_DESC_NAME

  • SQL_DESC_TYPE

  • SQL_DESC_DATETIME_INTERVAL_CODE (para registos cujo tipo é SQL_DATETIME ou SQL_INTERVAL)

  • SQL_DESC_OCTET_LENGTH

  • SQL_DESC_PRECISION

  • SQL_DESC_SCALE

  • SQL_DESC_NULLABLE

O SQLGetDescRec não recupera os valores dos campos de cabeçalho.

Uma aplicação pode impedir o retorno da definição de um campo ao definir o argumento que corresponde ao campo para um ponteiro nulo.

Quando uma aplicação chama SQLGetDescRec 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 é indefinido. Por exemplo, chamar SQLGetDescRec 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 SQLGetDescRec 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, consulte "Inicialização de Campos de Descritores" em SQLSetDescField.

Os valores dos campos também podem ser recuperados individualmente através de uma chamada ao SQLGetDescField. Para uma descrição dos campos num cabeçalho ou registo descritor, veja SQLSetDescField. Para mais informações sobre descritores, veja Descritores.

Para obter informações sobre Veja
Encadernação de uma coluna Função SQLBindCol
Ligar um parâmetro Função SQLBindParameter
Obtenção de um campo descritor Função SQLGetDescField
Definição de múltiplos campos de descrição Função SQLSetDescRec

Conteúdo relacionado

  • Last updated on