Q-TILITY DOC
COPYRIGHT (C) 1986 BY CHARLES SHELTON

NOTE: THIS PROGRAM IS BEING DISTRIBUTED UNDER THE "SHAREWARE" CONCEPT. IT MAY
BE COPIED AND SHARED WITH OTHERS, AND A VOLUNTARY CONTRIBUTION OF $10.00 IS
REQUESTED FROM THOSE USERS WHO FIND IT USEFUL. IT MAY NOT BE DISTRIBUTED
COMMERCIALLY BY ANYONE WITHOUT WRITTEN PERMISSION FROM THE AUTHOR.


    The following is a brief description of Q-Tility and it's functions.  More
complete documentation is in the process of being written.

    Q-Tility is a utility program for the Commodore 64 written entirely in
machine language.  It incorporates a form of 'transparent technology' whereby
any of the functions of the utility can be accessed at any time, even while
another program is currently running in the computer (similar to 'SIDEKICK' on
the IBM-PC).  When the user presses the 'CTRL' key at the same time as the CRSR
UP/DOWN key on the keyboard, the currently-running program, whether BASIC or
Machine Language, is interrupted in its execution and the utility menu appears
on the screen.  To load and activate Q-Tility, simply enter load "Q-Tility
1.1",8 (as with a normal basic program) and enter RUN when the ready prompt
returns.  The program will then relocate itself to the proper area of memory
and also activate itself.  The program can be de-activated by either pressing
RUN-STOP and restore in combination, or entering SYS 49175, and it can be
re-activated again with SYS 49152.  The program presently includes the
following functions:

       1> Calculator
       2> Disk Command Sender
       3> Disk Directory Reader
       4> Disk Error Channel Reader
       5> Sequential File Reader/Printer
       6> Free Basic RAM Reporter
       7> Screen & Character Color Changer
       8> Low Resolution Screen Dump to Printer
       9> Notepad

The user chooses which function he/she wants to use, executes the function
chosen, and is then given the option of exiting the utility program or
continuing to use the functions.  If the user presses the CTRL key along with
the CRSR RIGHT-LEFT key, Q-Tility 'hides' itself away again and the interrupted
program reappears on the screen and resumes execution at exactly the point at
which it was interrupted.  Some of the functions in Q-Tility, as well as some
of the functions yet to be added, are available in similar forms as Public
Domain Programs and in other commercial programs, but Q-Tility offers the real
convenience of making these functions transparent and constantly accessable
without having to exit any current program and load the utility into the
computer.  A brief description of each of the current functions follows.


    'Q-Calc' is the calculator function within Q-Tility.  It uses various
techniques to enable it to evaluate complex math formulas and expressions.  The
user can enter a math expression of up to 80 characters in length, using the
standard math operators +,-,/, and *, as well as any of the math functions
available in CBM basic (SIN, COS, SQR, ^, the PI symbol, etc.).  Parentheses
can also be used wherever needed in expressions, as well as any
currently-declared (e.g., by the interrupted basic program) numeric variables,
both single and array (single or multi-demensioned).  Other than lacking a
memory-store function, Q-CALC therefore simulates a full-function scientific
calculator, with the added convenience of being able to handle variables.
    Q-CALC also has a custom error-handling routine, whereby if a user makes a
syntax mistake in his expression entry the normal basic error report routine
(which would cause both Q-Tility and the interrupted program to stop execution)
is bypassed, the error is reported, and the user is returned to the expression
input prompt to re-enter the expression.  This routine also works to trap math
overflow errors.
     An interesting and convenient extra resulting from Q-Calc's ability to
handle variables is the fact that the user can interrupt a basic program at any
point and find out the value of any of the program's numeric variables by
simply entering the variable label at Q-CALC's input prompt.  For example, the
user can find out how many times so far a program has completed a for-next loop
by entering the loop-counter variable at the prompt.  If the loop uses J as the
counter variable, for example, and J is entered at the Q-CALC prompt, the
present value for J will be returned.  This added extra can come in handy when
debugging a program or following its progress.
    Because of the fact that Q-CALC uses routines already in the basic ROM to
evaluate expressions, the entry of the basic FRE(0) function at Q-CALC's prompt
could normally cause an interrupted basic program to crash upon resumption of
execution, due to the fact that FRE(0) forces garbage collection, which changes
important basic variable pointers.  The program avoids this potential problem
by reporting entry of the FRE function as an error and disallowing it.


    The Disk Drive Command Sender avoids the need to have a seperate command
'wedge' installed in order to send commands to the drive without having to open
and close the command channel.  If the user wishes to scratch a file from the
disk all he has to do is enter at the prompt: 'S:Filename' and the command will
be sent directly to the drive.  Normal 1541 syntax is used for all of the drive
commands.  If the user changes his mind about sending a command after receiving
the 'command:' prompt, he simply presses the return key with no input on the
line and the function aborts back to the main menu.  The only things the
'sender' is lacking that many wedges have is a non-destructive directory reader
and an error-channel reader.  That's why I wrote the following two routines.


    The Disk Directory Reader is a non-destructive (simply prints the directory
to the screen) reader that is executed immediately upon choosing #3 from the
Main Menu.  While the directory is printing to the screen, output can be paused
by pressing any key and thereafter resumed by pressing any key again.


    Choosing #4 from the Main Menu immediately causes the drive error channel
