Yellow Pig's BBC Computer Pages

The BBC Master 512

Display Control Sequences

Everyone who uses the BBC Micro in native mode (ie as a true BBC Micro) knows that you can control how the screen operates by writing to it various "control codes". You can do this from BBC Basic using the VDU command, or in many instances from the command line simply by pressing CTRL with other keys. Some of the controls are single characters, like VDU 12 (which clears the screen). Others are sequences, like VDU 19,... (which is used to change the colour palette).

Perhaps not everybody realises that a similar system exists on the Master 512 running DOS-Plus. The control sequences are very different from those of the native BBC, and look rather more like the Escape sequences used to control many printers. Also, the collection of functions they can perform is rather different. Looked at as a whole, the 512's control sequences seem a rather motley collection, with various sequences duplicating one another. The reason for this is that there are a number of different sets of sequences, each with its own history. Master 512 DOS-Plus has been designed to be reasonably compatible with a number of other systems, so the sequences from each system have been included.

Unlike the native BBC Micro, on the Master 512 you cannot enter the control sequences at the command line. This is because practically all of them begin with an "Escape" character (ie the character with an ASCII value of 27). COMMAND.COM understands pressing the Escape key as a signal to abandon the current command line. Consequently, when you press the "Escape" key the "Escape character" is not sent to the screen driver. There are, though, at least three ways in which you can use the sequences quite easily.

			You can include them within text files. When a text file containing control sequences is TYPEd to the screen, the sequences are acted upon.
			In a rather similar way, you can include them in ECHO lines in batch files. As the line is displayed on the screen the controls are actioned.
			If you are programming, then you can send control sequences to the screen driver in the same way as you send normal characters and character strings.

Using these facilities you can get some reasonably good effects from simple text files. The results are maybe not as stunning as those possible with the native screen modes, but still they can be more interesing than plain, unadorned text.

To give you an idea of what is possible, download the demonstration file, and at the 512's command line try entering:

TYPE DEMOCTLS.TXT /P

(the "/P" is important) and see what you get. After you have done so, look at the file with a word-processor to convince yourself that it is just text with command codes included.

Do not expect the control sequences all to work in quite the same way on a true PC-compatible. Some of them will (at least if ANSI.SYS was loaded on system boot), but others have never been a part of MS-DOS, and some are pure Acorn.

One detail is worth watching if you want to use these control sequences seriously. The Master 512 runs in two modes, known as "PC Mode" and "CP/M Mode". In PC Mode the screen has 25 lines. In CP/M Mode the bottom line is not used, so the screen has only 24 lines. Normally when you are at the DOS prompt, and this includes TYPEing a text file, the machine is in CP/M Mode. If you re-load COMMAND.COM (simply by entering COMMAND at the prompt) it will go into PC Mode. This can make a difference to exactly how much text is on the screen at once, and may occasionally affect the appearance when a pause occurs if you are using the /P option with TYPE.

If you want to know more about how the 512's screen system works, then have a look at the screen information (in this collection). This explains about screen modes and attributes, as well as a number of other more obscure items.

Control Characters and Sequences

