Fonction SQLBindCol (CLI)-Liaison d'une colonne à une variable d'application ou à un releveur de coordonnées LOB

Spécification :

• Interface de ligne de commande 1.1
• ODBC 1.0
• Interface de ligne de commande ISO

SQLBindCol() est appelé une fois pour chaque colonne de l'ensemble de résultats que l'application doit extraire.

En général, SQLPrepare(), SQLExecDirect() ou l'une des fonctions de schéma est appelée avant cette fonction et SQLFetch(), SQLFetchScroll(), SQLBulkOperations()ou SQLSetPos() est appelé après. Des attributs de colonne peuvent également être nécessaires avant d'appeler SQLBindCol()et peuvent être obtenus à l'aide de SQLDescribeCol() ou SQLColAttribute().

Syntaxe

SQLRETURN   SQLBindCol (
               SQLHSTMT          StatementHandle,            /* hstmt */
               SQLUSMALLINT      ColumnNumber,               /* icol */
               SQLSMALLINT       TargetType,                 /* fCType */
               SQLPOINTER        TargetValuePtr,             /* rgbValue */
               SQLLEN            BufferLength,               /* cbValueMax */
               SQLLEN            *StrLen_or_IndPtr);         /* *pcbValue */

arguments de fonctions

• Pour cette fonction, TargetValuePtr et StrLen_or_IndPtr sont des sorties différées, ce qui signifie que les emplacements de stockage que ces pointeurs pointent ne sont pas mis à jour tant qu'une ligne d'ensemble de résultats n'est pas extraite. Par conséquent, les emplacements référencés par ces pointeurs doivent rester valides jusqu'à ce que SQLFetch() ou SQLFetchScroll() soit appelé. Par exemple, si SQLBindCol() est appelé dans une fonction locale, SQLFetch() doit être appelé à partir de la même portée de la fonction ou la mémoire tampon TargetValuePtr doit être allouée comme étant statique ou globale.
• L' interface de ligne de commande pourra optimiser l'extraction de données pour tous les types de données de longueur variable si TargetValuePtr est placé consécutivement en mémoire après StrLen_or_IndPtr.

Utilisation

Appelez SQLBindCol() une fois pour chaque colonne de l'ensemble de résultats pour laquelle les données ou, pour les colonnes LOB, le releveur de coordonnées LOB doivent être extraits. Lorsque SQLFetch() ou SQLFetchScroll() est appelé pour extraire des données de l'ensemble de résultats, les données de chacune des colonnes liées sont placées dans les emplacements affectés par les pointeurs TargetValuePtr et StrLen_or_IndPtr . Lorsque l'attribut d'instruction SQL_ATTR_ROW_ARRAY_SIZE est supérieur à 1, TargetType doit faire référence à un tableau de mémoires tampon. Si TargetType est un releveur de coordonnées LOB, une valeur de releveur de coordonnées est renvoyée, et non les données LOB réelles. Le releveur de coordonnées LOB fait référence à la totalité de la valeur de données dans la colonne LOB.

Si une application CLI ne fournit pas de mémoire tampon de sortie pour une colonne LOB à l'aide de la fonction SQLBindCol() , le client de serveur de donnéesIBM® demande, par défaut, un releveur de coordonnées LOB pour le compte de l'application pour chaque colonne LOB dans les ensembles de résultats.

Une fois que les colonnes ont été liées, lors des extractions suivantes, l'application peut modifier la liaison de ces colonnes ou lier des colonnes précédemment non liées en appelant SQLBindCol(). La nouvelle liaison ne s'applique pas aux données déjà extraites ; elle sera utilisée lors de l'extraction suivante. Pour annuler la liaison d'une seule colonne (y compris les colonnes liées par SQLBindFileToCol()), appelez SQLBindCol() avec le pointeur TargetValuePtr défini sur NULL. Pour annuler la liaison de toutes les colonnes, l'application doit appeler SQLFreeStmt() avec l'entrée Option définie sur SQL_UNBIND.

L'application doit s'assurer que l'espace de stockage alloué est suffisant pour que les données puissent être extraites. Si la mémoire tampon doit contenir des données de longueur variable, l'application doit allouer autant de mémoire que la longueur maximale de la colonne liée plus le caractère de fin NULL. Sinon, les données risquent d'être tronquées. Si la mémoire tampon doit contenir des données de longueur fixe, l' interface de ligne de commande suppose que la taille de la mémoire tampon correspond à la longueur du type de données C. Si la conversion de données est spécifiée, la taille requise peut être affectée.

