SQLSetStmtAttr, fonction

  • Article

Conformité
Version introduite : Conformité aux normes ODBC 3.0 : ISO 92

Résumé
SQLSetStmtAttr définit des attributs liés à une instruction.

Remarque

Pour plus d’informations sur ce que le Gestionnaire de pilotes mappe cette fonction lorsqu’une application ODBC 3.x fonctionne avec un pilote ODBC 2.x , consultez Fonctions de remplacement de mappage pour la compatibilité descendante des applications.

Syntaxe

  
SQLRETURN SQLSetStmtAttr(  
     SQLHSTMT      StatementHandle,  
     SQLINTEGER    Attribute,  
     SQLPOINTER    ValuePtr,  
     SQLINTEGER    StringLength);

Arguments

StatementHandle
[Entrée] Handle d’instruction.

Attribut
[Entrée] Option à définir, répertoriée dans « Commentaires ».

ValuePtr
[Entrée] Valeur à associer à l’attribut. Selon la valeur de l’attribut, ValuePtr est l’une des suivantes :

  • Handle de descripteur ODBC.

  • Valeur SQLUINTEGER.

  • Valeur SQLULEN.

  • Pointeur vers l’un des éléments suivants :

    • Chaîne de caractères terminée par null.

    • Mémoire tampon binaire.

    • Valeur ou tableau de type SQLLEN, SQLULEN ou SQLUSMALLINT.

    • Valeur définie par le pilote.

Si l’argument Attribute est une valeur spécifique au pilote, ValuePtr peut être un entier signé.

StringLength
[Entrée] Si l’attribut est un attribut défini par ODBC et que ValuePtr pointe vers une chaîne de caractères ou une mémoire tampon binaire, cet argument doit être la longueur de *ValuePtr. Si l’attribut est un attribut défini par ODBC et ValuePtr est un entier, StringLength est ignoré.

Si l’attribut est un attribut défini par le pilote, l’application indique la nature de l’attribut dans le Gestionnaire de pilotes en définissant l’argument StringLength . StringLength peut avoir les valeurs suivantes :

  • Si ValuePtr est un pointeur vers une chaîne de caractères, StringLength est la longueur de la chaîne ou SQL_NTS.

  • Si ValuePtr est un pointeur vers une mémoire tampon binaire, l’application place le résultat de la macro SQL_LEN_BINARY_ATTR(length) dans StringLength. Cela place une valeur négative dans StringLength.

  • Si ValuePtr est un pointeur vers une valeur autre qu’une chaîne de caractères ou une chaîne binaire, StringLength doit avoir la valeur SQL_IS_POINTER.

  • Si ValuePtr contient une valeur de longueur fixe, StringLength est SQL_IS_INTEGER ou SQL_IS_UINTEGER, le cas échéant.

Retours

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

Lorsque SQLSetStmtAttr retourne SQL_ERROR ou SQL_SUCCESS_WITH_INFO, une valeur SQLSTATE associée peut être obtenue en appelant SQLGetDiagRec avec un HandleType de SQL_HANDLE_STMT et un Handle of StatementHandle. Le tableau suivant répertorie les valeurs SQLSTATE couramment retournées par SQLSetStmtAttr et explique chacune d’elles dans le contexte de cette fonction ; la notation « (DM) » précède les descriptions de SQLSTATEs retournées par le Gestionnaire de pilotes. Le code de retour associé à chaque valeur SQLSTATE est SQL_ERROR, sauf indication contraire.

SQLSTATE Erreur Description
01000 Avertissement général Message d’information spécifique au pilote. (La fonction retourne SQL_SUCCESS_WITH_INFO.)
01S02 Valeur d’option modifiée Le pilote n’a pas pris en charge la valeur spécifiée dans ValuePtr, ou la valeur spécifiée dans ValuePtr n’était pas valide en raison des conditions de travail d’implémentation, de sorte que le pilote a remplacé une valeur similaire. (SQLGetStmtAttr peut être appelé pour déterminer la valeur temporairement substituée.) La valeur de remplacement est valide pour l’InstructionHandle jusqu’à ce que le curseur soit fermé, auquel point l’attribut d’instruction revient à sa valeur précédente. Les attributs d’instruction qui peuvent être modifiés sont les suivants :

SQL_ ATTR_CONCURRENCY SQL_ ATTR_CURSOR_TYPE SQL_ ATTR_KEYSET_SIZE SQL_ ATTR_MAX_LENGTH SQL_ ATTR_MAX_ROWS SQL_ ATTR_QUERY_TIMEOUT SQL_ATTR_ROW_ARRAY_SIZE SQL_ ATTR_SIMULATE_CURSOR

(La fonction retourne SQL_SUCCESS_WITH_INFO.)
08S01 Échec du lien de communication Le lien de communication entre le pilote et la source de données à laquelle le pilote a été connecté a échoué avant l’achèvement du traitement de la fonction.
24 000 État de curseur non valide L’attribut était SQL_ATTR_CONCURRENCY, SQL_ATTR_CURSOR_TYPE, SQL_ATTR_SIMULATE_CURSOR ou SQL_ATTR_USE_BOOKMARKS, et le curseur était ouvert.
HY000 Erreur générale Une erreur s’est produite pour laquelle il n’y avait aucun SQLSTATE spécifique et pour lequel aucun SQLSTATE spécifique à l’implémentation n’a été défini. Le message d’erreur retourné par SQLGetDiagRec dans la mémoire tampon *MessageText décrit l’erreur et sa cause.
HY001 Erreur d’allocation de mémoire Le pilote n’a pas pu allouer de mémoire nécessaire pour prendre en charge l’exécution ou l’achèvement de la fonction.
HY009 Utilisation non valide du pointeur Null L’argument Attribute a identifié un attribut d’instruction qui nécessitait un attribut de chaîne, et l’argument ValuePtr était un pointeur Null.
HY010 Erreur de séquence de fonction (DM) Une fonction en cours d’exécution asynchrone a été appelée pour le handle de connexion associé à StatementHandle. Cette fonction asynchrone était toujours en cours d’exécution lorsque la fonction SQLSetStmtAttr a été appelée.

(DM) SQLExecute, SQLExecDirect ou SQLMoreResults a été appelé pour l’instruction StatementHandle et retourné SQL_PARAM_DATA_AVAILABLE. Cette fonction a été appelée avant la récupération des données pour tous les paramètres diffusés en continu.

(DM) Une fonction en cours d’exécution asynchrone a été appelée pour l’instruction StatementHandle et était toujours en cours d’exécution lors de l’appel de cette fonction.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos a été appelé pour l’instructionHandle et retourné SQL_NEED_DATA. Cette fonction a été appelée avant que les données ne soient envoyées pour tous les paramètres ou colonnes de données à l’exécution.
HY011 Impossible de définir l’attribut maintenant L’attribut a été SQL_ATTR_CONCURRENCY, SQL_ ATTR_CURSOR_TYPE, SQL_ ATTR_SIMULATE_CURSOR ou SQL_ ATTR_USE_BOOKMARKS, et l’instruction a été préparée.
HY013 Erreur de gestion de la mémoire L’appel de fonction n’a pas pu être traité, car les objets de mémoire sous-jacents n’ont pas pu être accessibles, éventuellement en raison de conditions de mémoire insuffisantes.
HY017 Utilisation non valide d’un descripteur alloué automatiquement (DM) L’argument Attribut était SQL_ATTR_IMP_ROW_DESC ou SQL_ATTR_IMP_PARAM_DESC.

