@(x,y) Function

@(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). By using this function instead of hard coding control sequences into programs, applications can be portable across a wide range of terminal devices or emulations.

 

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.

 

Some functions are extensions to the standard terminal capability definitions and may require use of AccuTerm with terminal type that have a -at suffix or QMTerm in qmterm mode.

 

 

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.

 

Some terminal emulations (e.g. vpa2-at) may not handle cursor positions correctly if set to a large screen size such as 132 column width. This is not a defect in QM but is caused by limitations of the control codes used by these terminals.

 

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 returns 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 visual 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 such as the Wyse50, 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 position 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 character position 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

 

-7

IT$SPA

Start protected area

 

-8

IT$EPA

End protected area

 

-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$EBOLD

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, obsolete)

-251

IT$KEYS

Display/hide screen keyboard

0 = hide, 1 = display (PDA, obsolete)

 

 

 

Descriptions

 

Each of the descriptions below expands on the preceding table. There is also a reference to the terminfo element that is used to determine the control code sent to the terminal. Unless otherwise stated, where more than one terminfo element is shown, the first one defined for the current terminal device is used. The function will only operate correctly if the corresponding terminfo element is correctly defined.

 

 

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). Terminfo "clear".

 

IT$CAH (Cursor home)

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

 

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

 

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

 

IT$SBLINK (Start flashing text)

Displays subsequent text in flashing mode. Terminfo "blink".

 

IT$EBLINK (End flashing text)

Terminates flashing mode. Terminfo "eblink" or "sgr0".

 

IT$SPA (Start protected area)

Displays subsequent text in protected mode. Characters displayed in this mode can only be updated by erasing them from the screen with modes IT$CS, IT$CLEOS or IT$CLEOL. Terminfo "prot".

 

IT$EPA (End protected area)

Terminates protected mode. Terminfo "eprot" or "sgr0".

 

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. Terminfo "cub1" repeated.

 

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. Terminfo "cuu1" repeated.

 

IT$SHALF (Start half brightness)

Displays subsequent data in half brightness (dim) mode. Terminfo "dim".

 

IT$EHALF (End half brightness)

Terminates half brightness (dim) mode. Terminfo "edim" or "sgr0".

 

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

 

IT$EREV (End reverse video)

If in reverse video mode, this operation reverts to the normal display colours for subsequent text output. Terminfo "erev" or "sgr0".

 

IT$SUL (Start underline)

Displays subsequent data in underline mode. Terminfo "smul".

 

IT$EUL (End underline)

Terminates underline mode. Terminfo "rmul".

 

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. Terminfo "il1" if inserting one line, otherwise "il" with qualifying line count.

 

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. Terminfo "dl1" if inserting one line, otherwise "dl" with qualifying line count.

 

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. Terminfo "ich1" repeated.

 

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. Terminfo "dch1" repeated.

 

IT$AUXON (Turn on printer)

For terminals with attached printers, this mode directs output to the printer. Terminfo "mc5".

 

IT$AUXOFF (Turn off printer)

For terminals with attached printers, this mode turns off output to the printer. Terminfo "mc4".

 

IT$E80 (Set 80 column mode)

The display window is set to be 80 characters wide. Terminfo "set80".

 

IT$E132 (Set 132 column mode)

The display window is set to be 132 characters wide. Terminfo "set132".

 

IT$RIC (Reset inhibit cursor)

The cursor is displayed if it was previously inhibited. Terminfo "cvvis".

 

IT$SIC (Inhibit cursor)

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

 

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. Terminfo "cud1" repeated.

 

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. Terminfo "cuf1" repeated.

 

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. Terminfo "setf" with colour value.

 

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. Terminfo "setb" with colour value.

 

IT$SLT (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. Terminfo "slt".

 

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

 

IT$SBOLD (Start bold)

Displays subsequent data in bold mode. Terminfo "bold".

 

IT$EBOLD (End bold)

Terminates bold mode. Terminfo "ebold" or "sgr0".

 

IT$ACMD (Asynchronous command)

Executes the given command on the client system without suspending the QM session. Terminfo "u8" with qualifying data.

 

IT$SCMD (Synchronous command)

Executes the given command on the client system, suspending the QM session until the command completes. Terminfo "u9" with qualifying data.

 

IT$STYLUS (Enable/disable stylus taps)

Applicable only to QM on a PDA, this operation is equivalent to use of the MOUSE statement and 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. Terminfo "stylus" with qualifier. Use of the KEYCODE() or KEYCODEV() functions will automatically process the positional data related to the stylus tap, leaving the screen coordinates in @MCOL and @MROW.

 

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. Terminfo "pdakeys" with qualifier.

 

 

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.