Função SQLNativeSql

Conformidade
Versão Introduzida: Conformidade com os Padrões ODBC 1.0: ODBC

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

Sintaxe

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

Argumentos

Identificador de conexão
[Entrada] Identificador de conexão.

TextoDeInStatement
[Entrada] String de texto SQL a ser traduzida.

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

OutstatementText
[Saída] Apontador para um buffer no qual retorna a string SQL traduzida.

Se OutStatementText for NULL, TextLength2Ptr ainda retornará o número total de caracteres (excluindo o caractere de término nulo para dados de caracteres) disponíveis para retorno no buffer apontado pelo OutStatementText.

BufferLength
[Entrada] Número de caracteres no buffer *OutStatementText . Versões anteriores dessa documentação sugeriam erroneamente que essa contagem de caracteres deveria ser mesmo que o valor retornado em *InStatementText fosse uma string Unicode (ao chamar SQLNativeSqlW). Não existe tal restrição. Para interoperabilidade ideal, os desenvolvedores de drivers devem esperar que qualquer contagem de caracteres seja passada para essa função, enquanto os desenvolvedores de aplicativos são recomendados a sempre usar uma contagem par.

TextLength2Ptr
[Saída] Apontador para um buffer no qual retorna o número total de caracteres (excluindo terminação nula) disponíveis para retorno em *OutStatementText. Se o número de caracteres disponíveis para retorno for maior ou igual a BufferLength, a string SQL traduzida em *OutStatementText é truncada para BufferLength menos o comprimento de um caractere de terminação nula.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

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 pelo SQLNativeSQL e explica cada um no contexto dessa função; a notação "(DM)" precede as descrições dos SQLSTATEs retornadas pelo Gerenciador de Drivers. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, a menos que indicado de outra forma.

SQLSTATE Erro Description
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 toda a string SQL, então a string SQL foi truncada. O comprimento da string SQL não arrunada é retornado em *TextLength2Ptr. (A função retorna SQL_SUCCESS_WITH_INFO.)
08003 Conexão não aberta O ConnectionHandle não estava em 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 estava conectado falhou antes que a função concluísse o processamento.
22007 Formato de data e hora inválido * InStatementText continha uma cláusula de escape com data, hora ou valor de carimbo de tempo inválidos.
24000 Estado de cursor inválido O cursor referido na instrução era posicionado antes do início do conjunto de resultados ou após o fim do conjunto de resultados. Esse erro pode não ser retornado por um driver que tenha uma implementação nativa de cursor do SGBD.
HY000 Erro geral Ocorreu um erro para o qual não havia SQLSTATE específico e para o qual nenhum SQLSTATE específico da 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 dar suporte à 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 era chamada para o ConnectionHandle e ainda estava executando quando essa função era 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 memória baixa.
HY090 Cadeia de caracteres ou comprimento de buffer inválido (DM) O argumento TextLength1 era 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 deletada ou não havia sido buscada. Esse erro pode não ser retornado por um driver que tenha uma implementação nativa de cursor do SGBD.
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 da conexão expirou antes que a fonte de dados respondesse à 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 suporta esta função (DM) O driver associado ao ConnectionHandle não suporta essa função.

Comments

A seguir, estão exemplos do que o SQLNativeSQL pode devolver para a seguinte string SQL de entrada contendo a função escalar CONVERT. Suponha que o empid da coluna seja do tipo INTEGER na fonte de dados:

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

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

SELECT convert (smallint, empid) FROM employee

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

SELECT to_number (empid) FROM employee

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

SELECT int2 (empid) FROM employee

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

None.

Conteúdo relacionado

  • Last updated on