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 en fonction des besoins 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 renvoie 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 de 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.
SQLSTATE | Error | Description |
---|---|---|
01000 | Avertissement général | Message d’information spécifique au pilote. (La fonction retourne SQL_SUCCESS_WITH_INFO.) |
01004 | Données de chaîne, tronquées à droite | Le nom du curseur ayant dépassé la limite maximale, seul le nombre maximal autorisé de caractères a été utilisé. |
24 000 | État de curseur non valide | L’instruction correspondant à StatementHandle était déjà dans un état exécuté ou positionné au curseur. |
34000 | Nom de curseur non valide | Le nom du curseur spécifié dans *CursorName n’était pas valide, car il a dépassé la longueur maximale définie par le pilote, ou il a commencé par « SQLCUR » ou « SQL_CUR ». |
3C000 | Nom du curseur en double | Le nom du curseur spécifié dans *CursorName existe déjà. |
HY000 | Erreur générale | Une erreur s’est produite pour laquelle il n’y avait pas de SQLSTATE spécifique et pour laquelle aucun SQLSTATE spécifique à l’implémentation n’a été défini. Le message d’erreur retourné par SQLGetDiagRec dans la mémoire tampon *MessageText décrit l’erreur et sa cause. |
HY001 | Erreur d’allocation de mémoire | Le pilote n’a pas pu allouer la mémoire nécessaire pour prendre en charge l’exécution ou l’achèvement de la fonction. |
HY009 | Utilisation non valide du pointeur Null | (DM) L’argument CursorName était un pointeur null. |
HY010 | Erreur de séquence de fonction | (DM) Une fonction en exécution asynchrone a été appelée pour le handle de connexion associé à l’InstructionHandle. Cette fonction aynchronous était toujours en cours d’exécution lorsque la fonction SQLSetCursorName a été appelée. (DM) Une fonction en cours d’exécution asynchrone a été appelée pour l’InstructionHandle et était toujours en cours d’exécution lorsque cette fonction a été appelée. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos a été appelé pour l’InstructionHandle et a retourné SQL_NEED_DATA. Cette fonction a été appelée avant l’envoi des données pour toutes les colonnes ou paramètres de données au moment de l’exécution. |
HY013 | Erreur de gestion de la mémoire | L’appel de fonction n’a pas pu être traité, car les objets de mémoire sous-jacents n’ont pas pu être accessibles, peut-être en raison de conditions de mémoire insuffisantes. |
HY090 | Chaîne ou longueur de mémoire tampon non valide | (DM) L’argument NameLength était inférieur à 0, mais pas égal à SQL_NTS. |
HY117 | La connexion est suspendue en raison d’un état de transaction inconnu. Seules les fonctions de déconnexion et de lecture seule sont autorisées. | (DM) Pour plus d’informations sur l’état suspendu, consultez Fonction SQLEndTran. |
HYT01 | Délai d’attente de la connexion expiré | Le délai d’expiration de la connexion a expiré avant que la source de données ne réponde à la demande. Le délai d’expiration de connexion est défini via SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
IM001 | Le pilote ne prend pas en charge cette fonction | (DM) Le pilote associé à l’InstructionHandle ne prend pas en charge la fonction . |
Commentaires
Les noms de curseurs sont utilisés uniquement dans les instructions de mise à jour et de suppression positionnées (par exemple, UPDATEtable-name ... WHERE CURRENT OFcursor-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.
Tous les noms de curseur dans 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é aux applications de limiter les noms de curseurs à 18 caractères maximum. Dans ODBC 3*.x*, si un nom de curseur est un identificateur entre guillemets, il est traité de manière sensible à la casse et il peut contenir des caractères que la syntaxe sql n’autorise pas ou traiterait spécialement, tels que des vides ou des mots clés réservés. Si un nom de curseur doit être traité en respectant la casse, il doit être passé en tant qu’identificateur entre guillemets.
Un nom de curseur défini explicitement ou implicitement reste défini jusqu’à ce que l’instruction à laquelle il est associé 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 descripteurs 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
Pour obtenir des informations sur | Consultez |
---|---|
Exécution d’une instruction SQL | SQLExecDirect, fonction |
Exécution d’une instruction SQL préparée | SQLExecute, fonction |
Retour d’un nom de curseur | SQLGetCursorName Function |
Définition des options de défilement du curseur | SQLSetScrollOptions, fonction |
Voir aussi
Informations de référence sur l’API ODBC
Fichiers d’en-tête ODBC
Commentaires
https://aka.ms/ContentUserFeedback.
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultezEnvoyer et afficher des commentaires pour