Addressing Initialization and Assignment Settings with $setting

Parameters

vSettings = $setting ("", "upi\*", "INISETTINGS")

vSections = $setting ("C:\my_app.ini", "u*", "INISECTIONS")

Syntax of RetrieveProfile and Setting

The second parameter of $settings can specify a retrieve profile or a specific setting. You can use the following syntax:

Section\Setting

If Topic is INISETTINGS and INIDATA, the Section must be explicitly defined. If Setting is empty, an error is returned if Topic is INISETTINGS or INIDATA.

If Topic is INISECTIONS, specifying Setting returns an error.

Effect of Topic on Second Parameter

The way Uniface interprets the second parameter depends on the value of the Topic parameter.

• When Topic is INIDATA, the second parameter is always interpreted as a specific setting and it cannot contain wildcards (GOLD * and GOLD ?) . The setting specification must include the file section. For example:

  ; set the value of the translines setting 
  $setting("usys.ini","upi\translines", "INIDATA") = 5000
  
  ; retrieve the value of Uniface's javascript path:
  vSetting = $setting("usys.ini","paths\javascript", "INIDATA")

• When Topic is INISETTINGS or INISECTIONS, the second parameter is interpreted as a retrieve profile, so it can contain wildcards (GOLD * and GOLD ?). For example:

  ;retrieve vSections = $setting("","*","INISECTIONS")
  vSettings = $setting("usys.ini","paths\*", "INISETTINGS")
   

  Note: When using INISETTINGS, it is not possible to use wildcards in both the Section and Setting part of the second parameter. 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. See Retrieve a List of All Settings in a Source.

• When Topic is INIDATA, if the specified Section, Setting, or Value is larger than the maximum length, error -1118 is returned.

Adding or Changing a Setting

You can add or modify a setting only if Topic is INIDATA. If the setting does not exist, it is added to the end of the section. If the setting already exists, the value is changed.

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

Using $setting with Initialization Files

On Windows, the global (and default) initialization file is usys.ini. You can specify the ConfigFile as an empty string (so usys.ini is used) or as a specific initialization file. On other platforms, initialization files are user-defined.

When retrieving multiple sections or sections, use a retrieve profile (GOLD *).

For example:

• To retrieve a list of sections starting with U from an my_app.ini file:

  vSections = $setting ("C:\my_app.ini", "u*", "INISECTIONS") 

• To retrieve a list of settings within a section of usys.ini:

  vSettings = $setting ("", "upi\*", "INISETTINGS")

• Retrieve the value of a specific setting in usys.ini:

  vValue = $setting ("", "upi\msglines", "INIDATA")
  ;vValue = $setting ("", "[upi]msglines", "INIDATA") ;alternative Setting syntax

• To modify or add a specific setting to the my_app.ini file:

  $setting ("C:\my_app.ini", "upi\msglines", "INIDATA") = 5 

Using $setting with Assignment Files

Uniface assignment files have the same format as initialization files, so it is possible to manipulate assignment settings and file sections as if they were initialization settings.

However, $settings behaves slightly differently for an assignment file than an initialization file:

• It determines the assignment file semantics based on the file name (it must end in .asn) and the section name (it must be a valid section file name).
• For Uniface assignment files, settings in the [SETTINGS] and [PROXY_SETTINGS] sections can be specified with or without underscores.
• A setting that does not take a value, returns the string value "True". In initialization files, such a setting returns an empty string "".