(DM) L’argument Attribute était SQL_ATTR_APP_ROW_DESC ou SQL_ATTR_APP_PARAM_DESC, et la valeur de ValuePtr était un descripteur alloué implicitement autre que le handle initialement alloué pour l’ARD ou APD.
HY024 Valeur d’attribut non valide Étant donné la valeur d’attribut spécifiée, une valeur non valide a été spécifiée dans ValuePtr. (Le Gestionnaire de pilotes retourne ce SQLSTATE uniquement pour les attributs de connexion et d’instruction qui acceptent un ensemble discret de valeurs, tels que SQL_ATTR_ACCESS_MODE ou SQL_ ATTR_ASYNC_ENABLE. Pour tous les autres attributs de connexion et d’instruction, le pilote doit vérifier la valeur spécifiée dans ValuePtr.)

L’argument Attribute était SQL_ATTR_APP_ROW_DESC ou SQL_ATTR_APP_PARAM_DESC, et ValuePtr était un handle de descripteur alloué explicitement qui ne se trouve pas sur la même connexion que l’argument StatementHandle .
HY090 Longueur de la chaîne ou de la mémoire tampon non valide (DM) *ValuePtr est une chaîne de caractères, et l’argument StringLength était inférieur à 0, mais n’était pas SQL_NTS.
HY092 Identificateur d’attribut/d’option non valide (DM) La valeur spécifiée pour l’attribut d’argument n’était pas valide pour la version d’ODBC prise en charge par le pilote.

(DM) La valeur spécifiée pour l’attribut argument était un attribut en lecture seule.
HY117 La connexion est suspendue en raison d’un état de transaction inconnu. Seules les fonctions de déconnexion et de lecture seule sont autorisées. (DM) Pour plus d’informations sur l’état suspendu, consultez la fonction SQLEndTran.
HYC00 Fonctionnalité facultative non implémentée La valeur spécifiée pour l’attribut argument était un attribut d’instruction ODBC valide pour la version d’ODBC prise en charge par le pilote, mais elle n’était pas prise en charge par le pilote.

L’argument Attribute a été SQL_ATTR_ASYNC_ENABLE et un appel à SQLGetInfo avec un InfoType de SQL_ASYNC_MODE retourne SQL_AM_CONNECTION.

L’argument Attribut était SQL_ATTR_ENABLE_AUTO_IPD et la valeur de l’attribut de connexion SQL_ATTR_AUTO_IPD était SQL_FALSE.
HYT01 Délai d’attente de la connexion expiré La période d’expiration de la connexion a expiré avant que la source de données ne réponde à la demande. La période d’expiration de connexion est définie via SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 Le pilote ne prend pas en charge cette fonction (DM) Le pilote associé à StatementHandle ne prend pas en charge la fonction.
S1118 Le pilote ne prend pas en charge la notification asynchrone Si vous appelez SQLSetStmtAttr pour définir SQL_ATTR_ASYNC_STMT_EVENT ; la notification asynchrone n’est pas prise en charge par le pilote.

Commentaires

Les attributs d’instruction d’une instruction restent en vigueur tant qu’ils ne sont pas modifiés par un autre appel à SQLSetStmtAttr ou jusqu’à ce que l’instruction soit supprimée en appelant SQLFreeHandle. L’appel de SQLFreeStmt avec l’option SQL_CLOSE, SQL_UNBIND ou SQL_RESET_PARAMS ne réinitialise pas les attributs d’instruction.

Certains attributs d’instruction prennent en charge la substitution d’une valeur similaire si la source de données ne prend pas en charge la valeur spécifiée dans ValuePtr. Dans ce cas, le pilote retourne SQL_SUCCESS_WITH_INFO et SQLSTATE 01S02 (valeur d’option modifiée). Par exemple, si l’attribut est SQL_ATTR_CONCURRENCY et ValuePtr est SQL_CONCUR_ROWVER et si la source de données ne prend pas en charge cela, le pilote remplace SQL_CONCUR_VALUES et retourne SQL_SUCCESS_WITH_INFO. Pour déterminer la valeur substituée, une application appelle SQLGetStmtAttr.

Le format des informations définies avec ValuePtr dépend de l’attribut spécifié. SQLSetStmtAttr accepte les informations d’attribut dans l’un des deux formats différents : une chaîne de caractères ou une valeur entière. Le format de chacun est noté dans la description de l’attribut. Ce format s’applique aux informations retournées pour chaque attribut dans SQLGetStmtAttr. Les chaînes de caractères pointées par l’argument ValuePtr de SQLSetStmtAttr ont une longueur de StringLength.

Remarque

La possibilité de définir des attributs d’instruction au niveau de la connexion en appelant SQLSetConnectAttr a été déconseillée dans ODBC 3.x. Les applications ODBC 3.x ne doivent jamais définir des attributs d’instruction au niveau de la connexion. Les attributs d’instruction ODBC 3.x ne peuvent pas être définis au niveau de la connexion, à l’exception des attributs SQL_ATTR_METADATA_ID et SQL_ATTR_ASYNC_ENABLE, qui sont à la fois des attributs de connexion et des attributs d’instruction, et peuvent être définis au niveau de la connexion ou au niveau de l’instruction.

Remarque

Les pilotes ODBC 3.x n’ont besoin que de prendre en charge cette fonctionnalité s’ils doivent utiliser des applications ODBC 2.x qui définissent les options d’instruction ODBC 2.x au niveau de la connexion. Pour plus d’informations, consultez « Définition des options d’instruction au niveau de la connexion » sous Mappage SQLSetConnectOption dans l’annexe G : Instructions relatives à la compatibilité descendante.

Attributs d’instruction qui définissent des champs de descripteur

De nombreux attributs d’instruction correspondent à un champ d’en-tête d’un descripteur. La définition de ces attributs entraîne en fait la définition des champs de descripteur. La définition de champs par un appel à SQLSetStmtAttr plutôt qu’à SQLSetDescField présente l’avantage qu’un handle de descripteur ne doit pas être obtenu pour l’appel de fonction.

Attention

L’appel de SQLSetStmtAttr pour une instruction peut affecter d’autres instructions. Cela se produit lorsque l’APD ou l’ARD associé à l’instruction est explicitement alloué et est également associé à d’autres instructions. Étant donné que SQLSetStmtAttr modifie l’APD ou ARD, les modifications s’appliquent à toutes les instructions auxquelles ce descripteur est associé. Si ce n’est pas le comportement requis, l’application doit dissocier ce descripteur des autres instructions (en appelant SQLSetStmtAttr pour définir le champ SQL_ATTR_APP_ROW_DESC ou SQL_ATTR_APP_PARAM_DESC sur un handle de descripteur différent) avant d’appeler à nouveau SQLSetStmtAttr .

