Retornando a coleção de campos de um Histórico via objeto Fields no E3

Introdução

O objeto Fields (HistFieldsCollection) do Histórico foi introduzido na versão 5.0 do Elipse E3 com o propósito de retornar a coleção de campos de um Histórico. Este pode ser manipulado não só em modo Studio mas também em tempo de execução (runtime), o que proporciona uma maior flexibilidade na criação, edição e automatização de objetos históricos. O objeto Fields pode ser acessado através da propriedade Fields do Histórico.

Objeto Coleção (HistFieldsCollection)

Em primeiro lugar, uma Coleção (objeto do tipo HistFieldsCollection) permite o uso da sintaxe for/each. Seus métodos/propriedades são os seguintes:

Count: (long) Retorna a quantidade de campos da coleção.
Item(Index): (objeto) Retorna o campo (objeto tipo HistField, ver a seguir*) com o nome ou índice Index (baseado em 1) especificado.
AddField(Name, SourceLink, Type, Size): (objeto) Retorna o objeto criado (ou Nothing no caso de erro). Todos parâmetros são opcionais. Então, se omitido, o nome padrão é “Campo” (auto incrementado se necessário), o tipo padrão é Integer (1), o tamanho padrão é 0 e o Link padrão.
DeleteField(Index): Exclui o campo com o nome ou índice Index (baseado em 1) especificado. Por isso, o campo E3Timestamp criado automaticamente pelo E3 não pode ser removido.

Objeto Campos (HistField*)

Logo após, temos os objetos dos campos (do tipo HistField*), que têm as seguintes propriedades (equivalentes às colunas Nome, Chave, Tipo, Fonte e Tamanho, na mesma ordem em que aparecem no Editor do objeto Hist):

Name: (string) Nome do campo. Anteriormente, seu valor poderia ser Null, Empty, Nothing, Application, True e False, mas a partir da v5.0, esses nomes não poderão mais ser atribuídos ao criar ou modificar um campo.
PrimaryKey: (bool) Indica se o campo deve ser utilizado na definição da chave primária do histórico.
Type: (enum FieldTypes) Tipo do campo.
Link: (string) Expressão que vai ser avaliada/registrada no campo.
Size: (long) Tamanho do campo (normalmente usado em strings). Não pode ser negativo.

Não é possível fazer qualquer mudança (adicionar/remover campos, mudar as propriedades do campos, etc.) com o objeto Hist que contém a coleção/campo ativo. Todavia, todas propriedades e campos podem ser acessados para leitura. Em tabelas de usuário, apenas a propriedade Link dos campos pode ser modificada, e novos campos não podem ser inseridos (no entanto, eles podem ser apagados, como acontece pelo Editor/View).

Para salvar as alterações em tempo de execução, utilize o método Save(); em seguida, atualize o arquivo de projeto no Studio.

Método AddField

Este método adiciona um novo Campo de Histórico no objeto Fields e então retorna o objeto criado. Em caso de erro, este método retorna Nothing. Todos os parâmetros deste método são opcionais.

 
Sub CommandButton1_Click()
set hist = Application.GetObject("Hist1")
set camp = hist.Fields
 hist.Deactivate()
  
 'AddField(Name, SourceLink, Type, Size):    
 set field1 = camp.AddField("Campo_1","Data.TagDemo1.Value",1,20)
 field1.PrimaryKey = True

hist.Activate()
hist.Save()
End Sub

Método DeleteField(Index)

Remove o Campo de Histórico informado no parâmetro Index; este, então, pode ser a posição do Campo de Histórico (iniciando em um) ou o valor da propriedade Name do Campo de Histórico, se este Campo de Histórico existir no objeto Fields. Caso contrário, este método retorna um erro de script.

Sub CommandButton2_Click()
 set hist = Application.GetObject("Hist1")
 set camp = hist.Fields
   
   hist.Deactivate()
   if camp.count > 1 then 
     s=""
     for each j in camp
        if j.Name <> "E3TimeStamp" then
          s = s & " Name : " & j.Name & chr(10) & chr(13)
          camp.DeleteField j.Name 
        end if   
     next  
     hist.Activate()
     msgbox "Deleted Fields: " & chr(10) & chr(13) & s     
   end if 
   hist.Save()
End Sub

No anexo, há uma aplicação exemplo que foi desenvolvida no Elipse E3 v5.0.437 e que ilustra o funcionamento do objeto Fields.

Para maiores detalhes sobre o uso do CustomConfig (presente na aplicação exemplo), verifique o artigo CustomConfig de objetos ElipseX.

Anexos:

HistFields.zip

Retornando a coleção de campos de um Histórico utilizando o objeto Fields no Elipse E3.