Funzione JetAddColumn

Articolo
06/13/2023

Si applica a: Windows | Windows Server

Funzione JetAddColumn

La funzione JetAddColumn aggiunge una nuova colonna a una tabella esistente in un database 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
    );

Parametri

sesid

Contesto della sessione di database da usare per la chiamata API.

tableid

Tabella a cui aggiungere la colonna.

szColumnName

Nome della colonna da aggiungere. Il nome deve soddisfare i criteri seguenti:

Deve essere minore di JET_cbNameMost caratteri in lunghezza, non inclusa la terminazione NULL.
Deve contenere caratteri solo dai set seguenti: da 0 a 9, da A a Z, da z a z e da tutti gli altri punti di punteggiatura tranne per punto esclamativo (!), virgola (),parentesi quadre ([) e chiusura parentesi quadre (]), ovvero caratteri ASCII 0x20, 0x22 attraverso 0x2d, 0x2f attraverso 0x5a, 0x5c e 0x5d attraverso 0x7f.
Non può iniziare con uno spazio.
Deve contenere almeno un carattere non spazio.

pcolumndef

Puntatore a una struttura JET_COLUMNDEF , che definisce i dati che possono essere archiviati in una colonna.

pvDefault

Puntatore a un buffer contenente il valore predefinito per la colonna. La lunghezza del buffer è cbDefault. Se non esiste alcuna impostazione predefinita, impostare pvDefault su NULL e cbDefault su zero. I valori predefiniti non possono essere maggiori di JET_cbColumnMost byte per colonne fisse o JET_cbLVDefaultValueMost byte per valori lunghi. Se un valore predefinito è maggiore di quello, verrà troncato in modo invisibile all'utente.

Se grbit ha JET_bitColumnUserDefinedDefault impostato, pvDefault verrà interpretato come puntatore a una struttura JET_USERDEFINEDDEFAULT .

cbDefault

Dimensioni, in byte, del buffer specificato in pvDefault.

pcolumnid

Puntatore a una struttura JET_COLUMNID che, in caso di esito positivo, riceverà l'identificatore della colonna appena creata. In caso di errore, il valore non è definito.

Valore restituito

Questa funzione restituisce il tipo di dati JET_ERR con uno dei codici restituiti seguenti. Per altre informazioni sugli errori ESE possibili, vedere Errori del motore di archiviazione estendibili e parametri di gestione degli errori.

