Fonction JetSetColumn

S’applique à : Windows | Windows Server

Fonction JetSetColumn

La fonction JetSetColumn modifie une valeur de colonne unique dans un enregistrement modifié à insérer ou à 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 tout 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 donner une valeur columnid égale à 0 (zéro). Lorsque columnid 0 (zéro) est donné, toutes les colonnes balisé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 les 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 contient les options à utiliser pour cet appel, qui incluent zéro ou plusieurs des éléments suivants :

Valeur	Signification
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 il n’est pas nécessaire de connaître la taille de la valeur de colonne existante.
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, c’est comme si la valeur longue existante avait été définie sur 0 (zéro) longueur avant de définir les nouvelles données.
JET_bitSetRevertToDefaultValue	Cette option s’applique uniquement aux colonnes balisées, éparses ou à valeurs multiples. La colonne retourne alors 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 permet de forcer le stockage d’une valeur longue, colonnes de type JET_coltypLongText ou JET_coltypLongBinary, 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 séparé de la valeur longue. Notez que les valeurs longues de quatre octets de taille inférieure ne peuvent pas être forcées d’ê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 comme un nombre entier d’octets à définir comme longueur de la valeur longue décrite par le columnid donné et, le cas échéant, le numéro de séquence dans psetinfo-itagSequence>. Si la taille indiqué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 est tronquée.
JET_bitSetUniqueMultiValues	Cette option permet d’appliquer que toutes les valeurs d’une colonne à valeurs multiples sont distinctes. Cette option compare les données de colonne source, sans transformations, à 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 permet d’appliquer que toutes les valeurs d’une colonne à valeurs multiples sont distinctes. Cette option compare la transformation normalisée par clé des données de colonne à d’autres valeurs de colonne existantes 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 une longueur nulle. 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 faire la différence entre 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 est définie sur NULL. Toutefois, si la colonne est une colonne balisée de longueur fixe, la longueur de colonne est définie sur 0. Lorsque la colonne balisée de longueur fixe est définie sur 0 longueur, les tentatives de récupération de la colonne avec JetRetrieveColumn ou JetRetrieveColumns réussissent, mais la longueur réelle retournée dans le paramètre cbActual est 0.
JET_bitSetIntrinsicLV	Cette option est utilisée pour stocker la valeur longue entière 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 lors de la tentative de 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 valeur ibLongValue de 0 (zéro) avaient été données. Cela oblige le jeu 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	Signification
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 existante, la valeur donnée est à nouveau 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 renvoyée

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 Erreurs du moteur de stockage extensible et Paramètres de gestion des erreurs.

Code de retour	Description
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 sur le instance associée à la session ont cessé à la suite d’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 de mise à jour d’une valeur longue a été effectuée lors d’une opération de mise à jour d’origine de suppression de copie 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ée pour des colonnes texte ou binaire de longueur fixe. Cette erreur est également retournée lors du passage de plus de 1 024 octets de données pour une colonne longue et de la définition de l’indicateur JET_bitSetIntrinsicLV.
JET_errInstanceUnavailable	Il n’est pas possible d’effectuer l’opération, car le instance associé à 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 sera retournée uniquement par Windows XP et les versions ultérieures.
JET_errInvalidBufferSize	La taille de données de la 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 de mise à jour d’une colonne d’incrément automatique a été effectuée lors d’une opération d’insertion ou de mise à jour, ou de mise à jour d’une colonne de version lors d’une opération de remplacement.
JET_errInvalidgrbit	Les options fournies sont inconnues ou une combinaison non conforme 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 set column a tenté de créer une valeur en double et a spécifié JET_bitSetUniqueMultiValues ou JET_bitSetUniqueNormalizedMultiValues.
JET_errNotInitialized	Il n’est pas possible d’effectuer l’opération, car le instance associé à la session n’a pas encore été initialisé.
JET_errNotInTransaction	Une tentative non conforme 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 cela aurait entraîné le dépassement de la limite de taille de la page liée à la taille de la page. 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 d’enregistrement. Même les colonnes longues nécessitent 5 octets d’espace dans l’enregistrement en tant que liaison, ce qui peut également entraîner le retour de JET_errRecordTooBig.
JET_errRestoreInProgress	Il n’est pas possible d’effectuer l’opération, car une opération de restauration est en cours sur le instance associé à 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 sera retournée uniquement par Windows XP et les versions ultérieures.
JET_errTermInProgress	Il n’est pas possible d’effectuer l’opération, car le instance associé à la session est en cours d’arrêt.
JET_errUpdateNotPrepared	Le curseur n’est actuellement 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 peut avoir é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.

Notes

La définition de valeurs longues, valeurs pour les colonnes JET_coltypLongBinary de type JET_coltypLongText ou JET_coltypLongBinary, ne doit être effectuée que lorsque la session appelante est 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 entièrement 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 annulant la transaction de session.

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

La taille d’un enregistrement est limitée en fonction de la taille de la page de base de données. Toutes les valeurs longues de l’enregistrement supérieures à cinq octets sont stockées séparément de l’enregistrement si les données de l’enregistrement dépassent sa limite à la suite d’une opération JetSetColumn . Le JET_errRecordTooBig d’erreur n’est retourné 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

Condition requise	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