Partilhar via

Função SQLGetStmtAttr

  • Artigo

Conformidade
Versão introduzida: ODBC 3.0 Standards Compliance: ISO 92

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

Observação

Para obter mais informações sobre o que o Gerenciador de Driver mapeia essa função para quando um ODBC 3. o aplicativo x está trabalhando com um ODBC 2. x driver, consulte Mapeando funções de substituição para compatibilidade com versões anteriores de aplicativos.

Sintaxe

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

Argumentos

StatementHandle
[Entrada] Identificador de instrução.

Atributo
[Entrada] Atributo a ser recuperado.

ValuePtr
[Saída] Ponteiro para um buffer no qual retornar o valor do atributo especificado em Attribute.

Se ValuePtr for NULL, StringLengthPtr ainda retornará o número total de bytes (excluindo o caractere de terminação nula para dados de caractere) disponíveis para retornar no buffer apontado por 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 Attribute for um atributo definido por ODBC e *ValuePtr for um inteiro, BufferLength será ignorado. Se o valor retornado em *ValuePtr for uma cadeia de caracteres Unicode (ao chamar SQLGetStmtAttrW), o argumento BufferLength deverá ser um número par.

Se Attribute for um atributo definido pelo driver, o aplicativo indicará a natureza do atributo para o Gerenciador de Driver definindo o argumento BufferLength . BufferLength pode ter os seguintes valores:

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

  • Se *ValuePtr for um ponteiro para um buffer binário, o aplicativo colocará o resultado da macro SQL_LEN_BINARY_ATTR(length) em BufferLength. Isso coloca um valor negativo em BufferLength.

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

  • Se *ValuePtr contiver um tipo de dados de comprimento fixo, BufferLength será SQL_IS_INTEGER ou SQL_IS_UINTEGER, conforme apropriado.

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

Retornos

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnósticos

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 Identificador de StatementHandle. A tabela a seguir lista os valores SQLSTATE normalmente retornados por SQLGetStmtAttr 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.)
01004 Dados de cadeia de caracteres, truncados à direita Os dados retornados em *ValuePtr foram truncados para serem BufferLength menos o comprimento de um caractere de terminação nula. O comprimento do valor da cadeia de caracteres não confiável é retornado em *StringLengthPtr. (A função retorna SQL_SUCCESS_WITH_INFO.)
24.000 Estado de cursor inválido O argumento Attribute foi 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 após o final do conjunto de resultados.
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 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ções (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 foram chamados para o StatementHandle e retornaram 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.
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 Comprimento de buffer ou cadeia de caracteres inválida (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 Attribute não era válido para a versão do ODBC compatível com o driver.
HY109 Posição inválida do cursor O argumento Attribute foi SQL_ATTR_ROW_NUMBER e a linha foi excluída ou não pôde ser buscada.
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.
HYC00 Recurso opcional não implementado O valor especificado para o argumento Attribute era um atributo de instrução ODBC válido para a versão do ODBC compatível com o driver, mas não era compatível com o driver.
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 correspondente ao StatementHandle não dá suporte à função.

Comentários

Para obter informações gerais sobre atributos de instrução, consulte Atributos de instrução.

Uma chamada para SQLGetStmtAttr retorna em *ValuePtr o valor do atributo de instrução especificado em Attribute. Esse valor pode ser um valor SQLULEN ou uma cadeia de caracteres terminada em nulo. Se o valor for um valor SQLULEN, alguns drivers só poderão gravar os 32 bits inferiores ou 16 bits de um buffer e deixar o bit de ordem superior inalterado. Portanto, os aplicativos devem usar um buffer de SQLULEN e inicializar o valor como 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 cadeia de caracteres terminada em nulo, o aplicativo especificará o comprimento máximo dessa cadeia de caracteres no argumento BufferLength e o driver retornará o comprimento dessa cadeia de caracteres no buffer *StringLengthPtr .

Para permitir que aplicativos que chamam SQLGetStmtAttr funcionem com o ODBC 2. x drivers, uma chamada para SQLGetStmtAttr é mapeada no Gerenciador de Driver para SQLGetStmtOption.

Os atributos de instrução a seguir são somente leitura, portanto, podem ser recuperados por SQLGetStmtAttr, mas não definidos por SQLSetStmtAttr:

  • SQL_ATTR_IMP_PARAM_DESC

  • SQL_ATTR_IMP_ROW_DESC

  • SQL_ATTR_ROW_NUMBER

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

Para obter informações sobre Consulte
Retornando a configuração de um atributo de conexão Função SQLGetConnectAttr
Configurando um atributo de conexão Função SQLSetConnectAttr
Configurando um atributo de instrução Função SQLSetStmtAttr

Consulte Também

Referência de API do ODBC
Arquivos de cabeçalho ODBC