Função SQLSetDescRec
Conformidade
Versão introduzida: ODBC 3.0 Standards Compliance: ISO 92
Resumo
A função SQLSetDescRec define vários campos de descritor que afetam o tipo de dados e o buffer associados a uma coluna ou dados de parâmetro.
Sintaxe
SQLRETURN SQLSetDescRec(
SQLHDESC DescriptorHandle,
SQLSMALLINT RecNumber,
SQLSMALLINT Type,
SQLSMALLINT SubType,
SQLLEN Length,
SQLSMALLINT Precision,
SQLSMALLINT Scale,
SQLPOINTER DataPtr,
SQLLEN * StringLengthPtr,
SQLLEN * IndicatorPtr);
Argumentos
DescriptorHandle
[Entrada] Identificador de descritor. Isso não deve ser um identificador IRD.
RecNumber
[Entrada] Indica o registro do descritor que contém os campos a serem definidos. Os registros do descritor são numerados de 0, com o número de registro 0 sendo o registro de indicador. Esse argumento deve ser igual ou maior que 0. Se RecNumber for maior que o valor de SQL_DESC_COUNT, SQL_DESC_COUNTis alterado para o valor de RecNumber.
Tipo
[Entrada] O valor para o qual definir o campo SQL_DESC_TYPE para o registro do descritor.
Subtipo
[Entrada] Para registros cujo tipo é SQL_DATETIME ou SQL_INTERVAL, esse é o valor para o qual definir o campo SQL_DESC_DATETIME_INTERVAL_CODE.
Comprimento
[Entrada] O valor para o qual definir o campo SQL_DESC_OCTET_LENGTH para o registro do descritor.
Precisão
[Entrada] O valor para o qual definir o campo SQL_DESC_PRECISION para o registro do descritor.
Escala
[Entrada] O valor para o qual definir o campo SQL_DESC_SCALE para o registro do descritor.
DataPtr
[Entrada ou saída adiada] O valor para o qual definir o campo SQL_DESC_DATA_PTR para o registro do descritor. O DataPtr pode ser definido como um ponteiro nulo.
O argumento DataPtr pode ser definido como um ponteiro nulo para definir o campo SQL_DESC_DATA_PTR como um ponteiro nulo. Se o identificador no argumento DescriptorHandle estiver associado a um ARD, isso desvincula a coluna.
StringLengthPtr
[Entrada ou saída adiada] O valor para o qual definir o campo SQL_DESC_OCTET_LENGTH_PTR para o registro do descritor. StringLengthPtr pode ser definido como um ponteiro nulo para definir o campo SQL_DESC_OCTET_LENGTH_PTR como um ponteiro nulo.
IndicatorPtr
[Entrada ou saída adiada] O valor para o qual definir o campo SQL_DESC_INDICATOR_PTR para o registro do descritor. IndicatorPtr pode ser definido como um ponteiro nulo para definir o campo SQL_DESC_INDICATOR_PTR como um ponteiro nulo.
Retornos
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnósticos
Quando SQLSetDescRec 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 SQLSetDescRec 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 de outra forma.
| SQLSTATE | Erro | Descrição |
|---|---|---|
| 01000 | Aviso geral | Mensagem informativa específica do driver. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 07009 | Índice de descritor inválido | O argumento RecNumber foi definido como 0 e DescriptorHandle se referiu a um identificador IPD. O argumento RecNumber era menor que 0. O argumento RecNumber era maior que o número máximo de colunas ou parâmetros que a fonte de dados pode dar suporte e o argumento DescriptorHandle era um APD, IPD ou ARD. O argumento RecNumber era igual a 0 e o argumento DescriptorHandle se referia a uma APD alocada implicitamente. (Esse erro não ocorre com um descritor de aplicativo explicitamente alocado porque não se sabe se um descritor de aplicativo alocado explicitamente é um APD ou ARD até o tempo de execução.) |
| 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 conclusão do processamento da função. |
| 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. |
| HY010 | Erro de sequência de funções | (DM) O 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) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos foi chamado para o StatementHandle ao qual o DescriptorHandle foi associado 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 de execução assíncrona foi chamada para o identificador de conexão associado ao DescriptorHandle. Essa função asíncrona ainda estava em execução quando a função SQLSetDescRec foi chamada. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults foi chamado para um dos identificadores de instrução associados ao DescriptorHandle e retornados SQL_PARAM_DATA_AVAILABLE. Essa função foi chamada antes de os dados serem recuperados para todos os parâmetros transmitidos. |
| 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. |
| HY016 | Não é possível modificar um descritor de linha de implementação | O argumento DescriptorHandle foi associado a um IRD. |
| HY021 | Informações inconsistentes do descritor | O campo Tipo ou qualquer outro campo associado ao campo SQL_DESC_TYPE no descritor não era válido ou consistente. As informações do descritor verificadas durante uma verificação de consistência não eram consistentes. (Confira "Verificações de consistência", mais adiante nesta seção.) |
| HY090 | Comprimento de buffer ou cadeia de caracteres inválida | (DM) O driver era um driver ODBC 2.x , o descritor era um ARD, o argumento ColumnNumber foi definido como 0 e o valor especificado para o argumento BufferLength não era igual a 4. |
| HY117 | A conexão é suspensa devido ao estado de transação desconhecido. 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 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 ao DescriptorHandle não dá suporte à função . |
Comentários
Um aplicativo pode chamar SQLSetDescRec para definir os seguintes campos para uma única coluna ou parâmetro:
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_DATA_PTR
SQL_DESC_OCTET_LENGTH_PTR
SQL_DESC_INDICATOR_PTR
Observação
Se uma chamada para SQLSetDescRec falhar, o conteúdo do registro do descritor identificado pelo argumento RecNumber será indefinido.
Ao associar uma coluna ou parâmetro, SQLSetDescRec permite alterar vários campos que afetam a associação sem chamar SQLBindCol ou SQLBindParameter ou fazer várias chamadas para SQLSetDescField. SQLSetDescRec pode definir campos em um descritor não associado a uma instrução no momento. Observe que SQLBindParameter define mais campos do que SQLSetDescRec, pode definir campos em um APD e um IPD em uma chamada e não requer um identificador de descritor.
Observação
O atributo de instrução SQL_ATTR_USE_BOOKMARKS sempre deve ser definido antes de chamar SQLSetDescRec com um argumento RecNumber de 0 para definir campos de indicador. Embora isso não seja obrigatório, é altamente recomendável.
Verificações de consistência
Uma verificação de consistência é executada pelo driver automaticamente sempre que um aplicativo define o campo SQL_DESC_DATA_PTR de um APD, ARD ou IPD. Se qualquer um dos campos for inconsistente com outros campos, SQLSetDescRec retornará SQLSTATE HY021 (informações inconsistentes do descritor).
Sempre que um aplicativo define o campo SQL_DESC_DATA_PTR de um APD, ARD ou IPD, o driver verifica se o valor do campo SQL_DESC_TYPE e os valores aplicáveis a esse campo de SQL_DESC_TYPE são válidos e consistentes. Essa verificação sempre é executada quando SQLBindParameter ou SQLBindCol é chamado ou quando SQLSetDescRec é chamado para um APD, ARD ou IPD. Essa verificação de consistência inclui as seguintes verificações nos campos do descritor:
O campo SQL_DESC_TYPE deve ser um dos tipos ODBC C ou SQL válidos ou um tipo SQL específico do driver. O campo SQL_DESC_CONCISE_TYPE deve ser um dos tipos ODBC C ou SQL válidos ou um tipo C ou SQL específico do driver, incluindo os tipos concisos datetime e interval.
Se o campo de registro SQL_DESC_TYPE for SQL_DATETIME ou SQL_INTERVAL, o campo SQL_DESC_DATETIME_INTERVAL_CODE deverá ser um dos códigos de datetime ou intervalo válidos. (Consulte a descrição do campo SQL_DESC_DATETIME_INTERVAL_CODE em SQLSetDescField.)
Se o campo SQL_DESC_TYPE indicar um tipo numérico, os campos SQL_DESC_PRECISION e SQL_DESC_SCALE serão verificados como válidos.
Se o campo SQL_DESC_CONCISE_TYPE for um tipo de dados time ou timestamp, um tipo de intervalo com um componente de segundos ou um dos tipos de dados de intervalo com um componente de tempo, o campo SQL_DESC_PRECISION será verificado como sendo uma precisão de segundos válida.
Se o SQL_DESC_CONCISE_TYPE for um tipo de dados de intervalo, o campo SQL_DESC_DATETIME_INTERVAL_PRECISION será verificado como sendo um valor de precisão à esquerda de intervalo válido.
O campo SQL_DESC_DATA_PTR de um IPD normalmente não está definido; no entanto, um aplicativo pode fazer isso para forçar uma verificação de consistência de campos IPD. Uma verificação de consistência não pode ser executada em um IRD. O valor como o campo SQL_DESC_DATA_PTR do IPD não é realmente armazenado e não pode ser recuperado por uma chamada para SQLGetDescField ou SQLGetDescRec; a configuração é feita apenas para forçar a verificação de consistência.
Funções relacionadas
| Para obter informações sobre | Consulte |
|---|---|
| Associando uma coluna | Função SQLBindCol |
| Associando um parâmetro | Função SQLBindParameter |
| Obtendo um único campo de descritor | Função SQLGetDescField |
| Obtendo vários campos de descritor | Função SQLGetDescRec |
| Definindo campos de descritor único | Função SQLSetDescField |