Fonction JetAddColumn

S’applique à : Windows | Windows Serveurs

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 la 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 respecter les critères suivants :

  • Sa longueur doit être inférieure à JET_cbNameMost caractères, à l’exclusion de la valeur null de fin.

  • Il ne doit contenir que des caractères issus des jeux suivants : de 0 à 9, de A à Z, de a à z et toutes les autres signes de ponctuation, à l’exception du point d’exclamation ( ! ), de la virgule (,), du crochet ouvrant () et du [ crochet fermant ( ] ).

  • Il ne peut pas commencer par un espace.

  • Il doit contenir au moins un caractère autre qu’un espace.

pcolumndef

Pointeur vers une structure JET_COLUMNDEF , qui définit les données qui peuvent ê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, affectez la valeur null à pvDefault et cbDefault à zéro. Les valeurs par défaut ne peuvent pas être supérieures à JET_cbColumnMost octets pour les colonnes fixes ou les octets JET_cbLVDefaultValueMost pour les valeurs longues. Si une valeur par défaut est supérieure à celle-ci, elle sera 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, reçoit l’identificateur de la colonne qui vient d’être 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 de modification de la définition des données d’une table DDL fixe a été effectuée. Une table de modèle est un exemple de table avec une DDL fixe.

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 .

  • Le passage de JET_bitColumnUserDefinedDefault, mais pas la définition de cbDefault sur sizeof (JET_USERDEFINEDDEFAULT).

JET_errInTransaction

Une tentative a été effectuée pour ajouter une colonne avec le bit JET_bitColumnUnversioned défini, mais la session est 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 de mise à jour de tiers de confiance ne peut être ajoutée qu’à une table vide.

JET_errRecordTooBig

L’enregistrement est trop volumineux. 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 comporter plus de JET_ccolFixedMost colonnes fixes, ni plus de JET_ccolVarMost colonnes de longueur variable, ni plus de JET_ccolTaggedMost colonnes avec balises.

JET_errColumnRedundant

Une tentative d’ajout d’une colonne redondante a été effectuée. Il ne doit y avoir qu’une seule colonne AutoIncrement et pas plus d’une colonne 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 la journalisation suffisante est activée.

JET_wrnColumnMaxTruncated

Un 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 ( 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 pour szColumnName.

JET_errInvalidColumnType

Le champ coltyp n’est pas 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 l’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 avec balises, de valeurs longues 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 avec balises, une valeur longue ou une colonne 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 de version (JET_bitColumnVersion).

  • JET_bitColumnEscrowUpdate a été utilisé sur une colonne AutoIncrememnt (JET_bitColumnAutoincrement).

  • JET_bitColumnEscrowUpdate a été utilisé sur une colonne qui n’a pas de valeur par défaut (cbDefault était égal à zéro).

  • JET_bitColumnFinalize a été utilisé sur une colonne qui n’est pas une colonne de mise à jour de dépôt (JET_bitColumnEscrowUpdate n’a pas été définie).

  • JET_bitColumnDeleteOnZero a été utilisé sur une colonne qui n’est pas une colonne de mise à jour de dépôt (JET_bitColumnEscrowUpdate n’a pas été définie).

  • JET_bitColumnAutoincrement a été utilisé sur une colonne qui n’a pas été JET_coltypLonge.

    Windows 2000 : cette raison du code d’erreur est utilisée 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ée dans les systèmes d’exploitation Windows XP et versions ultérieures.

  • JET_bitColumnVersion a été utilisé sur une colonne qui n’a pas été JET_coltypLonge.

  • JET_bitColumnVersion a été utilisé sur une colonne AutoIncrement.

  • 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 balisée (qui est fixe ou variable).

JET_errMultiValuedColumnMustBeTagged

Une colonne à valeurs multiples (JET_bitColumnMultiValued) peut uniquement être utilisée sur une colonne avec balises ou de valeurs longues (JET_coltypLongBinary ou JET_coltypLongText).

JET_errCannotBeTagged

Une tentative d’utilisation d’une colonne avec balises a été effectuée lorsque la colonne n’est peut-être pas référencée. Voici quelques-unes des contraintes pour interdire les colonnes avec balises :

  • Une colonne de mise à jour de dépôt (JET_bitColumnEscrowUpdate) ne peut pas être utilisée sur une colonne avec balises ou de valeurs longues (JET_coltypLongBinary ou JET_coltypLongText).

  • Une colonne AutoIncrement ne peut pas être référencée.

  • Une colonne de version n’est peut-être pas référencée.

JET_errExclusiveTableLockRequired

Un verrou exclusif sur la table était requis pour cette opération.

JET_wrnColumnMaxTruncated

Un 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 ( JET_coltypLongBinary et JET_coltypLongText).

Spécifications

Condition requise Valeur

Client

requiert Windows Vista, Windows XP ou Windows 2000 Professional.

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

Requiert 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