Função SQLGetStmtAttr

Conformidade
Versão Introduzida: Normas ODBC 3.0 Conformidade: ISO 92

Summary
SQLGetStmtAttr devolve a definição atual de um atributo de instrução.

Note

Para mais informações sobre o que o Driver Manager mapeia esta função quando um ODBC 3. A aplicação x está a funcionar com um ODBC 2. x , veja Mapear Funções de Substituição para Compatibilidade Retrocedora de Aplicações.

Syntax

  
SQLRETURN SQLGetStmtAttr(  
     SQLHSTMT        StatementHandle,  
     SQLINTEGER      Attribute,  
     SQLPOINTER      ValuePtr,  
     SQLINTEGER      BufferLength,  
     SQLINTEGER *    StringLengthPtr);

Arguments

HandleStatement
[Entrada] Identificador do extrato.

Atributo
[Entrada] Atributo para recuperar.

ValuePtr
[Saída] Apontar para um buffer onde devolver o valor do atributo especificado em Attribute.

Se o ValuePtr for NULL, o StringLengthPtr continuará a devolver o número total de bytes (excluindo o carácter de terminação nula para dados de caracteres) disponíveis para devolver no buffer apontado pelo ValuePtr.

BufferLength
[Entrada] Se o Atributo for um atributo definido por ODBC e o ValuePtr apontar para uma cadeia de caracteres ou um buffer binário, este argumento deve corresponder ao comprimento de *ValuePtr. Se o Atributo for definido por ODBC e *ValuePtr for um inteiro, o BufferLength é ignorado. Se o valor devolvido em *ValuePtr for uma cadeia Unicode (ao chamar SQLGetStmtAttrW), o argumento BufferLength deve ser um número par.

Se o Atributo for um atributo definido pelo driver, a aplicação indica a natureza do atributo ao Driver Manager definindo o argumento BufferLength . BufferLength pode ter os seguintes valores:

  • Se *ValuePtr for um ponteiro para uma cadeia de caracteres, então BufferLength é o comprimento da cadeia ou SQL_NTS.

  • Se *ValuePtr for um ponteiro para um buffer binário, então a aplicação coloca o resultado da macro SQL_LEN_BINARY_ATTR(comprimento) em BufferLength. Isto coloca um valor negativo no BufferLength.

  • Se *ValuePtr for um ponteiro para um valor diferente de uma cadeia de caracteres ou binária, então BufferLength deve ter o valor SQL_IS_POINTER.

  • Se *ValuePtr contiver um tipo de dado de comprimento fixo, então BufferLength é SQL_IS_INTEGER ou SQL_IS_UINTEGER, conforme apropriado.

StringLengthPtr
[Saída] Um apontador para um buffer onde deves o número total de bytes (excluindo o carácter de terminação nula) disponíveis para devolver em *ValuePtr. Se o valor do atributo for uma cadeia de caracteres, e o número de bytes disponíveis para devolver for maior ou igual ao BufferLength, os dados em *ValuePtr são truncados para BufferLength menos o comprimento de um carácter de terminação nula e são terminados por null pelo driver.

Devoluções

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnósticos

Quando SQLGetStmtAttr devolve SQL_ERROR ou SQL_SUCCESS_WITH_INFO, pode ser obtido um valor SQLSTATE associado chamando SQLGetDiagRec com um HandleType de SQL_HANDLE_STMT e um Handle de StatementHandle. A tabela seguinte lista os valores SQLSTATE normalmente devolvidos pelo SQLGetStmtAttr e explica cada um no contexto desta função; a notação "(DM)" precede as descrições dos SQLSTATEs devolvidas pelo Gestor de Drivers. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, salvo indicação em contrário.

