PreviousOverview of Character User Interface Methods AdisNext

Chapter 3: Low-level Routines for Character Interfaces

The COBOL library routinesenable 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.

3.1 Overview

The following sections list the available routines and briefly describe them.

3.1.1 Screen Routines

CBL_CLEAR_SCR Clear screen
CBL_GET_CSR_POS Get cursor position
CBL_GET_SCR_SIZE Get screen size
CBL_READ_SCR_ATTRS Read attribute string
CBL_READ_SCR_CHARS Read character string
CBL_READ_SCR_CHATTRS Read character & attribute strings
CBL_SET_CSR_POS Set cursor position
CBL_SWAP_SCR_CHATTRS Swap character & attribute
CBL_WRITE_SCR_ATTRS Write attribute string
CBL_WRITE_SCR_CHARS Write character string
CBL_WRITE_SCR_CHARS_ATTR Write character string with attribute
CBL_WRITE_SCR_CHATTRS Write character & attribute strings
CBL_WRITE_SCR_N_ATTR Repeat write attribute
CBL_WRITE_SCR_N_CHAR Repeat write character
CBL_WRITE_SCR_N_CHATTR Repeat write character & attributes
CBL_WRITE_SCR_TTY Write characters TTY-style
X"A7" function 25 Get Screen Type
X"AF" function 1 Configure Adis
X"AF" function 18 Display Character
X"AF" function 22 Sound Alarm
X"AF" function 26 Get 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 any of the X"A7" routines for screen handling, use the CBL_CLR_SCR routine.

3.1.2 Keyboard Routines

CBL_GET_KBD_STATUS Test for character at keyboard
CBL_READ_KBD_CHAR Read character from keyboard (no echo)
X"B0" function 4 Disable Keyboard Interrupts

3.2 Description of Routines


CBL_CLEAR_SCR

Clears the whole screen to a specified character and attribute.

Syntax:
call "CBL_CLEAR_SCR"   using     character 
                                 attribute 
                       returning status-code
Parameters:

character           pic x.
attribute           pic x.
status-code         See Key

On Entry:
character The character to write.
attribute The attribute to write.
On Exit:

None


CBL_GET_CSR_POS

Returns the cursor position.

Syntax:
call "CBL_GET_CSR_POS" using     screen-position 
                       returning status-code
Parameters:

screen-position     Group item defined as:
    row-number          pic x comp-x.
    column-number       pic x comp-x.
status-code         See Key

On Entry:

None

On Exit:
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.

CBL_GET_KBD_STATUS

Checks whether there is a character waiting to be read from the keyboard.

Syntax:
call "CBL_GET_KBD_STATUS" using     key-status 
                          returning status-code
Parameters:

key-status          pic x comp-x.
status-code         See Key

On Entry:

None

On Exit:
key-status The status of the keyboard:

0 No character available
1 Character available
Comments:

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 ADIS ACCEPT or DISPLAY statement (see the Adis chapter) or by calling one of the CBL_ display routines (in this chapter). Otherwise, the behavior is undefined.


CBL_GET_SCR_SIZE

Returns information about the size of the screen.

Syntax:
call "CBL_GET_SCR_SIZE" using     depth 
                                  width 
                        returning status-code
Parameters:

depth               pic x comp-x.
width               pic x comp-x.
status-code         See Key

On Entry:

None

On Exit:
depth Number of lines.
width Number of columns.

CBL_READ_KBD_CHAR

Waits until a character is typed and then reads it with no echo.

Syntax:
call "CBL_READ_KBD_CHAR" using     char 
                         returning status-code
Parameters:

char                pic x.
status-code         See Key

On Entry:

None

On Exit:

char The character that was typed, in ASCII.
Comments:

This routine should be preceded by an ADIS ACCEPT or DISPLAY statement (see the Adis chapter) or by calling one of the CBL_ display routines (in this chapter). Otherwise, the behavior is undefined.


CBL_READ_SCR_ATTRS

Reads a string of attributes from the screen.

Syntax:
call "CBL_READ_SCR_ATTRS" using     screen-position 
                                    attribute-buffer 
                                    string-length 
                          returning status-code
Parameters:

screen-position     Group item defined as:
    row-number          pic x comp-x.
    column-number       pic x comp-x.
attribute-buffer    pic x(n).
string-length       pic x(2) comp-x.
status-code         See Key

On Entry:
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.
On Exit:
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.

CBL_READ_SCR_CHARS

Reads a string of characters from the screen.

Syntax:
call "CBL_READ_SCR_CHARS" using     screen-position 
                                    character-buffer 
                                    string-length 
                          returning status-code
