Omnicalc 2 Expansion & Conversion Kit

OMNICALC 2 EXTENSION KIT





The programs contained on this tape have been designed tor use


with the OMNICALC 2 Spreadsheet for the 48K Spectrum. They can


broadly be divided into three types - which between them satisfy the


majority of requests we have had for extensions.





Firstly there are the expansion programs, which allow users to


add in their own BASIC-like commands to OMNICALC 2. This


enables various wafadrives and floppy-disk drives to be incorporated


within the program.





Secondly there is a screen-dump routine, which is parameter


driven and can be used to produce a screen COPY on any graphics


printer.





Lastly there is a routine to print out formulae. so that complete


documentation is available on models produced by OMNICALC 2.





We hope that these routines will help you get the full benefit from


your OMNICALC.





Expansion programs


Four programs that allow you to add in your own commands to


Omnicalc 2 are included on the tape.





To extend 'om2' use 'om2ex'; for 'om64000' use 'om64000ex';


for the Timex 2068 programs 'tom2' use 'tom2ex' and for 'tom64000'


use 'tom64000ex'.





All the programs work identically:





1. Load the required expansion program.





2. Enter the commands that you want added to Omnicalc 2 as if they


were BASIC lines in lines 1 - 9.





3. Type in a set of keywords to enable you to select between these


commands, entering these in a REM statement in line 10.





4. Call a machine code routine at address 40000 to check the


format of your BASIC lines.





5. Providing no error occurs call the machine code routine at


address 41250 which allows you to load the original Omnicalc 2


program that you want to extend into the computer and incorpor-


ates your extensions.





6. Now save the extended program under any name you choose


when you now use your extended Omnicalc 2 program you will


find a new function - function Z � which, when chosen displays the


option keywords you set up in line 10, enabling you to select a com-


mand by pressing the first letter of the keyword. By setting up the


variables in your commands as if they were elements in the arrays Z


and z$ for numeric and string variables respectively, and making the


element name the same as the prompt you want to see on the screen,


you can also get the program to ask you for any variable information in


your commands. The example that follows should make this clear:





In this example we shall assume that you wish to extend 'om2',


that you are saving and loading to tape (from this you should easily be


able to work out the commands for other devices) and that you have


a printer and from time to time you wish to send control codes (to


change character size or line spacing etc). You would proceed as


follows:





A. Load the program 'om2ex' (in this case) from the tape. Upon


loading this will set up some machine code and do a NEW. So do


not be alarmed when the Sinclair Copyright message reappears.





B. Type in your commands in lines 1-9 and your keyword options in


line 10. In this case this means the following:





1 SAVE z$ (model name)


2 LOAD z$ (model name)


3 SAVE Z$ (workarea name) CODE 59392 512


4 LOAD z$ (workarea-name) CODE


5 LET c=z (no-of-codes) : LPRINT CHR$ z (ch1);: IF c>1 THEN


LPRINT CHR$ z (ch2);: IF c>2 THEN LPRINT CHR$ z (ch3) ;


10 REM Save-model/Load-model/Copy-work/Restore-work/


Print?





Note





a) You need not fill in all lines 1-9.





b) Line 10 has all the keywords written out fully, they are in the


sequence of the commands and must be separated by "/"s, and


the first letter of each keyword is different so that one letter


uniquely defines a command.





c) In lines 1-4 the item you are saving is an element in the array z$.


This means that before you execute this command the element


name (ie. whatever you put in brackets) will appear on the screen


as a prompt, and you can then key in the actual name that you


want to use (which can be up to 10 characters long)





d) Models are saved and loaded as if they were programs (see lines


1 & 2).





e) The workarea is saved and loaded as a 512 byte CODE block. This


starts at 59392 for om2 and tom2, and for om64000 and


tom64000 at 57856.





f) Colons can be used to build up relatively complex statements as


in line 5 which asks you how many control characters you want to


send to the printer and the numeric equivalents of each character.


It then only actually LPRINTS the number you wanted to send


(hence the IF statements).





g) The numeric variable 'c' is the only variable you are allowed to use


(other than the z and z$ arrays which are not interpreted by the


extended Omnicalc 2 program as real variables anyway). If you


use any other variable your information will become corrupted. Do


not use FOR-NEXT loops or INPUT, GOTO or GOSUB statements


as part of your commands.





C. Call the machine code routine at address 40000 (by the com-


mand RANDOMIZE USR 40000). If you do not get report code O, it


implies that there is something wrong with your commands. To


find out more about the error refer to the table of error numbers


below. (Ignore the error text that appears on the screen).





Error No. Meaning


1 There is no line 10.


2 Line 10 is not a REM statement (or contains REM and


nothing else).


3 Line 10 contains more than 64 prompt characters.


4 Line 10 contains characters that are not ASCII codes 32


-127.


5 A line number greater than 10 is present.


6 There are no lines 1-9.


7 Line 1-9 take up too much space (About 400 charac-


ters is tree for your commands which should almost


always be sufficient).





D. You can now proceed to produce an extended version of your


program by calling the routine at address 41250 (use the com-


mand RANDOMIZE USR 41250) If you immediately get error


