Attributes and Fields methods
This topic lists the methods of the Attributes and Fields collection container objects.
Note that the Add2() and the ItemByNameIndex() functions are only available with Fields. Fields support multiple entries with the same name, which is forbidden with Attributes.
Add(const String Name, const String Value)
Adds a new element to the collection. If the specified name already exists in the collection, the new value overwrites the previous one.
Parameters
Name
Name of the element to add. The name must adhere to this syntax rules: start with a letter, followed by zero or more letters, numbers, underscore or dash. The name is not case-sensitive.
Value
Value of the element. There is no restriction on the content, although binary is discouraged.
Exceptions
- EOleException The name is empty or invalid.
Add2(const String Name, const String Value, TAddFlags Flags, Integer Index (optional))
Fields only
Adds a new field to the collection. The behavior of the method when the specified name already exists in the collection is determined by the Flags argument.
Parameters
Name
Name of the field to add. The name must adhere to this syntax rules: start with a letter, followed by zero or more letters, numbers, underscore or dash. The name is not case-sensitive.
Value
Value of the element. There is no restriction on the content, although binary is discouraged.
Flags
Additional flags for the method. This determines how the method behaves when the specified name already exists.
| afReplace | 0 | Overwrites the previous value with the new |
| afAppend | 1 | Appends the new value at the end of the previous one |
| afDuplicate | 2 | Creates a new field with the same name |
| afFail | 3 | Raise an error |
Note: In an Active Script environment, such as the Run Script task, you must use the numerical value, since the TAddFlags type is not defined in an Active Script environment.
Index (optional)
Instance of the field to modify. This must be a numeric value equal to 0 or greater and can only be used with the afReplace flag.
Exceptions
- EOleException The name is empty or invalid.
- EOleException The flags value is invalid.
- EOleException The name already exists and the afFail flag was specified.
- EOleException The index is invalid.
- EOleException An index is specified but afReplace is not specified.
CountByName(const String Name)
Returns the number of attributes or fields (integer) with the specified name.
Parameters
Name
Name of the element to count.
Returns
Number of occurrences of elements with the specified name.
Note that when counting an attribute by name, the only possible values are 1 and 0 because attributes can only occur once.
Delete(Integer Index)
Delete a specified element from the collection.
Parameters
Index
0-based index of the element to delete. The first element in the collection is at index 0 and the last is at Count-1.
Exceptions
- EOleException Index is lower than 0 or higher than Count-1.
Item(Integer Index)
Returns the value of the element at the specified index in the collection.
Parameters
Index
0-based index of the element to delete. The first element in the collection is at index 0 and the last is at Count-1.
Returns
The value of the specified element as a string.
Exceptions
- EOleException Index is lower than 0 or higher than Count-1.
ItemByName(const String Name)
Returns the value of the element of the specified name.
Parameters
Name
Name of the element to retrieve.
Returns
The value of the element as a string. If no element is found, an empty string is returned.
Fields only: If more than one field has the specified name, the value of the first one in the list is returned.
ItemByNameIndex(const String Name, Integer Index)
Fields only
Returns the value of the n'th field of the specified name. This method can be used to retrieve the value of a specific field when more than one field has the same name.
Parameters
Name
Name of the field to retrieve.
Index
Ordinal of the field to retrieve. To retrieve the value of the first field named Name, use 0. For the second field, use 1, and so on.
Returns
The value of the specified field as a string. If an field named Name is not found, or Index is higher or equal to the number of fields named Name (in other words, you specify 4 to get the fifth but there are only three), an empty string is returned.
Exceptions
- EOleException Index is lower than 0.
Name(Integer Index)
Returns the name of the element at the specified index.
Parameters
Index
0-based Index of the element value to retrieve. The first element in the collection is at index 0, and the last is at Count-1.
Returns
The name of the element as a string.
Exceptions
- EOleException Index is lower than 0 or higher than Count-1.