Storing values when a macro ends

When a macro ends, the values stored in its variables aren't automatically saved to disk. If a macro needs to preserve a value, it must store that value outside itself before the macro execution is completed. This topic describes five locations where macro values can be easily stored and retrieved.

Document variables

Document variables allow you to store values as part of a document or a template. For example, you might store macro values in the document or template where the macro resides. You can add variables to a document or template using the Add method of the Variables collection. The following example saves a document variable in the same location as the macro that is running (document or template) using the ThisDocument property.

ThisDocument.Variables.Add Name:="Age", Value:=12

The following example uses the Value property with a Variable object to return the value of a document variable.

num = ThisDocument.Variables("Age").Value

Note   You can use the DOCVARIABLE field to insert a document variable into a document.

Document properties

Like document variables, document properties allow you to store values as part of a document or a template. Document properties can be viewed in the Properties dialog box (File menu).

The Word object model breaks document properties into two groups: built-in and custom. Custom document properties include the properties shown on the Custom tab in the Properties dialog box. Built-in document properties include the properties on all the tabs in the Properties dialog box except the Custom tab.

To access built-in properties, use the BuiltInDocumentProperties property to return a DocumentProperties collection that includes the built-in document properties. Use the CustomDocumentProperties property to return a DocumentProperties collection that includes the custom document properties. The following example creates a custom document property named "YourName" in the same location as the macro that is running (document or template).

ThisDocument.CustomDocumentProperties.Add Name:="YourName", _
    LinkToContent:=False, Value:="Joe", Type:=msoPropertyTypeString

Built-in document properties cannot be added to the DocumentProperties collection returned by the BuiltInDocumentProperties property. You can, however, retrieve the contents of a built-in document property or change the value of a read/write built-in document property.

Note   You can use the DOCPROPERTY field to insert document properties into a document.

AutoText entries

AutoText entries can be used to store information in a template. Unlike a document variable or property, AutoText entries can include items beyond macro variables such as formatted text or a graphic. Use the Add method with the AutoTextEntries collection to create a new AutoText entry. The following example creates an AutoText entry named "MyText" that contains the contents of the selection. If the following instruction is part of a template macro, the new AutoText entry is stored in the template, otherwise, the AutoText entry is stored in the template attached to the document where the instruction resides.

ThisDocument.AttachedTemplate.AutoTextEntries.Add Name:="MyText", _
    Range:=Selection.Range

Use the Value property with an AutoTextEntry object to retrieve the contents of an AutoText entry object.

Settings files

You can set and retrieve information from a settings file using the PrivateProfileString property. The structure of a Windows settings file is the same as the Windows 3.1 WIN.INI file. The following example sets the DocNum key to 1 under the DocTracker section in the Macro.ini file.

System.PrivateProfileString( _
    FileName:="C:\My Documents\Macro.ini", _
    Section:="DocTracker", Key:="DocNum") = 1

After running the above instruction, the Macro.ini file includes the following text.

[DocTracker]
DocNum=1

The PrivateProfileString property has three arguments: FileName, Section, and Key. The FileName argument is used to specify a settings file path and file name. The Section argument specifies the section name that appears between brackets before the associated keys (don't include the brackets with section name). The Key argument specifies the key name which is followed by an equal sign (=) and the setting.

Use the same PrivateProfileString property to retrieve a setting from a settings file. The following example retrieves the DocNum setting under the DocTracker section in the Macro.ini file.

num = System.PrivateProfileString( _
    FileName:="C:\My Documents\Macro.ini", _
    Section:="DocTracker", Key:="DocNum")

Windows registry

You can set and retrieve information from the Windows registry using the PrivateProfileString property. The following example retrieves the Word 2000 program directory from the Windows registry.

aSec = "HKEY_CURRENT_USER\Software\Microsoft" _
    & "\Office\9.0\Word\Options"
programDir = System.PrivateProfileString(FileName:="", _
    Section:=aSec, Key:="PROGRAMDIR")
MsgBox programDir

The PrivateProfileString property has three arguments: FileName, Section, and Key. To return or set a value for a registry entry, specify an empty string ("") for the FileName argument. The Section argument should be the complete path to the registry subkey. The Key argument should be the name of an entry in the subkey specified by Section.

You can also set information in the Windows registry using the following PrivateProfileString syntax.

System.PrivateProfileString(FileName, Section, Key) = value

The following example sets the DOC-PATH entry to “C:\” in the Options subkey for Word 9.0 in the Windows registry.

aSec = "HKEY_CURRENT_USER\Software\Microsoft" _
    & "\Office\9.0\Word\Options"
System.PrivateProfileString(FileName:="", _
    Section:=aSec, Key:="DOC-PATH") = "C:\"