report 8, it simply means that you either did not attempt or had


an error while running the previous section. Otherwise place your


original Omnicalc 2 tape in a cassette recorder and load in the


program you wish to extend (om2 in thus case). The computer will


wait until it meets the required program on the tape and then


display the message 'FOUND'. It will then load the program before


making the extensions and returning you to BASIC.





E. Immediately save the extended program to whatever device and


under any name you choose. It should ideally be saved as a


SAVE "name" LINE 1). Do not do anything else before saving the


program as this may cause corruption.





F. When you now load the extended program and press 'Z' the key-


words from line 10 will be displayed. From these you can select


which command you want to use by pressing the first letter of the


relevant keyword. If, in turn, you had set up your commands to


include prompts, by using the arrays z$ and z, the prompts will be


displayed and whatever you key in in response to them will re-


place the z$ (prompt) when the command is actually executed.


For example in this case if you press S, then the prompt 'model-


Name?' will appear, and if you reply 'MODEL 2' then the command


that will be executed will be SAVE "MODEL2".





G. Errors can occur in two ways. Firstly you may have put in more


keywords than you have commands, in which case the Omnicalc


2 program will give you the error message 'not heading'. Sec-


ondly an error may occur when one of your added commands is


executed. In this case you will normally get the error message


'calc. error' with the error number being shown on the line below.


However some hardware devices do not handle errors in the


normal Spectrum fashion but may alter BASIC variables and


return you to BASIC. You can return to the Omnicalc2 program by


the command RANDOMIZE USR 63081 for om2 and tom2 (for


om64000 and tom64000 use RANDOMIZE USR 61545). Unfort-


unately in this case corruption to other variables may have oc-


curred, so you are advised to double-check your model.





H. 1024 bytes of space is needed to extend your Omnicalc 2 pro-


gram. This may mean that larger models may no longer fit and you


may be forced to compress them within an unextended program.





Screen dump routine


The tape contains a program called 'COPY' which allows you to


construct a machine code routine to produce single or double size


screen dumps to any graphics printer. It is particularly intended for


use with the RS232 port of Interface 1 and can be used both to print


histograms from OMNICALC 2 and as a sub-routine in your other pro-


grams. To customise the routine for your printer you need to supply


various parameters, as follows:





a) The control string needed at the start of the screen dump. This


should tell your printer the line spacing, dot spacing etc needed


to produce a graphic image.





b) The control string needed at the end of the screen dump to reset


the print for text.





c) The control string needed at the start of each line. This would tell


the printer that what follows is graphics, and probably how many


bytes of graphics data to expect. (This would be 256 for a single-


size screen dump)





d) The control string at the end of each line. Normally this would just


tell the printer that the line has ended ,and would consist of either


a single carriage return code or a carriage return followed by


line feed.





The strings in a, b and c above can be up to 7 characters long and


must be preceded by a further character indicating how many


characters are actually used, making a maximum of 8 in all. The string


in d above is limited to 3 characters but again must be preceded by a


length byte making a maximum of 4. If any of the control strings is not


needed then you must still tell the routine by putting zero in the length


parameter.





e) You must supply 8 parameters telling your routine how your


printer expects each of the 8 bits un a byte of graphics data to be


derived, and 1 further parameter indicating how many rows are


printed at once. It is these features that differ between different


printers. For example, the Epson MX-100 can print 8 rows at a


time, with the top row on the print-out going in bit 7 (ie. The 1st of the


8 parameters). On the other hand, the Seikosha GP100A can only


print 7 rows at at a time and the top row on the print-out goes in bit 0


(ie. the last of the 8 parameters)





To work out the 8 parameters, imagine the screen as a series of


Rows of dots with the top row as row 0, the row below this as row 1 etc.


For each of the parameters you must say which row the equivalent bit


in the graphics data is made up from. Thus in the case of the Epson,


the parameters are 0, 1, 2, 3, 4, 5, 6, 7 and the parameter indicating


how many rows are printed is 8. However for the Seikosha, the situ-


ation is more complex, as the format of the graphics data byte


requires that bit 7 is always set to the value 1. If a bit must always be a 1,


you should give the equivalent parameter the value 255. (Similarly, if


you have a printer which must have a 0, you should give the


equivalent parameter the value 254). Thus for the Seikosha the eight


bit parameters are 255, 6, 5, 4, 3, 2, 1, 0 and the parameter indicating


how many rows are printed is 7.





All the information needed to deduce these parameters should be in


your printer manual.





f) a to e above have been considered for a single size screen dump.


The whole set of information must now be repeated for a double-


size dump.





You will probably find that a, b c and d are very much the same -


the only likely difference is that the number of graphics bytes in c will


double as each byte is printed twice. Unfortunately however, e is more


complex. In fact instead of supplying 9 parameters, you now need to


supply 2 lots of 9 parameters, making 18 in all.





To understand this, consider that a double size screen dump re-


quires each row on the screen to occupy two rows on the print-out.


Thus if the printer actually prints 7 dots at a time it can only cover 3.5


screen rows on one pass of the print-head. On the first pass the 7 dots


you would print might be 2, corresponding to screen row 0, 2 corre-