Si une troncature de chaîne se produit, SQL_SUCCESS_WITH_INFO est renvoyé et StrLen_or_IndPtr sera défini sur la taille réelle de TargetValuePtr disponible pour être renvoyé à l'application.

La troncature est également affectée par l'attribut d'instruction SQL_ATTR_MAX_LENGTH (utilisé pour limiter la quantité de données renvoyées à l'application). L'application peut spécifier de ne pas signaler la troncature en appelant SQLSetStmtAttr() avec SQL_ATTR_MAX_LENGTH et une valeur pour la longueur maximale à renvoyer pour toutes les colonnes de longueur variable, et en allouant une mémoire tampon TargetValuePtr de même taille (plus le caractère de fin null). Si les données de colonne sont supérieures à la longueur maximale définie, SQL_SUCCESS est renvoyé lorsque la valeur est extraite et la longueur maximale, et non la longueur réelle, est renvoyée dans StrLen_or_IndPtr.

Si la colonne à lier est un type SQL_GRAPHIC, SQL_VARGRAPHIC ou SQL_LONGVARGRAPHIC, TargetType peut être défini sur SQL_C_DBCHAR ou SQL_C_CHAR. Si TargetType est SQL_C_DBCHAR, les données extraites dans la mémoire tampon TargetValuePtr seront terminées par une valeur null avec un caractère de fin null double octet. Si TargetType est SQL_C_CHAR, il n'y aura pas d'arrêt null des données. Dans les deux cas, la longueur de la mémoire tampon TargetValuePtr (BufferLength) est exprimée en unités d'octets et doit donc être un multiple de 2. Il est également possible de forcer l' interface de ligne de commande à mettre fin aux chaînes graphiques à l'aide du mot clé PATCH1 .

• Le type SQL est un type de longueur variable, et
• StrLen_or_IndPtr et TargetValuePtr sont contigus, et
• Le type de colonne est NOT NULLABLE, et
• Une troncature de chaîne s'est produite.

Descripteurs et SQLBindCol

Les sections suivantes décrivent comment SQLBindCol() interagit avec les descripteurs.

Mappages d'arguments

Si l'appel à SQLBindCol() échoue, le contenu des zones de descripteur qu'il aurait définies dans l'ARD n'est pas défini et la valeur de la zone SQL_DESC_COUNT de l'ARD est inchangée.

Réinitialisation implicite de la zone COUNT

SQLBindCol() définit SQL_DESC_COUNT sur la valeur de l'argument ColumnNumber uniquement lorsque la valeur de SQL_DESC_COUNT est augmentée. Si la valeur de l'argument TargetValuePtr est un pointeur null et que la valeur de l'argument ColumnNumber est égale à SQL_DESC_COUNT (c'est-à-dire lors de l'annulation de la liaison de la colonne de limite supérieure), SQL_DESC_COUNT est défini sur le numéro de la colonne de limite restante la plus élevée.

Précautions concernant SQL_C_DEFAULT

Pour extraire correctement les données de colonne, l'application doit déterminer correctement la longueur et le point de départ des données dans la mémoire tampon de l'application. Lorsque l'application spécifie un TargetTypeexplicite, les idées fausses de l'application sont facilement détectées. Toutefois, lorsque l'application spécifie un TargetType de SQL_C_DEFAULT, SQLBindCol() peut être appliqué à une colonne d'un type de données différent de celui prévu par l'application, soit à partir des modifications apportées aux métadonnées, soit en appliquant le code à une colonne différente. Dans ce cas, l'application risque de ne pas pouvoir déterminer le début ou la longueur des données de colonne extraites. Cela peut entraîner des erreurs de données non signalées ou des violations de mémoire.

Codes de retour

Diagnostics

Restrictions

La prise en charge des données LOB est disponible uniquement lorsqu'elle est connectée à un serveur qui prend en charge les types de données d'objet LOB. Si l'application tente de spécifier un type de données C de releveur de coordonnées LOB pour un serveur qui ne le prend pas en charge, SQLSTATE HYC00 est renvoyé.