Função JetRenameColumn

Artigo
06/13/2023

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

Função JetRenameColumn