SQLSetCursorName, fonction

Conformité
Version introduite : Conformité aux normes ODBC 1.0 : ISO 92

Résumé
SQLSetCursorName associe un nom de curseur à une instruction active. Si une application n’appelle pas SQLSetCursorName, le pilote génère des noms de curseurs si nécessaire pour le traitement des instructions SQL.

Syntaxe

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

Arguments

StatementHandle
[Entrée] Handle d’instruction.

CursorName
[Entrée] Nom du curseur. Pour un traitement efficace, le nom du curseur ne doit pas inclure d’espaces de début ou de fin dans le nom du curseur et si le nom du curseur inclut un identificateur délimité, le délimiteur doit être positionné comme premier caractère dans le nom du curseur.

NameLength
[Entrée] Longueur en caractères de *CursorName.

Retours

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

Lorsque SQLSetCursorName retourne SQL_ERROR ou SQL_SUCCESS_WITH_INFO, une valeur SQLSTATE associée peut être obtenue en appelant SQLGetDiagRec avec un HandleType de SQL_HANDLE_STMT et un Handle of StatementHandle. Le tableau suivant répertorie les valeurs SQLSTATE couramment retournées par SQLSetCursorName et explique chacune d’elles dans le contexte de cette fonction ; la notation « (DM) » précède les descriptions de SQLSTATEs retournées par le Gestionnaire de pilotes. Le code de retour associé à chaque valeur SQLSTATE est SQL_ERROR, sauf indication contraire.

Commentaires

Les noms de curseurs sont utilisés uniquement dans les instructions de mise à jour et de suppression positionnées (par exemple, update table-name ...WHERE CURRENT OF cursor-name). Pour plus d’informations, consultez Instructions de mise à jour et de suppression positionnées. Si l’application n’appelle pas SQLSetCursorName pour définir un nom de curseur, lors de l’exécution d’une instruction de requête, le pilote génère un nom qui commence par les lettres SQL_CUR et ne dépasse pas 18 caractères de longueur.

Tous les noms de curseurs au sein de la connexion doivent être uniques. La longueur maximale d’un nom de curseur est définie par le pilote. Pour une interopérabilité maximale, il est recommandé que les applications limitent les noms de curseurs à plus de 18 caractères. Dans ODBC 3*.x*, si un nom de curseur est un identificateur entre guillemets, il est traité de manière sensible à la casse et peut contenir des caractères que la syntaxe de SQL n’autorise pas ou ne traiterait pas spécialement, comme des espaces ou des mots clés réservés. Si un nom de curseur doit être traité de manière sensible à la casse, il doit être transmis en tant qu’identificateur entre guillemets.

Un nom de curseur défini explicitement ou implicitement reste défini jusqu’à ce que l’instruction associée soit supprimée, à l’aide de SQLFreeHandle. SQLSetCursorName peut être appelé pour renommer un curseur sur une instruction tant que le curseur est dans un état alloué ou préparé.

Exemple de code

Dans l’exemple suivant, une application utilise SQLSetCursorName pour définir un nom de curseur pour une instruction. Il utilise ensuite cette instruction pour récupérer les résultats de la table CUSTOMERS. Enfin, il effectue une mise à jour positionnée pour modifier le numéro de téléphone de John Smith. Notez que l’application utilise des handles d’instructions différents pour les instructions SELECT et UPDATE .

Pour obtenir un autre exemple de code, consultez 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);  
}  

Fonctions connexes

Voir aussi

Informations de référence sur l’API ODBC
Fichiers d’en-tête ODBC