Função JetAddColumn

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