Função SQLGetDescRec

Conformidade
Versão introduzida: Conformidade de padrões do ODBC 3.0: ISO 92

Resumo
SQLGetDescRec retorna as configurações atuais ou os valores de vários campos de um registro de descritor. Os campos retornados descrevem o nome, o tipo de dados e o armazenamento de dados de coluna ou parâmetro.

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] Identificador do descritor.

RecNumber
[Entrada] Indica o registro do descritor do qual o aplicativo busca informações. Os registros do descritor são numerados de 1, com o número de registro 0 sendo o registro de indicador. 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 obter mais informações, confira "Inicialização de campos de descritor" em SQLSetDescField.)

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

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

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

StringLengthPtr
[Saída] Um ponteiro para um buffer no qual retornar o número de caracteres de dados disponíveis para retornar no buffer *Name , excluindo o caractere de terminação nula. Se o número de caracteres for maior ou igual a BufferLength, os dados em *Name serão truncados para BufferLength menos o comprimento de um caractere de terminação nula e serão encerrados em nulo pelo driver.

TypePtr
[Saída] Um ponteiro para um buffer no qual 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, esse é um ponteiro para um buffer no qual retornar o valor do campo SQL_DESC_DATETIME_INTERVAL_CODE.

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

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

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

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

Retornos

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA ou SQL_INVALID_HANDLE.

SQL_NO_DATA será retornado se RecNumber for maior que o número atual de registros descritores.

SQL_NO_DATA será retornado se DescriptorHandle for um identificador IRD e a instrução estiver no estado preparado ou executado, mas não houver nenhum cursor aberto associado a ele.

Diagnósticos

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 Identificador de DescriptorHandle. A tabela a seguir lista os valores SQLSTATE normalmente retornados por SQLGetDescRec e explica cada um deles no contexto dessa função; a notação "(DM)" precede as descrições de SQLSTATEs retornadas pelo Gerenciador de Driver. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, a menos que indicado o contrário.

Comentários

Um aplicativo pode chamar SQLGetDescRec para recuperar os valores dos seguintes campos de descritor 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.

Um aplicativo pode impedir o retorno da configuração de um campo definindo o argumento que corresponde ao campo como um ponteiro nulo.

Quando um aplicativo chama SQLGetDescRec para recuperar o valor de um campo indefinido para um tipo de descritor específico, 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 mas um valor indefinido para o campo.

Quando um aplicativo chama SQLGetDescRec para recuperar o valor de um campo definido para um tipo de descritor específico, mas que não tem nenhum valor padrão e ainda não foi definido, a função retorna SQL_SUCCESS mas o valor retornado para o campo é indefinido. Para obter mais informações, consulte "Inicialização de campos de descritor" em SQLSetDescField.

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

Funções relacionadas

Consulte Também

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