SQLSetStmtAttr

S’applique à : SQL Server Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System (PDW)

Le pilote ODBC SQL Server Native Client ne prend pas en charge le modèle de curseur mixte (jeu de clés/dynamique). Les tentatives de définir la taille du jeu de clés à l'aide de SQL_ATTR_KEYSET_SIZE échoue si la valeur définie n'est pas égale à 0.

L’application définit SQL_ATTR_ROW_ARRAY_SIZE sur toutes les instructions pour déclarer le nombre de lignes retournées sur un appel de fonction SQLFetch ou SQLFetchScroll. Sur les instructions qui indiquent un curseur côté serveur, le pilote utilise SQL_ATTR_ROW_ARRAY_SIZE pour déterminer la taille du bloc des lignes que le serveur génère pour satisfaire une demande d'extraction du curseur. Dans la taille des blocs d'un curseur dynamique, l'appartenance et l'ordre des lignes sont fixes si le niveau d'isolation de la transaction est suffisant pour garantir des lectures renouvelables des transactions validées. Le curseur est totalement dynamique en dehors du bloc indiqué par cette valeur. La taille des blocs de curseur côté serveur est complètement dynamique et peut être changée à n'importe quel stade du traitement d'extraction.

SQLSetStmtAttr et paramètres table

SQLSetStmtAttr peut être utilisé pour définir SQL_SOPT_SS_PARAM_FOCUS dans le descripteur de paramètre d’application (APD) avant d’accéder aux champs de descripteur pour les colonnes de paramètres table.

Si une tentative est effectuée pour définir SQL_SOPT_SS_PARAM_FOCUS sur l’ordinal d’un paramètre qui n’est pas un paramètre table, SQLSetStmtAttr retourne SQL_ERROR et un enregistrement de diagnostic est créé avec SQLSTATE = HY024 et le message « Valeur d’attribut non valide ». SQL_SOPT_SS_PARAM_FOCUS n'est pas modifié quand SQL_ERROR est retourné.

La définition de SQL_SOPT_SS_PARAM_FOCUS sur 0 restaure l'accès aux enregistrements de descripteurs pour les paramètres.

SQLSetStmtAttr peut également être utilisé pour définir SQL_SOPT_SS_NAME_SCOPE. Pour plus d'informations, consultez la section SQL_SOPT_SS_NAME_SCOPE, plus loin dans cette rubrique.

Pour plus d’informations, consultez Métadonnées de paramètre table pour les instructions préparées.

Pour plus d’informations sur les paramètres table, consultez Paramètres table (ODBC) .

Prise en charge par SQLSetStmtAttr des colonnes éparses

SQLSetStmtAttr peut être utilisé pour définir SQL_SOPT_SS_NAME_SCOPE. Pour plus d’informations, consultez la section SQL_SOPT_SS_NAME_SCOPE, plus loin dans cette rubrique. Pour plus d’informations sur les colonnes éparses, consultez La prise en charge des colonnes éparses (ODBC).

Attributs d'instruction

Le pilote ODBC SQL Server Native Client prend également en charge les attributs d’instruction spécifiques au pilote suivants.

SQL_SOPT_SS_CURSOR_OPTIONS

L'attribut SQL_SOPT_SS_CURSOR spécifie si le pilote utilise les options de performances spécifiques au pilote sur les curseurs. SQLGetData n’est pas autorisé lorsque ces options sont définies. La valeur par défaut est SQL_CO_OFF. La valeur de ValuePtr est de type SQLLEN.

Valeur ValuePtr	Description
SQL_CO_OFF	Par défaut. Désactive les curseurs rapides en avant uniquement, en lecture seule et autorécupération, active SQLGetData sur les curseurs en lecture seule et en lecture seule. Lorsque SQL_SOPT_SS_CURSOR_OPTIONS a la valeur SQL_CO_OFF, le type de curseur ne change pas. Autrement dit, le curseur avant uniquement rapide demeure un curseur avant uniquement rapide. Pour modifier le type de curseur, l’application doit maintenant définir un type de curseur différent à l’aide de SQLSetStmtAttr/SQL_ATTR_CURSOR_TYPE.
SQL_CO_FFO	Active les curseurs rapides en avant uniquement, en lecture seule, désactive SQLGetData sur les curseurs en lecture seule et en lecture seule.
SQL_CO_AF	Active l'option d'auto-extraction sur tout type de curseur. Lorsque cette option est définie pour un handle d’instruction, SQLExecute ou SQLExecDirect génère un SQLFetchScroll implicite (SQL_FIRST). Le curseur est ouvert et le premier lot de lignes est retourné en un seul aller-retour au serveur.
SQL_CO_FFO_AF	Active les curseurs avant uniquement rapides avec l'option d'auto-extraction. La situation est la même que si SQL_CO_AF et SQL_CO_FFO étaient spécifiés.

