Função JetAddColumn

  • Artigo

Aplica-se a: Windows | Windows Server

Função JetAddColumn

A função JetAddColumn adiciona uma nova coluna a uma tabela existente em um banco de dados 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

O contexto de sessão de banco de dados a ser usado para a chamada à API.

Tableid

A tabela à qual adicionar a coluna.

szColumnName

O nome da coluna a ser adicionada. O nome deve atender aos seguintes critérios:

  • Ele deve ter menos de JET_cbNameMost caracteres de comprimento, não incluindo o NULL de terminação.

  • Ele deve conter caracteres somente dos seguintes conjuntos: 0 a 9, A a Z, a a z e todas as outras pontuações, exceto o ponto de exclamação (!), vírgula (,), colchete de abertura ([) e colchete de fechamento (]) — ou seja, caracteres ASCII 0x20, 0x22 0x2d, 0x2f 0x5a, 0x5c e 0x5d por meio de 0x7f.

  • Ele não pode começar com um espaço.

  • Ele deve conter pelo menos um caractere que não seja de espaço.

pcolumndef

Um ponteiro para uma estrutura JET_COLUMNDEF , que define os dados que podem ser armazenados em uma coluna.

pvDefault

Um ponteiro para um buffer que contém o valor padrão da coluna. O comprimento do buffer é cbDefault. Se não houver nenhum padrão, defina pvDefault como NULL e cbDefault como zero. Os valores padrão não podem ser maiores do que JET_cbColumnMost bytes para colunas fixas ou bytes JET_cbLVDefaultValueMost para valores longos. Se um valor padrão for maior que isso, ele será truncado silenciosamente.

Se grbit tiver JET_bitColumnUserDefinedDefault definido, pvDefault será interpretado como um ponteiro para uma estrutura JET_USERDEFINEDDEFAULT .

cbDefault

O tamanho, em bytes, do buffer especificado em pvDefault.

pcolumnid

Um ponteiro para uma estrutura JET_COLUMNID que, com êxito, receberá o identificador da coluna recém-criada. Em caso de falha, o valor é indefinido.

Valor Retornado

Essa função retorna o tipo de dados JET_ERR com um dos seguintes códigos de retorno. Para obter mais informações sobre os possíveis erros do ESE, consulte Erros extensíveis do mecanismo de armazenamento e parâmetros de tratamento de erros.

Código de retorno

Descrição

JET_errSuccess

A operação foi bem-sucedida.

JET_errFixedDDL

Foi feita uma tentativa de modificar a definição de dados de uma tabela DDL fixa. Um exemplo de uma tabela com DDL fixa é uma Tabela de Modelo.

JET_errInvalidParameter

Um parâmetro inválido foi passado para a API. Alguns exemplos de parâmetros inválidos são:

  • Passar o tamanho errado da estrutura JET_COLUMNDEF em seu membro cbStruct .

  • Passando JET_bitColumnUserDefinedDefault, mas não definindo cbDefault como sizeof(JET_USERDEFINEDDEFAULT).

JET_errInTransaction

Foi feita uma tentativa de adicionar uma coluna com o conjunto de bits JET_bitColumnUnversioned, mas a sessão está atualmente em uma transação.

JET_errColumnDuplicate

Uma coluna já existe. Foi feita uma tentativa de adicionar uma coluna sem informações de versão e essa coluna já existe.

JET_errTableNotEmpty

A tabela contém dados. Uma coluna Escrow Update só pode ser adicionada a uma tabela vazia.

JET_errRecordTooBig

O disco é muito grande. A soma do parâmetro cbMax para as colunas fixas não deve exceder um determinado valor.

JET_errTooManyColumns

Foi feita uma tentativa de adicionar muitas colunas à tabela. Uma tabela não pode ter mais do que JET_ccolFixedMost colunas fixas, não mais do que JET_ccolVarMost colunas de comprimento variável e não mais do que JET_ccolTaggedMost colunas marcadas.

JET_errColumnRedundant

Foi feita uma tentativa de adicionar uma coluna redundante. Não deve haver mais de uma coluna decremento automático e não mais do que uma coluna de versão por tabela.

JET_errCallbackNotResolved

A função de retorno de chamada não pôde ser resolvida. A DLL pode não ter sido encontrada ou a função na DLL pode não ter sido encontrada. O log de eventos fornecerá mais detalhes se o log suficiente estiver habilitado.

JET_wrnColumnMaxTruncated

Um aviso que indica que o comprimento máximo (cbMax) de uma coluna fixa ou variável foi maior que JET_cbColumnMost. Esse limite não se aplica a Valores Longos (ou seja , JET_coltypLongBinary e JET_coltypLongText).

JET_errInvalidName

Um nome inválido foi passado como szColumnName. Para obter mais informações sobre as restrições, consulte os critérios para szColumnName.

JET_errInvalidColumnType

O campo coltyp não foi definido como um tipo de coluna válido.

JET_errInvalidCodePage

