Função SQLGetStmtAttr

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

Summary
SQLGetStmtAttr retorna a configuração atual de um atributo de instrução.

Note

Para mais informações sobre o que o Driver Manager mapeia essa função quando um ODBC 3. A aplicação x está funcionando com um ODBC 2. x , veja Mapeamento de Funções de Substituição para Compatibilidade Retroativa de Aplicações.

Sintaxe

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

Argumentos

Identificador de declaração
[Entrada] Identificador de instrução.

Atributo
[Entrada] Atributo para recuperar.

ValuePtr
[Saída] Apontador para um buffer no qual devolver o valor do atributo especificado em Atributo.

Se ValuePtr for NULL, StringLengthPtr ainda retornará o número total de bytes (excluindo o caractere de terminação nula para dados de caracteres) disponíveis para retorno no buffer apontado pelo ValuePtr.

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

Se o Atributo for 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 é um ponteiro para uma cadeia de caracteres, então BufferLength é o comprimento da string 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. Isso coloca um valor negativo no BufferLength.

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

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

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

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

Quando SQLGetStmtAttr retorna SQL_ERROR ou SQL_SUCCESS_WITH_INFO, um valor SQLSTATE associado pode ser obtido chamando SQLGetDiagRec com um HandleType de SQL_HANDLE_STMT e um Handle de StatementHandle. A tabela a seguir lista os valores SQLSTATE comumente retornados pelo SQLGetStmtAttr e explica cada um no contexto dessa função; a notação "(DM)" precede as descrições dos SQLSTATEs retornadas pelo Gerenciador de Drivers. 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.)
01004 Dados de cadeia de caracteres, truncados à direita Os dados retornados em *ValuePtr foram truncados para ser BufferLength menos o comprimento de um caractere de terminação nula. O comprimento do valor da string não arrunada é retornado em *StringLengthPtr. (A função retorna SQL_SUCCESS_WITH_INFO.)
24000 Estado de cursor inválido O argumento Atributo estava SQL_ATTR_ROW_NUMBER e o cursor não estava aberto, ou o cursor foi 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 havia SQLSTATE específico e para o qual nenhum SQLSTATE específico da implementação foi definido. A mensagem de erro retornada pelo SQLGetDiagRec no argumento 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ção (DM) Uma função de execução assíncrona foi chamada para o identificador de conexão associado ao StatementHandle. Essa função assíncrona ainda estava em execução quando a função SQLGetStmtAttr foi chamada.

(DM) Uma função de execução assíncrona foi chamada para o StatementHandle e ainda estava em execução quando essa função foi chamada.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos foi chamado para o StatementHandle e retornado SQL_NEED_DATA. Essa função foi chamada antes que os dados fossem enviados para todos os parâmetros ou colunas de dados em execução.
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.
HY090 Cadeia de caracteres ou comprimento de buffer inválido (DM) *ValuePtr é uma sequência 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 atributo do argumento não era válido para a versão do ODBC suportada pelo driver.
HY109 Posição inválida do cursor O argumento do Atributo foi SQL_ATTR_ROW_NUMBER e a linha foi deletada ou não pôde ser recuperada.
HY117 A conexão está suspensa devido ao estado desconhecido da transação. 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.
HYC00 Recurso opcional não implementado 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 O tempo limite da conexão expirou O período de tempo limite da conexão expirou antes que a fonte de dados respondesse à 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 suporta esta função (DM) O driver correspondente ao StatementHandle não dá suporte à função.

Comments

Para informações gerais sobre atributos de sentença, veja Atributos de Sentença.

Uma chamada para SQLGetStmtAttr retorna 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 gravar apenas 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 em 0 antes de chamar essa função. Além disso, os argumentos BufferLength e StringLengthPtr não são usados. Se o valor for uma string terminada por nulo, a aplicação especifica o comprimento máximo dessa string no argumento BufferLength , e o driver retorna o comprimento dessa string no buffer *StringLengthPtr .

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

Os atributos da seguinte instrução são somente leitura, podendo 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
Retornando a configuração de um atributo de conexão Função SQLGetConnectAttr
Definindo um atributo de conexão Função SQLSetConnectAttr
Configurando um atributo de instrução Função SQLSetStmtAttr

Conteúdo relacionado

  • Last updated on