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.
Valori restituiti
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 handleType di 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, UPDATE table-name ...WHERE CURRENT OF cursor-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 handleType di 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 |