@(x, y) Function

Top  Previous  Next

 

The @(x, y) function is used to control the format of displayed output.

 

 

Format

 

@(col {, line})Cursor movement
@(mode {, arg})Device control functions

 

where

 

colevaluates to a display column position.

 

lineevaluates to a display line position.

 

modeevaluates to a mode value as described below.

 

argprovides qualifying information for use with some mode values.

 

 

The @(x, y) functions return string values which can be used in the same way as any other strings. They only take effect when the string is used in a CRT, DISPLAY or PRINT statements directed to the display. The actual value returned by the function is a control code to be sent to the terminal and is dependant on the type of terminal in use (see the TERM command).

 

When output is directed to a printer or to a file for later printing rather than to the display, escape sequences relevant to the printer may be used for formatting, etc. Because the @(x,y) function returns codes specific for the terminal in use, it is unlikely that these codes are relevant for printers.

 

 

Cursor Positioning

 

The @(col {, line}) format specifies that subsequent output is to appear at the given column and, optionally, line position. Columns and lines are numbered from zero where the top left of the screen is line 0, column 0. The effect of attempting to move to a cursor position outside the display area is undefined.

 

Use of the @(col {, line}) function disables screen pagination (automatic display of the "Press return to continue" prompt after each screen of output). Pagination remains disabled until the program executes the PRINTER RESET statement or return to the command prompt.

 

Use of the EXECUTE statement enables screen pagination, executes the command(s) and then restores pagination to its state when the EXECUTE was performed.

 

 

Special Functions

 

@(x, y) functions with negative values of x are used to provide a variety of control functions. These are largely in common with the functions defined for other systems. The token names shown in the table below are defined in the KEYS.H include record in the SYSCOM file.

 

Functions not supported by the terminal device in use return a null string and hence will be ignored. Note that individual terminal types may place restrictions on use of display attributes such as flashing, underline, colour, etc. For example, although each attribute has a corresponding start and end control code pair, many terminals can only apply a single attribute to any particular screen region.

 

Display attributes are also implemented in two fundamentally distinct ways. Most modern terminals maintain an attribute for each character position on the display and data is stored by the terminal using the currently active attributes regardless of any intervening cursor movements. On some other terminals, the code sent by an @() function to set or clear an attribute occupies a character position on the screen. Starting at the top left of the screen and working row by row through each character position, the attributes of any particular character are determined by the most recent attribute setting encountered.

 

For example,

DISPLAY @(-1):@(-15):'ABC':@(-16):'DEF'

on a terminal that stores the attribute for each character position would result in a display of

ABCDEF

whereas a terminal that uses a character cell to store the attribute would display

ABC DEF

 

Furthermore, if the program then executed

DISPLAY @(3,0):'X'

the first terminal would display

ABCXEF

but the second would display

ABCXDEF    

with the underline extending to the end of the screen or the next cell holding an attribute setting.

 

 

Value

Token

Function

Argument

-1

IT$CS

Clear screen

 

-2

IT$CAH

Cursor home

 

-3

IT$CLEOS

Clear to end of screen

 

-4

IT$CLEOL

Clear to end of line

 

-5

IT$SBLINK

Start flashing text

 

-6

IT$EBLINK

End flashing text

 

-9

IT$CUB

Backspace

No of characters (default 1)

-10

IT$CUU

Cursor up

No of lines (default 1)

-11

IT$SHALF

Start half brightness

 

-12

IT$EHALF

End half brightness

 

-13

IT$SREV

Start reverse video

 

-14

IT$EREV

End reverse video

 

-15

IT$SUL

Start underline

 

-16

IT$EUL

End underline

 

-17

IT$IL

Insert line

No of lines (default 1)

-18

IT$DL

Delete line

No of lines (default 1)

-19

IT$ICH

Insert character

No of characters (default 1)

-22

IT$DCH

Delete character

No of characters (default 1)

-23

IT$AUXON

Turn on printer

 

-24

IT$AUXOFF

Turn off printer

 

-29

IT$E80

Set 80 column mode

 

-30

IT$E132

Set 132 column mode

 

-31

IT$RIC

Reset inhibit cursor

 

-32

IT$SIC

Inhibit cursor

 

-33

IT$CUD

Cursor down

No of lines (default 1)

-34

IT$CUF

Cursor forward

No of characters (default 1)

-37

IT$FGC

Set foreground colour

Colour

-38

IT$BGC

Set background colour

Colour

-54

IT$SLT

Set line truncation

 

-55

IT$RLT

Reset line truncation

 

-58

IT$SBOLD

Set bold mode

 

-59

IT$RBOLD

Reset bold mode

 

-100 to -107

User definable via the u0 to u7 terminfo keys

-108

IT$ACMD

Asynchronous command

Command to execute

-109

IT$SCMD

Synchronous command

Command to execute

-250

IT$STYLUS

Enable/disable stylus taps

0 = disable, 1 = enable (PDA)

-251

IT$KEYS

Display/hide screen keyboard

0 = hide, 1 = display (PDA)

 

 

 

Descriptions

 

IT$CS (Clear screen)

The screen is cleared to the current background colour. The cursor is positioned at the top left of the screen (position 0,0).

 

IT$CAH (Cursor home)

The cursor is positioned at the top left of the screen (position 0,0).

 

IT$CLEOS (Clear to end of screen)