There are 4 kinds of control sequences recognized by 512 DOS-Plus:

			Single control characters.

			"ANSI.SYS" sequences. These all begin Esc [ (ASCII 27,91). A file called ANSI.SYS exists for true PC-compatibles running MS-DOS. This can be started at system boot, and if it is then the screen responds to sequences beginning Esc [. The Master 512 has no separate ANSI.SYS file. The sequences are always available. Note, though, that not all facilities of a PC's ANSI.SYS are incorporated in the 512's system and, of those that are, some of them contain bugs.

			"Acorn specials". These sequences begin with Esc # (ASCII 27,35). They are exclusive to the Master 512, and will not be found on any other system.

			Other sequences beginning with Esc. These have various origins, and so some functions appear more than once within the group. They have mostly come into DOS-Plus through its CP/M heritage, and so they cannot be expected to work on MS-DOS machines.

A number of the controls can take parameters. There are, though, various ways of entering these.

For the ANSI.SYS sequences, the usual pattern is that the sequence begins with Esc [, the parameter(s) follow, and there is a controlling character to terminate the sequence. The parameters are entered as decimal numbers (ie genuine strings of the characters "0" to "9") separated by the semi-colon character (";" – ASCII 59).

With other sequences, the parameter(s) come after the controlling character. For these each parameter is entered as a single character, and they follow one another directly if there is more than one, with no spaces or other separators. Things are set up so that every character apart from the initial Esc is a normal printing character (with ASCII value above 31). To make this work, when numerical parameters are required you may have to include the character whose ASCII value is 32 more than the appropriate number. There is one exception to this, namely the second parameter of the palette change sequence Esc # D. This is probably another bug, but you can normally get round it without too much difficulty.

In the following table c1, c2, etc denote single characters. On the other hand, the symbols N1, N2, etc mean decimal numbers made up of number characters. "Esc" means the Escape code, with ASCII value 27. The spaces between the characters are only included here for clarity, and they must be omitted in actual use. It is important whether a character is in upper or lower case.

Single Control Characters

	Character	Meaning

	NUL (ASCII 0)	Does nothing.

	Ctrl/G (ASCII 7)	"Bell" character. Sound a bleep.

	Ctrl/H (ASCII 8)	Back-space. The cursor moves back one place on the screen without deleting the character there. Nothing happens if the cursor is already at the top-left hand corner of the screen.

	Ctrl/I (ASCII 9)	Tab. Enough spaces are output to move to the next tab-stop position.

	Ctrl/J (ASCII 10)	Line feed. The cursor moves down one line. The screen scrolls up if the cursor was on the bottom line.

	Ctrl/M (ASCII 13)	Return. The cursor moves to the beginning of the current line.

Note that the other active combinations with the Ctrl key (Ctrl/C, Ctrl/P, Ctrl/Q, Ctrl/S, etc) are not special characters for the screen driver. They are understood as controls by the keyboard reading routine and acted on as the keys are pressed. All characters other than the above and the Escape character will type onto the screen as normal characters with their usual IBM-style designs.

"ANSI.SYS" Escape Sequences

Code sequence

Meaning

Esc [ N1 A

There is a bug in this. It should move the cursor up by N1 lines (or 1 line if N1 is omitted). In fact the cursor ends up one space above and one space to the left of where it ought.

Esc [ N1 B

This should move the cursor down by N1 positions (again with 1 as default). It has the same bug as the previous sequence.

Esc [ N1 C

The same bug again. It should move the cursor N1 places to the right.

Esc [ N1 D

Once again the same bug. It should move the cursor N1 places to the left.

Esc [ N1 ; N2 H

Move the cursor to row N1, column N2. Important note: with this sequence the top left of the screen is position (1,1) and not the more logical (0,0). (This quirk is clearly the origin of the bug in the four sequences above – a programmer remembered it at one point and forgot it at another.) You can move the cursor onto the bottom line of the screen by using this sequence with N1=25. If you do not use this (or an equivalent) and if the screen is in CP/M Mode, then the display will normally scroll up rather than use the last line.

Esc [ N1 ; N2 f

Move the cursor to column N1, row N2. (This is the same as Esc [ N2 ; N1 H – identical to the previous command except that the co-ordinates are reversed.)

Esc [ N1 J

Clear all or part of the screen, depending on the value of N1:

	N1=0 (or omitted)	clear from cursor position to end of screen.
	N1=1	clear from start of screen to character before cursor.
	N1>=2	clear whole screen and home cursor.

Esc [ N1 K

Clear all or part of the line containing the cursor, again determined by the value of N1:

	N1=0 (or omitted)	clear from cursor to end of line.
	N1=1	clear from start of line up to character before cursor.
	N1>=2	clear whole of line.

Esc [ L

Insert a line at the cursor. The screen from the cursor downwards scrolls down by one line, leaving a blank line.

Esc [ M

Remove the line at the cursor. The screen from the cursor line downwards scrolls up by one.

Esc [ s

Store current position of cursor. This causes the current cursor position to be recorded by the system, so that a future "regain cursor position" can make it to come back here.

Esc [ u

Regain position of cursor (as stored by Esc [ s or Esc j). The cursor will go back to the position it was at when the "store position" sequence was issued.

Esc [ N1 m

On a full PC-compatible this sequence can be used to set the character attributes. It is implemented on the 512 in a very limited way. The effect differs depending on whether the current screen mode is a 2-colour or 4-colour one. The results of using it are:

In 2-colour modes:

	N1=0 (or omitted)	set normal video.
	N1<>0	set inverse video.

In 4-colour modes:

	N1=0 (or omitted)	set foreground colour to 3 (normally white).
	N1<>0	hide text (by making the foreground colour the same as the background).

Any use of this sequence (with any value of N1 or none) will reset the character intensity (ie bold font) to normal. (Whether this is intentional may be open to question, but it happens.)

Esc [ = c1 h

Select screen mode. c1 must be a single decimal digit "0" to "9" (ASCII 48 - 57). The screen mode indicated by this will be selected (modulo 8 if character "8" or "9" is used). c1 can be omitted and then Mode 7 is selected. The modes here are the DOS screen modes, as also selected by the PCSCREEN.EXE utility. See the screen information for more details of the modes.

Esc [ ? c1 h

This works exactly as the previous sequence. It selects the screen mode.

"Acorn Special" Escape Sequences

Code sequence

Meaning

Esc # A c1 c2

Write a number of copies of character c2 to the screen. The number of copies written is the ASCII value of c1 minus 32. Thus if c1 is ! (ASCII value 33), 1 copy will be written, if it is " (ASCII 34) then 2 copies, etc. Make sure you do not over-run the end of the screen or the system may get confused.

Esc # B

Clear screen and draw a neat border, including box for title (to be inserted on line 1). The cursor does not move. Note: This works by writing some "top-bit-set" characters to the screen. In graphics modes (modes 4/5 and 6) these do not normally have the same appearance as in text modes. (A program can set them up to its own set of shapes, but they are undefined initially.) The result of this is that the sequence only works correctly in text modes. The border also looks rather poor in DOS Mode 7 or after Esc # }.

Esc # C c1

Set the attributes of a number of characters. See screen information for more about attributes. On the 512 the only attributes a character may have are intensity (ie bold or normal font) and (for 2-colour modes) inverse/normal video or (for 4-colour modes) foreground colour. The current attributes can be set by sequences like Esc p, Esc r, etc (see below). This sequence sets the attributes of characters to the current setting. The number of characters affected is 32 less than the ASCII value of c1 (as in the Esc # A string, described above). The first character is the one at the cursor, and the others follow it. The cursor ends up at the position after the last character affected. As with Esc # A, you should ensure that the cursor does not run off the end of the screen.

Esc # D c1 c2

Define one colour of the palette. c1 is the logical colour and c2 is the physical colour. Only the lowest 3 bits of the ASCII value of c1 are relevant, and so the character might as well be a digit between 0 and 7. This number is the Master 512 DOS-Plus logical colour, ie:

	0 and 1	colours for normal 2-colour modes, background and foreground;
	2 and 3	colours for the monochrome GEM screen;
	4 to 7	colours for all 4-colour modes, both DOS and GEM.

Character c2 defines the physical colour that will be used for this logical colour, and the value specified is the normal BBC Micro colour value (0 – black, 1 – red, etc). However, you need to be a bit careful with c2, probably because of another bug in the system. If c1 lies between 0 and 4 inclusive (so you are defining a colour for a 2-colour mode or just the background for a 4-colour mode) then only the four least significant bits of c2 are relevant. In this case you can just use a normal printing character for c2. "2" will give green, "L" will give flashing blue/yellow, etc. However, if c1 is greater than 4 then the ASCII value of c2 must actually be less than 16. If you try this sequence with c2 having a value of 16 or greater, and c1 equal to 5, 6 or 7, then you are likely to make rather a mess of the screen in DOS Modes 0/1 or 4/5 (though, just to add to the confusion, 4-colour GEM will still work properly).

Esc # {

Remove gaps between lines (so that the display is compressed towards the centre of the screen, as in normal DOS Modes 0 to 6).

Esc # }

Insert gaps between lines (so the display fills the screen, as in normal DOS Mode 7).

Other Escape Sequences

Code sequence

Meaning

Esc A

Move cursor up 1 line. The cursor will not go beyond the edge of the screen.

Esc I

Move cursor up 1 line. Unlike the previous sequence, with this if the cursor is at the top of the screen, then the screen scrolls down one line to make room.

Esc B

Move cursor down 1 line. The cursor will not go beyond the edge of the screen.

Esc C

Move cursor right by 1 character position. Again, the cursor will not go beyond the edge of the screen.

Esc D

Move cursor left by 1 character position. Once again, the cursor will not go beyond the edge of the screen.

Esc H

Home cursor (to top left of screen) but without clearing the screen.

Esc Y c1 c2

Move cursor to position defined by c1 and c2. The relevant values are again the ASCII values of the characters minus 32. c1 defines the row number, c2 the column. The top left of the screen is position (0,0), so Esc Y followed by two spaces (ie two characters with an ASCII value of 32) has the same effect as Esc H.

Esc = c1 c2

Same as Esc Y c1 c2.

Esc E

Clear screen and home cursor.

Esc J

Clear screen from the cursor position up to the end of the screen.

Esc d

Clear screen from the start up to the character position before the cursor.

Esc l

Clear the line containing the cursor.

Esc K

Clear the current line from the cursor position to the end of the line.

Esc o

Clear the current line up to the character position before the cursor.

Esc L

Insert a line at the cursor. (The screen from the cursor line scrolls down.)

Esc M

Remove the line at the cursor. (The screen below the cursor line scrolls up.)

Esc N

There is a bug in this. It is meant to delete the character at the cursor and close up the line. It actually also copies the first character of the next line onto the end of the current line and replaces that character with a space. This is consistent, but less than useful!

Esc j

Store current cursor position. See Esc [ s for further explanation.

Esc k

Regain stored cursor position (as set by an earlier Esc j or Esc [ s).

Esc b c1

"Set foreground colour." This is of limited effect on the 512 (again see screen information for a discussion of attributes). In 2-colour modes only bit 3 (value 8) of the ASCII value of c1 is relevant. This is the "intensity" bit, and the bold font is used if it is set. In a 4-colour mode bits 0 and 1 are also relevant and specify the foreground colour.

Esc c c1

"Set background colour." Again of limited effect on the 512. In a 4-colour mode the sequence has no visible effect at all. In a 2-colour mode only the bottom 3 bits of the ASCII value of c1 are relevant. If these are all 0 (so c1 MOD 8 is 0), then text appears in normal video. If any of these bits is set, then text is in inverse video.

Esc f

Make the flashing cursor invisible. Note that the cursor will automatically be re-enabled when you return to the DOS prompt at the end of the text file or program.

Esc x c1

Works exactly like Esc f and hides the cursor. The value of c1 is ignored.

Esc e

Make the flashing cursor visible again.

Esc y c1

Works exactly like Esc e and reveals the cursor. The value of c1 is ignored.

Esc p

This changes the current attribute setting. The effect will depend on the screen mode:

	2-colour modes:	Set inverse video.
	4-colour modes:	Hide text (set foreground colour to 0).

This sequence also sets the bold (ie "intense") font off.

Esc )

Same as Esc p.

Esc q

Another sequence which affects the current attributes and whose effect varies with the screen mode in use:

	2-colour modes:	Set normal video.
	4-colour modes:	Set foreground colour to 3 (normally white).

This sequence also sets the bold (ie "intense") font off.

Esc (

Same as Esc q.

Esc r

Set intense (bold font) text on.

Esc u

Set normal font text (ie "intensity" off).

Esc w

Turn off wrap at line end. After this, when you type beyond the end of a line the cursor does not go on to the next line. Rather it remains at the last character of the line, so subsequent characters continue to overtype this one character until a true "Return" character occurs. This might be useful (like the native Master's "scroll protect" option) to place a character in the last possible screen cell without having the screen scroll up.

Esc v

Turn on normal wrapping at line end.

Esc z

Restore some normality! This resets the current character attribute to the default (bold off, normal video in 2-colour modes, foreground colour 3 in 4-colour modes). It also sets the end-of-line wrap on and makes sure the flashing cursor is on. Other features that may have been changed remain as they are.

Esc F

This causes certain characters to be translated into other (mostly graphics "top-bit-set") characters before they are displayed on the screen. The result is that simple graphics may be used by outputting only normal keyboard characters. The best way to find out what becomes what is simply to try them out. All the characters affected are either symbols or lower case letters. Upper case letters and numerals do not change. The character "^" (ASCII 94) becomes character 7, and makes the machine beep. Some lower case letters are merely converted to NULs (ASCII 0) and do nothing.

Esc G

Cancels the effect of Esc F. Characters are all output according to their own values.

Esc 6

Turn function key expansion off. This is rather an oddity in that it affects the keyboard rather than the screen. It is of limited use on the 512 since function key expansion only works in CP/M Mode, and also you cannot re-define the function key strings. After using it the function keys return various graphics (ie top-bit-set) characters instead of the strings they usually produce at the command line. The function keys are not affected in PC Mode. Note that the cursor keys are also affected, but only when a .CMD program is running (not when in PC Mode and not at the command line). Note also that the "6" in the control sequence is a genuine decimal digit character, ASCII value 54.

Esc 7

Turn function key expansion on. This cancels the effect of the previous sequence.

Various other Escape sequences are recognized by the system, but do not actually do anything. These include Esc 0, Esc 1, etc up to Esc 5. They might conceivably be useful as place holders which do not appear when a file is viewed.