HP 3000 Manuals HP 3000 Manuals
Keyboard Handling Via ADIS
This section describes:
* Types of keys on the keyboard
* CRT STATUS clause
* Termination
* User function keys
* ADIS keys
* Defining in both the user and ADIS key list
* Data key handling
* ADIS-compatible GET SINGLE CHARACTER call
Function Key Handling
This section describes how to use function keys in this COBOL system. It
only describes the portable method that will work on all environments.
There is another method, using the x"B0" routine, which is not described
here as it is machine dependent. If you are using this routine, refer to
section Conflict with the x"B0" COBOL System Library Routine later in
this section for details of how this may cause problems with certain
configurations.
Types of Keys on the Keyboard.
In general, the keys on the keyboard can be split into two groups - data
keys and function keys.
Data Keys
The data keys are those that generate characters that are in the extended
ASCII character set, that is, those with ASCII codes in the range 32 to
255. During an ACCEPT operation, pressing one of these keys will simply
place the character into the field. However, it is possible to disable a
key completely or make it terminate the accept operation (similar to the
action of a function key). This is covered later in this section.
There is a complication in that the ASCII codes in the range 0 to 31 can
be considered as either data keys or function keys. For most purposes,
they are treated as function keys and are disabled as data keys.
Function Keys
The most general definition of a function key is any key you would not
find on a typewriter keyboard. This definition includes explicit
function keys on the keyboard (usually labeled F1, F2, etc.) and such
keys as Escape, the cursor keys, Tab, Backspace, etc. The return or
Enter key Enter is also treated as a function key, but with special
considerations, described later.
In your COBOL system, these keys are divided into two groups - the
ADIS keys and the User function keys.
ADIS Keys
This is the term given to those keys that are used by ADIS during the
execution of an ACCEPT statement. This includes the cursor keys, Tab,
Backspace, Delete and Enter.
Normally, these keys will operate as defined during an ACCEPT. For
example, the cursor-left key will move the cursor to the left, Backspace
will erase the previous character, and so on. With the exception of the
Enter key, they will not normally terminate the ACCEPT. However, you can
make these keys terminate the ACCEPT if required. This is described
later in this section.
User Function Keys
These keys are so called because the programmer decides what they will be
used for when the application is written. There is no predefined action
assigned to these keys. The user function keys generally include the
keys labeled F1, F2, etc. and the Escape key as well as any other
special keys that are on the keyboard.
The CRT STATUS Clause.
If you decide that you want your application to use function keys, it is
highly likely that you will want to be able to determine exactly which
key has been pressed. To do this you need to include the CRT STATUS
clause in the Special-Names paragraph of your program. For example:
special-names.
crt status is key-status.
where key-status is a three-byte data item that should be defined in the
Working-Storage section of your program. It has the following
definition:
01 key-status.
03 key-type pic x.
03 key-code-1 pic 9(2) comp-x.
03 key-code-2 pic 9(2) comp-x.
Whenever an ACCEPT statement is executed, key-status will be set to
indicate how the ACCEPT was terminated. The exact usage of the
individual fields in key-status is described later. However, in general
they have the following uses:
key-type Indicates how the ACCEPT was terminated. The values
returned are as follows:
"0" - Normal termination of the ACCEPT
"1" - Termination by a USER function key
"2" - Termination by an ADIS key
"3" - Termination by an 8 bit data key
"4" - Termination by a 16 bit data key
"9" - Error
These different values are described fully later in this section.
key-code-1 Indicates the number of the key that terminated the
ACCEPT. The exact meaning of this number depends on
the value returned in key-type.
key-code-2 If key-type and key-code-1 are zero, key-code-2
contains the raw keyboard code
for the key that terminated the ACCEPT operation.
Where a sequence of keystrokes rather than a single
key has been configured to perform a single
function, only the code for the first keystroke is
returned.
If key-type is 4, key-code-2 will contain the second
byte of the character which caused the ACCEPT to
terminate.
Otherwise, the contents of key-code-2 are undefined.
Normal Termination of an ACCEPT.
There are two cases of normal termination of an ACCEPT. They both return
a value of "0" in key-type:
* The most common way of terminating an ACCEPT is by pressing the
return key. This will return a value of 48 (the ASCII code for
"0") in key-code-1.
* It is possible to configure ADIS so that an auto-skip in the last
field on the screen will terminate the ACCEPT (use ADISCF to do
this). This is also classed as a normal termination, but it
returns a value of 1 in key-code-1.
Example
accept data-item at 0101
if key-type = "0"
if key-code-1 = 48
display "terminated by return key"
else
display "terminated by auto-skip last field"
end-if
end-if.
Using the User Function Keys.
There are up to 128 user function keys. Some come already configured,
but you can use KEYBCF to configure the keys as needed. The defaults
supplied with your COBOL system differ on different operating
environments, but the following keys are standard:
Keystrokes User Function Key Number
Escape 0
F1 1
F2 2
F3 3
F4 4
F5 5
F6 6
F7 7
F8 8
F9 9
F10 10
Your keyboard may not have these keys, but if they are there they should
be configured as above. Additionally, on IBM-PC compatible terminals,
the following user function keys are defined:
Keystrokes User Function Key Number
Shift+F1 - F10 11 - 20
Ctrl+F1 - F10 21 - 30
Alt+F1 - F10 31 - 40
Alt+1 - 9 41 - 49
Alt+0 50
Alt+- 51
Alt+= 52
PgUp 53
PgDn 54
Ctrl+PgUp 55
Ctrl+PgDn 56
Alt+A - Z 65 - 90
The following are available only on the extended IBM-PC keyboard.
F11 91
F12 92
Shift+F11 93
Shift+F12 94
Ctrl+F11 95
Ctrl+F12 96
Alt+F11 97
Alt+F12 98
Default User Function Keys.
Function Meaning Default Key
00 Escape Esc
01 to 63 Function keys 01 to KEY_F (01 to 63)
63
A third function key list, the Animator function key list, is also
available to you. Refer to Chapter 4 , Animating for details of the
default settings of these keys.
Enabling and Disabling the User Function Keys
Before any of the user function keys can be used, they must be enabled.
If a user key is enabled, it will terminate the ACCEPT operation when
pressed. If the key is disabled, the key will be rejected and the bell
rung.
On UNIX systems, the user function keys are enabled by default. Micro
Focus COBOL for DOS and OS/2 has the user function keys disabled by
default. Therefore, if you want to write programs that work in both
environments, include code to enable the keys you want and disable all
others.
The following call is used to selectively enable and disable the user
function keys:
call x"AF" using set-bit-pairs user-key-control
where:
01 set-bit-pairs pic 9(2) comp-x value 1.
01 user-key-control.
03 user-key-setting pic 9(2) comp-x.
03 filler pic x value "1".
03 first-user-key pic 9(2) comp-x.
03 number-of-keys pic 9(2) comp-x.
The fields of user-key-control are used as follows:
user-key-setting Set to 0 to disable keys or 1 to enable keys
first-user-key The number of the first key to be enabled or
disabled
number-of-keys The number of consecutive keys to enable or disable
Function keys are enabled or disabled until explicitly changed by another
call to x"AF" or until the application terminates. Calls to enable or
disable function keys are additive. For example, if you call x"AF" to
enable Function Key F1 and then make a second call to enable F10, both
keys are enabled.
Example
If you want to enable the Escape key and keys F1 ... F10, but you want
to ensure that all other user function keys are disabled, then the
following code will do this:
* Enable 11 keys starting from key 0 (escape key)
move 1 to user-key-setting
move 0 to first-user-key
move 11 to number-of-keys
call x"AF" using set-bit-pairs user-key-control
* Disable 117 keys starting from key 11
move 0 to user-key-setting
move 11 to first-user-key
move 117 to number-of-keys
call x"AF" using set-bit-pairs user-key-control.
* Enable F1 and F10.
move 1 to user-key-setting
* Enable F1.
move 1 to first-user-key
move 1 to number-of-keys
call x"AF" using set-bit-pairs user-key-control
* Enable F10
move 10 to first-user-key
call x"AF" using set-bit-pairs user-key-control
Detecting the User Function Keys
If you press an enabled user function key during an ACCEPT operation, the
ACCEPT will be terminated and the fields in key-status will be set as
follows:
key-type "1"
key-code-1 Set to the number of the user key that was pressed
key-code-2 Undefined
Example
accept data-item at 0101
if key-type = "1"
evaluate key-code-1
when 0
display "escape was pressed"
when 1
display "f1 was pressed"
when 10
display "f10 was pressed"
end-evaluate
end-if.
The Compatibility Key List
Most of the time, you will need to use only the one list of user function
keys. However, if you are converting from another dialect of COBOL, you
may have some programs that expect the values returned from the standard
user key list and some programs that expect the values returned by the
function keys in some other dialect of COBOL. To enable you to do this,
the compatibility key list is provided. This works in exactly the same
way as the normal key list. Any program can use either the standard user
key list or the compatibility list, but not both.
By default, a program will use the standard user key list. If you want
all programs in your system to use the compatibility key list, you can
use ADISCF to
select its use. If you want different programs to use different lists,
you can insert the following call into your programs to select the list
you require:
call x"AF" using set-bit-pairs key-list-selection
where:
01 set-bit-pairs pic 9(2) comp-x value 1.
01 key-list-selection.
03 key-list-number pic 9(2) comp-x.
03 filler pic x value "1".
03 filler pic 9(2) comp-x value 87.
03 filler pic 9(2) comp-x value 1.
key-list-number should be set to one of the following values:
1 Selects the standard user function key list.
2 Selects the compatibility key list.
The default compatibility key list included in your COBOL system is set
up to return the values provided by function keys in the UNIX version of
RM/COBOL 2.0. You can change this list to the values you require by
using KEYBCF; see Chapter 24 , Keyboard Configuration Utility.
The User Function Keys and Validation Clauses
Normally, if a validation clause, such as FULL or REQUIRED, is specified
in an ACCEPT statement, that clause must be satisfied before you can
leave the field. For example, when the statement:
accept data-item with required
is executed, you will not be allowed to terminate the ACCEPT unless
something has been entered into the field.
However, if an enabled user function key is pressed during an ACCEPT, it
is regarded as an "exception" and will terminate the ACCEPT even if the
validation clause has not been satisfied. If you do not want function
keys to terminate the ACCEPT without satisfying validation clauses, you
can set Accept/Display option 9 using ADISCF. See Chapter 21 , ADIS
Configuration Utility for more details.
Using the ADIS Keys.
As noted earlier, the ADIS keys are those keys that perform functions
within an ACCEPT such as cursor movement, delete character, backspace,
etc. However, it is possible to make these keys terminate the ACCEPT.
First, the distinction has to be made between the keys that perform the
functions and the functions themselves, because there is actually a
"soft" mapping between the keys and the functions they perform. This
means that the programmer can change the function that one of the ADIS
keys performs.
The Functions Performed by the ADIS Keys
A full list of the functions performed by the ADIS keys is given in the
section "List of Standard ADIS Key Functions" in the chapter Keyboard
Configuration Utility. The functions 0 to 27 are simple functions.
Those in the range 55 to 62 are complex functions which may perform
different actions depending on some state. For example, those functions
provided for RM compatibility have a different action depending on
whether or not the UPDATE clause was specified in the ACCEPT statement.
The ADIS Keys.
There are 26 ADIS keys. Each of these is "mapped" onto a function, so
that when a key is pressed, it performs the function it has been mapped
to. The functions are described in the section "List of Standard ADIS
Key Functions" in the chapter Keyboard Configuration Utility. What
is often confusing is that the ADIS keys themselves are given names.
This name is used to distinguish the different keys, but may not
necessarily describe the function the key actually performs. The
following list gives the names of the keys and the sequences which
generate that code.
ADIS Meaning Default Key
Function
Key Number
00 Terminate Accept Ctrl+J or KEY_ENTER
01 Terminate Program Ctrl+K
02 Carriage Return Ctrl+M (Mapped to 00)
03 Cursor Left KEY_LEFT
04 Cursor Right KEY_RIGHT
05 Cursor Up KEY_UP
06 Cursor Down KEY_DOWN
07 Move to start of screen KEY_HOME
08 Move to next tab stop Ctrl+I (Mapped to 11) or KEY_TAB
09 Move to previous tab stop Ctrl+L (Mapped to 12) or
KEY_BACKTAB
10 Move to end of screen KEY_LL or Ctrl+O or KEY_END
11 Move to next field Ctrl+N
12 Move to previous field Ctrl+P
13 Change case of character Ctrl+F
14 Backspace character KEY_BACKSPACE or Ctrl+H
15 Retype rubbed out character Ctrl+R
16 Insert single character KEY_IC or Ctrl+V
17 Delete character KEY_DC or Del
18 Restore deleted Ctrl+U character
19 Clear to end of field KEY_EOL or Ctrl+Z
20 Clear Field KEY_DL or Ctrl+X
21 Clear to end of screen KEY_EOS or Ctrl+D
22 Clear screen KEY_CLEAR or Ctrl+E
23 Set Insert mode KEY_IL or Ctrl+T
24 Set Replace mode Not defined
25 Reset field to its original Ctrl+A value
26 Move to start of field Ctrl+W
Note: The carriage return (CR) key is referred to here as the Enter
key. On some keyboards, there is a CR key and an Enter key. In
this case, the ADIS key "Carriage Return" should be set up as CR
and the ADIS key "Terminate Accept" should be set up as Enter.
Another function key list is available to you. This is the user function
key list. It describes the mappings of control keys and terminfo codes
onto user function keys. You can use these keys to cause special
termination of ACCEPT operations. The default keystrokes assigned to the
user function keys are listed in Chapter 24 , Keyboard Configuration
Utility.
Mapping the ADIS Keys to the Functions
In general, the ADIS keys are mapped onto the function of the same name.
Therefore, the cursor-left key will move the cursor to the left, the
Backspace key will erase a character and so on. However, some keys are
by default mapped onto different functions:
Key Function
Enter Terminate Accept (function 0)
Tab Next Field (function 11)
Backtab Previous Field (function 12)
Ins Insert Toggle (function 58)
Therefore, when you press the Enter key on your terminal, it will
terminate the ACCEPT.
At this stage, the idea of mapping keys may seem an unnecessary
complication. Where it becomes really useful is in the emulation of
other dialects of COBOL. For example, in
Microsoft COBOL V2.2, the Enter key moves to the next field rather than
terminating the ACCEPT. This is easy to emulate by simply changing the
mapping for key 2 (Enter) from 0 (Terminate Accept) to 11 (Next Field).
If you look at the Function Mappings screen in ADISCF for the Microsoft
COBOL V2.2 compatibility configuration, you will see that this has been
done.
The
RM/COBOL V2.0 compatibility configuration contains even more changes to
the default mappings to emulate the action of keys in RM/COBOL.
If a key is mapped on to a value of 255, that key will not perform any
function during an ACCEPT operation.
Special Mappings
All of the standard functions described above always perform the same
function, regardless of context. For example, the "Move to next field"
function will always attempt to move to the next field. However, there
are some functions that behave differently depending on the context.
These functions are described at the end of the section "List of Standard
ADIS Key Functions" in the chapter Keyboard Configuration Utility,
but are summarized here:
Function Number Function Name
55 RM Clear Field
56 RM Back Space
57 RM Tab
58 Insert Toggle
59 Replace Toggle
60 Forwards Tab
61 Backwards Tab
62 Restore
For example, the Insert key (key number 23) is normally mapped to
function 58 (Insert Toggle). This means that repeated pressing of the
Insert key toggles between Insert and Replace mode.
Changing the Mappings from a Program
As well as changing the mappings through ADISCF, you can do this from an
application program using the call:
call x"AF" using set-map-byte adis-key- mapping
where:
01 set-map-byte pic 9(2) comp-x value 3.
01 adis-key-mapping.
03 adis-mapping-byte pic 9(2) comp-x.
03 adis-key-number pic 9(2) comp-x.
adis-key-number should be set to the number of the key you wish to
change. adis-mapping-byte should be set to the number of the function
you wish the key to be mapped to. Example
The following code will change the action of the Backspace key (key
number 14) to simply move the cursor to the left (function 3), and change
the tab key (key number 8) to perform the tab function (function 8)
* Change mapping of cursor left key
move 14 to adis-key-number
move 3 to adis-mapping-byte
call x"AF" using set-map-byte adis-key-mapping
* Change mapping of the tab key
move 8 to adis-key-number
move 8 to adis-mapping-byte
call x"AF" using set-map-byte adis-key-mapping.
Conflict With X"B0" COBOL System Library Routine
The x"B0" COBOL system library routine is not available for the UNIX
system, but may have been used by applications developed under DOS and
OS/2. The x"AF" library routine described in this chapter is
operating-system-independent and should be used instead.
Enabling/Disabling the ADIS Keys
By default, all of the ADIS keys are enabled to perform their defined
functions during an ACCEPT. However, it is possible to disable the keys
or make them act as function keys instead using the following call:
call x"AF" using set-bit-pairs adis-key-control
where:
01 set-bit-pairs pic 9(2) comp-x value 1.
01 adis-key-control.
03 adis-key-setting pic 9(2) comp-x.
03 filler pic x value "2".
03 first-adis-key pic 9(2) comp-x.
03 number-of-adis-keys pic 9(2) comp-x.
The fields of adis-key-control are used as follows:
adis-key-setting Defines the action of the keys affected, as follows:
0 The keys are disabled. If the key is pressed during
an ACCEPT, the key will be rejected.
1 The key will act like a function key. If pressed
during an ACCEPT, it will terminate the ACCEPT (see
below).
2 The key will do its normal action during an ACCEPT
(this is the default value).
3 The key will do its normal action unless it causes
the cursor to leave the current field. If this
happens, it will act like a function key.
first-adis-key The number of the first key to be affected.
number-of-adis-keys The number of consecutive keys to be affected.
Detection of ADIS Keys
If an ADIS key has been set up to act as a function key, it will
terminate the ACCEPT operation and key-status will be set up with the
following values.
key-type "2"
key-code-1 Set to the number of the ADIS key that was pressed.
Note that this is the number of the key not the
number of the function the key has been mapped to.
key-code-2 Undefined.
Example
The following code sets up Tab and Backtab to act as function keys and
the cursor-left and cursor-right keys to act as function keys if they
cause the cursor to leave the field.
* Set up tab (key 8) and back-tab (Key 9) to act as
* function keys
move 1 to adis-key-setting
move 8 to first-adis-key
move 2 to number-of-adis-keys
call x"AF" using set-bit-pairs adis-key-control
* Set up cursor left (key 3) and cursor right (key 4) to act as
* function keys ONLY if they cause the cursor to leave the field.
move 3 to adis-key-setting
move 3 to first-adis-key
move 2 to number-of-adis-keys
call x"AF" using set-bit-pairs adis-key-control
accept data-item at 0101
if key-type = "2"
evaluate key-code-1
when 3
display "cursor left caused the cursor to
- "leave the field"
when 4
display "cursor right caused the cursor to
- "leave the field"
when 8
display "the tab key was pressed"
when 9
display "the backtab key was pressed"
end-evaluate
end-if.
Defining a Key in Both the User and ADIS Key Lists.
In general, a particular key will be defined in either the user key list
or the ADIS key list, but not both. However, there is nothing to stop
you defining the same key in both lists. In fact, the default values in
the compatibility list (set up for RM/COBOL V2.0 on UNIX compatibility)
include the cursor keys which are also defined in the ADIS key list.
If a key that is defined in both lists is pressed during an ACCEPT, the
sequence of actions is as follows:
1. Is the key defined in the user key list?
2. If not, goto (5).
3. Is the user key enabled?
4. If it is, return "1" in key-type and the number of the key in
key-code-1.
5. Is the key defined in the ADIS key list?
6. If not, report to the user that the key is undefined.
7. Perform the required action for the ADIS key depending on whether
it is disabled, enabled or to act as a function key.
Function Keys and the COBKEYTIMEOUT variable.
On network based systems, information is split into packets, and thus
under certain conditions it is possible for part of a function key
sequence to be split across two packets. This can lead to incorrect key
recognition. This typically occurs while using the 'telnet'
or the 'rlogin'
commands.
Your Micro Focus COBOL system provides you with the COBKEYTIMEOUT
environment variable, which you can use to determine the timeout between
the arrival of the first key of a function or special key sequence and
the arrival of the next. Setting this environment variable allows
function key sequences to be recognized correctly. See Appendix I ,
Environment Variables for details on setting COBKEYTIMEOUT.
The timeout period, a value in the range 1 to 26, is dependent on the
type of connection and the effective average baud rate. For example,
ethernet connections should not require a value greater than 10. Using
too small a value will result in incorrect function and special key
recognition; too large a value will result in a delay when certain keys
are pressed (such as escape) unless they are followed by other keys (such
as escape).
If the value of the COBKEYTIMEOUT environment variable is either outside
the range 1 to 126, is null, is non-integer or does not exist, then a
direct connection between the terminal and the machine is assumed.
You could also use the COBKEYTIMEOUT environment variable to recognize
function key sequences on terminals which do not send such sequences at
the correct baud rate, but insert pauses between the characters instead.
This environment variable is read once only, when the screen handling
subsystem is initialized. Changing its value after this has no effect.
Data Key Handling
The data keys are the 256 keys in the extended ASCII character set.
Normally, when you press one of these keys during an ACCEPT, the
character is simply put straight into the field. The exception to this
is the keys with ASCII codes in the range 0 to 31, that is, the control
keys. These are generally disabled.
Controlling the Data Keys
Just like most other keys on the keyboard, it is possible to disable data
keys or make them act like function keys, that is, terminate the ACCEPT.
To do this, use the following call:
call x"AF" using set-bit-pairs data-key-control
where:
01 set-bit-pairs pic 9(2) comp-x value 1.
01 data-key-control.
03 data-key-setting pic 9(2) comp-x.
03 filler pic x value "3".
03 first-data-key pic x.
03 number-of-data-keys pic 9(2) comp-x.
The fields in data-key-control should be set up as follows:
data-key-setting Defines the action of the keys affected,as follows:
0 The key is disabled. If it is pressed, during an
ACCEPT, the bell is rung and the key rejected.
1 The key will act as a function key (see below). It
will terminate the ACCEPT.
2 (The default.) The character will simply be entered
into the field.
first-data-key The first character to be affected.
number-of-data-keys The number of characters to be affected.
Detecting Data Keys Set Up to Act as Function Keys
The data keys are the 256 keys in the extended ASCII character set.
Normally, when you press one of these keys during an ACCEPT, the
character is simply put straight into the field. The exception to this
is the keys with ASCII codes in the range 0 to 31, that is, the control
keys. These are generally disabled.
If a data key has been set up to act as a function key, it will terminate
the ACCEPT when pressed and key-status will be set up as follows:
key-type "3"
key-code-1 Set to the ASCII code of the key that was pressed
key-code-2 Undefined
Example
* Set up the characters "A" to "Z" to terminate the
* ACCEPT
move 1 to data-key-setting
move "a" to first-data-key
move 26 to number-of-data-keys
call x"AF" using set-bit-pairs data-key-control
accept data-item at 0101
if key-type = "3"
evaluate key-code-1
when 65
display "a pressed"
when 66
display "b pressed"
when 90
display "z pressed"
end-evaluate
end-if.
The Alt And Ctrl Keys
Most UNIX terminals cannot detect the depression of the Alt or Ctrl keys
unless they are pressed in conjunction with another valid key. You
should, therefore, avoid using these keys by themselves in portable
applications. Alternatively, the key sequences /a and /c can be used to
simulate the use of Alt and Ctrl keys.
See Appendix N , UNIX Key Usage Chart.
Get Single Character Routine
This routine allows you to get a single key from the keyboard. It uses
ADIS itself, so all of the function keys supported by ADIS are supported.
The routine only reads the keyboard and so does not echo the key to the
screen.
The format of the call is:
call x"AF" using get-single-char-func key-status
where:
01 get-single-char-func pic 9(2) comp-x value 26.
01 key-status.
03 key-type pic x.
03 key-code.
05 key-code-1 pic 9(2) comp-x.
05 key-code-2 pic 9(2) comp-x.
The values returned in key-status are the same as those described
previously, except that a value of "0" is never returned in key-type by
this call. The Enter key returns a value of "2" in key- type and a value
of 2 in key-code-1.
The values returned in key-status are as follows:
key-type key-code-1
"1" Returns the number of the user function pressed.
"2" Returns the number of the ADIS key pressed. Note that no
mapping of keys occurs in this call. Therefore the number
returned is the number of the actual key pressed.
"3" Returns the ASCII code of the 8 bit data key pressed.
"4" Returns the first byte of the 16 bit data key pressed. The
second byte is contained in key-code-2. Only applicable on
machines that support double-byte characters.
"9" Returns a value indicating the error condition. Values
are:
8 Disabled character. The data key pressed is
disabled.
9 Invalid keystroke. A function key has been pressed
that is not defined in either the user or ADIS
function key list.
Example
call x"AF" using get-single-char-func key- status
evaluate key-type
when "1"
* User function key pressed. Do required
* action depending on value in key-code-1.
when "2"
* ADIS function key pressed. Do required
* action depending on value in key-code-1.
when "3"
* Data key pressed. Do required action
* depending on the ASCII code in key-code-1.
when "4"
* Double byte data key pressed. Do required
* action depending on the 16-bit character in
* key-code.
when "9"
* Invalid or disabled key. Do required action.
end-evaluate.
Program Sample
$set ans85
***********************************************************
* This program is an example of how to write programs that
* make use of function keys.
*
* It is assumed that the Escape key is available, but any
* other function key can be selected by either pressing the
* function key or by pressing "/" followed by the first
* letter of the option.
*
* This program assumes that the Default Configuration has
* been selected using ADISCF.
**********************************************************
special-names.
cursor is cursor-position
crt status is key-status.
data division.
working-storage section.
**********************************************************
* Parameters to be used for the X"AF" calls.
**********************************************************
01 set-bit-pairs pic 9(2) comp-x value 1.
01 get-single-character pic 9(2) comp-x value 26.
01 enable-esc-and-f1.
03 filler pic 9(2) comp-x value 1.
03 filler pic x value "1".
03 filler pic 9(2) comp-x value 0.
03 filler pic 9(2) comp-x value 2.
01 disable-all-other-user-keys.
03 filler pic 9(2) comp-x value 0.
03 filler pic x value "1".
03 filler pic 9(2) comp-x value 2.
03 filler pic 9(2) comp-x value 126.
01 enable-slash-key.
03 filler pic 9(2) comp-x value 1.
03 filler pic x value "3".
03 filler pic x value "/".
03 filler pic 9(2) comp-x value 1.
************************************************************
* Status returned after termination of an ACCEPT.
************************************************************
01 key-status.
03 key-type pic x.
03 key-code-1 pic 9(2) comp-x.
03 key-code-1-x redefines key-code-1 pic x.
03 key-code-2 pic 9(2) comp-x.
***********************************************************
* Cursor-Position is returned by ADIS containing the
* position of the cursor when the ACCEPT was terminated.
***********************************************************
01 cursor-position.
03 cursor-row pic 99.
03 cursor-column pic 99.
***********************************************************
* Work Areas used by the program.
***********************************************************
01 work-areas.
03 wa-name pic x(30).
03 wa-address-line-1 pic x(40).
03 wa-address-line-2 pic x(40).
03 wa-address-line-3 pic x(40).
03 wa-address-line-4 pic x(40).
03 wa-age pic 999.
01 exit-flag pic 9(2) comp-x value 0.
**********************************************************
* Screen Section.
**********************************************************
screen section.
01 main-screen.
03 blank screen.
03 line 2 column 27
value "typical data entry screen".
03 line 3 column 27
value "-------------------------".
03 line 5 column 1 value "name [".
03 pic x(30) using wa-name highlight prompt " ".
03 value "]".
03 line 7 column 1 value "address [".
03 pic x(40) using wa-address-line-1 highlight prompt " ".
03 value "]".
03 line 8 column 1 value " [".
03 pic x(40) using wa-address-line-2 highlight prompt " ".
03 value "]".
03 line 9 column 1 value " [".
03 pic x(40) using wa-address-line-3 highlight prompt " ".
03 value "]".
03 line 10 column 1 value " [".
03 pic x(40) using wa-address-line-4 highlight prompt " ".
03 value "]".
03 line 12 column 1 value "age [".
03 pic zz9 using wa-age highlight prompt " ".
03 value "]".
03 line 20 column 1 value
"------------------------------------
- "----------------------------------------".
03 line 21 column 1 value "f1" highlight.
03 value "=/help".
03 column 75 value "esc" highlight.
03 value "ape".
01 help-screen.
03 blank screen.
03 line 1 column 34 value "help screen".
03 line + 1 column 34 value "-----------".
03 line 4 value "escape" highlight.
03 value " leave this program.".
03 line 6 column 1 value "f1 or /h" highlight.
03 value " obtains this screen.".
03 line 8 column 1
value "use cursor keys to move around ".
03 value "the fields on the screen".
03 value "enter will".
03 line + 1 column 1 value "accept the data ".
03 value " present new blank form to fill in.".
03 line 24 column 25
value "press any key to continue ...".
***************************************************************
* Procedure Division.
***************************************************************
procedure division.
entry-point section.
* First we want to ensure that the keys are enabled as we want
* them. Enable the Escape and F1 keys.
call x"AF" using set-bit-pairs
enable-esc-and-f1
* disable every other user function key.
call x"AF" using set-bit-pairs
disable-all-other-user-keys
* set up "/" key to act as a function key and terminate
* the accept.
call x"AF" using set-bit-pairs
enable-slash-key
* Now ensure that the cursor position will be returned when
an
* ACCEPT is terminated. Setting to row 1, column 1 will ensure
* that the cursor will be initially positioned at the start of
* the first field.
move 1 to cursor-row
move 1 to cursor-column
* Loop until the Escape key is pressed.
perform until exit-flag = 1
display main-screen
accept main-screen
evaluate key-type
when "0"
* Accept terminated normally, i.e., the Enter key was pressed.
* Here, we simply blank out the work areas and restart in the
* first field.
move spaces to work-areas
move 1 to cursor-row
move 1 to cursor-column
when "1"
* A user function key has been pressed. This will either be
Esc
* or F1 as all others have been disabled.
if key-code-1 = 0
* Escape has been pressed, so we wish to leave the program.
move 1 to exit-flag
else
* F1 has been pressed so display the help screen.
perform display-help-screen
end-if
when "3"
* A data key has terminated the Accept. It must be "/" as no
* other keys have been enabled to do this. Now get the next
* character to see if "H" or "h" has been pressed.
call x"AF" using get-single-character
key-status
if key-type = "3"
and (key-code-1-x = "h" or
key-code-1-x = "h")
perform display-help-screen
end-if
end-evaluate
end-perform
stop run.
display-help-screen section.
* Display the help screen and then wait for a key to be pressed.
display help-screen
call x"AF" using get-single-character
key-status.
Solutions to Common Problems
On some terminals, you may find that some keys do not function as
expected or do not function at all.
This may be due to inconsistencies between the system terminfo
database, the absolute control sequences
generated by some keys and the default Micro Focus COBOL special full
screen ACCEPT/DISPLAY keys (for example, change case of character).
You should first ensure that the appropriate terminal name is set in the
$TERM
environment variable and that this gives access to a matching entry in
the system terminfo database. See Appendix I , Environment Variables.
You should then ensure that all the essential entries are present for the
terminal in the terminfo database and that all the escape sequences
match those generated by the appropriate terminal keys when in raw mode.
See Chapter 22 , Device Handling and Terminfo.
Micro Focus may supply some terminfo files. If so, these files will be
in $COBDIR/terminfo. The Micro Focus Screen Handling Package, libscreen,
will search for terminfo files in $COBDIR/terminfo before searching
anywhere else.
Solutions to some of the problems you may encounter are listed below:
* The cursor-left and Backspace keys produce the same escape
sequence.
If so, the cursor-left will take priority over Backspace. You
will need to configure an alternate key for Backspace using the
keybcf utility if you need this function.
* The cursor-down and Enter keys produce the same escape sequence.
If so, the Enter key will take priority over cursor-down. You
will need to configure an alternate key for cursor-down using the
keybcf utility if you need this function.
* Animator function keys do not work.
Some terminfo files may not contain information on function
keys. If this is true, you must configure keys for these
functions using the keybcf
utility. See Chapter 4 , Animating and Chapter 24 ,
Keyboard Configuration Utility.
* If you use the keybcf utility to configure any key which starts
with the escape character as the first character in its sequence,
you will not be able to use the Escape key.
In order to resolve this, configure the Escape function as escape
escape, that is, two escapes. You will then be able to use this
function by pressing Escape twice.
* The keybcf utility creates a single configuration file,
cobkeymp,
which is capable of defining the configuration of only a single
terminal type. If you need to define more than one terminal, you
can create multiple cobkeymp
files, and select the desired one on a per user basis, using the
environment variable dd_cobkeymp
to map to different configuration files. See Chapter 12 ,
COBOL File Handling for details on dd_file-name mapping.
* To add extra terminal initialization sequences
when entering COBOL (for example, to enable user function keys),
you should extend init_1string to include the appropriate
sequences. See your terminal manual for further details on escape
sequences.
* If your terminal and terminfo support color and you specify the
REVERSE-VIDEO reserved word, the foreground and background colors
on your screen are swapped. However, your terminfo entry ncv
may prevent this behavior. See Chapter 22 , Device Handling
and Terminfo for further details.