TCAlter

Altera a estrutura de uma tabela.

Sintaxe

TCAlter ( <cNome>, <aEstruturaAtual>, <aEstruturaNova>, [@nErro] ) --> lRet

Parâmetros / Elementos

Nome	Tipo	Descrição	Obrigatório	Referência
cNome	Caracter	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

lRet (lógico)

Após a execução da função TCAlter(), se o retorno for verdadeiro (.T.), a alteração foi realizada com sucesso e <nErro> será 0 (zero).

Caso, o retorno seja falso (.F.), deve-se verificar <nErro>. Se <nErro> ainda for nulo (NIL), a instrução de alteração da estrutura não passou pela pré-validação do Protheus, não sendo enviada ao banco. Caso não seja NIL, a instrução foi enviada ao banco de dados, e não obteve sucesso, sendo retornado na propriedade <nErro> o número da ocorrência do DBAccess relacionada ao erro.

Observações

É 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:
Campo inserido ( existe na nova estrutura, mas não existe na estrutura atual)
Campo eliminado ( existe na estrutura atual, mas não existe na nova estrutura )
Campo mantido ( existe em ambas as estruturas, com os mesmos atributos – tipo e tamanhos )
Campo alterado ( 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.

Exemplo

User Function ex_TCAlter()

Local cTableNAme := "TTABLE"
Local nTopErr := NIL
 
// conecta com o dbaccess
nStatus := tclink("POSTGRES/teste","192.168.189.128")
 
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

Árvore de páginas

TCAlter