(Windows only)
Adds,
modifies, and deletes keys in the current environment.
Note: Does not apply to SpeedScript programming.
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
- Suppresses ABL errors or error messages that would otherwise
occur and diverts them to the ERROR-STATUS system handle. If an error occurs, the action of the statement
is not done and execution continues with the next statement. If
the statement fails, any persistent side-effects of the statement
are backed out. If the statement includes an expression that contains
other executable elements, like methods, the work performed by these
elements may or may not be done, depending on the order the AVM
resolves the expression elements and the occurrence of the error.
To
check for errors after a statement that uses the NO-ERROR option:
- Check the ERROR-STATUS:ERROR attribute to see if the AVM raised
the ERROR condition.
- Check if the ERROR-STATUS:NUM-MESSAGES attribute is greater than
zero to see if the AVM generated error messages. ABL handle methods
used in a block without a CATCH end block treat errors as
warnings and do not raise ERROR, do not set the ERROR-STATUS:ERROR
attribute, but do add messages to the ERROR-STATUS system handle.
Therefore, this test is the better test for code using handle methods
without CATCH end blocks. ABL handle methods used in a block with a
CATCH end block raise ERROR and add messages to the error object
generated by the AVM. In this case, the AVM does not update the
ERROR-STATUS system handle.
- Use ERROR-STATUS:GET-MESSAGE( message-num )
to retrieve a particular message, where message-num is
1 for the first message.
If the statement does not include
the NO-ERROR option, you can use a CATCH end block to handle errors
raised by the statement.
Some other important usage notes
on the NO-ERROR option:
- NO-ERROR does not suppress errors
that raise the STOP or QUIT condition.
- A CATCH statement, which introduces a CATCH end block, is analogous
to a NO-ERROR option in that it also suppresses errors, but it does so
for an entire block of code. It is different in that the error messages
are contained in a class-based error object (generated by the AVM
or explicitly thrown), as opposed to the ERROR-STATUS system handle.
Also, if errors raised in the block are not handled by a compatible
CATCH block, ON ERROR phrase, or UNDO statement, then the error
is not suppressed, but handled with the default error processing
for that block type.
- When a statement contains the NO-ERROR option and resides in
a block with a CATCH end block, the NO-ERROR option takes precedence over
the CATCH block. That is, an error raised on the statement with
the NO-ERROR option will not be handled by a compatible CATCH end block.
The error is redirected to the ERROR-STATUS system handle as normal.
- If an error object is thrown to a statement that includes the NO-ERROR
option, then the information and messages in the error object will
be used to set the ERROR-STATUS system handle. This interoperability
feature is important for those integrating code that uses the traditional
NO-ERROR technique with the newer, structured error handling that
features error objects and CATCH end blocks.
Examples
If
the current environment resides in the registry, the PUT-KEY-VALUE statement:
- Searches in the registry under the current environment for the subkey
MYSECTION
- Creates MYSECTION if it does not exist
- Searches MYSECTION for the subkey MYKEY
- 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 PUT-KEY-VALUE
statement:
- Searches the initialization file for the section
MYSECTION
- Creates MYSECTION if it does not exist
- Searches MYSECTION for the key MYKEY
- Sets MYKEY to the value MYVARIABLE (if MYKEY exists), or adds MYKEY
and the value MYVARIBLE (if MYKEY does not exist):
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:
PUT-KEY-VALUE SECTION "" KEY "MYKEY" VALUE MYVARIABLE
|
PUT-KEY-VALUE SECTION "?" KEY "MYKEY" VALUE MYVARIABLE
|
If the current environment resides in an initialization
file, the previous examples return an error.
If the current
environment resides in the registry, the following examples:
- Search in the registry under the current environment for the
key MYSECTION.
- Search MYSECTION for the value name MYKEY.
- Delete MYKEY and its value.
PUT-KEY-VALUE SECTION "MYSECTION" KEY "MYKEY" VALUE ""
|
PUT-KEY-VALUE SECTION "MYSECTION" KEY "MYKEY" VALUE ?
|
If the current environment resides in an initialization
file, the previous examples delete the key MYKEY, including its
value, from the section MYSECTION.
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:
PUT-KEY-VALUE SECTION "MYSECTION " KEY "?" VALUE ?
|
PUT-KEY-VALUE SECTION "MYSECTION " KEY "" VALUE ""
|
If the current environment resides in an initialization
file, the previous examples remove the section MYSECTION, and all
key-value pairs within MYSECTION, from the initialization file.
If
the current environment resides in the registry, the following example:
- Searches the current environment for the subkey MYAPP
- Sets the default key under MYAPP to NEWVALUE
PUT-KEY-VALUE SECTION "MYAPP" KEY DEFAULT VALUE "NEWVALUE"
|
If the current environment resides in an initialization
file, the previous example returns an error.
Notes
- 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 OpenEdge Development: Programming Interfaces.
- The current environment is one of the following:
- The
default environment
- An environment that a startup parameter specified (the startup
environment)
- An environment that a LOAD statement loaded and that the most
recent USE statement made current
- If you UNLOAD the current environment, a subsequent PUT-KEY-VALUE
writes to the startup environment.
- To remove a key-value pair from an environment, set key-name to
the name of the key and value to the Unknown value (?).
- To remove a section, including all its key-value pairs, from
an environment, set section-name to the name
of the section and key-name to the Unknown value (?).
- To change the definitions in the internal color table, use one
of the following techniques:
- To display a dialog box that
lets the user change the color definitions, use the SYSTEM-DIALOG-COLOR
statement.
- To change the color definitions directly from ABL, use the attributes
and methods of the COLOR-TABLE handle.
Note: The
COLOR option of the PUT-KEY-VALUE statement does not change the
definitions in the internal color table. This option merely moves
some or all of those definitions to the current environment.
- To change the definitions in the internal font table, use one
of the following techniques:
- To display a dialog box that
lets the user change the font definitions, use the SYSTEM-DIALOG-FONT
statement.
- To change the font definitions directly from ABL, use the attributes
and methods of the FONT-TABLE handle.
Note: The
FONT option of the PUT-KEY-VALUE statement does not change the definitions
in the internal font table. This option merely moves some or all
of those definitions to the current environment.
- For more information on colors and fonts, see the chapter on
colors and fonts in OpenEdge Development: Programming Interfaces.