Adding Custom Fields

Within this new message object is a child object known as a Fields collection, which is the actual array of fields that house data. To start using the Fields collection, you may first want to obtain a handle to it with the following call:

Set oNewFields = oNewMessage.Fields
 

This call provides a handle to all the message's properties. After making this call, you can check its value for success (Nothing = failure). With the oNewFields handle, you can now add new fields to the message with the Fields.Add method, as in the following call:

oNewFields.Add "Category Name", Category_Type, Value
 

You can also determine the number of fields (or properties) in the message using Fields.Count (in this case, oNewFields.Count). For more information, see Add Method (Fields Collection). The code example at the bottom of the topic is reproduced here:

' Fragment from Fields_Add; uses the type "vbString" 
    Set objNewField = objFieldsColl.Add( _ 
                      Name:="Keyword", _ 
                      Class:=vbString, _ 
                      Value:="Peru") 
'  verify that objNewField is a valid Field object 
' Fragment from Field_Type; display the integer type value 
    MsgBox "Field type = " & objOneField.Type 
 

In this example, the message contains a Fields collection whose handle is objFieldsColl. Using the Add method, a new field called Keyword is created whose class is vbString and whose value is "Peru". Then, the variable objNewField is assigned ("Set") the value of this field creation operation, so that you can check for success. If the value assigned is not Nothing, the field was created.

Field Names and Field Identifiers

Some fields have names ("named properties"), and others do not, such as the FROM field. Unnamed fields are identified by their identifiers. It is easiest to use the named property when it exists, but you must use the property identifier otherwise. In the file amprops.inc, a number of custom property form name identifier numbers are defined. These are hexadecimal numbers used to identify fields. None of these fields are necessarily rendered, although they may contain data.

For example, in one sample script data is being retrieved from the FROM field. The Fields object is opened and the current index in the Fields object is set to the identifier of the FROM field. The identifier must be used because a given field (the FROM field in this example) is not always in the same position within a Fields collection. Because you can determine the number of properties in the Fields collection (with Fields.Count), you incrementally loop through the fields (from zero to the Fields count) until you reach the one whose identifier is equal to the constant defined for the FROM field. Then, you can read its value.