Partage via

SQLSetDescRec, fonction

  • Article

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

Résumé
La fonction SQLSetDescRec définit plusieurs champs de descripteur qui affectent le type de données et la mémoire tampon liés aux données d’une colonne ou d’un 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] Handle de descripteur. 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 à partir de 0, 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 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 de 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 de descripteur.

DataPtr
[Entrée ou sortie différée] Valeur à laquelle définir le champ SQL_DESC_DATA_PTR pour l’enregistrement de 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 dans l’argument DescriptorHandle est associé à un ARD, cela dissocie la colonne.

StringLengthPtr
[Entrée ou sortie différée] Valeur à laquelle définir le champ SQL_DESC_OCTET_LENGTH_PTR pour l’enregistrement de 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 de descripteur. IndicatorPtr peut être défini sur un pointeur null pour définir le champ SQL_DESC_INDICATOR_PTR sur un pointeur null.

Retours

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

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 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.)
07009 Index de descripteur non valide L’argument RecNumber a été défini sur 0, et le 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 APD, IPD ou ARD.

L’argument RecNumber était égal à 0, et l’argument DescriptorHandle faisait référence à un APD implicitement alloué. (Cette erreur ne se produit pas avec un descripteur d’application explicitement alloué, car on ne sait pas si un descripteur d’application explicitement alloué est un APD ou un ARD jusqu’au moment de l’exécution.)
08S01 Échec de la liaison de communication La liaison de communication entre le pilote et la source de données à laquelle le pilote a été connecté a échoué avant que la fonction n’ait terminé le traitement.
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 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 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) Le DescriptorHandle était associé à un StatementHandle pour lequel une fonction d’exécution asynchrone (et non celle-ci) était appelée et s’exécutait toujours lorsque cette fonction était appelée.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos a été appelé pour l’InstructionHandle à laquelle le DescriptorHandle a été associé et retourné 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.

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

(DM) SQLExecute, SQLExecDirect ou SQLMoreResults a été appelé pour l’un des handles d’instruction associés au DescriptorHandle et a renvoyé 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.
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.
HY016 Impossible de modifier un descripteur de ligne d’implémentation L’argument DescriptorHandle a été associé à un IRD.
HY021 Informations de descripteurs 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’étaient pas cohérentes. (Voir « Vérifications de cohérence », plus loin dans cette section.)
HY090 Chaîne ou longueur de mémoire tampon non valide (DM) Le pilote était un pilote ODBC 2.x , le descripteur était un ARD, l’argument ColumnNumber a été 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 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 associé au DescriptorHandle ne prend pas en charge la fonction.

Commentaires

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

  • 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

Notes

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 peut définir des champs sur un descripteur qui n’est actuellement pas associé à une instruction. Notez que SQLBindParameter définit plus de champs que SQLSetDescRec, peut définir des champs sur un APD et un IPD dans un seul appel, et ne nécessite pas de handle de descripteur.

Notes

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’un APD, d’un ARD ou d’un IPD. Si l’un des champs est incohérent avec d’autres champs, SQLSetDescRec renvoie 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é ou quand 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 ODBC C ou SQL 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 interval 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 interval valides. (Consultez la description du champ SQL_DESC_DATETIME_INTERVAL_CODE dans SQLSetDescField.)

  • Si le champ SQL_DESC_TYPE indique un type numérique, la validité des champs SQL_DESC_PRECISION et SQL_DESC_SCALE est vérifiée.

  • Si le champ SQL_DESC_CONCISE_TYPE est un type de données time ou timestamp, un type d’intervalle avec un composant 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 secondes 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 étant 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. Impossible d’effectuer une vérification de cohérence sur un IRD. La valeur sur laquelle le champ SQL_DESC_DATA_PTR de l’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 obtenir des informations sur Consultez
Liaison d’une colonne Fonction SQLBindCol
Liaison d’un paramètre Fonction SQLBindParameter
Obtention d’un champ de descripteur unique Fonction SQLGetDescField
Obtention de plusieurs champs de descripteur SQLGetDescRec, fonction
Définition de champs de descripteur unique SQLSetDescField, fonction

Voir aussi

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