9.7 ALLOW_EXTRA_USER_KEY
Note: Built-In Function Rules Usage Options
Enables an "extra" user defined function key above and beyond any that are normally enabled by parameters on a DISPLAY, REQUEST or POP_UP command.
Arguments
|
No
|
Type
|
Req/ Opt
|
Description
|
Min Len
|
Max Len
|
Min Dec
|
Max Dec
|
|
1
|
N
|
Req
|
A literal or variable that specifies or contains the number of the extra function key to be enabled. The value specified should be in the range 1 to 24 or it will be ignored.
|
1
|
2
|
0
|
0
|
|
2
|
A
|
Opt
|
Literal or variable that specifies or contains the description that should be associated with the function key when it is displayed in the function key area of a screen panel.
|
1
|
10
|
|
|
|
Return Values
No return values.
Technical Notes
- Once an extra function key is enabled by ALLOW_EXTRA_USER_KEY, it will affect the processing of all following DISPLAY, REQUEST or POP_UP commands within the current function.
- Each time ALLOW_EXTRA_USER_KEY is executed it adds another (or even the same) function key to a "stack" of extra keys that should be enabled by all following DISPLAY, REQUEST or POP_UP commands. This "stack" of extra enabled function keys can contain at most 24 entries. Attempting to enable more than 24 extra function keys (even if the same function key is enabled repeatedly) will cause an execution time application failure.
- All entries on the "stack" of extra function keys are removed by use of the DROP_EXTRA_USER_KEYS Built-In Function.
- Caution should be used to ensure that extra function keys enabled this way do not conflict with function keys automatically enabled by the normal parameters on a DISPLAY, REQUEST or POP_UP command. If such a conflict is allowed to occur then unpredictable or unexpected results may occur.
- The ability of this Built-In Function to dynamically enable and disable function keys, and to dynamically vary their associated descriptions, prevents the screen panel images used by the full function checker and screen painter from showing them in the image's function key area. Such function keys will only appear in the function key area of an executing application.
Examples
Enable function key 5 on all panels and pop-ups within a function:
FUNCTION OPTIONS( ........)
USE BUILTIN(ALLOW_EXTRA_USER_KEY) WITH_ARGS(5 'Refresh')
Enable function keys 18 and 19 on a particular panel and make sure that no other extra keys are accidentally enabled:
USE BUILTIN(DROP_EXTRA_USER_KEYS)
USE BUILTIN(ALLOW_EXTRA_USER_KEY) WITH_ARGS(18 '''Hold''')
USE BUILTIN(ALLOW_EXTRA_USER_KEY) WITH_ARGS(19 '''Save''')
DISPLAY FIELDS(........)
CASE OF_FIELD(#IO$KEY)
WHEN VALUE_IS('= ''18''')
<< hold processing >>
WHEN VALUE_IS('= ''19''')
<< save processing >>
ENDCASE
Enable extra function keys 14 to 21:
DEFINE FIELD(#I) TYPE(*DEC) LENGTH(2) DECIMALS(0)
USE BUILTIN(DROP_EXTRA_USER_KEYS)
BEGIN_LOOP FROM(14) TO(21) USING(#I)
USE BUILTIN(ALLOW_EXTRA_USER_KEY) WITH_ARGS(#I)
END_LOOP
