Referencing Outlook field and property names in non-English locales

Article
01/29/2012

In Microsoft Outlook, fields store values in forms and properties store values in macros or add-ins. If you use forms, macros, or add-ins that reference standard or custom fields in non-English locales, you should be aware that the forms or code should reference standard and custom fields using their locale-dependent field names. Also, if your macro or add-in uses Jet queries to filter on built-in properties, regardless of the locale, your Jet queries should always reference the built-in properties using their English names.

Outlook fields and properties

In Outlook, fields apply to forms pages in the Outlook forms designer, and properties apply to extending Outlook using the object model. Fields are used to display values in forms, and properties are used to store values pertaining to their parent objects. There are standard fields that are built into Outlook, for example, the [Subject] field in an appointment form. Some of these fields map to properties of objects in the Outlook object model. In particular, there are fields that apply to Outlook items, and many of these fields map to properties of corresponding item objects in the object model. Using the afore-mentioned [Subject] field as an example, that [Subject] field is mapped to the Subject property of the AppointmentItem object in the object model. As another example, the [Total Work] and [Actual Work] fields are standard Task fields available in the forms designer. They map to respectively the TotalWork and ActualWork properties of the TaskItem object in the object model.

Using the Outlook forms designer, you can create custom formula fields for a custom form page. For example, you can create a field called [ Accumulated time] as the sum of the [Total Work] and [Actual Work] fields. See figure 1.

Figure 1. Creating a custom formula field for the task item in the Outlook forms designer.

A custom property of the formula type in the object model is similar to a custom formula field. Along the same lines as the preceding [Accumulated time] field example, you can create a macro that uses the UserProperty and UserProperties objects to create a custom property for the TaskItem object. The custom property is called AccumulatedTime and is of the formula type. Note that formula fields and formula properties have their calculations based on standard or custom fields. So when you assign a formula to a custom formula property, the formula references field names instead of property names.

The following is a VBA function, CustomPropertyFormula, that creates an AccumulatedTime custom formula property for the TaskItem object. The AccumulatedTime property is assigned the formula which is the sum of the [Total Work] and [Actual Work] fields.

Sub CustomPropertyFormula()

Dim task As Outlook.TaskItem

Dim customProp As UserProperty

Set task = Outlook.CreateItem(olTaskItem)

task.TotalWork = 4

task.ActualWork = 3

' Create a custom property for the TaskItem.

' The custom property is of the formula type, called AccumulatedTime.

Set customProp = task.UserProperties.Add("AccumulatedTime", olFormula)

' Assign the formula which is the sum of the [Total Work] and [Actual Work] fields.

' [Total Work] field maps to the TaskItem.TotalWork property, and

' [Actual Work] maps to the TaskItem.ActualWork property.

customProp.Formula = "[Total Work] + [Actual Work]"

MsgBox customProp.Value

customProp.Delete

task.Delete

End Sub

All is well if you are using the custom form or macro in the English locale. However, fields are locale-dependent and in some scenarios – forms and custom formula properties, fields must be referenced by the appropriate field names corresponding to each locale. In the case of Jet queries, built-in properties must be referenced in their English names regardless of the locale.

Referencing standard or custom fields in custom forms for different locales

If you plan to run a custom form that references standard fields or custom fields in different locales, you should first create a form for each locale. Each such form would reference standard fields and custom fields using the locale-specific field names.

For example, if you are using a custom form for the Japanese locale, you should first do the following to switch to using Japanese as the display language in Outlook:

Install the Japanese language pack for Office.
In Outlook, select File, Options, and then Language.
Select Japanese under Display Language.
Select Set as Default.

Then in the forms designer, you should be able to see locale-dependent names for standard fields in the Field Chooser.

To use custom fields in your custom form, you should use the Field Chooser to first create the custom fields in the specific locale to get the locale-specific names, before referencing the custom fields.

Referencing standard or custom fields in a custom formula property for different locales

If you plan to run in different locales a macro that references standard or custom fields in a formula property, you must first modify the formula to reference the fields using their locale-specific names. Using the Japanese locale and the previous macro as an example, you must
replace in the macro the names of the standard fields [Total Work] and [Actual Work] by their Japanese names. That is, in place of:

customProp.Formula = "[Total Work] + [Actual Work]"

Do:

customProp.Formula = "[予測時間] + [実働時間]"

Otherwise, your macro will return a runtime error.

You can verify the localized names of standard fields and custom fields by switching the Outlook display language to the corresponding locale and then looking for the localized field names in the Field Chooser in the Outlook forms designer.

Referencing properties in Jet queries

Outlook supports filtering by using queries in the Microsoft Jet query language syntax and DASL Searching and Locating (DASL) syntax. In Jet query syntax, you can filter on a property by enclosing the property name with square brackets in the query, similar to the way you would reference a field name. For example, you can create a query for the ContactItem.CompanyName property being “Microsoft”. To express this query in Jet syntax, you can enclose the property with square brackets, as in [CompanyName] , and specify the filter, sFilter, as follows:

sFilter = "[CompanyName] = 'Microsoft'"

Note that if the property is a built-in property in the object model, then in a Jet query, you must reference the field in its English name regardless of the locale. If on the other hand, the property is a custom property, then in a non-English locale, you can reference the property in the Jet query using either its English name or its locale-specific name.