Função SQLNativeSql

Conformidade
Versão Introduzida: Conformidade com as Normas ODBC 1.0: ODBC

Summary
O SQLNativeSQL devolve a string SQL conforme modificada pelo driver. O SQLNativeSQL não executa a instrução SQL.

Syntax

  
SQLRETURN SQLNativeSql(  
     SQLHDBC        ConnectionHandle,  
     SQLCHAR *      InStatementText,  
     SQLINTEGER     TextLength1,  
     SQLCHAR *      OutStatementText,  
     SQLINTEGER     BufferLength,  
     SQLINTEGER *   TextLength2Ptr);

Arguments

ConnectionHandle
[Entrada] Alavanca de ligação.

InStatementText
[Entrada] String de texto SQL a traduzir.

TextLength1
[Entrada] Comprimento em caracteres da string de texto *InStatementText .

OutstatementText
[Saída] Apontador para um buffer onde deveria devolver a string SQL traduzida.

Se OutStatementText for NULL, o TextLength2Ptr continuará a devolver o número total de caracteres (excluindo o carácter de terminação nula para dados de caracteres) disponíveis para devolver no buffer apontado pelo OutStatementText.

BufferLength
[Entrada] Número de caracteres no *OutStatementText buffer. Versões anteriores desta documentação sugeriram erroneamente que esta contagem de caracteres deve ser mesmo que o valor devolvido em *InStatementText seja uma cadeia Unicode (ao chamar SQLNativeSqlW). Não existe tal restrição. Para uma interoperabilidade ótima, os criadores de drivers devem esperar que qualquer contagem de caracteres seja passada para esta função, enquanto os criadores de aplicações são recomendados a usar sempre uma contagem par.

TextLength2Ptr
[Saída] Apontar para um buffer onde devolver o número total de caracteres (excluindo terminação nula) disponíveis para devolver em *OutStatementText. Se o número de caracteres disponíveis para devolver for maior ou igual a BufferLength, a string SQL traduzida em *OutStatementText é truncada para BufferLength menos o comprimento de um carácter de terminação nula.

Devoluções

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 seguinte lista os valores SQLSTATE normalmente devolvidos pelo SQLNativeSQL e explica cada um no contexto desta função; a notação "(DM)" precede as descrições dos SQLSTATEs devolvidas pelo Gestor de Drivers. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, salvo indicação em contrário.

SQLSTATE Erro Description
01000 Aviso geral Mensagem informativa específica para o condutor. (Função devolve SQL_SUCCESS_WITH_INFO.)
01004 Dados de cadeia, truncados à direita O buffer *OutStatementText não era suficientemente grande para devolver toda a string SQL, por isso a string SQL foi truncada. O comprimento da string SQL não arruinada é devolvido em *TextLength2Ptr. (Função devolve SQL_SUCCESS_WITH_INFO.)
08003 Ligação não aberta O ConnectionHandle não estava num estado ligado.
08S01 Falha da ligação de comunicação A ligação de comunicação entre o driver e a fonte de dados à qual o driver estava ligado falhou antes de a função concluir o processamento.
22007 Formato de data-hora inválido * O InStatementText continha uma cláusula de escape com data, hora ou carimbo temporal inválidos.
24000 Estado do cursor inválido O cursor referido na instrução era posicionado antes do início do conjunto de resultados ou depois do fim do conjunto. Este erro pode não ser devolvido por um driver que tenha uma implementação nativa do cursor do SGBD.
HY000 Erro geral Ocorreu um erro para o qual não existia um SQLSTATE específico e para o qual não estava definido nenhum SQLSTATE específico da implementação. A mensagem de erro devolvida pelo SQLGetDiagRec no buffer *MessageText descreve o erro e a sua causa.
HY001 Erro de alocação de memória O driver não conseguia alocar a memória necessária para suportar a execução ou conclusão da função.
HY009 Uso inválido do ponteiro nulo (DM) *InStatementText era um ponto nulo.
HY010 Erro de sequência de funções (DM) Uma função de execução assíncrona era chamada para o ConnectionHandle e continuava a ser executada quando esta função era chamada.
HY013 Erro de gestão de memória A chamada de função não podia ser processada porque os objetos de memória subjacentes não podiam ser acedidos, possivelmente devido a condições de baixa memória.
HY090 Comprimento inválido da corda ou do buffer (DM) O argumento TextLength1 era inferior a 0, mas não igual a SQL_NTS.
(DM) O argumento BufferLength era inferior a 0 e o argumento OutStatementText não era um ponteiro nulo.
HY109 Posição inválida do cursor A linha atual do cursor tinha sido apagada ou não tinha sido recuperada. Este erro pode não ser devolvido por um driver que tenha uma implementação nativa do cursor do SGBD.
HY117 A ligação é suspensa devido ao estado desconhecido da transação. Apenas funções de desconexão e de leitura são permitidas. (DM) Para mais informações sobre o estado suspenso, veja Função SQLEndTran.
HYT01 Expirou o tempo limite de ligação O período de timeout da ligação expirou antes de a fonte de dados responder ao pedido. O período de tempo de expiração da ligação é definido através do SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 O driver não suporta esta função (DM) O driver associado ao ConnectionHandle não suporta esta função.

Comments

Seguem-se exemplos do que o SQLNativeSQL pode devolver para a seguinte string SQL de entrada contendo a função escalar CONVERT. Assuma que o empid da coluna é do tipo INTEGER na fonte de dados:

SELECT { fn CONVERT (empid, SQL_SMALLINT) } FROM employee

Um driver para Microsoft SQL Server pode devolver a seguinte string SQL traduzida:

SELECT convert (smallint, empid) FROM employee

Um driver para o ORACLE Server pode devolver a seguinte string SQL traduzida:

SELECT to_number (empid) FROM employee

Um driver para Ingres pode devolver a seguinte string SQL traduzida:

SELECT int2 (empid) FROM employee

Para mais informações, consulte Execução Direta e Execução Preparada.

Nenhum.

Conteúdo relacionado

  • Last updated on