sponding to screen row 1, 2 corresponding to screen row 2, but only 1


corresponding to screen row 3. If on the next pass you did not print the


remaining dot from screen row 3, you would not have a uniform


double size print.





For the Epson the 18 parameters you need to supply are as


follows:





0, 0, 1, 1, 2, 2, 3, 3, 4, 0, 0, 1, 1, 2, 2, 3, 3, 4. As this has


8 bit graphics this is simply the same 9 parameters printed twice (advancing 4


screen rows at the end of each). However for the Seikosha GP100A


the 18 parameters do not repeat as this has 7-bit graphics. The


parameters in this case are:


255, 3, 2, 2, 1, 1, 0, 0, 3, 255, 3, 3, 2, 2, 1, 1, 0, 4. As you


can see, the routine advances 3 screen rows at the end of the first pass,


but 4 at the end of the 2nd pass.





To produce and then use your screen dump routine proceed as


follows:-





1) Load "COPY" from the tape. This will load some bytes called


"COPYCODE".





2) The program will then stop, to allow you to add/edit lines. The par-


ameters needed by the routine are fed in by data statements. To


help you, suggested parameters for the Epson MX100 (lines 100-


190), the Seikosha GP100A (lines 200-290) and the Microline 84


(lines 300-390) are supplied. If your printer is not one of these,


then you will probably find it easy to adapt one of the above for


your purposes. Please note that the line numbers are important ie.


lines ending in 00 (line 100, 200 etc) are for the control strings


needed right at the beginning of a single size screen dump. Also


note that in all cases it is assumed that a carriage return at the end


of a line will automatically cause a line feed (lines 130, 180, 230,


280, 330, 380). If you require a separate line feed character then


change these lines to "DATA 2, 13, 10"





3) When you are satisfied with your data then GOTO line 9000. This


will ask you for the start line of the DATA statements that you wish


to use and will then set up your parameters as part of the machine


code routine.





4) You can test your routine by typing in GOTO 9900. This will draw a


circle on the screen and then print out a single and double size


version screen copy.





5) Your customised code is located at address 64000 and occupies


256 bytes. You should now save the code (by eg. SAVE


"CUSTOMDUMP" CODE 64000, 256).





6) You can load this code anywhere when it comes to be needed.


Note that being 256 bytes long the code will fit in the printer buffer


of the Spectrum at address 23296. For OMNICALC 2 you have


two choices. You can either put it in the Spectrum printer buffer or


you can use it with om64000 or tom64000 by putting it above


address 64000. In both cases remember to load the code before


loading your OMNICALC 2 program.





If you are calling the routine from OMNICALC 2 you will need to set


the Graphics address within function X. If you want the double size


screen dump, then you should set this to the address at which you


loaded the code. For the single-size option add 1 to the address


where the code was loaded. If you are using the screen dumps as


part of a BASIC program, then you can call it via a RANDOMISE USR


xxxxx statement where xxxxx is the address where the code was


loaded for a double size dump, or this address +1 for the single-size


dump.





Note that to use thus code for a TIMEX 2068 you will need to do two


POKE commands. These commands are POKE 64006 48, and


POKE 64007, 18 and should be done immediately after 1 above.





You should also be aware that the printer information is set to


channel 3. If you are using the RS232 port in Interface 1 then you must


ensure that thus has been opened as a 'b' channel.





(The alternative is to execute the command POKE 64004, 4


Before 1 above. This will direct any print out to channel 4 and you can


Open this as a 'b' channel in your programs. If you are using your


screen dump code with OMNICALC 2 remember to open this


channel before loading the program, as the OPEN command in the


program only works on channel 3).





Printing Formulae


The tape contains a machine code routine called 'formprint'


which is used for printing the equations used in your models. The


routine is 256 bytes long and is fully relocatable. There are two


possible places where you might like to locate the routine:





a) In the printer buffer at address 23296. Obviously if you are using a


ZX-printer or a printer interface which itself has software that sits in


this area, then this is unpractical.





b) Above address 64000 providing that you are using om64000


or tom64000.





Remember that you should load the code before loading your


OMNICALC 2 program.





To call the routine from OMNCALC you have two choices. If you


have taken advantage of an expansion program you can include the


command to print the formulae as part of the options in your new


function Z. (The command you need is RANDOMISE USR xxxxx


where xxxxx is the address to which you loaded the code).





The alternative is to 'cheat' and to fool the program into printing the


formulae when it thinks it is doing a screen copy. To do this you should


set the graphics address in function X to the address at which you


loaded the 'formprint' code. If you now use the graphics function to


produce a histogram, and press graphics as if you were going to do a


screen copy, you will find that a list of formulae is printed. You can


always of course reset the graphics address to what it should be


when you have finished.





Please remember that unlike the other programs on the tape


'formprint' is supplied as CODE so you must load it as LOAD


"formprint" CODE xxxxx, where xxxxx is the address you wish it to start


at. Should you wish to save the routine, to microdrive for example, you


will need to know that the routine is 256 bytes long.





Two versions of the code routine are supplied on the tape. These


are "formprint" which is for the Spectrum and "tformprint" which is for


the TIMEX 2068.