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

Last reviewed: June 8, 1997
Article ID: Q90988
The information in this article applies to:
  • 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.
    
    
  3. Remove or comment out the duplicated declarations statements.
  4. 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
      
      
    NOTE: This example does not have error trapping. Unexpected results may occur if the declarations and the variable types are not correct or your file is not in the location specified or does not exist.

    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 PgmApi
Version : 1.0 1.10 2.0
Platform : WINDOWS
Hardware : X86
Issue type : kbhowto


THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY.

Last reviewed: June 8, 1997
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.