SQLCompleteAsync, fonction
Conformité
Version introduite : Conformité aux normes ODBC 3.8 : Aucune
Résumé
SQLCompleteAsync peut être utilisé pour déterminer quand une fonction asynchrone est terminée à l’aide d’un traitement basé sur la notification ou l’interrogation. Pour plus d’informations sur les opérations asynchrones, consultez Exécution asynchrone.
SQLCompleteAsync est implémenté uniquement dans le Gestionnaire de pilotes ODBC.
En mode de traitement asynchrone basé sur la notification, SQLCompleteAsync doit être appelé après que driver Manager déclenche l’objet d’événement utilisé pour la notification. SQLCompleteAsync termine le traitement asynchrone et la fonction asynchrone génère un code de retour.
En mode de traitement asynchrone basé sur l’interrogation, SQLCompleteAsync est une alternative à l’appel de la fonction asynchrone d’origine, sans avoir à spécifier les arguments dans l’appel de fonction asynchrone d’origine. SQLCompleteAsync peut être utilisé, que la bibliothèque de curseurs ODBC soit activée ou non.
Syntaxe
SQLRETURN SQLCompleteAsync(
SQLSMALLINT HandleType,
SQLHANDLE Handle,
RETCODE * AsyncRetCodePtr);
Arguments
HandleType
[Entrée] Type du handle sur lequel effectuer le traitement asynchrone. Les valeurs valides sont SQL_HANDLE_DBC ou SQL_HANDLE_STMT.
Handle
[Entrée] Handle sur lequel effectuer le traitement asynchrone. Si Handle n’est pas un handle valide du type spécifié par HandleType, SQLCompleteAsync retourne SQL_INVALID_HANDLE.
Si Handle n’est pas un handle valide du type spécifié par HandleType, SQLCompleteAsync retourne SQL_INVALID_HANDLE.
AsyncRetCodePtr
[Sortie] Pointeur vers une mémoire tampon qui contiendra le code de retour de l’API asynchrone. Si AsyncRetCodePtr a la valeur NULL, SQLCompleteAsync retourne SQL_ERROR.
Retours
SQL_SUCCESS, SQL_ERROR, SQL_NO_DATA ou SQL_INVALID_HANDLE.
Diagnostics
Si SQLCompleteAsync retourne SQL_SUCCESS, une application doit obtenir le code de retour de la fonction asynchrone à partir de la mémoire tampon pointée par AsyncRetCodePtr. Le SQLSTATE associé, le cas échéant, peut être obtenu en appelant SQLGetDiagRec avec un HandleType de SQL_HANDLE_STMT et un handle d’instruction ou un HandleType de SQL_HANDLE_DBC et un handle de connexion. Ces enregistrements de diagnostic sont associés à la fonction asynchrone, et non à cette fonction SQLCompleteAsync .
SQLCompleteAsync retourne un code autre que SQL_SUCCESS pour indiquer que SQLCompleteAsync n’est pas appelé correctement. SQLCompleteAsync ne publie aucun enregistrement de diagnostic dans ce cas. Les codes de retour possibles sont les suivants :
SQL_INVALID_HANDLE : le handle indiqué par HandleType et Handle n’est pas un handle valide.
SQL_ERROR : AsyncRetCodePtr a la valeur NULL ou le traitement asynchrone n’est pas activé sur le handle.
SQL_NO_DATA : en mode notification, une opération asynchrone n’est pas en cours ou le Gestionnaire de pilotes n’a pas averti l’application. En mode interrogation, une opération asynchrone n’est pas en cours.
Commentaires
En mode de traitement asynchrone basé sur l’interrogation, AsyncRetCodePtr peut être SQL_STILL_EXECUTING lorsque SQLCompleteAsync retourne SQL_SUCCESS. L’application doit continuer à interroger jusqu’à ce qu’AsyncRetCodePtr ne soit pas SQL_STILL_EXECUTING. En mode de traitement asynchrone basé sur la notification, AsyncRetCodePtr ne sera jamais SQL_STILL_EXECUTING.