JetSetColumn, fonction

s’applique à : Windows | Windows Server

JetSetColumn, fonction

La fonction JetSetColumn modifie une valeur de colonne unique dans un enregistrement modifié à insérer ou pour mettre à jour l’enregistrement actif. Il peut remplacer une valeur existante, ajouter une nouvelle valeur à une séquence de valeurs dans une colonne à valeurs multiples, supprimer une valeur d’une séquence de valeurs dans une colonne à valeurs multiples, ou mettre à jour toutes ou partie d’une valeur longue, une colonne de type JET_coltypLongText ou JET_coltypLongBinary.

    JET_ERR JET_API JetSetColumn(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          JET_COLUMNID columnid,
      __in_opt      const void* pvData,
      __in          unsigned long cbData,
      __in          JET_GRBIT grbit,
      __in_opt      JET_SETINFO* psetinfo
    );

Paramètres

sesid

Session à utiliser pour cet appel.

tableid

Curseur à utiliser pour cet appel.

columnid

JET_COLUMNID de la colonne à récupérer. Vous pouvez également attribuer une valeur columnid de 0 (zéro). Lorsque columnid 0 (zéro) est donné, toutes les colonnes marquées, les colonnes éparses et les colonnes à valeurs multiples, sont traitées comme une seule colonne. Cela facilite la récupération de toutes les colonnes éparses présentes dans un enregistrement.

pvData

Mémoire tampon d’entrée contenant des données à utiliser pour la valeur de colonne.

cbData

Taille en octets de la mémoire tampon d’entrée.

grbit

Groupe de bits qui contiennent les options à utiliser pour cet appel, qui incluent zéro ou plusieurs des éléments suivants :

Valeur	Sens
JET_bitSetAppendLV	Cette option permet d’ajouter des données à une colonne de type JET_coltypLongText ou JET_coltypLongBinary. Le même comportement peut être obtenu en déterminant la taille de la valeur longue existante et en spécifiant ibLongValue dans psetinfo. Toutefois, il est plus simple d’utiliser ce grbit , car la connaissance de la taille de la valeur de colonne existante n’est pas nécessaire.
JET_bitSetOverwriteLV	Cette option est utilisée pour remplacer la valeur longue existante par les données nouvellement fournies. Lorsque cette option est utilisée, elle est comme si la valeur longue existante a été définie sur 0 (zéro) avant de définir les nouvelles données.
JET_bitSetRevertToDefaultValue	Cette option s’applique uniquement aux colonnes étiquetées, éparses ou à valeurs multiples. La colonne retourne la valeur de colonne par défaut lors des opérations de récupération de colonne suivantes. Toutes les valeurs de colonne existantes sont supprimées.
JET_bitSetSeparateLV	Cette option est utilisée pour forcer une valeur longue, des colonnes de type JET_coltypLongText ou JET_coltypLongBinary, à stocker séparément du reste des données d’enregistrement. Cela se produit normalement lorsque la taille de la valeur longue l’empêche d’être stockée avec les données d’enregistrement restantes. Toutefois, cette option peut être utilisée pour forcer le stockage de la valeur longue séparément. Notez que les valeurs longues de quatre octets de taille inférieure ne peuvent pas être forcées à être séparées. Dans ce cas, l’option est ignorée.
JET_bitSetSizeLV	Cette option permet d’interpréter la mémoire tampon d’entrée en tant que nombre entier d’octets à définir comme longueur de la valeur longue décrite par la colonne donnée et, si elle est fournie, le numéro de séquence dans psetinfo-itagSequence>. Si la taille donnée est supérieure à la valeur de colonne existante, la colonne est étendue avec 0s. Si la taille est inférieure à la valeur de colonne existante, la valeur sera tronquée.
JET_bitSetUniqueMultiValues	Cette option est utilisée pour appliquer que toutes les valeurs d’une colonne à valeurs multiples sont distinctes. Cette option compare les données de colonne source, sans aucune transformation, à d’autres valeurs de colonne existantes et une erreur est retournée si un doublon est trouvé. Si cette option est donnée, JET_bitSetAppendLV, JET_bitSetOverwriteLV et JET_bitSetSizeLV ne peuvent pas également être donnés.
JET_bitSetUniqueNormalizedMultiValues	Cette option est utilisée pour appliquer que toutes les valeurs d’une colonne à valeurs multiples sont distinctes. Cette option compare la transformation normalisée clé des données de colonne, à d’autres valeurs de colonne transformées de la même façon et une erreur est retournée si un doublon est trouvé. Si cette option est donnée, JET_bitSetAppendLV, JET_bitSetOverwriteLV et JET_bitSetSizeLV ne peuvent pas également être donnés.
JET_bitSetZeroLength	Cette option est utilisée pour définir une valeur sur zéro longueur. Normalement, une valeur de colonne est définie sur NULL en passant un cbMax de 0 (zéro). Toutefois, pour certains types, comme JET_coltypText, une valeur de colonne peut être de 0 (zéro) longueur au lieu de NULL, et cette option est utilisée pour différencier la longueur NULL et 0 (zéro). Note En général, si la colonne est une colonne de longueur fixe, ce bit est ignoré et la colonne a la valeur NULL. Toutefois, si la colonne est une colonne étiquetée de longueur fixe, la longueur de la colonne est définie sur 0. Lorsque la colonne étiquetée de longueur fixe est définie sur 0, tente de récupérer la colonne avec JetRetrieveColumn ou JetRetrieveColumns réussit, mais la longueur réelle retournée dans le paramètre cbActual est 0.
JET_bitSetIntrinsicLV	Cette option est utilisée pour stocker l’intégralité de la valeur longue dans l’enregistrement.
JET_bitSetCompressed	Cette option est utilisée pour tenter la compression des données lors du stockage des données. Windows 7 : JET_bitSetCompressed est introduit dans Windows 7.
JET_bitSetUncompressed	Cette option n’est pas utilisée pour tenter la compression lors du stockage des données. Windows 7 : JET_bitSetUnCompressed est introduit dans Windows 7.

