Funzione SQLSetCursorName

  • Articolo

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.

Resi

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 handleTypedi 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, 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, 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);  
}
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

Vedi anche

Riferimento API ODBC
File di intestazione ODBC