O parâmetro cp da estrutura JET_COLUMNDEF não foi definido como uma página de código válida. Os únicos valores válidos para colunas de texto são inglês (1252) e Unicode (1200). Um valor igual a 0 significa que o padrão será usado (inglês, 1252).

JET_errTaggedNotNULL

JET_bitColumnNotNULL não pode ser usado com colunas marcadas, Valor Longo ou SLV.

JET_errInvalidgrbit

Uma combinação inválida de grbits foi especificada. Alguns dos motivos para esse erro são:

  • JET_bitColumnFixed foi usado em uma coluna marcada, Valor Longo ou SLV.

  • JET_bitColumnEscrowUpdate foi usado em uma coluna que não era do tipo JET_coltypLong.

  • JET_bitColumnEscrowUpdate foi usado em uma coluna Version (JET_bitColumnVersion).

  • JET_bitColumnEscrowUpdate foi usado em uma coluna AutoIncrememnt (JET_bitColumnAutoincrement).

  • JET_bitColumnEscrowUpdate foi usado em uma coluna que não tinha um valor padrão (cbDefault era igual a zero).

  • JET_bitColumnFinalize foi usado em uma coluna que não era uma coluna Escrow Update (JET_bitColumnEscrowUpdate não foi definido).

  • JET_bitColumnDeleteOnZero foi usado em uma coluna que não era uma coluna Escrow Update (JET_bitColumnEscrowUpdate não foi definido).

  • JET_bitColumnAutoincrement foi usado em uma coluna que não foi JET_coltypLong.

    Windows 2000: Esse motivo para o código de erro é usado apenas no Windows 2000.

    JET_bitColumnAutoincrement foi usado em uma coluna que não era JET_coltypLong nem JET_coltypCurrency.

    Windows XP: Esse motivo para o código de erro é usado em sistemas operacionais Windows XP e posteriores.

  • JET_bitColumnVersion foi usado em uma coluna que não foi JET_coltypLong.

  • JET_bitColumnVersion foi usado em uma coluna de autoincremento.

  • JET_bitColumnUserDefinedDefault foi usado em conjunto com JET_bitColumnFixed.

  • JET_bitColumnUserDefinedDefault foi usado em conjunto com JET_bitColumnNotNULL.

  • JET_bitColumnUserDefinedDefault foi usado em conjunto com JET_bitColumnVersion.

  • JET_bitColumnUserDefinedDefault foi usado em conjunto com JET_bitColumnAutoincrement.

  • JET_bitColumnUserDefinedDefault foi usado em conjunto com JET_bitColumnUpdatable.

  • JET_bitColumnUserDefinedDefault foi usado em conjunto com JET_bitColumnEscrowUpdate.

  • JET_bitColumnUserDefinedDefault foi usado em conjunto com JET_bitColumnFinalize.

  • JET_bitColumnUserDefinedDefault foi usado em conjunto com JET_bitColumnDeleteOnZero.

  • JET_bitColumnUserDefinedDefault foi usado em conjunto com JET_bitColumnMaybeNull.

  • JET_bitColumnUserDefinedDefault foi usado em uma coluna não marcada (que é fixa ou variável).

JET_errMultiValuedColumnMustBeTagged

Uma coluna de vários valores (JET_bitColumnMultiValued) só pode ser usada em uma coluna marcada ou valor longo (JET_coltypLongBinary ou JET_coltypLongText).

JET_errCannotBeTagged

Foi feita uma tentativa de usar uma coluna marcada quando a coluna pode não ser marcada. Algumas das restrições para não permitir colunas marcadas são:

  • Uma coluna Escrow Update (JET_bitColumnEscrowUpdate) não pode ser usada em uma coluna marcada ou valor longo (JET_coltypLongBinary ou JET_coltypLongText).

  • Uma coluna de autoincremento pode não ser marcada.

  • Uma coluna Versão pode não ser marcada.

JET_errExclusiveTableLockRequired

Um bloqueio exclusivo na tabela era necessário para essa operação.

JET_wrnColumnMaxTruncated

Um aviso que indica que o comprimento máximo (cbMax) de uma coluna fixa ou variável foi maior que JET_cbColumnMost. Esse limite não se aplica a Valores Longos (ou seja , JET_coltypLongBinary e JET_coltypLongText).

Requisitos

Requisito Valor

Cliente

Requer Windows Vista, Windows XP ou Windows 2000 Professional.

Servidor

Requer o Windows Server 2008, o Windows Server 2003 ou o Windows 2000 Server.

Cabeçalho

Declarado em Esent.h.

Biblioteca

Use ESENT.lib.

DLL

Requer ESENT.dll.

Unicode

Implementado como JetAddColumnW (Unicode) e JetAddColumnA (ANSI).

Consulte Também

JET_COLTYP
JET_COLUMNCREATE
JET_COLUMNDEF
JET_COLUMNID
JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetCreateTableColumnIndex
JetCreateTableColumnIndex2