SQLSTATE Erro Description
01000 Aviso geral Mensagem informativa específica para o condutor. (Função devolve SQL_SUCCESS_WITH_INFO.)
01004 Dados de cadeia, truncados à direita Os dados devolvidos em *ValuePtr foram truncados para ser BufferLength menos o comprimento de um carácter de terminação nula. O comprimento do valor da cadeia não arrunada é devolvido em *StringLengthPtr. (Função devolve SQL_SUCCESS_WITH_INFO.)
24000 Estado do cursor inválido O argumento Atributo estava SQL_ATTR_ROW_NUMBER e o cursor não estava aberto, ou o cursor estava posicionado antes do início do conjunto de resultados ou depois do fim do conjunto de resultados.
HY000 Erro geral Ocorreu um erro para o qual não existia um SQLSTATE específico e para o qual não estava definido nenhum SQLSTATE específico da implementação. A mensagem de erro devolvida pelo SQLGetDiagRec no argumento MessageText descreve o erro e a sua causa.
HY001 Erro de alocação de memória O driver não conseguia alocar a memória necessária para suportar a execução ou conclusão da função.
HY010 Erro de sequência de funções (DM) Uma função de execução assíncrona era chamada para o handle de ligação associado ao StatementHandle. Esta função assíncrona ainda estava a ser executada quando a função SQLGetStmtAttr foi chamada.

(DM) Uma função de execução assíncrona era chamada para o StatementHandle e ainda estava a correr quando esta função foi chamada.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos era chamado para o StatementHandle e devolvido SQL_NEED_DATA. Esta função era chamada antes de os dados serem enviados para todos os parâmetros ou colunas de dados na execução.
HY013 Erro de gestão de memória A chamada de função não podia ser processada porque os objetos de memória subjacentes não podiam ser acedidos, possivelmente devido a condições de baixa memória.
HY090 Comprimento inválido da corda ou do buffer (DM) *ValuePtr é uma cadeia de caracteres, e BufferLength era menor que zero, mas não igual a SQL_NTS.
HY092 Identificador de atributo/opção inválido O valor especificado para o argumento Atributo não era válido para a versão de ODBC suportada pelo driver.
HY109 Posição inválida do cursor O argumento do Atributo foi SQL_ATTR_ROW_NUMBER e a linha tinha sido apagada ou não podia ser recuperada.
HY117 A ligação é suspensa devido ao estado desconhecido da transação. Apenas funções de desconexão e de leitura são permitidas. (DM) Para mais informações sobre o estado suspenso, veja Função SQLEndTran.
HYC00 Funcionalidade opcional não implementada O valor especificado para o atributo argumento Attribute era válido para a versão de ODBC suportada pelo driver, mas não era suportado pelo driver.
HYT01 Expirou o tempo limite de ligação O período de timeout da ligação expirou antes de a fonte de dados responder ao pedido. O período de tempo de expiração da ligação é definido através do SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 O driver não suporta esta função (DM) O driver correspondente ao StatementHandle não suporta a função.

Comments

Para informações gerais sobre atributos de instruções, consulte Atributos de Statement.

Uma chamada ao SQLGetStmtAttr devolve em *ValuePtr o valor do atributo da instrução especificado em Attribute. Esse valor pode ser um valor SQLULEN ou uma cadeia de caracteres terminada por nulo. Se o valor for um valor SQLULEN, alguns drivers podem apenas escrever os 32 ou 16 bits inferiores de um buffer e deixar o bit de ordem superior inalterado. Portanto, as aplicações devem usar um buffer de SQLULEN e inicializar o valor a 0 antes de chamar esta função. Além disso, os argumentos BufferLength e StringLengthPtr não são utilizados. Se o valor for uma cadeia terminada por nulo, a aplicação especifica o comprimento máximo dessa cadeia no argumento BufferLength , e o driver devolve o comprimento dessa cadeia no buffer *StringLengthPtr .

Para permitir que aplicações que chamam SQLGetStmtAttr funcionem com ODBC 2. x , uma chamada para SQLGetStmtAttr é mapeada no Gestor de Drivers para SQLGetStmtOption.

Os seguintes atributos da instrução são apenas de leitura, pelo que podem ser recuperados pelo SQLGetStmtAttr, mas não definidos pelo SQLSetStmtAttr:

  • SQL_ATTR_IMP_PARAM_DESC

  • SQL_ATTR_IMP_ROW_DESC

  • SQL_ATTR_ROW_NUMBER

Para uma lista de atributos que podem ser definidos e recuperados, veja SQLSetStmtAttr.

Para obter informações sobre Veja
Devolver a definição de um atributo de conexão Função SQLGetConnectAttr
Definir um atributo de ligação Função SQLSetConnectAttr
Definir um atributo de instrução Função SQLSetStmtAttr

Conteúdo relacionado

  • Last updated on