Add Method (Formats Collection)
Add Method (Formats Collection)
Important The Collaboration Data Objects (CDO) 1.2.1 Rendering objects are not installed by or supported for use with Exchange Server 2003 or later.
The Add method creates and returns a new Format object in the Formats collection.
Syntax
Set objFormat = objFormatsColl.Add(varProperty [, varName] )
objFormat
On successful return, contains the new Format object.
objFormatsColl
Required. The Formats collection object.
varProperty
Required. Variant (Long or String). The property tag for the predefined property, or the custom name of the user-defined property, that is to be formatted by the new Format object. A value of zero is used to indicate a special-purpose format not representing any property.
varName
Optional. String. The name to be assigned to the new Format object. The varName parameter is for special-purpose formats only. If it is specified, the varProperty parameter must be set to zero.
Remarks
The Add method parameters correspond to the Property and Name properties of the Format object.
The varProperty parameter designates the property to be rendered. The parameter can be a long integer designating the property by property tag, or a string designating it by custom name. In both cases it corresponds to the Property property.
If the varProperty parameter is a custom name, it can optionally be prefixed with a GUID string identifying its property set. In this case, the GUID should be enclosed in braces. For more information and examples, see Using Named Properties.
The varName parameter designates a reference name for a special-purpose format, which does not represent a specific property. The format name should not be confused with a property name; in fact, when the varProperty parameter supplies a property name, the varName parameter must be omitted.
CDO enforces uniqueness of format names within the same Formats collection. If you attempt to set the varName parameter to an existing name, Add returns an error.
You should avoid giving a format a name that coincides with any of the substitution tokens, as this could cause unexpected results from the rendering methods. For a list of the substitution tokens, see the RenderUsing property of the Pattern object.
Every property to be rendered can have at most one format. The Formats collection cannot contain more than one Format object for any one property.
You can add a format corresponding to a predefined property at any time, but if you wish to add a format corresponding to a user-defined property, you must first set the data source of the rendering object you are working with, that is, either the ContainerRenderer object's DataSource property or the ObjectRenderer object's DataSource property.
If you attempt to add a user-defined property without the data source being set, you get an error return from Add. Because the CDO Rendering Library runs primarily in server-side script, which does not support exception handling, you must explicitly test for errors:
Set objFormat = objFormatsColl.Add("CustomPropName")
If Err.Number <> 0 Then
If Err.Number = &H8000FFFF Then ' E_UNEXPECTED no data source
' handle error perhaps set DataSource property and try again
End If
End If