WD: Macros to Read Data from a Private .ini File

ID: Q81793

The information in this article applies to:

SUMMARY

You can write macros that use a settings file to store and retrieve 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 with information arranged like the information in the Windows 3.x Win.ini file. On the Macintosh, a settings file is a resource file such as Word Settings (97).

This article discusses methods you can use to extract information from a settings file other than the Win.ini file. Each method and example is specific to a version of Microsoft Word.

MORE INFORMATION

Word for Windows 6.0, 7.0, 7.0a

WARNING: ANY USE BY YOU OF THE MACRO CODE PROVIDED IN THIS ARTICLE IS AT YOUR OWN RISK. Microsoft provides this macro code "as is" without warranty of any kind, either express or implied, including but not limited to the implied warranties of merchantability and/or fitness for a particular purpose.

GetPrivateProfileString:

The GetPrivateProfileString function was added in Word version 6.0. Use GetPrivateProfileString to return a setting from a private settings file.

A settings file is a text file such as Win.ini that your macros can use to store and retrieve settings.

The following is an example of the GetPrivateProfileString$() command. 

   Sub MAIN
      temp$ = GetPrivateProfileString$("Section Name", "keyname", \ 
      "H:\winword\text.ini")
      MsgBox temp$
   End Sub
The above macro reads the contents the Text.ini file and posts the contents of "keyname=" heading in a message box.

The GetPrivateProfileString function reads a character string from the specified section of the specified initialization file. The return value is the number of characters copied into the buffer if successful or 0 (zero) if unsuccessful.

Word for the Macintosh 6.0, 6.0.1

The following is an example of the GetPrivateProfileString$() command. 

   Sub MAIN
      temp$ = GetPrivateProfileString$("Microsoft Word", "INI-Path", \ 
      "Word Settings (6)")
      MsgBox temp$
   End Sub
The above macro reads the contents the Word Settings (6) file and posts the contents of "INI-Path=" heading in a message box.

The GetPrivateProfileString function reads a character string from the specified section of the specified initialization file. The return value is the number of characters copied into the buffer if successful or 0 (zero) if unsuccessful.

Word for Windows 2.x

According to the Microsoft Windows Software Development Kit documentation, the GetPrivateProfileString function has the following parameters: 

   INT GetPrivateProfileString(lpszSectionName, lpszKeyName, lpszDefault,
   lpszReturnBuffer, cbReturnBuffer, lpszFileName)

   LPCSTR lpszSectionName;    section name
   LPCSTR lpszKeyName;        keyname
   LPCSTR lpszDefault;        default return string
   LPSTR lpszReturnBuffer;    variable assignment for INI information
   int cbReturnBuffer;        size of the destination buffer
   LPCSTR lpszFileName;       initialization filename

   [section name]
   keyname=string to read
The following WordBasic macro demonstrates the use of the Windows GetPrivateProfileString function: 

   Declare Function GetPrivateProfileString Lib "kernel" \ 
   (lpApplicationName$, lpKeyName$, lpDefault$, lpReturnedString$, \ 
   nSize As Integer, lpFileName$)  As Integer

   Sub MAIN
      a = GetPrivateProfileString("Section Name", "keyname", "", Temp$,\ 
      255,"H:\WINWORD\Text.ini")
      MsgBox Temp$
   End Sub
The above macro reads the contents the Text.ini file and posts the contents of "keyname=" heading in a message box.

The GetPrivateProfileString function reads a character string from the specified section of the specified initialization file. The return value is the number of characters copied into the buffer if successful or 0 (zero) if unsuccessful.

NOTE: To obtain a string from the Win.ini file use the WordBasic "GetProfileString" function.

REFERENCES

"Microsoft Windows Software Development Kit," Vol. 1, page 4-199 through page 4-200

Additional query words: WritePrivateProfileString 

Keywords          : kbmacro wordnt kbmacroexample winword ntword macword word6 winword2 word7 word95 kbhowto 
Version           : WINDOWS:2.0,2.0a,2.0a-CD,2.0b,2.0c,6.0,6.0a,6.0c,7.0,7.0a; MACINTOSH:6.0,6.0.1,6.0.6.0.1a
Platform          : MACINTOSH Win95 WINDOWS winnt
Issue type        : kbhowto kbinfo

Last Reviewed: February 4, 1998