Envoi de données de type Long

  • Article

Les SGBD définissent des données longues comme des données caractères ou binaires sur une certaine taille, par exemple 254 caractères. Il peut ne pas être possible de stocker un élément entier de données longues en mémoire, par exemple lorsque l’élément représente un document de texte long ou une bitmap. Étant donné que ces données ne peuvent pas être stockées dans une mémoire tampon unique, la source de données l’envoie au pilote dans des parties avec SQLPutData lorsque l’instruction est exécutée. Les paramètres pour lesquels les données sont envoyées au moment de l’exécution sont appelés paramètres de données à l’exécution.

Remarque

Une application peut réellement 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.

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

  1. Transmet une valeur 32 bits qui identifie le paramètre dans l’argument ParameterValuePtr dans SQLBindParameter plutôt que de passer l’adresse d’une mémoire tampon. Cette valeur n’est pas analysée par le pilote. Elle sera retournée ultérieurement à l’application. Elle doit donc signifier quelque chose à l’application. Par exemple, il peut s’agir du nombre du paramètre ou du handle d’un fichier contenant des données.

  2. Transmet l’adresse d’une mémoire tampon de longueur/indicateur dans l’argument StrLen_or_IndPtr de SQLBindParameter.

  3. Stocke SQL_DATA_AT_EXEC ou le résultat de la macro SQL_LEN_DATA_AT_EXEC(length) dans la mémoire tampon de longueur/indicateur. Ces deux valeurs indiquent au pilote que les données du paramètre seront envoyées avec SQLPutData. SQL_LEN_DATA_AT_EXEC(length) est utilisé 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.

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

  5. 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 qui identifie le paramètre data-at-execution. S’il existe plusieurs paramètres de données au moment de l’exécution, l’application doit utiliser cette valeur pour déterminer le paramètre pour lequel envoyer des données ; le pilote n’est pas nécessaire pour demander des données pour les paramètres de données au niveau de l’exécution dans un ordre particulier.

  6. Appelle SQLPutData pour envoyer les données de paramètre au pilote. Si les données de paramètre ne s’intègrent 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 dans des parties ; il est jusqu’au pilote et à la source de données 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.

  7. Appelle à nouveau SQLParamData pour indiquer qu’il a envoyé toutes les données du paramètre. S’il existe des paramètres de données au niveau de l’exécution pour lesquels les données n’ont pas été envoyées, le pilote retourne SQL_NEED_DATA et la valeur qui identifie le paramètre suivant ; l’application retourne à l’étape 6. Si des données ont été envoyées pour tous les paramètres de données au niveau de l’exécution, l’instruction est exécutée. SQLParamData retourne SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO et peut retourner n’importe quelle valeur de retour ou diagnostic que SQLExecute ou SQLExecDirect peut retourner.

Une fois QUE SQLExecute ou SQLExecDirect retourne SQL_NEED_DATA et avant que les données n’ont été entièrement envoyées pour le dernier paramètre de données au moment de l’exécution, l’instruction est dans un état de données besoin. Alors qu’une instruction est dans un état De données besoin, 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.

Pour obtenir un exemple d’envoi de données au moment de l’exécution, consultez la description de la fonction SQLPutData .