Progress
Language Reference


PUT-KEY-VALUE Statement

Interfaces
OS
SpeedScript
All
All
No

Adds, modifies, and deletes keys in the current environment.

Environments typically consist of sections, each of which contains 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 COLOR7 and the value 255,255,0. This key attaches the name COLOR7 to color value 255,255,0 (a color specification that uses 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 equal sign (=), and a value.

For more information on environments, see the chapter on colors and fonts in the Progress Programming Handbook .

SYNTAX

PUT-KEY-VALUE 
  {  { SECTION section-name
         KEY { key-name | DEFAULT }
         VALUE value
     }
     |  { COLOR | FONT } { number | ALL } 
  }
  [ NO-ERROR ] 

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 a PUT-KEY-VALUE statement, omit the square brackets.

KEY key-name

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

DEFAULT

Tells PUT-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 modify 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 value

The value of the key to write to the environment. value must evaluate to a CHARACTER expression of no more than 128 bytes.

COLOR { number | ALL }

Updates color definitions in the current environment from the definitions in the internal color table. The number parameter is a literal integer that specifies the number of a single color in the current environment whose definition you want to update. The ALL option updates all color definitions in the current environment.

FONT { number | ALL }

Updates font definitions in the current environment from the definitions in the internal font table. The number parameter is a literal integer that specifies the number of a single font in the current environment whose definition you want to update. The ALL option updates all font definitions in the current environment.

NO-ERROR

Specifies that any errors that occur as a result of the PUT-KEY-VALUE operation are suppressed. After the PUT-KEY-VALUE statement completes, you can check the ERROR-STATUS system handle for information on any errors that might have occurred.

EXAMPLES

If the current environment resides in the registry, the following example:

  1. Searches in the registry under the current environment for the subkey MYSECTION
  2. Creates MYSECTION if it does not exist
  3. Searches MYSECTION for the subkey MYKEY
  4. Sets MYKEY to the value MYVARIABLE (if MYKEY exists),
    or adds MYKEY and the value MYVARIBLE (if MYKEY does not exist)

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

  1. Searches the initialization file for the section MYSECTION
  2. Creates MYSECTION if it does not exist
  3. Searches MYSECTION for the key MYKEY
  4. Sets MYKEY to the value MYVARIABLE (if MYKEY exists),
    or adds MYKEY and the value MYVARIBLE (if MYKEY does not exist)
  5. PUT-KEY-VALUE SECTION "MYSECTION" KEY "MYKEY" VALUE MYVARIABLE 
    

If the current environment resides in the registry, the following examples add, directly under the current environment, the value name MYKEY and the value MYVARIABLE.

If the current environment resides in an initialization file, the following examples return an error.

PUT-KEY-VALUE SECTION "" KEY "MYKEY" VALUE MYVARIABLE 

PUT-KEY-VALUE SECTION "?" KEY "MYKEY" VALUE MYVARIABLE 

If the current environment resides in the registry, the following examples:

  1. Search in the registry under the current environment for the key MYSECTION
  2. Search MYSECTION for the value name MYKEY
  3. Delete MYKEY and its value

If the current environment resides in an initialization file, the following examples delete the key MYKEY, including its value, from the section MYSECTION.

PUT-KEY-VALUE SECTION "MYSECTION" KEY "MYKEY" VALUE "" 

PUB-KEY-VALUE SECTION "MYSECTION" KEY "MYKEY" VALUE ? 

If the current environment resides in the registry, the following examples delete the subkey MYSECTION, all values under MYSECTION, all subkeys under MYSECTION, and all values under those subkeys.

If the current environment resides in an initialization file, the following examples remove the section MYSECTION, and all key-value pairs within MYSECTION, from the initialization file.

PUT-KEY-VALUE SECTION "MYSECTION " KEY "?" VALUE ? 

PUT-KEY-VALUE SECTION "MYSECTION " KEY "" VALUE "" 

If the current environment resides in the registry, the following example:

  1. Searches the current environment for the subkey MYAPP
  2. Sets the default key under MYAPP to NEWVALUE

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

PUT-KEY-VALUE SECTION "MYAPP" KEY DEFAULT VALUE "NEWVALUE" 

NOTES

SEE ALSO

COLOR-TABLE System Handle, FONT-TABLE System Handle, GET-KEY-VALUE Statement, LOAD Statement, SYSTEM-DIALOG COLOR Statement, SYSTEM-DIALOG FONT Statement, UNLOAD Statement, USE Statement


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