Panels

Windowing Support for Text-based Systems

Chapter 6: COBOL System Library Routines

The COBOL System Library contains sets of routines that you can call to paint characters and attributes to a character screen, read keys pressed on the keyboard, and to communicate with a mouse.

This chapter lists the routines available and describes them in detail.

6.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 and attribute strings
CBL_SET_CSR_POS	Set cursor position
CBL_SWAP_SCR_CHATTRS	Swap character and 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 and attribute strings
CBL_WRITE_SCR_TTY	Write characters TTY-style
CBL_WRITE_SCR_N_ATTR	Repeat write attribute
CBL_WRITE_SCR_N_CHAR	Repeat write character
CBL_WRITE_SCR_N_CHATTR	Repeat write character and attributes
X"A7" function 17	Set Cursor Type
X"A7" function 18	Redirectable Console I/O
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

6.1.1 Introduction to Screen Routines

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.

The CBL_GET_SCR routines enable you to make use of generic line drawing to produce the best possible representation of graphics characters available in any supported environment without having to modify your source programs.

Before using any of the X"A7" routines for screen handling, use the CBL_CLR_SCR routine.

6.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 0	Create Function-key Table
X"B0" function 2	Test Shift-key Status
X"B0" function 4	Disable Keyboard Interrupts

6.3 Mouse Routines

CBL_GET_MOUSE_MASK	Get mouse event mask
CBL_GET_MOUSE_POSITION	Get mouse screen coordinates
CBL_GET_MOUSE_STATUS	Get number of events in queue
CBL_HIDE_MOUSE	Hide mouse pointer
CBL_INIT_MOUSE	Initialize mouse support
CBL_READ_MOUSE_EVENT	Read mouse event queue
CBL_SET_MOUSE_MASK	Set mouse event mask
CBL_SET_MOUSE_POSITION	Set mouse screen coordinates
CBL_SHOW_MOUSE	Draw mouse pointer
CBL_TERM_MOUSE	Terminate mouse support
PC_GET_MOUSE_SHAPE	Get mouse pointer shape
PC_SET_MOUSE_HIDE_AREA	Set mouse hide area
PC_SET_MOUSE_SHAPE	Set mouse pointer shape

6.3.1 Introduction to Mouse Routines

These routines do not work under UNIX.

UNIX:
In UNIX environments, CBL_INIT_MOUSE returns a nonzero RETURN-CODE indicating that no mouse is present. The other CBL_ calls listed above exist only as stubs and have no effect.

6.3.2 Using the Mouse Routines

The mouse is useful for applications that require users to select from a list of options or move objects around on the screen.

To use these routines, you must ensure that your system knows that you have a mouse attached.

You must hide the mouse during the execution of any ANSI ACCEPT or DISPLAY statement that operates on the area of the screen where the mouse pointer is located.

The attributes referred to in the descriptions of routines are screen attributes, not user attributes. The top left-hand corner of the screen is row 0, column 0.

6.3.3 Mouse Events

Whenever the mouse is moved or a button on the mouse is pressed or released, the mouse hardware causes an interrupt. The mouse device driver takes control and, depending on a mask you have set, either saves it in a queue or ignores it. This prevents events being lost if a subsequent interrupt occurs before the application has read the event. With the mouse routines, you can read the event queue and determine how many events are in the queue.

When an event is generated, a description of it is stored in a data structure called the event-data. If the mask allows (see below), this is added to the queue. The layout of event-data is:

 event-type           pic x(2) comp-x.
 event-time           pic x(4) comp-x.
 event-row            pic x(2) comp-x.
 event-col            pic x(2) comp-x.

where the parameters are:

event-type

The action (that is, change of state) that took place:

bit 7-4	reserved
bit 3	set = button 3 pressed
bit 2	set = button 2 pressed
bit 1	set = button 1 pressed
bit 0	set = mouse moved

A button release is indicated by the bit for that button changing from 1 to 0. For example, if the mouse moves and button 1 is pressed at the same time, event-type contains 3.

event-time The time elapsed between when the event took place and some arbitrary but fixed starting time.

event-row, event-col The position of the mouse when the event took place.

6.3.4 The Event Mask

