General Value Substitution Syntax
Info*Engine substitution expressions are always delimited by the characters $( and ). Within these delimiters, specify the group and attributes for which the substitution is made as follows:
$(group_name[element_selector]attribute_name[value_selector])
where:
group_name
Names a group that exists in the VDB. This group can be a context group such as @FORM or a data group that results from the execution of a task.
element_selector
Identifies the elements (rows) within the group that are selected. The selector can be one of the following:
◦ An integer, which identifies an element by its index. The first element has an index of 0. Therefore, if a group contains 10 elements, their indices range from 0 to 9.
◦ The letter N, which selects the last element of the group.
◦ Empty, which selects all elements and concatenates them together into a string using no separators. The empty selector is usually used when there is only one element.
◦ The word META, which selects the metadata from the group instead of selecting elements.
◦ The asterisk (*) symbol, which selects all elements and concatenates them together into a string. Semicolons separate the elements in the string.
◦ An attribute and value pair specified as attribute=value. Info*Engine selects the first element it finds that contains the specified value for the named attribute. For example, assume that the “grp1” group contains “name” and “phone” attributes. To locate the phone number of an employee named “Doyle,” use the following substitution expression:
$(grp1[name=Doyle]phone[])
attribute_name
Names an attribute (column) that exists within the selected elements.
If META is specified for element_selector, then one of the following attributes can be specified for attribute_name:
◦ COUNT is the number of elements in the group.
◦ STATUS is the numeric status value currently associated with the group. A status of 0 indicates success. A status of anything but 0 indicates failure.
◦ NAME is the name of the group.
◦ TYPE is the type of group. The group creator may set the meta value of TYPE but is not required to. Valid group types include:
▪ Object -- The group contains data.
▪ Status -- The group contains the success or failure of a request
▪ Exception -- The group contains the error information produced when an exception has occurred.
▪ Unknown -- The group creator did not set the TYPE information for the group.
◦ MESSAGE is the current message associated with the group. If there is no message associated with the group, the substitution is an empty string. You can retrieve multiple messages from the MESSAGE metadata. For example, to get all messages associated with “Grp123” you can use the following substitution expression:
$(Grp123[META]MESSAGE[*])
In addition, you can specify any metadata attribute defined in the group for attribute_name.
value_selector
Identifies the attribute values that are selected. The selector can be one of the following:
◦ An integer, which identifies a value by its index. The first value has an index of 0. Therefore, if an attribute contains 5 values, their indices range from 0 to 4.
◦ The letter N, which selects the last value of the attribute.
◦ Empty, which selects all values and concatenates them together into a string using no separators. The empty selector is usually used when there is only one value.
◦ The asterisk (“*”) symbol, which selects all values and concatenates them together into a string. Commas separate the values in the string.
The following substitution expression selects all XYZ values from the element in the @FORM group and concatenates them together into a string using a comma to separate the values:
$(@FORM[]XYZ[*])
The following substitution expression selects the first NAME attribute value from the element in the USERS group:
$(USERS[]NAME[0])
The following substitution expression selects the COUNT value from the metadata in the OUTGRP group:
$(OUTGRP[META]COUNT[])
Default Values for Substitutions
To cover the possibility that the evaluation of a substitution expression could return no values, you should include a default for the expression. Specify a default by including the following default attribute on the param tag:
default="value"
For example, the following param tag sets the default for the ATTRIBUTE parameter to the string "*":
<ie:param name="ATTRIBUTE" … default="*"/>