Storing Values When a Macro Ends
|Word Developer Reference|
When a macro ends, the values stored in its variables are not 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 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 ActiveDocument property.
You can use the DOCVARIABLE field to insert a document variable into a document.
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.
The Microsoft Office 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 of a Document object or a Template object 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).
Built-in document properties cannot be added to the DocumentProperties collection returned by the BuiltInDocumentProperties property of a Document object or Template object. You can, however, retrieve the contents of a built-in document property or change the value of a read/write built-in document property.
You can use the DOCPROPERTY field to insert document properties into a document.
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.
You can set and retrieve information from a settings file using the PrivateProfileString property of the System object. The structure of a Microsoft 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.
After running the above instruction, the Macro.ini file includes the following text.
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 (do not include the brackets with the 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.
You can set and retrieve information from the Windows registry using the PrivateProfileString property. The following example retrieves the Microsoft Office Word 2007 program directory from the Windows registry.
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:\My Documents" in the Options subkey for Office Word 2007 in the Windows registry.