Lorsqu’un champ de descripteur est défini en conséquence de l’attribut d’instruction correspondant défini, le champ est défini uniquement pour les descripteurs applicables qui sont actuellement associés à l’instruction identifiée par l’argument StatementHandle , et le paramètre d’attribut n’affecte pas les descripteurs qui peuvent être associés à cette instruction à l’avenir. Lorsqu’un champ descripteur qui est également un attribut d’instruction est défini par un appel à SQLSetDescField, l’attribut d’instruction correspondant est défini. Si un descripteur explicitement alloué est dissocié d’une instruction, un attribut d’instruction qui correspond à un champ d’en-tête rétablit la valeur du champ dans le descripteur implicitement alloué.

Lorsqu’une instruction est allouée (voir SQLAllocHandle), quatre descripteurs sont automatiquement alloués et associés à l’instruction. Les handles de descripteur explicitement alloués peuvent être associés à l’instruction en appelant SQLAllocHandle avec un fHandleType de SQL_HANDLE_DESC pour allouer un handle de descripteur, puis en appelant SQLSetStmtAttr pour associer le handle descripteur à l’instruction.

Les attributs d’instruction du tableau suivant correspondent aux champs d’en-tête du descripteur.

Attribut d’instruction Champ d’en-tête Desc.
SQL_ATTR_PARAM_BIND_OFFSET_PTR SQL_DESC_BIND_OFFSET_PTR APD
SQL_ATTR_PARAM_BIND_TYPE SQL_DESC_BIND_TYPE APD
SQL_ATTR_PARAM_OPERATION_PTR SQL_DESC_ARRAY_STATUS_PTR APD
SQL_ATTR_PARAM_STATUS_PTR SQL_DESC_ARRAY_STATUS_PTR DIP
SQL_ATTR_PARAMS_PROCESSED_PTR SQL_DESC_ROWS_PROCESSED_PTR DIP
SQL_ATTR_PARAMSET_SIZE SQL_DESC_ARRAY_SIZE APD
SQL_ATTR_ROW_ARRAY_SIZE SQL_DESC_ARRAY_SIZE ARD
SQL_ATTR_ROW_BIND_OFFSET_PTR SQL_DESC_BIND_OFFSET_PTR ARD
SQL_ATTR_ROW_BIND_TYPE SQL_DESC_BIND_TYPE ARD
SQL_ATTR_ROW_OPERATION_PTR SQL_DESC_ARRAY_STATUS_PTR ARD
SQL_ATTR_ROW_STATUS_PTR SQL_DESC_ARRAY_STATUS_PTR IRD
SQL_ATTR_ROWS_FETCHED_PTR SQL_DESC_ROWS_PROCESSED_PTR IRD

Attributs d'instruction

Les attributs actuellement définis et la version d’ODBC dans laquelle ils ont été introduits sont présentés dans le tableau suivant ; on s’attend à ce que d’autres attributs soient définis par les pilotes pour tirer parti de différentes sources de données. Une plage d’attributs est réservée par ODBC ; les développeurs de pilotes doivent réserver des valeurs pour leur propre utilisation spécifique au pilote à partir d’Open Group. Pour plus d’informations, consultez Types de données spécifiques au pilote, Types de descripteur, Types d’informations, Types de diagnostic et Attributs.

Attribut Contenu valuePtr
SQL_ATTR_APP_PARAM_DESC (ODBC 3.0) Handle vers aPD pour les appels suivants à SQLExecute et SQLExecDirect sur le handle d’instruction. La valeur initiale de cet attribut est le descripteur implicitement alloué lorsque l’instruction a été initialement allouée. Si la valeur de cet attribut est définie sur SQL_NULL_DESC ou sur le handle initialement alloué pour le descripteur, un handle APD alloué explicitement associé au handle d’instruction est dissocié de celui-ci et le handle d’instruction revient au handle APD alloué implicitement.

Cet attribut ne peut pas être défini sur un handle de descripteur qui a été implicitement alloué pour une autre instruction ou à un autre handle de descripteur qui a été implicitement défini sur la même instruction ; Les handles de descripteur alloués implicitement ne peuvent pas être associés à plusieurs handles d’instruction ou de descripteur.
SQL_ATTR_APP_ROW_DESC (ODBC 3.0) Handle vers l’ARD pour les extractions suivantes sur le handle d’instruction. La valeur initiale de cet attribut est le descripteur implicitement alloué lorsque l’instruction a été initialement allouée. Si la valeur de cet attribut est définie sur SQL_NULL_DESC ou sur le handle initialement alloué pour le descripteur, un handle ARD alloué explicitement associé au handle d’instruction est dissocié de celui-ci et le handle d’instruction revient au handle ARD alloué implicitement.

Cet attribut ne peut pas être défini sur un handle de descripteur qui a été implicitement alloué pour une autre instruction ou à un autre handle de descripteur qui a été implicitement défini sur la même instruction ; Les handles de descripteur alloués implicitement ne peuvent pas être associés à plusieurs handles d’instruction ou de descripteur.
SQL_ATTR_ASYNC_ENABLE (ODBC 1.0) Valeur SQLULEN qui spécifie si une fonction appelée avec l’instruction spécifiée est exécutée de manière asynchrone :

SQL_ASYNC_ENABLE_OFF = Désactiver la prise en charge de l’exécution asynchrone au niveau de l’instruction (valeur par défaut).

SQL_ASYNC_ENABLE_ON = Activer la prise en charge de l’exécution asynchrone au niveau de l’instruction.

Pour plus d’informations, consultez Exécution asynchrone (méthode d’interrogation).

Pour les pilotes avec prise en charge de l’exécution asynchrone au niveau de l’instruction, l’attribut d’instruction SQL_ATTR_ASYNC_ENABLE est en lecture seule. Sa valeur est identique à la valeur de l’attribut de niveau de connexion portant le même nom au moment où le handle d’instruction a été alloué.

Appel de SQLSetStmtAttr pour définir SQL_ATTR_ASYNC_ENABLE lorsque l’InfoType SQL_ASYNC_MODE retourne SQL_AM_CONNECTION retourne SQLSTATE HYC00 (fonctionnalité facultative non implémentée). Pour plus d’informations, consultez la fonction SQLSetConnectAttr pour plus d’informations.
SQL_ATTR_ASYNC_STMT_EVENT (ODBC 3.8) Valeur SQLPOINTER qui est un handle d’événement.

La notification de l’achèvement des fonctions asynchrones est activée en appelant SQLSetStmtAttr pour définir l’attribut SQL_ATTR_ASYNC_STMT_EVENT et spécifier le handle d’événement.
SQL_ATTR_ASYNC_STMT_PCALLBACK (ODBC 3.8) SQLPOINTER vers la fonction de rappel asynchrone.

Seul le Gestionnaire de pilotes peut appeler la fonction SQLSetStmtAttr d’un pilote avec cet attribut.
SQL_ATTR_ASYNC_STMT_PCONTEXT (ODBC 3.8) SQLPOINTER dans la structure de contexte

Seul le Gestionnaire de pilotes peut appeler la fonction SQLSetStmtAttr d’un pilote avec cet attribut.
SQL_ATTR_CONCURRENCY (ODBC 2.0) Valeur SQLULEN qui spécifie la concurrence du curseur :

