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.
| 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 descritor. Portanto, o campo foi truncado. O comprimento do campo descritor não confiável é retornado em *StringLengthPtr. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 07009 | Índice de descritor inválido | O argumento FieldIdentifier era um campo de registro, o argumento RecNumber foi definido como 0 e o argumento DescriptorHandle era um identificador IPD. (DM) O argumento RecNumber foi definido como 0 e o atributo de instrução SQL_ATTR_USE_BOOKMARKS foi definido como SQL_UB_OFF e o argumento DescriptorHandle era um identificador IRD. O argumento 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 foi conectado falhou antes da função concluir o processamento. |
| HY000 | Erro geral | Ocorreu um erro para o qual não havia nenhum 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 instrução associada não está preparada | DescriptorHandle foi associado a um IRD e o identificador de instrução associado não estava no estado preparado ou executado. |
| HY010 | Erro de sequência de funções | (DM) DescriptorHandle foi associado a um StatementHandle para o qual uma função de execução assíncrona (não esta) foi chamada e ainda estava em execução quando essa função foi chamada. (DM) DescriptorHandle foi associado a um StatementHandle para o qual SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos foi chamado e retornado SQL_NEED_DATA. Essa função foi chamada antes de os dados serem enviados para todos os parâmetros ou colunas de dados em execução. (DM) Uma função em execução assíncrona foi chamada para o identificador de conexão associado ao DescriptorHandle. Essa função assíncrona ainda estava em execução quando 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 de transação desconhecido. Somente funções desconectar 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 da fonte de dados responder à 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 dá suporte a essa função | (DM) O driver associado a DescriptorHandle não dá suporte à função . |
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
| Para obter informações sobre | Consulte |
|---|---|
| Associar uma coluna | Função SQLBindCol |
| Associar um parâmetro | Função SQLBindParameter |
| Obtendo um campo de descritor | Função SQLGetDescField |
| Configurando vários campos de descritor | Função SQLSetDescRec |