Parameters:

screen-position     Group item defined as:
    row-number          pic x comp-x.
    column-number       pic x comp-x.
character-buffer    pic x(n).
string-length       pic x(2) comp-x.
status-code         See Key

On Entry:
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.
On Exit:
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.

CBL_READ_SCR_CHATTRS

Reads a string of characters and their attributes from the screen.

Syntax:
call "CBL_READ_SCR_CHATTRS" using    screen-position 
                                     character-buffer 
                                     attribute-buffer 
                                     string-length 
                           returning status-code
Parameters:

screen-position     Group item defined as:
    row-number          pic x comp-x.
    column-number       pic x comp-x.
character-buffer    pic x(n).
attribute-buffer    pic x(n).
string-length       pic x(2) comp-x.
status-code         See Key

On Entry:
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.
On Exit:
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.

CBL_SET_CSR_POS

Moves the cursor.

Syntax:
call "CBL_SET_CSR_POS" using     screen-position 
                       returning status-code
Parameters:

screen-position     Group item defined as:
    row-number          pic x comp-x.
    column-number       pic x comp-x.
status-code         See Key

On Entry:
screen-position The screen position at which to put the cursor. The top left corner is row 0, column 0. See Screen Routines.
On Exit:

None


CBL_SWAP_SCR_CHATTRS

Swaps a string of characters and their attributes with a string from the screen.

Syntax:
call "CBL_SWAP_SCR_CHATTRS" using    screen-position 
                                     character-buffer 
                                     attribute-buffer 
                                     string-length 
                           returning status-code
Parameters:

screen-position     Group item defined as:
    row-number          pic x comp-x.
    column-number       pic x comp-x.
character-buffer    pic x(n).
attribute-buffer    pic x(n).
string-length       pic x(2) comp-x.
status-code         See Key

On Entry:
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.
On Exit:
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.
See also:

Screen Routines


CBL_WRITE_SCR_ATTRS

Writes a string of attributes to the screen.

Syntax:
call "CBL_WRITE_SCR_ATTRS" using     screen-position 
                                     attribute-buffer 
                                     string-length 
                           returning status-code
Parameters:

screen-position     Group item defined as:
    row-number          pic x comp-x.
    column-number       pic x comp-x.
attribute-buffer    pic x(n).
string-length       pic x(2) comp-x.
status-code         See Key

On Exit:

None

See also:

Screen Routines


CBL_WRITE_SCR_CHARS

Writes a string of characters to the screen.

Syntax:
call "CBL_WRITE_SCR_CHARS" using     screen-position 
                                     character-buffer 
                                     string-length 
                           returning status-code
Parameters:

screen-position     Group item defined as:
    row-number          pic x comp-x.
    column-number       pic x comp-x.
character-buffer    pic x(n).
string-length       pic x(2) comp-x.
status-code         See Key

On Entry:
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.
On Exit:

None

See also:

Screen Routines


CBL_WRITE_SCR_CHARS_ATTR

Writes a string of characters to the screen, giving them all the same attribute.

Syntax:
call "CBL_WRITE_SCR_CHARS_ATTR" 
                           using     screen-position 
                                     character-buffer 
                                     string-length 
                                     attribute 
                           returning status-code
Parameters:

screen-position     Group item defined as:
    row-number          pic x comp-x.
    column-number       pic x comp-x.
character-buffer    pic x(n).

string-length       pic x(2) comp-x.
attribute           pic x.

status-code         See Key

On Entry:
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.
On Exit:

None

See also:

Screen Routines


CBL_WRITE_SCR_CHATTRS

Writes a string of characters and their attributes to the screen.

Syntax:
call "CBL_WRITE_SCR_CHATTRS" using   screen-position 
                                     character-buffer 
                                     attribute-buffer 
                                     string-length 
                           returning status-code
Parameters:

screen-position     Group item defined as:
    row-number          pic x comp-x.
    column-number       pic x comp-x.
character-buffer    pic x(n).
attribute-buffer    pic x(n).
string-length       pic x(2) comp-x.
status-code         See Key

On Entry:
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.
On Exit:

None

See also:

Screen Routines


CBL_WRITE_SCR_N_ATTR

Writes a specified attribute to a string of positions on the screen.

Syntax:
call "CBL_WRITE_SCR_N_ATTR" using     screen-position 
                                      attribute 
                                      fill-length 
                            returning status-code
Parameters:

screen-position     Group item defined as:
    row-number          pic x comp-x.
    column-number       pic x comp-x.
attribute           pic x.
fill-length         pic x(2) comp-x.
status-code         See Key

