Função SQLNativeSql
Conformidade
Versão introduzida: ODBC 1.0 Conformidade com padrões: ODBC
Resumo
SQLNativeSql retorna a cadeia de caracteres SQL conforme modificada pelo driver. SQLNativeSql não executa a instrução SQL.
Syntax
SQLRETURN SQLNativeSql(
SQLHDBC ConnectionHandle,
SQLCHAR * InStatementText,
SQLINTEGER TextLength1,
SQLCHAR * OutStatementText,
SQLINTEGER BufferLength,
SQLINTEGER * TextLength2Ptr);
Argumentos
Identificador de conexão
[Entrada] Identificador de conexão.
InStatementText
[Entrada] Cadeia de texto SQL a ser traduzida.
Comprimento do texto1
[Entrada] Comprimento em caracteres da cadeia de texto *InStatementText .
OutStatementText
[Saída] Ponteiro para um buffer no qual retornar a cadeia de caracteres SQL traduzida.
Se OutStatementText for NULL, TextLength2Ptr ainda retornará o número total de caracteres (excluindo o caractere de terminação nula para dados de caracteres) disponíveis para retornar no buffer apontado por OutStatementText.
BufferLength
[Entrada] Número de caracteres no buffer *OutStatementText . Versões anteriores desta documentação implicaram erroneamente que essa contagem de caracteres deve ser mesmo se o valor retornado em *InStatementText for uma cadeia de caracteres Unicode (ao chamar SQLNativeSqlW). Não há essa restrição. Para uma interoperabilidade ideal, os criadores de drivers devem esperar que qualquer contagem de caracteres seja passada para essa função, enquanto os escritores de aplicativos são recomendados a sempre usar uma contagem par.
TextLength2Ptr
[Saída] Ponteiro para um buffer no qual retornar o número total de caracteres (excluindo terminação nula) disponíveis para retornar em *OutStatementText. Se o número de caracteres disponíveis para retorno for maior ou igual a BufferLength, a cadeia de caracteres SQL traduzida em *OutStatementText será truncada para BufferLength menos o comprimento de um caractere de terminação nula.
Retornos
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnósticos
Quando SQLNativeSql retorna SQL_ERROR ou SQL_SUCCESS_WITH_INFO, um valor SQLSTATE associado pode ser obtido chamando SQLGetDiagRec com um HandleType de SQL_HANDLE_DBC e um Handle de ConnectionHandle. A tabela a seguir lista os valores SQLSTATE comumente retornados por SQLNativeSql e explica cada um 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 | O buffer *OutStatementText não era grande o suficiente para retornar a cadeia de caracteres SQL inteira, portanto, a cadeia de caracteres SQL foi truncada. O comprimento da cadeia de caracteres SQL não truncada é retornado em *TextLength2Ptr. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 08003 | Conexão não aberta | O ConnectionHandle não estava em um estado conectado. |
| 08S01 | Falha no link de comunicação | O link de comunicação entre o driver e a fonte de dados à qual o driver foi conectado falhou antes que o processamento da função fosse concluído. |
| 22007 | Formato datetime inválido | *InStatementText continha uma cláusula de escape com um valor de data, hora ou carimbo de data/hora inválido. |
| 24.000 | Estado inválido do cursor | O cursor referido no enunciado foi posicionado antes do início da série de resultados ou após o término da série de resultados. Esse erro não pode ser retornado por um driver com uma implementação de cursor DBMS nativa. |
| 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 *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. |
| HY009 | Uso inválido de ponteiro nulo | (DM) *InStatementText era um ponteiro nulo. |
| HY010 | Erro de sequência de função | (DM) Uma função de execução assíncrona foi chamada para o ConnectionHandle e ainda estava em execução quando essa função foi chamada. |
| 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. |
| HY090 | Cadeia de caracteres inválida ou comprimento do buffer | (DM) O argumento TextLength1 foi menor que 0, mas não igual a SQL_NTS. |
| (DM) O argumento BufferLength era menor que 0 e o argumento OutStatementText não era um ponteiro nulo. | ||
| HY109 | Posição inválida do cursor | A linha atual do cursor havia sido excluída ou não havia sido buscada. Esse erro não pode ser retornado por um driver com uma implementação de cursor DBMS nativa. |
| 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. |
| HYT01 | O tempo limite da 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 de conexão é definido por meio de SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Driver não suporta esta função | (DM) O driver associado ao ConnectionHandle não oferece suporte à função. |
Comentários
A seguir estão exemplos do que SQLNativeSql pode retornar para a seguinte cadeia de caracteres SQL de entrada que contém a função escalar CONVERT. Suponha que a coluna empid é do tipo INTEGER na fonte de dados:
SELECT { fn CONVERT (empid, SQL_SMALLINT) } FROM employee
Um driver para o Microsoft SQL Server pode retornar a seguinte sequência de caracteres SQL traduzida:
SELECT convert (smallint, empid) FROM employee
Um driver para o ORACLE Server pode retornar a seguinte cadeia de caracteres SQL traduzida:
SELECT to_number (empid) FROM employee
Um driver para Ingres pode retornar a seguinte sequência de caracteres SQL traduzida:
SELECT int2 (empid) FROM employee
Para obter mais informações, consulte Execução direta e Execução preparada.
Funções relacionadas
Nenhum.