Données de type Long, et SQLSetPos et SQLBulkOperations

  • Article

Comme c’est le cas avec des paramètres dans des instructions SQL, des données longues peuvent être envoyées lors de la mise à jour de lignes avec SQLBulkOperations ou SQLSetPos ou lors de l’insertion de lignes avec SQLBulkOperations. Les données sont envoyées en parties, avec plusieurs appels à SQLPutData. Les colonnes pour lesquelles les données sont envoyées au moment de l’exécution sont appelées colonnes data-at-execution.

Remarque

Une application peut en fait envoyer n’importe quel type de données au moment de l’exécution avec SQLPutData, bien que seules les données caractères et binaires puissent être envoyées en parties. Toutefois, si les données sont suffisamment petites pour s’adapter à une seule mémoire tampon, il n’existe généralement aucune raison d’utiliser SQLPutData. Il est beaucoup plus facile de lier la mémoire tampon et de laisser le pilote récupérer les données à partir de la mémoire tampon.

Étant donné que les colonnes de données longues ne sont généralement pas liées, l’application doit lier la colonne avant d’appeler SQLBulkOperations ou SQLSetPos et la dissocier après avoir appelé SQLBulkOperations ou SQLSetPos. La colonne doit être liée, car SQLBulkOperations ou SQLSetPos fonctionne uniquement sur des colonnes liées et doit être indépendante afin que SQLGetData puisse être utilisé pour récupérer des données de la colonne.

Pour envoyer des données au moment de l’exécution, l’application effectue les opérations suivantes :

  1. Place une valeur 32 bits dans la mémoire tampon d’ensemble de lignes au lieu d’une valeur de données. Cette valeur est retournée ultérieurement à l’application. L’application doit donc la définir sur une valeur significative, telle que le nombre de la colonne ou le handle d’un fichier contenant des données.

  2. Définit la valeur de la mémoire tampon longueur/indicateur sur le résultat de la macro SQL_LEN_DATA_AT_EXEC(length). Cette valeur indique au pilote que les données du paramètre seront envoyées avec SQLPutData. La valeur de longueur est utilisée lors de l’envoi de données longues à une source de données qui doit savoir combien d’octets de données longues seront envoyés afin qu’elles puissent préallouer l’espace. Pour déterminer si une source de données nécessite cette valeur, l’application appelle SQLGetInfo avec l’option SQL_NEED_LONG_DATA_LEN. Tous les pilotes doivent prendre en charge cette macro ; si la source de données ne nécessite pas la longueur d’octet, le pilote peut l’ignorer.

  3. Appelle SQLBulkOperations ou SQLSetPos. Le pilote découvre qu’une mémoire tampon de longueur/indicateur contient le résultat de la macro SQL_LEN_DATA_AT_EXEC(length) et retourne SQL_NEED_DATA comme valeur de retour de la fonction.

  4. Appelle SQLParamData en réponse à la valeur de retour SQL_NEED_DATA. Si des données longues doivent être envoyées, SQLParamData retourne SQL_NEED_DATA. Dans la mémoire tampon pointée par l’argument ValuePtrPtr , le pilote retourne la valeur unique que l’application a placée dans la mémoire tampon de l’ensemble de lignes. S’il existe plusieurs colonnes de données au niveau de l’exécution, l’application utilise cette valeur pour déterminer la colonne pour laquelle envoyer des données ; le pilote n’est pas nécessaire pour demander des données pour les colonnes de données au niveau de l’exécution dans un ordre particulier.

  5. Appelle SQLPutData pour envoyer les données de colonne au pilote. Si les données de colonne ne tiennent pas dans une mémoire tampon unique, comme c’est souvent le cas avec des données longues, l’application appelle SQLPutData à plusieurs reprises pour envoyer les données en parties ; il est à la source de données et au pilote pour réassembler les données. Si l’application transmet des données de chaîne terminées par null, le pilote ou la source de données doit supprimer le caractère d’arrêt null dans le cadre du processus de réassemblage.

  6. Appelle à nouveau SQLParamData pour indiquer qu’il a envoyé toutes les données de la colonne. S’il existe des colonnes de données au niveau de l’exécution pour lesquelles les données n’ont pas été envoyées, le pilote retourne SQL_NEED_DATA et la valeur unique de la colonne suivante data-at-execution ; l’application retourne à l’étape 5. Si des données ont été envoyées pour toutes les colonnes de données à l’exécution, les données de la ligne sont envoyées à la source de données. SQLParamData retourne ensuite SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO et peut retourner n’importe quel SQLSTATE que SQLBulkOperations ou SQLSetPos peut retourner.

Une fois QUE SQLBulkOperations ou SQLSetPos retourne SQL_NEED_DATA et avant que les données n’ont été complètement envoyées pour la dernière colonne de données à l’exécution, l’instruction est dans un état de données besoin. Dans cet état, l’application peut appeler uniquement SQLPutData, SQLParamData, SQLCancel, SQLGetDiagField ou SQLGetDiagRec ; toutes les autres fonctions retournent SQLSTATE HY010 (erreur de séquence de fonction). L’appel de SQLCancel annule l’exécution de l’instruction et le retourne à son état précédent. Pour plus d’informations, consultez l’annexe B : Tables de transition d’état ODBC.