The event mask, which you supply, tells the system which kinds of event should be queued and which ignored. It has the same structure as event-type. An event is queued only if it happens while the corresponding mask bit is on, or while another state is on whose mask bit is on. When an event-data is queued, the bit for each state is set correctly; that is, the mask does not mask them out.

For example, the operator moving the mouse generates an event if either the mask bit for "mouse moved" is on or the operator is holding down a button and the mask bit for that button is on.

6.4 Key

Descriptions for all of the call-by-name routines appear alphabetically. Each description contains the routine name and function, and the following entries, as appropriate:

Syntax:

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

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; for example, PIC X(2) COMP-5.

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.

Remarks:

Provides any additional information necessary for the successful use of the routine.

6.5 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 the section 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 the section 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 the section Introduction to 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 the section 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.

CBL_GET_MOUSE_MASK

Returns the mouse event mask.

Syntax:

call "CBL_GET_MOUSE_MASK" using     mouse-handle            
                         event-mask 
                          returning status-code

On Exit:

`depth`	Number of lines.
`width`	Number of columns.

CBL_HIDE_MOUSE

Makes the mouse pointer invisible.

Syntax:

call "CBL_HIDE_MOUSE" using     mouse-handle 
                      returning status-code

Parameters:

mouse-handle pic x(4) comp-x
status-code See the section Key

On Entry:

mouse-handle Mouse identifier, obtained by earlier call to CBL_INIT_MOUSE.

On Exit:

None

Comments:

This routine has no effect in UNIX environments.

After this routine has been called, mouse events still take place, but the mouse pointer is not displayed.

CBL_INIT_MOUSE

Initializes mouse support. This routine must be called before other mouse routines can be called.

Syntax:

call "CBL_INIT_MOUSE" using     mouse-handle                
                 mouse-buttons 
                      returning status-code

Parameters:

mouse-handle        pic x(4) comp-x
mouse-buttons       pic x(2) comp-x
status-code         See the section Key

On Entry:

None

On Exit:

`mouse-handle`	Mouse identifier. You pass this to any mouse routines you call subsequently.
`mouse-buttons`	The number of buttons on the mouse.

Comments:

If status-code (or RETURN-CODE) contains a nonzero status on return from this routine, mouse handling is not available and calls to any of the mouse routines should not be made.

In UNIX environments this routine always returns a nonzero status-code.

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 the section Key

On Entry:

None

On Exit:

char The character that was typed, in ASCII.

CBL_READ_MOUSE_EVENT

Reads the mouse event queue and returns information about an event.

Syntax:

call "CBL_READ_MOUSE_EVENT" using     mouse-handle          
                             event-data                                       
read-type 
                            returning status-code

Parameters:

mouse-handle        pic x(4) comp-x.
event-data          See the section Introduction to Mouse Routines
read-type           pic x comp-x.
status-code         See the section Key

On Entry:

mouse-handle Mouse identifier, obtained by earlier call to CBL_INIT_MOUSE.

read-type

Indicates what to do if there are no events in the queue:

0	Return immediately
1	Wait for an event and then return

On Exit:

event-data See the section Introduction to Mouse Routines

Comments:

This routine has no effect in UNIX environments.

If there are no events in the event queue, the return from this routine depends on the value of read-type. If read-type is zero, the routine returns immediately with all zero values in event-data. If read-type has a value of one, return is delayed until an event has been queued.

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 the section Key

On Entry:

`screen-position`	The screen position to start reading at. The top left corner is row 0, column 0. See the section Introduction to 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 the section Key

On Entry:

`screen-position`	The screen position to start reading at. The top left corner is row 0, column 0. See the section Introduction to 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 the section Key

On Entry:

`screen-position`	The screen position to start reading at. The top left corner is row 0, column 0. See the section Introduction to 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 the section Key

On Entry:

screen-position The screen position at which to put the cursor. The top left corner is row 0, column 0. See the section Introduction to Screen Routines

On Exit:

None

Comments:

To make the cursor invisible, set row-number and column-number to 255.

CBL_SET_MOUSE_MASK

Sets the mouse event mask.

Syntax:

