Funzione SQLSetCursorName
Conformità
Versione introdotta: Conformità agli standard ODBC 1.0: ISO 92
Riepilogo
SQLSetCursorName associa un nome di cursore a un'istruzione attiva. Se un'applicazione non chiama SQLSetCursorName, il driver genera nomi di cursore in base alle esigenze per l'elaborazione dell'istruzione SQL.
Sintassi
SQLRETURN SQLSetCursorName(
SQLHSTMT StatementHandle,
SQLCHAR * CursorName,
SQLSMALLINT NameLength);
Argomenti
StatementHandle
[Input] Handle di istruzione.
CursorName
[Input] Nome cursore. Per un'elaborazione efficiente, il nome del cursore non deve includere spazi iniziali o finali nel nome del cursore e se il nome del cursore include un identificatore delimitato, il delimitatore deve essere posizionato come primo carattere nel nome del cursore.
NameLength
[Input] Lunghezza in caratteri di *CursorName.
Valori restituiti
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR o SQL_INVALID_HANDLE.
Diagnostica
Quando SQLSetCursorName 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 SQLSetCursorName e spiega ognuno di essi 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 nome del cursore ha superato il limite massimo, quindi è stato usato solo il numero massimo consentito di caratteri. |
| 24000 | Stato del cursore non valido | L'istruzione corrispondente a StatementHandle era già in uno stato eseguito o posizionato nel cursore. |
| 34000 | Nome di cursore non valido | Il nome del cursore specificato in *CursorName non è valido perché ha superato la lunghezza massima definita dal driver oppure ha iniziato con "SQLCUR" o "SQL_CUR". |
| 3C000 | Nome cursore duplicato | Il nome del cursore specificato in *CursorName esiste già. |
| 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) L'argomento CursorName è un puntatore Null. |
| HY010 | Errore della sequenza di funzioni | (DM) È stata chiamata una funzione in esecuzione asincrona per l'handle di connessione associato a StatementHandle. Questa funzione aynchronous era ancora in esecuzione quando è stata chiamata la funzione SQLSetCursorName . (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. |
| HY090 | Lunghezza della stringa o del buffer non valida | (DM) L'argomento NameLength era minore di 0 ma non uguale a SQL_NTS. |
| 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, durante l'esecuzione di un'istruzione di query il driver genera un nome che inizia con le lettere SQL_CUR e non supera i 18 caratteri di lunghezza.
Tutti i nomi di cursore all'interno della connessione devono essere univoci. La lunghezza massima di un nome di cursore viene definita dal driver. Per garantire la massima interoperabilità, è consigliabile che le applicazioni limitino i nomi dei cursori a non più di 18 caratteri. In ODBC 3*.x*, se un nome di cursore è un identificatore tra virgolette, viene trattato in modo con distinzione tra maiuscole e minuscole e può contenere caratteri che la sintassi di SQL non consente o considera in modo speciale, ad esempio spazi vuoti o parole chiave riservate. Se un nome di cursore deve essere trattato in modo con distinzione tra maiuscole e minuscole, deve essere passato come identificatore tra virgolette.
Un nome di cursore impostato in modo esplicito o implicito rimane impostato fino a quando non viene eliminata l'istruzione con cui è associata, usando SQLFreeHandle. È possibile chiamare SQLSetCursorName per rinominare un cursore su un'istruzione, purché il cursore si trova in uno stato allocato o preparato.
Esempio di codice
Nell'esempio seguente un'applicazione usa SQLSetCursorName per impostare un nome di cursore per un'istruzione . Usa quindi tale istruzione per recuperare i risultati dalla tabella CUSTOMERS. Infine, esegue un aggiornamento posizionato per modificare il numero di telefono di John Smith. Si noti che l'applicazione usa handle di istruzione diversi per le istruzioni SELECT e UPDATE .
Per un altro esempio di codice, vedere SQLSetPos.
#define NAME_LEN 50
#define PHONE_LEN 10
SQLHSTMT hstmtSelect,
SQLHSTMT hstmtUpdate;
SQLRETURN retcode;
SQLHDBC hdbc;
SQLCHAR szName[NAME_LEN], szPhone[PHONE_LEN];
SQLINTEGER cbName, cbPhone;
/* Allocate the statements and set the cursor name. */
SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmtSelect);
SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmtUpdate);
SQLSetCursorName(hstmtSelect, "C1", SQL_NTS);
/* SELECT the result set and bind its columns to local buffers. */
SQLExecDirect(hstmtSelect,
"SELECT NAME, PHONE FROM CUSTOMERS",
SQL_NTS);
SQLBindCol(hstmtSelect, 1, SQL_C_CHAR, szName, NAME_LEN, &cbName);
SQLBindCol(hstmtSelect, 2, SQL_C_CHAR, szPhone, PHONE_LEN, &cbPhone);
/* Read through the result set until the cursor is */
/* positioned on the row for John Smith. */
do
retcode = SQLFetch(hstmtSelect);
while ((retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) &&
(strcmp(szName, "Smith, John") != 0));
/* Perform a positioned update of John Smith's name. */
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
SQLExecDirect(hstmtUpdate,
"UPDATE EMPLOYEE SET PHONE=\"2064890154\" WHERE CURRENT OF C1",
SQL_NTS);
}
Funzioni correlate
| Per informazioni su | Vedere |
|---|---|
| Esecuzione di un'istruzione SQL | Funzione SQLExecDirect |
| Esecuzione di un'istruzione SQL preparata | Funzione SQLExecute |
| Restituzione di un nome di cursore | Funzione SQLGetCursorName |
| Impostazione delle opzioni di scorrimento del cursore | Funzione SQLSetScrollOptions |