Add Method (Fields Collection)

Add Method (Fields Collection)

The Add method creates and returns a new Field object in the Fields collection.

Syntax

Set objField = objFieldsColl.Add (name, Class [, value] [, PropsetID**] )**

Set objField = objFieldsColl.Add (PropTag, value)

objField

On successful return, contains the new Field object.

objFieldsColl

Required. The Fields collection object.

name

Required. String. The property name assigned to a custom named property.

Class

Required. Long. The data type for the field, such as string or integer. The Class parameter represents the same values as the Field object's Type property. The following types are allowed:

The current version of CDO does not support the vbNull and vbDataObject data types.

value

Required (optional in first syntax). Variant. The value of the field, of the data type specified in the Class parameter or implicit in the PropTag parameter. You can change the value later by setting it directly or by subsequent calls to the Field object's ReadFromFile method.

PropsetID

Optional. String. Contains the GUID that identifies the property set, represented as a string of hexadecimal characters. When this identifier is not present, the property is created within the default property set. The default property set is either the property set most recently supplied to the SetNamespace method, or the initial default property set value, PS_PUBLIC_STRINGS.

PropTag

Required. Long. The MAPI property tag for a predefined MAPI property.

Remarks

The Field object created by the Add method always represents a MAPI property. This can be either a predefined MAPI property, which is designated by a property identifier, or a custom property, which is designated by a unique name that MAPI associates with an identifier by means of a name-identifier mapping. This mapping makes use of the property set GUID that is common to every named property in that property set.

The first syntax is used for a named property. The name parameter contains the custom name that MAPI maps to a property identifier. You can optionally include the property set GUID with the name as an alternative to using the PropsetID parameter. If you elect this option, the GUID is placed in braces immediately preceding the property name itself. If the property set GUID is supplied in both the name and PropsetID parameters, the value in PropsetID takes precedence.

The length of the name of a custom property is limited to 120 characters. An attempt to exceed this limit returns an error. Note that this limitation does not apply to the value of the property.

If the Class parameter contains vbEmpty or an invalid setting, the Add method attempts to derive the data type from the new field's value. If this attempt fails, for example if the value parameter is not set, the Add method returns CdoE_NO_SUPPORT.

Note   The Microsoft® Exchange Server supports only predefined MAPI properties on Folder objects. You cannot add or define custom named properties on Microsoft Exchange Server folders. Other servers may support named properties on folders, however.

The second syntax is used for a predefined MAPI property. The PropTag parameter contains the 32-bit MAPI property tag associated with the property and corresponds to the ID property of the Field object. The property tag contains the MAPI property identifier in its high-order 16 bits and the MAPI property type in its low-order 16 bits. All MAPI properties are accessible except those of MAPI type PT_OBJECT or PT_CLSID.

Support for the Add method is provider-dependent. Not all providers support named properties.

The name, Class, and value parameters in the first syntax correspond to the Name, Type, and Value properties of the Field object.

The Index property of the new Field object equals the new Count property of the Fields collection.

The field is saved in the MAPI system when you Update the parent object, or Send it if the Fields collection's parent is a Message object.

The vbArray data type must always be used in conjunction with one of the other types, for example vbArray + vbInteger. The entire array must be of the same data type. Note that operations such as comparison cannot be done with a single operator on types involving vbArray.

When you use a multivalued field in conjunction with an array, you must declare the array to be of the appropriate data type. The data type depends on whether you are writing to the field or reading from it, because a multivalued field accepts arrays of various data types but always returns a vbVariant array.To write to the field, that is, to copy an array to it, declare the type of the array the same as the base type of the field:

Dim Words(10) As String ' NOT just Dim Words(10)
' ...
Set objKeysField = objFieldsColl.Add("Keywords", vbArray + vbString)
objKeysField.Value = Words
 

Failure to do this results in a CdoE_INVALID_TYPE error. To read from the field, that is, to copy it to an array, declare the array as Variant:

Dim Tags(10) As Variant ' NOT Dim Tags(10) or Dim Tags (10) As Long
' ... instantiate object objSource exposing objTagsField ...
Set objTagsField = objSource.Fields.Item("Tags")
objTagsField.Value = Tags
 

Failure to do this results in a VB compiler error.

When you use the vbBlob type for binary data, you supply the value in the form of a hexadecimal string that contains the hexadecimal representation of the bytes in the binary object (such as a hexadecimal dump of the object).

MAPI stores all custom properties that represent date and time information using Greenwich Mean Time (GMT). CDO converts these properties so that the values appear to the user in local time.

Example

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

See Also

Concepts

Fields Collection Object