Función JetAddColumn

Artículo
06/13/2023

Se aplica a: Windows | Windows Server

Función JetAddColumn

La función JetAddColumn agrega una nueva columna a una tabla existente en una base de datos 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
    );

Parámetros

sesid

Contexto de sesión de base de datos que se va a usar para la llamada API.

tableid

Tabla a la que se va a agregar la columna.

szColumnName

Nombre de la columna que se va a agregar. El nombre debe cumplir los siguientes criterios:

Debe tener menos de JET_cbNameMost caracteres de longitud, sin incluir el valor NULL de terminación.
Solo debe contener caracteres de los siguientes conjuntos: 0 a 9, A a Z, a a z y todos los demás signos de puntuación, excepto el signo de exclamación (!), coma (,), corchete de apertura ([) y corchete de cierre (]), es decir, caracteres ASCII 0x20, 0x22 a través de 0x2d, 0x2f a través de 0x5a, 0x5c y 0x5d a través de 0x7f.
No puede comenzar con un espacio.
Debe contener al menos un carácter que no sea de espacio.

pcolumndef

Puntero a una estructura JET_COLUMNDEF , que define los datos que se pueden almacenar en una columna.

pvDefault

Puntero a un búfer que contiene el valor predeterminado de la columna. La longitud del búfer es cbDefault. Si no hay ningún valor predeterminado, establezca pvDefault en NULL y cbDefault en cero. Los valores predeterminados no pueden ser mayores que JET_cbColumnMost bytes para columnas fijas o JET_cbLVDefaultValueMost bytes para valores largos. Si un valor predeterminado es mayor que eso, se truncará silenciosamente.

Si grbit tiene JET_bitColumnUserDefinedDefault establecido, pvDefault se interpretará como un puntero a una estructura JET_USERDEFINEDDEFAULT .

cbDefault

Tamaño, en bytes, del búfer especificado en pvDefault.

pcolumnid

Un puntero a una estructura JET_COLUMNID , que, si se ejecuta correctamente, recibirá el identificador de la columna recién creada. En caso de error, el valor no está definido.

Valor devuelto

Esta función devuelve el tipo de datos JET_ERR con uno de los siguientes códigos de retorno. Para obtener más información sobre los posibles errores de ESE, vea Extensible Storage Engine Errors and Error Handling Parameters.

