ModifyTags

(VTScada-Layer function. Must be called with a leading backslash.)

Description:	Can be used to create, modify, or delete running tags. Replacement for StartTag for the case where persisted tags were created. See comments for more detail.
Returns:	Object reference
Usage:	Script Only.
Function Groups:	Configuration
Related to:	GetTagConfiguredParameters
Format:	\ModifyTags(pSuccess, TagParameters[ , newTags, UserID, Comment, Merge, HaveLock, pErrors)
Parameters:

pSuccess

An optional pointer to a value, which will be set to 1 on successful completion or 0 on failure.

TagParameters

Dictionary of tag parameters, each of which is also a dictionary. See examples.

NewTags

Optional. Dictionary of tag additions. Key is tag friendly name and value is tag type.
If you have a NewTags entry for a tag that already exists, then the action will be a deletion and an add of that tag. The added tag will not have the same UniqueID as the original tag, and therefore page references and history for the old tag will not be associated with the new tag,

UserID

Optional. User making change

Comment

Optional. Comment to store with changes

Merge

Optional. On update, true to retain parameters not specified in parameter dictionary, false to revert all other parameters to their defaults. Defaults to TRUE

HaveLock

Optional. If false, this module gets the working copy lock and commits changes and update tags when finished. If true, caller must have WC lock ModifyTags will not get WC lock, commit changes, or update running tags. Defaults to FALSE

pErrors

Optional output: dictionary of errors, keyed by name of tag with error, containing #MODTAGS_* error code. Defined in Code.

Constants used as error codes, returned in the pErrors dictionary parameter of ModifyTags:

Constant	Value	Description
#MODTAGS_BADNAME	1	Name of added tag is not allowed. Refer to tag naming rules.
#MODTAGS_BADTYPE	2	Provided type is not an existing type
#MODTAGS_MISSINGTAG	3	Attempting to modify a non-existent tag.
#MODTAGS_MISSINGPARENT	4	Attempting to add a child to a non-existing parent.

Constants used as global error codes returned in root value of ModifyTags's pErrors dictionary parameter:

Constant	Value	Description
#MODTAGS_NOERROR	0	No error.
#MODTAGS_TAGERROR	1	One of the errors listed in the preceding table.
#MODTAGS_NOTEDITABLE	2	Application cannot be edited at this time. (Most likely, a restart is required.)

Comments:

Some readers may have used non-persisted StartTag calls to create parent/child tag structures. Now that StartTag is obsolete, those structures should be created with the Tag Browser, not in code.

This module launches a worker module into Code so that the operation is not interrupted by this module's caller being slain. The return value of the function is a reference to this worker module. By watching for this to become invalid, you can discover when the module has finished.

ModifyTags works by modifying root tag declarations or adding overrides for child tags not defined in the root tag database. It does not modify tag type definitions.

The TagParameters dictionary is formatted as follows:

 TagParameters[FullFriendlyName] = {TheChange};

For tag deletion, {TheChange} is simply Invalid.
For a creation or update, {TheChange} is a dictionary of parameter values, keyed by parameter name.

When creating a new tag, the NewTags dictionary must have an entry specifying the tag type. If there is a tag with the given name already running, it will be deleted and the new tag will be created with a new unique ID, even if the type specified in NewTags is the same as the type of the currently-running tag. Hence, this is a way to stop a tag and create a tag having the same friendly name, but a different unique ID and possibly a different type, all in a single operation.

When updating a tag, what will happen to tag parameters that are not specified in the TagParameters dictionary will depend on the value of the Merge parameter. If TRUE (the default), then those parameters remain unchanged by the operation. If FALSE, then those parameters revert to their default, where default for a root tag is the default specified in the tag type, and the default for a child tag is the value specified by its parent's type's child tag definition record (that is, the value it would have without any root overrides). The Merge parameter has no effect on tag additions or deletions.

To set parameters to expressions, you can set metadata on individual parameter values. For example:

TagParms[TagName][ParmName] = ExpressionText;
Metadata(TagParms[TagName][ParmName], System.#EXPRESS_META) = System.#EXPRESS_REFRESH; {non-optimized expression}
Metadata(TagParms[TagName][ParmName], System.#EXPRESS_META) = System.#EXPRESS_SNAPSHOT; {optimized expression}

If HaveLock is TRUE, then when this module finishes, the memory cache of tag parameters will have been updated, and those changes will be pending to be written out to tag files and incorporated into running tags. Note that there is no guarantee that those actions have been performed. That will happen during the next commit. If HaveLock is FALSE, then it is guaranteed that all running tags affected by these changes will have been updated or stopped (whichever applies). Also, while all root tags and all child tags (whose parents are running and that the changes cause to bring into existence) will be running, it is not guaranteed that they will have run their Refresh modules. It is also not guaranteed that children of tags just started will be running yet let alone Refreshed.

When called with the Merge==FALSE parameter it is possible to revert a tag parameter to its default or remove an override using the API GetTagConfiguredParameters. If ModifyTags is called with Merge=FALSE without using this API, there is no way to remove some configured parameters while keeping others. To make changes to some configured parameters, called GetTagConfiguredParameters, modify the dictionary of parameters (add/modify/remove), then pass the modified dictionary into a call to ModifyTags.

Examples:

Example 1 - Modify running tags (A and B exist and are running):

TagParms = Dictionary();
NewTags   = Dictionary();

TagParms["A"] = Dictionary();
TagParms["A"]["Description"] = "Updated description1";
TagParms["A\B"] = Dictionary();
TagParms["A\B"]["Description"] = "Updated description2";

Success = Invalid;
Code\ModifyTags(&Success, TagParms, NewTags, GetUserID(), "Modify tags", TRUE, FALSE, &Errors);

Example 2 - Add child tags (Tag C exists and is running):

TagParms = Dictionary();
NewTags   = Dictionary();

NewTags["C\D"]   = "AnalogInput";
TagParms["C\D"] = Dictionary();
TagParms["C\D"]["Description"] = "New AI description";
NewTags["C\D\E"]  = "DigitalInput";
TagParms["C\D\E"] = Dictionary();
TagParms["C\D\E"]["Description"] = "New DI description";

Success = Invalid;
Code\ModifyTags(&Success, TagParms, NewTags, GetUserID(), "Add tags", TRUE, FALSE, &Errors);

Example 3 - Delete a tag (Tag C\F exists. The third parameter must be invalid. The sixth must be false.):

TagParms = Dictionary();
TagParms["C\F"] = Invalid;
Success = Invalid;
Code\ModifyTags(&Success, TagParms, Invalid, GetUserID(), "Delete Tags", FALSE, FALSE, &Errors);

Example 4 - Add a parent and a child tag (G and H do not exist):

TagParms = Dictionary();
NewTags   = Dictionary();

NewTags["G"]   = "Calculation";
TagParms["G"] = Dictionary();
TagParms["G"]["Description"] = "New Calc description";
NewTags["G\H"]   = "AnalogStatus";
TagParms["G\H"] = Dictionary();
TagParms["G\H"]["Description"] = "New AS description";

Success = Invalid;
Code\ModifyTags(&Success, TagParms, NewTags, GetUserID(), "Add tags", TRUE, FALSE, &Errors);

After ModifyTags completes, the following changes to the running tags are guaranteed:

A and A\B will be updated.
C\F will be stopped.
C\D and G will be running but not necessarily refreshed yet.
C\D\E and G\H (added tags whose parents weren't already running) will not necessarily be running yet.

If TagParms includes the deletion of a parent tag, then all TagParms and NewTags records related to the addition/modification/deletion of any children of that tag are discarded.