On Entry:
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.
On Exit:

None

See also:

Screen Routines


CBL_WRITE_SCR_N_CHAR

Writes a specified character to a string of positions on the screen.

Syntax:
call "CBL_WRITE_SCR_N_CHAR" using     screen-position 
                                      character 
                                      fill-length 
                            returning status-code
Parameters:

screen-position     Group item defined as:
    row-number          pic x comp-x.
    column-number       pic x comp-x.
character           pic x.
fill-length         pic x(2) comp-x.
status-code         See Key

On Entry:
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.
On Exit:

None

See also:

Screen Routines


CBL_WRITE_SCR_N_CHATTR

Writes a specified character and attribute to a string of positions on the screen.

Syntax:
call "CBL_WRITE_SCR_N_CHATTR" using   screen-position 
                                      character 
                                      attribute 
                                      fill-length 
                            returning status-code
Parameters:

screen-position     Group item defined as:
    row-number          pic x comp-x.
    column-number       pic x comp-x.
character           pic x.
attribute           pic x.
fill-length         pic x(2) comp-x.
status-code         See Key

On Entry:
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.
On Exit:

None

See also:

Screen Routines


CBL_WRITE_SCR_TTY

Writes a string of characters to the screen starting at the current position and scrolling.

Syntax:
call "CBL_WRITE_SCR_TTY" using     character-buffer 
                                   string-length 
                         returning status-code
Parameters:

character-buffer    pic x(n).
string-length       pic x(2) comp-x.
status-code         See Key

On Entry:
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.
On Exit:

None


X"A7" function 25 - Get Screen Type

Returns the current screen type as recognized by the run-time system.

Syntax:
call x"A7" using function-code 
                 parameter
Parameters:

function-code       pic x comp-x.
parameter           pic x comp-x.

On Entry:
function-code Value 25
On Exit:
parameter Bit settings indicating the type of screen as follows:

bit 0 unset = monochrome screen
bit 1 reserved
bit 2 reserved
bit 3 set = EGA-type screen
bit 4 set = VGA-type screen
bit 5 reserved
bit 6 reserved
bit 7 reserved
Comments:

Before using this routine, use the CBL_CLEAR_SCR routine, to prevent possible errors.


X"AF" function 1 - Configure Adis

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.

Syntax:
call x"AF" using function-code 
                 parameter-block
Parameters:

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

On Entry:
function-code Value 1
sub-fn-code One of:

1 Enable/disable user function keys and compatibility keys
2 Enable/disable Adis control keys and other configurables
3 Enable/disable data keys
4 Enable/disable shift keys
5 Enable/disable lock keys
Comments:

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.


X"AF" function 18 - Display Character

Displays a character to the screen at the current cursor position.

Syntax:
call x"AF" using function-code 
                 char
Parameters:

function-code       pic x comp-x
char                pic x

On Entry:
function-code Value 18
char The character to be displayed.
On Exit:

None

Comments:

Before using this routine, use the CBL_CLEAR_SCR routine, to prevent possible errors.

See also:

Screen Routines


X"AF" function 22 - Sound Alarm

Sounds the terminal alarm.

Syntax:
call x"AF" using function-code 
                 parameter
Parameters:

function-code       pic x comp-x
parameter           pic x

On Entry:
function-code Value 22.
parameter Reserved
On Exit:

None

See also:

Screen Routines


X"AF" function 26 - Get Character

Gets a character from the keyboard.

Syntax:
call x"AF" using function-code 
                 key-status
Parameters:

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.

On Entry:
function-code Value 26
On Exit:
key-type The type of key read, as follows:

1 user-defined function key
2 Adis function key
3 Data key
9 Error
key-code-1 When key-type is 1 or 2, contains the number of the key; 0-127 for user-defined and 0-39 for Adis. See the chapter Adis Configuration Utility (AdisCF) 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:

8 A disabled character has been keyed, and key-code-2 contains the character.
9 An invalid keystroke (more than one byte) has occurred.

Comments:

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.

See also:

Screen Routines


X"B0" function 4 - Disable Keyboard Interrupts

Disables keyboard interrupts.

Syntax:
call X"B0" using function-code 
                 parameter
Parameters:

function-code       pic x comp-x.
parameter           pic x comp-x.

On Entry:
function-code Value 4.
parameter Value 1.
On Exit:

None

Comments:

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.


X"E5" - Sound Bell

Sounds the bell

Syntax:
call x"E5"
Parameters:

None

Comments:

The duration and pitch of the bell depends on the environment.


Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.
PreviousOverview of Character User Interface Methods AdisNext