Lorsque ces options sont définies, le serveur ferme automatiquement le curseur lorsqu'il détecte que la dernière ligne a été extraite. L’application doit toujours appeler SQLFreeStmt (SQL_CLOSE) ou SQLCloseCursor, mais le pilote n’a pas besoin d’envoyer la notification proche au serveur.

Si la liste de sélection contient un texte, ntext ou une colonne d’image, le curseur avant uniquement rapide est converti en curseur dynamique et SQLGetData est autorisé.

SQL_SOPT_SS_DEFER_PREPARE

L’attribut SQL_SOPT_SS_DEFER_PREPARE détermine si l’instruction est préparée immédiatement ou différée jusqu’à SQLExecute, SQLDescribeCol ou SQLDescribeParam est exécutée. Dans SQL Server 7.0 et versions antérieures, cette propriété est ignorée (aucune préparation différée). La valeur de ValuePtr est de type SQLLEN.

Valeur ValuePtr	Description
SQL_DP_ON	Par défaut. Après avoir appelé SQLPrepare Function, la préparation de l’instruction est différée jusqu’à ce que SQLExecute soit appelée ou l’opération de métapropriété (SQLDescribeCol ou SQLDescribeParam) soit exécutée.
SQL_DP_OFF	L’instruction est préparée dès que SQLPrepare est exécuté.

SQL_SOPT_SS_REGIONALIZE

L'attribut SQL_SOPT_SS_REGIONALIZE est utilisé pour déterminer la conversion des données au niveau de l'instruction. L'attribut oblige le pilote à respecter les paramètres régionaux du client lors de la conversion des valeurs date, heure et devise monétaire en chaînes de caractères. La conversion est de types de données natifs SQL Server en chaînes de caractères uniquement.

La valeur de ValuePtr est de type SQLLEN.

Valeur ValuePtr	Description
SQL_RE_OFF	Par défaut. Le pilote ne convertit pas les valeurs date, heure et devise monétaire en données de chaînes de caractères à l'aide des paramètres régionaux du client.
SQL_RE_ON	Le pilote utilise les paramètres régionaux du client lors de la conversion des données date, heure et devise monétaire en données de chaînes de caractères.

Les paramètres de conversion régionaux s'appliquent aux types de données monétaire, numérique, date et heure. Le paramètre de conversion est applicable uniquement aux conversions sortantes lorsque des valeurs monétaire, numérique, de date ou d'heure sont converties en chaînes de caractères.

Remarque

Lorsque l'option d'instruction SQL_SOPT_SS_REGIONALIZE est activée, le pilote utilise les paramètres du Registre des paramètres régionaux de l'utilisateur en cours. Le pilote ne respecte pas les paramètres régionaux du thread actuel si l’application la définit par exemple en appelant SetThreadLocale.

La modification du comportement régional d'une source de données peut provoquer l'échec de l'application. Une application qui analyse les chaînes date et s'attend à ce qu'elles apparaissent comme définies par ODBC peut être affectée de manière négative par la modification de cette valeur.

SQL_SOPT_SS_TEXTPTR_LOGGING

L’attribut SQL_SOPT_SS_TEXTPTR_LOGGING bascule la journalisation des opérations sur les colonnes contenant du texte ou des données d’image. La valeur de ValuePtr est de type SQLLEN.

Valeur ValuePtr	Description
SQL_TL_OFF	Désactive la journalisation des opérations effectuées sur le texte et les données d’image.
SQL_TL_ON	Par défaut. Active la journalisation des opérations effectuées sur le texte et les données d’image.

SQL_SOPT_SS_HIDDEN_COLUMNS

L’attribut SQL_SOPT_SS_HIDDEN_COLUMNS expose, dans le jeu de résultats, les colonnes masquées dans une instruction SQL Server SELECT FOR BROWSE. Le pilote n'expose pas ces colonnes par défaut. La valeur de ValuePtr est de type SQLLEN.

Valeur ValuePtr	Description
SQL_HC_OFF	Par défaut. Les colonnes FOR BROWSE sont masquées dans le jeu de résultats.
SQL_HC_ON	Expose les colonnes FOR BROWSE.

SQL_SOPT_SS_QUERYNOTIFICATION_MSGTEXT

L'attribut SQL_SOPT_SS_QUERYNOTIFICATION_MSGTEXT retourne le texte du message pour la demande de notification de requête.

SQL_SOPT_SS_QUERYNOTIFICATION_OPTIONS

L'attribut SQL_SOPT_SS_QUERYNOTIFICATION_OPTIONS spécifie les options utilisées pour la demande de notification de requête. Ces options sont spécifiés dans une chaîne avec la syntaxe name=value comme spécifié ci-dessous. L'application est chargée de créer le service et de lire les notifications de la file d'attente.

