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.