Функция JetAddColumn

Статья
06/13/2023

Применимо к: Windows | Windows Server

Функция JetAddColumn

Функция JetAddColumn добавляет новый столбец в существующую таблицу в базе данных 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
    );

Параметры

sesid

Контекст сеанса базы данных, используемый для вызова API.

tableid

Таблица, в которую добавляется столбец.

szColumnName

Имя добавляемого столбца. Имя должно соответствовать следующим критериям:

Длина не должна превышать JET_cbNameMost символов, не включая завершающее значение NULL.
Он должен содержать только символы из следующих наборов: от 0 до 9, от A до Z, от a до z и всех других знаков препинания, кроме восклицательного знака (!), запятой (,), открывающей скобки ([) и закрывающей скобки (]), то есть символы ASCII 0x20, 0x22 через 0x2d, 0x2f через 0x5a, 0x5c и 0x5d через 0x7f.
Она не может начинаться с пробела.
Он должен содержать по крайней мере один символ, отличный от пробела.

pcolumndef

Указатель на структуру JET_COLUMNDEF , которая определяет данные, которые могут храниться в столбце.

pvDefault

Указатель на буфер, содержащий значение по умолчанию для столбца. Длина буфера — cbDefault. Если значение по умолчанию отсутствует, задайте для параметра pvDefaultзначение NULL , а для cbDefault — нулевое значение. Значения по умолчанию не могут превышать JET_cbColumnMost байт для фиксированных столбцов или JET_cbLVDefaultValueMost байтов для длинных значений. Если значение по умолчанию больше этого, оно будет автоматически усечено.

Если для grbit задано JET_bitColumnUserDefinedDefault, pvDefault будет интерпретироваться как указатель на структуру JET_USERDEFINEDDEFAULT .

cbDefault

Размер (в байтах) буфера, указанного в pvDefault.

pcolumnid

Указатель на структуру JET_COLUMNID , которая при успешном выполнении получает идентификатор только что созданного столбца. При сбое значение не определено.

Возвращаемое значение

Эта функция возвращает тип данных JET_ERR с одним из следующих кодов возврата. Дополнительные сведения о возможных ошибках ESE см. в разделах Ошибки подсистемы расширяемого хранилища и Параметры обработки ошибок.

