Fonction SQLGetStmtAttr
Conformité
Version introduite : Conformité aux normes ODBC 3.0 : ISO 92
Résumé
SQLGetStmtAttr retourne le paramètre actuel d’un attribut d’instruction.
Notes
Pour plus d’informations sur ce à quoi le Gestionnaire de pilotes mappe cette fonction lorsqu’un odbc 3. L’application x fonctionne avec odbc 2. x pilote, consultez Mappage des fonctions de remplacement pour la compatibilité descendante des applications.
Syntaxe
SQLRETURN SQLGetStmtAttr(
SQLHSTMT StatementHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
Arguments
StatementHandle
[Entrée] Handle d’instruction.
Attribut
[Entrée] Attribut à récupérer.
ValuePtr
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner la valeur de l’attribut spécifié dans Attribut.
Si ValuePtr a la valeur NULL, StringLengthPtr retourne toujours le nombre total d’octets (à l’exclusion du caractère de fin null pour les données de caractères) disponibles pour retourner dans la mémoire tampon pointée par ValuePtr.
BufferLength
[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 *ValuePtr est un entier, BufferLength est ignoré. Si la valeur retournée dans *ValuePtr est une chaîne Unicode (lors de l’appel de SQLGetStmtAttrW), l’argument BufferLength doit être un nombre pair.
Si l’attribut 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 BufferLength . BufferLength peut avoir les valeurs suivantes :
Si *ValuePtr est un pointeur vers une chaîne de caractères, BufferLength correspond à 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 BufferLength. Cela place une valeur négative dans BufferLength.
Si *ValuePtr est un pointeur vers une valeur autre qu’une chaîne de caractères ou une chaîne binaire, bufferLength doit avoir la valeur SQL_IS_POINTER.
Si *ValuePtr contient un type de données de longueur fixe, BufferLength est SQL_IS_INTEGER ou SQL_IS_UINTEGER, le cas échéant.
StringLengthPtr
[Sortie] Pointeur vers une mémoire tampon dans laquelle renvoyer le nombre total d’octets (à l’exclusion du caractère de terminaison null) disponibles pour retourner dans *ValuePtr. Si la valeur de l’attribut est une chaîne de caractères et que le nombre d’octets disponibles à retourner est supérieur ou égal à BufferLength, les données dans *ValuePtr sont tronquées en BufferLength moins la longueur d’un caractère de terminaison null et sont terminées par null par le pilote.
Retours
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnostics
Lorsque SQLGetStmtAttr 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 SQLGetStmtAttr 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.) |
| 01004 | Données de chaîne, tronquées à droite | Les données retournées dans *ValuePtr ont été tronquées pour être BufferLength moins la longueur d’un caractère de terminaison null. La longueur de la valeur de chaîne non structurée est retournée dans *StringLengthPtr. (La fonction retourne SQL_SUCCESS_WITH_INFO.) |
| 24 000 | État de curseur non valide | L’argument Attribut a été SQL_ATTR_ROW_NUMBER et le curseur n’était pas ouvert, ou le curseur était positionné avant le début du jeu de résultats ou après la fin du jeu de résultats. |
| 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 l’argument 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. |
| HY010 | Erreur de séquence de fonction | (DM) Une fonction d’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 SQLGetStmtAttr a été appelée. (DM) Une fonction 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 renvoyé 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. |
| 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 consultés, peut-être en raison de conditions de mémoire insuffisantes. |
| HY090 | Chaîne ou longueur de mémoire tampon non valide | (DM) *ValuePtr est une chaîne de caractères, et BufferLength était inférieur à zéro, mais pas égal à SQL_NTS. |
| HY092 | Identificateur d’attribut/d’option non valide | La valeur spécifiée pour l’argument Attribute n’était pas valide pour la version d’ODBC prise en charge par le pilote. |
| HY109 | Position du curseur non valide | L’argument Attribute a été SQL_ATTR_ROW_NUMBER et la ligne a été supprimée ou n’a pas pu être extraite. |
| 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. |
| 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 correspondant à l’InstructionHandle ne prend pas en charge la fonction. |
Commentaires
Pour plus d’informations générales sur les attributs d’instruction, consultez Attributs d’instruction.
Un appel à SQLGetStmtAttr retourne dans *ValuePtr la valeur de l’attribut d’instruction spécifié dans Attribute. Cette valeur peut être une valeur SQLULEN ou une chaîne de caractères null. Si la valeur est une valeur SQLULEN, certains pilotes peuvent écrire uniquement les 32 bits ou 16 bits inférieurs d’une mémoire tampon et laisser le bit d’ordre supérieur inchangé. Par conséquent, les applications doivent utiliser une mémoire tampon de SQLULEN et initialiser la valeur sur 0 avant d’appeler cette fonction. En outre, les arguments BufferLength et StringLengthPtr ne sont pas utilisés. Si la valeur est une chaîne terminée par null, l’application spécifie la longueur maximale de cette chaîne dans l’argument BufferLength , et le pilote retourne la longueur de cette chaîne dans la mémoire tampon *StringLengthPtr .
Pour autoriser les applications appelant SQLGetStmtAttr à fonctionner avec ODBC 2. x pilotes, un appel à SQLGetStmtAttr est mappé dans le Gestionnaire de pilotes à SQLGetStmtOption.
Les attributs d’instruction suivants étant en lecture seule, ils peuvent être récupérés par SQLGetStmtAttr, mais pas définis par SQLSetStmtAttr :
SQL_ATTR_IMP_PARAM_DESC
SQL_ATTR_IMP_ROW_DESC
SQL_ATTR_ROW_NUMBER
Pour obtenir la liste des attributs qui peuvent être définis et récupérés, consultez SQLSetStmtAttr.
Fonctions connexes
| Pour obtenir des informations sur | Consultez |
|---|---|
| Retour du paramètre d’un attribut de connexion | Fonction SQLGetConnectAttr |
| Définition d’un attribut de connexion | Fonction SQLSetConnectAttr |
| Définition d’un attribut d’instruction | Fonction SQLSetStmtAttr |
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