Compartilhar via

Função SQLSetDescRec

  • Artigo

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

de Resumo do
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 a partir 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.

de comprimento
[Entrada] O valor para o qual definir o campo SQL_DESC_OCTET_LENGTH para o registro do descritor.

de precisão
[Entrada] O valor para o qual definir o campo SQL_DESC_PRECISION para o registro do descritor.

de 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. 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.

Retorna

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

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 de identificador de 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 observado o contrário.

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 o DescriptorHandle referenciado a um identificador IPD.

O argumento RecNumber foi menor que 0.

O argumento RecNumber foi maior do que o número máximo de colunas ou parâmetros aos quais 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 referenciado 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 explicitamente alocado é um APD ou ARD até o tempo de execução.)
08S01 Falha no link de comunicação O vínculo de comunicação entre o driver e a fonte de dados à qual o driver foi conectado falhou antes de a 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 à 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, SQLBulkOperationsou SQLSetPos foi chamado para o StatementHandle com o 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 assíncrona ainda estava em execução quando a função SQLSetDescRec foi chamada.

(DM) SQLExecute, SQLExecDirectou SQLMoreResults foi chamado para um dos identificadores de instrução associados ao DescriptorHandle e retornado 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 baixas.
HY016 Não é possível modificar um descritor de linha de implementação O argumento DescriptorHandle foi associado a um IRD.
HY021 Informações de descritor inconsistentes 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. (Consulte "Verificações de consistência", mais adiante nesta seção.)
HY090 Comprimento inválido de cadeia de caracteres ou buffer (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 desconectadas e somente leitura são permitidas. (DM) Para obter mais informações sobre o estado suspenso, consulte de função SQLEndTran .
HYT01 Tempo limite de conexão expirado 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 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

Nota

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 uma APD e um IPD em uma chamada e não requer um identificador de descritor.

Nota

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 de descritor inconsistentes).

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 SQL_DESC_TYPE são válidos e consistentes. Essa verificação sempre é executada quando sqlBindParameter ou SQLBindCol é chamado ou quando SQLSetDescRec é chamado para uma 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 de datetime e intervalo.

  • 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 intervalo ou datetime 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 de tempo ou carimbo de data/hora, 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. Não é possível executar uma verificação de consistência em um IRD. O valor para o qual o campo SQL_DESC_DATA_PTR do IPD não está 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.

Para obter informações sobre Ver
Associar uma coluna de função SQLBindCol
Associar um parâmetro função SQLBindParameter
Obtendo um único campo de descritor de função SQLGetDescField
Obtendo vários campos de descritor função SQLGetDescRec
Definindo campos de descritor único função SQLSetDescField

Consulte Também

referência da API ODBC
arquivos de cabeçalho ODBC