$setting

Retrieve, add, or change configuration settings. Depending on the platform, settings may be stored in initialization files, assignment files, environment variables, logicals, data areas, or the Windows Registry.

Retrieve settings or sections:

ReturnedValue = $setting(Source,RetrieveProfile,Topic)

vSections = $setting ("C:\my_app.ini", "u*", "INISECTIONS") ; retrieve a list of file sections
vEnvVar = $setting ("", "SRC", "ENVDATA") ; retrieve the value of an environment variable

Add or change a setting:

$setting (Source,Setting, Topic) = Value

$setting ("C:\my_app.ini", "upi\msglines", "INIDATA") = 5 ; set value of msglines to 5

Parameters

Parameters
Parameter	Data Type	Description
Source	String	Location of the setting or settings. Valid values depend on the platform and must be supported by the Topic. Empty string (`""`)—default source for the platform. On Windows, the default source depends on the specified Topic. On other platforms, the default sources are environment variables (Unix, Linux, iSeries), or registry values (Windows). ConfigurationFile—name of an initialization file or assignment file. An assignment file must end with the .asn extension. For more information, see Addressing Initialization and Assignment Settings with $setting. USYS—runtime settings. Except on Windows, it is only possible to address WORKDIR and the USYS path logicals. For more information, see Addressing Runtime Settings with $setting . On iSeries only, a platform-specific value or keyword that species a system or global location. For more information, see Addressing Environment Variables with $setting . For the supported values for each platform, see Values of Source Argument per Platform.
Topic	String	Topic—keyword defining the information that needs to retrieved or set in the specified Source. See Values of Topic. Topic determines how the first and second arguments are interpreted. The Source and Topic must match.
RetrieveProfile	String	Retrieve profile for settings or sections, appropriate to the Topic; it can include wildcards (GOLD * and GOLD ?).
Setting	String	Specification for the setting. When setting initialization, assignment, or runtime settings, it must include the file section or Registry key: Section`\`Setting See Specifying Settings.

Values of Topic

The Topic determines the way that the Source and RetrieveProfile or Setting arguments are interpreted.

Allowed Values for Topic
Value of Topic	Description
`INIDATA` `INISECTIONs` `INISETTINGS`	Get or set settings in initialization or assignment files. For more information, see Addressing Initialization and Assignment Settings with $setting.
`USYSDATA` `USYSSECTIONS` `USYSSETTINGS`	Get or set runtime settings. For more information, see Addressing Runtime Settings with $setting . Note: The WORKDIR setting and the USYS path logicals are the only runtime settings that can be read and set on all platforms.
`ENVDATA` `ENVVARS`	Get or set environment variables or their platform-specific equivalents. Data areas and environment variables on iSeries. On Windows, Linux and Unix, it is only possible to address environment variables for the current process. For more information, see Addressing Environment Variables with $setting .
`REGDATA` `REGVALUES` `REGKEYS`	Get or set registry values on Windows only. For more information, see Addressing Registry Keys with $setting.

Return Values

$setting returns the value of a setting or a Uniface list that matches the profile specified by the RetrieveProfile argument.

If no data matches the pattern, an empty list ("") is returned and $procerror is set to 0.

If an error occurred, an empty list is returned and $procerror is set to the exact error number.

Values commonly returned by $procerror following $settings
Value	Error Constant	Meaning
`0`	UACT_SUCCESS	Success. This value is also returned if no results were returned because the data does not exist.
`-4`	UIOSERR_OPEN_FAILURE	The specified source could not be opened.
`-12`	UIOSERR_FILE_READ_WRITE	An error occurred while trying to read or write to the file, registry, or environment variable.
`-1118`	UPROCERR_ARGUMENT	The argument specified is incorrect. For example, the Setting does not exist or is incorrectly specified. This error is returned if: Setting is empty and Topic is INISETTINGS, USYSSETTINGS, ENVVARS, INIDATA, or USYSDATA. Setting is specified and Topic is INISECTIONS or USYSSECTIONS. Topic is INIDATA and the section, setting, or value string parameter exceeds the maximum length. Note: It is not an error for REGVALUES and REGDATA because every local registry key has an unnamed value (Default), and an empty Setting matches this value.

Use

Allowed in all component types.

Description

The $setting function enables you to:

Set the value of a setting. If it does not exist, the setting is added to the specified source. If the setting is in an initialization or assignment file, the field section must be specified.
Retrieve a list of settings.
Retrieve a list of file sections or registry keys.

It is not possible to add or change a file section using $setting.

To delete a setting, use deletesetting. For more information, see deletesetting.

The $setting ProcScript function accepts all Unicode, but returns an error status if environment variables are used and the data contains characters that are not in $SYS_CHARSET. It also returns an error if the name of the setting does not conform to the rules of the operating system.

Specifying Settings

The second parameter of $settings can specify a retrieve profile or a specific setting. The way Uniface interprets this parameter depends on the Topic parameter.

When Topic ends with DATA, it is always interpreted as a specific setting and it cannot contain wildcards (GOLD * and GOLD ?).

In all other cases, Topic the second parameter is interpreted as a retrieve profile that can include GOLD* and GOLD ?. For INIDATA or USYSDATA, the setting specification must include the file section. For example, to retrieve a list of settings in the [upi] section of usys.ini:

vSettings = $setting("usys.ini","upi/t*", "INISETTINGS")

The syntax used to specify a setting or a retrieve profile can be any of the following:

{Section\}Setting
{Section/}Setting
{[Section]}Setting
[Section/Setting]

Note: When addressing Windows registry keys, you can only use a backslash (\) as a path separator, not a forward slash (/).

The Section may be required or optional, depending on the Topic:

Required for INISETTINGS, INIDATA, USYSSETTINGS, or USYSDATA.
Optional for REGVALUES or REGDATA; if not specified, the default key is used, which is HKEY_CURRENT_USER\Software\Uniface\USYS10
Omitted if Topic is INISECTIONS, ENVVARS, or USYSSECTIONS, but not for REGKEYS because registry keys can have sub-keys.

Retrieving a Setting

To retrieve information about initialization settings, use the $setting function on the right side of an assignment:

vSetting = $setting ("", "paths\javascript", "INIDATA")

Or in the argument list of a function or operation as input parameter. For example:

activate MyComponent."oper"(arg1, $setting("", "SRC", "ENVDATA"), argn)

If the setting exists, the value is returned as a string and $procerror is set to 0, even if the value is an empty string.

If a setting does not exist, an empty string is returned and $procerrror is set to -1118.

Note: To retrieve a list of all initialization or assignment settings in a source, you need to first get a list of all the file sections, and then loop through that list to get a list of the settings in each section. For more information, see Retrieve a List of All Settings in a Source.

Adding or Changing a Setting

You can add or modify a setting only if the Topic parameter ends in DATA—INIDATA, REGDATA, ENVDATA, or USYSDATA. If the setting does not exist, it is added to the end of the section. If the setting does exist, the value is changed.

To set the value, put the $setting function on the left side of an assignment. For example:

$setting ("", "SRC", "ENVDATA") = "c:\u9601"

$setting ("", "HKEY_CURRENT_USER\Software\Uniface 10\greeting", "REGDATA") = "Hello"

Values of Source Argument per Platform

Values of Source on Windows
Valid Value	Description
Empty string (`""`)	usys.ini file, if Topic is one of `INISECTIONS` \| `INISETTINGS` \| `INIDATA` \| `USYSSECTIONS` \| `USYSSETTINGS` \| `USYSDATA` Environment variables, if Topic is `ENVVARS` or `ENVDATA` Registry of current machine if Topic is `REGDATA`, `REGKEYS`, or `REGVALUES`
IniFile	Name of an existing initialization file; valid only if Topic is one of `INISECTIONS` \| `INISETTINGS` \| `INIDATA` \| `USYSSECTIONS` \| `USYSSETTINGS` \| `USYSDATA`
`USYS`	Runtime initialization settings; valid only if Topic is `USYSDATA` or `USYSSETTINGS`
`//`MachineName	Registry of remote machine if Topic is `REGDATA`, `REGKEYS`, or `REGVALUES`
`"32"` \| `"64"`	Registry to address, the 32-bit registry or the 64-bit registry. On 32-bit platforms `""` is equivalent to `"32"` and on 64-bit platforms `""` is equivalent to `"64"`. Valid only when Topic is REGDATA, `REGVALUES`, or `REGKEYS`.

