Overview of Character User Interface Methods | Adis |
The COBOL library routines enable you to paint characters and attributes to a character screen and read keys pressed on the keyboard.
This chapter lists the routines available and describes them in detail.
The COBOL system call-by-name library routines (those of the form CBL_name_name) use type definitions and COBOL CALL prototypes; this helps you to ensure that all calls to these routines are valid. For further information see the section Using the Library Routine TYPEDEFs and CALL Prototypes in the chapter Library Routines in your Programmer's Guide to Writing Programs. The call-by-number library routines (those of the form x"XX" do not use CALL prototypes.
To ensure that the type definitions and CALL protoypes are used by your program, you should include the copyfile $COBDIR/cpylib/cblproto.cpy in your program. cblproto.cpy must be copied before the Identification Division of the program being compiled.
The following sections list the available routines and briefly describe them.
CBL_CLEAR_SCR | Clears screen |
CBL_GET_CSR_POS | Gets cursor position |
CBL_GET_SCR_SIZE | Gets screen size |
CBL_READ_SCR_ATTRS | Reads attribute string |
CBL_READ_SCR_CHARS | Reads character string |
CBL_READ_SCR_CHATTRS | Reads character and attribute strings |
CBL_SET_CSR_POS | Sets cursor position |
CBL_SWAP_SCR_CHATTRS | Swaps character and attribute |
CBL_WRITE_SCR_ATTRS | Writes attribute string |
CBL_WRITE_SCR_CHARS | Writes character string |
CBL_WRITE_SCR_CHARS_ATTR | Writes character string with attribute |
CBL_WRITE_SCR_CHATTRS | Writes character and attribute strings |
CBL_WRITE_SCR_N_ATTR | Repeats write attribute |
CBL_WRITE_SCR_N_CHAR | Repeats write character |
CBL_WRITE_SCR_N_CHATTR | Repeats write character and attributes |
CBL_WRITE_SCR_TTY | Writes characters TTY-style |
X"A7" function 25 | Gets screen type |
X"AF" function 1 | Configures Adis |
X"AF" function 18 | Displays character |
X"AF" function 22 | Sounds alarm |
X"AF" function 26 | Gets character |
X"E5" | Sound bell |
A number of the screen routines specify the screen-position parameter. In this COBOL system, the top left corner of the screen is row 0, column 0. For example, if you want to change attributes beginning in row 5, column 8, you specify row-number as 4 and column-number as 7.
Before using the X"A7" routine for screen handling, use the CBL_CLEAR_SCR routine.
CBL_GET_KBD_STATUS | Tests for character at keyboard |
CBL_READ_KBD_CHAR | Reads character from keyboard (no echo) |
X"B0" function 4 | Disables keyboard interrupts |
Clears the whole screen to a specified character and attribute.
call "CBL_CLEAR_SCR" using character attribute returning status-code
character
cblt-x1-compx. attribute
cblt-x1-compx. status-code
See
Key
in the Preface
character |
The character to write. |
attribute |
The attribute to write. |
None
Returns the cursor position.
call "CBL_GET_CSR_POS" using screen-position returning status-code
screen-position |
A group item predefined as cblt-screen-position ,
containing the following subordinate items:
|
||||||
status-code |
See Key in the Preface |
None
screen-position |
The screen position of the cursor. The top left corner is row 0, column 0. If the cursor is invisible, row-number and column-number are both set to 255. See Screen Routines. |
Checks whether there is a character waiting to be read from the keyboard.
call "CBL_GET_KBD_STATUS" using key-status returning status-code
key-status
cblt-x1-compx. status-code
See
Key in the Preface.
None
key-status |
The status of the keyboard:
|
Some UNIX implementations do not allow you to poll the keyboard in this way. See the documentation supplied with your UNIX system to determine if this is the case in your implementation.
This routine should be preceded by an enhanced ACCEPT or DISPLAY statement (see the chapter Adis) or by calling one of the CBL_ display routines (in this chapter). Otherwise, the behavior is undefined.
Returns information about the size of the screen.
call "CBL_GET_SCR_SIZE" using depth width returning status-code
depth
cblt-x1-compx. width
cblt-x1-compx.
See
Key in the Preface.
status-code
None
depth |
Number of lines. |
width |
Number of columns. |
Waits until a character is typed and then reads it with no echo.
call "CBL_READ_KBD_CHAR" using char returning status-code
char |
cblt-x1-compx. |
status-code |
See Key in the Preface. |
None
char |
The character that was typed, in ASCII. |
This routine should be preceded by an enhanced ACCEPT or DISPLAY statement (see the chapter Adis) or by calling one of the CBL_ display routines (in this chapter). Otherwise, the behavior is undefined.
Reads a string of attributes from the screen.
call "CBL_READ_SCR_ATTRS" using screen-position attribute-buffer string-length returning status-code
screen-position | A group item predefined as cblt-screen-position ,
containing the following subordinate items:
|
||||||
attribute-buffer |
pic x(n). | ||||||
string-length |
cblt-x2-compx. | ||||||
status-code |
See Key
in the Preface |
screen-position |
The screen position to start reading at. The top left corner is row 0, column 0. See Screen Routines. |
string-length |
The length of the string to read. |
attribute-buffer |
The attributes read from the screen. This data item must be at least as long as specified by string-length; positions in it beyond that length are unchanged. |
string-length |
If the end of the screen is reached the length read is returned in here. |
Reads a string of characters from the screen.
call "CBL_READ_SCR_CHARS" using screen-position character-buffer string-length returning status-code
screen-position |
A group item predefined as cblt-screen-position ,
containing the following subordinate items:
|
||||||
attribute-buffer |
pic x(n). | ||||||
string-length |
cblt-x2-compx. | ||||||
status-code |
See Key
in the Preface |
character-buffer
pic x(n). string-length
pic
x(2) comp-x. status-code
See
Key
screen-position |
The screen position to start reading at. The top left corner is row 0, column 0. See Screen Routines. |
string-length |
The length of the string to read. |
character-buffer |
The characters read from the screen. This data item must be at least as long as specified by string-length; positions in it beyond that length are unchanged. |
string-length |
If the end of the screen is reached, the length read is returned in here. |
Reads a string of characters and their attributes from the screen.
call "CBL_READ_SCR_CHATTRS" using screen-position character-buffer attribute-buffer string-length returning status-code
screen-position |
A group item predefined as cblt-screen-position ,
containing the following subordinate items:
|
||||||
character-buffer |
|||||||
string-length |
cblt-x2-compx. | ||||||
status-code |
See Key
in the Preface |
screen-position |
The screen position to start reading at. The top left corner is row 0, column 0. See Screen Routines. |
string-length |
The length of the string to read. |
character-buffer |
The characters read from the screen. This data item must be at least as long as specified by string-length; positions in it beyond that length are unchanged. |
attribute-buffer |
The attributes read from the screen. This data item must be at least as long as specified by string-length; positions in it beyond that length are unchanged. |
string-length |
If the end of the screen is reached, the length read (in cells, that is, character-attribute pairs) is returned in here. |
Moves the cursor.
call "CBL_SET_CSR_POS" using screen-position returning status-code
screen-position |
A group item predefined as cblt-screen-position ,
containing the following subordinate items:
|
||||||
status-code |
See Key
in the Preface |
screen-position |
The screen position at which to put the cursor. The top left corner is row 0, column 0. See Screen Routines. |
None
Swaps a string of characters and their attributes with a string from the screen.
call "CBL_SWAP_SCR_CHATTRS" using screen-position character-buffer attribute-buffer string-length returning status-code
screen-position |
A group item predefined as cblt-screen-position ,
containing the following subordinate items:
|
||||||
character-buffer |
pic x(n). | ||||||
attribute-buffer |
pic x(n). | ||||||
string-length |
cblt-x2-compx. | ||||||
status-code |
See Key
in the Preface |
screen-position |
The screen position at which to start writing. The top left corner is row 0, column 0. See Screen Routines. |
character-buffer |
The characters to write. |
attribute-buffer |
The attributes to write. |
string-length |
The length of the string to write. If this would go off the end of the screen, the write finishes at the end of the screen. |
character-buffer |
The characters read from the screen. This data item must be at least as long as specified by string-length; positions in it beyond that length are unchanged. |
attribute-buffer |
The attributes read from the screen. This data item must be at least as long as specified by string-length; positions in it beyond that length are unchanged. |
string-length |
If the end of the screen is reached the length swapped (in cells, that is, character-attribute pairs) is returned in here. |
Writes a string of attributes to the screen.
call "CBL_WRITE_SCR_ATTRS" using screen-position attribute-buffer string-length returning status-code
screen-position |
A group item predefined as cblt-screen-position ,
containing the following subordinate items:
|
||||||
attribute-buffer |
pic x(n). | ||||||
string-length |
cblt-x2-compx. | ||||||
status-code |
See Key
in the Preface |
None
Writes a string of characters to the screen.
call "CBL_WRITE_SCR_CHARS" using screen-position character-buffer string-length returning status-code
screen-position |
A group item predefined as cblt-screen-position ,
containing the following subordinate items:
|
||||||
character-buffer |
pic x(n). | ||||||
string-length |
cblt-x2-compx. | ||||||
status-code |
See Key
in the Preface |
screen-position |
The screen position at which to start writing. The top left corner is row 0, column 0. See Screen Routines |
character-buffer |
The characters to write. |
string-length |
The length of the string to write. If this would go off the end of the screen, the write finishes at the end of the screen. |
None
Writes a string of characters to the screen, giving them all the same attribute.
call "CBL_WRITE_SCR_CHARS_ATTR" using screen-position character-buffer string-length attribute returning status-code
screen-position |
A group item predefined as cblt-screen-position ,
containing the following subordinate items:
|
||||||
character-buffer |
pic x(n). | ||||||
string-length |
cblt-x2-compx. | ||||||
attribute |
cblt-x1-compx. | ||||||
status-code |
See Key
in the Preface |
screen-position |
The screen position at which to start writing. The top left corner is row 0, column 0. See Screen Routines. |
character-buffer |
The characters to write. |
attribute |
The attribute to write. |
string-length |
The length of the string to write. If this would go off the end of the screen, the write finishes at the end of the screen. |
None
Writes a string of characters and their attributes to the screen.
call "CBL_WRITE_SCR_CHATTRS" using screen-position character-buffer attribute-buffer string-length returning status-code
screen-position |
A group item predefined as cblt-screen-position ,
containing the following subordinate items:
|
||||||
character-buffer |
pic x(n). | ||||||
attribute-buffer |
pic x(n). | ||||||
string-length |
cblt-x2-compx. | ||||||
status-code |
See Key
in the Preface |
screen-position |
The screen position at which to start writing. The top left corner is row 0, column 0. See Screen Routines |
character-buffer |
The characters to write. |
attribute-buffer |
The attributes to write. |
string-length |
The length of the string to write. If this would go off the end of the screen, the write finishes at the end of the screen. |
None
Writes a specified attribute to a string of positions on the screen.
call "CBL_WRITE_SCR_N_ATTR" using screen-position attribute fill-length returning status-code
screen-position |
A group item predefined as cblt-screen-position ,
containing the following subordinate items:
|
||||||
|
cblt-x1-compx. | ||||||
fill-length |
cblt-x2-compx. | ||||||
status-code |
See Key
in the Preface |
screen-position |
The screen position at which to start writing. The top left corner is row 0, column 0. See Screen Routines |
attribute |
The attribute to write. |
string-length |
The number of screen positions to write the attribute to. If this would go off the end of the screen, the write finishes at the end of the screen. |
None
Writes a specified character to a string of positions on the screen.
call "CBL_WRITE_SCR_N_CHAR" using screen-position character fill-length returning status-code
screen-position |
A group item predefined as cblt-screen-position ,
containing the following subordinate items:
|
||||||
|
cblt-x1-compx. | ||||||
fill-length |
cblt-x2-compx. | ||||||
status-code |
See Key
in the Preface |
screen-position |
The screen position at which to start writing. The top left corner is row 0, column 0. See Screen Routines. |
attribute-buffer |
The attributes to write. |
string-length |
The number of screen positions to write the character to. If this would go off the end of the screen, the write finishes at the end of the screen. |
None
Writes a specified character and attribute to a string of positions on the screen.
call "CBL_WRITE_SCR_N_CHATTR" using screen-position character attribute fill-length returning status-code
screen-position |
A group item predefined as cblt-screen-position ,
containing the following subordinate items:
|
||||||
|
cblt-x1-compx. | ||||||
attribute |
cblt-x1-compx. | ||||||
fill-length |
cblt-x2-compx. | ||||||
status-code |
See Key
in the Preface |
screen-position |
The screen position at which to start writing. The top left corner is row 0, column 0. See Screen Routines. |
character |
The character to write. |
attribute |
The attribute to write. |
string-length |
The number of screen positions to write the character-attribute pair to. If this would go off the end of the screen, the write finishes at the end of the screen. |
None
Writes a string of characters to the screen starting at the current position and scrolling.
call "CBL_WRITE_SCR_TTY" using character-buffer string-length returning status-code
character-buffer |
pic x(n). |
string-length |
cblt-x2-compx. |
status-code |
See Key in the Preface |
character-buffer |
The characters to write. |
string-length |
The length of the string to write. If this would go off the edge of the screen, the screen is scrolled up a line and the write continues on the bottom line. |
None
Returns the current screen type as recognized by the run-time system.
call x"A7" using function-code parameter
function-code |
pic x comp-x. |
parameter |
pic x comp-x. |
function-code |
Value 25 |
parameter |
Bit settings indicating the type of screen as follows:
|
Before using this routine, use the CBL_CLEAR_SCR routine, to prevent possible errors.
Sets various configurable features of Adis, including enabling or disabling individual user function, Adis or data keys, or a series of consecutive keys at run time.
call x"AF" using function-code parameter-block
function-code
pic
x comp-x parameter-block
Group
item defined as: key-setting
pic
x comp-x sub-fn-code
pic
x comp-x first-key-id
pic
x comp-x number-of-keys
pic
x comp-x
function-code |
Value 1 | ||||||||||
sub-fn-code |
One of:
|
Features are enabled or disabled until explicitly changed by another call to x"AF" or until the application terminates. The initial state of user function keys depends on the run-time operating system (see the chapter Adis for details). Calls to enable or disable functions keys are additive. For example, if you call x"AF" to enable function key F1 and then make another call to enable F10, both keys are enabled.
The chapter Adis describes the features and parameter in detail.
Before using this routine, use the CBL_CLEAR_SCR routine, to prevent possible errors.
Displays a character at the current cursor position.
call x"AF" using function-code char
function-code |
pic x comp-x |
char |
pic x |
function-code |
Value 18 |
char |
The character to be displayed. |
None
Before using this routine, use the CBL_CLEAR_SCR routine, to prevent possible errors.
Sounds the terminal alarm.
call x"AF" using function-code parameter
function-code |
pic x comp-x |
parameter |
pic x |
function-code |
Value 22. |
parameter |
Reserved |
None
Gets a character from the keyboard.
call x"AF" using function-code key-status
function-code
pic
x comp-x key-status
Group
item defined as: key-type
pic
x. key-code-1
pic
x comp-x. key-code-2
pic
x comp-x.
function-code |
Value 26 |
key-type |
The type of key read, as follows:
|
||||||||
key-code-1 |
When key-type is 1 or 2, contains the number
of the key; 0 through 127 for user-defined and 0 through 39 for Adis.
See the chapter Configuring
Enhanced Accept and Display for more details on function keys.
When key-type is 3, contains the ASCII code of the key pressed When key-type is 9, contains an error code:
|
This routine also causes the COBOL screen handling system to be invoked. See the chapter Comparison of Screen Handling Methods for details.
Before using this routine, use the CBL_CLEAR_SCR routine, to prevent possible errors.
Disables keyboard interrupts.
call X"B0" using function-code parameter
function-code |
pic x comp-x. |
parameter |
pic x comp-x. |
function-code |
Value 4. |
parameter |
Value 1. |
None
This routine disables keyboard interrupts for the rest of the application. It should be called before any subprograms are called.
This function has the same effect as the -i run-time switch.
Sounds the bell.
call x"E5"
None
The duration and pitch of the bell depends on the environment.
Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
Overview of Character User Interface Methods | Adis |