Annexe B : Tableaux des transitions d’état ODBC

Les tableaux de cette annexe montrent comment les fonctions ODBC provoquent des transitions des états d’environnement, de connexion, d’instruction et de descripteur. L’état de l’environnement, de la connexion, de l’instruction ou du descripteur détermine généralement quand les fonctions qui utilisent le type de handle correspondant (environnement, connexion, instruction ou descripteur) peuvent être appelées. Les états d’environnement, de connexion, d’instruction et de descripteur se chevauchent approximativement, comme illustré dans les illustrations suivantes. Par exemple, le chevauchement exact des états de connexion C5 et C6 et des états d’instruction S1 à S12 dépend de la source de données, car les transactions commencent à des moments différents sur différentes sources de données, et l’état du descripteur D1i (descripteur implicitement alloué) dépend de l’état de l’instruction à laquelle le descripteur est associé, tandis que l’état D1e (descripteur explicitement alloué) est indépendant de l’état d’une instruction. Pour obtenir une description de chaque état, consultez Transitions d’environnement, Transitions de connexion, Transitions d’instruction et Transitions de descripteur, plus loin dans cette annexe.

L’environnement et les états de connexion se chevauchent comme suit :

Les états de connexion et d’instruction se chevauchent comme suit :

Les états de l’instruction et du descripteur se chevauchent comme suit :

Les états de connexion et de descripteur se chevauchent comme suit :

Chaque entrée d’une table de transition peut être l’une des valeurs suivantes :

• -- -L’état est inchangé après l’exécution de la fonction.

• E

  n , C_n_, S_n_ ou D_n_ : l’état de l’environnement, de la connexion, de l’instruction ou du descripteur passe à l’état spécifié.

• (IH) : un handle non valide a été passé à la fonction. Si le handle était un handle null ou s’il s’agissait d’un handle valide du type incorrect (par exemple, un handle de connexion a été passé lorsqu’un handle d’instruction était requis), la fonction retourne SQL_INVALID_HANDLE ; sinon, le comportement n’est pas défini et probablement fatal. Cette erreur s’affiche uniquement lorsqu’il s’agit du seul résultat possible de l’appel de la fonction dans l’état spécifié. Cette erreur ne modifie pas l’état et est toujours détectée par le Gestionnaire de pilotes, comme indiqué par les parenthèses.

• NS - État suivant. La transition d’instruction est la même que si l’instruction n’avait pas traversé les états asynchrones. Par exemple, supposons qu’une instruction qui crée un jeu de résultats entre dans l’état S11, car SQLExecDirect a retourné SQL_STILL_EXECUTING. La notation NS dans l’état S11 signifie que les transitions de l’instruction sont les mêmes que celles d’une instruction à l’état S1 qui crée un jeu de résultats. Si SQLExecDirect retourne une erreur, l’instruction reste à l’état S1 ; si elle réussit, l’instruction passe à l’état S5 ; si elle a besoin de données, l’instruction passe à l’état S8 ; et s’il est toujours en cours d’exécution, il reste à l’état S11.

• XXXXX ou (XXXXX) : SQLSTATE lié à la table de transition ; LES SQLSTATEs détectés par le Gestionnaire de pilotes sont placés entre parenthèses. La fonction a retourné SQL_ERROR et le SQLSTATE spécifié, mais l’état ne change pas. Par exemple, si SQLExecute est appelé avant SQLPrepare, il retourne SQLSTATE HY010 (erreur de séquence de fonction).

Notes

Les tables n’affichent pas d’erreurs sans rapport avec les tables de transition qui ne modifient pas l’état. Par exemple, lorsque SQLAllocHandle est appelé à l’état d’environnement E1 et retourne SQLSTATE HY001 (erreur d’allocation de mémoire), l’environnement reste à l’état E1 ; cela n’est pas indiqué dans la table de transition d’environnement pour SQLAllocHandle.

Si l’environnement, la connexion, l’instruction ou le descripteur peut passer à plusieurs états, chaque état possible est affiché et une ou plusieurs notes de bas de page expliquent les conditions dans lesquelles chaque transition a lieu. Les notes de bas de page suivantes peuvent apparaître dans n’importe quel tableau.