La syntaxe de la chaîne des options de notifications de requêtes est :

service=<service-name>[;(local database=<database>|broker instance=<broker instance>)]

Par exemple :

service=mySSBService;local database=mydb

SQL_SOPT_SS_QUERYNOTIFICATION_TIMEOUT

L'attribut SQL_SOPT_SS_QUERYNOTIFICATION_TIMEOUT spécifie le nombre de secondes pendant lesquelles la notification de requête demeure active. La valeur par défaut est de 432 000 secondes (5 jours). La valeur de ValuePtr est de type SQLLEN.

SQL_SOPT_SS_PARAM_FOCUS

L’attribut SQL_SOPT_SS_PARAM_FOCUS spécifie le focus pour les appels SQLBindParameter, SQLGetDescField, SQLSetDescField, SQLGetDescRec et SQLSetDescRec.

Le type de SQL_SOPT_SS_PARAM_FOCUS est SQLULEN.

La valeur par défaut est 0, ce qui signifie que ces appels adressent les paramètres qui correspondent aux marqueurs de paramètre dans l'instruction SQL. En cas de définition sur le numéro de paramètre d'un paramètre table, ces appels adressent les colonnes de ce paramètre table. En cas de définition sur une valeur qui n'est pas le numéro de paramètre d'un paramètre table, ces appels retournent l'erreur IM020 : « Le focus de paramètre ne fait pas référence à un paramètre table ».

SQL_SOPT_SS_NAME_SCOPE

L'attribut SQL_SOPT_SS_NAME_SCOPE spécifie la portée de nom des appels de fonctions de catalogue suivants. Le jeu de résultats retourné par SQLColumns dépend du paramètre de SQL_SOPT_SS_NAME_SCOPE.

Le type de SQL_SOPT_SS_NAME_SCOPE est SQLULEN.

Valeur ValuePtr	Description
SQL_SS_NAME_SCOPE_TABLE	Par défaut. Lors de l'utilisation de paramètres table, indique que les métadonnées des tables réelles doivent être retournées. Lorsque vous utilisez la fonctionnalité colonnes éparses, SQLColumns retourne uniquement les colonnes qui ne sont pas membres de la column_set éparse.
SQL_SS_NAME_SCOPE_TABLE_TYPE	Indique que l'application requiert les métadonnées pour un type de table, plutôt qu'une table réelle (les fonctions de catalogue doivent retourner les métadonnées pour les types de table). L’application transmet ensuite la TYPE_NAME du paramètre table comme paramètre TableName .
SQL_SS_NAME_SCOPE_EXTENDED	Lors de l’utilisation de la fonctionnalité colonnes éparses, SQLColumns retourne toutes les colonnes, quelle que soit l’appartenance column_set .
SQL_SS_NAME_SCOPE_SPARSE_COLUMN_SET	Lorsque vous utilisez la fonctionnalité colonnes éparses, SQLColumns retourne uniquement les colonnes membres de l’column_set éparse.
SQL_SS_NAME_SCOPE_DEFAULT	Identique à SQL_SS_NAME_SCOPE_TABLE.

SS_TYPE_CATALOG_NAME et SS_TYPE_SCHEMA_NAME sont utilisés avec les paramètres CatalogName et SchemaName, respectivement, pour identifier le catalogue et le schéma du paramètre table. Quand une application a fini d'extraire les métadonnées des paramètres table, elle doit redéfinir SQL_SOPT_SS_NAME_SCOPE avec sa valeur par défaut SQL_SS_NAME_SCOPE_TABLE.

Lorsque SQL_SOPT_SS_NAME_SCOPE est défini avec la valeur SQL_SS_NAME_SCOPE_TABLE, les requêtes adressées aux serveurs liés échouent. Les appels à SQLColumns ou SQLPrimaryKeys avec un catalogue contenant un composant serveur échouent.

Si vous essayez de définir SQL_SOPT_SS_NAME_SCOPE avec une valeur non valide, SQL_ERROR est retourné et un enregistrement de diagnostic est généré avec SQLSTATE HY024 et le message « Valeur d'attribut non valide ».

Si une fonction catalogue autre que SQLTables, SQLColumns ou SQLPrimaryKeys est appelée lorsque SQL_SOPT_SS_NAME_SCOPE a une valeur autre que SQL_SS_NAME_SCOPE_TABLE, SQL_ERROR est retournée. Un enregistrement de diagnostic est généré avec SQLSTATE HY010 et le message « Erreur de séquence de fonction (SQL_SOPT_SS_NAME_SCOPE n'est pas défini avec la valeur SQL_SS_NAME_SCOPE_TABLE) ».

Voir aussi

SQLGetStmtAttr, fonction
Détails de l’implémentation d’API ODBC