Função SQLGetDescRec

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

Summary
SQLGetDescRec retorna as configurações ou valores atuais de múltiplos campos de um registro descritor. Os campos retornados descrevem o nome, tipo de dado e armazenamento dos dados das colunas ou parâmetros.

Sintaxe

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

Argumentos

DescriptorHandle
[Entrada] Descritor de nome.

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

Nome
[Saída] Um ponteiro para um buffer no qual deveria retornar o campo SQL_DESC_NAME para o registro de descritor.

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

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

StringLengthPtr
[Saída] Um ponteiro para um buffer no qual deveria retornar o número de caracteres de dados disponíveis para retorno no buffer *Name , excluindo o caractere de terminação nula. Se o número de caracteres fosse maior ou igual ao BufferLength, os dados em *Name são truncados para BufferLength menos o comprimento de um caractere de terminação nula, e são null-terminados pelo driver.

TypePtr
[Saída] Um ponteiro para um buffer no qual deveria retornar o valor do campo SQL_DESC_TYPE para o registro do descritor.

SubTypePtr
[Saída] Para registros cujo tipo é SQL_DATETIME ou SQL_INTERVAL, isso é um apontador para um buffer no qual é retornado o valor do campo SQL_DESC_DATETIME_INTERVAL_CODE.

LengthPtr
[Saída] Um ponteiro para um buffer no qual deveria retornar o valor do campo SQL_DESC_OCTET_LENGTH para o registro descritor.

PrecisionPtr
[Saída] Um ponteiro para um buffer no qual deveria retornar o valor do campo SQL_DESC_PRECISION para o registro do detrator.

ScalePtr
[Saída] Um ponteiro para um buffer no qual deveria retornar o valor do campo SQL_DESC_SCALE para o registro do descritor.

NullablePtr
[Saída] Um ponteiro para um buffer no qual deveria retornar o valor do campo SQL_DESC_NULLABLE para o registro do descritor.

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 SQLGetDescRec retorna 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 a seguir lista os valores SQLSTATE normalmente retornados pelo SQLGetDescRec 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 *Name não era grande o suficiente para retornar todo o campo do descritor. Portanto, 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 O argumento FieldIdentifier era um campo de registro, o argumento RecNumber era definido como 0, e o argumento DescriptorHandle era um handle IPD.

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

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 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 de instrução associado não estava no estado 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 o SQLGetDescRec foi chamado.
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.
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 obter mais informações sobre o estado suspenso, consulte 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 a função.

Comments

Uma aplicação pode chamar SQLGetDescRec para recuperar os valores dos seguintes campos de descritores para uma única coluna ou parâmetro:

  • SQL_DESC_NAME

  • SQL_DESC_TYPE

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

  • SQL_DESC_OCTET_LENGTH

  • SQL_DESC_PRECISION

  • SQL_DESC_SCALE

  • SQL_DESC_NULLABLE

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

Uma aplicação pode impedir o retorno da configuração de um campo ao definir o argumento correspondente ao campo para um ponteiro nulo.

Quando uma aplicação chama SQLGetDescRec 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 SQLGetDescRec para o campo SQL_DESC_NAME ou SQL_DESC_NULLABLE de um APD ou ARD retornará SQL_SUCCESS valor indefinido para o campo.

Quando uma aplicação chama SQLGetDescRec para recuperar o valor de um campo definido para um tipo específico de descritor, 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 é indefinido. Para mais informações, veja "Inicialização de Campos Descritores" em SQLSetDescField.

Os valores dos campos também podem ser recuperados individualmente por meio de uma chamada para SQLGetDescField. Para uma descrição dos campos em um cabeçalho ou registro de descritor, veja SQLSetDescField. Para obter mais informações sobre descritores, consulte Descritores.

Para obter informações sobre Veja
Vinculação de uma coluna Função SQLBindCol
Vinculação de um parâmetro Função SQLBindParameter
Obtendo um campo descritor Função SQLGetDescField
Definindo múltiplos campos de descritores Função SQLSetDescRec

Conteúdo relacionado

  • Last updated on