call "CBL_SET_MOUSE_MASK" using     mouse-handle 
                                    event-mask 
                          returning status-code

Parameters:

mouse-handle        pic x(4) comp-x.
event-mask          pic x(2) comp-x.
status-code         See the section Key

On Entry:

`mouse-handle`	Mouse identifier, obtained by earlier call to CBL_INIT_MOUSE.
`event-mask`	See the section Introduction to Mouse Routines

On Exit:

None

Comments:

This routine has no effect in UNIX environments.

CBL_GET_MOUSE_MASK should be called first to find out which events are enabled.

CBL_SET_MOUSE_POSITION

Moves the mouse pointer.

Syntax:

call "CBL_SET_MOUSE_POSITION" using     mouse-handle        
                                 mouse-position
                              returning status-code

Parameters:

On Entry:

`mouse-handle`	Mouse identifier, obtained by earlier call to CBL_INIT_MOUSE.
`mouse-position`	The screen position to move the mouse pointer to.

On Exit:

None

Comments:

This routine has no effect in UNIX environments.

CBL_SHOW_MOUSE

Makes the mouse pointer visible.

Syntax:

call "CBL_SHOW_MOUSE" using     mouse-handle 
                      returning status-code

Parameters:

mouse-handle pic x(4) comp-x
status-code See the section Key

On Entry:

mouse-handle Mouse identifier, obtained by earlier call to CBL_INIT_MOUSE.

On Exit:

None

Comments:

This routine has no effect in UNIX environments.

When the mouse support has been initialized by the CBL_INIT_MOUSE call, the pointer is not displayed until this routine is called. After this call the system displays the mouse pointer until a routine to hide the mouse or terminate mouse support is called. This routine cancels any collision area defined earlier by PC_SET_MOUSE_HIDE_AREA.

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:

On Entry:

`screen-position`	The screen position at which to start writing. The top left corner is row 0, column 0. See the section Introduction to 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.

CBL_TERM_MOUSE

Terminates mouse support, releasing internal resources.

Syntax:

call "CBL_TERM_MOUSE" using     mouse-handle 
                      returning status-code

Parameters:

mouse-handle pic x(4) comp-x
status-code See the section Key

On Entry:

mouse-handle Mouse identifier, obtained by earlier call to CBL_INIT_MOUSE.

On Exit:

None

Comments:

This routine has no effect in UNIX environments.

The routine releases internal resources allocated by CBL_INIT_MOUSE. After this routine, mouse-handle is no longer valid and calling any mouse routine other than CBL_INIT_MOUSE results in an error.

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:

On Exit:

None

Comments:

The blink attribute is not supported on this COBOL system. Specifying that a character is to blink results in the character being displayed with a bright background color.

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:

On Entry:

`screen-position`	The screen position at which to start writing. The top left corner is row 0, column 0. See the section Introduction to 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

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 the section Key

On Entry:

`screen-position`	The screen position at which to start writing. The top left corner is row 0, column 0. See the section Introduction to 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:

The blink attribute is not supported on this COBOL system. Specifying that a character is to blink results in the character being displayed with a bright background color.

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:

On Entry:

`screen-position`	The screen position at which to start writing. The top left corner is row 0, column 0. See the section Introduction to 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:

The blink attribute is not supported on this COBOL system. Specifying that a character is to blink results in the character being displayed with a bright background color.

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 the section Key

On Entry:

`screen-position`	The screen position at which to start writing. The top left corner is row 0, column 0. See the section Introduction to 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:

The blink attribute is not supported on this COBOL system. Specifying that a character is to blink results in the character being displayed with a bright background color.

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 the section Key

On Entry:

`screen-position`	The screen position at which to start writing. The top left corner is row 0, column 0. See the section Introduction to 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

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 the section Key

On Entry:

`screen-position`	The screen position at which to start writing. The top left corner is row 0, column 0. See the section Introduction to 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:

The blink attribute is not supported on this COBOL system. Specifying that a character is to blink results in the character being displayed with a bright background color.

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 the section 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

PC_GET_MOUSE_SHAPE

Returns information about the shape of the mouse pointer.

Syntax:

call "PC_GET_MOUSE_SHAPE" using     mouse-handle            
                         reserved-item                                     
