Progress
Language Reference


GET-KEY-VALUE Statement

Interfaces
OS
SpeedScript
All
Windows only
No

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

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 the Progress Programming Handbook .

SYNTAX

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

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-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.

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
  3. 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
  3. 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

SEE ALSO

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


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