SetPrivateProfileString, SetPrivateProfileString()

Syntax

SetPrivateProfileString Section$, KeyName$, Setting$, Filename$

SetPrivateProfileString(Section$, KeyName$, Setting$, Filename$)

Remarks

Defines or redefines a setting in a settings file, a file that your macros can use for storing and retrieving settings. For example, you can store the name of the active document when you quit Word so that it can be reopened automatically the next time you start Word. In Windows, a settings file is a text file such as WINWORD6.INI. On the Macintosh, a settings file is a resource file such as Word Settings (6). In Windows 95 and Windows NT, you can use SetPrivateProfileString to assign a setting to a value in the registry.

Argument

Explanation

Section$

The name of the section in the settings file that contains the key you want to set. In Windows, this is the name that appears between brackets before the associated keys (do not include the brackets with Section$).

If you are using SetPrivateProfileString in Windows 95 or Windows NT to assign a setting to a value in the registry, Section$ should be the complete path to the key, including the root (for example, "HKEY_CURRENT_USER\Software\Microsoft\Word\6.0\Options".

KeyName$

The key to set. In a Windows settings file, the key name is followed by an equal sign (=) and the setting.

If you are using SetPrivateProfileString in Windows 95 or Windows NT to assign a setting to a value in the registry, KeyName$ should be the name of the value in the key specified by Section$ (for example, "MessageBeeps").

Setting$

The new setting.

Filename$

The filename for the settings file. If a path is not specified, the Windows folder (Windows) or the Preferences folder (Macintosh) is assumed. If the file does not already exist, Word creates it.

If you are using S etPrivateProfileString in Windows 95 or Windows NT to assign a setting to a value in the registry, Filename$ must be an empty string ("").


The SetPrivateProfileString() function behaves the same as the statement and also returns a value indicating whether the action was successful: –1 means the key was set, 0 (zero) means the key was not set. Keys cannot be set if the settings file is read-only.

Example

This pair of auto macros automatically opens the document that was active the last time you quit Word. On the Macintosh, substitute a settings filename such as MY SETTINGS for MY.INI.

The following is the AutoExit macro. If the active window is a macro-editing window, the If conditional prevents Word from writing the macro name to the settings file. This prevents an error from occurring in the AutoExec macro.


Sub MAIN
If SelInfo(27) <> -1 Then a$ = FileName$()
check = SetPrivateProfileString("Word Info", "LastActive", a$, \
    "MY.INI")
If check = 0 Then MsgBox "Could not set INI option."
End Sub

The following is the AutoExec macro:


Sub MAIN
name$ = GetPrivateProfileString$("Word Info", "LastActive", \
    "MY.INI")
If name$ <> "" Then FileOpen .Name = name$
End Sub

See Also

GetProfileString$(), GetPrivateProfileString$(), SetProfileString, ToolsAdvancedSettings