Funzione SQLNativeSql

Conformità
Versione introdotta: Conformità agli standard ODBC 1.0: ODBC

Riepilogo
SQLNativeSql restituisce la stringa SQL modificata dal driver. SQLNativeSql non esegue l'istruzione SQL.

Sintassi

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

Argomenti

ConnectionHandle
[Input] Handle di connessione.

InStatementText
[Input] Stringa di testo SQL da tradurre.

TextLength1
[Input] Lunghezza in caratteri della stringa di testo *InStatementText .

OutStatementText
[Output] Puntatore a un buffer in cui restituire la stringa SQL tradotta.

Se OutStatementText è NULL, TextLength2Ptr restituirà comunque il numero totale di caratteri (escluso il carattere di terminazione Null per i dati di tipo carattere) da restituire nel buffer a cui punta OutStatementText.

BufferLength
[Input] Numero di caratteri nel buffer *OutStatementText . Le versioni precedenti di questa documentazione implicano erroneamente che questo conteggio di caratteri deve essere anche se il valore restituito in *InStatementText è una stringa Unicode (quando si chiama SQLNativeSqlW). Non esiste alcuna restrizione di questo tipo. Per un'interoperabilità ottimale, i writer di driver devono aspettarsi che qualsiasi numero di caratteri venga passato a questa funzione, mentre i writer di applicazioni sono consigliati per usare sempre un conteggio pari.

TextLength2Ptr
[Output] Puntatore a un buffer in cui restituire il numero totale di caratteri (esclusa la terminazione Null) disponibile per la restituzione in *OutStatementText. Se il numero di caratteri disponibili per la restituzione è maggiore o uguale a BufferLength, la stringa SQL tradotta in *OutStatementText viene troncata in BufferLength meno la lunghezza di un carattere di terminazione Null.

Resi

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnostica

Quando SQLNativeSql restituisce SQL_ERROR o SQL_SUCCESS_WITH_INFO, è possibile ottenere un valore SQLSTATE associato chiamando SQLGetDiagRec con handleTypedi SQL_HANDLE_DBC e handle di ConnectionHandle. La tabella seguente elenca i valori SQLSTATE comunemente restituiti da SQLNativeSql e ne spiega ognuno nel contesto di questa funzione. La notazione "(DM)" precede le descrizioni di SQLSTATEs restituite da Gestione driver. Il codice restituito associato a ogni valore SQLSTATE è SQL_ERROR, a meno che non sia specificato diversamente.

SQLSTATE	Errore	Descrizione
01000	Avviso generale	Messaggio informativo specifico del driver. (La funzione restituisce SQL_SUCCESS_WITH_INFO.
01004	Dati stringa, troncati a destra	Il buffer *OutStatementText non è sufficientemente grande da restituire l'intera stringa SQL, quindi la stringa SQL è stata troncata. La lunghezza della stringa SQL non troncata viene restituita in *TextLength2Ptr. (La funzione restituisce SQL_SUCCESS_WITH_INFO.
08003	Connessione non aperta	ConnectionHandle non era in uno stato connesso.
08S01	Errore del collegamento di comunicazione	Collegamento di comunicazione tra il driver e l'origine dati a cui è stato connesso il driver non è riuscito prima del completamento dell'elaborazione della funzione.
22007	Formato datetime non valido	*InStatementText contiene una clausola di escape con un valore di data, ora o timestamp non valido.
24000	Stato del cursore non valido	Il cursore a cui si fa riferimento nell'istruzione è stato posizionato prima dell'inizio del set di risultati o dopo la fine del set di risultati. Questo errore potrebbe non essere restituito da un driver con un'implementazione nativa del cursore DBMS.
HY000	Errore generale:	Si è verificato un errore per il quale non è stato specificato SQLSTATE e per il quale non è stato definito alcun SQLSTATE specifico dell'implementazione. Il messaggio di errore restituito da SQLGetDiagRec nel buffer *MessageText descrive l'errore e la relativa causa.
HY001	Errore di allocazione della memoria	Il driver non è riuscito ad allocare memoria necessaria per supportare l'esecuzione o il completamento della funzione.
HY009	Uso non valido del puntatore Null	(DM) *InStatementText era un puntatore Null.
HY010	Errore della sequenza di funzioni	(DM) È stata chiamata una funzione in esecuzione asincrona per ConnectionHandle ed era ancora in esecuzione quando questa funzione è stata chiamata.
HY013	Errore di gestione della memoria	Impossibile elaborare la chiamata di funzione perché non è stato possibile accedere agli oggetti di memoria sottostanti, probabilmente a causa di condizioni di memoria insufficiente.
HY090	Lunghezza della stringa o del buffer non valida	(DM) L'argomento TextLength1 era minore di 0, ma non uguale a SQL_NTS.
		(DM) L'argomento BufferLength era minore di 0 e l'argomento OutStatementText non era un puntatore Null.
HY109	Posizione del cursore non valida	La riga corrente del cursore è stata eliminata o non è stata recuperata. Questo errore potrebbe non essere restituito da un driver con un'implementazione nativa del cursore DBMS.
HY117	La connessione viene sospesa a causa dello stato sconosciuto della transazione. Sono consentite solo funzioni disconnesse e di sola lettura.	(DM) Per altre informazioni sullo stato sospeso, vedere Funzione SQLEndTran.
HYT01	Il timeout della connessione è scaduto	Periodo di timeout della connessione scaduto prima che l'origine dati rispondesse alla richiesta. Il periodo di timeout della connessione viene impostato tramite SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Il driver non supporta questa funzione	(DM) Il driver associato a ConnectionHandle non supporta la funzione.

Commenti

Di seguito sono riportati esempi di ciò che SQLNativeSql potrebbe restituire per la stringa SQL di input seguente contenente la funzione scalare CONVERT. Si supponga che l'empid della colonna sia di tipo INTEGER nell'origine dati:

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

Un driver per Microsoft SQL Server potrebbe restituire la stringa SQL tradotta seguente:

SELECT convert (smallint, empid) FROM employee  

Un driver per ORACLE Server potrebbe restituire la stringa SQL tradotta seguente:

SELECT to_number (empid) FROM employee  

Un driver per in ingresso potrebbe restituire la stringa SQL tradotta seguente:

SELECT int2 (empid) FROM employee  

Per altre informazioni, vedere Esecuzione diretta ed esecuzione preparata.

Funzioni correlate

Nessuno.

Vedi anche

Riferimento API ODBC
File di intestazione ODBC