Creating Tags

Before sending any data to the historian server, the SDK application needs to know which tag the data values are supposed to be associated with. There are two options in this case:

1. The tags to be used should be created by the SDK application before the data values are sent. 
2. The tags to be used have already been created on the historian server, and the SDK application should just use them to send data.

If a tag already exists on the server (for example, it could have been created manually in the Configuration Editor), then the SDK application needs to perform the following steps before it can start storing data values for that tag:

1. Determine the tag name to be used.
2. Establish a connection to the historian server.
3. Query the historian server to retrieve the tag metadata instance of the tag.

The SDK application will be unable to start storing data until those steps are performed. If the historian server is unavailable when the SDK application starts up, nothing can be stored. While you can use this approach, the recommended option is to have the the SDK application be the actual owner of the tag that gets created on the fly.

To create a tag, you need to create a tag metadata instance of HistorianTag class and fill out all of the properties that you want to be different from the default values. There are only two properties of the HistorianTag class that are required to be provided: TagName and TagDataType. For the complete list of the HistorianTag class properties and their default values, see the SDK reference. 

Example

HistorianTag myTag = new HistorianTag();
myTag.TagName     = "MyIntegerTag";
myTag.TagDataType = HistorianDataType.Int4;

The tag creation operation can be initiated by the HistorianAccess.AddTag() method.

Example

UInt32 tagKey;
HistorianAccessError error;
if (!historian.AddTag(myTag, out tagKey, out error))
    Console.WriteLine("Failed to request tag creation: {0}", error.ErrorDescription);

The HistorianAccess.AddTag() method returns a tag key that is automatically assigned to that tag. The SDK application is responsible for remembering that tag key to be used later for sending values.

It is important to understand that that tag key value is valid only within the current historian connection until it gets closed. It should never be reused by other historian connections.

After a successful return from the AddTag() method, the tag gets created in the internal HCAL cache, and will be synchronized in the background with the historian server. If you have a properly configured store-and-forward subsystem, you can start storing data for that tag right away.

If store-and-forward was not configured for that historian connection, the SDK application must wait until all tags have been successfully created on the historian server before it can send any values for that tag. That can be checked using the HistorianAccess.GetTagStatusByName() method.

Example

HistorianTagStatus tagStatus = new TagStatus();
tagStatus.TagName = myTag.TagName;
historian.GetTagStatusByName(ref tagStatus);

if (tagStatus.Pending)
    Console.WriteLine("Tag status is not determined yet");
else
    if (tagStatus.ErrorOccurred)
        Console.WriteLine("Tag creation error: {0}", tagStatus.Error.ErrorDescription);
    else
        Console.WriteLine("Tag added successfully");

The managed HCAL caches the tag metadata locally in the store-and-forward subsystem so that if the application creates exactly the same tag every time it starts, there is no metadata duplication occurring locally or on the historian server. Moreover, the recommended way is when the SDK application always blindly creates the tags it needs to store data for.