Release 10.1A: OpenEdge Development:
Progress 4GL Reference

> ## 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 following example:

> 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 following example:

> 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 following example:

> 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 following examples:

> 1. Search the current environment for the subkey MYSECTION.

> 2. Return a comma-separated list of all value names in MYSECTION.

> If the current environment resides in an initialization file, the following examples:

> 1. Search the current environment for the section MYSECTION.

> 2. Return a comma-separated list of all key names in MYSECTION.

>     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 following example:

> 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

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095