Код возврата	Описание
JET_errSuccess	Операция выполнена успешно.
JET_errFixedDDL	Предпринята попытка изменить определение данных фиксированной таблицы DDL. Примером таблицы с фиксированным DDL является таблица шаблонов.
JET_errInvalidParameter	В API передан недопустимый параметр. Ниже приведены некоторые примеры недопустимых параметров. Передача неправильного размера структуры JET_COLUMNDEF в ее члене cbStruct . Передача JET_bitColumnUserDefinedDefault, но не установка параметра cbDefault в sizeof(JET_USERDEFINEDDEFAULT).
JET_errInTransaction	Предпринята попытка добавить столбец с набором битов JET_bitColumnUnversioned, но сеанс в настоящее время находится в транзакции.
JET_errColumnDuplicate	Столбец уже существует. Предпринята попытка добавить столбец без сведений о версии, и этот столбец уже существует.
JET_errTableNotEmpty	Таблица содержит данные. Столбец Escrow Update можно добавить только в пустую таблицу.
JET_errRecordTooBig	Запись слишком велика. Сумма параметра cbMax для фиксированных столбцов не должна превышать определенное значение.
JET_errTooManyColumns	Предпринята попытка добавить в таблицу слишком много столбцов. Таблица может содержать не более JET_ccolFixedMost фиксированных столбцов, не более JET_ccolVarMost столбцов переменной длины и не более JET_ccolTaggedMost столбцов с тегами.
JET_errColumnRedundant	Предпринята попытка добавить избыточный столбец. В каждой таблице должно быть не более одного столбца с автоматическим приращением и не более одного столбца версии.
JET_errCallbackNotResolved	Не удалось разрешить функцию обратного вызова. Возможно, библиотека DLL не найдена или функция в библиотеке DLL не найдена. В журнале событий будут предоставлены дополнительные сведения, если включено достаточное ведение журнала.
JET_wrnColumnMaxTruncated	Предупреждение, указывающее, что максимальная длина (cbMax) фиксированного или переменного столбца превышает JET_cbColumnMost. Это ограничение не применяется к длинным значениям ( то есть JET_coltypLongBinary и JET_coltypLongText).
JET_errInvalidName	В качестве szColumnName передано недопустимое имя. Дополнительные сведения об ограничениях см. в критериях для szColumnName.
JET_errInvalidColumnType	Для поля coltyp не задан допустимый тип столбца.
JET_errInvalidCodePage	Параметр cp структуры JET_COLUMNDEF не имеет допустимой кодовой страницы. Единственными допустимыми значениями текстовых столбцов являются английский (1252) и Юникод (1200). Значение 0 означает, что будет использоваться значение по умолчанию (английский язык, 1252).
JET_errTaggedNotNULL	JET_bitColumnNotNULL нельзя использовать со столбцами с тегами, длинными значениями или столбцами SLV.
JET_errInvalidgrbit	Указана недопустимая комбинация grbits . Ниже приведены некоторые причины этой ошибки. JET_bitColumnFixed использовался в столбце с тегами, длинном значении или столбце SLV. JET_bitColumnEscrowUpdate использовался для столбца, не являющегося типом JET_coltypLong. JET_bitColumnEscrowUpdate использовался в столбце Версии (JET_bitColumnVersion). JET_bitColumnEscrowUpdate использовался в столбце AutoIncrememnt (JET_bitColumnAutoincrement). JET_bitColumnEscrowUpdate использовался для столбца, который не имеет значения по умолчанию (cbDefault был равен нулю). JET_bitColumnFinalize использовался для столбца, который не был столбцом обновления escrow (JET_bitColumnEscrowUpdate не задан). JET_bitColumnDeleteOnZero использовался для столбца, который не был столбцом обновления escrow (JET_bitColumnEscrowUpdate не задан). JET_bitColumnAutoincrement использовался для столбца, который не был JET_coltypLong. Windows 2000: Эта причина кода ошибки используется только в Windows 2000. JET_bitColumnAutoincrement использовался для столбца, который не был ни JET_coltypLong , ни JET_coltypCurrency. Windows XP: Эта причина кода ошибки используется в Операционных системах Windows XP и более поздних версий. JET_bitColumnVersion использовался для столбца, который не был JET_coltypLong. JET_bitColumnVersion использовался в столбце с автоматическим приращением. JET_bitColumnUserDefinedDefault использовался в сочетании с JET_bitColumnFixed. JET_bitColumnUserDefinedDefault использовался в сочетании с JET_bitColumnNotNULL. JET_bitColumnUserDefinedDefault использовалась в сочетании с JET_bitColumnVersion. JET_bitColumnUserDefinedDefault использовался в сочетании с JET_bitColumnAutoincrement. JET_bitColumnUserDefinedDefault использовалась в сочетании с JET_bitColumnUpdatable. JET_bitColumnUserDefinedDefault использовалась в сочетании с JET_bitColumnEscrowUpdate. JET_bitColumnUserDefinedDefault использовалась в сочетании с JET_bitColumnFinalize. JET_bitColumnUserDefinedDefault использовался в сочетании с JET_bitColumnDeleteOnZero. JET_bitColumnUserDefinedDefault использовался в сочетании с JET_bitColumnMaybeNull. JET_bitColumnUserDefinedDefault использовался в столбце без тегов (который является фиксированным или переменным).
JET_errMultiValuedColumnMustBeTagged	Столбец с несколькими значениями (JET_bitColumnMultiValued) можно использовать только в столбце с тегами или столбце с длинным значением (JET_coltypLongBinary или JET_coltypLongText).
JET_errCannotBeTagged	Предпринята попытка использовать столбец с тегами, если столбец может не быть помечен. Ниже приведены некоторые ограничения для запрета столбцов с тегами. Столбец escrow Update (JET_bitColumnEscrowUpdate) нельзя использовать в столбце с тегами или столбце с длинным значением (JET_coltypLongBinary или JET_coltypLongText). Столбец с автоматическим приращением может не быть помечен тегом. Столбец Version может не быть помечен тегом.
JET_errExclusiveTableLockRequired	Для этой операции требовалась монопольная блокировка таблицы.
JET_wrnColumnMaxTruncated	Предупреждение, указывающее, что максимальная длина (cbMax) фиксированного или переменного столбца превышает JET_cbColumnMost. Это ограничение не применяется к длинным значениям ( то есть JET_coltypLongBinary и JET_coltypLongText).

Требования

Требование	Значение
Клиент	Требуется Windows Vista, Windows XP или Windows 2000 Профессиональная.
Сервер	Требуется Windows Server 2008, Windows Server 2003 или Windows 2000 Server.
Верхняя часть	Объявлено в Esent.h.
Библиотека	Используйте ESENT.lib.
DLL	Требуется ESENT.dll.
Юникод	Реализовано как JetAddColumnW (Юникод) и JetAddColumnA (ANSI).

См. также:

JET_COLTYP
JET_COLUMNCREATE
JET_COLUMNDEF
JET_COLUMNID
JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetCreateTableColumnIndex
JetCreateTableColumnIndex2

Функция JetAddColumn