Partilhar via

Função SQLSetDescRec

  • Artigo

Conformidade
Versão introduzida: Conformidade com as normas ODBC 3.0: ISO 92

Resumo
A função SQLSetDescRec define vários campos descritores que afetam o tipo de dados e o buffer vinculado 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 do descritor. Este 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 do indicador. Este argumento deve ser igual ou superior a 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.

de 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 diferida] 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 uma ARD, isso desvinculará a coluna.

StringLengthPtr
[Entrada ou saída diferida] 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 diferida] 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.

Devoluções

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnóstico

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 Handle 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 retornados pelo Gerenciador de Driver. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, salvo indicação em contrário.

SQLSTATE Erro Descrição
01000 Advertência geral Mensagem informativa específica do motorista. (A função retorna SQL_SUCCESS_WITH_INFO.)
07009 Índice de descritor inválido O argumento RecNumber foi definido como 0 e o DescriptorHandle se referia a um identificador IPD.

O argumento RecNumber foi inferior a 0.

O argumento RecNumber era maior do que o número máximo de colunas ou parâmetros que a fonte de dados pode suportar, e o argumento DescriptorHandle era um APD, IPD ou ARD.

O argumento RecNumber foi igual a 0, e o argumento DescriptorHandle referia-se a um APD implicitamente alocado. (Este 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 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 de implementação foi definido. A mensagem de erro retornada por SQLGetDiagRec no buffer de *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 suportar a execução ou conclusão da função.
HY010 Erro de sequência de função (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. Esta 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 retornou SQL_PARAM_DATA_AVAILABLE. Esta função foi chamada antes que os dados fossem 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 pouca memória.
HY016 Não é possível modificar um descritor de linha de implementação O argumento DescriptorHandle foi associado a uma 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. (Consulte "Verificações de consistência", mais adiante nesta seção.)
HY090 String inválida ou comprimento do 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 desconhecido da transação. Apenas as 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 de conexão expirou O período de tempo limite de conexão expirou antes que a fonte de dados respondesse à solicitação. O período de tempo limite da conexão é definido por meio SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT.
IM001 Driver não suporta esta função (DM) O driver associado ao DescriptorHandle não suporta a função.

Observações

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 registos 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 descritor identificado pelo argumento RecNumber será indefinido.

Ao vincular 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 atualmente a uma instrução. 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 deve sempre 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 recomendado.

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 um APD, ARD ou IPD. Esta 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 data/hora 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 de carimbo de data/hora 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 uma precisão de segundos válida.

  • Se o SQL_DESC_CONCISE_TYPE for um tipo de dados de intervalo, verifica-se que o campo SQL_DESC_DATETIME_INTERVAL_PRECISION é um valor de precisão à esquerda de intervalo válido.

O campo SQL_DESC_DATA_PTR de um IPD não é normalmente definido; no entanto, um aplicativo pode fazer isso para forçar uma verificação de consistência dos campos IPD. Uma verificação de consistência não pode ser executada em um IRD. O valor para o qual o campo SQL_DESC_DATA_PTR do IPD está definido 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.

Para obter informações sobre Ver
Vinculando uma coluna da função SQLBindCol
Vinculando um parâmetro da função SQLBindParameter
Obter um único campo descritor da função SQLGetDescField
Obter vários campos descritores de função SQLGetDescRec
Definição de campos descritores únicos da função SQLSetDescField

Ver também

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