mouse-ptr-shape 
                          returning status-code

Parameters:

mouse-handle        pic x(4) comp-x.
reserved-item       pic x(10).
mouse-ptr-shape     Group item defined as:
    char_AND_mask       pic x comp-x.
    attr_AND_mask       pic x comp-x.
    char_XOR_mask       pic x comp-x.
    attr_XOR_mask       pic x comp-x.
status-code         See the section Key

On Entry:

`mouse-handle`	Mouse identifier, obtained by earlier call to CBL_INIT_MOUSE.
`reserved-item`	Reserved for future use.

On Exit:

mouse-ptr-shape The bitmaps that would create the pointer's current shape.

Comments:

This routine is available only in DOS, Windows and OS/2 environments.

The masks in mouse-ptr-shape are bitmaps that, applied to a screen position, would superimpose the mouse shape upon it. The pointer shape is formed by PC_SET_MOUSE_SHAPE by ANDing the screen character at the mouse position with char_AND_mask, XORing the result with char_XOR_mask, and then displaying the result on the screen. The attribute is formed similarly.

PC_SET_MOUSE_HIDE_AREA

Defines an area ("collision area") where the mouse is to be invisible.

Syntax:

call "PC_SET_MOUSE_HIDE_AREA" using     mouse-handle        
                                 collision-area
                              returning status-code

Parameters:

mouse-handle        pic x(4) comp-x.
collision-area      Group item defined as:
    top-row             pic x(2) comp-x.
    left-col            pic x(2) comp-x.
    bottom-row          pic x(2) comp-x.
    right-col           pic x(2) comp-x.
status-code         See the section Key

On Entry:

`mouse-handle`	Mouse identifier, obtained by earlier call to CBL_INIT_MOUSE.
`collision-area`	Defines the collision area. Whenever the pointer is in this area, it is hidden. A value of zeros in this item makes the whole screen a collision area. There can be only one collision area at any one time.

On Exit:

None

Comments:

This routine is available only in DOS, Windows V3.1 and 16-bit OS/2.

PC_SET_MOUSE_SHAPE

Sets the shape of the mouse pointer.

Syntax:

call "PC_SET_MOUSE_SHAPE" using     mouse-handle            
                         reserved-item                                     
mouse-ptr-shape 
                          returning status-code

Parameters:

On Entry:

`mouse-handle`	Mouse identifier, obtained by earlier call to CBL_INIT_MOUSE.
`reserved-item`	Reserved for future use.
`mouse-ptr-shape`	The bitmaps to create the pointer's desired shape.

On Exit:

None

Comments:

This routine is available only in DOS, Windows and OS/2 environments.

To call this routine you must have previously called PC_GET_MOUSE_SHAPE with the same mouse-handle. The data item reserved-item must be as preserved from that call.

X"A7" function 17 - Set Cursor Type

Sets the cursor type.

Syntax:

call X"A7" using function-code                   cursor-type

Parameters:

function-code       pic x comp-x.
cursor-type         Group item defined as:
    cursor-end          pic x comp-x.
    cursor-start        pic x comp-x.

On Entry:

`function-code`	Value 17.
`cursor-end`	Scan line cursor ends on.
`cursor-start`	Scan line cursor starts on.

On Exit:

None

Comments:

This routine is available only in DOS, Windows and OS/2 environments.

Details of cursor start and end lines can be found in your IBM BIOS Technical Reference manual.

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

X"A7" function 18 - Redirectable Console I/O

Makes console I/O redirectable.

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

parameter

Action to perform:

0	Disable DOS-style console I/O
1	Enable DOS-style console I/O

On Exit:

None

Comments:

This routine is available only in DOS, Windows and OS/2 environments.

Normally the RTE uses the BIOS to read the keyboard, and writes direct to the video map for all displays. This routine makes the RTE use operating system functions instead. This means the operator can use the operating system facilities for re-directing keyboard input and screen output.

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

X"A7" function 25 - Get Screen Type

Returns the current screen type as recognized by the RTS.

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 Enhanced ACCEPT/DISPLAY Syntaxfor 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 Enhanced ACCEPT/DISPLAY Syntaxdescribes 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.

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

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 Enhanced ACCEPT/DISPLAY Syntax 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:

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

