SetTaggedValue Method
The SetTaggedValue method adds a TaggedValue to the application's TaggedValues array 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.
This method has the following syntax:
status = AppSource.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:
myAppSource.SetTaggedValue(tag='test#one', item= myfirstitem);
myAppSource.SetTaggedValue(tag='test#two', item= myseconditem);
To replace the myfirstitem object in the tagged value "test", use the following code:
myAppSource.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:
myAppSource.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.