SQL_CONCUR_READ_ONLY = Le curseur est en lecture seule. Aucune mise à jour n’est autorisée.

SQL_CONCUR_LOCK = Le curseur utilise le niveau de verrouillage le plus bas suffisant pour s’assurer que la ligne peut être mise à jour.

SQL_CONCUR_ROWVER = Cursor utilise le contrôle d’accès concurrentiel optimiste, en comparant les versions de lignes telles que SQLBase ROWID ou Sybase TIMESTAMP.

SQL_CONCUR_VALUES = Cursor utilise le contrôle d’accès concurrentiel optimiste, comparant les valeurs.

La valeur par défaut de SQL_ATTR_CONCURRENCY est SQL_CONCUR_READ_ONLY.

Cet attribut ne peut pas être spécifié pour un curseur ouvert. Pour plus d’informations, consultez Types d’accès concurrentiel.

Si l’attribut SQL_ATTR_CURSOR_TYPE est remplacé par un type qui ne prend pas en charge la valeur actuelle de SQL_ATTR_CONCURRENCY, la valeur de SQL_ATTR_CONCURRENCY est modifiée au moment de l’exécution et un avertissement émis lorsque SQLExecDirect ou SQLPrepare est appelé.

Si le pilote prend en charge l’instruction SELECT FOR UPDATE et qu’une telle instruction est exécutée pendant que la valeur de SQL_ATTR_CONCURRENCY est définie sur SQL_CONCUR_READ_ONLY, une erreur est retournée. Si la valeur de SQL_ATTR_CONCURRENCY est remplacée par une valeur prise en charge par le pilote pour une valeur de SQL_ATTR_CURSOR_TYPE, mais pas pour la valeur actuelle de SQL_ATTR_CURSOR_TYPE, la valeur de SQL_ATTR_CURSOR_TYPE sera modifiée au moment de l’exécution et SQLSTATE 01S02 (valeur d’option modifiée) est émise lorsque SQLExecDirect ou SQLPrepare est appelée.

Si l’accès concurrentiel spécifié n’est pas pris en charge par la source de données, le pilote remplace une autre concurrence et retourne SQLSTATE 01S02 (valeur d’option modifiée). Pour SQL_CONCUR_VALUES, le pilote remplace SQL_CONCUR_ROWVER, et vice versa. Pour SQL_CONCUR_LOCK, le conducteur remplace, dans l’ordre, SQL_CONCUR_ROWVER ou SQL_CONCUR_VALUES. La validité de la valeur substituée n’est pas vérifiée tant que le temps d’exécution n’est pas vérifié.

Pour plus d’informations sur la relation entre SQL_ATTR_CONCURRENCY et les autres attributs de curseur, consultez Caractéristiques du curseur et Type de curseur.
SQL_ATTR_CURSOR_SCROLLABLE (ODBC 3.0) Valeur SQLULEN qui spécifie le niveau de prise en charge requis par l’application. La définition de cet attribut affecte les appels suivants à SQLExecDirect et SQLExecute.

SQL_NONSCROLLABLE = Les curseurs pouvant faire défiler ne sont pas obligatoires sur le handle d’instruction. Si l’application appelle SQLFetchScroll sur ce handle, la seule valeur valide de FetchOrientation est SQL_FETCH_NEXT. Il s’agit de la valeur par défaut.

SQL_SCROLLABLE = Curseurs pouvant faire défiler l’instruction sont requis sur le handle d’instruction. Lors de l’appel de SQLFetchScroll, l’application peut spécifier n’importe quelle valeur valide de FetchOrientation, en obtenant le positionnement du curseur dans les modes autres que le mode séquentiel.

Pour plus d’informations sur les curseurs à défilement, consultez Curseurs pouvant faire défiler. Pour plus d’informations sur la relation entre SQL_ATTR_CURSOR_SCROLLABLE et les autres attributs de curseur, consultez Caractéristiques du curseur et Type de curseur
SQL_ATTR_CURSOR_SENSITIVITY (ODBC 3.0) Valeur SQLULEN qui spécifie si les curseurs sur le handle d’instruction rendent visibles les modifications apportées à un jeu de résultats par un autre curseur. La définition de cet attribut affecte les appels suivants à SQLExecDirect et SQLExecute. Une application peut lire la valeur de cet attribut pour obtenir son état initial ou son état comme le plus récemment défini par l’application.

SQL_UNSPECIFIED = Il n’est pas spécifié ce que le type de curseur est et si les curseurs sur le handle d’instruction rendent visibles les modifications apportées à un jeu de résultats par un autre curseur. Les curseurs sur le handle d’instruction peuvent rendre visibles aucun, certains ou toutes ces modifications. Il s’agit de la valeur par défaut.

SQL_INSENSITIVE = Tous les curseurs sur le handle d’instruction affichent le jeu de résultats sans refléter les modifications apportées à celui-ci par tout autre curseur. Les curseurs non sensibles sont en lecture seule. Cela correspond à un curseur statique, qui a une concurrence en lecture seule.

SQL_SENSITIVE = Tous les curseurs du handle d’instruction rendent visible toutes les modifications apportées à un jeu de résultats par un autre curseur.

Pour plus d’informations sur la relation entre SQL_ATTR_CURSOR_SENSITIVITY et les autres attributs de curseur, consultez Caractéristiques du curseur et Type de curseur.
SQL_ATTR_CURSOR_TYPE (ODBC 2.0) Valeur SQLULEN qui spécifie le type de curseur :

SQL_CURSOR_FORWARD_ONLY = Le curseur défile uniquement vers l’avant.

SQL_CURSOR_STATIC = Les données du jeu de résultats sont statiques.

SQL_CURSOR_KEYSET_DRIVEN = Le pilote enregistre et utilise les clés pour le nombre de lignes spécifiées dans l’attribut d’instruction SQL_ATTR_KEYSET_SIZE.

SQL_CURSOR_DYNAMIC = Le pilote enregistre et utilise uniquement les clés des lignes de l’ensemble de lignes.

La valeur par défaut est SQL_CURSOR_FORWARD_ONLY. Cet attribut ne peut pas être spécifié après la préparation de l’instruction SQL.

Si le type de curseur spécifié n’est pas pris en charge par la source de données, le pilote remplace un type de curseur différent et retourne SQLSTATE 01S02 (valeur d’option modifiée). Pour un curseur mixte ou dynamique, le pilote remplace, dans l’ordre, un curseur statique ou piloté par un jeu de clés. Pour un curseur piloté par l’ensemble de clés, le pilote remplace un curseur statique.

Pour plus d’informations sur les types de curseurs défilants, consultez Types de curseurs pouvant faire défiler. Pour plus d’informations sur la relation entre SQL_ATTR_CURSOR_TYPE et les autres attributs de curseur, consultez Caractéristiques du curseur et Type de curseur.
SQL_ATTR_ENABLE_AUTO_IPD (ODBC 3.0) Valeur SQLULEN qui spécifie si la population automatique de l’IPD est effectuée :

