ACC: How to Use Get, WritePrivateProfileString Functions 1.x/2.0

• Microsoft Access versions 1.0, 1.1, 2.0

SUMMARY

Advanced: Requires expert coding, interoperability, and multiuser skills.

Microsoft Access version 2.0 does not have a simple function to store or access settings in .INI files (that is, a log of users, window position settings, and so on). However, you can use the Microsoft Windows 3.1 application program interface (API) through Access Basic to read or write settings in an .INI file.

MORE INFORMATION

The GetPrivateProfileString() and WritePrivateProfileString() functions enable you to create new sections, keys or key values, retrieve key values, or modify existing key values.

How to Create the GetIniKeyValue() Function

1. Create a new module.



2. Type the following declarations in the Global Declarations section:
   
   NOTE: In the following sample code, an underscore (_) at the end of a line is used as a line-continuation character. Remove the underscore from the end of the line when re-creating this code in Access Basic.
   
   Option Explicit
   
   

   
         Declare Function alias_GetPrivateProfileString Lib "Kernel"_
            Alias "GetPrivateProfileString"_
            (ByVal lpapplicationname as string, _
            ByVal lpkeyname as String, _
            ByVal lpDefault as String
            ByVal lpreturnedstring as String, _
            ByVal nSize as Integer,
            ByVal lpfilename as String) as Integer
   
   
         Declare Function alias_WritePrivateProfileString Lib "Kernel" _
            Alias "WritePrivateProfileString" _
            (ByVal lpapplicationname as String, _
            ByVal lpkeyname as String, _
            ByVal lpString as String, _
            ByVal lpfilename as String) as Integer 

   
   
   NOTE: The lpkeyname argument for GetProfileString, WriteProfileString is declared as type Any in the Microsoft Access help file. This is because lpkeyname can be either a string or Null. lpkeyname is declared as string in this example to simplify use of the function.
   
   NOTE: You may have these Microsoft Windows API functions defined in an existing Microsoft Access library or module; therefore, your declarations may be duplicates causing a duplicate procedure name error message. There are two resolutions to this error.

• Remove or comment out the duplicated declarations statements.



• Use function aliasing by replacing the phrase "alias_" throughout the code below with your own unique aliasing characters. This method allows you to remove the other module and not lose the declarations for the API functions in the new module. For more information on aliasing see page 369 of the "Building Applications" book.

1. Type the following function in the module:
   

   
       '*************************************************************
       '  FUNCTION: GetIniKeyValue()
       '
       '     Used to return the value of a key in an .ini file. While you
       '     could call alias_GetPrivateProfileString directly it's return
       '     value is the number of characters read. It does not return the
       '     characters that make up the key value.
       '     alias_GetPrivateProfileString fills a buffer that you set
       '     aside(lpReturnedString in this example function) with the
       '     actual key value. GetIniKeyValue() returns this key value.
       '     If you provide an invalid file name, section or key
       '     this function returns the default key value.
       '
       '  ARGUMENTS:
       '
       '     lpFileName   - the .INI Filename (found in the
       '                    Windows directory by default).
       '     lpApplicationName  - is the section title that appears in
       '                          square brackets in the .INI file.
       '     lpKeyName          - The .INI file entry that points to the
       '                          key (followed by an equal sign).
       '     lpDefault          - Return value when key is not found.
       '
       '  EXAMPLE:
       '
       '     To find out the value of the Load= line in the [windows]
       '     section of the WIN.INI file type the following into the
       '     immediate window.
       '
       '     ?GetIniKeyValue("c:\windows\win.ini","windows","load","")
       '
       '*************************************************************
         Function GetIniKeyValue(lpFileName, lpApplicationName, _
              lpKeyname,lpDefault)
   
             Dim lpReturnedString As String
             Dim nSize As Integer
             Dim CharReturned As Integer
   
             On Error GoTo GetIni_err
   
             lpReturnedString = Space$(255)
             'Set aside the lpReturnedString variable as a 255 character
             'buffer to hold the key value filled by
             'alias_GetPrivateProfileString.
   
             nSize = Len(lpReturnedString)
             'Tell the alias_GetPrivateProfileString function how how many
             'characters the lpReturnedString buffer can hold so it doesn't
             'over fill it.
   
             CharReturned = alias_GetPrivateProfileString(lpApplicationName,_
                 lpKeyname, lpDefault, lpReturnedString, nSize, lpFileName)
             'CharReturned is the number of characters returned by the
             'alias_GetPrivateProfileString function. This can be used in
             'error trapping to see if the lpReturnedString has been
             'truncated.
   
             GetIniKeyValue = lpReturnedString
             'Pass the key value out of the GetIni() function.
   
             Exit Function
   
         GetIni_err:
   
             MsgBox Error$
             Exit Function
   
         End Function
   
       '*************************************************************
       '  FUNCTION: WriteIniKeyValue()
       '
       '     Used to Set the value of a key in an .ini file. You
       '     could call alias_WritePrivateProfileString directly.
       '
       '  ARGUMENTS:
       '
       '     lpFileName         - the .INI Filename (found in the
       '                          Windows directory by default).
       '     lpApplicationName  - is the section title that appears in
       '                          square brackets in the .INI file.
       '     lpKeyName          - The .INI file entry that points to the
       '                          key (followed by an equal sign).
       '     lpDefault          - Return value when key is not found.
       '
       '  EXAMPLE:
       '
       '     To set the value of the load= line in the [windows] section
       '     of the WIN.INI file to load=write type the following into
       '     the immediate window.
       '
       '     ?WriteIniKeyValue("c:\windows\win.ini","windows","load",_
       '          "write")
       '
       '*************************************************************
         Function WriteIniKeyValue(lpFileName, lpApplicationName, lpKeyname,_
             lpString)
   
             WriteIniKeyValue = alias_WritePrivateProfileString_
                 (lpApplicationName, lpKeyName, lpString, lpFileName)
   
         End Function 

REFERENCES

Microsoft Access "Introduction to Programming," version 1.0, chapters 1-5

Microsoft Access "Language Reference," version 1.0, Part 1

"Microsoft Windows Software Development Kit," Microsoft Press, 1992

"Programming Windows: the Microsoft Guide to Writing Applications for Windows 3," Charles Petzold, Microsoft Press, 1990

"Programmer's Reference Library: Microsoft Windows 3.1 Guide to Programming Reference," Volumes 1-6, Microsoft Press, 1992

Keywords          : kbprg 
Version           : 1.0 1.10 2.0
Platform          : WINDOWS 
Issue type        : kbhowto 

Last Reviewed: March 11, 1999