Ini_New

IniText Ini_New (int automaticSorting);

Purpose

This function creates an object which can contain an in-memory list of tag/value pairs within sections. You can:

Since this instrument driver has not been implemented with any multithread-safe locking, we recommend that you do not share the same .ini object among multiple threads. It is all right to have multiple .ini objects among multiple threads as long has no single .ini object is shared among the threads.

This function allows you to choose whether the in-memory list is automatically sorted. See the help text for the Automatic Sorting control for information regarding how automatic sorting affects performance.

By default, each time you add an object to the in-memory list using one of the Ini_Put functions, a check is made for items with the same name. This can prevent unwanted duplicates, but it also can slow performance. You can disable this feature using the Ini_SetDuplicateChecking function.

Parameters

Input
Name Type Description
automaticSorting integer If you pass a non-zero value, the in-memory list of tag/value pairs is maintained in sorted order.

The sorting is based on section name, and tag name within section name. The sorting is done on a case-insensitive basis.

If you pass a zero value, the sections and tags are kept in the order created (or read from the file).

You can dynamically change the sorting mode by calling Ini_Sort or Ini_DisableSorting.

Effect of Sorting on Performance

If sorting is enabled, the following performance characteristics hold:

  • Getting values from the in-memory list is faster.
  • If checking for duplicates is enabled (the default), adding values to the in-memory list is faster than it would be for a non-sorted list.
  • If checking for duplicates is disabled, adding values to the in-memory list is slower than it would be for a non-sorted list. (See the Ini_SetDuplicateChecking function.)

Return Value

Name Type Description
handle IniText The handle to the object created in this function.

0 is returned if there is not enough memory.

Use this handle as the first parameter to all of the other functions in this instrument driver.