SQLGetCursorName Function

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

Résumé
SQLGetCursorName retourne le nom de curseur associé à une instruction spécifiée.

Syntaxe

  
SQLRETURN SQLGetCursorName(  
     SQLHSTMT        StatementHandle,  
     SQLCHAR *       CursorName,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   NameLengthPtr);  

Arguments

StatementHandle
[Entrée] Handle d’instruction.

CursorName
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner le nom du curseur.

Si CursorName a la valeur NULL, NameLengthPtr retourne toujours le nombre total de caractères (à l’exclusion du caractère d’arrêt Null pour les données de caractères) pouvant être retournés dans la mémoire tampon vers laquelle cursorName pointe.

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

NameLengthPtr
[Sortie] Pointeur vers la mémoire dans laquelle retourner le nombre total de caractères (à l’exception du caractère d’arrêt null) disponibles à retourner dans *CursorName. Si le nombre de caractères disponibles à retourner est supérieur ou égal à BufferLength, le nom du curseur dans *CursorName est tronqué en BufferLength moins la longueur d’un caractère d’arrêt Null.

Retours

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

Lorsque SQLGetCursorName 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 de StatementHandle. Le tableau suivant répertorie les valeurs SQLSTATE couramment retournées par SQLGetCursorName 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	La mémoire tampon *CursorName n’étant pas assez grande pour renvoyer le nom du curseur entier, le nom du curseur a été tronqué. La longueur du nom du curseur nontrudé est retournée dans *NameLengthPtr. (La fonction retourne SQL_SUCCESS_WITH_INFO.)
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.
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 asynchrone était toujours en cours d’exécution lorsque la fonction SQLGetCursorName a été appelée. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults a été appelé pour l’InstructionHandle et a retourné SQL_PARAM_DATA_AVAILABLE. Cette fonction a été appelée avant la récupération des données pour tous les paramètres diffusés en continu. (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.
HY015	Aucun nom de curseur disponible	(DM) Le pilote était un pilote ODBC 2*.x*, il n’y avait pas de curseur ouvert sur l’instruction et aucun nom de curseur n’avait été défini avec SQLSetCursorName.
HY090	Chaîne ou longueur de mémoire tampon non valide	(DM) La valeur spécifiée dans l’argument BufferLength était inférieure à 0.
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, le pilote génère un nom. Ce nom commence par les lettres SQL_CUR.

Notes

Dans ODBC 2*.x*, lorsqu’il n’y avait pas de curseur ouvert et qu’aucun nom n’avait été défini par un appel à SQLSetCursorName, un appel à SQLGetCursorName renvoyait SQLSTATE HY015 (aucun nom de curseur disponible). Dans ODBC 3*.x*, cela n’est plus vrai ; quel que soit le moment où SQLGetCursorName est appelé, le pilote retourne le nom du curseur.

SQLGetCursorName retourne le nom d’un curseur, que le nom ait été créé explicitement ou implicitement. Un nom de curseur est généré implicitement si SQLSetCursorName n’est pas appelé. SQLSetCursorName peut être appelé pour renommer un curseur sur une instruction tant que le curseur est dans un état alloué ou préparé.

Un nom de curseur défini explicitement ou implicitement reste défini jusqu’à ce que l’instruction StatementHandle à laquelle il est associé soit supprimée, à l’aide de SQLFreeHandle avec un HandleType de SQL_HANDLE_STMT.

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
Préparation d’une instruction pour l’exécution	Fonction SQLPrepare
Définition d’un nom de curseur	SQLSetCursorName, fonction

Voir aussi

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