SQL_TRUE = Active la population automatique de l’IPD après un appel à SQLPrepare. SQL_FALSE = Désactive la population automatique de l’IPD après un appel à SQLPrepare. (Une application peut toujours obtenir des informations de champ IPD en appelant SQLDescribeParam, si pris en charge.) La valeur par défaut de l’attribut d’instruction SQL_ATTR_ENABLE_AUTO_IPD est SQL_FALSE. Pour plus d’informations, consultez Population automatique de l’IPD.
SQL_ATTR_FETCH_BOOKMARK_PTR (ODBC 3.0) SQLLEN * qui pointe vers une valeur de signet binaire. Lorsque SQLFetchScroll est appelé avec fFetchOrientation égale à SQL_FETCH_BOOKMARK, le pilote récupère la valeur de signet à partir de ce champ. Ce champ est défini par défaut sur un pointeur Null. Pour plus d’informations, consultez Défilement par signet.

La valeur indiquée par ce champ n’est pas utilisée pour la suppression par signet, mise à jour par signet ou extraction par les opérations de signet dans SQLBulkOperations, qui utilisent des signets mis en cache dans des mémoires tampons d’ensemble de lignes.
SQL_ATTR_IMP_PARAM_DESC (ODBC 3.0) Handle vers l’ADRESSE IPD. La valeur de cet attribut est le descripteur alloué lorsque l’instruction a été initialement allouée. L’application ne peut pas définir cet attribut.

Cet attribut peut être récupéré par un appel à SQLGetStmtAttr , mais pas défini par un appel à SQLSetStmtAttr.
SQL_ATTR_IMP_ROW_DESC (ODBC 3.0) Poignée de l’IRD. La valeur de cet attribut est le descripteur alloué lorsque l’instruction a été initialement allouée. L’application ne peut pas définir cet attribut.

Cet attribut peut être récupéré par un appel à SQLGetStmtAttr , mais pas défini par un appel à SQLSetStmtAttr.
SQL_ATTR_KEYSET_SIZE (ODBC 2.0) SQLULEN qui spécifie le nombre de lignes dans l’ensemble de clés pour un curseur piloté par l’ensemble de clés. Si la taille du jeu de clés est 0 (valeur par défaut), le curseur est entièrement piloté par keyset. Si la taille du jeu de clés est supérieure à 0, le curseur est mixte (piloté par le jeu de clés dans le jeu de clés et dynamique en dehors du jeu de clés). La taille du jeu de clés par défaut est 0. Pour plus d’informations sur les curseurs pilotés par keyset, consultez Curseurs pilotés par keyset.

Si la taille spécifiée dépasse la taille maximale du jeu de clés, le pilote remplace cette taille et retourne SQLSTATE 01S02 (valeur d’option modifiée).

SQLFetch ou SQLFetchScroll retourne une erreur si la taille du jeu de clés est supérieure à 0 et inférieure à la taille de l’ensemble de lignes.
SQL_ATTR_MAX_LENGTH (ODBC 1.0) Valeur SQLULEN qui spécifie la quantité maximale de données retournées par le pilote à partir d’un caractère ou d’une colonne binaire. Si ValuePtr est inférieur à la longueur des données disponibles, SQLFetch ou SQLGetData tronque les données et retourne SQL_SUCCESS. Si ValuePtr est 0 (valeur par défaut), le pilote tente de retourner toutes les données disponibles.

Si la longueur spécifiée est inférieure à la quantité minimale de données que la source de données peut retourner ou supérieure à la quantité maximale de données que la source de données peut retourner, le pilote remplace cette valeur et retourne SQLSTATE 01S02 (valeur d’option modifiée).

La valeur de cet attribut peut être définie sur un curseur ouvert ; Toutefois, le paramètre peut ne pas prendre effet immédiatement, auquel cas le pilote retourne SQLSTATE 01S02 (valeur d’option modifiée) et réinitialise l’attribut à sa valeur d’origine.

Cet attribut est destiné à réduire le trafic réseau et doit être pris en charge uniquement lorsque la source de données (par opposition au pilote) dans un pilote à plusieurs niveaux peut l’implémenter. Ce mécanisme ne doit pas être utilisé par les applications pour tronquer les données ; pour tronquer les données reçues, une application doit spécifier la longueur maximale de la mémoire tampon dans l’argument BufferLength dans SQLBindCol ou SQLGetData.
SQL_ATTR_MAX_ROWS (ODBC 1.0) Valeur SQLULEN correspondant au nombre maximal de lignes à retourner à l’application pour une instruction SELECT . Si *ValuePtr est égal à 0 (valeur par défaut), le pilote retourne toutes les lignes.

Cet attribut est destiné à réduire le trafic réseau. Conceptuellement, il est appliqué lorsque le jeu de résultats est créé et limite le jeu de résultats aux premières lignes ValuePtr . Si le nombre de lignes du jeu de résultats est supérieur à ValuePtr, le jeu de résultats est tronqué.

SQL_ATTR_MAX_ROWS s’applique à tous les jeux de résultats de l’instruction, y compris ceux retournés par les fonctions de catalogue. SQL_ATTR_MAX_ROWS établit un maximum pour la valeur du nombre de lignes du curseur.

Un pilote ne doit pas émuler SQL_ATTR_MAX_ROWS comportement pour SQLFetch ou SQLFetchScroll (si les limitations de taille du jeu de résultats ne peuvent pas être implémentées à la source de données) s’il ne peut pas garantir que SQL_ATTR_MAX_ROWS sera implémenté correctement.

Il est défini par le pilote si SQL_ATTR_MAX_ROWS s’applique aux instructions autres que les instructions SELECT (telles que les fonctions de catalogue).

La valeur de cet attribut peut être définie sur un curseur ouvert ; Toutefois, le paramètre peut ne pas prendre effet immédiatement, auquel cas le pilote retourne SQLSTATE 01S02 (valeur d’option modifiée) et réinitialise l’attribut à sa valeur d’origine.
SQL_ATTR_METADATA_ID (ODBC 3.0) Valeur SQLULEN qui détermine la façon dont les arguments de chaîne des fonctions de catalogue sont traités.

Si SQL_TRUE, l’argument de chaîne des fonctions de catalogue est traité comme des identificateurs. Le cas n’est pas significatif. Pour les chaînes non délimitées, le pilote supprime tous les espaces de fin et la chaîne est pliée en majuscules. Pour les chaînes délimitées, le pilote supprime les espaces de début ou de fin et prend tout ce qui se trouve entre les délimiteurs littéralement. Si l’un de ces arguments est défini sur un pointeur Null, la fonction retourne SQL_ERROR et SQLSTATE HY009 (utilisation non valide du pointeur Null).

Si SQL_FALSE, les arguments de chaîne des fonctions de catalogue ne sont pas traités comme des identificateurs. L’affaire est importante. Ils peuvent contenir un modèle de recherche de chaîne ou non, en fonction de l’argument.

La valeur par défaut est SQL_FALSE.

L’argument TableType de SQLTables, qui prend une liste de valeurs, n’est pas affecté par cet attribut.

SQL_ATTR_METADATA_ID pouvez également être défini au niveau de la connexion. (Il et SQL_ATTR_ASYNC_ENABLE sont les seuls attributs d’instruction qui sont également des attributs de connexion.)

