Fonction JetAddColumn

Article
06/12/2023

S’applique à : Windows | Windows Server

Fonction JetAddColumn

La fonction JetAddColumn ajoute une nouvelle colonne à une table existante dans une base de données ESE.

    JET_ERR JET_API JetAddColumn(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          JET_PCSTR szColumnName,
      __in          const JET_COLUMNDEF* pcolumndef,
      __in_opt      const void* pvDefault,
      __in          unsigned long cbDefault,
      __out_opt     JET_COLUMNID* pcolumnid
    );

Paramètres

sesid

Contexte de session de base de données à utiliser pour l’appel d’API.

tableid

Table à laquelle ajouter la colonne.

szColumnName

Nom de la colonne à ajouter. Le nom doit répondre aux critères suivants :

Il doit contenir moins de JET_cbNameMost caractères, sans compter la valeur NULL de fin.
Elle doit contenir uniquement des caractères des jeux suivants : 0 à 9, A à Z, a à z et toutes les autres ponctuations à l’exception du point d’exclamation (!), de la virgule (,), du crochet ouvrant ([) et du crochet fermant (]), c’est-à-dire des caractères ASCII 0x20, 0x22 par 0x2d, 0x2f par 0x5a, 0x5c et 0x5d par 0x7f.
Il ne peut pas commencer par un espace.
Il doit contenir au moins un caractère autre que l’espace.

pcolumndef

Pointeur vers une structure JET_COLUMNDEF , qui définit les données pouvant être stockées dans une colonne.

pvDefault

Pointeur vers une mémoire tampon qui contient la valeur par défaut de la colonne. La longueur de la mémoire tampon est cbDefault. S’il n’y a pas de valeur par défaut, définissez pvDefault sur NULL et cbDefault sur zéro. Les valeurs par défaut ne peuvent pas être supérieures à JET_cbColumnMost octets pour les colonnes fixes ou JET_cbLVDefaultValueMost octets pour les valeurs longues. Si une valeur par défaut est supérieure à celle-ci, elle est tronquée en mode silencieux.

Si grbit a JET_bitColumnUserDefinedDefault défini, pvDefault est interprété comme un pointeur vers une structure JET_USERDEFINEDDEFAULT .

cbDefault

Taille, en octets, de la mémoire tampon spécifiée dans pvDefault.

pcolumnid

