********* Welcome to Project 64! http://project64.c64.org The goal of Project 64 is to preserve Commodore 64 related documents in electronic text format that might otherwise cease to exist with the rapid advancement of computer technology and declining interest in 8- bit computers on the part of the general population. If you would like to help by converting C64 related hardcopy documents to electronic texts please contact the manager of Project 64. Extensive efforts were made to preserve the contents of the original document. However, certain portions, such as diagrams, program listings, and indexes may have been either altered or sacrificed due to the limitations of plain vanilla text. Diagrams may have been eliminated where ASCII-art was not feasible. Program listings may be missing display codes where substitutions were not possible. Tables of contents and indexes may have been changed from page number references to section number references. Please accept our apologies for these limitations, alterations, and possible omissions. Document names are limited to the 8.3 file convention of DOS. The first characters of the file name are an abbreviation of the original document name. The version number of the etext follows next. After that a letter may appear to indicate the particular source of the document. Finally, the document is given a .TXT extension. The author(s) of the original document and members of Project 64 make no representations about the accuracy or suitability of this material for any purpose. This etext is provided "as-is". Please refer to the warrantee of the original document, if any, that may included in this etext. No other warrantees, express or implied, are made to you as to the etext or any medium it may be on. Neither the author(s) nor the members of Project 64 will assume liability for damages either from the direct or indirect use of this etext or from the distribution of or modification to this etext. Therefore if you read this document or use the information herein you do so at your own risk. ********* This is the English translation from a scan of the German manual of MAGIC- FORMEL (Eng.: Magic Formula). Being a Dutchman, it is possible you will run into grammatical errors. Either tell me about them or simply ignore them. Have fun !!! ___ / __|__ / / |_/ Ruud Baltissen \ \__|_\ \___| URL: Ruud.C64.org --------------------------------------------------------------------------- MAGIC - FORMEL Instruction manual Version 1.2 GREWE COMPUTERTECHNIK GMBH RICHARD – WAGNER – STR. 73 D – 4350 RECKLINGHAUSEN TEL.: (02361) 181354 [Frontpage] --------------------------------------------------------------------------- Table of contents Chapter 1: INSTALLING THE MODULE page 3 1.1 Installation page 3 1.2 Starting up page 3 Chapter 2: MAGICAL-FORMEL-MENUS page 4 2.1 Reset-menu page 5 2.2 Interrupt-menu page 6 2.3 Snapshot-menu page 7 2.4 Hardcopy-menu page 9 Chapter 3: MAGICAL-FORMEL-WINDOW page 10 Chapter 4: MULTIGRAF page 17 Chapter 5: Command EXPANSION page 22 5.1 Toolkit page 22 5.2 DOS-commands page 23 5.3 Graphics page 25 Chapter 6: ASSEMBLER PROGRAMMING page 29 6.1 Machine language monitor page 29 6.2 Floppy monitor page 32 6.3 Assembler page 33 6.4 Illegal opcodes page 37 Chapter 7: CENTRONICS INTERFACE page 38 Chapter 8: FUNCTION KEYS page 38 Chapter 9: FLOPPY FUNCTIONS page 39 Chapter 10: CASSETTE SPEEDER page 40 Chapter 11: COMPATABILITY page 40 APPENDICES Pre-announcement MAGIC-FORMEL-128 Demoprogram Graphics Demoprogram Assembler Guarantee: We give a our products a guarantee of 6 months. Errors, which can be tracked back to errors in the material or the production, will be repaired without any costs during this time interval. Any further claims will be rejected. 1 --------------------------------------------------------------------------- GREW COMPUTERTECHNIK GMBH Richard-Wagner-Str. 73 4350 Recklinghausen Tel.: 02361/181354 Dear customer, I'm very happy that you decided to choose for our product MAGIC-FORMEL! My team and I put a lot of effort and time into the development of this module and we hope that you are satisfied with it. We put a lot of effort making sure that MAGIC-FORMEL is errorfree. And we still try to improve this module in every way. Of course we will implement these improvements in our product. Owners of an older version of Magic- Formel have the possibility to obtain the newest version for a small fee. The introduction of a new version will be announced in our advertisements in the computermagazines. The next pages will explain the control of MAGIC-FORMEL and I hope you are satisfied with it. With kind regards [signature] Michael Grewe Manager 2 --------------------------------------------------------------------------- 1) Installing the module 1.1) Installation The installation of MAGIC-FORMEL is quite simple. First you power off the computer and all connected peripherals! If you insert the module when the computer is on, you possibly damage your module and you devices. Where to insert the MAGIC-FORMEL? When you turn around your computer (C-64, C-128 and C-128D), so you look at the back of the computer, you will see several openings. You have to insert Magic-Formel in the big opening at the very left ("EXPANSION- or MODULEPORT). One of the broad sides of the module has a smooth surface. This one must point up. Take care that the MAGIC-FORMEL fits well in the moduleport, don't mind to give it a firm push. An exception is the SX-64: here the moduleport is situated at the top, der module has to be inserted in such a way that the smooth surface points to the front. 1.2) Starting up After you have inserted MAGIC-FORMEL, you can poer-on the computer and connected peripherals. If you use a floppydrive, it is important to power it up first (or at the same time as the computer). If you power it on later, some computers won't recognise it. If inserted in the C-64 or SX-64, MAGIC-FORMEL will report itself at once. The C-128 and C-128 will start up in 128-mode first. To activate MAGIC- FORMEL, you can do two things. 1) give the GO 64 command after the computer has started; 2) push the C= button (down left) during start up, the computer will start up in 64-mode, and MAGIC-FORMEL will report itself at once. 3 --------------------------------------------------------------------------- 2) MAGIC-FORMEL-MENUS First you should become familiar with one of the most important features of MAGIC-FORMEL, the control through menus. You immediately see the first menu when you power on: the RESET-MENU. Beside this RESET-MENU MAGIC-FORMEL also offers you three further menus: the INTERRUPT-MENU the HARDCOPY-MENU and the SNAPSHOT-MENU. All these menus have in common: 1) The name of the menu is shown in capitals in the middle of the screen, 2) more down you will see the functions of the menu and the function keys that will enable you to activate these functions. Some menus allow you to use other keys as well. But first the RESET-MENU must be explained: 4 --------------------------------------------------------------------------- 2.1) THE RESET MENU You can get into this menu in two ways: 1) by powering up the computer or by initialising it by using the RESET- button. 2) from the INTERRUPT menu (see there) The RESET menu offers you the following features: Pushing one of the four function keys will cause a RESET of the computer but all with a different start-up message: - pushing the F1 button will disable MAGIC-FORMEL. The computer will start up in the original mode and the original start-up message will appear on the screen. In this mode almost every program can be loaded that won't run when MAGIC-FORMEL is active (some programs will block the NMI line, in this case MAGIC-FORMEL has to be removed). By using intelligent hardware it is still possible to use some of the MAGIC-FORMEL features (see INTERRUPT MENU). - the F3 key will also cause a reset but MAGIC-FORMEL will remain active. All features of the module can be used with the exception of the BASIC expansion set and MAGIC-FORMEL-WINDOW (see there). This is the highest compatibility mode of the activated module. - pushing the F5 button will cause the same as F3, but with one exception: the BASIC expansion set will be activated as well. By doing this the compatibility will decreased a bit. - using F7 will activate MAGIC-FORMEL completely, including the feature MAGIC-FORMEL-WINDOW. Besides the function keys two more keys are available in the RESET menu: INST/DEL this key will fill the memory with the value '0' as long as it does not crash the computer. RETURN pushing the RETURN key will cause leaving the RESET menu. The INTERRUPT menu will be called in its place. After a reset a computer must be initialised in any case by pushing one of the function keys in the RESET menu before one can call the INTERRUPT menu. If the INTERRUPT menu is called after a reset without any initialisation, in most cases the computer will crash if one returns to the normal workspace. 5 --------------------------------------------------------------------------- 2.2) THE INTERRUPT MENU There are two possibilities to call the Interrupt menu: 1) in the RESET menu using the RETURN key and 2) from almost any program using the RESTORE key A remark regarding calling the INTERRUPT menu using the RESTORE key, some computers don't react as they should. In this case you need to push the RESTORE key several times to call the INTERRUPT menu. The INTERRUPT menu is a very powerful funtion of MAGIC-FORMEL. When called, the momentary situation of the computer is "frozen" and all important parameters are stored in the built-in RAM of the module. After leaving the INTERRUPT menu the computer proceeds at exactly the same place where it was when it was interrupted. Even when MAGIC-FORMEL was de-activated (using the F1 key in the RESET menu), the INTERRUPT menu can be called using the RESTORE key. So the few programs that only run when MAGIC-FORMEL is de-activated, still have the functions HARDCOPY, SNAPSHOT, MONITOR and the RESET menu at their disposal. After leaving the INTERRUPT menu the computer is in the original state again. In the INTERRUPT menu one can call the following functions using the function keys: F1 key: calls the HARDCOPY menu (see there). From this menu it is possible to print the screen that could be seen before calling the INTERRUPT menu. F3 key: calls the SNAPSHOT menu (see there). This function enables you to store the actual state of the computer on a storage device (cassette or disk) ("FREEZEN") F5 key: this key starts up the machinelanguage monitor (see there). F7 key: calls the RESET menu. With pushing RETURN you can leave the RESET menu again. To leave the INTERRUPT menu, you have to push the RETURN key. The computer proceeds at the address the moment it was interrupted by the RETORE key. 6 --------------------------------------------------------------------------- 2.3) THE SNAPSHOT MENU The SNAPSHOT menu is called from the INTERRUPT menu. You certainly have heard of FREEZERS. MAGIC-FORMEL offers you this feature with the SNAPSHOT menu. Using this menu the momentary state of the computer is stored either on disk or cassette. The so stored program can be loaded again and the computer resumes at that point. The SNAPSHOT menu announces itself with Snapshot 1.1 (Turn drive off/on) Insert formatted disk or blank tape !! Device (1/8/9) Next a formatted disk is inserted (or a cassette, if you want to store using the datasette). Pay attention to the fact that there is enough free space on the disk. Now you have to set the storing device ("device"). The numbers have the following meaning: 1 - cassette recorder (with 10 times speed) 2 - floppy disk 3 - floppy disk 2 (when using 2 drives) When you have entered a number, the next thing SNAPSHOT asks is the name of the program. It may only be 15 characters long. Once you have entered all the input, the program is stored automatically. The next message appears: Working ! Please wait ! continue? (y/n) Typing "n" leads to the RESET menu, if you enter "y" for yes, the computer resumes the program. With some programs it can happen that the floppy disk won't start or continuously keeps on spinning. With these programs it is advisable to turn the disk off and on again before you call SNAPSHOT. 7 --------------------------------------------------------------------------- SNAPSHOT stores the state of the computer into 2 program files. One file has the name you entered. The second file has the same name but with a "1" added at the beginning of the name. To load the state of the computer again, you only have to load and start the first file (without "1"), the second part is loaded automatically. After starting a program stored by Snapshot, it can happen that the floppy keeps on spinning. In this case one should power it off and on again. For program technical reasons MAGIC-FORMEL stores both files in reverse order. When loading from disk this isn't of any importance. When using a DATASETTE, you must first load the second program file, rewind the cassette to the start of the first file and then enter "run". These files stored by SNAPSHOT will only run when the MAGIC-FORMEL-module is active! 8 --------------------------------------------------------------------------- 2.4) THE HARDCOPY MENU Using the HARDCOPY menu you can print then momentary screen. You can address several type of printers. Output is possible over the serial output as well as over the build-in Centronics interface. The Commodore printers MPS 801/802/803, all Epson compatible printers and the colour printer Okimate-20 are supported. On Epson compatible printers colours are printed in greyscale, on the OKIMATE-20 one can print in colour. One can set the various printing parameters in the Hardcopy menu using the function keys. F1 chooses the printers. You can choose from: - Commodore MPS 801/803 - Commodore MPS 802 - EPSON compatible - Okimate-20 F3 switches between normal and inverse printing F5 chooses the output format. Possible are the format 1/4-page and 1/2-page (for example a whole page with the MPS801/803 and OKI 20) F7 choose the way it is showed: - normal B/W (all printers) - greyscale (only Epson compatibles) - colour (only Okimate 20) Pushing the INST/DEL key starts the printing. When the printing has finished, you can leave the HARDCOPY menu by pushing the RETRUN key. The functions mentioned above can not be used with all printers. The input menu only allows legal combinations. Therefore it can happen you have to push a function key twice to get into the next function. Next you will see which functions can be used with the various printers. MPS 801/803: normal + inverse, 1/4 and whole page, only black/white. MPS 802: normal + inverse, only 1/4 page, only hardcopy froma text screen, only black/white. EPSON comp.: normal + inverse, 1/4 and 1/2 page, black/white and greyscale, greyscale only with 1/2 page. OKI-20: normal + inverse, 1/4 and whole page, black/white and colour. 9 --------------------------------------------------------------------------- 3) MAGIC-FORMEL-WINDOW The probably most comfortable function of MAGIC-FORMEL is MAGIC-FORMEL- WINDOW, further referred to as MFW. With help like pull-down menus and windows the control of your computer will be simplified essential. To use MFW, the module has to be activated completely in the RESET menu using the F7 key. MFW is controlled by joystick or a joystick compatible mouse. The control by keyboard is not possible. As long as you don't push the fire button, the computer behaves as you are used to. But if you push the fire button, a menu line and an arrow ("mouse pointer") will appear at the top of the screen. Releasing the button will make the line to disappear again. This menu line can only be called when the computer is in input mode ie. the cursor is blinking. In this menu line several function blocks are displayed. If you go over these several menu items with your mouse pointer with a pressed fire button, windows will appear under these items, displaying more functions. The following functions can be called under MGW: SYSTEM Desktop info FILES Catalog Copy Files Backup Disk Format Disk Commands TOOLS MULTIGRAF Monitor.. EXITS Window off Module off Reset SCREEN Colors You can select a function inside the opened window if put the mouse pointer over this function in this window. This function will then be showed inverted. If you release the fire button, the indicated function will be executed. If you release the fire button while not having selected a function, the menu line and its window will be turned off. 10 --------------------------------------------------------------------------- Now we will explain the individual functions: DESKTOP INFO shows the Copyright notice as well as the version number of MAGIC-FORMEL. CATALOG after calling this function the Catalog menu will appear on the screen. The three white windows on the left will show: the name of the disk, the files on the disk and the available space on the disk. Within the right part of the menu another window is visible. Here one can choose from the following functions: LOAD loads a program. LOAD+RUN loads a program and starts it. ORIG.RUN loads a program, then disables MAGIC-FORMEL and then starts the program (also see the command "crun"). DELETE deletes a program. RENAME gives a program a new name. you can select one of these functions when you place the mouse pointer over one of these function names and push the fire button. The selected function will be showed inverted. You can switch to another function any time. If you, _after_ selecting a function, point over a filename in the Catalog window with your mouse pointer, you will see that this name will be showed inverted. If you then press the fire button, the selected function will be executed with the selected file. Special attention should be paid to two functions: DELETE before executing this function, a conformation inquiry will be displayed. To answer it, you have to point the mouse pointer over one of the two answer windows and to press the fire button. With "cancel" the function will not be executed. RENAME a new window will appear, in which you have to fill in the new name. The input of the name will be ended by pushing the fire button or entering RETURN. Next a security inquiry must be answered. 11 --------------------------------------------------------------------------- After executing the functions RENAME and DELETE, a window will appear on the screen that will show the state of the floppy drive. This state window you will see more often. It will always wait for a push on the fire button as a conformation of the message. Next the new directory will be loaded (including the changes). In the right part of the Catalog menu you'll find some more windows with the following functions: DRIVE8 will load the directory of a disk into the Catalog window. DRIVE9 like DRIVE8, but now a possible drive with address 9 is accessed. The accessed drive is brought to your attention by inverting the according window. UP + DOWN if the directory of a disk contains more files then can be displayed, one can scroll through the directory using these keys. If the window is inverted, you know you can keep on scrolling in that direction. CANCEL if you click this window, the Catalog menu will disappear and you are able to resume you work. 12 --------------------------------------------------------------------------- COPY FILES: This function enables you to copy a file from a disk to another one. Not all type of files can be copied. Only files of the types USR, PRG and SEQ are allowed. And files may mot be longer then 200 blocks. The Copy-Files menu is about the same as the Catalog menu, the differences are: In the top right window you'll find two windows with the drive identifications. By clicking these windows you can mark the source and destination drive. If you click the upper part of these windows, the directory of the according drive is shown at the same time. The files that should be copied are selected by placing the mouse pointer over the according filename and pushing the fire button. If this file is according the above conditions, it is shown inverted. Another click on this file will clear the inversion. After clicking the window START FILECOPY a security inquiry is done because the complete memory will be cleared during the copying. Next the copy process will start. All inverted shown files will be copied. With more then one program, more then one disk change can be needed. If you use only one drive to copy, you are told by the comments INSERT MASTER DRIVE and INSERT SLAVE DRIVE to insert the source ie. destination disk. If during the copy process an error should occur, you will be told of it. By clicking one of the appearing fields IGNORE, RETRY and CANCEL you can ignore the faulty file, or another try is done to load the file, or the copy process is aborted. After ending the copy process the selected files will remain shown inverted on the screen. For executing another copy the COPY-FILE window must closed first and opened again. 13 --------------------------------------------------------------------------- BACKUP DISK This function enables one to copy a disk completely to another one. During the copying process the disk is _not_ formatted automatically. Therefore always a formatted disk must be used. By clicking the individual windows one can set several parameters. The windows MASTER- and SLAVE-DRIVE enables one to choose the source and destination disk. By clicking the field TRACKS you can set how many tracks have to be copied. Allowed are 35-42 tracks. Every push of the fire button increases the number of tracks by 1. In the VERIFY window one can set whether the copy process has to be verified or not. CANCEL makes you leave the BACKUP menu. START starts up the BACKUP function. Just like with the COPY-FILE menu you are asked to insert the source and destination disk. Because when using BACKUP, just like with COPY-FILE, the complete memory is cleared, a security inquiry is done. The error messages are displayed as in COPY-FILE menu. 14 --------------------------------------------------------------------------- FORMAT DISK This function enables you to format new disks. By clicking the fields DRIVE8 or DRIVE9 you can define in which drive the disk is to be formatted. To define the name and ID of the disk, you have to click the fields NAME adjectival ID. Using the INST/DEL key you can delete the name already displayed in the windows. Using the keyboard you can enter the name adjectival the ID of your choice. Take special care when clicking the ID window, you have to push the INST/DEL key twice to overwrite the given default ID! The input windows can be left by pushing the fire button or RETURN key. If you don't change the default names, the disk will have the name "NAME" and the ID "MF" (for MAGIC-FORMEL). Clicking the field will trigger a security inquiry, after giving a positive answer the disk will be formatted. Calling this menu the format process will be succeeded by a verification. This means the format process will take about 30 sec. A disk can also be formatted in 10 sec. without the succeeding verification. This can only be done by giving a direct floppy command (for example from the DISK COMMANDS menu or using the BASIC command SEND). The syntax is: SEND "n:name,ID,n". With some (wrong adjusted) disk drives it can happen that the fast format routine is not executed till the end, and that the floppy drive issues an error message or doesn't respond at all. In this case the floppy drive must be adjusted correctly or you must give the fast format routine up. COMMANDS The DISK-COMMAND-MENU is there to steer several functions of the floppy drive. With DRIVE8 or DRIVE9 one can select the drive. STATUS shows you the status message of the selected disk drive. It will remain on the screen until the fire button is pushed. IINITIALIZE and VALIDATE will execute the according drive finctions. The command DISK-RESET will send the command "uj" to the disk drive. This will initiate a software reset on the drive. Because this will take some seconds and the drive is unapproachable during this time, it is not allowed to click the STATUS field immediately after this command, otherwise the computer can crash. 15 --------------------------------------------------------------------------- MULTIGRAF This menu item will start up the drawing program MULTIGRAF. Because this program will erase the complete memory of the computer, a security inquiry will take place. MONITOR This menu item will start up the INTERRUPT menu, from where you can start up the machine language monitor. WINDOW OFF deactivates MAGIC-FORMEL-WINDOW. A security inquire will be done here as well. After executing this item the computer won't react anymore on the fire button. MODUL OFF deactivates MAGIC-FORMEL totally after a security inquiry and puts the computer in the original mode. There a RESET will be executed. RESET will start up the RESET-MENU after a security inquiry. COLORS COLOR-MENU enables you to change the screen colours. By clicking the field CURSOR, FRAME or BACK you can choose to change the colours of the cursor, screen frame or background. The fields UP and DOWN can be used to in- or decrease the colour value. TAKE will take over the defined colour while CANCEL will leave the menu without changing the colour. 16 --------------------------------------------------------------------------- 4) MULTIGRAF MULTIGRAF is a powerful drwing program. Using a joystick or a joystick compatible mouse (port 2) you can draw directly on the screen. Steering the pointer using the keyboard is impossible. MULTIGRAF is called from MAGIC-FORMEL-WINDOW through the field TOOLS. A empty drawing area and a menu will appear on the screen. All the functions of MULTIGRAF can be called through this menu. The menu can also be deactivated. This happens if you place the mouse pointer at the top of the screen for some time. In the same way the menu is activated again. An exception are the functions ZOOM and COPY. Here you have to push the spacebar to activate the menu again. If you run into the menu area during the drawing process, the menu will deactivate itself automatically. MULTIGRAF uses 16 colours. This is only possible using some extraordinary programming tricks, because normally the computer is only capable of handling 4 colours when in multi colour mode. That's why there is a small limitation when working with 16 colours: - if using several colours at the same time in a small part of the screen, it can happen that when doing a redraw, already painted areas can change of colour. This is a technical matter and impossible to change. The three-line menu has the following structure: 1st line: on the blue area comments and messages regarding the function will appear. In next field the actual colour will be displayed. In the next two white fields the x- and y-coordinate of the drawing pencil will be displayed. The zero point of this coordinate system is situated in the top-left corner of the screen. 2nd and 3rd line: This two lines can be used to choose from the functions provided by MULTIGRAF. The function is selected if you put the mouse pointer over the function and push the fire button. To confirm the choice of the selected function, the according box is shown inverted. The 8 boxes at the right in both lines can be used to choose the actual drawing colour. The chosen colour is displayed in the first menu line. The functions displayed in the 2nd and 3rd line have the following explanation: 17 --------------------------------------------------------------------------- 2nd line from left to right: paint enables free drawing on the screen. If the fire button is pushed, dots on the screen get a colour. create box creates rectangles. First you go with the mouse pointer to the point on the screen where the first corner should come. Now you push the fire button and go diagonally to the opposite corner. If you release the fire button, a rectangle will appear on the screen. circle creates circles and ellipses. The mouse pointer is first placed on the centre of the circle to be created. Then the fire button is pushed. Now the mouse pointer is used to adjust the horizontal and vertical radius of the ellipse. The ellipse is drawn the moment the fire button is released. zoom For making fine adjustments on the screen, it is very useful to enlarge a portion. This is made possible by this function. If you move the mouse pointer from the menu to the screen, a small box instead the usual crosshair will appear. This box is moved to the place you want to enlarge. A push on the fire button will enlarge this area. The enlarged area can be used to set dots. You can leave the zoom mode by pushing the space bar. copy the copy function enables you to move parts of the screen with the size as you wish. First the pointer is placed on the top-left corner of the area to be copied and then you push the fire button. With a pushed fire button you draw a rectangle that incorporates the area to be copied. The moment you release the fire button the enclosed area is copied and a rectangle is shown instead of the crosshair. You can move this rectangle to the place where the chosen area should be copied. A push on the fire button will paste the area. This can be done as many times you want. If you want to copy a new area, you first have to click the copy symbol in the menu. If you have deactivated the menu, you have to activate it again by pushing the spacebar. The with copy chosen area can also be copied to the second screen. 18 --------------------------------------------------------------------------- text horiz. enables you to write text on the screen. After clicking this function one can enter text using the keyboard which is placed horizontally on the screen where the pointer is situated. If you push the fire button, MULTIGRAF creates a security copy of the screen, which can be called by the undo function . clear clears the screen. This function can be reversed with undo. kill ends MULTIGRAF and leads to the REST menu. But first a security inquiry will appear that has to be answered with "y" for yes and "n" for no 2. screen MULTIGRAF can handle two pages which can be swapped using this function. dot mode this key activates the normal drawing mode. This means drawing dot wise. The opposite is the brush mode where one can draw with a self defined brush. Dot mode is default when MULTIGRAF is activated. zoom brush this function can only be enabled when brush mode is activated. It enables to enlarge or reduce the size of the self defined brush. rotate brush is also only available in brush mode, this function rotates the brush 90 degrees clockwise every time. Unfortunately the colour information is lost and the brush will continue with the actual colour. Because of different resolution of the screen in horizontal and vertical direction, after 4 turns it can happen that the brush looks different as before. 3rd line from left to right: line creates a line between two points. The mouse pointer is placed on the first point, then you push the fire button and you release it again when the mouse pointer is situated on the other end of the desired line. block resembles the function box, but now a filled rectangle is drawn. 19 --------------------------------------------------------------------------- spray this function emulates a spray can, the colour is sprayed on the screen when the fire button is pushed. fill fills a closed area of your choice with the actual colour. After the mouse pointer has been placed over the chosen area, the fill process is started by pushing the fire button. delete enables you to erase rectangular areas on the screen. After defining a rectangle like with the box function, the process is started by releasing the fire button. text vert. is equal to the function text horizontal, but in this the text is placed in vertical way on the screen. undo this function can undo most of the functions. Clicking this menu item will undo the last function. Another click will restore the previous picture again. disk activates the disk menu. This menu enables you to store pictures, to load them or to overwrite pictures already on the disk. Next the desired function has to be clicked (LOAD, SAVE or REPLACE). After selecting LOAD or REPLACE the pointer has to placed over the desired picture in the directory window and the fire button has to be pushed. With SAVE the desired name has to be entered. RETURN or pushing the fire button starts the save process. The drawing mode is activated again after the execution of the selected function. The directory of another disk can be shown by clicking the field "drive8" (adjectival "drive9" with a second drive). Only MULTIGRAF pictures are shown in the directory. These are marked by the character combination .MG at the end of the name. If none of the available functions is to be selected, the disk menu van be left by clicking the field "cancel". 20 --------------------------------------------------------------------------- backcolor changes the background colour of the screen. Every push of the fire button will increase the value with 1. brush-mode this function enables you to define your own drawing brush. After clicking this menu item the request "get brush" will appear and when you move the mouse pointer over the drawing field, a little box will appear. You have to move this little box to an area on the screen of your choice. If you push the fire button, the enclosed area will be used as base for further drawing actions. The inverted symbol in the menu tells you that the brush mode is active. By clicking the function dot mode this mode is deactivated again. The defined brush can be used in the functions paint, line, box and circle. mirror vert. mirrors the brush in vertical way. mirror hor. mirrors the brush in horizontal way. 21 --------------------------------------------------------------------------- 5) BASIC COMMAND EXPANSION Beside the until now explained by menu callable functions, MAGIC-FORMEL offers you many more possibilities. Among other things it offers a voluminous Basic command expansion. These new Basic commands can be separated in three groups: TOOLKIT, DOS- COMMANDS and GRAPHIC. Next the single commands and their syntax will be explained. 5.1) TOOLKIT COMMANDS AUTO XX enables the automatic line numbering where XX is the step rate. AUTO without parameter disables the feature again. DELETE AA-XX deletes the lines from AA to XX. One should pay attention to the fact that the given lines exist. The second line number must be greater then the first one, otherwise the program can be destroyed. DEZ "XXXX" converts the hexadecimal number XXXX into the decimal value. Instead XXXX an according string variable may be used as well. XXXX adjectival this string variable must have a length of 4 characters. FIND "TEXT" searches for the string TEXT in the Basic program. In case of an unknown character, one can use the wildcard "?". If the quotes are omitted, FIND will look for the token of the according command. HELP will show a list of the toolkit-, DOS- and graphic-commands on the screen. HEX X converts the decimal number X into the according hexadecimal value. Instead X a numeric value can be used as well. JUMP X with X=0-9, A-F this commands jumps to a machine language routine. Example: JUMP 6 jumps to $6000, JUMP C jumps to $C000. LLIST is equivalent to the command OPEN 1,4 : CMD : LIST. 22 --------------------------------------------------------------------------- LPRINT "TEXT" directs output to the printer instead of the screen. LPRINT without text or a string variable will produce a syntax error OLD restores erased BASIC programs as long as the memory is not overwritten by new programs. OLD may not be preceded by a syntax error otherwise the start of the program may be destroyed. OFF switches the computer to the original state without destroying programs or any other content of the memory. RENUM inc, start renumbers the line numbers of a BASIC program where start = the number to start with and inc = the stepping value. If the parameters are omitted, the default values will be 10, 100. 5.2) DOS commands _The values between parenthesises must not be entered._ CAT will list the directory of the disk without destroying the programs. CDRIVE sends a command to your floppy drive that changes the device address from 8 to 9. So you can use two drives without the need to change it by hardware. First you power on one drive, give the command CDRIVE and then power on the second drive. CONFIG S MAGIC-FORMEL is capable of reading and storing sequential files much faster. But only one file may opened at a given time. This can lead to problems with some programs. With "config s" you can disable the fast loading routines. After entering this command files will be loaded and stored with normal speed. But normal programs still will be loaded and saved in the fast way. Deactivating the fast routines will however effect MAGIC-FORMEL-WINDOW. After deactivation the functions COPY FILES and BACKUP are unavailable. The Centronics interface at the userport cannot be used as well. The command "config" (without parameter) activates the fast routines again. These routines are available by default after powering on the computer or after a reset. 23 --------------------------------------------------------------------------- CRUN resembles the command LRUN, but now the computer is set to the original state after the loading adjectival before the start. This command makes sense when using programs that won't cooperate with MAGIC-FORMEL. At least they can be loaded faster (not valid for auto-start programs). DAPPEND "(L:)NAME" where L=0 or 1 for the first or second drive. appends the program "name" to the program in memory. When needed the line numbers of this program have to be adjusted on forehand. DLOAD "(L:)NAME" replaces the command LOAD "NAME",8,1 DSAVE "NAME" replaces the command SAVE "NAME",8 DVERIFY "NAME" replaces the command VERIFY "NAME",8,1 LRUN "NAME" loads the program "NAME" and starts it. LRUN without a given name will load and start the first program from disk. If MAGIC-FORMEL-WINDOW is activated, the command LRUN is also executed by pushing the keys SHIFT/RESTORE. REPLACE "NAME" replaces the file "NAME" on the disk with the program in memory. REPLACE is equal to SAVE "@:NAME",8. The well known error in the 1541 is corrected while executing this command. SEND "(L:)command" replaces the command OPEN 1,8,15,"command". STATUS shows the error message of the floppy drive on screen. 24 --------------------------------------------------------------------------- 5.3) Graphic Introduction The graphic commands support the high resolution graphics with 320*200 dots as well as the multi colour graphics with 160*200 dots resolution. So in a multi colour graphics the resolution in x-direction is only half of the one of high resolution graphics, ie. the distance between two points is twice as big. Up to four screens can be selected. In the appendices you'll find an example program where many of the here explained commands are used. Coordinates x and y: In graphic mode the screen is layed out in a matrix of 320*200 dots. x is the x-coordinate, y the y-coordinate. The origin of the coordinate system, the coordinates (0,0) can be found in the bottom-left corner of the screen. x can range from 0 to 319, y can range from 0-199. Although there is only a resolution of 160 dots in x direction when in multi colour graphic mode, the range 0-319 is used here as well. The value is calculated to its half. Character type zt: This value defines how a dot will appear on the screen. It can range from 0-4: zt=0 clears a dot 1 draws a dot in colour 1 2 draws a dot in colour 2 3 draws a dot in colour 3 4 inverts a dot The values 2 and 3 have no meaning when in high resolution mode because there is only one colour possible except the background colour. The value 4 (inversion) has a special meaning when in multi colour mode: a dot with colour 1 becomes colour 2, a dot with colour 2 becomes colour 1, a dot with colour 3 is erased, a not defined dot is shown with colour 3. Colour table: The values 0-15 can be used and represent the following colours: bg= 0 black bg= 8 orange 1 white 9 brown 2 red 10 light red 3 turquoise 11 grey 1 4 violet 12 grey 2 5 green 13 light green 6 blue 14 light blue 7 yellow 15 grey 3 25 --------------------------------------------------------------------------- Graphic command set GRAPHIK n This command prepares the computer for displaying a graphical screen. The parameter n can range from 1 to 4 and tells the number of desired graphical pages. The command GRAPHIK has to be given at the beginning of all graphical operations (in programs at the beginning of the program), because it limits the memory size of the computer. The top of the available memory is decreased according the need graphical pages. ATTENTION: if this command is not placed at the beginning of the program and strings are used before this command, they will be lost! The connection between the number of graphical pages and the available memory is shown in the following table: n Address of the page top of the memory free RAM --------------------------------------------------------------------------- 1 $A000 = 40960 $8BFF = 35839 33789 2 $6000 = 24576 $5FFF = 24575 22525 3 $4000 = 16384 $3FFF = 16383 14333 4 $2000 = 8192 $1FFF = 8191 6141 All graphic commands, except GSAVE, GLOAD and TEXT, will raise an Overflow- error when GRAPHIK n wasn't issued before. HIRES cl, bg activates the highresolution graphic (320*200 dots). cl is the drawing colour and bg is the background colour (see colour table). Both parameters are mandatory. MULTI c1, c2, c3, bg activates the multi colour graphic mode (limited resolution of 160*200 dots). c1, c2 and c3 denotes the three colours from the colour table that should be used in the graphics. bg is the background colour. All parameters are mandatory. FRAME rf sets the colour of the frame. The values for rf can be found in the colour table. CLEAR clears the graphic screen. TEXT switches the screen from graphic mode into text mode. When in graphic mode this command can only be given by typing blind. Issuing the command TEXT without having executed another graphic command before, will result in a random colour combination for the screen. This could be black characters on a black background so nothing can be read anymore. But issuing the TEXT command without a previous graphic command makes no sense anyway. 26 --------------------------------------------------------------------------- PAGE n will swap the visible screen (equal to page 1) with the contents of the indicated page. The place and the number of the page were already explained with the command Graphik. n can have the values 2, 3 or 4. n=1 will make no sense as this will swap the graphic page with itself. The parameter n can not be greater then the value entered with the Graphik command otherwise programs can be overwritten. If a greater value is entered, an Overflow Error is raised. COPY n copies the contents of the according page to the screen. Parameters like with PAGE. MIX n will place the contents of the according page over the one on the screen, in this way graphic screen can be mixed. Parameters like with PAGE. INVERT inverts the graphic. In multi colour graphics the colours are inverted as described in the paragraph "Character type". GSAVE "NAME" will save the momentary graphic screen including all parameters to disk. PLOT x, y, zt will plot a point on the coordinates x,y. zt is the character type. LINE x1, y1, x2, y2, zt will draw a line from x1,y1 to x2,y2. DRAW x, y, zt is in fact the command LINE but with DRAW only the second coordinate is given. The second coordinate of a line drawn by a previous DRAW serves as the first coordinate. PLOT x, y, zt must be used to give the first DRAW command a starting coordinate. BOX x, y, lx, ly, zt draws a rectangle. x,y is the left-bottom corner of the rectangle. lx is the length in x-direction and ly is the length in y-direction. 27 --------------------------------------------------------------------------- BLOCK x, y, lx, ly, zt Like BOX, but a filled rectangle is drawn. CIRCLE x, y, rx, ry, zt will draw a circle adjectival an ellipse. x,y is the centre of the circle, rx the radius in x-direction and ry the radius in y-direction. FILL x, y, zt will fill a closed area where the coordinate x,y is situated with the colour zt. HPRINT x, y, zt, "TEXT" will write a text on the screen in horizontal direction. x,y is the bottom- left corner of the first character. Instead of "TEXT" a string variable can be entered as well, numerical variables must be converted before into a string variable using the command STR$(var). Because of the low resolution in multi-colour mode the text will be printed twice as wide. VPRINT x, y, zt, "TEXT" same as the command HPRINT, but now the text is printed in vertical way. Error messages The following error messages can occur: OVERFLOW-ERROR you have forgotten to enter the command Graphik before or the parameter n for the PAGE-, COPY-, or MIX- command is greater then the page number chosen with Grafik before. ILLEGAL-QUANTITY-ERROR: the x-coordinate is not within the range 0-319 or the y-coordinate is not within the range 0-199 or the parameter n (for GRAPHIK, PAGE, COPY, MIX) is not in the range 1-4. With most of the error messages the computer will switch back to the text, but it can happen that it remains in the graphic mode. In this case one can switch back to the text mode by typing blind TEXT to read the error message. 28 --------------------------------------------------------------------------- 6) ASSEMBLER PROGRAMMING To be able to program in machine language several comfortable tools have been installed in this module: the 2-pass assembler, the machine language monitor and the floppy monitor. The next pages will explain these programs. However this manual is not an introduction into the machine language programming, you'll find a lot of books on the market. Only the specific functions of these programs will be explained. 6.1) Machine language monitor The monitor is called from the INTERRUPT menu. The floppy monitor is integrated in the machine language monitor. The abbreviations used in the explanation of the commands have the following meaning: BA : Beginning address, a hexadecimal value is expected. It can have four or six digits. When using six, the first two numbers define the configuration of the processor port (address $01), which defines the memory configuration of the computer. Example: M35E000 E1000 shows the content of the memory in the range E000 - E1000, But in this case the RAM under the Kernal. The value 35 in the processor register means that the ROM in the range E000 - FFFF is deactivated and the parallel RAM is activated. Is the beginning address only entered a four digit number, the last entered value for the processor register is kept. When the monitor is activated, this is the value $37, this is the default value for the computer. EA : End address, 4 or 6 digits long, se above. BY : a byte, this value can be entered as a binary (%), octal (&), decimal (+) and as a hexadecimal ($). The characters between the parenthesises must be written before the value, to give the computer the number base. Examples: +128, %10010000, &2373, $F2A0. If the marker is omitted, automatically an hexadecimal value is assumed. 29 --------------------------------------------------------------------------- The commands and addresses have always to be separated by a space. The input of the opcode is done using the usual syntax, where a mark is place in front of the operand to mark the used number base. Examples: lda $01 , ora %01000000 , sta +127 One can leave the input mode with SHIFT/RETURN. The monitor will also process most of the "illegal" codes, you'll find a list of these opcodes in the appendices. When doing a memory dump or assembling, one can scroll up and down using the cursor keys. Commands: a BA opcode assembles at the given address, example: a 2F00 ldx #$02 c BA EA A2 compares the memory range AA-EA with the memory from A2 on. Example: c 2000 3000 5000 d BA (EA) disassembles from BA to EA (the end address can be ommitted). Changes can be performed directly in the listing. e. BA (EA) this command is used among other things to edit sprites or character sets. After the e another character is expected which tells how may binary values will follow: e! for one byte ( for character sets), e" for two bytes, e# for three bytes (for sprites). f BA EA BY fills the given range with BY. g address executes a JUMP to the given address. If the address is omitted, after leaving the monitor, with g the computer will resume at that place it was when it was interrupted by the INTERRUPT menu. You are not allowed to use g to jump to an address within the Kernal ($E000-$FFFF) as this will crash the computer. h BA EA BY BY ... will look in the given range for the given byte combination. l "name" (BA) will load a program file from the actual drive, the value BA is the address to where the file should be loaded in the computer. If the address is omitted, the file is loaded at the place from which it was saved. The actual drive can be set using @8 or @9. Default is 8. 30 --------------------------------------------------------------------------- m BA (EA) shows the given range as hexdump. Individual bytes in the memory can be altered by simply overwriting them in the listing. o displays the screen as it looked like before INTERRUPT menus was called. RUN/STOP activates the Monitor screen again. s "name" BA EA+1 saves the program in the given range. The device number can be set with @8 or @9. The individual values must be separated by blanks (space). The memory range $A000-$B000 and $E000-$FFFF can not be saved. t BA EA A2 moves the address range AA-EA to address A2. x call the RESET menu, from there one can return to the INTERRUPT menu using the RETURN key. ^ (C= arrow up) display the IRQ-, BRK- and NMI vector. The first 3 vectors are the RAM addresses $0314-0319 and can be changed in the line and updated with RETURN. <- activates and de-activates MAGIC-FORMEL As an extra some key functions have been integrated in some commands. They are called whenever the CONTROL key is pushed in combination with the according key. CTRL-U places the cursor in the left-bottom of the screen. CTRL-L places the cursor at the left end of the line. CTRL-R places the cursor at the right end of the line. CTRL-E deletes the line from the cursor to the end. CTRL-D deletes the complete line where the cursor is situated. CTRL-X swaps the momentary screen with the added RAM. The screen that now appears can be cleaned using SHIFT-CLR/HOME. Now you can work with two screens in the monitor that can be swapped by CTRL-X 31 --------------------------------------------------------------------------- 6.2) Floppy monitor The Floppy monitor is integrated within the Machine language monitor. To be able to manipulate the memory of the floppy, one has to enter F8 or F9 (device 8 or 9)instead of the values for the processor registers before the addresses. Example: D F8E000 F000 disassembles the memory range E000-F000 in drive 8. More commands: @ shows the state of the selected drive. @8 or @9 defines the drive that should be selected. @"command" sends commands to the disk. $r pu tr se reads sector se on track tr into buffer pu in the diskdrive. pu can range from 0-4. Example: $r 1 1A 01. (buffer starts at $0300, buffer 1 at $0400 etc..) If "status ok" is not shown after @r, then the disk has to be initialised with @"i" first. @w pu tr se writes the contents of the buffer to the mentioned sector. @$ shows the directory of the actual drive on the screen. 32 --------------------------------------------------------------------------- 6.3) Assembler Introduction: The assembler is a useful instrument to generate machine language programs. By using labels and logical expressions instead of using direct jumps and addresses, this 2-pass-assembler - in contrast with a direct assembler - is suited very well for creating long programs. For using an assembler the knowledge of machine language programming is needed of course. This manual can not be used as an introduction into the machine language programming, for this you can find enough adequate literature on the market. The source for the assembler is created like a Basic program, the advantage is that all Toolkit functions can be applied to this program. The assembler is able to chained assembling from disk. More information can be found in "Pseudo opcodes". In the appendices you'll an assembler listing that contains lots of the commands and directives you'll find on the next pages. Starting the assembler The assembler is called by the command ASSEMBLER. This directive must be placed in the first line to be assembled. Format A line inside the source should look like this: LN (LABEL) (opcode) (expression) (; comment) (: .....) The expressions between the parenthesises are optional. LN is the line number LABEL a combination of characters up to 32 characters long. The first character always must be a letter. A label always must be followed by an opcode. opcode is an instruction from the MOS standard instruction set or an illegal opcode (see list) or a pseudo opcode. expression must be used with more-byte-commands (see chapter "Expressions"). ; The semicolon is equal to REM in Basic. All following will ignored until the end of line or a colon. This character may not be used directly after a label, a label always must be followed by an opcode. : the colon introduces, like in Basic, a new instruction. 33 --------------------------------------------------------------------------- Expressions An expression has the following format: (function1) operand1 (function2 operator2) .... Function1 can be: ! the expression after ! is treated as an absolute value. Example: LDA !$01 is assembled as LDA $0001 < gives you the low-byte of the following expression. Example: LDA <$0022 is assembled as LDA $22. > gives you the high-byte of the following expression. Example: LDA >$0022 is assembled as LDA $00. - inverts the sign () the parenthesises can be used as with normal arithmetic functions. If not used, expressions will be processed from left to right. Operand1 can be: - a decimal number like 123, 65535 . - a hexadecimal number like $01, $D000. - a binary number like %01, %111100. - an ASCII character like "a", "A", "#". - an * , then the value of the program counter will be used. - a label. - or another expression. Function2 can be: a) an arithmetic function: +,-,*. b) a logical function & : and ! : or ^ : exclusive or (C= arrow up) < : shift the value left times right value > : shift the value right times right value Next you will see some expression as example: LDA #$00+3 ADC $FFFF-1*3 LDA LABEL1-LABEL2 EOR %111111<1 LDA videoram 380 stx counter+1 390 ldy #0 400 ; 410 invl lda (counter),y 420 eor #%10000000 ; invert 430 sta (counter),y 440 dec $55 ; timeloop 450 bne -2 460 inc counter 470 ; 480 bne invl 490 inc counter+1 500 ; 510 ldx counter+1 520 cpx #$08 530 bne invl 540 beq invert 550 ; 560 writescreen ldx #8 ; write 8 lines with the 570 ws2 ldy #40 ; character in accu to the screen 580 ws1 jsr bsout 590 dey 600 bne ws1 610 dex 620 bne ws2 630 rts 640 ; 650 text asc "assembler-demo" 660 byt 0 670 end 680 sys 4096*12 ---------------------------------------------------------------------------