The INFORMANT
Version 1.00
BBC Micro/Master Series Help ROM
(c) 1990
by Alan Blundell
Page 1
The INFORMANT ROM contains textual help information on a range of topics
selected to assist the 'serious' programmer to access the facilities
offered by the BBC Micro series and to reduce the dependance on manuals
for reference for information on how to access those facilities.
Most of the facilities are accessed by the standard
*HELP <topic> ...
syntax. Abbreviations are permitted according to Acorn conventions, using
a period (.) to indicate abbreviation.
The range of help topics is indicated by the INFORMANT main help message,
as generated by the command
*HELP HELP (minimum abbreviation: *H. H. )
This command generates the following message (assuming that the INFORMANT
is present in ROM or in SRAM):
Help is available on the
following topics:-
MEMUSE / VECTORS / FLAGS
VDU / PLOT / TELETEXT
ASCII / INKEY
EVENTS / ADVAL
PITCH / DURATION
OScalls
OSARGS / OSASCI / OSBGET / OSBPUT
OSCLI / OSEVEN / OSFILE / OSFIND
OSGBPB / OSNEWL / OSRDCH / OSRDRM
OSWORD / OSWRCH / GSINIT / GSREAD
Star commands:-
*ASCII <string> - Returns the ASCII
code(s) of <string>
*VDU <code>.. - Opposite of *ASCII
*DTOH <num> .. - Number converter.
*HTOD <num> .. - " "
Each of the topics listed produces its own textual response, ranging from
a short message to a lengthy, detailed response which goes on for several
screenfuls (such as *HELP MEMUSE, which provides a detailed breakdown of
Page 2
the use of RAM in the BBC Micro and Master series machines).
As sample output, the texts produced by *HELP OScalls (minimum
abreviation: *H. O.) and by *HELP OSFILE (*H. OSF. ) are reproduced
below:
*HELP OScalls
OS Calls summary.
_________________
Name Addr Function
OSCLI FFF7 Command line interpreter
OSBYTE FFF4 *FX calls
OSWORD FFF1 See OSWORD
OSWRCH FFEE Send char to vdu drivers
OSNEWL FFE7 Send CR/LF to vdu drivers
OSASCI FFE3 As OSWRCH/OSNEWL if necc.
OSRDCH FFE0 Read char from input
OSFILE FFDD Load/save files
OSARGS FFDA Filing system bits
OSBGET FFD7 Get 1 byte from file
OSBPUT FFD4 Put 1 byte to file
OSGBPB FFD1 Multiple OSBPUT/OSBGET
OSFIND FFCE Open/close files
NVRDCH FFCB Non-vectored RDCH.
NVWRCH FFC8 Non-vectored WRCH.
GSREAD FFC5 Read char from input
string
GSINIT FFC2 Initialise for GSREAD
OSEVEN FFBF Generate an event
OSRDRM FFB9 Read a byte in paged mem.
>*HELP OSFILE
OSFILE call addr &FFDD indirected &212
XY point to parameter block, A holds
the reason for the call:-
A=0 Save a block of memory
A=1 Write file name + addresses for
Page 3
an existing file
A=2 Write load addr for existing file
A=3 Write exec addr for existing file
A=4 Write attributes for existing fle
A=5 Read a file's catalogue info into
the parameter block
A=6 Delete the named file
A=&FF Load the named file
(XY+6)=0 to addr in control block
(XY+6)<>0 to file's own load addr
Format of the parameter block:-
00-01 Addr of filename (ends with &0D)
02-05 Load address
06-09 Execution address
0A-0D Start address for save
Length of file when loading
0E-11 End address for save
File attributes when loading
X and Y are preserved on return.
In total, the ROM contains approximately 22Kbytes of help text, in
addition to the rom header code, code to handle the help requests and four
new '*' commands. This is achieved by compaction of the help text
messages.
The algorithm used to compress the texts is encapsulated in the body of
the BASIC program used to perform the compression. Although fairly basic,
the compression method used resulted in a useful saving of over 30%
overall, saving over 7Kbytes of ROM space (which wasn't in fact available
- the alternative would have been to put less into the ROM).
The compression program is stored on the distribution disc as file
COMPRES, and is listed as follows. It is based on work published in
Personal Computer World magazine in May 1985, but improved and customised
by me for the purpose of producing compacted texts for this work.
10REM Text compression
20
30GOTO 270
40
Page 4
50 Coding rules:-
60 1st 4 bits are
70 (0-9) space + 9 common chars
80 (aeiorstln).
90 (A-F) use 6 subtables with
100 the next 4 bits
110 (16 chars each: 6*16=96
120
130 Subtables are as follows:-
140
150 HEX A B C D E F
160 From 32 48 64 80 96 112
170 To 47 63 79 95 111 127
180
190 NB: 32 is used for newline,
200 127 is used for end of text.
210
220 Subtable is given by
230 (char-32)DIV16
240
250__________________________________
260
270IC%=0 :REM input counter
280OC%=0 :REM output counter
290OB%=0 :REM output byte buffer
300OBE=1 :REM Flag=1 if ^ empty
310DIM AV%(126-97)
320FORI%=97TO122
330READ C$
340IF C$<>"" AV%(I%-97)=VALC$
350NEXT
360
370REM define the set of 4 bit codes
380REM a bcde fghi jkl mn o pqr s t uvwxyz<space>
390DATA1,,,,2,,,,3,,,8,,9,4,,,5,6,7,,,,,,,0
400INPUT"Name of source file :"T$
410F1=OPENINT$
420INPUT"Name of destination file:"T$
430F2=OPENOUTT$
440
450REM Main loop
460REPEAT
470C%=BGET#F1
480IFEOF#F1 GOTO570
490IC%=IC%+1
500IFC%<33 GOTO 550
510IFC%<97 PROCout8:GOTO570
520A%=AV%(C%-97)
Page 5
530IFA%=0 PROCout8 ELSEPROCout4
540GOTO570
550IF C%=32 A%=0:PROCout4:GOTO570
560IFC%=13 C%=32:PROCout8 ELSEPRINT"Ignore input character ";C%
570UNTILEOF#F1
580C%=127
590PROCout8
600CLOSE #0
610PRINT"Input counter =";IC%
620PRINT"Output counter =";OC%
630PRINT"Compression is ";OC%*1000 DIV IC%/10;"%"
640END
650
660DEFPROCout4
670IF OBE OB%=A%*16:OBE=0:ENDPROC
680REM Full byte ready to output
690OB%=OB%+A%
700BPUT#F2,OB%
710OBE=1
720OC%=OC%+1
730ENDPROC
740
750DEFPROCout8
760OC%=OC%+1
770REM Set C%left & C%right
780CL%=C%DIV16+8
790CR%=C%AND15
800IFOBE BPUT#F2,CL%*16+CR%:ENDPROC
810REM output buffer is \ full.....
820OB%=OB%+CL%
830BPUT#F2,OB%
840OB%=CR%*16
850IFC%=127 THEN BPUT#F2,OB%
860REM ^ is to flush buffer.
870ENDPROC
In addition to the help texts, the INFORMANT contains four new '*'
commands designed to help the programmer, which seemed to me to fit into
the overall design of this ROM. The 4 are:
*ASCII <string> - Returns the ASCII
code(s) of <string>
*VDU <code>.. - Opposite of *ASCII
*DTOH <num> .. - Number converter.
*HTOD <num> .. - " "
Page 6
They are fairly self - explanatory; *VDU sends any ASCII codes given
(in decimal) directly to the VDU drivers, and may be useful for changing
MODE in programs where this might not otherwise be possible (?). *DTOH
will convert any number from decimal to hex, *HTOD will do the reverse.
Both will work with numbers in the range 0 - 65535 (&0 - &FFFF); larger
input numbers will produce indeterminate results.
------------------
Page 7