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.

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

Vedi anche

Riferimento API ODBC
File di intestazione ODBC