GET-KEY-VALUE statement

(Windows only)

Searches the current environment for a particular key and places its value into a particular data item.

Note: Does not apply to SpeedScript programming.

Syntax

GET-KEY-VALUE SECTION section-name 
  KEY { key-name | DEFAULT }
  VALUE key-value
SECTION section-name

A CHARACTER expression that specifies the name of the section that contains the key of interest.

In initialization files, section names appear in square brackets([]). When you specify a section name in the GET-KEY-VALUE statement, omit the square brackets.

KEY key-name

A CHARACTER expression that specifies the name of the key of interest.

If you specify the Unknown value (?) or the empty string (""), GET-KEY-VALUE returns a comma-separated list of all keys in the section you specified.

DEFAULT
Tells GET-KEY-VALUE to use the default key of section section-name.

Some applications store data in the registry under the default key of a section. This option lets you retrieve this data. For an example, see the EXAMPLES section of this entry.

This option applies only to the registry and not to initialization files.

VALUE key-value
The name of a CHARACTER variable to hold the value of the key of interest.

Examples

If the current environment resides in the registry, the GET-KEY-VALUE statement:

  1. Searches the current environment for the subkey MYSECTION
  2. Searches MYSECTION for the value name MYKEY
  3. Assigns the value of MYKEY to the variable MYVARIABLE

If the current environment resides in an initialization file, the GET-KEY-VALUE statement:

  1. Searches the section MYSECTION for the key MYKEY
  2. Assigns the value of MYKEY to the variable MYVARIABLE as shown in the following example:

    GET-KEY-VALUE SECTION "MYSECTION" KEY "MYKEY" VALUE MYVARIABLE

If the current environment is the registry, the GET-KEY-VALUE statement:

  1. Searches the current environment for the key MYKEY
  2. Assigns the value of MYKEY to the variable MYVARIABLE

If the current environment resides in an initialization file, the following example returns a comma-separated list of all section names in the initialization file:

GET-KEY-VALUE SECTION "" KEY "MYKEY" VALUE MYVARIABLE

If the current environment resides in the registry, the GET-KEY-VALUE statement:

  1. Searches the current environment for the subkey MYSECTION
  2. Returns a comma-separated list of all value names in MYSECTION

If the current environment resides in an initialization file, the GET-KEY-VALUE statement:

  1. Searches the current environment for the section MYSECTION
  2. Returns a comma-separated list of all key names in MYSECTION; for example:

    GET-KEY-VALUE SECTION "MYSECTION" KEY "" VALUE MYVARIABLE
    GET-KEY-VALUE SECTION "MYSECTION" KEY "?" VALUE MYVARIABLE

If the current environment resides in the registry, the following examples return a comma-separated list of subkeys under the current environment location and all value names directly under the current environment location. The delimiter @value@ separates the subkey names from the value names.

If the current environment resides in an initialization file, the following examples return a comma-separated list of all section names in the initialization file:

GET-KEY-VALUE SECTION "" KEY "" VALUE MYVARIABLE
GET-KEY-VALUE SECTION "" KEY "?" VALUE MYVARIABLE
GET-KEY-VALUE SECTION "?" KEY "" VALUE MYVARIABLE
GET-KEY-VALUE SECTION "?" KEY "?" VALUE MYVARIABLE

If the current environment resides in the registry, the GET-KEY-VALUE statement:

  1. Searches the current environment for the subkey MYAPP
  2. Assigns the value of the default key under MYAPP to the variable MYVARIABLE

If the current environment resides in an initialization file, the following example returns an error:

GET-KEY-VALUE SECTION "MYAPP" KEY DEFAULT VALUE MYVARIABLE

Notes

See also

LOAD statement, PUT-KEY-VALUE statement, UNLOAD statement, USE statement