to be read and the result printed to the screen.  This routine is also
automatically executed upon completion of any of Q-Tility's other disk
functions (they jump through this routine back to the Main Menu).


    The Sequential File Reader (#5 on the Menu) will accept a filename from the
user to read and then give the option of printing the file either to the screen
or a printer.  At any time during the printing of the file the output can be
paused by pressing any key.  Once paused, the user can abort the reader and
return to the main menu by pressing the 'x' key, and continue reading the file
by pressing any other key.  If the user has chosen the option of sending output
to the printer, there is often some delay before output is paused when a key is
pressed, as the text is output a full line at a time and the size of the
printer buffer affects how many lines are printed before the pause takes
effect.  This function automatically switches to lower case on both the screen
and the printer (and back again when finished if the computer was originally in
upper case mode), as most text files are in such a mode.  The function can also
be used to read or print any notes written with the NOTEPAD function.


    Choosing #6 from the Menu will cause the program to report current free RAM
available within the basic program area.  This routine can be handy when a
basic program is currently running.  Just interrupt the program at any point to
see how much RAM has been used so far.


    This function gives the user the option of changing the current colors for
the characters, screen background, and the border.  Thus, if a program in
current execution uses colors that are not to your liking, simply interrupt its
execution and use this function.  All subsequent execution of the program will
be in your chosen colors.


    This function will dump the current screen (but not hi-res screens) of the
interrupted program to the printer on the serial bus.  Any reversed characters
on the screen will be printed as non-reversed.  The function also checks what
mode the computer is currently in, whether upper case/graphics or upper/lower
case, and dumps to the printer in that form, so always 'what you see is what
you get.'  The routine is very useful for dumping important data on the screen,
menus, etc. for later perusal.  I've also used it successfully with
non-printing machine language monitors for dumping disassemblies to the
printer.


    Let's say you are currently using another program, with 'Q-Tility' active
in the background, and you wish to write yourself a short note or memo and save
it to disk.  Just choose the notepad function from the Q-Tility menu.  The
screen will clear and the program will put you into input mode for the note.
 You are limited to 20 lines for your note.  You can compose your note on the
screen, with the cursor keys and insert & delete keys active.  BUT NOTE: Do not
use the <return> key until you have finished composing your note.  To signal a
place on the line at which to add a carriage return, type the left-arrow key
(in the upper left corner of the keyboard), and to jump to the beginning of the
next line you can press the shift and return keys at the same time.  When you
have finished your note, type the up-arrow key (^) to signal the end of the
note, and then press <return>, which signals the program that you're ready to
send the note to disk.  You will then receive a 'send note to disk?' prompt, at
which you press 'y' to do so, or 'n' to abort the function.  If you press 'y',
you are then prompted for the file name, which must be no more than 16
characters long.  The file is then written to disk, the error channel is read
to check on how the file-write went, and you receive the return-to-menu prompt.
 The note, as mentioned before, can then be read or sent to the printer with
the file reader function.

    Q-Tility currently loads into ram at $C000 (49152) and is activated by SYS
49152.  It stores the screen and color ram, as well as important
interrupted-program data, in RAM underneath the ROM in the $A000 area.  This is
only temporary, for purposes of further development.  Eventually, most of the
program will reside underneath the $A000 ROM and the screen/data storage area
will be either underneath rom in the high-$B000 area or the KERNAL ROM above
$D000, depending on how much RAM Q-Tility needs in the $A-$B000 area.  Thus, in
the next version, Q-Tility will leave almost all of basic memory free (1/2k or
so for the calculator can't sit underneath rom because the calculator uses some
of the ROM routines and rom has to be switched off in order to access ram in
that area).  The RAM above $C000 will also be completely free, as well as the
cassette buffer RAM, so other routines that normally install in these areas can
still be used.

    I'm currently working on a couple other functions to add to Q-Tility,
including a mini-terminal emulator, a disk sector editor, a routine to list a
basic program from disk to the screen, and a memory dump in hexadecimal.  But I
will probably be upgrading and improving on the original idea for some time to
come (a good hack is never really finished), and I can't wait forever to get
something marketable completed.  I may also write seperate utility programs
(such as a "Hacker's" Utility) with some of these and other functions for
seperate marketing, using the same basic driver.

    I'm also working on a couple of routines to make the program compatible
with as many other commercial programs as possible, and M.L. programs that
wedge into the basic interpreter.  Currently, Q-Tility can be disabled by
pressing the RUN-STOP/RESTORE combination of keys, and re-enabled again with
SYS 49152.  I did not want to disallow the RUN-STOP/RESTORE combination, as the
user could possibly need it for disabling some other program he is using.  The
only other way i can think of right now to make Q-Tility 'unstoppable' is to
put it on cartridge, which would add to its expense and the difficulty of
offering upgrades and fixing any previously-undiscovered bugs.

    As an example of Q-Tility's potential, I have tested it with machine
language monitors such as SUPERMON and MICROMON in current execution, and it
works well with them, adding Q-Tility's functions to those already available
within the monitors.  There aren't any monitors I have seen that have a
full-function calculator with the complexity of Q-CALC available, nor have I
seen one with a sequential file printer.  I have also used the program with the
Oracle Database Program by Batteries Included, as well as other commercial
programs and, as mentioned above, am working on compatibility with an even
wider range of programs.

    Registered users of Q-Tility (those who send $10 to the address below) will
be allowed to receive the next version, the one that will reside under basic
ROM, at cost for disk, postage, and handling (disk & copy costs) - $3.00.  New
programs, with different functions but using the same technique as Q-Tility
(such as the future "Hacker's" Toolkit) will also be made available to such
users at substantial discount.  I am a firm believer in the idea that useful
programs do not have to cost a fortune, and that copy-protection is not
necessary when a program is offered for a reasonable price.  I am counting on
you, the user, to prove me right.  I welcome any comments, criticisms,
questions, or suggestions that you might have.

CHARLES SHELTON
2626 FEDERAL ST.
EL PASO, TEXAS 79930
(915) 566-5369