StartTag

Deprecated. Do not use in new code.

Use ModifyTags for all new code.

Description:	Used to create tags by starting new instances of the tag type specified in the parameter list. When creating an application that requires child tags, it is recommended that this function be used in place of the older ChildLaunch function. StartTag can also be used to stop or to modify an existing tag.
Returns:	Numeric (0)
Usage:	Script Only.
Function Groups:	Advanced Module
Related to:	ModifyTags | OpChange | SimpleOpChange
Format:	StartTag(Parent, Flags,  TagType, ParameterList  )
Parameters:

Parent

An object that gives the parent for this new child tag. Defaults to VTSDB if invalid. See note in Comments section.

Flags

Bitwise expression indicating operational options. Bit # Operation 0 Add or change if TRUE. Delete if FALSE. 1 Persist change if TRUE. The tag will be output to the tag file. If Bit 0 is FALSE, it is not strictly relevant whether Bit 1 is TRUE or FALSE. The tag will be deleted both in memory and on disk. Regardless of this, it is good form to set bit 1 to TRUE when deleting a tag. When using StartTag to generate child tags, do not set bit 1 to TRUE. Flags should be set such that when the tag is stopped, StartTag is called with the a value of zero in the second parameter. This can be done using the expression, Valid(Root\Name). (See: Bitwise Parameters & Operations)

TagType

Required. The name of the tag type to be used for the tag. If modifying or deleting an existing child tag, you may set this parameter to invalid.

ParameterList

Required. All the parameters required by the child tag should be provided here. The child tag's parameter names and matching values may be supplied in any one of the follow forms: - As a comma-separated list of up to 256 name-value pairs. - As a two dimensional array of name-value pairs - As two arrays, the first containing the parameter names and the second parallel array, containing the matching values. - As a dictionary. - As a one-dimensional array of values. The order must match the order of parameters in the tag type, with no gaps or spaces. Note that there is no guarantee that the parameter order will remain the same in future versions - use of a dictionary is preferred. While there is no requirement that the child parameters must be given in the order that they are defined in the child tag, better performance will be obtained by matching that order. It is necessary to know the names of the parameters.

Comments:

When used to create a child tag, the name of that new child tag will always be unique since it will be a combination of the parent tag's name and the new child name in the format "ParentName\ChildName". If the first parameter (Parent) is not VTSDB, then it should be a tag object (the parent tag), and the StartTag call should only be made from that parent tag's Refresh module. When this function is used to create an ordinary tag, as opposed to a child tag, it is the responsibility of the programmer to ensure that a unique name is used for each new tag. If the tag does not exist and bit 0 of Flags is TRUE, then the tag is launched. If the tag exists and bit 0 of Flags is TRUE, then the tag's parameters are changed if necessary. Note that, if a new TagType is provided, then the existing tag will be deleted and a tag of the new type created. If the tag exists and bit 0 of Flags is FALSE or the tag's parent's Name is Invalid indicating that the tag is being stopped, then the tag is removed. Because of configuration management and the version control system, it is possible for a child tag have both temporary parameters (those created by code in the parent and existing only in memory) and a sub-set of permanent parameters in the tag files. These latter values are used to record user-overrides of the parameter values. If the application restarts, the child tag will be re-loaded from code and the overrides made in an earlier session will be read from the tag files. Permanent parameter values will always take precedence over temporary values. There are several ways that the tag's parameters can be passed to this module: Only one additional parameter which is an array of parameter values, a tag, or a tag mirror structure(*). In the case of a parameter value array the values must match to tags parameters in order, but may be fewer in number, allowing just the name to be passed, for example. Only one additional parameter which is a dictionary of parameter values keyed by parameter name. A pair of arrays is passed, with the first array being the array of parameter names and the second, parallel array, being the values for those named parameters. The "Name" parameter must be present, and the order of the pairs is not significant, other than matching  the formal parameter ordering gives some efficiency gains. A list of parameter name and value pairs of parameters. This is  typically used by ChildLaunch calls. Again "name" must be present and the ordering is only a small consideration for efficiency. (*) A tag mirror is a structure that has one element for each of a tag’s parameters, accessible by that parameter name (e.g. MyTag\IODevice). These should only be used by advanced VTScada programmers.

