Partilhar via


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.

Nenhum.

Consulte Também

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