PreviousOverview of Character User Interface Methods AdisNext

Chapter 3: Low-level Routines for Character Interfaces

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.

For other library routines, see the following references:

Generic line drawing The chapter Generic Line Drawing in this book
Generic display attributes The chapter Generic Display Attributes in this book
Debugging The chapter Library Routines in your Debugging Guide
File handling The chapter File Handling Library Routines in your File Handling book
Multi-threaded programming The chapter Library Routines for Multi-threading in your Multi-threaded Programming book
Programming environment The chapter Library Routines in your Program Development book

3.1 Type Definitions and Call Prototypes

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 Type Definitions and Call Prototypes in the chapter Library Routines in your Program Development book. 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 prototypes 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.

3.2 Overview

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

3.2.1 Screen Routines

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.

3.2.2 Keyboard Routines

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

3.3 Key to Library Routines

Each description of a routine contains the routine name and function and the following entries (as appropriate):

Syntax: Shows the CALL statement you could use to call the routine.

For all routines except the call-by-number routines (those of the form X"nn"), the optional RETURNING clause is also shown. Every routine returns a value showing the result of the operation. Unless otherwise indicated, zero indicates success, nonzero indicates failure. This value is left in the data item specified in the RETURNING clause, in this reference, status-code. If this clause is omitted, the value is left in the special register RETURN-CODE. (If call-convention bit two is set, RETURN-CODE is not changed.)

status-code must be a numeric data item capable of holding positive values from 0 to 65535; it is defined in cbltypes.cpy as cblt-rtn-code.

The name of the routine must be coded in upper case.

Parameters: Describes any parameters shown in the RETURNING and USING clause. A parameter enclosed in brackets, for example, [parameter1] is optional and might not be needed for all forms of the routine.
On Entry: Indicates which of the parameters shown are passed on entry
On Exit: Indicates which of the parameters shown are returned on exit

Where bits of one or more bytes are referenced, bit 0 is the least significant (rightmost) bit.

Comments: Provides any additional information necessary for the successful use of the routine
See Also: Lists other related topics.

3.4 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           cblt-x1-compx.
attribute           cblt-x1-compx.
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 A group item predefined as cblt-screen-position, containing the following subordinate items:
cblte-scrp-row cblt-x1-compx.
cblte-scrp-col cblt-x1-compx.
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, cblte-scrp-row and cblte-scrp-col 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          cblt-x1-compx.
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 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.

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               cblt-x1-compx.
width               cblt-x1-compx.
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 cblt-x1-compx.
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 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.

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 A group item predefined as cblt-screen-position, containing the following subordinate items:
cblte-scrp-row cblt-x1-compx.
cblte-scrp-col cblt-x1-compx.
attribute-buffer pic x(n).
string-length cblt-x2-compx.
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 A group item predefined as cblt-screen-position, containing the following subordinate items:
cblte-scrp-row cblt-x1-compx.
cblte-scrp-col cblt-x1-compx.
character-buffer pic x(n).
string-length cblt-x2-compx.
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 A group item predefined as cblt-screen-position, containing the following subordinate items:
cblte-scrp-row cblt-x1-compx.
cblte-scrp-col cblt-x1-compx.
character-buffer pic x(n).
attribute-buffer pic x(n).
string-length cblt-x2-compx.
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 A group item predefined as cblt-screen-position, containing the following subordinate items:
cblte-scrp-row cblt-x1-compx.
cblte-scrp-col cblt-x1-compx.
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 A group item predefined as cblt-screen-position, containing the following subordinate items:
cblte-scrp-row cblt-x1-compx.
cblte-scrp-col cblt-x1-compx.
character-buffer pic x(n).
attribute-buffer pic x(n).
string-length cblt-x2-compx.
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 A group item predefined as cblt-screen-position, containing the following subordinate items:
cblte-scrp-row cblt-x1-compx.
cblte-scrp-col cblt-x1-compx.
attribute-buffer pic x(n).
string-length cblt-x2-compx.
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 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

Comments:

Setting the blink attribute works only if the terminal supports this feature and a corresponding terminfo entry exists in the terminfo database.

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 A group item predefined as cblt-screen-position, containing the following subordinate items:
cblte-scrp-row cblt-x1-compx.
cblte-scrp-col cblt-x1-compx.
character-buffer pic x(n).
string-length cblt-x2-compx.
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 A group item predefined as cblt-screen-position, containing the following subordinate items:
cblte-scrp-row cblt-x1-compx.
cblte-scrp-col cblt-x1-compx.
character-buffer pic x(n).
string-length cblt-x2-compx.
attribute cblt-x1-compx.
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

Comments:

Setting the blink attribute works only if the terminal supports this feature and a corresponding terminfo entry exists in the terminfo database.

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 A group item predefined as cblt-screen-position, containing the following subordinate items:
cblte-scrp-row cblt-x1-compx.
cblte-scrp-col cblt-x1-compx.
character-buffer pic x(n).
attribute-buffer pic x(n).
string-length cblt-x2-compx.
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

Comments:

Setting the blink attribute works only if the terminal supports this feature and a corresponding terminfo entry exists in the terminfo database.

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
                                      string-length
                            returning status-code
Parameters:
screen-position A group item predefined as cblt-screen-position, containing the following subordinate items:
cblte-scrp-row cblt-x1-compx.
cblte-scrp-col cblt-x1-compx.
attribute cblt-x1-compx.
string-length cblt-x2-compx.
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

Comments:

Setting the blink attribute works only if the terminal supports this feature and a corresponding terminfo entry exists in the terminfo database.

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
                                      string-length
                            returning status-code
Parameters:
screen-position A group item predefined as cblt-screen-position, containing the following subordinate items:
cblte-scrp-row cblt-x1-compx.
cblte-scrp-col cblt-x1-compx.
character cblt-x1-compx.
string-length cblt-x2-compx.
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.
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
                                        string-length
                              returning status-code
Parameters:
screen-position A group item predefined as cblt-screen-position, containing the following subordinate items:
cblte-scrp-row cblt-x1-compx.
cblte-scrp-col cblt-x1-compx.
character cblt-x1-compx.
attribute cblt-x1-compx.
string-length cblt-x2-compx.
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

Comments:

Setting the blink attribute works only if the terminal supports this feature and a corresponding terminfo entry exists in the terminfo database.

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 cblt-x2-compx.
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

"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.

"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.

"AF" function 18 - Display Character

Displays a character 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

"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

"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 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:

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

"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.

"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 © 2002 Micro Focus 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