Funzione SQLSetCursorName

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

Summary
SQLSetCursorName associa un nome di cursore a un'istruzione attiva. Se un'applicazione non chiama SQLSetCursorName, il driver genera i nomi dei cursori in base alle esigenze per l SQL'elaborazione dell'istruzione.

Sintassi

  
SQLRETURN SQLSetCursorName(  
     SQLHSTMT      StatementHandle,  
     SQLCHAR *     CursorName,  
     SQLSMALLINT   NameLength);  

Argomenti

StatementHandle
[Input] Handle di istruzione.

CursorName
[Input] Nome del 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 *CursorName.

Restituisce

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 un HandleType di SQL_HANDLE_STMT e un Handle di StatementHandle. Nella tabella seguente sono elencati i valori SQLSTATE comunemente restituiti da SQLSetCursorName e vengono illustrati 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, se non diversamente specificato.

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, pertanto è 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 o è stato avviato con "SQLCUR" o "SQL_CUR".
3C000 Nome del cursore duplicato Il nome del cursore specificato in *CursorName esiste già.
HY000 Errore generale: Si è verificato un errore per il quale non è stato definito un SQLSTATE specifico e per il quale non è stato definito ALCUN VALORE 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 è stato in grado di allocare la memoria necessaria per supportare l'esecuzione o il completamento della funzione.
HY009 Uso non valido del puntatore Null (DM) L'argomento CursorName era 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 è stata chiamata questa funzione.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos sono stati chiamati per StatementHandle e sono stati restituiti 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 è minore di 0, ma non è uguale a SQL_NTS.
HY117 La connessione è stata sospesa a causa di uno stato di transazione sconosciuto. Sono consentite solo funzioni di disconnessione e di sola lettura. (DM) Per altre informazioni sullo stato sospeso, vedere Funzione SQLEndTran.
HYT01 Timeout della connessione scaduto Il periodo di timeout della connessione è scaduto prima che l'origine dati risponda 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 Positioned Update e Delete. Se l'applicazione non chiama SQLSetCursorName per definire un nome di cursore, all'esecuzione di un'istruzione di query il driver genera un nome che inizia con le lettere SQL_CUR e non supera i 18 caratteri.

Tutti i nomi dei cursori all'interno della connessione devono essere univoci. La lunghezza massima di un nome di cursore è definita dal driver. Per 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 con distinzione tra maiuscole e minuscole e può contenere caratteri che la sintassi di SQL non consentirebbe o tratterebbe in modo speciale, ad esempio spazi vuoti o parole chiave riservate. Se un nome di cursore deve essere considerato 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 a cui è associato, usando SQLFreeHandle. SQLSetCursorName può essere chiamato per rinominare un cursore in 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

Vedere anche

Informazioni di riferimento sulle API ODBC
File di intestazione ODBC