psetinfo

Pointeur vers des paramètres d’entrée facultatifs qui peuvent être définis pour cette fonction à l’aide de la structure JET_SETINFO .

Si psetinfo est donné comme NULL , la fonction se comporte comme si une itagSequence de 1 et une ibLongValue de 0 (zéro) ont été données. Cela entraîne l’ensemble de colonnes à définir la première valeur d’une colonne à valeurs multiples et à définir des données longues à partir du décalage 0 (zéro).

Les options suivantes peuvent être définies pour ce paramètre :

Valeur	Sens
ibLongValue	Décalage binaire dans une valeur de colonne longue où les données de jeu doivent commencer.
itagSequence	Numéro de séquence de la valeur de colonne à valeurs multiples souhaitée à définir. Si itagSequence est défini sur 0 (zéro), la valeur fournie doit être ajoutée à la fin de la séquence de valeurs à valeurs multiples. Si le numéro de séquence fourni est supérieur à la dernière valeur à valeurs multiples existantes, la valeur donnée est ajoutée à la fin de la séquence de valeurs. Si le numéro de séquence correspond à une valeur existante, cette valeur est remplacée par la valeur donnée.

Valeur

Sens

ibLongValue

Décalage binaire dans une valeur de colonne longue où les données de jeu doivent commencer.

itagSequence

Numéro de séquence de la valeur de colonne à valeurs multiples souhaitée à définir. Si itagSequence est défini sur 0 (zéro), la valeur fournie doit être ajoutée à la fin de la séquence de valeurs à valeurs multiples. Si le numéro de séquence fourni est supérieur à la dernière valeur à valeurs multiples existantes, la valeur donnée est ajoutée à la fin de la séquence de valeurs. Si le numéro de séquence correspond à une valeur existante, cette valeur est remplacée par la valeur donnée.

Valeur de retour

Cette fonction retourne le type de données JET_ERR avec l’un des codes de retour suivants. Pour plus d’informations sur les erreurs ESE possibles, consultez Les erreurs du moteur de stockage extensible et les paramètres de gestion des erreurs.

