SetTaggedValue Method
The SetTaggedValue method adds a TaggedValue to the method's TaggedValues if the tag is not already present, or amends the TaggedValue if it is present.
At least one of value, textvalue, or item must be supplied as a parameter.
Note: Using this method will not alter an inherited tag, but will override it. Changing or creating a tag that already exists in the same-named method in a subclass of the userclass to which the method belongs will not affect that subclass.
To amend an inherited tag, use
FindTag Method to get the classname of the tag's owner, then access that ClassSource (using AppSource.FetchComponent (see
FetchComponent Method)), access the relevant MethodObject (in ClassSource.Methods (see
Methods Attribute)) and issue SetTaggedValue for that MethodObject.
This method has the following syntax:
status = MethodObject.SetTaggedValue(tag = varchar(256),
[value = StringObject | textvalue = varchar(maxsize)][, item = Object])
This method has the following parameters:
tag
(Required) Specifies the name of the tag to be stored or accessed in the TaggedValues array.
If an Item parameter is supplied, the tag name must be suffixed by a subtag, delimited from the main tag name by the "#" character. This subtag is used to uniquely identify and access the object item being stored. If the specified subtag has already been used, the supplied item will replace whatever object was previously stored using that subtag; if the supplied item is a null, the subtag entry will be deleted.
For example, to store a tagged value with tag name "test" and two objects (items), the first with subtag "one", the second with subtag "two", use the following code:
myMethodObject.SetTaggedValue(tag='test#one', item= myfirstitem);
myMethodObject.SetTaggedValue(tag='test#two', item= myseconditem);
To replace the myfirstitem object in the tagged value "test", use the following code:
myMethodObject.SetTaggedValue(tag='test#one', item= myreplacementitem);
To delete the subtag entry "one" (and the object it references) in the tagged value "test", use the following code:
myMethodObject.SetTaggedValue(tag='test#one', item= null);
Note: The "#" and "&" characters are both reserved and must not be used within tag or subtag names. Use of either "#" and "&" within tag or subtag names leads to unpredictable results.
value
Specifies a StringObject to be stored as the Value attribute of the tagged value being created or changed.
textvalue
Specifies a text value to be stored as the Value attribute of the tagged value being created or changed.
item
Specifies an object to be stored as one of the KeyedItems in the tagged value being created or changed.
This method returns TV_ROW_CHANGED if the entry for this tag was already present, TV_ROW_ADDED if the tag was not already present, or TV_FAIL if unsuccessful. Descriptions of system constant values and their numeric equivalents are listed in
Tagged Value Settings.
Last modified date: 12/20/2023