Pour plus d’informations, consultez Arguments dans les fonctions de catalogue.
SQL_ATTR_NOSCAN (ODBC 1.0) Valeur SQLULEN qui indique si le pilote doit analyser les chaînes SQL pour les séquences d’échappement :

SQL_NOSCAN_OFF = Le pilote analyse les chaînes SQL pour les séquences d’échappement (la valeur par défaut).

SQL_NOSCAN_ON = Le pilote n’analyse pas les chaînes SQL pour les séquences d’échappement. Au lieu de cela, le pilote envoie l’instruction directement à la source de données.

Pour plus d’informations, consultez Séquences d’échappement dans ODBC.
SQL_ATTR_PARAM_BIND_OFFSET_PTR (ODBC 3.0) Valeur SQLULEN * qui pointe vers un décalage ajouté aux pointeurs pour modifier la liaison de paramètres dynamiques. Si ce champ n’est pas null, le pilote déréférence le pointeur, ajoute la valeur déréférence à chacun des champs différés dans l’enregistrement de descripteur (SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR et SQL_DESC_OCTET_LENGTH_PTR), puis utilise les nouvelles valeurs de pointeur lors de la liaison. Elle est définie sur Null par défaut.

Le décalage de liaison est toujours ajouté directement aux champs SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR et SQL_DESC_OCTET_LENGTH_PTR. Si le décalage est remplacé par une autre valeur, la nouvelle valeur est toujours ajoutée directement à la valeur dans le champ descripteur. Le nouveau décalage n’est pas ajouté à la valeur du champ, ainsi qu’à tous les décalages antérieurs.

Pour plus d’informations, consultez Décalages de liaison de paramètre.

La définition de cet attribut d’instruction définit le champ SQL_DESC_BIND_OFFSET_PTR dans l’en-tête APD.
SQL_ATTR_PARAM_BIND_TYPE (ODBC 3.0) Valeur SQLULEN qui indique l’orientation de liaison à utiliser pour les paramètres dynamiques.

Ce champ est défini sur SQL_PARAM_BIND_BY_COLUMN (valeur par défaut) pour sélectionner une liaison au niveau des colonnes.

Pour sélectionner une liaison en ligne, ce champ est défini sur la longueur de la structure ou une instance d’une mémoire tampon qui sera liée à un ensemble de paramètres dynamiques. Cette longueur doit inclure de l’espace pour tous les paramètres liés et tout remplissage de la structure ou de la mémoire tampon pour vous assurer que lorsque l’adresse d’un paramètre lié est incrémentée avec la longueur spécifiée, le résultat pointe vers le début du même paramètre dans le jeu de paramètres suivant. Lorsque vous utilisez l’opérateur sizeof dans ANSI C, ce comportement est garanti.

Pour plus d’informations, consultez Tableaux de liaison de paramètres.

La définition de cet attribut d’instruction définit le champ SQL_DESC_ BIND_TYPE dans l’en-tête APD.
SQL_ATTR_PARAM_OPERATION_PTR (ODBC 3.0) Valeur SQLUSMALLINT * qui pointe vers un tableau de valeurs SQLUSMALLINT utilisées pour ignorer un paramètre pendant l’exécution d’une instruction SQL. Chaque valeur est définie sur SQL_PARAM_PROCEED (pour que le paramètre soit exécuté) ou SQL_PARAM_IGNORE (pour que le paramètre soit ignoré).

Un ensemble de paramètres peut être ignoré pendant le traitement en définissant la valeur d’état dans le tableau pointé par SQL_DESC_ARRAY_STATUS_PTR dans l’APD pour SQL_PARAM_IGNORE. Un ensemble de paramètres est traité si sa valeur d’état est définie sur SQL_PARAM_PROCEED ou si aucun élément du tableau n’est défini.

Cet attribut d’instruction peut être défini sur un pointeur Null, auquel cas le pilote ne retourne pas de valeurs d’état de paramètre. Cet attribut peut être défini à tout moment, mais la nouvelle valeur n’est pas utilisée tant que SQLExecDirect ou SQLExecute n’est pas appelée.

Cet attribut est ignoré lorsqu’il n’existe aucun paramètre lié.

Pour plus d’informations, consultez Utilisation de tableaux de paramètres.

La définition de cet attribut d’instruction définit le champ SQL_DESC_ARRAY_STATUS_PTR dans l’en-tête APD.
SQL_ATTR_PARAM_STATUS_PTR (ODBC 3.0) Valeur SQLUSMALLINT * qui pointe vers un tableau de valeurs SQLUSMALLINT contenant des informations d’état pour chaque ligne de valeurs de paramètre après un appel à SQLExecute ou SQLExecDirect. Ce champ n’est requis que si PARAMSET_SIZE est supérieur à 1.

Les valeurs d’état peuvent contenir les valeurs suivantes :

SQL_PARAM_SUCCESS : l’instruction SQL a été exécutée avec succès pour cet ensemble de paramètres.

SQL_PARAM_SUCCESS_WITH_INFO : l’instruction SQL a été exécutée avec succès pour cet ensemble de paramètres ; toutefois, les informations d’avertissement sont disponibles dans la structure des données de diagnostic.

SQL_PARAM_ERROR : une erreur s’est produite lors du traitement de cet ensemble de paramètres. Des informations supplémentaires sur les erreurs sont disponibles dans la structure des données de diagnostic.

SQL_PARAM_UNUSED : ce jeu de paramètres n’a pas été utilisé, peut-être en raison du fait que certains ensembles de paramètres précédents ont provoqué une erreur qui a abandonné le traitement ultérieur, ou parce que SQL_PARAM_IGNORE a été défini pour cet ensemble de paramètres dans le tableau spécifié par le SQL_ATTR_PARAM_OPERATION_PTR.

SQL_PARAM_DIAG_UNAVAILABLE : le pilote traite les tableaux de paramètres comme une unité monolithique et ne génère donc pas ce niveau d’informations d’erreur.

Cet attribut d’instruction peut être défini sur un pointeur Null, auquel cas le pilote ne retourne pas de valeurs d’état de paramètre. Cet attribut peut être défini à tout moment, mais la nouvelle valeur n’est pas utilisée tant que SQLExecute ou SQLExecDirect n’est pas appelé. Notez que la définition de cet attribut peut affecter le comportement du paramètre de sortie implémenté par le pilote.

Pour plus d’informations, consultez Utilisation de tableaux de paramètres.

La définition de cet attribut d’instruction définit le champ SQL_DESC_ARRAY_STATUS_PTR dans l’en-tête IPD.
SQL_ATTR_PARAMS_PROCESSED_PTR (ODBC 3.0) Champ d’enregistrement SQLULEN * qui pointe vers une mémoire tampon dans laquelle retourner le nombre de jeux de paramètres qui ont été traités, y compris les jeux d’erreurs. Aucun nombre ne sera retourné s’il s’agit d’un pointeur Null.

La définition de cet attribut d’instruction définit le champ SQL_DESC_ROWS_PROCESSED_PTR dans l’en-tête IPD.

Si l’appel à SQLExecDirect ou SQLExecute qui remplit la mémoire tampon pointée par cet attribut ne retourne pas SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO, le contenu de la mémoire tampon n’est pas défini.

