home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / win / vb / ini_art.txt < prev    next >
Encoding:
Text File  |  1991-11-20  |  7.9 KB  |  159 lines
  1. Windows Profile Creation with Visual BASIC
  2. Tim Jones
  3. 11/9/91
  4.  
  5. Among the vast number of challenges that a Windows application author can 
  6. run into, usage of the .INI profile files can be confusing, at least, and 
  7. down right daunting, at worst. The profile settings are a part of Windows 
  8. and most users take them for granted - until they run into an application 
  9. that requires that some minor change be made each time they start the 
  10. application.  When creating a Windows application, the author should decide 
  11. if there are any settings that a user can change that may be static for 
  12. most operational sessions.  If so, the application should use one of the 
  13. .INI profile files supported by Windows.  Using the profile mechanisms, you 
  14. can make favorite settings appear as if they were defaults and make the use 
  15. of the application easier.
  16.  
  17. Windows currently supports two types of .INI files, a public file called 
  18. WIN.INI and a application-specific, or private, .INI file.  Windows reads 
  19. the WIN.INI file each time you start up, so if your application's settings 
  20. affect Windows or other Applications, you should place your application 
  21. profile entries here.  If the settings for your application affect only the 
  22. application itself, you should use a private .INI file.  More authors 
  23. should use the private file if my WIN.INI file is any example - there are 
  24. currently 313 lines in my WIN.INI file, of which, 173 do not directly 
  25. affect Windows or other Windows applications.
  26.  
  27. An entry in either .INI file consists of a section name, in square 
  28. brackets, followed by a list of keys and their assigned values:
  29.  
  30.     [VBTerm]
  31.     PORT=2
  32.     BAUD=19200
  33.     DATA=8
  34.     STOP=0
  35.     PARITY=N
  36.     Current System=3
  37.  
  38. In this example, the section name is "VBTerm" while "PORT" and "BAUD" are 
  39. keys.  All entries are case-insensitive - in other words, PARITY = Parity = 
  40. PaRIty, so the choice of case when creating the entries is just for 
  41. appearance sake.  Additionally, the same key may appear in different 
  42. sections of the same .INI file without fear of overwriting each other.  The 
  43. Windows API calls for writing and reading entries in one or the other of 
  44. these .INI files are:
  45.  
  46.     WIN.INI                PRIVATE.INI
  47.     WriteProfileString        WritePrivateProfileString
  48.     GetProfileString        GetPrivateProfileString
  49.     GetProfileInt            GetPrivateProfileInt
  50.  
  51. Each of these items requires the name of the section (an application entry 
  52. can consist of more than one section entry as this is managed by the 
  53. application), the key name, its value for a write or a pointer to a 
  54. variable to hold its returned value on a read, the default setting and 
  55. number of bytes to read for a read and the name of the .INI file in either 
  56. case if using the private functions.  Here are the declares for 
  57. WriteProfileString and ReadProfileString and some examples:
  58.  
  59. Declare Function WriteProfileString Lib "Kernel" (ByVal lpAppName As String, 
  60.                            ByVal lpKeyName As String, 
  61.                            ByVal lpString As String) 
  62.                            As Integer
  63.  
  64. Declare Function GetProfileString Lib "Kernel" (ByVal lpAppName As String, 
  65.                         ByVal lpKeyName As String, 
  66.                         ByVal lpDefault As String, 
  67.                         ByVal lpReturnedString As String, 
  68.                         ByVal nSize As Integer) 
  69.                         As Integer
  70.  
  71. Result% = WriteProfileString("Section Name", "Key Name", KeySetting$)
  72.  
  73. Result% is actually a BOOLEAN return (either TRUE or FALSE (for the sake of 
  74. simplicity, I will define TRUE as non-Zero here)) and can be discarded 
  75. after examination.  It will be TRUE (non-Zero) if the operation was a 
  76. success and FALSE (Zero) if it failed (see below).
  77.  
  78. Result% = GetProfileString("Section Name", "Key Name", Default$, Destination$, 5)
  79.  
  80. In this case, Result% will contain the value of the actual number of bytes 
  81. read, up to the maximum value (5 in this example), or Zero if the operation 
  82. failed.  A failed attempt here usually means that either the .INI file did 
  83. not exist (in the event of a private file) or the key was not defined in 
  84. the named section.  Since this should not be a show stopper, the value in 
  85. Default$ will be assigned to Destination$.  This is the way to assign a 
  86. value even when the entries have not been made because of a first run of 
  87. the application.
  88.  
  89. Since both of these examples used the public WIN.INI file for entries, it 
  90. is not necessary to specify the name of the .INI file from which to read.  
  91. In the event of a private .INI file, you would add the name of the .INI 
  92. file as the last parameter of the WritePrivateProfileString and other 
  93. private functions.  This name can either be just the filename or a fully 
  94. qualified path and filename.  If no path is specified, the file is searched 
  95. for in the Windows directory
  96.  
  97. When using the WritePrivateProfileString function, if no path is specified, 
  98. the named .INI file will be created if it does not already exist.  If a 
  99. path is specified, however, the file will not be created.  This should be 
  100. the only reason for a FALSE return from a call to this function.  If the 
  101. key exists, the existing value is replaced by the new value.  Also, sending 
  102. NULL ("") as the  lpString value will delete the key from the section.  
  103. Sending a string name that contains NULL data (i.e. Alpha$ = "") will just 
  104. delete the value assigned to key.
  105.  
  106. One important reminder about the way that strings are handled when used in 
  107. an API function in which the string contents are changed - the string must 
  108. be initialized before the API function is called.  I learned this the hard 
  109. way.  When I read a .INI's string entry into an uninitialized string, I 
  110. ended up with a UAE.  Costas Kitsos and others on Compuserve's MSBASIC 
  111. forum provided the kick in the head required and the code sample below is 
  112. now bullet proof.  Here are sections of code that will demonstrate how to 
  113. use these functions:
  114.  
  115. -----------------------------
  116. ' Initialize the string variable to 2 bytes (N, E, or O and the NULL)
  117. TParity = String$(2, 0)
  118.  
  119. ' Check to see if entries have been made.  If TPort comes back 0, then
  120. ' no VBTERM.INI file exists.  Since TPort is an Integer, we can get its 
  121. ' value directly using GetPrivateProfileInt instead of using 
  122. ' GetPrivateProfileString and converting the returned string.
  123. TPort = GetPrivateProfileInt("VBTerm", "PORT", 0, "VBTERM.INI")
  124.  
  125. ' If TPort is 1 or 2, then we continue to process the .INI entries
  126. If TPort <> 0 Then
  127.     TBaud = GetPrivateProfileInt("VBTerm", "BAUD", 2400, "VBTERM.INI")
  128.     TWord = GetPrivateProfileInt("VBTerm", "DATA", 8, "VBTERM.INI")
  129.     TStop = GetPrivateProfileInt("VBTerm", "STOP", 1, "VBTERM.INI")
  130.     R% = GetPrivateProfileString ("VBTerm", "PARITY", "N", TParity, 2, "VBTERM.INI")
  131. ' When R% is returned, it will indicate how many characters were actually
  132. ' read by the call to GetPrivateProfileInt. We force the function to only get
  133. ' two characters by the fifth entry in the parameter list.
  134.  
  135. Else
  136.  
  137. ' Otherwise, we bring up the configuration editor
  138.     Config.Show MODAL
  139. End If
  140.  
  141. ' Once we're done, we save the values into the .INI file so we are ready
  142. ' to go next time.  We also call this if Config is run again.  Note that we
  143. ' don't have a WritePrivateProfileInt function!  In this case, R% is a
  144. ' throw-away return as described in the text above.
  145. R% = WritePrivateProfileString("VBTerm", "PORT", Str$(TPort), "VBTERM.INI")
  146. R% = WritePrivateProfileString("VBTerm", "BAUD", Str$(TBaud), "VBTERM.INI")
  147. R% = WritePrivateProfileString("VBTerm", "DATA", Str$(TWord), "VBTERM.INI")
  148. R% = WritePrivateProfileString("VBTerm", "STOP", Str$(TStop), "VBTERM.INI")
  149. R% = WritePrivateProfileString("VBTerm", "PARITY", TParity, "VBTERM.INI")
  150. -----------------------------
  151.  
  152. This example has indicated the requirements for a private .INI file.  Also, 
  153. note that the name, in this case VBTERM.INI, can be anything you want.  
  154. Using some form of the application name is best unless you are into 
  155. confusing your users.
  156.  
  157. If you have any questions, you may reach me on Compuserve as 70750,701.  
  158. Good programming!
  159.