:Revision=3
:html
<<
128.127
IniFile-Object|IniFile
--
The IP-Object IniFile enables the reading and writing of data from resp. to Windows-Ini-files.
>>
<<
128.127.1
Functions of the IniFile-Object|Functions
--
>>
<<
128.127.1.1
IniFile.ReadString|ReadString
--
<!DEF>
function <!TW>INIFile.ReadString (sSection, sItem, sDefault : string) : string;
<!TXT>
Returns the string which is saved in the INI-File in the <!PW>sSection for the item <!PW>sItem.

If the item cannot be read, then <!PW>sDefault is returned.

<!TXT>

Example:
<!CODE>
var
  vsData : String;
Step
  // Set the INI file name, which should be used. Eine nicht
  // A INI file which doesn't exist, would be created.
  INIFile.SetFileName('%PRG%\IPHelpExample.INI');
  // Reads a string value from the INI file.
  vsData := INIFile.ReadString('SEC1', 'STRSEC1ITE1', 'Error');
  // Shows readed value in the debugging display.
  Debug.SHOW(1, 'Value: ', vsData);
  System.SetValue(0);
end.
<!TXT>

>>
<<
128.127.1.2
IniFile.ReadReal|ReadReal
--
<!DEF>
function <!TW>INIFile.ReadReal (sSection, sItem : string; rDefault : real) : real;
<!TXT>
Returns the number which is saved in the INI-File in the section <!PW>sSection for the item <!PW>sItem. 

If the item cannot be read or if the item value is not a number, then <!PW>rDefault is returned.

The item value can be also a Hex-number. In this case the item value must start with $.

<!TXT>

Example:
<!CODE>
var
  vrData : Real;
Step
  // Set the INI file name, which should be used. Eine nicht
  // A INI file which doesn't exist, would be created.
  INIFile.SetFileName('%PRG%\IPHelpExample.INI');
  // Reads a real value from the INI file.
  vrData := INIFile.ReadString('SEC1', 'STRSEC1ITE1', 0);
  // Shows readed value in the debugging display.
  Debug.SHOW(1, 'Value: ', vrData);
  System.SetValue(0);
end.
<!TXT>

>>
<<
128.127.1.3
IniFile.EOF|EOF
!128.127.3.2 - Example read INI file
--
<!DEF>
function <!TW>INIFile.EOF : real;
<!TXT>
Returns <!RW>TRUE, if there is no other item in the section.
>>
<<
128.127.1.4
IniFile.Name|Name
!128.127.3.2 - Example read INI file
--
<!DEF>
function <!TW>INIFile.Name : string;
<!TXT>
Returns the name of the current item of the scanned section.
(the part before '=')
>>
<<
128.127.1.5
IniFile.Value|Value
!128.127.3.2 - Example read INI file
--
<!DEF>
function <!TW>INIFile.Value : string;
<!TXT>
Returns the value of the current item of the scanned section
(the part after '=')
>>
<<
128.127.2
Procedures of the IniFile-Objects|Procedures
--
>>
<<
128.127.2.1
INIFile.WriteString|WriteString
!128.127.3.1 - Example write INI file
--
<!DEF>
procedure <!TW>INIFile.WriteString (sSection, sItem, sValue : string);
<!TXT>
Writes the string <!PW>sValue in the section <!PW>sSection for the item <!PW>sItem.

Example:
<!CODE>
IniFile.WriteString ('LastDUT', 'Barcode', '12345678A87654321');
<!TXT>

Generates in INI-File:
<!CODE>
[LastDUT]
Barcode=12345678A87654321
<!TXT>
>>
<<
128.127.2.2
INIFile.WriteReal|WriteReal
!128.127.3.1 - Example write INI file
--
<!DEF>
procedure <!TW>INIFile.WriteReal (sSection, sItem : string; rValue : real);
<!TXT>
Writes the real value <PW>rValue in the section <!PW>sSection for the item <!PW>sItem.

The number is converted to a string (maximum 15 position precision).

Example:
<!CODE>
IniFile.WriteString ('Constants', 'Result', 3*3+4*4);
<!TXT>

Generates in INI-File:
<!CODE>
[Constants]
Result=25
<!TXT>
>>
<<
128.127.2.3
IniFile.EraseSection|EraseSection
--
<!DEF>
procedure <!TW>IniFile.EraseSection (sSection : string);
<!TXT>
Deletes the section <!PW>sSection in the INIFile.

<!TXT>

Example:
<!CODE>
step
  // Set the INI file name, which should be used. Eine nicht
  // A INI file which doesn't exist, would be created.
  INIFile.SetFileName('%PRG%\IPHelpExample.INI');
  // Deletes the passed section from the INI file.
  INIFile.EraseSection('SEC2');
  System.SetValue(0);
end.
<!TXT>

>>
<<
128.127.2.4
IniFile.SetFileName|SetFileName
!128.127.3.1 - Example write INI file
!128.127.3.2 - Example read INI file
--
<!DEF>
procedure <!TW>INIFile.SetFileName (sFileName : string [; rAutoSynchronize : real]);
<!TXT>
Selects an INI-file. 

Default is IPS_DATA.INI in the type data directory.

If <!PW>sFileName is empty (''), then the default file is reselected.

 <!PW>sFileName may contain path templates.

