| Low-level Routines for Character Interfaces | Configuring Enhanced ACCEPT and DISPLAY | |
Adis is a run-time support module which is provided for Screen Section and enhanced ACCEPT/DISPLAY syntax. Adis can be configured to an application's requirements using the Adis Configuration utility (see the chapter Configuring Enhanced ACCEPT and DISPLAY). Alternatively, calls can be made from the COBOL application to Adis to configure it at run time; for example, to enable function keys.
Note: The term field when used in relation to screen handling refers to an area on the screen that corresponds to a single data item during ACCEPT and DISPLAY operations.
Adis provides the run-time support for Screen Section and enhanced ACCEPT/DISPLAY syntax. Adis consists of four modules:
Figure 4-1: The Adis Modules
The enhanced ACCEPT/DISPLAY syntax provides functionality beyond the standard ANSI ACCEPT syntax, which enables you to input a data item or accept the day, date or time into a data item, and the ANSI DISPLAY syntax, which enables you to output literals and the contents of data items.
With the enhanced ACCEPT/DISPLAY syntax supported by Adis, you can specify screen position and screen attributes. It also makes it possible to do either single-field or multiple-field ACCEPT operations. For multiple-field ACCEPT operations, FILLER describes the number of character positions to skip over to the next field. In a DISPLAY operation, FILLER defines the number of spaces between literals. All areas defined as FILLER are unaffected by the ACCEPT or DISPLAY operation.
The Screen Section is a section in the Data Division containing one or more screen definitions. A screen definition can contain fields, groups, text and attributes. Fields can have edited picture strings as well as features such as NO-ECHO, JUSTIFIED RIGHT and BLANK WHEN ZERO. The effect of ACCEPT and DISPLAY statements on screen definitions is handled by Adis.
Adis can be configured to affect the behavior of ACCEPT and DISPLAY statements at run time. You can configure Adis in two ways:
This section describes how ACCEPT and DISPLAY statements in the following format are handled at run time:
display data-item at xxyy ... accept data-item at xxyy ...
where the parameters are:
Adis does not display a character at the last position on the screen (for example, line 25 column 80 on a 25 line screen). This is because some terminals scroll automatically when a character appears in this position, giving different results on different hardware. If a character is displayed at a position off the screen, Adis scrolls the display such that it is visible.
We also recommend you avoid displaying at the last position of the screen on some non-UNIX environments, since scrolling can also occur.
The following sections describe how the ACCEPT statement is executed on different types of fields.
The term alphanumeric field is used here to cover all alphanumeric, alphabetic and alphanumeric-edited fields. For the purposes of an ACCEPT statement, an alphanumeric-edited field is treated as an alphanumeric field of the same length. Any insertion symbols such as the forward slash character (/) or zero are ignored and treated as an X. Therefore, a field defined as PIC XX0XX0XX is treated as if it was specified as PIC X(8).
If the field is defined as alphabetic, only the characters "A" to "Z", "a" to "z" and space are allowed into the field.
The cursor is initially placed at the start of the field.
As data is entered into the field, the cursor advances to the next character. The cursor can be moved back over the data in the field using the cursor keys, and editing functions such as backspace and delete are provided.
The form of data entry for numeric and numeric-edited fields can be one of the following:
Use the Adis Configuration utility to select the style you want. The default form of data entry is fixed-format. You should experiment with free-format to see which method you prefer, especially when accepting into simple numeric fields.
The three styles are described below, followed by notes on data entry in general.
Fixed-format mode is also known as formatted mode. It can best be described as "What you see is what you get". As each key is pressed, the field is automatically reformatted to conform to the picture string. Adis tries to ensure that the field always looks on the screen as it is stored in the Data Division, and its size is the same as the size of the data item.
Therefore, as with the DISPLAY statement, it is only really sensible to accept fields that are defined as USAGE DISPLAY with no implied sign or decimal point.
During data entry, characters other than numeric digits, the plus sign (+), minus sign (-) and the decimal point (.) are rejected. Insertion characters in edited fields are automatically skipped over as the cursor is moved backward and forward. Any sign indicator is automatically modified if a + or - is pressed, regardless of where the cursor is in the field.
Zeros are allowed as insertion characters only as a leading symbol before a decimal point, or as a trailing symbol following a decimal point. For example, PIC 0.9999 and PIC 999.90 are valid, but PIC 0.0009 and PIC 999.000 are not.
Data entry of simple numeric and numeric-edited fields with no zero suppression is similar to that for alphanumeric fields, except that insert mode is not supported in numeric and numeric-edited fields. If the decimal point character is pressed in a simple numeric field, the digits are right justified. For example, a field defined as PIC 9(5) which initially contains zeros is accepted as follows (underlined characters indicate cursor position):
Initial display 00000 Pressing 1 gives 10000 Pressing 2 gives 12000 Pressing 4 gives 12400 Pressing Backspace gives 12000 Pressing "." gives 00012
Data entry into zero-suppressed fields is handled differently. The cursor is initially placed on the first character position that is not zero-suppressed. If all the digits before the decimal point are suppressed, the cursor is positioned on the decimal point itself.
While the cursor is to the left of the decimal point; that is, in the integer part of the field, the cursor moves to the right as digits are entered until the decimal point is reached. Any further digits are inserted immediately before the decimal point until all the integer places are filled. The cursor is then automatically moved to the first decimal digit and advances as the decimal digits are entered.
If you wish to enter digits after the decimal point when there are integer places still unfilled, the decimal point (.) must be entered.
For example, assume that a numeric-edited data field is defined as PIC ZZZ99.99 and initially contains zeros, the field is displayed as follows during the ACCEPT:
Initial display 00.00 Pressing 1 gives 10.00 Pressing 2 gives 12.00 Pressing 3 gives 123.00 Pressing 4 gives 1234.00 Pressing Backspace gives 123.00 Pressing 5 gives 1235.00 Pressing 6 gives 12356.00 Pressing 7 gives 12356.70 Pressing 8 gives 12356.78
If you want to enter 123.45 into the same field, the field appears as follows:
Initial display 00.00 Pressing 1 gives 10.00 Pressing 2 gives 12.00 Pressing 3 gives 123.00 Pressing "." gives 123.00 Pressing 4 gives 123.40 Pressing 5 gives 123.45
Fixed-format mode is only allowed on numeric-edited data items of up to 32 characters in length. If they are longer than 32 characters, they are automatically handled in free-format mode as described below. Fields are also automatically treated as free-format if a SIZE clause is specified in the ACCEPT statement.
Free-format mode can be selected for either numeric fields or numeric-edited fields or both. This can be done using the Adis Configuration utility (see the section ACCEPT/DISPLAY Options in the chapter Configuring Enhanced ACCEPT and DISPLAY for more information).
During data entry into a free-format field, the field is treated as an alphanumeric field of the appropriate length. It is only when the user leaves the field that it is reformatted to comply with the picture string. Any characters other than the digits, the sign character and the decimal point character are discarded.
Fields occupy the same number of characters on the screen as they do bytes in memory, with the exception that an additional character is allocated for implied signs and decimal points. Therefore, a data item defined as PIC S99V99 occupies six characters on the screen in free-format mode as opposed to four characters in fixed-format mode.
It is advisable to compile the program with the DE-EDIT"1" Compiler directive set, since free-format allows data that does not conform to the screen item's PICTURE clause; with DE-EDIT"2" this is interpreted as zeros when moved to the USING or TO data item.
Data entry is the same as for alphanumeric fields.
If an enhanced ACCEPT statement is being used, the clauses SPACE-FILL, ZERO-FILL, LEFT-JUSTIFY, RIGHT-JUSTIFY and TRAILING-SIGN are applicable only to free-format non-edited fields (and are ignored with fixed-format fields). See the description of the ACCEPT statement in your Language Reference for further details of these clauses.
RM style data entry is selected using the appropriate Accept/Display option in the Adis Configuration utility . It is provided for emulation of numeric and numeric-edited ACCEPT operations in RM/COBOL V2.0. If this mode is selected, all other Accept/Display option numeric and numeric-edited data entries are ignored. Data entry is the same as for alphanumeric fields. All ACCEPT and DISPLAY statements behave as if the phrase MODE IS BLOCK has been specified. See the section The MODE IS BLOCK Clause for more information.
This style of numeric input is not intended for use with the screen handling syntax in this COBOL system, only with programs originally written for RM/COBOL.
These notes concern the accepting of data into fields:
For example, if you accept a data item that is PIC X(190) at line 1, column 1 and the screen is only 80 characters wide, the field is broken into three subfields, two with 80 characters and one with 30 characters.
The following sections describe the way that the DISPLAY statement functions.
When a data item is displayed on the screen, it normally occupies the same number of characters on the screen as it does bytes in memory. The only exceptions are DBCS encoding schemes such as EUC which includes characters which differ in storage space and display size. The following examples assume such characters do not occur.
| Data Description | Size on Screen | Comment |
|---|---|---|
| X(5) | 5 characters | |
| N(5) | 10 characters | Each PIC N character occupies 2 bytes in memory. |
| G(5) | 10 characters | Each PIC G character occupies 2 bytes in memory. |
| 9(5) | 5 characters | |
| 99.99 | 5 characters | |
| Z(4)9 | 5 characters | |
| 99V99 | 4 characters | V is an implied decimal point and so is not displayed on the screen. |
| S9(4) | 4 characters | The sign is implied and so is not displayed on the screen. |
| S9(4) SIGN LEADING SEPARATE | 5 characters | |
| 9(4) COMP | 2 characters | COMP fields are stored in binary; a 9(4) COMP field
occupies 2 bytes in memory. |
As you can see from the above examples, it is only really sensible to display fields defined as USAGE DISPLAY which do not contain implied signs or decimal points. When the field is displayed, it is copied byte-for-byte from the data item onto the screen at the required position.
Note: ANSI DISPLAY operations convert non-USAGE DISPLAY numeric items to USAGE DISPLAY before displaying.
Control sequences cannot be embedded in the data that is displayed. If you do embed control codes (that is, ASCII codes less than 32) into the data, the character corresponding to that code is displayed. For example, displaying ASCII code 7 results in a diamond character being displayed instead of sounding the bell. (In some environments, such characters are replaced by a space.) All highlighting and cursor control must be done through the syntax provided.
If you use the CRT-UNDER phrase in a DISPLAY statement, the data item is displayed with an attribute to make the display stand out from normal displayed text. Depending on your environment, use of the CRT-UNDER phrase might cause data items to be displayed underlined, highlighted, colorized or in reverse video. This can be changed using the Adis Configuration utility. See the chapter Configuring Enhanced ACCEPT and DISPLAY for more information.
When displaying or accepting group items, each elementary item within the group is treated as a separate field. If an elementary item is defined as FILLER, it is simply used as a positioning item of the appropriate size; that is, you cannot accept into or display FILLER items.
When accepting into a group item, each field is accepted into as described for single-field ACCEPT statements (see the section Single Field ACCEPT Statements).
Unless you explicitly position the cursor (see the section The CURSOR IS Clause), the cursor is initially placed at the start of the first field.
When the end of a field is reached, the cursor is normally advanced to the beginning of the next field automatically. This action can be prevented by turning off auto-skip (Accept/Display option 7 in the Adis Configuration utility; see the chapter Configuring Enhanced ACCEPT and DISPLAY). The cursor keys, and the keys set up for next and previous field operations (usually Tab and Backtab) move the cursor around the fields.
Consider the following group item:
01 display-item.
03 display-item-1 pic x(20).
03 filler pic x(35).
03 display-item-2 pic 9(10).
03 filler pic x(105).
03 display-item-3 pic z(4)9.
If the following statement is executed on a screen 80 characters wide:
display display-item at 0101
display-item-1 is displayed at row 1, column 1, display-item-2
is displayed at row 1, column 56, and display-item-3 is
displayed at row 3, column 11
All other areas of the screen are unaffected by this DISPLAY statement. FILLER items do not cause any data to be displayed on the screen. Consequently, data already on the screen in the positions defined by each FILLER is not altered in any way by this DISPLAY statement.
If a data item is defined as follows :
01 data-item.
03 data-char pic x occurs 2000.
and the following statement is executed:
display data-item at 0101
then this is treated as a display of 2000 fields, each defined as PIC X,
which is unlikely to be what you require. To avoid this, either redefine
data-item as a PIC X(2000) and display that, or use the MODE
IS BLOCK clause described in the section The MODE IS
BLOCK Clause.
If the MODE IS BLOCK clause is added to an ACCEPT or DISPLAY of a group item, the group item is treated as if it was an elementary item of the total size of the group item.
Consider the following group item:
01 display-item.
03 display-item-1 pic x(20).
03 filler pic x(35).
03 display-item-2 pic 9(10).
03 filler pic x(105).
03 display-item-3 pic z(4)9.
If the following statement is executed:
display display-item at 0101 mode is block.
display-item is treated as if it is an elementary item
defined as:
01 display-item pic x(175).
Consequently, the contents of the FILLER items are also displayed.
Note: If a program is compiled with the IBM-MS, MS"1", MS"2" or RM directives set, the Compiler treats all DISPLAY and ACCEPT operations of group items as if MODE IS BLOCK had been specified.
ACCEPT and DISPLAY operations involving Screen Section items are treated like any other ACCEPT or DISPLAY operation, but with one important difference. Consider the following code:
working-storage section.
01 item-a pic 9(5).
01 item-b pic 9(10).
01 item-c pic x(10).
...
screen section.
01 demo-screen.
03 blank screen.
03 line 1 column 1 pic z(4)9 from item-a.
03 line 3 column 1 pic 9(10) to item-b.
03 line 5 column 1 pic x(10) using item-c.
When this code is compiled, the Compiler sets up a work area for each
Screen Section level-01 item (record). Therefore, in this example, a work
area is set up for demo-screen, large enough to hold the
data for the three fields.
When the following statement:
display demo-screen
is executed, the contents of item-a and item-c
are moved from Working-Storage Section into the work area, then the data
in the work area for these two fields is displayed on the screen. item-b
is not displayed because it is an ACCEPT-only field.
When the following statement:
accept demo-screen
is executed, data is accepted into the work area for item-b
and item-c and then the data for these two fields is moved
from the work area into the Working-Storage Section. Data is not accepted
into item-a because it is a DISPLAY-only field.
It is important to note that moves from the Data Division to the work area occur only on execution of a DISPLAY statement, and moves from the work area to the Data Division occur only during execution of an ACCEPT statement. Therefore, if two ACCEPT statements are executed one after another with no intervening DISPLAY statement, the initial contents of the fields at the start of the second ACCEPT are those which were put into the work area during the previous ACCEPT operation not the current contents of the Data Division items.
Another implication of this is that a field should not be defined as numeric-edited in both the Data Division Section and the Screen Section . This results in the compiler making numeric-edited to numeric-edited moves in order to move the Data Division item into the work area and back again. The action of such moves is undefined and has unpredictable results. This is the case even if both the Data Division item and the Screen Section item have the same picture.
Hence, if the following lines are coded in your program:
working-storage section. 01 ws-item pic zz9.99 value 1.23
screen section.
01 demo-screen.
03 pic zz9.99 using ws-item.
procedure division.
display demo-screen.
the result of the DISPLAY operation is undefined . The items used in the Data Division as source or target for Screen Section ACCEPT or DISPLAY statements should always be non-edited fields.
The CURSOR IS clause allows you to specify precisely where in a field you want the cursor to be positioned at the start of the ACCEPT operation, and returns where the cursor was left at the end of an ACCEPT operation. If you do not specify a CURSOR IS clause in your program, the cursor is always initially positioned at the start of the first field for every ACCEPT operation.
The CURSOR IS clause is defined in the Special-Names paragraph , as follows:
special-names.
cursor is cursor-position.
where cursor-position is a field defined in the
Working-Storage Section of your program as follows:
01 cursor-position.
03 cursor-row pic 99.
03 cursor-column pic 99.
or:
01 cursor-position.
03 cursor-row pic 999.
03 cursor-column pic 999.
where:
cursor-row |
Specifies the row the cursor is positioned on. Valid values are between 1 and the number of lines on the screen. |
cursor-column |
Specifies the column the cursor is positioned on. Valid values are between 1 and the number of columns on the screen. |
Whenever an ACCEPT statement is executed, Adis attempts to initially
position the cursor at the position specified in cursor-position.
If the position specified is invalid (that is, either cursor-row
or cursor-column does not contain a valid value),
the cursor is positioned at the start of the first field on the screen.
If the value in cursor-position is valid, Adis
searches through all of the fields to see if the requested cursor position
lies within one of them. If it does, the cursor is positioned at the
required point. If it does not, then the cursor is positioned at the start
of the first field. Therefore, if you want the cursor to be positioned at
the start of the first field, set both cursor-row
and cursor-column to 1.
Where the defined position is on a suppressed character or insertion symbol in a numeric-edited field, the cursor moves to the first available character to the right. If there is no further data item, the cursor returns to the first data item on the screen.
When the ACCEPT is terminated, if the value in cursor-position
at the start of the ACCEPT was valid, the position of the cursor when the
terminating key is pressed is returned in cursor-position.
This might not be the same position as the current cursor position, since
Adis usually moves the cursor to the end of the field upon termination of
an ACCEPT operation to allow relative positioned ACCEPT statements to
start at the correct point on the screen.
If the value in cursor-position at the start of
the ACCEPT operation was invalid, then, when the ACCEPT operation is
terminated, the contents of cursor-position are
unchanged.
One example of the use of this facility is that in menu-type operations,
the operator need only move the cursor to a position on the screen
corresponding to the selection required. The operator's choice can be
determined by the returned value of cursor-position.
Screens larger than 25 lines can be detected by your COBOL system.
You can define the screen size in your terminfo entry or with the LINES and COLUMNS environment variables.
Programs using ANSI ACCEPT/DISPLAY statements, enhanced ACCEPT/DISPLAY syntax, Screen Section and the COBOL system library routines should run correctly on large screens. If an application is developed for a screen larger than the screen it is run on, the extra lines of a multiple-field ACCEPT or DISPLAY are lost. In addition, if the position specified by the AT clause of an ACCEPT or DISPLAY statement is off the screen, the screen is scrolled up by one line.
This system supports the CONTROL clause within the WITH phrase of Format 2 of the screen handling ACCEPT and DISPLAY statements, and within Adis ACCEPT and DISPLAY statements. This clause allows attributes associated with a Screen Section item to be defined at run time. See your Language Reference for details of format and syntax.
One of the powerful features of Adis is that it can be configured to tailor the behavior of ACCEPT and DISPLAY statements. Full configuration is possible using the Adis Configuration utility (supplied with this product) via the ADISCTRL file produced by this utility. Full details on how to do this are given in the chapter Configuring Enhanced ACCEPT and DISPLAY.
Adis is designed to operate with no ADISCTRL file present, using predefined defaults for all the configurable options. Applications that operate successfully using these default options can be shipped without the ADISCTRL file.
At run time, Adis searches for the ADISCTRL file in the current directory and then, if not found, in the COBOL system directory. Unless your applications all use the same non-default configuration, you are advised to work without the ADISCTRL file, if possible, and only to create it in the current directory if it is needed.
Remember that during installation, the default ADISCTRL file is copied to the COBOL system directory only when the Adis configuration is selected. If you wish to alter the default configuration, you are advised to move ADISCTRL into your current directory before changing it, and not return it to the COBOL system directory.
On some UNIX environments you might have been supplied with a cobkeymp file. If this is the case, it is essential, for correct operation of ACCEPT statements, that you have this file in the COBOL system directory. The cobkeymp file is produced by the Keyboard Configuration utility, which enables you to configure the behavior of your keyboard. See the chapter Configuring Your Keyboard for more information.
The ADISCTRL file contains a number of predefined Adis configurations. There is a library routine that your program can use to select which configuration to use during the execution of extended ACCEPT and DISPLAY statements. It overrides the configuration selected in the Adis Configuration utility.
The routine is defined as:
call x"AF" using set-configuration configuration-name
where set-configuration and configuration-name
are defined in the Working-Storage Section of your program as follows:
01 set-configuration pic 9(2) comp-x value 59. 01 configuration-name pic x(70).
where:
set-configuration
|
Contains the value 255 on return from the call if the
name specified in configuration-name is not found
in the ADISCTRL file. |
configuration-name
|
The name that appears on the F6=Choose menu in the Adis Configuration utility . |
This section describes features of Adis that are not available via COBOL syntax, but can be accessed with the x"AF" COBOL system library routine. Most of these features can also be set by configuring Adis using the Adis Configuration utility . See the chapter Configuring Enhanced ACCEPT and DISPLAY for more information.
All of these features are accessed by the following CALL statement:
call x"AF" using set-bit-pairs parameter-block
where the parameters are defined as follows:
01 set-bit-pairs pic 9(2) comp-x value 1.
01 parameter-block.
03 bit-pair-setting pic 9(2) comp-x.
03 bit-map-section pic x value "2".
03 bit-pair-number pic 9(2) comp-x.
03 filler pic 9(2) comp-x value 1.
The values to be set for the fields bit-pair-setting
and bit-pair-number vary according to the function
you want to perform. The required values for these two parameters are
given in each of the descriptions below.
With all x"AF" calls, if an error occurs, set-bit-pairs
is set to the value 255 on return from the call.
The following functions are available using this facility:
These functions are described in the following sections.
Note: The functions Time-out unit selection, Timer reset
selection and Skip concealed fields use a different definition of parameter-block
from that given above. See the descriptions for Select
Time-out Units, Time-out Reset Control
and Skip Concealed Fields later in this
chapter for details.
Enables you to control whether or not the initial contents of fields are predisplayed before any data entry is allowed when an ACCEPT statement is executed. This is also controlled by ACCEPT/DISPLAY option 5 in the Adis Configuration utility. See the section Function Descriptions in the chapter Configuring Enhanced ACCEPT and DISPLAY for more information.
This call overrides any value set in the Adis Configuration utility .
Note: The predisplay of fields defined as fixed-format numeric or numeric-edited cannot be turned off.
The fields in parameter-block should be set as
follows:
bit-pair-number must be set to 76. |
|||||||||
bit-pair-setting should be set to one of the
following values:
|
The following code turns off predisplay of fields for all following ACCEPT operations:
move 76 to bit-pair-number
move 0 to bit-pair-setting
call x"AF" using set-bit-pairs
parameter-block
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 Configuring Enhanced ACCEPT and DISPLAY for more information.
These calls override any settings made in the Adis Configuration utility
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:
|
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
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 Message/Indicator Positions menu in the Adis Configuration utility . See the section The Alter Message/Indicator Positions Menu in the chapter Configuring Enhanced ACCEPT and DISPLAY for more information.
This call overrides any settings made in the Adis Configuration utility. By default, these messages are displayed.
The fields in parameter-block should be set as
follows:
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
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 the Adis Configuration utility. See the section ACCEPT/DISPLAY Options in the chapter Configuring Enhanced ACCEPT and DISPLAY for more information.
This call overrides any settings made in the Adis Configuration utility.
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:
|
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
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:
|
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
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:
|
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
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 the Adis Configuration utility. See the section ACCEPT/DISPLAY Options in the chapter Configuring Enhanced ACCEPT and DISPLAY 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:
|
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
This routine enables you to determine whether the time-out value is interpreted as seconds or tenths of a second.
This can also be controlled using ACCEPT/DISPLAY option 32 in the Adis Configuration utility. See the section ACCEPT/DISPLAY Options in the chapter Configuring Enhanced ACCEPT and DISPLAY for more information.
For this routine, parameter-block should be
defined as follows:
01 parameter-block.
03 bit-pair-setting pic 9(2) comp-x.
03 bit-map-section pic x value "6".
03 bit-pair-number pic 9(2) comp-x.
03 filler pic 9(2) comp-x value 1.
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:
|
The following code specifies that any subsequent time-out 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
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.
This can also be controlled using ACCEPT/DISPLAY option 33 in the Adis Configuration utility. See the section ACCEPT/DISPLAY Options in the chapter Configuring Enhanced ACCEPT and DISPLAY for more information.
For this routine, parameter-block should be
defined as follows:
01 parameter-block.
03 bit-pair-setting pic 9(2) comp-x.
03 bit-map-section pic x value "6".
03 bit-pair-number pic 9(2) comp-x.
03 filler pic 9(2) comp-x value 1.
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:
|
This routine enables you to control circumstances in which you can skip to the following or preceding concealed field during execution of an ACCEPT statement. A concealed field is one which contains the NO-ECHO clause.
This can also be controlled using ACCEPT/DISPLAY option 30 in the Adis Configuration utility. See the section ACCEPT/DISPLAY Options in the chapter Configuring Enhanced ACCEPT and DISPLAY for more information.
For this routine, parameter-block should be
defined as follows:
01 parameter-block.
03 bit-pair-setting pic 9(2) comp-x.
03 bit-map-section pic x value "6".
03 bit-pair-number pic 9(2) comp-x.
03 filler pic 9(2) comp-x value 1.
The fields in parameter-block should be set as
follows:
bit-pair-number must be set to 16 |
|||||
bit-pair-setting should be set to one of the
following values:
|
The following code enables skipping of concealed fields:
move 16 to bit-pair-number
move 1 to bit-pair-setting
call x"AF" using set-bit-pairs
parameter-block
This function enables the initial field contents to be read from the current screen map held by the run-time system, when predisplay is off during an ACCEPT operation.
The fields in parameter-block should be set as
follows:
bit-map-section must be set to 6. |
|||||
bit-pair-setting should be set to one of the
following values:
|
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.
The following subjects are described in this section:
In general, the keys on the keyboard can be split into four groups:
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 Esc, 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 are those keys that are used by Adis during the execution of an ACCEPT statement. This includes the cursor keys, Tab, Backspace, Del and Enter.
Normally, these keys operate as defined during an ACCEPT operation. For example, the <left-arrow> 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 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 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.
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.
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.
This section describes how to use function keys in this COBOL system. It describes the portable method that works on all environments.
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 the parameter is:
key-status |
A three-byte data item in the Working-Storage Section of your program with 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. 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 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 Otherwise, the contents of |
See your Language Reference for more information on the CRT STATUS clause.
There are two cases of normal termination of an ACCEPT. They both return
a value of 0 in key-type:
key-code-1. key-code-1. 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.
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 it does, they should be configured as above. Additionally, the following user function keys might be defined:
| Keystroke
|
User Function Key Number
|
|---|---|
| Shift+F1 through Shift+F10 | 11 through 20 |
| Ctrl+F1 through Ctrl+F10 | 21 through 30 |
| Alt+F1 through Alt+F10 | 31 through 40 |
| Alt+1 through Alt+9 | 41 through 49 |
| Alt+0 | 50 |
| Alt+- | 51 |
| Alt+= | 52 |
| PgUp | 53 |
| PgDn | 54 |
| Ctrl+PgUp | 55 |
| Ctrl+PgDn | 56 |
| Alt+A through Alt+Z | 65 through 90 |
| F11 | 91 |
| F12 | 92 |
| Shift+F11 | 93 |
| Shift+F12 | 94 |
| Ctrl+F11 | 95 |
| Ctrl+F12 | 96 |
| Alt+F11 | 97 |
| Alt+F12 | 98 |
The function keys are defined in your terminfo database. The default function keys depend on your operating system and terminal type, and on some of these shifted function keys are not available. See also the appendix UNIX Key Usage Chart in the Server Express User's Guide.
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, 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 the parameters are:
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 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.
The following code enables the Escape key and function keys F1 and F10, but disables all other user function keys:
* Enable Escape key
move 1 to user-key-setting
move 0 to first-user-key
move 1 to number-of-keys
call x"AF" using set-bit-pairs
user-key-control
* Disable 126 keys starting from key 1
move 0 to user-key-setting
move 1 to first-user-key
move 126 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
If you press an enabled user function key during an ACCEPT operation,
the ACCEPT operation is terminated and the fields in key-status
are set as follows:
| Data Item |
Setting |
|---|---|
key-type |
"1" |
key-code-1 |
Set to the number of the user key that was pressed. |
key-code-2 |
Undefined. |
The following code detects which function key is pressed, assuming that the only enabled function keys are Escape, F1 and F10:
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.
Most of the time, you need to use only the one list of user function keys. However, if you are converting from another dialect of COBOL, you might be in the situation where you 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 handle 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 uses the standard user key list. If you want all programs in your system to use the compatibility key list, you can use the Adis Configuration utility 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 set-bit-pairs and key-list-selection
are defined in the Working-Storage Section of your program as follows:
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.
where key-list-number should be set to one of the
following values:
| 1 | To select the standard user function key list. |
| 2 | To select 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.
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 are not allowed to terminate the ACCEPT operation unless something has been entered into the field.
However, if an enabled user function key is pressed during an ACCEPT operation, it is regarded as an exception and terminates the ACCEPT operation even if the validation clause has not been satisfied. If you do not want function keys to terminate the ACCEPT operation without satisfying validation clauses, you can set ACCEPT/DISPLAY option 9 using the Adis Configuration utility. See the section ACCEPT/DISPLAY Options in chapter Configuring Enhanced ACCEPT and DISPLAY for more information.
As noted in the section Function Keys, the Adis keys are those keys that perform functions within an ACCEPT operation such as cursor movement, delete character, and backspace. However, it is possible to make these keys terminate an ACCEPT operation.
You must appreciate the distinction between the keys that perform the functions, and the functions themselves; there is actually a soft mapping between the keys and the functions they perform. This means that you can change the function that any of the Adis keys perform.
A full list of the functions performed by the Adis keys is given in the section Standard Adis Key Functions in the chapter Configuring Your Keyboard. Functions 0 through 27 are simple functions. Functions 55 through 62 are complex functions which can 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 is specified in the ACCEPT statement.
There are 27 (numbered 0 through 26) Adis keys in UNIX environments. Each key 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 Standard Adis Key Functions in the chapter Configuring Your Keyboard.
You must also be aware that the Adis keys themselves are given names. However, these names are used to distinguish the different keys; it might not necessarily describe the function the key actually performs. The following list gives the names of the keys and the keystrokes required to obtain them. You might have a different configuration for your environment; refer to your Release Notes for details.
| Key Number | Function | Default Key/Keystroke |
|---|---|---|
| 0 | Terminate ACCEPT | Ctrl+J or KEY_ENTER or KEY_RETURN |
| 1 | Terminate program | Ctrl+K |
| 2 | Carriage return (mapped to function 00) | Ctrl+M |
| 3 | Cursor left | KEY_LEFT |
| 4 | Cursor right | KEY_RIGHT |
| 5 | Cursor up | KEY_UP |
| 6 | Cursor down | KEY_DOWN |
| 7 | Home | KEY_HOME |
| 8 | Tab (mapped to function 11) | Ctrl+I or KEY_TAB |
| 9 | Backtab (mapped to function 12) | Ctrl+L or KEY_BACKTAB |
| 10 | End | KEY_LL or Ctrl+O or KEY_END |
| 11 | Next field | Ctrl+N |
| 12 | Previous field | Ctrl+P |
| 13 | Change case | Ctrl+F |
| 14 | Erase character | KEY_BACKSPACE or Ctrl+H |
| 15 | Retype character | Ctrl+R |
| 16 | Insert character | KEY_IC or Ctrl+V |
| 17 | Delete character | KEY_DC or Del |
| 18 | Restore character | Ctrl+U |
| 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 | Ctrl+A |
| 26 | Start of field | Ctrl+W |
| 27 | Move to mouse position | Not applicable |
Note: On some keyboards you can map different functions to the Enter and Return keys. In this case, map the Terminate ACCEPT function to the Enter key, and map the Carriage Return function to the Return key.
To change the UNIX mapping for the Enter and Return keys so that they behave the same as on DOS, Windows and OS/2, use the Keyboard Configuration utility (see the chapter Configuring Your Keyboard). You must first delete all the key mappings for the Terminate ACCEPT function, and then map the Carriage Return function to the Enter and Return keys.
In general, the Adis keys are mapped onto the function of the same name. Therefore, the <left-arrow> key moves the cursor to the left, the Backspace key erases a character and so on.
However, there are some functions that invoke other functions, thereby changing the effect of the key. The functions that invoke other functions are:
| Function |
Invoked Function |
|---|---|
| Carriage Return | Terminate ACCEPT, function 0 |
| Tab | Move to next field, function 11 |
| Backtab | Move to previous field, function 12 |
| Set Insert mode | Insert toggle, function 58 |
This means that when you press Enter on your keyboard, it terminates an ACCEPT operation, because Enter is mapped onto carriage return, and carriage return causes an ACCEPT operation to be terminated.
Note that because functions are mapped, you need to reference keys 11 and 12 in order to enable/disable respectively Adis keys 8 and 9 using the x"AF" call-by-number routine.
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 an ACCEPT operation. This is easy to emulate by simply changing the mapping for key 2 (carriage return) from 0 (terminate ACCEPT) to 11 (move to next field). If you look at the function mappings screen in the Adis Configuration utility for the Microsoft COBOL V2.2 compatibility configuration, you can 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 does not perform any function during an ACCEPT operation.
All of the standard functions described above always perform the same function, regardless of context. For example, the Move to next field function always attempts to move to the next field. However, there are some functions that behave differently depending on the context. These functions are described in the section Special Mapping Functions in the chapter Configuring Your Keyboard, but are summarized here:
| Function Number |
Function Name |
|---|---|
| 55 | RM clear field |
| 56 | RM Backspace |
| 57 | RM Tab |
| 58 | Insert toggle |
| 59 | Replace toggle |
| 60 | Forward Tab |
| 61 | Backward Tab |
| 62 | Restore |
For example, the Set Insert mode key (key number 23) is normally mapped to function 58 (Insert toggle). This means that pressing the Insert key toggles between Insert and Replace mode.
As well as changing the mappings through the Adis Configuration utility, you can do this from an application program using the following call:
call x"AF" using set-map-byte adis-key-mapping
where set-map-byte and adis-key-mapping
are defined in the Working-Storage Section of your program as follows:
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.
where the parameters:
adis-mapping-byte
|
Should be set to the number of the function you wish the key to be mapped to |
adis-key-number
|
Should be set to the number of the key you wish to change |
The following code changes the action of the Backspace key (key number 14) to simply move the cursor to the left (function 3), and changes the Tab key (key number 8) to perform the Tab function (function 8):
* Change mapping of Backspace 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
By default, all of the Adis keys are enabled to perform their defined functions during an ACCEPT operation. However, it is possible to disable the keys or make them act as function keys instead. The call to do this is as follows:
call x"AF" using set-bit-pairs adis-key-control
where set-bit-pairs and adis-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 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.
where the parameters are:
adis-key-setting
|
Defines the action of the keys affected, as follows:
|
||||||||
first-adis-key
|
The number of the first key to be affected. | ||||||||
number-of-adis-keys
|
The number of consecutive keys to be affected. |
If you have set up an Adis key to act as a function key, it terminates
the ACCEPT operation and key-status is returned with
the following values:
| Data Item |
Setting |
|---|---|
key-type |
"2" |
key-code-1 |
Set to the number of the pressed Adis key. This is the number of the key not the number of the function the key has been mapped to. |
key-code-2 |
Undefined. |
The following code sets up Tab and Backtab to act as function keys and the <left-arrow> and <right-arrow> keys to act as function keys if they cause the cursor to leave the field.
* Set up Tab (key 8) and Backtab (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 back tab key was pressed"
end-evaluate
end-if.
In general, a particular key is defined in either the user key list or the Adis key list, but not both. However, there is no reason why you should not define 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 operation, the sequence of actions is as follows:
key-type and
the number of the key in key-code-1.
On some UNIX terminals, you may find that some keys do not function as expected or do not function at all. This could be due to inconsistencies between the system terminfo database, the absolute control sequences generated by some keys and the default full screen ACCEPT/DISPLAY keys in this system (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 either the COBOL or the system terminfo database. See the chapter Terminfo Database and Terminal Devices for more information on the search paths used.
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.
Some terminfo files might be supplied with this system. If so, they are in $COBDIR/terminfo. The Micro Focus Screen Handling Package, libscreen, searches for terminfo files in the following places in order, and stops searching as soon as it finds them:
Solutions to some of the problems you may encounter are listed below:
If this happens, the <left-arrow> takes priority over Backspace. You need to configure an alternate key for Backspace using the Keyboard Configuration utility if you need this function.
If so, the Enter key takes priority over <down-arrow>. You need to configure an alternate key for <down-arrow> using the Keyboard Configuration utility if you need this function.
Some terminfo files might not contain information on function keys. If this is true, you must configure keys for these functions using the Keyboard Configuration utility . See the chapters Starting Animator in your Debugging Handbook and Configuring Your Keyboard in this book for more information.
In order to resolve this, configure the Escape function as escape escape, that is, two escapes. You are then able to use this function by pressing Escape twice.
init_1string
to include the appropriate sequences. See the chapter
Terminfo
Database and Terminal Devices in your Server Express
User's Guide for more information. See your terminal manual for
further details on escape sequences. On network-based UNIX 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.
Server Express provides you with the COBKEYTIMEOUT environment variable, which you can use to determine the time-out 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 the appendix Micro Focus Environment Variables in your Server Express User's Guide for details on setting COBKEYTIMEOUT.
The time-out period, a value in the range 1 through 126, 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 results in incorrect function and special key recognition; too large a value results 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 outside the range 1 to 126, null, non-integer or the variable 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.
The data keys are the 256 keys in the extended ASCII character set. Normally, when you press one of these keys during an ACCEPT operation, the character is simply put straight into the field. However, the keys with ASCII codes in the range 0 to 31 - the control keys - are an exception to this; these are generally disabled.
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 operation. To do this, use the following call:
call x"AF" using set-bit-pairs data-key-control
where set-bit-pairs and data-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 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:
|
||||||
first-data-key
|
The first character to be affected. | ||||||
number-of-data-keys
|
The number of characters to be affected. |
If a data key has been set up to act as a function key, it terminates
the ACCEPT operation when pressed, and key-status is
set up as follows:
| Data Item |
Setting |
|---|---|
key-type |
"3" |
key-code-1 |
Set to the ASCII code of the key that was pressed. |
key-code-2 |
Undefined. |
* Set up the characters "A" through "Z" to terminate the
* ACCEPT operation
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.
Adis provides a number of routines to enable an application to make use of the shift key capabilities of a keyboard. These routines are described in the following sections.
Most UNIX terminals cannot detect when the Alt or Ctrl keys are pressed 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 the appendix UNIX Key Usage Chart in your Server Express User's Guide for further details.
This routine enables you to find out which of the shift keys are detectable as unique events.
Use the following call to determine which shift keys are available to your program:
call x"AF" using adis-function adis-parameter
where adis-function and adis-parameter
are defined in the Working-Storage Section of your program as follows:
01 adis-function pic 9(2) comp-x. 01 adis-parameter pic 9(4) comp-x.
where the parameters are:
adis-function |
Must be 44. | ||||||||||||||
adis-parameter |
Returns which shift keys are available to your
program. The 16 bits in adis-parameter refer to
shift keys as follows, with bit 0 the least significant:
|
||||||||||||||
A value of 1 for any particular bit indicates that the associated key is uniquely detectable.
This routine enables you to determine which, if any, of the shift keys are currently pressed.
Use the following call to determine which of the shift keys are currently pressed:
call x"AF" using adis-function adis-parameter
where adis-function and adis-parameter
are defined in the Working-Storage Section of your program as follows:
01 adis-function pic 9(2) comp-x. 01 adis-parameter pic 9(4) comp-x.
where the parameters are:
adis-function |
Must be 46. | ||||||||||||
adis-parameter |
Returns which of the shift keys are currently pressed.
The 16 bits in adis-parameter refer to shift keys
as follows, with bit 0 the least significant:
|
A value of 1 for any particular bit indicates that the associated key is currently pressed.
By default, all of the shift keys are disabled during an ACCEPT operation, or the x"AF" call used to obtain a key. However, this routine enables you to enable or disable the shift keys dynamically.
Use the following call to enable or disable shift keys:
call x"AF" using adis-function adis-parameter
where adis-function and adis-parameter
are defined in the Working-Storage Section of your program as follows:
01 adis-function pic 9(2) comp-x.
01 adis-parameter.
03 shift-key-setting pic 9(2) comp-x.
03 filler pic x value "4".
03 first-shift-key pic 9(2) comp-x.
03 number-of-shift-keys pic 9(2) comp-x.
where:
adis-function |
Must be 1. | ||||
shift-key-setting
|
Defines the action of the keys affected, as follows:
|
||||
first-shift-key
|
The number of the first key to be affected. The events
to enable are numbered as follows:
0 - Alt pressed |
||||
number-of-shift-keys
|
The number of consecutive keys to be affected. |
The following code enables Ctrl so that it can terminate an ACCEPT operation, then checks to see whether an ACCEPT operation was terminated by Ctrl:
* Enable Ctrl
move 1 to shift-key-setting
move 2 to first-shift-key
move 1 to number-of-shift-keys
move 1 to adis-function
call x"AF" using adis-function
adis-parameter
accept data-item at 0101
if key-type = "5"
evaluate key-code-1
when 2
display "Ctrl pressed"
when other
display "Other shift key pressed"
end-evaluate
end-if.
Adis provides a number of routines to enable an application to make use of the lock key capabilities of a keyboard. These routines are described in the following sections.
This routine enables you to find out which of the lock keys are detectable as unique events.
Use the following call to determine which lock keys are available to your program:
call x"AF" using adis-function adis-parameter
where adis-function and adis-parameter
are defined in the Working-Storage Section of your program as follows:
01 adis-function pic 9(2) comp-x. 01 adis-parameter pic 9(4) comp-x.
where the parameters:
adis-function |
Must be 45. | ||||||||||||
adis-parameter |
Returns which lock keys are available to your program. The 16 bits
in adis-parameter refer to lock keys as follows,
with bit 0 the least significant:
|
A value of 1 for any particular bit indicates that the associated key is uniquely detectable.
This routine enables you to determine which, if any, of the lock keys are currently active. For example, the Scroll Lock key is active when scroll lock is on.
Use the following call to determine which of the lock keys are currently active:
call x"AF" using adis-function adis-parameter
where adis-function and adis-parameter
are defined in the Working-Storage Section of your program as follows:
01 adis-function pic 9(2) comp-x. 01 adis-parameter pic 9(4) comp-x.
where the parameters are:
adis-function |
Must be 47 | ||||||||||||
adis-parameter |
Returns which of the lock keys are currently active.
The 16 bits in adis-parameter refer to lock keys
as follows, with bit 0 the least significant:
|
A value of 1 for any particular bit indicates that the associated key is currently active.
By default, all of the lock keys are disabled during an ACCEPT operation, or the x"AF" call used to obtain a key. However, this routine enables you to enable or disable the lock keys dynamically.
Use the following call to enable or disable lock keys:
call x"AF" using adis-function
adis-parameter
where adis-function and adis-parameter
are defined in the Working-Storage Section of your program as follows:
01 adis-function pic 9(2) comp-x.
01 adis-parameter.
03 lock-key-setting pic 9(2) comp-x.
03 filler pic x value "5".
03 first-lock-key pic 9(2) comp-x.
03 number-of-lock-keys pic 9(2) comp-x.
where the parameters are:
adis-function |
Must be 1. | ||||||||
lock-key-setting
|
Defines the action of the keys affected, as follows:
|
||||||||
first-lock-key |
The number of the first key to be affected. The keys
to enable are numbered as follows:
|
||||||||
number-of-lock-keys
|
The number of consecutive keys to be affected. |
This routine enables 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 call used is:
call x"AF" using get-single-char-func key-status
where get-single-char-func and key-status
are defined in the Working-Storage Section of your program as follows:
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 carriage
return 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. 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. This
is only applicable on machines that support double-byte characters.
|
||||
| "5" | The number of the shift key pressed. | ||||
| "6" | The number of the lock key pressed. | ||||
| "9" | Error condition. Values are:
|
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 "5"
* Shift key pressed/released. Do required action
* depending on
* value in key-code-1
when "6"
* Lock key state changed. Do required action
* depending on value in key-code-1
when "9"
* Invalid or disabled key. Do required action.
end-evaluate.
The following is an example of how to write programs that make use of function keys. It assumes that Escape is available, but any other function key can be selected either by pressing the function key or by pressing a slash (/) followed by the first letter of the option.
$set ans85
**************************************************
* This program assumes that the default
* configuration has been selected using Adis
* Configuration utility.
***************************************************
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 value 0. 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 highlightprompt " ".
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 operation.
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"
* The ACCEPT operation terminated normally; that is the
* Enter key was pressed. In this case, we simply blank out
* the work areas and restart in the first field.
initialize 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 * Escape or F1 as all others have been disabled.
* 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 operation. 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.
if key-code-1 = 0
Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
| Low-level Routines for Character Interfaces | Configuring Enhanced ACCEPT and DISPLAY | |