CaptureSettings

Code Layer

Description: Gathers a single property value or an accumulated section and returns the result in a tabular format.
Returns: Object (Results are returned via a parameter)
Usage: Script Only.
Function Groups: Configuration Management
Related to: GetINIProperty |
Format: \CaptureSettings(Section, ValueName, pResult[, CallerHasLock])
Parameters:  
Section
Required. The name of the section where the property will be found.
ValueName
Required. The name of the property to return. Set to Invalid to retrieve the entire section.
pResult
Required. A pointer to a variable, in which the retrieved property or properties will be returned. See comments.
CallerHasLock

Optional Boolean. Set to TRUE if the caller holds the semaphore.

If you did not set a lock using AcquireLock or are not launching this module that is know to have a lock, set to FALSE or omit.
Comments:

A launched module, this function's return value is a reference to itself which becomes invalid when the operation completes. The caller must not slay itself while this object is valid. The check is performed in a critical section to prevent result corruption due to settings changes on other threads.
Comments are not included in the output, but hidden values are.

pResult can be any of the following:

  • If ValueName was provided and there is only one setting in the section with that name, it will be that one value (not an array).

  • If ValueName was provided and the setting appears multiple times in the section, then it will be a 1-dimensional array of those values.

  • If ValueName was not provided, then it will be a 2d array of all of the setting names+values in the section. For example, pResult[0][0] will contain the first setting name and pResult[1][0] will return its value.

If the property is found in more than one settings file, the returned result will be the one from the file with the highest priority. In order from lowest to highest priority, these are: SETUP.INI, Settings.Startup, Settings,Dynamic, Workstation.Startup, Workstation.Dynamic

Examples:

Init [
  If 1 WaitingForCaptureSettings;
  [
    CaptureObj = \CaptureSettings("Section", "ValueName", &Result);
  ]
]
WaitingForCaptureSettings [
  If !Valid(CaptureObj);
  [
    { Do something with Result }
  ]
]