Pointeur vers une structure JET_COLUMNID qui, en cas de réussite, recevra l’identificateur de la colonne nouvellement créée. En cas d’échec, la valeur n’est pas définie.

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 a réussi.
JET_errFixedDDL	Une tentative a été effectuée pour modifier la définition des données d’une table DDL fixe. Un exemple de table avec DDL fixe est une table de modèle.
JET_errInvalidParameter	Un paramètre non valide a été passé dans l’API. Voici quelques exemples de paramètres non valides : Passage de la taille incorrecte de la structure JET_COLUMNDEF dans son membre cbStruct . Passage de JET_bitColumnUserDefinedDefault, mais pas définition de cbDefault sur sizeof(JET_USERDEFINEDDEFAULT).
JET_errInTransaction	Une tentative d’ajout d’une colonne avec le JET_bitColumnUnversioned jeu de bits, mais la session se trouve actuellement dans une transaction.
JET_errColumnDuplicate	Une colonne existe déjà. Une tentative d’ajout d’une colonne sans informations de version a été effectuée, et cette colonne existe déjà.
JET_errTableNotEmpty	La table contient des données. Une colonne Mise à jour d’entiercement ne peut être ajoutée qu’à une table vide.
JET_errRecordTooBig	Le disque est trop grand. La somme du paramètre cbMax pour les colonnes fixes ne doit pas dépasser une certaine valeur.
JET_errTooManyColumns	Une tentative d’ajout d’un trop grand nombre de colonnes à la table a été effectuée. Une table ne peut pas avoir plus de JET_ccolFixedMost colonnes fixes, pas plus de JET_ccolVarMost colonnes de longueur variable et pas plus de JET_ccolTaggedMost colonnes balisées.
JET_errColumnRedundant	Une tentative d’ajout d’une colonne redondante a été effectuée. Il ne doit pas y avoir plus d’une colonne de création automatique et pas plus d’une colonne de version par table.
JET_errCallbackNotResolved	La fonction de rappel n’a pas pu être résolue. La DLL n’a peut-être pas été trouvée ou la fonction dans la DLL n’a peut-être pas été trouvée. Le journal des événements fournit plus de détails si une journalisation suffisante est activée.
JET_wrnColumnMaxTruncated	Avertissement indiquant que la longueur maximale (cbMax) d’une colonne fixe ou variable est supérieure à JET_cbColumnMost. Cette limite ne s’applique pas aux valeurs longues (c’est-à-dire JET_coltypLongBinary et JET_coltypLongText).
JET_errInvalidName	Un nom non valide a été passé en tant que szColumnName. Pour plus d’informations sur les restrictions, consultez les critères de szColumnName.
JET_errInvalidColumnType	Le champ coltyp n’a pas été défini sur un type de colonne valide.
JET_errInvalidCodePage	Le paramètre cp de la structure JET_COLUMNDEF n’a pas été défini sur une page de codes valide. Les seules valeurs valides pour les colonnes de texte sont Anglais (1252) et Unicode (1200). La valeur 0 signifie que la valeur par défaut sera utilisée (anglais, 1252).
JET_errTaggedNotNULL	JET_bitColumnNotNULL ne peut pas être utilisé avec des colonnes étiquetées, valeur longue ou SLV.
JET_errInvalidgrbit	Une combinaison non valide de grbits a été spécifiée. Voici quelques-unes des raisons de cette erreur : JET_bitColumnFixed a été utilisé sur une colonne étiquetée, Valeur longue ou SLV. JET_bitColumnEscrowUpdate a été utilisé sur une colonne qui n’était pas de type JET_coltypLong. JET_bitColumnEscrowUpdate a été utilisé sur une colonne Version (JET_bitColumnVersion). JET_bitColumnEscrowUpdate a été utilisé sur une colonne AutoIncrememnt (JET_bitColumnAutoincrement). JET_bitColumnEscrowUpdate a été utilisé sur une colonne qui n’avait pas de valeur par défaut (cbDefault était égal à zéro). JET_bitColumnFinalize a été utilisé sur une colonne qui n’était pas une colonne mise à jour d’entiercement (JET_bitColumnEscrowUpdate n’a pas été défini). JET_bitColumnDeleteOnZero a été utilisé sur une colonne qui n’était pas une colonne mise à jour d’entiercement (JET_bitColumnEscrowUpdate n’a pas été défini). JET_bitColumnAutoincrement a été utilisé sur une colonne qui n’était pas JET_coltypLong. Windows 2000 : Cette raison pour laquelle le code d’erreur est utilisé uniquement dans Windows 2000. JET_bitColumnAutoincrement a été utilisé sur une colonne qui n’était ni JET_coltypLong ni JET_coltypCurrency. Windows XP : Cette raison du code d’erreur est utilisé dans Windows XP et les systèmes d’exploitation ultérieurs. JET_bitColumnVersion a été utilisé sur une colonne qui n’était pas JET_coltypLong. JET_bitColumnVersion a été utilisé sur une colonne de création automatique. JET_bitColumnUserDefinedDefault a été utilisé conjointement avec JET_bitColumnFixed. JET_bitColumnUserDefinedDefault a été utilisé conjointement avec JET_bitColumnNotNULL. JET_bitColumnUserDefinedDefault a été utilisé conjointement avec JET_bitColumnVersion. JET_bitColumnUserDefinedDefault a été utilisé conjointement avec JET_bitColumnAutoincrement. JET_bitColumnUserDefinedDefault a été utilisé conjointement avec JET_bitColumnUpdatable. JET_bitColumnUserDefinedDefault a été utilisé conjointement avec JET_bitColumnEscrowUpdate. JET_bitColumnUserDefinedDefault a été utilisé conjointement avec JET_bitColumnFinalize. JET_bitColumnUserDefinedDefault a été utilisé conjointement avec JET_bitColumnDeleteOnZero. JET_bitColumnUserDefinedDefault a été utilisé conjointement avec JET_bitColumnMaybeNull. JET_bitColumnUserDefinedDefault a été utilisé sur une colonne non marquée (qui est fixe ou variable).
JET_errMultiValuedColumnMustBeTagged	Une colonne à valeurs multiples (JET_bitColumnMultiValued) ne peut être utilisée que sur une colonne étiquetée ou longue (JET_coltypLongBinary ou JET_coltypLongText).
JET_errCannotBeTagged	Une tentative d’utilisation d’une colonne étiquetée a été effectuée lorsque la colonne n’est peut-être pas étiquetée. Voici quelques-unes des contraintes permettant d’interdire les colonnes étiquetées : Une colonne Mise à jour de l’entiercement (JET_bitColumnEscrowUpdate) ne peut pas être utilisée sur une colonne étiquetée ou longue (JET_coltypLongBinary ou JET_coltypLongText). Il se peut qu’une colonne d’incréation automatique ne soit pas étiquetée. Il est possible qu’une colonne Version ne soit pas étiquetée.
JET_errExclusiveTableLockRequired	Un verrou exclusif sur la table était requis pour cette opération.
JET_wrnColumnMaxTruncated	Avertissement indiquant que la longueur maximale (cbMax) d’une colonne fixe ou variable était supérieure à JET_cbColumnMost. Cette limite ne s’applique pas aux valeurs longues (c’est-à-dire JET_coltypLongBinary et JET_coltypLongText).

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.
Unicode	Implémenté en tant que JetAddColumnW (Unicode) et JetAddColumnA (ANSI).

Voir aussi

JET_COLTYP
JET_COLUMNCREATE
JET_COLUMNDEF
JET_COLUMNID
JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetCreateTableColumnIndex
JetCreateTableColumnIndex2

Fonction JetAddColumn