Partager via

Fonction SQLGetStmtAttr

  • Article

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.

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