Accessing INI File Keys

An INI File is a pure ASCII Text file typically used to store settings of User Interface states or any arbitrary information. The data is organized in Categories containing any number of Keys and corresponding Values.

MAXScript provides a very error-tolerant set of functions to manage INI Files. For example, setting a new category and key in an non-existent INI file will automatically generate a new file without the need for any additional management function calls. Getting a non-existent key value from an existing file or even from a non-existent file will return an empty string without causing an error and so on.

The following methods provide read and write access to Categories, Keys and Values in INI files:

getINISetting <filename_string> <section_string> <key_string> [defaultValue:<string>]        

Reads an INI setting from the specified file. Within the file, the section identified by <section_string> is located, and then the key specified by the <key_string> is located.

The value assigned to this key is then returned as a string.

If the specified file, section, or key is not found, an empty string "" is returned.

NEW in 3ds Max 2022.2 Update:: If the optional defaultValue keyword parameter is defined, it is returned if the specified file, section, or key is not found.

EXAMPLE

   getINISetting "c:/temp/test.ini" "Directories" "Scenes"

In 3ds Max 6 and higher, if only the .ini file is specified, the method will return an array of the sections in the .ini file.

In 3ds Max 6 and higher, if only the .ini file and section are specified, the method will return an array of the keys in the section.

In 3ds Max 2017 Update 1 and higher, the return value can be up to 32,767 characters in length. In previous versions, values would be truncated at about 8000 characters.

setINISetting <filename_string> <section_string> <key_string> <key_value_string> [ forceUTF16:<boolean> ]

Sets an INI setting in the specified file.

Returns a value of true if the key value was written to the file, false if the key was not written.

Within the file, the section identified by <section_string> is located, and then the key specified by the <key_string> is located.

The <key_value_string> is then assigned to this key.

If the specified file, section, or key is not found, a new file, section, or key is created.

If the specified file is read-only, or the file is open in MAXScript, the key value is not written to the file.

EXAMPLE

   setINISetting "c:/temp/test.ini" "Directories" "Scenes" "c:/3dsmax/scenes"

The optional forceUTF16: keyword argument available in 3ds Max 2013 and higher controls whether the value is written using UTF16 encoding or as ASCII text.

By default, when the optional keyword argument is not supplied, or is supplied as true, UTF16 encoding will be used.

If the optional keyword is provided as false, the value will be written as ASCII text.

An additional method available in 3ds Max 2013 and higher controls the default behavior of the forceUTF16: optional keyword argument when it is not supplied:

<boolean>setIniForceUTF16Default <boolean>

After a fresh start, the forceUTF16: keyword argument's default value is true.

Calling setIniForceUTF16Default false will set the default encoding of the setINISetting() method to ASCII.

Calling setIniForceUTF16Default true will set the default encoding of the setINISetting() method to UTF16.

The default behavior is not sticky between sessions, after a restart it will revert back to forceUTF16: default encoding.

EXAMPLES

   setINISetting "c:/temp/deleteme.ini" "Hello" "World" "10" --utf16 encoding by default
   setINISetting "c:/temp/deleteme.ini" "Hello" "World" "10" forceUTF16:false --force ASCII
   setIniForceUTF16Default false --switch default behavior when keyword argument unsupplied
   setINISetting "c:/temp/deleteme.ini" "Hello" "World" "10" --ASCII by default
   setINISetting "c:/temp/deleteme.ini" "Hello" "World" "10" forceUTF16:true --force utf16 encoding
   setIniForceUTF16Default true --switch back to startup default 

delIniSetting <filename_string> <section_string> <key_string>   

Deletes the specified key from the supplied section of the given INI file.

delIniSetting <filename_string> <section_string> 

Deletes the section and all keys in the section of the given INI file.

hasINISetting <filename_string> <section_string> [<key_string>] 

Returns true if the INI setting exists in the specified file.

This method is available in 3ds Max 2008 and higher.

Within the file, the section identified by <section_string> is located, and then the key specified by the <key_string> is tested for.

If <key_string> is not specified, the section specified by <section_string> is tested for.

Related Methods:

getMAXIniFile() 

In 3ds Max 6 and higher, returns the current 3dsmax.ini file as a string. For some products that store the ini settings in the registry, this method returns undefined.