Compartilhar via


Função JetRenameColumn

Aplica-se a: Windows | Windows Server

Função JetRenameColumn

A função JetRenameColumn pode ser usada para alterar o nome de uma coluna existente em uma tabela.

Windows XP:JetRenameColumn é introduzido no Windows XP.

    JET_ERR JET_API JetRenameColumn(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          JET_PCSTR szName,
      __in          JET_PCSTR szNameNew,
      __in          JET_GRBIT grbit
    );

Parâmetros

sesid

A sessão a ser usada para essa chamada.

Tableid

O cursor a ser usado para essa chamada.

szName

O nome atual da coluna que será renomeada.

szNameNew

O novo nome para a coluna que será renomeada.

grbit

Esse parâmetro deve ser 0.

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 concluída com sucesso.

JET_errClientRequestToStopJetService

Não é possível concluir a operação porque todas as atividades na instância associada à sessão cessaram como resultado de uma chamada para JetStopService.

JET_errColumnNotFound

Esta coluna especificada não existe para esta tabela.

JET_errInvalidName

Um dos nomes de objeto especificados era inválido. Todos os nomes de objeto devem estar em conformidade com o mesmo conjunto de regras. Essas regras são as seguintes:

  • Os nomes de objeto devem ser compostos por caracteres ASCII.

  • Os nomes de objeto devem ter pelo menos um caractere de comprimento.

  • Os nomes de objetos não podem exceder JET_cbNameMost (64) caracteres de comprimento.

  • Os nomes de objeto podem não começar com um espaço – os nomes de objeto podem não conter caracteres de controle ASCII (0x00 por meio de 0x1F).

  • Os nomes de objeto podem não conter um ponto de exclamação (!), ponto (.), um caractere de colchete esquerdo ([) ou colchete direito (]).

  • Depois de validado, somente a parte da cadeia de caracteres até o primeiro espaço (se houver) será usada para o nome do objeto. Isso significa efetivamente que os nomes de objeto também podem não conter um espaço.

JET_errInvalidParameter

Um dos parâmetros fornecidos continha um valor inesperado ou continha um valor que não fazia sentido quando combinado com o valor de outro parâmetro. Isso pode acontecer para JetRenameColumn quando:

  • szName é NULL.

  • szNameNew é NULL.

JET_errInstanceUnavailable

Não é possível concluir a operação porque a instância associada à sessão encontrou um erro fatal que exige que o acesso a todos os dados seja revogado para proteger a integridade desses dados. Esse erro só será retornado pelo Windows XP e versões posteriores.

JET_errInTransaction

Essa operação só pode ser executada quando a sessão não está atualmente dentro de uma transação.

JET_errNotInitialized

Não é possível concluir a operação porque a instância associada à sessão ainda não foi inicializada.

JET_errRestoreInProgress

Não é possível concluir a operação porque uma operação de restauração está em andamento na instância associada à sessão.

JET_errSessionSharingViolation

A mesma sessão não pode ser usada para mais de um thread ao mesmo tempo. Esse erro só será retornado pelo Windows XP e versões posteriores.

JET_errTermInProgress

Não é possível concluir a operação porque a instância associada à sessão está sendo desligada.

JET_errTransReadOnly

Uma atualização não pode ser feita enquanto estiver dentro do escopo de uma transação somente leitura. Uma transação somente leitura é uma transação que foi iniciada usando uma chamada para JetBeginTransaction2 com JET_bitTransactionReadOnly. Esse erro só será retornado pelo Windows XP e versões posteriores.

Em caso de êxito, o nome da coluna especificada na tabela associada ao cursor é alterado permanentemente para o novo nome. Todos os índices que fazem referência a essa coluna também serão atualizados.

Em caso de falha, nenhuma alteração no estado do banco de dados ocorrerá.

Comentários

A operação de renomeação de coluna é incomum porque, ao contrário de outras operações de esquema, ela não é realizada como uma transação. Quando uma coluna em uma determinada tabela é renomeada em uma sessão, qualquer outra sessão usando essa tabela verá a alteração imediatamente, mesmo que elas estejam em uma transação que impeça essa sessão de ver qualquer outra alteração feita pela sessão fazendo a operação de renomeação.

A ID da coluna de uma coluna não é afetada pela operação de renomeação.

Requisitos

Requisito Valor

Cliente

Requer o Windows Vista ou o Windows XP.

Servidor

Requer o Windows Server 2008 ou o Windows Server 2003.

Cabeçalho

Declarado em Esent.h.

Biblioteca

Use ESENT.lib.

DLL

Requer ESENT.dll.

Unicode

Implementado como JetRenameColumnW (Unicode) e JetRenameColumnA (ANSI).

Consulte Também

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetBeginTransaction2