Addressing Runtime Settings with $setting

Retrieve, add, or change Uniface runtime settings. On most platforms, it is only possible to address WORKDIR and the USYS path logicals. However, on Windows, other runtime settings can be retrieved or set.

Retrieve settings:

ReturnedValue = $setting("USYS" | "", RetrieveProfile, "USYSDATA | USYSSETTINGS { | USYSSECTIONS}")

vValue = $setting("usys","paths\workdir","USYSDATA")

Add or change a setting:

$setting("USYS" | "", Section\Setting, "USYSDATA") = Value

$setting ("USYS", "[PATHS]WORKDIR", "USYSDATA") = "./bda/uniface/data"

Parameters

Parameters

Parameter

Data Type

Description

USYS

String

Runtime initialization settings; valid only if Topic is USYSDATA or USYSSETTINGS

""

 

Runtime initialization file sections. Use with USYSSECTIONS.

RetrieveProfile

String

Profile to retrieve the desired sections or settings. The profile must match the Topic. To retrieve multiple sections or settings, you can use the GOLD * and GOLD ? characters.

Section\Setting

String

Initialization or assignment setting whose value you want to retrieve or set.

USYSDATA

String

Get or set a runtime setting. Wildcards are not allowed, and the RetrieveProfile or Setting specification must include the field section in which the setting is located.

USYSSETTINGS

String

Get a list of runtime settings within the specified section. Only a limited set of runtime settings can be retrieved. Wildcards can be used for Setting, but not for Section. 

vSettings = $setting ("USYS", "*", "USYSSETTINGS")

USYSSECTIONS

String

If Source is an empty string, get a list of file sections. Equivalent to INISECTIONS.

Description

To address runtime settings, specify the Source as "USYS" and the Topic as "USYSSETTINGS" or "USYSDATA". The way the second parameter is interpreted depends on the value of Topic

$setting("USYS", "Section\Setting, "USYSDATA")

$setting("USYS", "Section\RetrieveProfile, "USYSSETTINGS")

For example, to access the value of USYSADM logical, use:

$setting("usys","paths\usysadm","USYSDATA")

Note:  The WORKDIR setting and the USYS path logicals are the only runtime settings that can be read and set on all platforms. The WORKDIR setting can be a relative path.

Modifying the WORKDIR setting immediately changes the working directory. Changing the runtime value of a USYS logical in the [paths] section has an immediate effect on file paths that are using these logicals (for example: usysadm:myasn.asn).

Addressing Runtime Settings on Windows

On Windows platforms, it is possible to read and set runtime values of many initialization settings. Runtime values are not necessarily the same as the values specified in the application's .ini. For example, if a setting was omitted in the .ini file, Uniface uses a default runtime value.

Some settings are used by Uniface only at startup and never again; changing such settings at runtime will not have any effect. Also, $setting never triggers GUI changes, so if you change a setting that has a visual effect, that effect will not be visible on the current form, but only on forms that are started after the setting was changed.

By setting Source to "USYS" and Topic to "USYSSETTINGS" or "USYSDATA", you can dynamically change the values of settings that Uniface is actually using, without modifying the .ini file or registry value it came from. However, it is only possible to do so for settings in the following sections or registry keys:

  • [upi]
  • [hotkeys]
  • [application]
  • [debug]
  • [toolbar]
  • [state]
  • [help]
  • [paths]—only WORKDIR and the logical paths that start with USYS can be read or changed at runtime

For example:

vRuntime = $setting ("usys", "hotkeys\button1", "USYSDATA")

The following restrictions apply:

  • The use of "USYS" as a Source is only supported for the Topic parameters "USYSDATA" and USYSSETTINGS. It is not supported for"USYSSECTIONS". To find out which settings in a section are supported, use $setting to retrieve a list of settings in one of the above-mentioned sections.
  • Although it is not an error to read and write settings into the registry or an .ini file that Uniface does not know about, if you try to set a runtime setting that Uniface does not support, ProcScript error -1118 will be issued. This also happens if the setting is a supported one, but it comes from a different section than the above-mentioned ones.
  • In the [hotkeys] section, you can set ALL to a value, but you cannot retrieve the value of ALL.