Código devuelto	Descripción
JET_errSuccess	La operación se realizó correctamente.
JET_errFixedDDL	Se intentó modificar la definición de datos de una tabla DDL fija. Un ejemplo de una tabla con DDL fijo es una tabla de plantilla.
JET_errInvalidParameter	Se pasó un parámetro no válido a la API. Algunos ejemplos de parámetros no válidos son: Pasar el tamaño incorrecto de la estructura JET_COLUMNDEF en su miembro cbStruct . Pasar JET_bitColumnUserDefinedDefault, pero no establecer cbDefault en sizeof(JET_USERDEFINEDDEFAULT).
JET_errInTransaction	Se intentó agregar una columna con el conjunto de bits de JET_bitColumnUnversioned, pero la sesión se encuentra actualmente en una transacción.
JET_errColumnDuplicate	Ya existe una columna. Se intentó agregar una columna sin información de versión y esa columna ya existe.
JET_errTableNotEmpty	La tabla contiene datos. Una columna Actualización de custodia solo se puede agregar a una tabla vacía.
JET_errRecordTooBig	El registro es demasiado grande. La suma del parámetro cbMax para las columnas fijas no debe superar un valor determinado.
JET_errTooManyColumns	Se intentó agregar demasiadas columnas a la tabla. Una tabla no puede tener más de JET_ccolFixedMost columnas fijas, más de JET_ccolVarMost columnas de longitud variable y no más de JET_ccolTaggedMost columnas etiquetadas.
JET_errColumnRedundant	Se intentó agregar una columna redundante. No debe haber más de una columna de autoincremento y no más de una columna de versión por tabla.
JET_errCallbackNotResolved	No se pudo resolver la función de devolución de llamada. Es posible que no se haya encontrado el archivo DLL o que no se haya encontrado la función en el archivo DLL. El registro de eventos proporcionará más detalles si está habilitado el registro suficiente.
JET_wrnColumnMaxTruncated	Advertencia que indica que la longitud máxima (cbMax) de una columna fija o variable era mayor que JET_cbColumnMost. Este límite no se aplica a valores largos (es decir , JET_coltypLongBinary y JET_coltypLongText).
JET_errInvalidName	Se pasó un nombre no válido como szColumnName. Para obtener más información sobre las restricciones, consulte los criterios de szColumnName.
JET_errInvalidColumnType	El campo coltyp no se estableció en un tipo de columna válido.
JET_errInvalidCodePage	El parámetro cp de la estructura JET_COLUMNDEF no se estableció en una página de códigos válida. Los únicos valores válidos para las columnas de texto son Inglés (1252) y Unicode (1200). Un valor de 0 significa que se usará el valor predeterminado (inglés, 1252).
JET_errTaggedNotNULL	JET_bitColumnNotNULL no se puede usar con columnas etiquetadas, long value o SLV.
JET_errInvalidgrbit	Se especificó una combinación no válida de grbits . Algunos de los motivos de este error son: JET_bitColumnFixed se usó en una columna etiquetada, Valor largo o SLV. JET_bitColumnEscrowUpdate se usó en una columna que no era de tipo JET_coltypLong. JET_bitColumnEscrowUpdate se usó en una columna Versión (JET_bitColumnVersion). JET_bitColumnEscrowUpdate se usó en una columna AutoIncrememnt (JET_bitColumnAutoincrement). JET_bitColumnEscrowUpdate se usó en una columna que no tenía un valor predeterminado (cbDefault era igual a cero). JET_bitColumnFinalize se usó en una columna que no era una columna de actualización de custodia (no se estableció JET_bitColumnEscrowUpdate). JET_bitColumnDeleteOnZero se usó en una columna que no era una columna de actualización de custodia (no se estableció JET_bitColumnEscrowUpdate). JET_bitColumnAutoincrement se usó en una columna que no se JET_coltypLong. Windows 2000: Este motivo para el código de error solo se usa en Windows 2000. JET_bitColumnAutoincrement se usó en una columna que no era JET_coltypLong ni JET_coltypCurrency. Windows XP: Este motivo para el código de error se usa en Windows XP y en sistemas operativos posteriores. JET_bitColumnVersion se usó en una columna que no se JET_coltypLong. JET_bitColumnVersion se usó en una columna de autoincremento. JET_bitColumnUserDefinedDefault se usó junto con JET_bitColumnFixed. JET_bitColumnUserDefinedDefault se usó junto con JET_bitColumnNotNULL. JET_bitColumnUserDefinedDefault se usó junto con JET_bitColumnVersion. JET_bitColumnUserDefinedDefault se usó junto con JET_bitColumnAutoincrement. JET_bitColumnUserDefinedDefault se usó junto con JET_bitColumnUpdatable. JET_bitColumnUserDefinedDefault se usó junto con JET_bitColumnEscrowUpdate. JET_bitColumnUserDefinedDefault se usó junto con JET_bitColumnFinalize. JET_bitColumnUserDefinedDefault se usó junto con JET_bitColumnDeleteOnZero. JET_bitColumnUserDefinedDefault se usó junto con JET_bitColumnMaybeNull. JET_bitColumnUserDefinedDefault se usó en una columna no etiquetada (que es fija o variable).
JET_errMultiValuedColumnMustBeTagged	Una columna con varios valores (JET_bitColumnMultiValued) solo se puede usar en una columna etiquetada o de valor largo (JET_coltypLongBinary o JET_coltypLongText).
JET_errCannotBeTagged	Se intentó usar una columna etiquetada cuando es posible que la columna no se etiquete. Algunas de las restricciones para no permitir columnas etiquetadas son: No se puede usar una columna actualización de custodia (JET_bitColumnEscrowUpdate) en una columna etiquetada o de valor largo (JET_coltypLongBinary o JET_coltypLongText). Es posible que una columna de creación automática no se etiquete. Es posible que una columna Versión no se etiquete.
JET_errExclusiveTableLockRequired	Se requería un bloqueo exclusivo en la tabla para esta operación.
JET_wrnColumnMaxTruncated	Advertencia que indica que la longitud máxima (cbMax) de una columna fija o variable era mayor que JET_cbColumnMost. Este límite no se aplica a valores largos (es decir , JET_coltypLongBinary y JET_coltypLongText).

Requisitos

Requisito	Value
Cliente	Requiere Windows Vista, Windows XP o Windows 2000 Professional.
Servidor	Requiere Windows Server 2008, Windows Server 2003 o Windows 2000 Server.
Encabezado	Declarado en Esent.h.
Library	Use ESENT.lib.
Archivo DLL	Requiere ESENT.dll.
Unicode	Se implementa como JetAddColumnW (Unicode) y JetAddColumnA (ANSI).

Consulte también

JET_COLTYP
JET_COLUMNCREATE
JET_COLUMNDEF
JET_COLUMNID
JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetCreateTableColumnIndex
JetCreateTableColumnIndex2

Compartir a través de

Función JetAddColumn