Fonction SQLSetStmtAttr
Conformité
Version introduite : Conformité aux normes ODBC 3.0 : ISO 92
Résumé
SQLSetStmtAttr définit les attributs liés à une instruction.
Notes
Pour plus d’informations sur ce à quoi le Gestionnaire de pilotes mappe cette fonction lorsqu’une application ODBC 3.x fonctionne avec un pilote ODBC 2.x , consultez Mappage des fonctions de remplacement 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 à Attribute. Selon la valeur de Attribute, ValuePtr est l’une des valeurs 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 Attribute 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 Attribute est un attribut défini par ODBC et Que ValuePtr est un entier, StringLength est ignoré.
Si Attribute est un attribut défini par le pilote, l’application indique la nature de l’attribut au 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 de la 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. Cette opération 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, selon le cas.
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 de 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 | Error | Description |
|---|---|---|
| 01000 | Avertissement général | Message d’information spécifique au pilote. (La fonction retourne SQL_SUCCESS_WITH_INFO.) |
| 01S02 | Valeur de l’option modifiée | Le pilote ne prenait pas 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 de l’implémentation. Le pilote a donc remplacé une valeur similaire. (SQLGetStmtAttr peut être appelé pour déterminer la valeur temporairement substituée.) La valeur de substitution est valide pour l’InstructionHandle jusqu’à ce que le curseur soit fermé, auquel cas 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 de la liaison de communication | Le lien de communication entre le pilote et la source de données à laquelle le pilote a été connecté a échoué avant la fin 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 pas de SQLSTATE spécifique et pour laquelle 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 la 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 exécution asynchrone a été appelée pour le handle de connexion associé à l’InstructionHandle. 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’InstructionHandle et a 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’InstructionHandle et était toujours en cours d’exécution lorsque cette fonction a été appelée. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos a été appelé pour l’InstructionHandle et a retourné SQL_NEED_DATA. Cette fonction a été appelée avant l’envoi des données pour toutes les colonnes ou paramètres de données au moment de 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, peut-être en raison de conditions de mémoire insuffisantes. |
| HY017 | Utilisation non valide d’un handle de descripteur alloué automatiquement | (DM) L’argument Attribute a été SQL_ATTR_IMP_ROW_DESC ou SQL_ATTR_IMP_PARAM_DESC. (DM) L’argument Attribute a été SQL_ATTR_APP_ROW_DESC ou SQL_ATTR_APP_PARAM_DESC, et la valeur dans ValuePtr était un handle de descripteur alloué implicitement autre que le handle initialement alloué pour l’ARD ou L’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 renvoie cette valeur SQLSTATE uniquement pour les attributs de connexion et d’instruction qui acceptent un ensemble discret de valeurs, comme 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 a été SQL_ATTR_APP_ROW_DESC ou SQL_ATTR_APP_PARAM_DESC, et ValuePtr était un handle de descripteur explicitement alloué qui n’est pas sur la même connexion que l’argument StatementHandle . |
| HY090 | Chaîne ou longueur de 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’argument Attribute n’était pas valide pour la version d’ODBC prise en charge par le pilote. (DM) La valeur spécifiée pour l’argument Attribute é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 FONCTION SQLEndTran. |
| HYC00 | Fonctionnalité facultative non implémentée | La valeur spécifiée pour l’argument Attribute était un attribut d’instruction ODBC valide pour la version d’ODBC prise en charge par le pilote, mais 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 Attribute a été SQL_ATTR_ENABLE_AUTO_IPD et la valeur de l’attribut de connexion SQL_ATTR_AUTO_IPD a été SQL_FALSE. |
| HYT01 | Délai d’attente de la connexion expiré | Le délai d’expiration de la connexion a expiré avant que la source de données réponde à la demande. La période de délai d’expiration de la connexion est définie via SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Le pilote ne prend pas en charge cette fonction | (DM) Le pilote associé à l’InstructionHandle 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 jusqu’à ce qu’ils soient 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 Attribute est SQL_ATTR_CONCURRENCY et Que 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 du jeu d’informations 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 chaque 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 stringLength.
Notes
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 d’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 de l’instruction.
Notes
Les pilotes ODBC 3.x doivent uniquement prendre en charge cette fonctionnalité s’ils doivent fonctionner avec 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 connexion » sous Mappage SQLSetConnectOption dans l’Annexe G : Instructions de pilote pour 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 aboutit 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’il n’est pas obligatoire d’obtenir un handle de descripteur 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 l’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 autre handle de descripteur) avant d’appeler à nouveau SQLSetStmtAttr .
Lorsqu’un champ de descripteur est défini à la suite de la définition de l’attribut d’instruction correspondant, 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 de 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 revient à la valeur du champ dans le descripteur implicitement alloué.
Lorsqu’une instruction est allouée (consultez SQLAllocHandle), quatre handles de descripteurs sont automatiquement alloués et associés à l’instruction. Les handles descripteurs 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 de descripteur à l’instruction.
Les attributs d’instruction du tableau suivant correspondent aux champs d’en-tête de 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 | IPD |
| SQL_ATTR_PARAMS_PROCESSED_PTR | SQL_DESC_ROWS_PROCESSED_PTR | IPD |
| 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 aux pilotes, Types de descripteurs, Types d’informations, Types de diagnostic et Attributs.
| Attribut | Contenu de ValuePtr |
|---|---|
| SQL_ATTR_APP_PARAM_DESC (ODBC 3.0) | Handle de l’APD pour les appels suivants à SQLExecute et SQLExecDirect sur le handle d’instruction. La valeur initiale de cet attribut est le descripteur implicitement alloué lors de l’allocation initiale de l’instruction. Si la valeur de cet attribut est définie sur SQL_NULL_DESC ou le handle initialement alloué pour le descripteur, un handle APD explicitement alloué qui était précédemment 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é à 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 de l’ARD pour les extractions suivantes sur le handle d’instruction. La valeur initiale de cet attribut est le descripteur implicitement alloué lors de l’allocation initiale de l’instruction. Si la valeur de cet attribut est définie sur SQL_NULL_DESC ou le handle initialement alloué pour le descripteur, un handle ARD explicitement alloué qui était précédemment 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é à 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é. L’appel de SQLSetStmtAttr pour définir SQL_ATTR_ASYNC_ENABLE lorsque le SQL_ASYNC_MODE InfoType retourne SQL_AM_CONNECTION renvoie SQLSTATE HYC00 (fonctionnalité facultative non implémentée). Pour plus d’informations, consultez FONCTION SQLSetConnectAttr . |
| 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 vers 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 garantir la mise à jour de la ligne. SQL_CONCUR_ROWVER = Cursor utilise le contrôle d’accès concurrentiel optimiste, en comparant des versions de ligne telles que SQLBase ROWID ou Sybase TIMESTAMP. SQL_CONCUR_VALUES = Le curseur utilise le contrôle d’accès concurrentiel optimiste, en 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 est é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 alors 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 est modifiée au moment de l’exécution et SQLSTATE 01S02 (Valeur d’option modifiée) est émis lorsque SQLExecDirect ou SQLPrepare est appelé. 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 vérifiée qu’au moment de l’exécution. 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 avec défilement 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 = Des curseurs avec défilement 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, ce qui permet de positionner le curseur dans des modes autres que le mode séquentiel. Pour plus d’informations sur les curseurs avec défilement, consultez Curseurs avec défilement. 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é quel est le type de curseur 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 visible aucune modification, une partie ou l’ensemble de 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 par un autre curseur. Les curseurs insensibles sont en lecture seule. Cela correspond à un curseur statique, qui a une concurrence en lecture seule. SQL_SENSITIVE = Tous les curseurs sur le handle d’instruction rendent visibles 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 pour les lignes de l’ensemble de lignes. La valeur par défaut est SQL_CURSOR_FORWARD_ONLY. Cet attribut ne peut pas être spécifié une fois l’instruction SQL préparée. Si le type de curseur spécifié n’est pas pris en charge par la source de données, le pilote remplace un autre type de curseur 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 un jeu de clés, le pilote remplace un curseur statique. Pour plus d’informations sur les types de curseurs avec défilement, consultez Types de curseurs avec défilement. 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 le remplissage automatique de l’IPD est effectué : SQL_TRUE = Active le remplissage automatique de l’IPD après un appel à SQLPrepare. SQL_FALSE = Désactive le remplissage automatique de l’IPD après un appel à SQLPrepare. (Une application peut toujours obtenir des informations de champ IPD en appelant SQLDescribeParam, si elle est prise 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 Remplissage 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 égal à 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 pointée par ce champ n’est pas utilisée pour les opérations de suppression par signet, de mise à jour par signet ou d’extraction par 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 de l’IPD. La valeur de cet attribut est le descripteur alloué lors de l’allocation initiale de l’instruction. 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) | Handle 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 le jeu de clés pour un curseur piloté par un jeu de clés. Si la taille du jeu de clés est 0 (valeur par défaut), le curseur est entièrement piloté par le jeu de clés. Si la taille du jeu de clés est supérieure à 0, le curseur est mixte (piloté dans le jeu de clés et dynamique en dehors du jeu de clés). La taille par défaut du jeu de clés est 0. Pour plus d’informations sur les curseurs pilotés par un jeu de clés, consultez Curseurs pilotés par un jeu de clés. 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 que le pilote retourne à 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 ne doit être pris en charge que 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 des 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 dans le 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 au niveau de 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. L’affaire n’est pas significative. Pour les chaînes non délimitées, le pilote supprime 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 littéralement tout ce qui se trouve entre les délimiteurs. 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 significative. Elles 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 peut également être défini au niveau de la connexion. (It 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 à la recherche de séquences d’échappement : SQL_NOSCAN_OFF = Le pilote analyse les chaînes SQL à la recherche de séquences d’échappement (valeur par défaut). SQL_NOSCAN_ON = Le pilote n’analyse pas les chaînes SQL à la recherche de 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 des 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) et 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 de descripteur. Le nouveau décalage n’est pas ajouté à la valeur du champ, plus 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 au niveau des lignes, ce champ est défini sur la longueur de la structure ou d’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 garantir 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 l’ensemble de paramètres suivant. Lors de l’utilisation de l’opérateur sizeof dans ANSI C, ce comportement est garanti. Pour plus d’informations, consultez Liaison de tableaux 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 lors de 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 les valeurs d’état des paramètres. Cet attribut peut être défini à tout moment, mais la nouvelle valeur n’est utilisée que lors de l’appel suivant de SQLExecDirect ou SQLExecute . 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 de données de diagnostic. SQL_PARAM_UNUSED : ce jeu de paramètres n’a pas été utilisé, peut-être en raison du fait qu’un jeu de paramètres précédent a provoqué une erreur qui a interrompu 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 les valeurs d’état des paramètres. Cet attribut peut être défini à tout moment, mais la nouvelle valeur n’est utilisée que lors de l’appel suivant de SQLExecute ou SQLExecDirect . 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 renvoyer le nombre d’ensembles de paramètres qui ont été traités, y compris les jeux d’erreurs. Aucun nombre n’est 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 de l’APD pointent 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 qu’une instruction SQL s’exécute 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 d’expiration maximal dans la source de données ou est inférieur au délai d’expiration 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 en mode synchrone et asynchrone. |
| 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 de 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 des 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 dans 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 d’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 des 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érencée à 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) et utilise les nouvelles valeurs de pointeur lors de la liaison. Elle a la valeur 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 au niveau 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 d’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 garantir 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. Lors de l’utilisation de l’opérateur sizeof avec des structures ou des unions dans ANSI C, ce comportement est garanti. La liaison au niveau des colonnes est l’orientation de liaison par défaut pour SQLFetch et SQLFetchScroll. Pour plus d’informations, consultez Liaison de colonnes à 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 numéro de la ligne actuelle dans l’ensemble du jeu de résultats. Si le nombre de la ligne actuelle ne peut pas être déterminé ou s’il n’existe aucune 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 lors des 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 avant l’appel suivant de SQLSetPos . 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 avant l’appel suivant de SQLBulkOperations, SQLFetch, SQLFetchScroll ou SQLSetPos . Pour plus d’informations, consultez Nombre de lignes extraites et É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 retourner le nombre de lignes extraites après un appel à SQLFetch ou SQLFetchScroll ; nombre de lignes affectées par une opération en bloc effectuée par un appel à SQLSetPos avec un argument Operation 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 É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 n’affectent qu’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 de la ligne active. À moins que ces colonnes ne constituent une clé unique, une telle instruction peut affecter plusieurs lignes. Pour garantir que ces instructions n’affectent qu’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 tenu de 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’affecteront qu’une seule ligne ; il incombe à l’application de le faire. Si une instruction affecte plusieurs lignes, SQLExecute, SQLExecDirect ou SQLSetPos retourne SQLSTATE 01001 (conflit d’opération 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’y a pas de clé unique. Si une instruction affecte plusieurs lignes, SQLExecute, SQLExecDirect ou SQLSetPos retourne SQLSTATE 01001 (conflit d’opération 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 prend en charge sql natif 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 support 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 type de simulation différent et retourne SQLSTATE 01S02 (Valeur d’option modifiée). Pour SQL_SC_UNIQUE, le pilote 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 d’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 lorsqu’elles utilisent des pilotes ODBC 2.x (qui ne prend 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 Liaison au niveau des colonnes et Liaison au niveau des lignes.
Fonctions connexes
| Pour obtenir des informations sur | Consultez |
|---|---|
| Annulation du traitement des instructions | SQLCancel, fonction |
| Retour du paramètre d’un attribut de connexion | Fonction SQLGetConnectAttr |
| Retour du paramètre d’un attribut d’instruction | Fonction SQLGetStmtAttr |
| Définition d’un attribut de connexion | Fonction SQLSetConnectAttr |
| Définition d’un champ unique du descripteur | SQLSetDescField, fonction |
Voir aussi
Informations de référence sur l’API ODBC
Fichiers d’en-tête ODBC
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour