Partager via

SQLSetDescRec, fonction

  • Article

conformité
Version introduite : Conformité aux normes ODBC 3.0 : ISO 92

résumé
La fonction SQLSetDescRec définit plusieurs champs descripteur qui affectent le type de données et la mémoire tampon liés à une colonne ou à des données de paramètre.

Syntaxe

  
SQLRETURN SQLSetDescRec(  
      SQLHDESC      DescriptorHandle,  
      SQLSMALLINT   RecNumber,  
      SQLSMALLINT   Type,  
      SQLSMALLINT   SubType,  
      SQLLEN        Length,  
      SQLSMALLINT   Precision,  
      SQLSMALLINT   Scale,  
      SQLPOINTER    DataPtr,  
      SQLLEN *      StringLengthPtr,  
      SQLLEN *      IndicatorPtr);

Arguments

DescriptorHandle
[Entrée] Descripteur handle. Il ne doit pas s’agir d’un handle IRD.

RecNumber
[Entrée] Indique l’enregistrement de descripteur qui contient les champs à définir. Les enregistrements de descripteur sont numérotés de 0, avec le numéro d’enregistrement 0 étant l’enregistrement de signet. Cet argument doit être égal ou supérieur à 0. Si RecNumber est supérieur à la valeur de SQL_DESC_COUNT, SQL_DESC_COUNTis remplacé par la valeur de RecNumber.

type
[Entrée] Valeur à laquelle définir le champ SQL_DESC_TYPE pour l’enregistrement du descripteur.

sous-type
[Entrée] Pour les enregistrements dont le type est SQL_DATETIME ou SQL_INTERVAL, il s’agit de la valeur à laquelle définir le champ SQL_DESC_DATETIME_INTERVAL_CODE.

longueur
[Entrée] Valeur à laquelle définir le champ SQL_DESC_OCTET_LENGTH pour l’enregistrement du descripteur.

Précision
[Entrée] Valeur à laquelle définir le champ SQL_DESC_PRECISION pour l’enregistrement du descripteur.

mettre à l’échelle
[Entrée] Valeur à laquelle définir le champ SQL_DESC_SCALE pour l’enregistrement du descripteur.

dataPtr
[Entrée ou sortie différée] Valeur à laquelle définir le champ SQL_DESC_DATA_PTR pour l’enregistrement du descripteur. DataPtr peut être défini sur un pointeur Null.

L’argument DataPtr peut être défini sur un pointeur Null pour définir le champ SQL_DESC_DATA_PTR sur un pointeur Null. Si le handle de l’argument de DescriptorHandle est associé à un ARD, cela annule la liaison de la colonne.

stringLengthPtr
[Entrée ou sortie différée] Valeur à laquelle définir le champ SQL_DESC_OCTET_LENGTH_PTR pour l’enregistrement du descripteur. StringLengthPtr peut être défini sur un pointeur Null pour définir le champ SQL_DESC_OCTET_LENGTH_PTR sur un pointeur Null.

IndicatorPtr
[Entrée ou sortie différée] Valeur à laquelle définir le champ SQL_DESC_INDICATOR_PTR pour l’enregistrement du descripteur. IndicatorPtr peut être défini sur un pointeur Null pour définir le champ SQL_DESC_INDICATOR_PTR sur un pointeur Null.

Retourne

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostic

Lorsque SQLSetDescRec 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_DESC et un Handle de DescriptorHandle. Le tableau suivant répertorie les valeurs SQLSTATE couramment retournées par SQLSetDescRec et explique chacune d’elles dans le contexte de cette fonction ; la notation « (DM) » précède les descriptions des SQLSTATEs retournées par le Gestionnaire de pilotes. Le code de retour associé à chaque valeur SQLSTATE est SQL_ERROR, sauf indication contraire.

SQLSTATE Erreur Description
01000 Avertissement général Message d’information spécifique au pilote. (La fonction retourne SQL_SUCCESS_WITH_INFO.)
07009 Index de descripteur non valide L’argument RecNumber a été défini sur 0, et la DescriptorHandle a fait référence à un handle IPD.

L’argument RecNumber était inférieur à 0.

L’argument RecNumber était supérieur au nombre maximal de colonnes ou de paramètres que la source de données peut prendre en charge, et l’argument DescriptorHandle était un argument APD, IPD ou ARD.

L’argument RecNumber était égal à 0, et l’argument DescriptorHandle fait référence à un APD implicitement alloué. (Cette erreur ne se produit pas avec un descripteur d’application alloué explicitement, car il n’est pas connu si un descripteur d’application explicitement alloué est un APD ou ARD jusqu’au moment de l’exécution.)
08S01 Échec du lien de communication Le lien de communication entre le pilote et la source de données à laquelle le pilote a été connecté a échoué avant l’achèvement du traitement de la fonction.
HY000 Erreur générale Une erreur s’est produite pour laquelle il n’y avait aucun SQLSTATE spécifique et pour lequel 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 de 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) L'DescriptorHandle a été associé à un StatementHandle pour lequel une fonction en cours d’exécution asynchrone (et non celle-ci) a été appelée et s’exécutait quand cette fonction était appelée.

(DM) SQLExecute , SQLExecDirect, SQLBulkOperations, ou SQLSetPos a été appelé pour le statementHandle avec lequel le DescriptorHand le a été associé et retourné SQL_NEED_DATA. Cette fonction a été appelée avant que les données ne soient envoyées pour tous les paramètres ou colonnes de données à l’exécution.

(DM) Une fonction en cours d’exécution asynchrone a été appelée pour le handle de connexion associé au descripteur de DescriptorHandle. Cette fonction asynchrone était toujours en cours d’exécution lorsque la fonction SQLSetDescRec a été appelée.

(DM) SQLExecute, SQLExecDirectou SQLMoreResults a été appelé pour l’un des handles d’instruction associés au DescriptorHandle et 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.
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, éventuellement en raison de conditions de mémoire insuffisantes.
HY016 Impossible de modifier un descripteur de ligne d’implémentation L’argument DescriptorHandle a été associé à un IRD.
HY021 Informations de descripteur incohérentes Le champ Type, ou tout autre champ associé au champ SQL_DESC_TYPE dans le descripteur, n’était pas valide ou cohérent.

Les informations de descripteur vérifiées lors d’une vérification de cohérence n’ont pas été cohérentes. (Consultez « Vérifications de cohérence », plus loin dans cette section.)
HY090 Longueur de la chaîne ou de la mémoire tampon non valide (DM) Le pilote était un pilote ODBC 2.x, le descripteur était un ARD, l’argument ColumnNumber était défini sur 0 et la valeur spécifiée pour l’argument BufferLength n’était pas égale à 4.
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.
HYT01 Expiration du délai d’expiration de la connexion La période d’expiration de la connexion a expiré avant que la source de données ne réponde à la demande. La période 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é au DescriptorHandle ne prend pas en charge la fonction.

Commentaires

Une application peut appeler SQLSetDescRec pour définir les champs suivants pour une seule colonne ou paramètre :

  • SQL_DESC_TYPE

  • SQL_DESC_DATETIME_INTERVAL_CODE (pour les enregistrements dont le type est SQL_DATETIME ou SQL_INTERVAL)

  • SQL_DESC_OCTET_LENGTH

  • SQL_DESC_PRECISION

  • SQL_DESC_SCALE

  • SQL_DESC_DATA_PTR

  • SQL_DESC_OCTET_LENGTH_PTR

  • SQL_DESC_INDICATOR_PTR

Note

Si un appel à SQLSetDescRec échoue, le contenu de l’enregistrement de descripteur identifié par l’argument RecNumber n’est pas défini.

