Return field collection from the Historic with Fields object in Elipse E3

Introduction

The Historic’s Fields object (HistFieldsCollection) was introduced at version 5.0 of Elipse E3 in order to return the collection of fields in a Historic. It can be handled not only in Studio mode but also at run time, which allows for greater flexibility for developing, editing and automating historic objects. Fields object can be accessed via Historic’s Fields property.

Collection object (HistFieldsCollection)

First of all, a Collection (HistFieldsCollection object type) allows using for/each syntax. Its methods/properties are the following:

Count: (long) Returns the amount of fields in the collection.
Item(Index): (object) Returns the field ( HistField object time, see next*) with name or Index (based in 1) specified.
AddField(Name, SourceLink, Type, Size): (object) Returns the developed object (or Nothing, in case of error). All parameters are optional. Therefore, if omitted, the default name is “Field” (auto increased, if necessary), the default type is Integer (1), default size is 0, and Link is default.
DeleteField(Index): Excludes fields with specified name or Index (based on 1). Thus, the EsTimestamp field, auto generated by Elise E3, cannot be removed.

Fields object (HistField*)

Then, we have the objects of the field (HistField* object type), whose properties are the following (equivalent to columns Name, Switch, Type, Source and Field, in the same order they appear at Hist object’s editor):

Name: (string) Field name. Previously, its possible values were Null, Empty, Nothing, Application, True or False, but from version 5.0 on, these names can no longer be attributed when developing or changing a field.
PrimaryKey: (bool) Indicates whether the field must be used to establish the primary key in the Historic.
Type: (enum FieldTypes) Field type.
Link: (string) Expression that will be evaluated/recorded in the field.
Size: (long) Field’s size (commonly used for strings). It can’t be negative.

You can’t make any changes (add/remove fields, change properties in the fields, etc.) with Hist object, which contais the active collection/field. However, all properties and fields can be accessed for read only. In users table, only the Link property of the fields can be edited, and you can’t add new fields (on the other hand, you can erase them, such as what already happens via Editor/View).

In order to save the changes at run time, use Save() method; then, update the project file in Studio.

AddField method

This method adds a new Historic Field to the Fields object, and then it returns a developed object. In case of error, this method returns Nothing. All the parameters in this method are optional.

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

DeleteField(Index) method

Removes the Historic Field informed by Index parameter; thus, this can be the position of the Historic Field (starting in 1) or then the value of Name property of the Historic Field, if this Historic Field exists in the Fields object. Otherwise, this method returns a script error.

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

Attached to this article is also a demo application developed with v5.0.437 that illustrates how the Fields object from Elipse E3 operates. For further information on how to use CustomConfig (which is in the demo application), check the article ElipseX’s CustomConfig.

Attachments:

HistFields.zip

Returning a Historic’s field collection by using Fields object in Elipse E3.