Função SQLGetStmtAttr
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.
Funções relacionadas
| 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 |