Funzione SQLGetCursorName

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

Riepilogo
SQLGetCursorName restituisce il nome del cursore associato a un'istruzione specificata.

Sintassi

  
SQLRETURN SQLGetCursorName(  
     SQLHSTMT        StatementHandle,  
     SQLCHAR *       CursorName,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   NameLengthPtr);  

Argomenti

StatementHandle
[Input] Handle di istruzione.

CursorName
[Output] Puntatore a un buffer in cui restituire il nome del cursore.

Se CursorName è NULL, NameLengthPtr 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 CursorName.

BufferLength
[Input] Lunghezza di *CursorName, in caratteri.

NameLengthPtr
[Output] Puntatore alla memoria in cui restituire il numero totale di caratteri (escluso il carattere di terminazione Null) disponibile per restituire in *CursorName. Se il numero di caratteri disponibili per la restituzione è maggiore o uguale a BufferLength, il nome del cursore in *CursorName viene troncato a 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 SQLGetCursorName restituisce SQL_ERROR o SQL_SUCCESS_WITH_INFO, è possibile ottenere un valore SQLSTATE associato chiamando SQLGetDiagRec con handleTypedi SQL_HANDLE_STMT e handle di StatementHandle. La tabella seguente elenca i valori SQLSTATE comunemente restituiti da SQLGetCursorName 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 *CursorName non è sufficientemente grande da restituire l'intero nome del cursore, quindi il nome del cursore è stato troncato. La lunghezza del nome del cursore non modificato viene restituita in *NameLengthPtr. (La funzione restituisce SQL_SUCCESS_WITH_INFO.
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.
HY010	Errore della sequenza di funzioni	(DM) È stata chiamata una funzione in esecuzione asincrona per l'handle di connessione associato a StatementHandle. Questa funzione asincrona era ancora in esecuzione quando è stata chiamata la funzione SQLGetCursorName . (DM) SQLExecute, SQLExecDirect o SQLMoreResults è stato chiamato per StatementHandle e restituito SQL_PARAM_DATA_AVAILABLE. Questa funzione è stata chiamata prima del recupero dei dati per tutti i parametri trasmessi. (DM) È stata chiamata una funzione in esecuzione asincrona per StatementHandle ed era ancora in esecuzione quando questa funzione è stata chiamata. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos è stato chiamato per StatementHandle e restituito SQL_NEED_DATA. Questa funzione è stata chiamata prima dell'invio dei dati per tutti i parametri o le colonne data-at-execution.
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.
HY015	Nessun nome di cursore disponibile	(DM) Il driver era un driver ODBC 2*.x*, non c'era alcun cursore aperto nell'istruzione e nessun nome del cursore era stato impostato con SQLSetCursorName.
HY090	Lunghezza della stringa o del buffer non valida	(DM) Il valore specificato nell'argomento BufferLength è minore di 0.
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 StatementHandle non supporta la funzione.

Commenti

I nomi dei cursori vengono usati solo nelle istruzioni update ed delete posizionate (ad esempio, UPDATEtable-name ...WHERE CURRENT OFcursor-name). Per altre informazioni, vedere Istruzioni di aggiornamento ed eliminazione posizionate. Se l'applicazione non chiama SQLSetCursorName per definire un nome di cursore, il driver genera un nome. Questo nome inizia con le lettere SQL_CUR.

Nota

In ODBC 2*.x*, quando non è presente alcun cursore aperto e nessun nome è stato impostato da una chiamata a SQLSetCursorName, una chiamata a SQLGetCursorName ha restituito SQLSTATE HY015 (nessun nome cursore disponibile). In ODBC 3*.x*, questo non è più vero; indipendentemente dal momento in cui viene chiamato SQLGetCursorName , il driver restituisce il nome del cursore.

SQLGetCursorName restituisce il nome di un cursore indipendentemente dal fatto che il nome sia stato creato in modo esplicito o implicito. Un nome di cursore viene generato in modo implicito se SQLSetCursorName non viene chiamato. È possibile chiamare SQLSetCursorName per rinominare un cursore su un'istruzione, purché il cursore si trova in uno stato allocato o preparato.

Un nome di cursore impostato in modo esplicito o implicito rimane impostato fino all'eliminazione di StatementHandle a cui è associato, usando SQLFreeHandle con handleTypedi SQL_HANDLE_STMT.

Funzioni correlate

Per informazioni su	Vedere
Esecuzione di un'istruzione SQL	Funzione SQLExecDirect
Esecuzione di un'istruzione SQL preparata	Funzione SQLExecute
Preparazione di un'istruzione per l'esecuzione	Funzione SQLPrepare
Impostazione di un nome di cursore	Funzione SQLSetCursorName

Vedi anche

Riferimento API ODBC
File di intestazione ODBC