Pour plus d’informations, consultez Utilisation de tableaux de paramètres.
SQL_ATTR_PARAMSET_SIZE (ODBC 3.0) Valeur SQLULEN qui spécifie le nombre de valeurs pour chaque paramètre. Si SQL_ATTR_PARAMSET_SIZE est supérieur à 1, SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR et SQL_DESC_OCTET_LENGTH_PTR du point APD vers des tableaux. La cardinalité de chaque tableau est égale à la valeur de ce champ.

Cet attribut est ignoré lorsqu’il n’existe aucun paramètre lié.

Pour plus d’informations, consultez Utilisation de tableaux de paramètres.

La définition de cet attribut d’instruction définit le champ SQL_DESC_ARRAY_SIZE dans l’en-tête APD.
SQL_ATTR_QUERY_TIMEOUT (ODBC 1.0) Valeur SQLULEN correspondant au nombre de secondes à attendre l’exécution d’une instruction SQL avant de revenir à l’application. Si ValuePtr est égal à 0 (valeur par défaut), il n’y a pas de délai d’expiration.

Si le délai d’expiration spécifié dépasse le délai maximal dans la source de données ou est inférieur au délai minimal, SQLSetStmtAttr remplace cette valeur et retourne SQLSTATE 01S02 (valeur d’option modifiée).

Notez que l’application n’a pas besoin d’appeler SQLCloseCursor pour réutiliser l’instruction si une instruction SELECT a expiré.

Le délai d’expiration de requête défini dans cet attribut d’instruction est valide dans les modes synchrones et asynchrones.
SQL_ATTR_RETRIEVE_DATA (ODBC 2.0) Valeur SQLULEN :

SQL_RD_ON = SQLFetchScroll et, dans ODBC 3.x, SQLFetch récupère les données après avoir placé le curseur à l’emplacement spécifié. Il s’agit de la valeur par défaut.

SQL_RD_OFF = SQLFetchScroll et, dans ODBC 3.x, SQLFetch ne récupère pas les données après avoir positionné le curseur.

En définissant SQL_RETRIEVE_DATA sur SQL_RD_OFF, une application peut vérifier qu’une ligne existe ou récupérer un signet pour la ligne sans entraîner la surcharge liée à la récupération de lignes. Pour plus d’informations, consultez Défilement et extraction de lignes.

La valeur de cet attribut peut être définie sur un curseur ouvert ; Toutefois, le paramètre peut ne pas prendre effet immédiatement, auquel cas le pilote retourne SQLSTATE 01S02 (valeur d’option modifiée) et réinitialise l’attribut à sa valeur d’origine.
SQL_ATTR_ROW_ARRAY_SIZE (ODBC 3.0) Valeur SQLULEN qui spécifie le nombre de lignes retournées par chaque appel à SQLFetch ou SQLFetchScroll. Il s’agit également du nombre de lignes d’un tableau de signets utilisé dans une opération de signet en bloc dans SQLBulkOperations. La valeur par défaut est 1.

Si la taille d’ensemble de lignes spécifiée dépasse la taille maximale de l’ensemble de lignes prise en charge par la source de données, le pilote remplace cette valeur et retourne SQLSTATE 01S02 (valeur d’option modifiée).

Pour plus d’informations, consultez Taille de l’ensemble de lignes.

La définition de cet attribut d’instruction définit le champ SQL_DESC_ARRAY_SIZE dans l’en-tête ARD.
SQL_ATTR_ROW_BIND_OFFSET_PTR (ODBC 3.0) Valeur SQLULEN * qui pointe vers un décalage ajouté aux pointeurs pour modifier la liaison de données de colonne. Si ce champ n’est pas null, le pilote déréférence le pointeur, ajoute la valeur déréférence à chacun des champs différés dans l’enregistrement de descripteur (SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR et SQL_DESC_OCTET_LENGTH_PTR), puis utilise les nouvelles valeurs de pointeur lors de la liaison. Elle est définie sur Null par défaut.

La définition de cet attribut d’instruction définit le champ SQL_DESC_BIND_OFFSET_PTR dans l’en-tête ARD.
SQL_ATTR_ROW_BIND_TYPE (ODBC 1.0) Valeur SQLULEN qui définit l’orientation de liaison à utiliser lorsque SQLFetch ou SQLFetchScroll est appelé sur l’instruction associée. La liaison à l’échelle des colonnes est sélectionnée en définissant la valeur sur SQL_BIND_BY_COLUMN. La liaison au niveau des lignes est sélectionnée en définissant la valeur sur la longueur d’une structure ou une instance d’une mémoire tampon dans laquelle les colonnes de résultat seront liées.

Si une longueur est spécifiée, elle doit inclure de l’espace pour toutes les colonnes liées et tout remplissage de la structure ou de la mémoire tampon pour vous assurer que lorsque l’adresse d’une colonne liée est incrémentée avec la longueur spécifiée, le résultat pointe vers le début de la même colonne dans la ligne suivante. Lorsque vous utilisez l’opérateur sizeof avec des structures ou des unions dans ANSI C, ce comportement est garanti.

La liaison à l’échelle des colonnes est l’orientation de liaison par défaut pour SQLFetch et SQLFetchScroll.

Pour plus d’informations, consultez Colonnes de liaison à utiliser avec des curseurs de bloc.

La définition de cet attribut d’instruction définit le champ SQL_DESC_BIND_TYPE dans l’en-tête ARD.
SQL_ATTR_ROW_NUMBER (ODBC 2.0) Valeur SQLULEN qui correspond au nombre de lignes actuelles dans l’ensemble du jeu de résultats. Si le nombre de lignes actuelles ne peut pas être déterminé ou qu’il n’y a pas de ligne actuelle, le pilote retourne 0.

Cet attribut peut être récupéré par un appel à SQLGetStmtAttr , mais pas défini par un appel à SQLSetStmtAttr.
SQL_ATTR_ROW_OPERATION_PTR (ODBC 3.0) Valeur SQLUSMALLINT * qui pointe vers un tableau de valeurs SQLUSMALLINT utilisées pour ignorer une ligne pendant une opération en bloc à l’aide de SQLSetPos. Chaque valeur est définie sur SQL_ROW_PROCEED (pour que la ligne soit incluse dans l’opération en bloc) ou SQL_ROW_IGNORE (pour que la ligne soit exclue de l’opération en bloc). (Les lignes ne peuvent pas être ignorées à l’aide de ce tableau pendant les appels à SQLBulkOperations.)

Cet attribut d’instruction peut être défini sur un pointeur Null, auquel cas le pilote ne retourne pas de valeurs d’état de ligne. Cet attribut peut être défini à tout moment, mais la nouvelle valeur n’est pas utilisée tant que SQLSetPos n’est pas appelé à la prochaine heure.

Pour plus d’informations, consultez Mise à jour de lignes dans l’ensemble de lignes avec SQLSetPos et suppression de lignes dans l’ensemble de lignes avec SQLSetPos.

La définition de cet attribut d’instruction définit le champ SQL_DESC_ARRAY_STATUS_PTR dans l’ARD.
SQL_ATTR_ROW_STATUS_PTR (ODBC 3.0) Valeur SQLUSMALLINT * qui pointe vers un tableau de valeurs SQLUSMALLINT contenant des valeurs d’état de ligne après un appel à SQLFetch ou SQLFetchScroll. Le tableau comporte autant d’éléments qu’il y a de lignes dans l’ensemble de lignes.

