Altera a estrutura de uma tabela.

Sintaxe

TCAlter( < cTable >, < aEstruturaAtual >, < aEstruturaNova >, [ @nErro ] )

Parâmetros

Nome

Tipo

Descrição

Obrigatório

Referência

cTable

caractere

Indica o nome da tabela que será alterada.

X


aEstruturaAtual

vetor

Indica o array que contém as informações dos campos atuais da tabela.

X


aEstruturaNova

vetor

Indica o array que contém a nova estrutura desejada para a tabela.

X


nErro

numérico

Caso ocorra algum erro na alteração da estrutura, o número do erro do DBAccess será retornado através desta variável.


X

Retorno

Nome

Tipo

Descrição

lRet

lógico

Retorna .T. se a alterção for realizada com sucesso, caso contrário, retorna .F.

É responsabilidade do programador passar a estrutura atual corretamente. Caso seja passada uma estrutura diferente da atual, pode haver perda de uma ou mais colunas da tabela.

A função determina internamente as ações a serem tomadas para adequar a estrutura atual para a nova estrutura informada, mantendo os dados na tabela. Nesta operação, dependendo do SGDB em questão, um ou mais índices existentes para a tabela podem ser apagados para que a operação seja completa.

Ao comparar as estruturas, são determinadas originalmente quatro ações para cada campo da estrutura

  • Coluna Inserida ( existe na nova estrutura, mas não existe na estrutura atual )
  • Coluna Eliminada ( existe na estrutura atual, mas não existe na nova estrutura )
  • Coluna Mantida ( existe em ambas as estruturas, com os mesmos atributos – tipo e tamanhos )
  • Coluna Alterada ( existe em ambas as estruturas, porém com tipo ou tamanho diferentes )

Na mudança de atributos em alteração de campo, a única conversão de tipo suportada é N (numérico) para C (caracter). Caso seja realizada uma conversão de tipo não suportada, todos os dados da coluna em questão serão apagados. A partir do DBAccess 20220303 (Build 22.1.1.0) e superiores, será suportada a conversão de campos C (caractere) para M (Memo), sem perder o conteúdo do campo, para os bancos de dados MSSQL, ORACLE e POSTGRES. O conteúdo do campo Caractere será convertido para Memo, apenas eliminando os espaços a direita do conteúdo atual.

Exemplos

USER FUNCTION ex_TCAlter()
  Local cTableNAme := "TTABLE"
  Local nTopErr := NIL
   
  // conecta com o dbaccess
  nStatus := TCLink()
   
  If nStatus < 0
   UserException("TOPCONN - Falha de conexao ["+str(nStatus,4)+"]")
  Endif
   
  // Array com a antiga estrutura
  aStru := {}
  aadd(aStru,{"CPO01","N",8,0})
  aadd(aStru,{"CPO02","N",10,0})
  aadd(aStru,{"CPO03","D",8,0})
   
  // Cria a tabela para o teste
  DbCreate(cTableName,aStru,"TOPCONN")
  // Array com a nova estrutura
  aNewStru := {}
  aadd(aNewStru,{"CPO01","C",8,0})
  aadd(aNewStru,{"CPO02","N",10,0})
  aadd(aNewStru,{"CPO03","D",8,0})
  
  bRet := TCAlter(cTableNAme,aStru,aNewStru, @ nTopErr)
  If !bRet
   MsgInfo(tcsqlerror(),"Erro no TCAlter!")
  Endif
RETURN

Veja também