Note	Signification
b	Avant ou après. Le curseur a été positionné avant le début du jeu de résultats ou après la fin du jeu de résultats.
c	Fonction actuelle. La fonction actuelle s’exécute de manière asynchrone.
d	Vous avez besoin de données. La fonction a retourné SQL_NEED_DATA.
e	Erreur. La fonction a retourné SQL_ERROR.
i	Ligne non valide. Le curseur a été positionné sur une ligne du jeu de résultats et la ligne a été supprimée ou une erreur s’est produite lors d’une opération sur la ligne. Si le tableau d’état des lignes existait, la valeur dans le tableau d’état des lignes pour la ligne était SQL_ROW_DELETED ou SQL_ROW_ERROR. (Le tableau d’état des lignes est pointé vers l’attribut d’instruction SQL_ATTR_ROW_STATUS_PTR.)
nf	Introuvable. La fonction a retourné SQL_NO_DATA. Cela ne s’applique pas lorsque SQLExecDirect, SQLExecute ou SQLParamData retourne SQL_NO_DATA après l’exécution d’une instruction de mise à jour ou de suppression recherchée.
np	Non préparé. L’instruction n’a pas été préparée.
nr	Aucun résultat. L’instruction n’a pas créé ou n’a pas créé de jeu de résultats.
o	Autre fonction. Une autre fonction s’exécutait de manière asynchrone.
p	Préparé. L’instruction a été préparée.
r	Résultats. L’instruction crée ou a créé un jeu de résultats (éventuellement vide).
s	Réussite. La fonction retournée SQL_SUCCESS_WITH_INFO ou SQL_SUCCESS.
v	Ligne valide. Le curseur a été positionné sur une ligne du jeu de résultats, et la ligne a été correctement insérée, correctement mise à jour, ou une autre opération sur la ligne a été effectuée avec succès. Si le tableau d’état des lignes existait, la valeur dans le tableau d’état des lignes pour la ligne était SQL_ROW_ADDED, SQL_ROW_SUCCESS ou SQL_ROW_UPDATED. (Le tableau d’état des lignes est pointé vers l’attribut d’instruction SQL_ATTR_ROW_STATUS_PTR.)
x	En cours d'exécution. La fonction a retourné SQL_STILL_EXECUTING.

SQLFreeHandle

Dans cet exemple, la ligne de la table de transition d’état de l’environnement pour SQLFreeHandle lorsque HandleType est SQL_HANDLE_ENV est la suivante.

E0 Non alloué	E1 Allocated	E2 Connexion
(IH)	E0	(HY010)

Si SQLFreeHandle est appelé dans l’état d’environnement E0 avec HandleType défini sur SQL_HANDLE_ENV, le Gestionnaire de pilotes retourne SQL_INVALID_HANDLE. S’il est appelé à l’état E1 avec HandleType défini sur SQL_HANDLE_ENV, l’environnement passe à l’état E0 si la fonction réussit et reste à l’état E1 si la fonction échoue. S’il est appelé dans l’état E2 avec HandleType défini sur SQL_HANDLE_ENV, le Gestionnaire de pilotes retourne toujours SQL_ERROR et SQLSTATE HY010 (erreur de séquence de fonction) et l’environnement reste à l’état E2.

Pour comprendre les tables de transition d’état, il est nécessaire de comprendre à quel élément (environnement, connexion, instruction ou descripteur) elles font référence. Supposons qu’une fonction accepte le handle d’un élément de type X. La table de transition d’état X pour cette fonction décrit comment l’appel de la fonction, avec le handle d’un élément de type X, affecte cet élément. Par exemple, SQLDisconnect accepte un handle de connexion. La table de transition de l’état de connexion pour SQLDisconnect décrit comment SQLDisconnect affecte l’état de la connexion pour laquelle il est appelé.

Supposons qu’une fonction accepte le handle d’un élément de type Y, où Y n’est pas égal à X. La table de transition d’état X pour cette fonction décrit comment l’appel de la fonction, avec un handle de type X associé à l’élément de type Y, affecte l’élément de type Y. Par exemple, la table de transition d’état d’instruction pour SQLDisconnect décrit comment SQLDisconnect affecte l’état d’une instruction lorsqu’elle est appelée avec le handle de la connexion à laquelle l’instruction est associée.

Cette annexe contient les rubriques suivantes.

• Transitions d’environnement

• Transitions de connexion

• Transitions d’instruction

• Transitions de descripteur