=====Reading and writing .INI data files=====

//by Richard Russell, May 2006//\\ \\  You may want your program to read configuration settings or user options on start up, to avoid the user having to enter them every time. One way of doing that is to use the //registry//, and this is described in the main help documentation [[http://www.bbcbasic.co.uk/bbcwin/manual/bbcwine.html#registry|here]].\\ \\  However there may be reasons why you prefer not to use the registry, for example you might like the configuration settings to be in a file which can be easily read and edited, and even transferred between different computers. In that case you can store the data in a **.INI** file, which is a text file in a standardised format. Here is an example of a .INI file:\\ \\ 
<code ini>
  [settings]
  aspect=1
  scaling=1
  filmise=0
  aperture=3
  blanking=0
  scroll=0
  henhance=0
  venhance=0

  [codec]
  compressor=mp4v
  quality=512
</code>
The file consists of a number of sections (here they are **settings** and **codec**) and within each section are one or more lines in the format "key=value". Windows makes it very easy to use such files because it provides API routines to access them.\\ \\  To read data from a .INI file you can use the following function:\\ \\ 
<code bb4w>
        DEF FNgetinistring(file$, section$, key$)
        LOCAL buf%
        DIM buf% LOCAL 255
        SYS "GetPrivateProfileString", section$, key$, "", buf%, 256, file$
        = $$buf%
</code>
You would call that from your program in the following way, using the above file (called ARCQTM.INI) as an example:\\ \\ 
<code bb4w>
        aperture = VAL(FNgetinistring(@usr$+"ARCQTM.INI", "settings", "aperture"))
        compressor$ = FNgetinistring(@usr$+"ARCQTM.INI", "codec", "compressor")
</code>
Here it is assumed that the file resides in the user's **Documents** folder. You should always specify a full path to the file.\\ \\  Arguably, a better place to store the file would be the user's **Application Data** folder, which you can do as follows:\\ 
<code bb4w>
        appdata$ = FNspecialfolder(26)
        aperture = VAL(FNgetinistring(appdata$+"ARCQTM.INI", "settings", "aperture"))
        compressor$ = FNgetinistring(appdata$+"ARCQTM.INI", "codec", "compressor")
</code>
The **FNspecialfolder** routine is listed in the main Help documentation [[http://www.bbcbasic.co.uk/bbcwin/manual/bbcwine.html#specialfolders|here]].\\ \\  The above examples retrieve the data as a string. If you know that the data will be an integer, then a simpler form can be used:\\ \\ 
<code bb4w>
        SYS "GetPrivateProfileInt", section$, key$, default%, file$ TO aperture%
</code>
The value **default%** is returned in the case where the section or key does not already exist in the .INI file, such as when first running a program. There is no equivalent system call for writing of integers and the method below should be used.\\ \\  To write data to (and if necessary create) a .INI file you can use the following procedure:\\ \\ 
<code bb4w>
        DEF PROCputinistring(file$, section$, key$, info$)
        LOCAL res%
        SYS "WritePrivateProfileString", section$, key$, info$, file$ TO res%
        IF res% = 0 ERROR 100, "Couldn't write to file "+file$
        ENDPROC
</code>
You would call that from your program as follows:\\ \\ 
<code bb4w>
        PROCputinistring(appdata$+"ARCQTM.INI", "settings", "aperture", STR$(aperture))
        PROCputinistring(appdata$+"ARCQTM.INI", "codec", "compressor", compressor$)
</code>