Codice restituito	Descrizione
JET_errSuccess	L'operazione è stata completata.
JET_errFixedDDL	È stato effettuato un tentativo di modificare la definizione dei dati di una tabella DDL fissa. Un esempio di tabella con DDL fisso è una tabella modello.
JET_errInvalidParameter	Un parametro non valido è stato passato all'API. Alcuni esempi di parametri non validi sono: Passando le dimensioni sbagliate della struttura JET_COLUMNDEF nel membro cbStruct . Passando JET_bitColumnUserDefinedDefault, ma non impostando cbDefault su sizeof(JET_USERDEFINEDDEFAULT).
JET_errInTransaction	È stato eseguito un tentativo di aggiungere una colonna con il set di bit JET_bitColumnUnversioned, ma la sessione è attualmente in una transazione.
JET_errColumnDuplicate	Esiste già una colonna. È stato eseguito un tentativo di aggiungere una colonna senza informazioni sulla versione e tale colonna esiste già.
JET_errTableNotEmpty	La tabella contiene dati. Una colonna Di aggiornamento escrow può essere aggiunta solo a una tabella vuota.
JET_errRecordTooBig	Il record è troppo grande. La somma del parametro cbMax per le colonne fisse non deve superare un determinato valore.
JET_errTooManyColumns	È stato effettuato un tentativo di aggiungere troppe colonne alla tabella. Una tabella non può avere più di JET_ccolFixedMost colonne fisse, non più di JET_ccolVarMost colonne a lunghezza variabile e non più di JET_ccolTaggedMost colonne contrassegnate.
JET_errColumnRedundant	È stato effettuato un tentativo di aggiungere una colonna ridondante. Non deve essere presente più di una colonna autoincrement e non più di una colonna di versione per tabella.
JET_errCallbackNotResolved	Impossibile risolvere la funzione di callback. La DLL potrebbe non essere stata trovata o la funzione nella DLL potrebbe non essere stata trovata. Il registro eventi fornisce altri dettagli se è abilitata la registrazione sufficiente.
JET_wrnColumnMaxTruncated	Avviso che indica che la lunghezza massima (cbMax) di una colonna fissa o variabile è maggiore di JET_cbColumnMost. Questo limite non si applica ai valori lunghi, ovvero JET_coltypLongBinary e JET_coltypLongText.
JET_errInvalidName	Un nome non valido è stato passato come szColumnName. Per altre informazioni sulle restrizioni, vedere i criteri per szColumnName.
JET_errInvalidColumnType	Il campo coltyp non è stato impostato su un tipo di colonna valido.
JET_errInvalidCodePage	Il parametro cp della struttura JET_COLUMNDEF non è stato impostato su una tabella codici valida. Gli unici valori validi per le colonne di testo sono inglese (1252) e Unicode (1200). Un valore pari a 0 indica che il valore predefinito verrà usato (inglese, 1252).
JET_errTaggedNotNULL	JET_bitColumnNotNULL non può essere usato con colonne tag, Long Value o SLV.
JET_errInvalidgrbit	È stata specificata una combinazione non valida di grbit . Alcuni dei motivi per questo errore sono: JET_bitColumnFixed è stato usato in una colonna con tag, Long Value o SLV. JET_bitColumnEscrowUpdate è stato usato in una colonna che non era di tipo JET_coltypLong. JET_bitColumnEscrowUpdate è stato usato in una colonna Version (JET_bitColumnVersion). JET_bitColumnEscrowUpdate è stato usato in una colonna AutoIncrememnt (JET_bitColumnAutoincrement). JET_bitColumnEscrowUpdate è stato usato in una colonna che non ha un valore predefinito (cbDefault è uguale a zero). JET_bitColumnFinalize è stato usato in una colonna che non era una colonna Escrow Update (JET_bitColumnEscrowUpdate non è stata impostata). JET_bitColumnDeleteOnZero è stato usato in una colonna che non era una colonna Escrow Update (JET_bitColumnEscrowUpdate non è stata impostata). JET_bitColumnAutoincrement è stato usato in una colonna non JET_coltypLong. Windows 2000: Questo motivo per il codice di errore viene usato solo in Windows 2000. JET_bitColumnAutoincrement è stato usato in una colonna che non era JET_coltypLong né JET_coltypCurrency. Windows XP: Questo motivo per il codice di errore viene usato in Windows XP e nei sistemi operativi successivi. JET_bitColumnVersion è stato usato in una colonna non JET_coltypLong. JET_bitColumnVersion è stato usato in una colonna autoincrement. JET_bitColumnUserDefinedDefault è stato usato insieme a JET_bitColumnFixed. JET_bitColumnUserDefinedDefault è stato usato insieme a JET_bitColumnNotNULL. JET_bitColumnUserDefinedDefault è stato usato insieme a JET_bitColumnVersion. JET_bitColumnUserDefinedDefault è stato usato insieme a JET_bitColumnAutoincrement. JET_bitColumnUserDefinedDefault è stato usato insieme a JET_bitColumnUpdatable. JET_bitColumnUserDefinedDefault è stato usato insieme a JET_bitColumnEscrowUpdate. JET_bitColumnUserDefinedDefault è stato usato in combinazione con JET_bitColumnFinalize. JET_bitColumnUserDefinedDefault è stato usato insieme a JET_bitColumnDeleteOnZero. JET_bitColumnUserDefinedDefault è stato usato insieme a JET_bitColumnMaybeNull. JET_bitColumnUserDefinedDefault è stato usato in una colonna non contrassegnata, ovvero fissa o variabile.
JET_errMultiValuedColumnMustBeTagged	Una colonna multivalore (JET_bitColumnMultiValued) può essere usata solo in una colonna con tag o valore lungo (JET_coltypLongBinary o JET_coltypLongText).
JET_errCannotBeTagged	È stato eseguito un tentativo di usare una colonna contrassegnata quando la colonna potrebbe non essere contrassegnata. Alcuni dei vincoli per la disabilitazione delle colonne contrassegnate sono: Impossibile usare una colonna Di aggiornamento escrow (JET_bitColumnEscrowUpdate) in una colonna con tag o valore lungo (JET_coltypLongBinary o JET_coltypLongText). Una colonna autoincrement potrebbe non essere contrassegnata. Una colonna Version potrebbe non essere contrassegnata.
JET_errExclusiveTableLockRequired	Per questa operazione è stato necessario un blocco esclusivo sulla tabella.
JET_wrnColumnMaxTruncated	Avviso che indica che la lunghezza massima (cbMax) di una colonna fissa o variabile è maggiore di JET_cbColumnMost. Questo limite non si applica ai valori lunghi, ovvero JET_coltypLongBinary e JET_coltypLongText.

Requisiti

Requisito	Valore
Client	Richiede Windows Vista, Windows XP o Windows 2000 Professional.
Server	Richiede Windows Server 2008, Windows Server 2003 o Windows 2000 Server.
Intestazione	Dichiarato in Esent.h.
Libreria	Usare ESENT.lib.
DLL	Richiede ESENT.dll.
Unicode	Implementato come JetAddColumnW (Unicode) e JetAddColumnA (ANSI).

Vedere anche

JET_COLTYP
JET_COLUMNCREATE
JET_COLUMNDEF
JET_COLUMNID
JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetCreateTableColumnIndex
JetCreateTableColumnIndex2

Condividi tramite

Funzione JetAddColumn