If <!PW>rAutoSynchronize is  <!RW>TRUE, the data will be synchronized with the file on disc <i>before every read operation </i> and <i>after every write access</i>. Thsi might be necessary under very special circumstances and is more convenient than calling <!RW>Inifile.Synchronize every time. Default for <!PW>rAutoSynchronize is <!RW>FALSE.
>>
<<
128.127.2.5
IniFile.Load|Load
!128.127.3.2 - Example read INI file
--
<!DEF>
procedure <!TW>INIFile.Load (sSection);
<!TXT>
Reads (Scans) in the entire section <!PW>sSection.

The items an be enquired with <!RW>Inifile.First/<!RW>Next/<!RW>Name/<!RW>Value.

If <!PW>sSection is empty (''), then the list of sections existing in the INI-File are read. 
The section data can be enquired with <!RW>Inifile.First/<!RW>Next/<!RW>Name.
>>
<<
128.127.2.6
IniFile.First|First
!128.127.3.2 - Example read INI file
--
<!DEF>
procedure <!TW>INIFile.First;
<!TXT>
Sets the internal pointer on the first item of the section scanned previously.
>>
<<
128.127.2.7
IniFile.Next|Next
!128.127.3.2 - Example read INI file
--
<!DEF>
procedure <!TW>INIFile.Next;
<!TXT>
Sets the internal pointer to the next item of the section scanned previously.
>>
<<
128.127.2.8
IniFile.Synchronize|Synchronize
--
<!DEF>
procedure <!TW>INIFile.Synchronize;
<!TXT>
Forces the synchronization between the Windows internal buffer and the physical represantation of the file.

Normaly, this synchronization is not neccessary.

In cases with a consistent need for synchronization, the <!SW>rAutoSynchronize parameter  of the <!RW>SetFilename procedure should be set to <!RW>True.
>>
<<
128.127.2.9
IniFile.EraseFile|EraseFile
--
<!DEF>
procedure <!TW>INIFile.EraseFile;
<!TXT>
Deletes the INI-File.

<!TXT>

Example:
<!CODE>
step
  // Set the INI file name, which should be used. Eine nicht
  // A INI file which doesn't exist, would be created.
  INIFile.SetFileName('%PRG%\IPHelpExample.INI');
  // Deletes the passed INI file.
  INIFile.EraseFile;
  System.SetValue(0);
end.
<!TXT>

>>
<<
128.127.3
Examples with INI files|Examples
--
>>
<<
128.127.3.1
Example write INI file|Write INI file
!128.127.2.4 - Procedure SetFileName
!128.127.2.1 - Procedure WriteString
!128.127.2.2 - Procedure WriteReal
--

With the following example a INI file with any entries could be created or enlarged.

<!TXT>

Example:
<!CODE>
var
  vrSectionIndex : Real;
  vsSectionName  : String;
  vrItemIndex    : Real;
  vsItemName     : String;
step
  // Set the INI file which should be readed or written. A non existing
  // INI file would be created. A Existing INI file would be enlarged.
  INIFile.SetFileName('%PRG%\IPHelpExample.INI');
  for vrSectionIndex := 1 to 4 do begin
    for vrItemIndex := 1 to 3 do begin
      vsSectionName := 'Sec' + Str(vrSectionIndex);
      vsItemName := vsSectionName + 'Ite' + Str(vrItemIndex);
      // Writes a string into the INI file in the specified section for the specified item.
      // If the section or the item doesn't exist, they would be created.
      INIFile.WriteString( vsSectionName, 'Str' + vsItemName, 'Val' + Str(vrItemIndex) );
      // Writes a real value into the INI file in the specified section for the specified item.
      // If the section or the item doesn't exist, they would be created.
      INIFile.WriteReal( vsSectionName, 'Rea' + vsItemName, vrItemIndex);
    end;
  end;
  System.SetValue(0);
end.
<!TXT>

>>
<<
128.127.3.2
Example read INI file|Read INI file
!128.127.2.4 - Procedure SetFileName
!128.127.2.5 - Procedure Load
!128.127.2.6 - Procedure First
!128.127.1.4 - Function Name
!128.127.1.5 - Function Value
!128.127.2.7 - Procedure Next
!128.127.1.3 - Function EOF
--

The following example reads a INI file.

<!TXT>

Example read sections:
<!CODE>
step
  // Set the INI file which should be readed or written. A non existing
  // INI file would be created. A Existing INI file would be enlarged.
  INIFile.SetFileName('%PRG%\IPHelpExample.INI');
  // Loads all section from the specified INI file.
  INIFile.Load('');
  // A internal pointer is set to the first section.
  INIFile.First;
  repeat
    // The name of the pointed section is read and displayed in the debugging window.
    DEBUG.SHOW(1, 'Section: ', INIFile.Name );
    // The internal pointer would be set to the next section.
    INIFile.Next;
  until INIFile.EOF;  // Loop condition would be true if the last section is reached.
  System.SetValue(0);
end.
<!TXT>

Example read items:
<!CODE>
step
  // Set the INI file which should be readed or written. A non existing
  // INI file would be created. A Existing INI file would be enlarged.
  INIFile.SetFileName('%PRG%\IPHelpExample.INI');
  // load from the INI file a complete section with all items and their values.
  INIFile.Load('Sec1');
  // A internal pointer is set to the first section.
  INIFile.First;
  repeat
    //Read the name of the Item and display it in the debugging window.
    DEBUG.SHOW(1, 'Item Name  : ', INIFile.Name );
    //Read the value of the Item and display it in the debugging window.
    DEBUG.SHOW(1, 'Item Value : ', INIFile.Value );
    // The internal pointer would be set to the next item.
    INIFile.Next;
  until INIFile.EOF;  // Loop condition would be true if the last item in the section is reached.
  System.SetValue(0);
end.
<!TXT>
>>