Cet attribut d’instruction peut être défini sur un pointeur Null, auquel cas le pilote ne retourne pas de valeurs d’état de ligne. Cet attribut peut être défini à tout moment, mais la nouvelle valeur n’est pas utilisée tant que SQLBulkOperations, SQLFetch, SQLFetchScroll ou SQLSetPos n’est pas appelée.

Pour plus d’informations, consultez Nombre de lignes extraites et d’état.

La définition de cet attribut d’instruction définit le champ SQL_DESC_ARRAY_STATUS_PTR dans l’en-tête IRD.

Cet attribut est mappé par un pilote ODBC 2.x au tableau rgbRowStatus dans un appel à SQLExtendedFetch.
SQL_ATTR_ROWS_FETCHED_PTR (ODBC 3.0) Valeur SQLULEN * qui pointe vers une mémoire tampon dans laquelle renvoyer le nombre de lignes extraites après un appel à SQLFetch ou SQLFetchScroll ; le nombre de lignes affectées par une opération en bloc effectuée par un appel à SQLSetPos avec un argument Opération de SQL_REFRESH ; ou le nombre de lignes affectées par une opération en bloc effectuée par SQLBulkOperations. Ce nombre inclut les lignes d’erreur.

Pour plus d’informations, consultez Nombre de lignes extraites et d’état.

La définition de cet attribut d’instruction définit le champ SQL_DESC_ROWS_PROCESSED_PTR dans l’en-tête IRD.

Si l’appel à SQLFetch ou SQLFetchScroll qui remplit la mémoire tampon pointée par cet attribut ne retourne pas SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO, le contenu de la mémoire tampon n’est pas défini.
SQL_ATTR_SIMULATE_CURSOR (ODBC 2.0) Valeur SQLULEN qui spécifie si les pilotes qui simulent les instructions de mise à jour et de suppression positionnées garantissent que ces instructions affectent une seule ligne.

Pour simuler des instructions de mise à jour et de suppression positionnées, la plupart des pilotes construisent une instruction UPDATE ou DELETE recherchée contenant une clause WHERE qui spécifie la valeur de chaque colonne dans la ligne active. Sauf si ces colonnes constituent une clé unique, une telle instruction peut affecter plusieurs lignes.

Pour garantir que ces instructions affectent une seule ligne, le pilote détermine les colonnes d’une clé unique et ajoute ces colonnes au jeu de résultats. Si une application garantit que les colonnes du jeu de résultats constituent une clé unique, le pilote n’est pas nécessaire pour le faire. Cela peut réduire le temps d’exécution.

SQL_SC_NON_UNIQUE = Le pilote ne garantit pas que les instructions de mise à jour ou de suppression positionnées simulées n’affectent qu’une seule ligne ; c’est la responsabilité de l’application de le faire. Si une instruction affecte plusieurs lignes, SQLExecute, SQLExecDirect ou SQLSetPos retourne SQLSTATE 01001 (conflit d’opérations de curseur).

SQL_SC_TRY_UNIQUE = Le pilote tente de garantir que les instructions de mise à jour ou de suppression positionnées simulées n’affectent qu’une seule ligne. Le pilote exécute toujours ces instructions, même si elles peuvent affecter plusieurs lignes, par exemple lorsqu’il n’existe aucune clé unique. Si une instruction affecte plusieurs lignes, SQLExecute, SQLExecDirect ou SQLSetPos retourne SQLSTATE 01001 (conflit d’opérations de curseur).

SQL_SC_UNIQUE = Le pilote garantit que les instructions de mise à jour ou de suppression positionnées simulées n’affectent qu’une seule ligne. Si le pilote ne peut pas garantir cela pour une instruction donnée, SQLExecDirect ou SQLPrepare retourne une erreur.

Si la source de données fournit une prise en charge SQL native pour les instructions de mise à jour et de suppression positionnées et que le pilote ne simule pas les curseurs, SQL_SUCCESS est retourné lorsque SQL_SC_UNIQUE est demandé pour SQL_SIMULATE_CURSOR. SQL_SUCCESS_WITH_INFO est retourné si SQL_SC_TRY_UNIQUE ou SQL_SC_NON_UNIQUE est demandé. Si la source de données fournit le niveau de prise en charge SQL_SC_TRY_UNIQUE et que le pilote ne le fait pas, SQL_SUCCESS est retourné pour SQL_SC_TRY_UNIQUE et SQL_SUCCESS_WITH_INFO est retourné pour SQL_SC_NON_UNIQUE.

Si le type de simulation de curseur spécifié n’est pas pris en charge par la source de données, le pilote remplace un autre type de simulation et retourne SQLSTATE 01S02 (valeur d’option modifiée). Pour SQL_SC_UNIQUE, le conducteur remplace, dans l’ordre, SQL_SC_TRY_UNIQUE ou SQL_SC_NON_UNIQUE. Pour SQL_SC_TRY_UNIQUE, le pilote remplace SQL_SC_NON_UNIQUE.

La valeur par défaut est SQL_SC_UNIQUE.

Pour plus d’informations, consultez Simulation des instructions de mise à jour et de suppression positionnées.
SQL_ATTR_USE_BOOKMARKS (ODBC 2.0) Valeur SQLULEN qui spécifie si une application utilisera des signets avec un curseur :

SQL_UB_OFF = Désactivé (valeur par défaut)

SQL_UB_VARIABLE = Une application utilise des signets avec un curseur et le pilote fournit des signets de longueur variable s’ils sont pris en charge. SQL_UB_FIXED est déconseillé dans ODBC 3.x. Les applications ODBC 3.x doivent toujours utiliser des signets de longueur variable, même lors de l’utilisation de pilotes ODBC 2.x (qui ne pris en charge que des signets de longueur fixe de 4 octets). Cela est dû au fait qu’un signet de longueur fixe n’est qu’un cas spécial d’un signet de longueur variable. Lorsque vous utilisez un pilote ODBC 2.x , le Gestionnaire de pilotes mappe SQL_UB_VARIABLE à SQL_UB_FIXED.

Pour utiliser des signets avec un curseur, l’application doit spécifier cet attribut avec la valeur SQL_UB_VARIABLE avant d’ouvrir le curseur.

Pour plus d’informations, consultez Récupération des signets.

[1] Ces fonctions peuvent être appelées de manière asynchrone uniquement si le descripteur est un descripteur d’implémentation, et non un descripteur d’application.

Consultez la liaison à l’échelle des colonnes et la liaison à ligne.

Pour plus d’informations sur Consultez
Annulation du traitement des instructions SQLCancel, fonction
Renvoi du paramètre d’un attribut de connexion SQLGetConnectAttr, fonction
Renvoi du paramètre d’un attribut d’instruction SQLGetStmtAttr, fonction
Définition d’un attribut de connexion SQLSetConnectAttr, fonction
Définition d’un seul champ du descripteur SQLSetDescField, fonction

Voir aussi

Informations de référence sur l’API ODBC
Fichiers d’en-tête ODBC