Curseurs de bloc, curseurs avec défilement et compatibilité descendante pour les applications ODBC 3.x

L’existence de SQLFetchScroll et SQLExtendedFetch représente la première division claire dans ODBC entre l’interface de programmation d’application (API), qui est l’ensemble de fonctions que les appels d’application et l’interface du fournisseur de services (SPI), qui est l’ensemble des fonctions que le pilote implémente. Ce fractionnement est nécessaire pour équilibrer l’exigence dans ODBC 3.x, qui utilise SQLFetchScroll, pour s’aligner sur les normes et être compatible avec ODBC 2.x, qui utilise SQLExtendedFetch.

L’API ODBC 3.x , qui est l’ensemble de fonctions que l’application appelle, inclut SQLFetchScroll et les attributs d’instruction associés. LE SPI ODBC 3.x , qui est l’ensemble de fonctions implémentées par le pilote, inclut SQLFetchScroll, SQLExtendedFetch et les attributs d’instruction associés. Étant donné que ODBC n’applique pas formellement ce fractionnement entre l’API et le SPI, il est possible que les applications ODBC 3.x appellent SQLExtendedFetch et les attributs d’instruction associés. Toutefois, il n’existe aucune raison pour que les applications ODBC 3.x effectuent cette opération. Pour plus d’informations sur les API et les API spIs, consultez l’introduction à l’architecture ODBC.

Pour plus d’informations sur la façon dont ODBC 3.x Driver Manager mappe les appels aux pilotes ODBC 2.x et ODBC 3.x, ainsi que les fonctions et attributs d’instruction qu’un pilote ODBC 3.x doit implémenter pour les curseurs de bloc et de défilement, consultez l’annexe G : Instructions relatives à la compatibilité descendante.

Le tableau suivant récapitule les fonctions et attributs d’instruction qu’une application ODBC 3.x doit utiliser avec des curseurs de bloc et de défilement. Il répertorie également les modifications entre ODBC 2.x et ODBC 3.x dans ce domaine que les applications ODBC 3.x doivent être compatibles avec les pilotes ODBC 2.x .

Fonction ou attribut d'instruction	Commentaires
SQL_ATTR_FETCH_BOOKMARK_PTR	Pointe vers le signet à utiliser avec SQLFetchScroll. Lorsqu’une application définit cela dans un pilote ODBC 2.x , cela doit pointer vers un signet de longueur fixe.
SQL_ATTR_ROW_STATUS_PTR	Pointe vers le tableau d’état de ligne rempli par SQLFetch, SQLFetchScroll, SQLBulkOperations et SQLSetPos. Si une application définit cela dans un pilote ODBC 2.x et appelle SQLBulkOperation avec une opération de SQL_ADD avant d’appeler SQLFetchScroll, SQLFetch ou SQLExtendedFetch, SQLSTATE HY011 (l’attribut ne peut pas être défini maintenant) est retourné. Lorsqu’une application appelle SQLFetch dans un pilote ODBC 2.x, SQLFetch est mappé à SQLExtendedFetch et retourne donc des valeurs dans ce tableau.
SQL_ATTR_ROWS_FETCHED_PTR	Pointe vers la mémoire tampon dans laquelle SQLFetch et SQLFetchScroll retournent le nombre de lignes extraites. Lorsqu’une application appelle SQLFetch dans un pilote ODBC 2.x, SQLFetch est mappé à SQLExtendedFetch et retourne donc une valeur dans cette mémoire tampon.
SQL_ATTR_ROW_ARRAY_SIZE	Définit la taille de l’ensemble de lignes. Si une application appelle SQLBulkOperations avec une opération de SQL_ADD dans un pilote ODBC 2.x , SQL_ROWSET_SIZE sera utilisée pour l’appel, et non SQL_ATTR_ROW_ARRAY_SIZE, car l’appel est mappé à SQLSetPos avec une opération de SQL_ADD, qui utilise SQL_ROWSET_SIZE. L’appel de SQLSetPos avec une opération de SQL_ADD ou SQLExtendedFetch dans un pilote ODBC 2.x utilise SQL_ROWSET_SIZE. L’appel de SQLFetch ou SQLFetchScroll dans un pilote ODBC 2.x utilise SQL_ATTR_ROW_ARRAY_SIZE.
SQLBulkOperations	Effectue des opérations d’insertion et de signet. Lorsque SQLBulkOperations avec une opération de SQL_ADD est appelée dans un pilote ODBC 2.x , il est mappé à SQLSetPos avec une opération de SQL_ADD. Voici les détails de l’implémentation : - Lors de l’utilisation d’un pilote ODBC 2.x , une application doit utiliser uniquement l’ARD implicitement alloué associé à l’instruction StatementHandle ; elle ne peut pas allouer un autre ARD pour l’ajout de lignes, car les opérations de descripteur explicites ne sont pas prises en charge dans un pilote ODBC 2.x . Une application doit utiliser SQLBindCol pour établir une liaison à l’ARD, et non à SQLSetDescField ou SQLSetDescRec. - Lors de l’appel d’un pilote ODBC 3.x , une application peut appeler SQLBulkOperations avec une opération de SQL_ADD avant d’appeler SQLFetch ou SQLFetchScroll. Lors de l’appel d’un pilote ODBC 2.x , une application doit appeler SQLFetchScroll avant d’appeler SQLBulkOperations avec une opération de SQL_ADD.
SQLFetch	Retourne l’ensemble de lignes suivant. Voici les détails de l’implémentation : - Lorsqu’une application appelle SQLFetch dans un pilote ODBC 2.x , elle est mappée à SQLExtendedFetch. - Lorsqu’une application appelle SQLFetch dans un pilote ODBC 3.x , elle retourne le nombre de lignes spécifiées avec l’attribut d’instruction SQL_ATTR_ROW_ARRAY_SIZE.
SQLFetchScroll	Retourne l’ensemble de lignes spécifié. Voici les détails de l’implémentation : - Lorsqu’une application appelle SQLFetchScroll dans un pilote ODBC 2.x , elle retourne SQLSTATE 01S01 (Erreur en ligne) avant chaque erreur qui s’applique à une seule ligne. Cela est uniquement dû au fait que le Gestionnaire de pilotes ODBC 3.x mappe ceci à SQLExtendedFetch et SQLExtendedFetch retourne ce SQLSTATE. Lorsqu’une application appelle SQLFetchScroll dans un pilote ODBC 3.x , elle ne retourne jamais SQLSTATE 01S01 (Erreur dans la ligne). - Lorsqu’une application appelle SQLFetchScroll dans un pilote ODBC 2.x avec FetchOrientation définie sur SQL_FETCH_BOOKMARK, l’argument FetchOffset doit être défini sur 0. SQLSTATE HYC00 (fonctionnalité facultative non implémentée) est retourné si la récupération de signet basée sur offset est tentée avec un pilote ODBC 2.x .

Remarque

Les applications ODBC 3.x ne doivent pas utiliser SQLExtendedFetch ou l’attribut d’instruction SQL_ROWSET_SIZE. Au lieu de cela, ils doivent utiliser SQLFetchScroll et l’attribut d’instruction SQL_ATTR_ROW_ARRAY_SIZE. Les applications ODBC 3.x ne doivent pas utiliser SQLSetPos avec une opération de SQL_ADD, mais doivent utiliser SQLBulkOperations avec une opération de SQL_ADD.