The PX-8 uses a separate CPU to handle the console. Rather than have many calls to specific routines for particular console functions, the functions are ex- ecuted by sending a sequence of characters to the console. This appendix deals with the use of these command sequences. It is also possible to use certain AS- CII control codes. These are described in Appendix E.
The sequences involve the ESCAPE character ASCII code 27 decimal (1B in hexadecimal), followed by one or more characters, the values of which deter- mine the command to be carried out. In the remainder of this appendix the ESCAPE character is denoted by the letters "ESC". The ESC code would nor- mally be used as part of a machine code routine, by using the CONOUT rou- tine described in section 5.7.3, although they could also be input directly from the keyboard on the CP/M command line in many cases. Since it may be neces- sary to enter them from the keyboard, the key sequence is given where this is possible. The character sequence can also be executed as part of a BASIC PRINT statement. The BASIC MANUAL contains further information on using the sequences in BASIC programs. Not all the commands are supported in BASIC because they interact with the screen editor.
The following table shows an alphabetical list to enable the character sequence for each command to be found. Notes on the use of the commands and parameters are given in numerical order following the table. The numerical values are given in decimal and hexadecimal notation in the table and headings.
Control Code Decimal Hexadecimal Function ESC "%" 27,37 1B,25 Access CGROM directly ESC 243 27,243 1B,F3 Arrow key code ESC 246 27,246 1B,F6 Buffer clear key ESC 163 27,163 1B,A3 CAPS LED off ESC 162 27,162 1B,A2 CAPS LED on ESC "C" 27,67 1B,43 Character table ESC 246 27,246 1B,F6 Clear key buffer ESC "*" 27,42 1B,2A Clear screen ESC 245 27,245 1B,F5 CTRL key code ESC 215 27,215 1B,D7 Cursor find ESC 243 27,243 1B,F3 Cursor key code ESC "2" 27,50 1B,32 Cursor off ESC "3" 27,51 1B,33 Cursor on ESC "=" 27,61 1B,3D Cursor position set ESC 214 27,214 1B,D6 Cursor type select ESC "P" 27,80 1B,50 Dump screen ESC "T" 27,84 1B,54 Erase to end of line ESC "Y" 27,89 1B,59 Erase to end of screen ESC 210 27,210 1B,D2 Display characters on real screen ESC 208 27,208 1B,D0 Display mode set ESC 198 27,198 1B,C6 Dot line write ESC 224 27,224 1B,E0 Download user defined character ESC 213 27,213 1B,D5 End locate ESC 215 27,215 1B,D7 Find cursor ESC 176 27,176 1B,B0 Function key code returned ESC 177 27,177 1B,B1 Function key string returned ESC 211 27,211 1B,D3 Function key display select ESC "C" 27,67 1B,43 International character sets ESC 161 27,161 1B,A1 INS LED off ESC 160 27,160 1B,A0 INS LED on
Control Code Decimal Hexadecimal Function ESC 242 27,242 1B,F2 Key repeat interval time ESC 240 27,240 1B,F0 Key repeat on/off ESC 241 27,241 1B,F1 Key repeat start time ESC 244 27,244 1B,F4 Key code scroll ESC 247 27,247 1B,F7 Key shift set ESC "T" 27,84 1B,54 Line erase ESC 198 27,198 1B,C6 Line dot draw ESC 213 27,213 1B,D5 Locate end of screen ESC 212 27,212 1B,D4 Locate top of screen ESC 125 27,125 1B,7D Non secret ESC 165 27,165 1B,A5 NUM LED off ESC 164 27,164 1B,A4 NUM LED on ESC 199 27,199 1B,C7 PSET/PRESET ESC 242 27,242 1B F2 Repeat key interval time ESC 240 27,240 1B,F0 Repeat on/off for keys ESC 241 27,241 1B,F1 Repeat start time for keys ESC "*" 27,42 1B,2A Screen clear ESC 151 27,151 1B 97 Screen down ESC 209 27,209 1B,D1 Screen display select ESC "P" 27,80 1B,50 Screen dump ESC 213 27,213 1B,D5 Screen window end ESC "Y" 27,89 1B,59 Screen erase ESC 212 27,212 1B,D4 Screen window top ESC 145 27,145 1B,91 Scroll down ESC 244 27,244 1B,F4 Scroll key code ESC 148 27,148 1B,94 Scroll step ESC 149 27,149 1B,95 Scroll mode ESC 144 27,144 1B,90 Scroll up ESC 151 27,151 1B,97 Screen down n lines ESC 150 27,150 1B,96 Screen up n lines ESC 123 27,123 1B,7B Secret mode ESC 125 27,125 1B,7D Secret mode cancel ESC 214 27,124 1B,D6 Select cursor type ESC 209 27,209 1B,D1 Select display screen ESC 211 27,211 1B,D3 Select function key display ESC 247 27,247 1B,F7 Shift key set ESC 149 27,149 1B,95 Tracking mode ESC 212 27,212 1B,D4 Top locate ESC 224 27,224 1B,E0 User defined characters
Where numeric codes must be given from the keyboard (shown as n or m in the escape sequence these are ASCII codes) the key or key combination giv- ing that code can be found in the table in Appendix E. Some sequences cannot be obtained direct from the keyboard. Also some control codes (e.g. CTRL-M which is equivalent to pressing the RETURN key) will function normally and so terminate the input.
Example 1 ESC control sequence from the CP/M command line
The following example shows how to turn the cursor off and then back on again on the CP/M command line.
Press the ESC key followed by the number 2 then press the RETURN key.
The display will show:
with no cursor after the CP/M prompt. To make the cursor display return, type the ESC key followed by the number 3. The question mark in either case means CP/M does not understand the command.
Example 2 The use of the CONOUT routine
The CONOUT routine (section 5.7.3) be used to execute the console ESC se- quences, for example to change the cursor to non flashing.
Reads the character corresponding to the specified code from the character gener- ator ROM and displays it at the present cursor position in the currently select- ed screen (in the virtual screen for modes 0, 1, and 2, and in the real screen for mode 3). The sequence is as follows:
The value of n is the ASCII code corresponding to the character to be displayed. This code cannot be obtained directly from the keyboard.
Clears the currently selected screen and moves the cursor to the home position. The [CRL] key or [CTRL] - [L] performs the same function.
Turns off display of the cursor. However, the cursor is still present even though it cannot actually be seen.
The cursor can also be turned on and off by using the CONFIG program.
Turns on the cursor.
Moves the cursor to the specified position on the current screen. In the track-ing mode, the screen window is moved so that the cursor is positioned at the screen center if the position specified is outside the screen window. The track-ing mode is turned on and off by pressing the shift and SCRN keys together, or by using the sequence ESC 149. The sequence for moving the cursor is as follows:
Here, m specifies the vertical cursor position and n specifies the horizontal po-sition. The value of n should be greater than 1 and less than the screen width in the particular screen mode being used. The value of m should be greater than 1 and less than the number of lines in the virtual screen.
ESC "C" < character > Used to select one of the nine international character sets as follows:
The < character > is a letter which corresponds to the character sets of one of the following countries.
Keyboard Decimal Hexadecimal US ASCII ESC,C,U 27,67,85 1B,43,55 France ESC,C,F 27,67,70 1B,43,46 Germany ESC,C,G 27,67,71 1B,43,47 England ESC,C,E 27,67,69 1B,43,45 Denmark ESC,C,D 27,67,68 1B,43,441 Sweden ESC,C,W 27,67,87 1B,43,57 Italy ESC,C,I 27,67,73 1B,43,49 Spain ESC,C,S 27,67,83 1B,43,53 Norway ESC,C,N 27,67,78 1B,43,4E
This code sequence is equivalent to the BASIC OPTION COUNTRY command. The "country" option of the CONFIG progrm can also be used to change the full character set.
In screen modes 0, 1, and 2 this escape sequence outputs the contents of the screen window currently being displayed to a printer in ASCII format. In mode 3 it outputs the contents of the entire physical screen in bit image format. It duplicates the COPY command of BASIC or screen dump function obtained by pressing the CTRL and PF5 key.
Clears the line currently containing the cursor from its present position to the end of that logical line.
Clears the screen from the current position of the cursor to the end of the screen.
Keyboard ESC, Y
Causes all characters to be displayed on the screen as blanks (the secret mode). The secret mode is not active in the System Display.
WARNING: You should make sure that a program returns the user to normal non- secret mode, for example with an error handling routine. If the user is placed in immediate mode and the secret mode is still active, it is impossi- ble to know what is happening. Also the reset button on the left of the
ESC 125 Terminates the secret mode.
Keyboard ESC A
Scrolls (m - 1) lines starting at line (n+1) up one line so that line (n+ m - 1) becomes blank. This is done as follows:
Keyboard ESC,GRPH-U,(n - 1),(m)
Decimal 27,144,n - 1,m
Hexadecimal 1B,90,n - 1,m
Numbers specified for n and m must satisfy all of the following conditions.
0 =< (n - )1 < (R - 1)
1 =< m =< R
(n-1+m - 1) < R
Here, R is the number of virtual screen lines in mode 0, 1, or 2 and is the num-ber of screen window lines in mode 3.
Scrolls the (m 1) lines starting at line n down one line so that line n becomes blank. This is done as follows:
Keyboard ESC,GRPH-I,(n 1),(m)
Decimal 27,145,n 1,m
Hexadecimal 1B,91,n 1,m
Numbers specified for n and m must satisfy all of the following conditions:
Here, R is the number of virtual screen lines in mode 0, 1, or 2 and is the num-ber of screen window lines in mode 3.
In modes 0, 1, and 2 this escape sequence sets the number of lines n which are moved by one scrolling operation. The actual scrolling is carried out by print-ing an ESC 150 sequence. The number of lines are set up using the following sequence:
Hexadecimal 1B,94,n The number specified for n must be greater than 1 and less than the number of lines in the screen window. This escape sequence does nothing in mode 3.
In modes 0, 1, and 2 this escape sequence determines whether scrolling is per-formed automatically. The automatic scrolling mode is referred to as the tracking mode, and the mode in which automatic scrolling is not performed is referred to as the non-tracking mode. The tracking mode is used unless otherwise speci-fied. The escape sequence for determining the tracking mode is as follows:
Keyboard ESC,GRPH-K,CTRL-@ for tracking mode
ESC,GRPH-K,CTRL-A for non-tracking mode
Decimal 27,149,0 or 1 Hexadecimal 1B,95,0 or 1
In this sequence, < mode > is specified as either 0 or 1. The tracking mode is selected when 0 is specified, and the non-tracking mode is selected when 1 is specified.
Normally the ΏSCRI4 key or CONFIG command can be used to switch between the tracking and non-tracking modes.
In modes 0, 1, and 2 this escape sequence displays the contents of the virtual screen containing the cursor after moving the screen window up n lines where n is the value specified by ESC 148, or 1 if ESC 148 has not been executed. If scrolling the screen up n lines would move the screen window beyond.the home position, the virtual screen is displayed starting at the home position. The cursor remains in its original position in the virtual screen.
In modes 0, 1, and 2 this escape sequence displays the contents of the virtual screen containing the cursor after moving the screen window down n lines, where n is the value specified by ESC 148, or 1 if ESC 148 has not been executed. If scrolling the screen down n lines would move the screen window beyond the end of the virtual screen, the screen window is positioned so that the virtual screens last line is displayed in the last line of the screen window. The cursor remains in its original position in the virtual screen.
Lights the INS LED. It does not put the user in insert mode.
ESC 161 Turns off the INS LED.
ESC 162 Lights the CAPS LED. It does not set the caps lock key to the on position.
ESC 163 Turns off the CAPS LED.
ESC 164 Lights the NUM LED, but does not set the numeric keypad.
ESC 165 Turns off the NUM LED.
Returns the key codes of the programmable function keys, and disable the string printed by them. (from E0 to E9)
This ESC code re-enables the programmable function keys so that a string is printed when they are pressed.
In mode 3, this escape sequence draws a line on the graphic screen using the
dot pattern specified by the user. No operation is performed when this sequence is executed modes 0, 1, or 2. The elements of the sequence are as follows:
The starting and ending positions are specified as two-byte hexadecimal num-bers which indicate co-ordinates in the graphic screen. For example, starting co-ordinates of 400,20 (&H0190,&H0014) would be specified as follows:
The mask pattern used for drawing the line is specified in bit image format as described in the explanation of the LINE statement in Chapter 4 of the PX-8 BASIC Manual. Calculations for diagonal lines are performed automatically. Function is specified as a number from 1 to 3 with the following meanings:
Dot positions corresponding to 1 bits in the mask pattern are re-set (turned off) when 1 is specified for the function and are set (turned on) when 2 is speci-fied. When 3 is specified, the complements of dots corresponding to 1 bits are displayed (ON dots corresponding to 1 bits are turned off, and OFF dots are turned on).
An example of specification of this sequence as follows draws a line from point (400,18) of the screen to point (18,18):
This command duplicates the LINE command of BASIC, but also allows the dots to be inverted (i.e. switch them on if they are off and vice versa), which LINE does not.
This escape sequence sets or re-sets the specified points of the graphic screen. No operation is performed if this sequence is executed in modes 0, 1, or 2..The sequence consists of six bytes as follows:
Numbers specified for n1 and n2 must be in the following ranges:
Decimal 0<n1<63, 0<n2<479
Hexadecimal 0 < n1 < 3F, 0 < n2 < 1DF
Switches the display mode. Mode specification is as follows:
|Mode 0||Mode 2|
|Byte 1:||27||1B||Byte 1:||27||1B|
|Byte 2:||208||DO||Byte 2:||208||DO|
|Byte 3:||2||2||Byte 3:||2||2|
|Byte 4:||n1||n1||Byte 4:||n1||n1|
|Byte 5:||n2||n2||Byte 5:||m||m|
|Mode 1||Mode 3|
|Byte 1:||27||1B||Byte 1:||27||1B|
|Byte 2:||208||DO||Byte 2:||208||DO|
|Byte 3:||1||1||Byte 3:||3||3|
The meanings of n1, n2, m, and p are as follows:
The following sequence selects screen mode 2, sets the number of lines in virtu-al screen 1 to 10, the number of columns to 20 and # as the boundary character.
Hexadecimal 1B, DO,2,A,14,23
In modes 0, 1, or 2 this escape sequence specifies which of the two virtual screens is to be displayed. The operation is performed if this sequence is executed in mode 3. This is done as follows:
The first virtual screen is selected when 0 is specified for n, and the second vir-tual screen is selected when 1 is specified for n. If the third byte is not specified the default is 0.
Displays the specified character in the specified position on the real screen. This is done as follows:
The meanings of x, y and p are as follows:
This sequence makes it possible to output characters to any location in the real
screen, regardless of the position of the cursor or number of lines in the screen window.
Turns on or off display of function key definitions. This is done as follows:
Function key definitions are displayed when 0 is specified for n, and are not displayed when 1 is specified. The default value is l.
In modes 0, 1, and 2 this escape sequence moves the screen window to the top of the virtual screen containing the cursor. No operation is performed if this sequence is executed in mode 3. The position of the cursor remains unchanged.
In modes 0, 1, and 2 this escape sequence moves the screen window to the end of the virtual screen containing the cursor. No operation is performed it his sequence is executed in mode 3. The position of the cursor remains unchanged.
In modes 0, 1, and 2 this escape sequence selects the type of cursor to be dis-played. In mode 3 always cursor type 3 is selected. The sequence consists of three bytes as follows:
In modes 0, 1, and 2 this escape sequence moves the screen window to the posi-tion occupied by the cursor. This sequence does nothing if executed in mode 3. The screen window is positioned so that the cursor is located near its centre.
This escape sequence defines those characters corresponding to ASCII codes 224 (&HEO) to 254 (&HFE). This sequence consists of eleven bytes as follows:
|Byte 3:||Character code|
|Byte 4:||Pattern for dot row 1|
|Byte 5:||Pattern for dot row 2|
|Byte 6:||Pattern for dot row 3|
|Byte 7:||Pattern for dot row 4|
|Byte 8:||Pattern for dot row 5|
|Byte 9:||Pattern for dot row 6|
|Byte 10:||Pattern for dot row 7|
|Byte 11:||Pattern for dot row 8|
The pattern making up each dot row is specified as the ASCII code equivalent of the binary number whose "1" bits correspond to dots which are turned on, and whose "0" bits correspond to dots which are turned off. For example, specifying 63 (where 63 is the decimal equivalent of 00111111B) for byte 4 causes all dots in dot row one to be turned on when the character code specified in byte 3 is displayed; conversely, specifying 0 (00000000) causes all dots in the applicable row to be turned off.
A sample definition for character code 230 is shown below:
CTRL-^,?,CTRL-L, CTRL-R, CTRL-0, CTRL-@
The altered code can be seen by pressing GRPH-6.
Controls the key repeat function. This sequence consists of three bytes as follows:
If 0 is specified for n, the repeat function is turned off. If 1 is specified, it is turned on.
Sets the starting time for the key repeat function. The sequence consists of three bytes as follows:
The repeat function starting time is equal to n/64 seconds where n is a number from 1 to 127 (decimal) or 1 to 7F (hexadecimal).
Sets the duration of the key repeat interval. This sequence consists of three bytes as follows:
The key repeat interval is equal to n/256 seconds, where n is a number from 1 to 127 (decimal) or 1 to 7F (hexadecimal).
Sets the arrow key codes. This sequence consists of six bytes as follows:
|Byte 3:||Code for|
|Byte 4:||Code for|
|Byte 5:||Code for|
|Byte 6:||Code for|
Sets the SHIFT + arrow key codes. This sequence consists of six bytes as follows:
|Byte 3:||Code for SHIFT +|
|Byte 4:||Code for SHIFT +|
|Byte 5:||Code for SHIFT +|
|Byte 6:||Code for SHIFT +|
Sets the CTRL + arrow key codes. This sequence consists of six bytes as follows:
|Byte 3:||Code for CTRL +|
|Byte 4:||Code for CTRL +|
|Byte 5:||Code for CTRL +|
|Byte 6:||Code for CTRL +|
For further details of the arrow code setting see the OS Reference Manual.
Clears the keyboard buffer of all unprocessed input characters.
Keyboard ESC, CTRL-6
The ESC 247 code allows the programmer to switch the various shift keys on and off. Thus the numeric key pad can be set on, or the shift key held down. The key state is set to normal by the user pressing the appropriate key, so it is advisable to program with the possiblity in mind that the key may be reset outside program control.
The sequence of characters is as follows:
Numbers which may be specified for n and their meanings are as follows:
|CTRL-F||6||6||CAPS LOCK SHIFT|
This sequence does nothing if numbers other than those above are specified for n.