Lors de la liaison d’une colonne ou d’un paramètre, SQLSetDescRec vous permet de modifier plusieurs champs affectant la liaison sans appeler SQLBindCol ou SQLBindParameter ou effectuer plusieurs appels à SQLSetDescField. SQLSetDescRec pouvez définir des champs sur un descripteur non actuellement associé à une instruction. Notez que SQLBindParameter définit plus de champs que SQLSetDescRec, peut définir des champs sur une APD et un IPD dans un appel et ne nécessite pas de handle de descripteur.

Note

L’attribut d’instruction SQL_ATTR_USE_BOOKMARKS doit toujours être défini avant d’appeler SQLSetDescRec avec un argument RecNumber de 0 pour définir les champs de signet. Bien que cela ne soit pas obligatoire, il est fortement recommandé.

Vérifications de cohérence

Une vérification de cohérence est effectuée automatiquement par le pilote chaque fois qu’une application définit le champ SQL_DESC_DATA_PTR d’une application APD, ARD ou IPD. Si l’un des champs est incohérent avec d’autres champs, SQLSetDescRec retourne SQLSTATE HY021 (informations de descripteur incohérentes).

Chaque fois qu’une application définit le champ SQL_DESC_DATA_PTR d’un champ APD, ARD ou IPD, le pilote vérifie que la valeur du champ SQL_DESC_TYPE et les valeurs applicables à ce champ SQL_DESC_TYPE sont valides et cohérentes. Cette vérification est toujours effectuée lorsque SQLBindParameter ou SQLBindCol est appelée ou lorsque SQLSetDescRec est appelé pour un APD, ARD ou IPD. Cette vérification de cohérence inclut les vérifications suivantes sur les champs de descripteur :

  • Le champ SQL_DESC_TYPE doit être l’un des types SQL ou C ODBC valides ou un type SQL spécifique au pilote. Le champ SQL_DESC_CONCISE_TYPE doit être l’un des types ODBC C ou SQL valides ou un type C ou SQL spécifique au pilote, y compris les types datetime et intervalle concis.

  • Si le champ d’enregistrement SQL_DESC_TYPE est SQL_DATETIME ou SQL_INTERVAL, le champ SQL_DESC_DATETIME_INTERVAL_CODE doit être l’un des codes datetime ou intervalle valides. (Consultez la description du champ SQL_DESC_DATETIME_INTERVAL_CODE dans SQLSetDescField.)

  • Si le champ SQL_DESC_TYPE indique un type numérique, les champs SQL_DESC_PRECISION et SQL_DESC_SCALE sont vérifiés comme valides.

  • Si le champ SQL_DESC_CONCISE_TYPE est un type de données time ou timestamp, un type d’intervalle avec un composant en secondes ou l’un des types de données d’intervalle avec un composant de temps, le champ SQL_DESC_PRECISION est vérifié comme étant une précision de seconde valide.

  • Si le SQL_DESC_CONCISE_TYPE est un type de données d’intervalle, le champ SQL_DESC_DATETIME_INTERVAL_PRECISION est vérifié comme une valeur de précision de début d’intervalle valide.

Le champ SQL_DESC_DATA_PTR d’un IPD n’est normalement pas défini ; Toutefois, une application peut le faire pour forcer une vérification de cohérence des champs IPD. Une vérification de cohérence ne peut pas être effectuée sur un IRD. La valeur à laquelle le champ SQL_DESC_DATA_PTR de l’ADRESSE IPD n’est pas réellement stockée et ne peut pas être récupérée par un appel à SQLGetDescField ou SQLGetDescRec; le paramètre est effectué uniquement pour forcer la vérification de cohérence.

Pour plus d’informations sur Voir
Liaison d’une colonne fonction SQLBindCol
Liaison d’un paramètre fonction SQLBindParameter
Obtention d’un seul champ de descripteur fonction SQLGetDescField
Obtention de plusieurs champs de descripteur fonction SQLGetDescRec
Définition de champs de descripteur unique fonction SQLSetDescField

Voir aussi

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