X"B0" function 0 - Create Function-key Table

Creates a function-key table.

Syntax:

call X"B0" using function-code                   key-table

Parameters:

function-code pic x comp-x.

key-table           Group item defined as:
    key-pressed         pic x comp-x
    key-entry-list      Group item defined as one iteration of the
following for each key to be detected:
        key-entry-len       pic x comp-x
        key-entry           pic x(n)
    key-list-end        pic x comp-x

On Entry:

`function-code`	Contains 0.
`key-entry-len`	The length of key-entry in bytes (1 or 2).
`key-entry`	The code sequence produced by the required key.
`key-list-end`	Contains 0.

On Exit:

key-pressed The table entry matching the key used, or zero if no match is made.

Comments:

This routine is avilable only on DOS, Windows and OS/2. It is specific to IBM PC compatible environments. If you intend to use your application in a non-IBM environment, use call x"AF".

Any keys defined by this call take precedence over those defined with AdisCF.

The function key table set up by AdisCF and used by call x"AF" is separate from the function key table used by call x"B0". Both can be enabled at the same time with all key sequences in the x"B0" table causing the carriage return x"0D" character to be returned to Adis.

X"B0" function 2 - Test Shift-key Status

Tests the status of the Shift, Alt, Ctrl and Lock keys.

Syntax:

call X"B0" using function-code                  
status-block

Parameters:

function-code       pic x comp-x
status-block        Group item defined as:
    status-inds         pic x
    status-id           pic x comp-x
    status-res          pic x(6)

On Entry:

`function-code`	Value 2.
`status-id`	Must be set to 2. It is overwritten by the call, so must be reset to 2 before each call.
`status-res`	Reserved.

On Exit:

status-inds

Contains bit settings indicating the status of the keys (1=key pressed, 0=key not pressed) in the following order:

Bit 7	Ins
Bit 6	Caps Lock
Bit 5	Num Lock
Bit 4	Scroll Lock
Bit 3	Alt
Bit 2	Ctrl
Bit 1	Shift (left key only)
Bit 0	Shift (right key only)

Comments:

This routine is avilable only on DOS, Windows and OS/2.

For the Alt, Ctrl and Shift keys, the routine returns a 1 only if the key is actually pressed when the routine is called; for the other, the relevant bit is alternately set and unset each time the key is pressed.

Effective use of function 2 requires that the call is repeated at very frequent intervals.

X"B0" function 4 - Disable Keyboard Interrupts

Disables keyboard interrupts (Ctrl+Break on DOS, Windows and OS/2).

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.

Panels

Windowing Support for Text-based Systems

Syntax:

Parameters:

On Entry:

On Exit:

Remarks:

See also:

CBL_CLEAR_SCR

Syntax:

Parameters:

On Entry:

On Exit:

CBL_GET_CSR_POS

Syntax:

Parameters:

On Entry:

On Exit:

CBL_GET_KBD_STATUS

Syntax:

Parameters:

On Entry:

On Exit:

Comments:

CBL_GET_MOUSE_MASK

Syntax:

Parameters:

On Entry:

On Exit:

Comments:

See also:

CBL_GET_MOUSE_POSITION

Syntax:

Parameters:

On Entry:

On Exit:

Comments:

See also:

CBL_GET_MOUSE_STATUS

Syntax:

Parameters:

On Entry:

On Exit:

Comments:

See also:

CBL_GET_SCR_SIZE

Syntax:

Parameters:

On Entry:

On Exit:

CBL_HIDE_MOUSE

Syntax:

Parameters:

On Entry:

On Exit:

Comments:

See also:

CBL_INIT_MOUSE

Syntax:

Parameters:

On Entry:

On Exit:

Comments:

See also:

CBL_READ_KBD_CHAR

Syntax:

Parameters:

On Entry:

On Exit:

CBL_READ_MOUSE_EVENT

Syntax:

Parameters:

On Entry:

On Exit:

Comments:

See also:

CBL_READ_SCR_ATTRS

Syntax:

Parameters:

On Entry:

On Exit:

CBL_READ_SCR_CHARS