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.