@INIVALUE
— Returns a value
from an .INI file.
Syntax:
%@INIVALUE[
filename,
section,
entry,
index,
errorstr,
flags]
filename | the file to examine |
section | the name of the section to search for the entry |
entry | the name associated with the desired value |
index | which entry to return; defaults to 0 (the first); -1 returns the number of matching entries |
errorstr | the string to return on any error; defaults to nothing (the empty string) |
flags | a 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.