All screen positions between the current cursor position and the end of the screen are cleared. Some terminal devices/emulators set the cleared character positions to have the current background colour.

 

IT$CLEOL (Clear to end of line)

All screen positions between the current cursor position and the end of the line are cleared. Some terminal devices/emulators set the cleared character positions to have the current background colour.

 

IT$CUB (Backspace)

The cursor moves left by the number of positions specified in the second argument which defaults to one or until the left edge of the screen is reached.

 

IT$CUU (Cursor up)

The cursor moves up by the number of lines specified in the second argument which defaults to one or until the top line of the screen is reached.

 

IT$SHALF (Start half brightness)

Displays subsequent data in half brightness (dim) mode.

 

IT$EHALF (End half brightness)

Terminates half brightness (dim) mode.

 

IT$SREV (Start reverse video)

If not already in reverse video mode, the foreground and background colours are interchanged for subsequent output. Selecting this mode does not directly affect any data which is already displayed.

 

IT$EREV (End reverse video)

If in reverse video mode, this operation reverts to the normal display colours for subsequent text output.

 

IT$IL (Insert line)

The number of lines specified in the second argument (default value one) are inserted at the current cursor position. Data at the bottom of the screen will be lost. The newly inserted lines are set to the background colour.

 

IT$DL (Delete line)

The number of lines specified in the second argument (default value one) are deleted at the current cursor position. Blank lines are inserted at the bottom of the screen.

 

IT$ICH (Insert character)

The number of characters specified in the second argument (default value one) are inserted at the current cursor position. Data at the right of the screen will be lost.

 

IT$DCH (Delete character)

The number of characters specified in the second argument (default value one) are deleted at the current cursor position. Blanks are inserted at the right edge of the screen.

 

IT$AUXON (Turn on printer)

For terminals with attached printers, this mode directs output to the printer. The mc5 terminfo entry must be set correctly for this to work.

 

IT$AUXOFF (Turn off printer)

For terminals with attached printers, this mode turns off output to the printer. The mc4 terminfo entry must be set correctly for this to work.

 

IT$E80 (Set 80 column mode)

The display window is set to be 80 characters wide.

 

IT$E132 (Set 132 column mode)

The display window is set to be 132 characters wide.

 

IT$RIC (Reset inhibit cursor)

The cursor is displayed if it was previously inhibited.

 

IT$SIC (Inhibit cursor)

Display of the cursor is inhibited. All cursor positioning functions continue to work whilst the cursor is not visible.

 

IT$CUD (Cursor down)

The cursor moves down by the number of lines specified in the second argument which defaults to one or until the bottom line of the screen is reached.

 

IT$CUF (Cursor forward)

The cursor moves right by the number of positions specified in the second argument which defaults to one or until the right edge of the screen is reached.

 

IT$FGC (Set foreground colour)

The foreground colour is set according to the value of the second argument. This may be set using the tokens listed below from the KEYS.H record of the SYSCOM file.

 

IT$BLACK0
IT$BLUE 1
IT$GREEN2
IT$CYAN3
IT$RED 4
IT$MAGENTA5
IT$BROWN6
IT$WHITE7
IT$GREY8
IT$BRIGHT.BLUE9
IT$BRIGHT.GREEN10
IT$BRIGHT.CYAN11
IT$BRIGHT.RED12
IT$BRIGHT.MAGENTA13
IT$YELLOW14
IT$BRIGHT.WHITE15

 

Some terminal emulators provide the ability to map these colour values to an alternative colour palette. The terminfo COLOURMAP setting can be used to translate the internal QM values listed above to an alternative set relevant to a specific terminal emulator.

 

IT$BGC (Set background colour)

The background colour is set according to the value of the second argument. This may be set using the tokens from the KEYS.H record of the SYSCOM file as listed above.

 

IT$SLC (Set line truncation)

With this mode enabled, the cursor does not automatically move to a new line when data is displayed in the final column of the screen. Any further output on the line will overwrite the final character.

 

IT$RLT (Reset line truncation)

Clears line truncation mode so that the cursor automatically moves to a new line when data is displayed in the final column of the screen.

 

IT$ACMD (Asynchronous command)

Executes the given command on the client system without suspending the QM session. This operation depends on correct setting of the terminfo u8 token.

 

IT$SCMD (Synchronous command)

Executes the given command on the client system, suspending the QM session until the command completes. This operation depends on correct setting of the terminfo u9 token.

 

IT$STYLUS (Enable/disable stylus taps)

Applicable only to QM on a PDA, this operation allows an application to receive stylus taps via input operations. When enabled, a stylus tap appears as char(200) (K$MOUSE) followed by the column and row coordinates separated by a comma and terminated with a carriage return. Set the second argument to a non-zero value to enable stylus taps, zero to disable them. Stylus input is disabled by default when QM starts.

 

IT$KEYS (Display/hide screen keyboard)

Applicable only to QM on a PDA, this operation displays or hides the on screen keyboard. Set the second argument to a non-zero value to show the keyboard, zero to hide it.

 

 

Examples

 

DISPLAY @(IT$CS) : @(34,10) : "Please wait" :

 

This statement clears the screen and displays "Please wait" .

 

 

DISPLAY @(IT$FGC, IT$BRIGHT.RED) : "Error " : STATUS()

 

This statement displays the value of the STATUS() function in bright red. Further output to the display will continue to be in this colour until the foreground colour is reset.