


                         Cymbol Mathematical Platform
                          For Running Cymbol Applets

                                version 0.3a
                              22 November 1998


                               (C) Kirk Meyer
                               kirk@ticalc.org



--- Introduction ---------------------------------------------------------

    Cymbol is a mathematical platform that supports applets. This means
    that you can load the applets that you need, and leave the rest on
    your computer. It also means that any assembly language programmer can
    write an applet. The applet format is explained later in this readme.
    You will need the included CYMBOL.H to write your own applets.

    NOTE: Before you start using these, I suggest that you create a Cymbol
    directory on your hard drive so that you can keep everything straight.
    Trying to remember what applets you have and then trying to get their
    readme files might be confusing if you don't do this. You have been
    warned! IMPORTANT! Any Cymbol applet which is not included in this
    Cymbol ZIP file may be incompatible with Cymbol. The use of such
    applets is entirely at your own risk.

    This program has been extensively tested but there are still a few
    cases where the program can appear to lock up. To this end, always run
    the program with "Asm(cymbol", not from a shell. Then, if the program
    appears to lock up, all you have to do is press F5, ENTER, EXIT and
    you should be okay. If this bug fix does not work, or if you have info
    on when this bug occurs, please e-mail me at <kirk@ticalc.org>.


--- Controls -------------------------------------------------------------

    ON          - break out of calculation
    LEFT        - select the previous entry field
    RIGHT       - select the next entry field
    UP          - select the previous applet
    DOWN        - select the next applet
    CLEAR       - set selected field to zero
    EXIT        - exit

    To change the selected entry field, simply type the number and press
    ENTER when done. You may use the DEL key while typing to correct your
    errors. Pressing ENTER automatically selects the next input field.


--- Versions -------------------------------------------------------------

    v0.1        - The initial release. 3 applets included, no source.
    v0.2        - When ENTER is pressed, the next input field is selected
                  automatically. Source code for 2 of 3 applets released,
                  as well as information on how to create the applets.
    v0.3        - Source code for quadratic formula released. Ability to
                  break out of applets with ON key. Ability to clear a
                  field with the CLEAR key.
    v0.3a       - Eliminated a call which was ROM dependent, causing some
                  calculators to behave stangely when running Cymbol.


--- The fine print -------------------------------------------------------

    This program is provided to you for your convenience, free of charge.
    I can not and will not be held responsible for any damage or loss this
    product may cause, either directly or indirectly. If my program screws
    anything up, you are on your own. You may not sell this program to
    others for money. It is intended to be freely distributed.


--- Creating Applets -----------------------------------------------------

    IMPORTANT! You must adhere to the following guidelines for Cymbol
    applets. If you do not then your applet will not be included in the
    Cymbol ZIP file. First, you must write up some sort of readme file
    detailing how the applet functions (similar to the ones I have made
    for the included applets). ZIP your applet, THE SOURCE CODE, and the
    readme file and send it to me. I will, as necessary, modify your
    program and/or your source code so that it is most beneficial to the
    public. In all cases, you will remain as author of the program. 

    NEW: When the user pushes clear, the area is cleared to "zero". In
    fact, it is cleared to "almost zero". Almost zero is defined as:
        .db $00,$00,$FC,$00,$00,$00,$00,$00,$00,$01
    This is most useful in equation solvers, where the program needs to
    see what variables to solve for. Additionally, you can allow the
    user to break out of your applet by pressing ON. Simply include a
    "call AllowBreak" command in the middle of a potentially time
    consuming loop. The square root reducer already has one built in.

    All cymbol applets should #include the file "cymbol.h", included in
    this ZIP file, as well as any other include files they may need. That
    include file has various OP-related ROM routines, some Cymbol-specific
    calls, and also some macros (i.e. pop_op and push_op). Here is a
    commented listing of a cymbol applet. Note that numbers are replaced
    with letters, etc.

    #include "cymbol.h"
    ;
    .org $8FFE                      ;where the applets are loaded to
    .dw $CB07                       ;identifying bytes
    ;
    .db x                   ;x = how many inputs (selectable numbers)
    .db y                   ;y = what input is selected? y starts at x
                            ;    and then goes to 1, i.e. if there are
                            ;    x=3 and y=3 the first input is the one
                            ;    that is automatically selected
    .dw applet_data         ;always the same - points to applet info
    ;
    ;now follow x data structures of the following format:
    .db f                   ;f = any flags that apply, see later for info
    .dw $YYXX               ;XX = the x coordinate of the number,
                            ;YY = the y coordinate of the number; however
                            ;these are in relation to the previous input!
                            ;i.e. this number is added to the current
                            ;cursor position before the number is shown
    .db FP_NUMBER           ;a 10-byte floating point number that is the
                            ;default value for this input
    .db STRING              ;any string to be appended to the end of the
                            ;number - commonly units.  zero terminated.
    ;
    ;... (x-1) more structures ...
    ;
    applet_data:
    .db "Title String 21 Bytes",0   ;title of applet, 21 chars, 0 term.
    ;update code follows. this code is called whenever something has been
    ;changed. About the only restriction is that you shouldn't write to
    ;the upper 16 lines of the screen, to keep applets looking the same.
    ret
    ;
    .end

    The following are cymbol-specific function which you can call:

        PlusMinus       displays a plus/minus symbol at the current
                        _penCol and _penRow
        ReduceOP1       reduces radical sqrt(OP1) into OP4*sqrt(OP6)
        PrintReal       shows the real number in OP1. A = any flags,
                        see note later about the flags
        PrintString     shows string at HL. A = any flags, see note
                        following about the flags

    Flags (for PrintReal, PrintString, and the f byte in applets):

        bit 7 set               always show sign, whether + or -
                                (PrintReal only)
        bit 7 clr               only show sign if negative
                                (PrintReal only)
        bit 6 clr               left justified text, number, etc.
        bit 6 set, bit 5 clr    center justified text, number, etc.
        bit 6 set, bit 5 set    right justified text, number, etc.

    I have defined the following macros to make life easier:

        pop_op1(x)              x = the OP# to pop
        push_op1(x)             x = the OP# top push

    See the included applet source codes for more clarification. If you
    are having trouble with your applet feel free to e-mail me about it
    at <kirk@ticalc.org>. Be sure to send your source code.
