@INIVALUE — Returns a value from an .INI file.

Syntax:
%@INIVALUE[filename,section,entry,index,errorstr,flags]

filenamethe file to examine
sectionthe name of the section to search for the entry
entrythe name associated with the desired value
indexwhich entry to return; defaults to 0 (the first); -1 returns the number of matching entries
errorstrthe string to return on any error; defaults to nothing (the empty string)
flagsa bitmapped integer controlling advanced features:
   1 — bomb out on file errors
   2 — treat section as a wildcard to match
   4 — treat entry as a wildcard to match

This function is essentially @INIREAD without GetPrivateProfileString(). It can handle some things that @INIREAD can’t, such as UTF-8 .INI files, sectionless values, multiple values with the same name, and multiple headers for the same section.

You must specify the full name and extension of the filename. If you do not include a path, the file is assumed to be in the Windows directory, not in the current directory! To force this function to look in the current directory, begin the filename with .\.

If you do not specify a section, the function will look for a matching entry before the first section header. If section is an asterisk, the function will look for a matching entry throughout the file, ignoring all section headers.

Sometimes an .INI file will contain multiple lines with the same entry name. For example, TCMD.INI may have more than one NormalKey directive. You can loop through multiple entries with the index argument. An index of 0 returns the first matching entry, 1 returns the second, and so on. Set index to -1 to return the number of matching entries.

The default behavior is to return an empty string on any error: file not found, access denied, or no matching section or entry. If you specify an errorstr, then that value will be returned instead. (This is useful if the .INI file can contain empty values.) Additionally, you can set flags to 1, and any error opening the file will result in an error message instead of returning a string value. You can also check the _INIVALUERC internal variable to get information about the last call to @INIVALUE.

See also: the _INIVALUERC variable, which returns an exit code for this function.