Code de retour	Descriptif
JET_errSuccess	L’opération s’est terminée avec succès.
JET_errBadColumnId	L’ID de colonne donné est en dehors des limites légales d’un ID de colonne.
JET_errClientRequestToStopJetService	Il n’est pas possible d’effectuer l’opération, car toutes les activités associées à la session ont cessé suite à un appel à JetStopService.
JET_errColumnNotFound	La colonne décrite par le columnid donné n’existe pas dans la table.
JET_errColumnNotUpdatable	Une tentative illégale a été effectuée pour mettre à jour une valeur longue pendant une opération de suppression de copie d’origine d’insertion.
JET_errColumnTooBig	Les données de valeur de colonne données dans la mémoire tampon d’entrée dépassent la limite de taille naturelle pour une colonne de longueur fixe ou configurées pour le texte de longueur fixe ou les colonnes binaires. Cette erreur est également retournée lors de la transmission de plus de 1024 octets de données pour une colonne longue et la définition de l’indicateur de JET_bitSetIntrinsicLV.
JET_errInstanceUnavailable	Il n’est pas possible d’effectuer l’opération, car l’instance associée à la session a rencontré une erreur irrécupérable qui exige que l’accès à toutes les données soit révoqué pour protéger l’intégrité de ces données. Windows XP : Cette erreur ne sera retournée que par Windows XP et versions ultérieures.
JET_errInvalidBufferSize	La taille de données de valeur de colonne donnée ne correspond pas à ce qui est naturel pour le type de données de longueur fixe.
JET_errInvalidColumnType	Une tentative illégale a été effectuée pour mettre à jour une colonne incrémentée automatiquement pendant une opération d’insertion ou de mise à jour, ou pour mettre à jour une colonne de version pendant une opération de remplacement.
JET_errInvalidgrbit	Les options fournies sont inconnues ou une combinaison illégale de paramètres de bits connus.
JET_errInvalidParameter	Le psetinfo-cbStruct> donné n’est pas une taille valide pour la structure JET_SETINFO .
JET_errMultiValuedDuplicate	L’opération de colonne set a tenté de créer une valeur en double et spécifiée JET_bitSetUniqueMultiValues ou JET_bitSetUniqueNormalizedMultiValues.
JET_errNotInitialized	Il n’est pas possible d’effectuer l’opération, car l’instance associée à la session n’a pas encore été initialisée.
JET_errNotInTransaction	Une tentative illégale a été effectuée pour mettre à jour une valeur de colonne longue lorsque la session appelante n’était pas dans une transaction.
JET_errNullInvalid	Une tentative illégale a été effectuée pour définir une colonne non NULL sur NULL.
JET_errColumnIllegalNull	Identique à JET_errNullInvalid.
JET_errRecordTooBig	La valeur de colonne n’a pas pu être définie sur la valeur dans la mémoire tampon d’entrée, car elle aurait provoqué le dépassement de la taille liée à la taille de l’enregistrement. Les colonnes de type JET_coltypLongText ou JET_coltypLongBinary peuvent être stockées séparément des données d’enregistrement restantes. Toutefois, d’autres colonnes doivent être stockées avec l’enregistrement et peuvent entraîner le dépassement de la limite de taille de l’enregistrement. Même les colonnes longues nécessitent 5 octets d’espace dans l’enregistrement en tant que liaison et cela peut également entraîner JET_errRecordTooBig être retourné.
JET_errRestoreInProgress	Il n’est pas possible d’effectuer l’opération, car une opération de restauration est en cours sur l’instance associée à la session.
JET_errSessionSharingViolation	La même session ne peut pas être utilisée pour plusieurs threads en même temps. Windows XP : Cette erreur ne sera retournée que par Windows XP et versions ultérieures.
JET_errTermInProgress	Il n’est pas possible d’effectuer l’opération, car l’instance associée à la session est arrêtée.
JET_errUpdateNotPrepared	Le curseur n’est pas en cours d’insertion d’un nouvel enregistrement ou de mise à jour d’un enregistrement existant.
JET_errVersionStoreOutOfMemory	Cette erreur se produit lorsque la taille configurée du magasin de versions est insuffisante pour contenir toutes les mises à jour en attente.
JET_wrnColumnMaxTruncated	La valeur de colonne dans la mémoire tampon d’entrée a dépassé la longueur maximale configurée pour une colonne de longueur variable et a été tronquée.

En cas de réussite, la partie souhaitée d’une valeur de colonne pour la colonne donnée est définie avec les données copiées à partir de la mémoire tampon d’entrée. Le jeu de données a peut-être été tronqué s’il a dépassé la longueur maximale spécifiée pour une colonne de longueur variable.

En cas d’échec, l’emplacement du curseur reste inchangé et aucune donnée de valeur de colonne n’est mise à jour dans la mémoire tampon de copie.

Remarques

La définition de valeurs longues, de valeurs pour les colonnes JET_coltypLongBinary de type JET_coltypLongText ou de JET_coltypLongBinary, doit être effectuée uniquement lorsque la session appelante se trouve dans une transaction. Si la session appelante n’est pas dans une transaction, les modifications apportées aux valeurs longues stockées séparément peuvent être validées complètement même lorsque l’opération de mise à jour est annulée ultérieurement. Si la session appelante se trouve dans une transaction, les effets de la mise à jour peuvent être entièrement restaurés en annulant la mise à jour et en rétablissant la transaction de session.

Les mises à jour d’index ne sont pas effectuées suite aux opérations JetSetColumn . Au lieu de cela, les index sont mis à jour uniquement une fois toutes les modifications de colonne terminées et JetUpdate est appelé. Cela permet la mise à jour la plus efficace des index lorsque les index impliquent plusieurs colonnes modifiées.

Un enregistrement est limité en fonction de la taille de la page de base de données. Toutes les valeurs longues de l’enregistrement supérieures à cinq octets seront stockées séparément de l’enregistrement si les données de l’enregistrement dépassent sa limite en raison d’une opération JetSetColumn . L’erreur JET_errRecordTooBig ne sera retournée qu’une fois que toutes les données de colonne d’enregistrement séparables ont été stockées séparément de l’enregistrement et que l’enregistrement dépasse toujours la limite de taille d’enregistrement.

Spécifications

Besoin	Valeur
Client	Nécessite Windows Vista, Windows XP ou Windows 2000 Professionnel.
Serveur	Nécessite Windows Server 2008, Windows Server 2003 ou Windows 2000 Server.
En-tête	Déclaré dans Esent.h.
Bibliothèque	Utilisez ESENT.lib.
DLL	Nécessite ESENT.dll.

Voir aussi

JET_COLUMNID
JET_ERR
JET_SESID
JET_TABLEID
JET_SETINFO
JetRetrieveColumn
JetSetColumns

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2025-06-10

Partager via

JetSetColumn, fonction