Values of Source on Unix and Linux
Valid Value	Description
Empty string (`""`)	Environment variable
IniFile	Name of an existing initialization file ; valid only if Topic is one of `INISECTIONS` \| `INISETTINGS` \| `INIDATA` \| `USYSSECTIONS` \| `USYSSETTINGS` \| `USYSDATA`
`USYS`	Runtime values of logical path settings (WORKDIR and USYS path logicals); valid only if Topic is `USYSDATA` or `USYSSETTINGS`.

Values of Source on iSeries
Valid Value	Description
Empty string (`""`)	Current process
IniFile	Name of an existing initialization file ; valid only if Topic is one of `INISECTIONS` \| `INISETTINGS` \| `INIDATA` \| `USYSSECTIONS` \| `USYSSETTINGS` \| `USYSDATA`
LibraryName	Name of a data area; valid only if Topic is `ENVVARS` or `ENVDATA`
`*SYS`	System-level environment variable; valid only if Topic is`ENVVARS` or `ENVDATA`
`*SYSVAL`	System-level environment variable; valid only when retrieving a value and Topic is `ENVVARS` or `ENVDATA`
`*JOB`	Job level environment variable, same as empty string; valid only if Topic is `ENVVARS` or `ENVDATA`
`USYS`	Runtime values of logical path settings (WORKDIR and USYS path logicals); valid only if Topic is `USYSDATA` or `USYSSETTINGS`.

History
Version	Change
9.6.05	Added Source values of `"32"` and `"64"` to enable alternate registry access on older Windows platforms
9.6.04	Added support for assignment settings
9.3.01	Introduced