deletesetting

Delete initialization settings.

deletesetting  Source,  Setting,  Topic

Parameters

  • Source—location of the 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, it is environment variables (Unix), or data areas (iSeries).
    • IniFile—name of an initialization file.
    • USYS—use the runtime settings.

      Note:  Except on Windows, it is only possible to address WORKDIR and the USYS path logicals.

    • Platform-specific value or keyword. For more information, see Values of Source per Platform .

  • Setting—setting or section specification; the syntax is {Section\}Setting or {[Section]}Setting.

    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.
    • Omitted if Topic is INISECTIONS or USYSSECTIONS, but not for REGKEYS because registry keys can have sub-keys.

    Wildcards (GOLD * and GOLD ?) are supported except for INIDATA, USYSDATA, ENVDATA or REGDATA.

  • Topic—keyword defining the setting or settings to be deleted, depending on the Source. For more information, see Values of Topic.

Values of Topic

Allowed Values for Topic
Value of Topic Description
INIDATA Delete the setting. Wildcards are not allowed.
INISETTINGS Delete settings in the specified section that match the Setting pattern.

Wildcards can be used for Setting, but not for Section.

INISECTIONS Delete the file sections that match the Setting pattern, if they are empty. Wildcards (GOLD * and GOLD ?) can be used.
USYSDATA Delete the setting. Wildcards are not allowed.

If Source is USYS, restore the default value of the runtime setting. Only a limited set of runtime settings can be addressed.

USYSSETTINGS Delete the settings that match the Setting pattern. Only a limited set of runtime settings can be addressed.

Wildcards can be used for Setting, but not for Section.

USYSSECTIONS Delete the file sections that match the Setting pattern, if they are empty. Equivalent to INISECTIONS.
ENVDATA Delete an environment variable, symbol/logical, or data area. Wildcards are not allowed. The maximum length that can be assigned to an environment variable is 4096 bytes.
ENVVARS Delete one or more environment variables, data areas (iSeries), that match the Setting pattern.
REGDATA Delete the registry value. Wildcards are not allowed. Windows only.
REGVALUES Delete registry values under the specified key. Wildcards (GOLD * and GOLD ?) are allowed only in Value but not in Key. Windows only.
REGKEYS Delete subkeys under the specified key, if they are empty. Wildcards can be used for Subkey but not for Key. Windows only.

Values of Source 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.

Return Values

Values commonly returned by $procerror following deleteseetting

Value

Error Constant

Meaning

0

UACT_SUCCESS

Success. This value is also returned if no settings have been deleted because none matched the profile provided in the Setting parameter.

-4

UIOSERR_OPEN_FAILURE

The specified source could not be opened.

-5

UIOSERR_UPDATE_NOT_ALLOWED

The specified section is not empty.

-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 specified setting does not exist.

Use

Allowed in all Uniface component types.

Description

An initialization setting can be considered to any of the following:

  • Setting in an initialization file (on all platforms)
  • Environment variable (on all platforms )
  • Data area or system value (on iSeries)
  • Key value in the Registry (on Windows )

A section is considered to be a file section in an initialization file, or a key in the Windows Registry

You can use the deletesetting command to delete a setting, settings in a specific section, or one or more empty sections.

  • Single setting—specify the Topic parameter as INIDATA, USYSDATA, REGDATA or ENVDATA.
  • Zero or more settings in a specific section or subkey (if applicable)—specify a retrieve profile using wildcards in the Setting parameter and specify the Topic parameter as INISETTINGS, USYSSECTIONS, REGVALUES or ENVVARS.
  • Zero or more empty sections or subkeys—specify a retrieve profile using wildcards in the Setting parameter and specify the Topic parameter as INISECTIONS, USYSSECTIONS or REGKEYS.

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

Deleting a setting with topic USYSDATA restores its default value.

If no settings or sections match the profile, $procerror is set to 0, indicating that no items were removed. If any of the section or subkey is not empty, nothing is removed and $procerror is set to -5.