In all examples, ParentRoot is assumed to be a pre-existing tag object with name "Something".

Examples:

Example 1 - Creating a child tag by supplying a series of name, value pairs.

   Code\StartTag(ParentRoot, 0b11, "AnalogStatus",
          "Name",         "CylinderVolume"
          "Area",         Area,
          "Description",  Concat(Name, ": Cylinder Volume"),
          "DeviceTag",    PollDriverName,
          "Address",      "F8:0",
          "ScanRate",     Invalid,
          "UnscaledMin",  0,
          "UnscaledMax",  100,
          "ScaledMin",    0,
          "ScaledMax",    100,
          "Units",        "gal",
          "AlarmLo",      Invalid,
          "AlarmHi",      Invalid,
          "PriorityLo",   Invalid,
          "PriorityHi",   Invalid,
          "InhibitLo",    1,
          "InhibitHi",    1,
          "AlarmSound",   Invalid,
          "ManualValue",  Invalid,
          "Threshold",    1,
          "Questionable", 0,
          "Quality",      Invalid,
          "DisplayOrder", 1,
          "HelpKey",      Invalid);

This creates a child analog status tag named SOMETHING\CylinderVolume.

Example 2 - Creating a persistent tag by supplying a series of name, value pairs.

   Code\StartTag(CodeVTSDB, 0b11, "AnalogStatus",
          "Name",         "CylinderVolume"
          "Area",         Area,
          "Description",  "My Cylinder Volume"),
          "DeviceTag",    PollDriverName,
          "Address",      "F8:0",
          "ScanRate",     Invalid,
          "UnscaledMin",  0,
          "UnscaledMax",  100,
          "ScaledMin",    0,
          "ScaledMax",    100,
          "Units",        "gal",
          "AlarmLo",      Invalid,
          "AlarmHi",      Invalid,
          "PriorityLo",   Invalid,
          "PriorityHi",   Invalid,
          "InhibitLo",    1,
          "InhibitHi",    1,
          "AlarmSound",   Invalid,
          "ManualValue",  Invalid,
          "Threshold",    1,
          "Questionable", 0,
          "Quality",      Invalid,
          "DisplayOrder", 1,
          "HelpKey",      Invalid);

This creates a persistent analog status tag named CylinderVolume.

Example 3 - creating a child tag using a dictionary of parameters.

    ParmsDict = Dictionary();
    ParmsDict["Name"]        = "P1";
    ParmsDict["Area"]        = "West";
    ParmsDict["Description"] = "P1 West"; 
    ParmsDict["IODevice"]    = "Mod1";
    ParmsDict["Address"]     = 100; 
    Code\StartTag(ParentRoot, 0b11, "Parent", ParmsDict);

Example 4  -  creating a child tag using an array of parameters:

    ParmsArray = New(7); 
    ParmsArray[0] = "P2";
    ParmsArray[1] = "East";
    ParmsArray[2] = "P2 East";
    ParmsArray[3] = "Mod1"; 
    ParmsArray[4] = 200; 
    ParmsArray[5] = 2; 
    Code\StartTag(ParentRoot, 0b11, "Parent", ParmsArray);

Example 5 - Creating a child tag using parameters in an array of names and an array of values

    ParmNames     = New(5); 
    ParmNames[0]  = "Area";
    ParmNames[1]  = "Name";
    ParmNames[2]  = "Description";
    ParmNames[3]  = "Address";
    ParmNames[4]  = "IODevice";
    ParmValues    = New(5); 
    ParmValues[0] = "North";
    ParmValues[1] = "P4";
    ParmValues[2] = "P4 North";
    ParmValues[3] = 400; 
    ParmValues[4] = "Mod1";
    Code\StartTag(ParentRoot, 0b11, "Parent", ParmNames, ParmValues);

Example 6  -  Creating a child tag using parameter Name/Value pairs (parms out of order)

    Code\StartTag(CodeVTSDB, 0b11, "Parent",
                  "IODevice",    "Mod3", 
                  "Area",        "Central",
                  "Name",        "P5",
                  "Description", "P5 Central",
                  "Address",     500, 
                  "NotAParm",    0);