SetINIProperty

(System Library)

Description:	Given an INIFiles structure, this function sets the property with the specified name and section to the specified value. Does not affect the running system until WritePropertiesFile is called.
Returns:	Reference to the INIProperty structures for the specified section.
Usage:	Script Only.
Function Groups:	Configuration Management, Variable
Related to:	ReadPropertiesFile \| WritePropertiesFile \| GetINIProperty
Format:	System.SetIniProperty(pProperties, Section, Name, Value, Comment, pFail)
Parameters:

pProperties

Required. An INIFiles structure.

Section

Required. The name of the section in which the property belongs.

Name

Required. The name of the property being modified.

Value

Required. The value to set for the given property.

Comment

An optional text expression for the comment to write. If invalid, the existing comment (if any) for the property will be used.

pFail

A pointer to a Boolean value. Will be set TRUE if the operation fails.

Comments:

This function does not change the property in configuration - it only changes the value in the INIFiles structure, which is obtained using a call to ReadPropertiesFile.
The standard usage is to obtain the structure using ReadPropertiesFile, modify a value using SetINIProperty, then write the structure back to disk using WritePropertiesFile.

The INIFiles structure returned is as follows:

INIFiles Struct [
  FileName    { full path and file name to the settings file          };
  OEM         { TRUE if an OEM layer file                             };
  Workstation { Name of the workstation or invalid if global          };
  Layer       { Instance of application layer owning the file         };
  Dynamic     { TRUE if a dynamic property                            };
  Sections    { Dictionary of sections each element of which 
                is an array of Property structures         };
  Changed     { User sets to true if the file has been changed,
                initialized to false                                  };
 ]

The INIProperty structure is…

INIProperty Struct [
    Name        { Variable name in the .startup/.dynamic file  };
    Value       { Simple value                                 };
    Comment     { Text comment if present in the file          };
    Hidden      { TRUE if not visible in Edit Properties GUI   };
  ];