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.

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.

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

Voir aussi

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