Operation (cont) [ Micro Focus COBOL System Reference, Volume 1 ] MPE/iX 5.0 Documentation
Micro Focus COBOL System Reference, Volume 1
Operation (cont)
Adis Configuration (cont)
Enable or Disable Display of the Adis Indicators.
These routines enable you to enable or disable the display of the
indicators that Adis displays during an ACCEPT to indicate insert/replace
mode, autoclear mode or "off end of field". These can also be controlled
using the Alter Message/Indicator Positions menu in Adis. See the
section The Alter Message/Indicator Positions Menu in the chapter Adis
Configuration Utility (Adiscf) for more information.
These calls override any settings made in Adiscf. By default, these
indicators are displayed.
There is a different call to control each of the three indicators, but
they all have the same format.
The fields in parameter-block should be set as follows:
bit-pair-number should be set to one of the following:
56 To control the Insert/Replace mode indicator.
57 To control the Off end of field indicator.
58 To control the Autoclear indicator.
bit-pair-setting should be set to one of the following:
0 The indicator is displayed if necessary. This is the default.
3 The indicator is never displayed.
Example.
The following code disables display of the insert/replace indicator and
enables display of the Off end of field indicator:
move 56 to bit-pair-number
move 3 to bit-pair-setting
call x"AF" using set-bit-pairs
parameter-block
move 57 to bit-pair-number
move 0 to bit-pair-setting
call x"AF" using set-bit-pairs
parameter-block
Enable or Disable Display Adis Error Messages .
This routine enables you to enable or disable the display of the messages
that Adis outputs during execution of an ACCEPT statement. These can
also be controlled by use of the Alter Messages/Indictators Positions
menu in Adiscf. See the section Altering Message/Indicator Positions in
the chapter Adis Configuration Utility (Adiscf) for more information.
This call overrides any settings made in Adiscf. By default, these
messages are displayed.
The fields in parameter-block should be set as follows:
bit-pair-number must be set to 44.
bit-pair-setting should be set to one of the following values:
0 Error messages are never displayed, but the bell is rung.
Invalid data entered into a numeric or numeric-edited field in
free-format mode is not reported as an error.
1 Error messages are never displayed, but the bell is rung.
Invalid data entered into a numeric or numeric-edited field in
free format mode is reported as an error by ringing the bell.
2 Error messages are displayed and the bell is rung if the
appropriate error occurs. Invalid data entered into a numeric or
numeric-edited field in free-format mode is not reported as an
error.
3 Error messages are displayed and the bell is rung if the
appropriate error occurs. Invalid data entered into a numeric or
numeric-edited field in free-format mode is reported as an error
by ringing the bell.
Example.
The following code disables the display of error messages and disables
the reporting of invalid data in numeric and numeric-edited fields.
move 44 to bit-pair-number
move 0 to bit-pair-setting
call x"AF" using set-bit-pairs
parameter-block
Enable or Disable Auto-skip Between Fields.
This routine enables you to control circumstances in which auto-skip to a
following or preceding field occurs during execution of an ACCEPT
statement. This can also be controlled using ACCEPT/DISPLAY option 7 in
Adiscf. See the section Altering ACCEPT/DISPLAY Options in chapter Adis
Configuration Utility (Adiscf) for more information.
This call overrides any settings made in Adiscf.
The fields in parameter-block should be set as follows:
bit-pair-number must be set to 81.
bit-pair-setting should be set to one of the following values:
1 No auto-skip. An explicit Tab or cursor key (but not Backspace)
must be used to move between fields.
3 Auto-skip enabled. Any cursor movement or a character key causes
auto-skip to the next field if at end of the current field. This
is the default.
Example.
The following code disables auto-skip between fields:
move 81 to bit-pair-number
move 1 to bit-pair-setting
call x"AF" using set-bit-pairs
parameter-block
Enable or Disable Input Data Case Conversion.
This routine enables you to control whether lower-case ASCII characters
are automatically converted to upper-case on entry during execution of an
ACCEPT statement.
The fields in parameter-block should be set as follows:
bit-pair-number must be set to 85.
bit-pair-setting should be set to one of the following values:
0 No case conversion occurs. This is the default.
1 Lower-case alphabetic input data is converted to upper-case on
entry.
Example.
The following code enables conversion to upper-case of all alphabetic
input:
move 85 to bit-pair-number
move 1 to bit-pair-setting
call x"AF" using set-bit-pairs
parameter-block
Enable or Disable Password Concealment.
This routine enables you to control whether or not characters input when
an ACCEPT statement is executed should be echoed to the screen.
The fields in parameter-block should be set as follows:
bit-pair-number must be set to 84.
bit-pair-setting should be set to one of the following values:
0 Input is echoed to the screen. This is the default.
1 Input is not echoed to the screen for the next ACCEPT statement
encountered only.
2 Input is not echoed to the screen for any following ACCEPT
statements until it is re-enabled.
Example.
The following code conceals the input for the next ACCEPT statement only:
move 84 to bit-pair-number
move 1 to bit-pair-setting
call x"AF" using set-bit-pairs
parameter-block
Enable or Disable Pre-clear and Auto-clear.
This routine enables you to control whether a field is cleared before
data entry (pre-clear), or is cleared on entry of the first keystroke
(auto-clear). This can also be controlled using the ACCEPT/DISPLAY
option 15 in Adiscf. See the section ACCEPT/DISPLAY Options in chapter
Adis Configuration Utility (Adiscf) for more information.
The fields in parameter-block should be set as follows:
bit-pair-number must be set to 86.
bit-pair-setting should be set to one of the following values:
0 No pre-clear or auto-clear action occurs. This is the default.
1 Pre-clear mode. On moving forward into a field for the first
time it is cleared to spaces or zeros. The original contents of
the field can be recovered by pressing Undo.
2 Auto-clear mode. If the first keystroke after moving forward
into a field for the first time is a valid data character, the
field is cleared to spaces or zeros before processing the
character. Any other type of key turns off auto-clear mode. The
original contents of the field can be recovered by pressing Undo.
3 Pre-clear mode. As for option 2, except that Undo cannot be used
to recover the original contents of the field.
Example.
The following code enables pre-clear mode:
move 86 to bit-pair-number
move 1 to bit-pair-setting
call x"AF" using set-bit-pairs
parameter-block
Select Timeout Units.
This routine enables you to determine whether the timeout value is
interpreted as seconds or tenths of a second.
The fields in parameter-block should be set as follows:
bit-pair-number must be set to 14.
bit-pair-setting should be set to one of the following values:
0 Units are seconds. This is the default.
1 Units are tenths of a second.
Example.
The following code specifies that any subsequent timeout is specified in
tenths of a second:
move 14 to bit-pair-number
move 1 to bit-pair-setting
call x"AF" using set-bit-pairs
parameter-block
Timeout Reset Control .
This routine enables you to control whether the timer is reset every time
a character is entered, or times out after the specified period anyway.
The fields in parameter-block should be set as follows:
bit-pair-number must be set to 15.
bit-pair-setting should be set to one of the following values:
0 Timer is never reset. Timeout occurs after the specified time
from the start of the ACCEPT operation. This is the default.
1 The timer is reset each time a character is entered.
Enable or Disable Screen Read on Non-FED Terminals.
This function enables the initial field contents to be read from the
current screen map held by the RTS, when predisplay is off during an
ACCEPT operation.(UNIX)
The fields in parameter-block' should be set as follows:
bit-map-section must be set to 6.
bit-pair-number must be set to 6.
bit-pair-setting' should be set to one of the following values:
0 No read takes place. This is the default.
1 During an ACCEPT operation, if predisplay is off, the initial
field contents are read from the current screen map held by the
RTS.
NOTE bit-map-section is set to 6 for this function, but 2 for all the
other functions listed in this section. Do not forget to restore
it to 2 after using this function if you are going to use another
one.
Keyboard Handling Via Adis
The following subjects are described in this section:
* 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.
* CONTROL clause in an ACCEPT/DISPLAY statement.
* Screen Section size.
Types of Keys on the Keyboard.
In general, the keys on the keyboard can be split into four groups:
* Function keys.
* Data keys.
* Shift keys.
* Lock 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...F12) and such
keys as Escape, the cursor keys, Tab, and Backspace. Enter is also
treated as a function key, but with special considerations, described
later.
In your COBOL system, these function keys are divided into two groups:
* Adis keys.
* 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 operate as defined during an ACCEPT operation. For
example, the [[backspace]] key moves the cursor to the left, Backspace
erases the previous character, and so on. With the exception of the
Enter key, they do not normally terminate the ACCEPT operation. However,
you can make these keys terminate the ACCEPT operation if required. This
is described later in this section.
User Function Keys.
These keys are so called because you can decide what they are used for
when you are writing an application. There is no predefined action
assigned to these keys. The user function keys generally include the
keys labeled F1, F2...F12, the Escape key, and any other special keys
that are on the keyboard.
Data Keys.
Data keys are those keys 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
simply places 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.
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.
Shift Keys.
A shift key is a key whose depression and release are regarded as
separate events. Examples of shift keys in Adis are Alt, Ctrl and Shift.
See the section Shift Key Handling later in this chapter for more
information on shift keys.
Lock Keys.
A lock key is a key whose state is toggled when it is pressed. Examples
of lock keys are Caps Lock, Insert, Num Lock and Scroll Lock. See the
section Lock Key Handling later in this chapter for more information on
lock keys.
Function Key Handling.
This section describes how to use function keys in this COBOL system. It
describes the portable method that works 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, see the section
Conflict with the x"B0" COBOL System Library Routine for details of how
this could cause problems with certain configurations.
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 as follows:
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 is 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.
"5" - Termination by a shift key.
"6" - Termination by a lock 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 operation. 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 0, key-code-2 contains
the raw keyboard codefor 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 contains the second byte
of the character which caused the ACCEPT operation to
terminate.
Otherwise, the contents of key-code-2 are undefined.
See your Language Reference for more information on the CRT STATUS
clause.
Normal Termination of an ACCEPT Operation.
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 operation is by
pressing Enter. This returns a value of 48 (the ASCII code for 0)
in key-code-1.
* It is possible to configure Adis (using Adiscf) so that an
auto-skip in the last field on the screen terminates the ACCEPT
operation. 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. The defaults supplied with your
COBOL system differ on different operating environments, but the
following keys are standard:
Keystroke 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 might not have these keys, but if they are there, they
should be configured as above. Additionally, the following user function
keys might be defined:
Keystroke User
Function
Key Number
-------------------------------------
Shift+F1 - Shift+F10 11 - 20
Ctrl+F1- Ctrl+F10 21 - 30
Alt+F1 - Alt+F10 31 - 40
Alt+1 - Alt+9 41 - 49
Alt+0 50
Alt+ - 51
Alt+= 52
PgUp 53
PgDn 54
Ctrl+PgUp 55
Ctrl+PgDn 56
Alt+A - Alt+Z 65 - 90
F11 91
F12 92
Shift+F11 93
Shift+F12 94
Ctrl+F11 95
Ctrl+F12 96
Alt+F11 97
Alt+F12 98
On UNIX environments, function keys 11 to 63 are defined in your terminfo
database. See also the appendix UNIX Key Usage Chart. (UNIX)
Enabling and Disabling the User Function Keys.
Before you can use any of the user function keys, they must be enabled.
If a user key is enabled, it terminates the ACCEPT operation when
pressed. If the key is disabled, the key is rejected and the bell rung.
By default, on DOS, OS/2 and Windows this COBOL system disables the user
function keys; on UNIX the COBOL system enables the user function keys.
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:
set-bit-pairs and user-key-control are defined in the Working-Storage
Section of your program as follows:
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.
where:
user-key-setting is set to 0 to disable keys or 1 to enable keys.
first-user-key is the number of the first key to be enabled or
disabled.
number-of-keys is 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 cumulative. For example, if you call x"AF" to
enable function key F1, then make a second call to enable F10, both keys
are enabled.
MPE/iX 5.0 Documentation