GET-KEY-VALUE statement

(Windows only)

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

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

• Environments typically consist of sections, each of which can contain keys, each of which consists of a name and a value. A typical section name is COLORS. A typical key within this section consists of the name "COLOR16" and the value 255,255,0. This key attaches this particular name to this particular color. (The value represents a color specification using the red-green-blue color-naming scheme.)

  The current environment might be the registry or an initialization file. The registry consists of sections called keys and subkeys arranged in a hierarchy. Keys and subkeys contain value entries, each of which consists of a value name and value data. Initialization files, by contrast, consist of a single level of sections. Sections contain entries, each of which consists of a name, an equals sign (=), and a value.

  For more information on environments, see the chapter on colors and fonts in OpenEdge Development: Programming Interfaces.

• The current environment is either the default environment, the startup environment (an environment that a startup parameter specified), or an application environment that the LOAD statement loaded and that the USE statement made current.
• If you unload the current environment (using the UNLOAD statement) and then use the GET-KEY-VALUE statement, you access the startup environment.

See also

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