Поделиться через


Функция JetAddColumn

Применимо к: 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_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