
+----------------------------------------------------------+
|                                                          |
|                  TimeOut UltraMacros                     |
|                                                          |
|                   by Beagle Brothers                     |
|                                                          |
|                                                          |
|                                                          |
|                 Documentation typed by:                  |
|                                                          |
|         Chapter 1      Some Other Guy                    |
|         Chapter 2      Some Other Guy & Sects Fiend      |
|         Chapter 3      Sects Fiend                       |
|         Chapter 4      Sects Fiend & Some Other Guy      |
|                                                          |
|                    Sects Fiend                           |
|                  Sends Thanks to:                        |
|                                                          |
|       Shiftr Shiftr, Captain Sensible, Robin Hood        |
|                                                          |
|                                                          |
|                  Some Other Guy                          |
|                  Sends Thanks to:                        |
|                                                          |
|        Beowulf and the Strata Crackers gang              |
|                                                          |
+----------------------------------------------------------+


Page numbers are not provided for obvious reasons. The table of contents is
provided so you can see what is in each of the 5 files and where things are in
relation to each other.

                              Contents
                              --------

Chapter 1      Welcome to TimeOut UltraMacros
                     So What's a Macro?
                     Special Features of UltraMacros
                           New AppleWorks Commands
                           Bug Extermination
                           Mousing Around

Chapter 2      Installation
                     TimeOut Compatibility
                     Installing TimeOut
                           The TimeOut Menu
                           Location of TimeOut Applications
                           Location of AppleWorks
                           Reinstalling TimeOut
                     Installing UltraMacros
                     Copying Applications to the TimeOut Applications disk
                     Starting up AppleWorks with TimeOut
                     Accessing TimeOut Applications
                     Memory usage
                     Control Reset Patch

Chapter 3      UltraMacros Tutorial
                     Using the New UltraMacros Commands
                     Recording Your Own Macros
                     Creating Custom Macros
                           Built-In Macros
                           Creating a Macro File
                           Creating your Very Own UltraMacro


HERE TO THE END IS IN FILES CHAPTER 4

Chapter 4      UltraMacros Reference
                     The Anatomy of a Macro
                           Tokens
                           Local and Global Macros
                           Calling other Macros
                     Reserved Macros
                           <sa-del>     SOLID-APPLE-DELETE
                           <ahead>      SOLID-APPLE-.
                           <back>       SOLID-APPLE-,
                           <date>       SOLID-APPLE-'
                           <date2>      SOLID-APPLE-"
                           <time>       SOLID-APPLE-=
                           <time24>     SOLID-APPLE-+
                           <find>       SOLID-APPLE-RETURN
                           <findpo>     SOLID-APPLE-^
                           <print>      SOLID-APPLE-P

                     New Open-Apple Commands
                           no token     OPEN-APPLE-X
                           "sa-del"     OPEN-APPLE-DELETE
                           "getstr"     OPEN-APPLE-O
                           <oa-ctrl-@>  OPEN-APPLE-CONTROL-@
                           <uc>         OPEN-APPLE-:
                           <lc>         OPEN-APPLE-;
                           <insert>     OPEN-APPLE-!
                           <zoom>       OPEN-APPLE-@
                           <read>       OPEN-APPLE-^
                           <disk>       OPEN-APPLE-&
                           <path>       OPEN-APPLE-*
                           <cell>       OPEN-APPLE--
                           <store>      OPEN-APPLE-<
                           <recall>     OPEN-APPLE->
                           <inc>        OPEN-APPLE-CONTROL-W
                           <dec>        OPEN-APPLE-CONTROL-A
                           <bell>       OPEN-APPLE-CONTROL-G
                           <nosleep>    OPEN-APPLE-CONTROL-N
                           <clear>      OPEN-APPLE-CONTROL-X

                     Special UltraMacros Tokens
                           <input>
                           <id#>
                           <ifkey>
                           <key>
                           <begin>
                           <rpt>
                           <stop>

                     Special UltraMacros Tokens with Parameters
                           Defining Numeric Variables
                           Defining String Variables
                           Parameters
                           <chr$ NUM>
                           <getstr NUM>
                           <goto MACRO>
                           <hilight NUM EXP,NUM EXP,NUM EXP,NUM EXP>
                           <left STRING VSR,NUM>
                           <len STRING VAR>
                           <msg STRING>
                           <onerr OPTION>
                           <posn VAR,VAR>
                           <pr# NUM EXP>
                           <print>
                           <rem STRING>
                           <right STRING VAR,NUM>
                           <screen NUM EXP,NUM EXP,NUM EXP>
                           <str$ VAR NAME>
                           <val STRING VAR>
                           <wait NUM EXP>
                           <wake MACRO at NUM EXP:NUM EXP>

                     If-Then-Else Logic
                           <if>
                           <ifnot>
                           <then>
                           <else>
                           <elseoff>

                     For Experienced 6502 Programmers Only
                           <call>
                           <poke>
                           <peek>

                     Macro Compiler
                           Compile a New Set of Macros
                           Macro Compiler Errors
                           Display Current Macro Set

                     Macro Options
                           1. Launch a New Task
                           2. Create a Task File
                           3. Save Macro Table as Default Set
                           4. Deactivate Macros
                           5. Reactivate Single Stepping
                           6. Version
                           7. Other Activities

                     Other Activities
                           1. Set Cursor Blink
                           2. Set Mouse Button Response
                           3. Set Mouse Response
                           4. Deactivate the Mouse
                           5. Reactivate Key Lock
                           6. Reactivate Screen Preserver
                           7. Set Screen Preserver Delay

                     Data Converter
                     Allowing Control-@
                     Mouse Control
                     Linking Files
                     Startup Menus
                     Task Files
                     The Special Case of Macro Zero
                     A Macro Explained
                     TimeOut MacroTools
                     Changes from Super MacroWorks
                     Macro Token List

Appendix       TimeOut Utilities
                     Using the Utilities
                           Configure
                           Load to Memory
                           Dump from Memory
                           Change Memory Status
                           Change Name
                           Sort Menu

               Key Chart

Help!          Customer Support Information







WELCOME TO TIMEOUT ULTRAMACROS
------------------------------

TimeOut UltraMacros is a powerful addition to the TimeOut family of AppleWorks
enhancements, adding macro capability and numerous new commands that can be used
with any AppleWorks or UltraMacros application. Because UltraMacros is
compatible with all other TimeOut packages, it is a solid foundation to build
on.

So What's a Macro?
------------------
A macro is a single keystroke that does the work of many keystrokes. An
AppleWorks macro is a SOLID-APPLE key command; you simply hold down the
SOLID-APPLE key while pressing another key and a predefined sequence of
keystrokes is performed. For example, you can set up a macro like SOLID-APPLE-N
that types your name and address, or use SOLID-APPLE-I to indent a paragraph
three spaces (one keystroke instead of the usual seven). Macros save you a lot
of typing and a lot of time. Also, with fewer keystrokes, the fewer chances of
making errors.

  NOTE: The SOLID-APPLE key on the Apple //e and //c has been replaced by the
  OPTION key on the //gs. If you have a //gs, think OPTION whenever the manual
  mentions SOLID-APPLE.

  The //gs numeric keypad does not add extra keys for macro users. ENTER is the
  same as RETURN, CLEAR is CONTROL-X, and the other keys are simply duplicates
  of their main keyboard equivalents.

Remember that macros are SOLID-APPLE commands, The AppleWorks OPEN-APPLE
commands perform the same commands as before.

UltraMacros is a very flexible package. A wide variety of built-in macros are
provided on the UltraMacros disk. They can be used "as-is" or changed to suit
your own needs. You can also design completely new macros once you get more
familiar with UltraMacros. Novices and experts alike will appreciate the many
new OPEN-APPLE commands which are also included.

Special Features of UltraMacros
--------------------------------
In addition to macros, UltraMacros provides other features that make your life
at the keyboard easier and more productive. These include new AppleWorks
commands, an AppleWorks bug fix, and mouse control.

New AppleWorks Commands
-----------------------
UltraMacros adds new OPEN-APPLE and SOLID-APPLE commands that save you time and
effort. For example, you can press SOLID-APPLE-= at any time to enter the
current time (if you have a clock). Read about the new commands starting on page
16 (Chapter 3). A complete list of new commands starts on page 31 (Chapter 4).

Bug Extermination
-----------------
AppleWorks has a bug that doesn't allow you to enter CONTROL-@ for printer or
interface definitions. See page 72 (Chapter 4), for details on solving this
problem.

Mousing Around
--------------
UltraMacros allows you to use a mouse to scroll rapidly through AppleWorks and
to make menu selections. See page 72 (Chapter 4) for details.

  Note: This manual assumes that you are familiar with AppleWorks and the
  AppleWorks method of doing things (e.g. selecting menu options, etc.). If
  you're not, then refer to the appropriate sections of your AppleWorks manuals.

 -END- Chapter.1

                                   Chapter 2
                                  INSTALLATION


This chapter tells you how to install TimeOut and add the UltraMacros commands
to your AppleWorks Startup disk.

Before you can use macros and the new commands, you must update a copy of your
AppleWorks Startup disk. (Note: the floppy disk version of AppleWorks uses two
disks: a STARTUP disk and a PROGRAM disk. If you are running AppleWorks from a
hard disk, 3.5" disk or RAM disk, there is only one disk.)

You actually need to make two modifications to AppleWorks; TimeOut must be added
so that you can use the TimeOut applications on the UltraMacros disk, and then a
file, called ULTRA.SYSTEM, must be added to your AppleWorks STARTUP disk. This
is the actual macro program.

TimeOut UltraMacros is provided on both 5.25" and 3.5" disks. Before using your
TimeOut UltraMacros disk, please take a moment to make a backup copy of the disk
you will be using. Since the disks are not copy protected, you may use any
standard disk copier or Beagle Brothers' TimeOut FileMaster. Be sure to write
protect your original disk so you don't accidentally overwrite it. Please do
this now.


All of the sample AppleWorks files (macros) are on side 2 of the 5 1/4" disk.
Read "Path Notes" for information about the PathFinder demo.


Beagle Bros' software isn't copy protected. That makes it easier for you to use
and easier to make backup copies. Please support us in our commitment to supply
friendly, easy-to-use software by not giving away copies to your friends.

TIMEOUT COMPATIBILITY
---------------------

TimeOut is compatible with AppleWorks versions 2.0 and later. If you have an
earlier version, contact your dealer about getting an update from Apple. You
must also have the USA version. TimeOut does not work with foreign language
versions of AppleWorks.

TimeOut is compatible with most enhancements to AppleWorks including Applied
Engineering's desktop expander and Checkmate's desktop expander. UltraMacros is
not compatible with Pinpoint, Super MacroWorks or AutoWorks.

INSTALLING TIMEOUT
------------------

Once your backup copy has been made, boot your TimeOut UltraMacros disk by
placing it in your boot drive and turning your computer off and back on or by
pressing Control-Open-Apple-Reset. Then press "T" for install TimeOut.

Soon the title screen will appear. The menu contains three options.

     1. Update AppleWorks

     2. Read NOTES

     3. Quit

Select READ NOTES. This will inform you of any changes to TimeOut UltraMacros
that have been made since this instruction manual was printed.

After you read the NOTES, you will return to the TimeOut startup screen. This
time select Update AppleWorks.

THE TIMEOUT MENU
----------------
You must now specify whether or not you would like TimeOut to sort the list of
TimeOut applications in the TimeOut menu. The names will be sorted
alphabetically if you specify Yes. Otherwise, they will appear in the same order
as they do in the disk catalog. By specifying No, you decide the order of the
names in the TimeOut menu by placing them on your TimeOut applications disk in
the order you want.

LOCATIONS OF TIMEOUT APPLICATIONS
---------------------------------
The next step is to indicate where TimeOut should look for the TimeOut
applications. If you can't fit all of your TimeOut applications on a single
5 1/4-inch floppy disk, you can now have multiple application disks.  All of the
application disks must have the same name (for example: /TIMEOUT).  When you are
installing TimeOut on your AppleWorks disk, specify YES when asked if you need
more than one TimeOut Application disk.

When you start up AppleWorks, insert each TimeOut Application disk, specifying
YES when asked "Read another TimeOut Application disk?"  Specify NO when the
last TimeOut Application disk has been read.

Be sure to insert the correct TimeOut Application disk when you select the
application from the TimeOut menu.



 All of the TimeOut applications must be placed on the same disk, or any ProDOS
disk device. (See Copying Applications to the TimeOut Application disk several
pages ahead of this point.) The choices you have are:

     1. AppleWorks STARTUP disk

     2. Slot and Drive

     3. ProDOS directory

Be sure to insert the correct TimeOut Application disk when you select the
application from the TimeOut menu.


The simplest approach is to place the TimeOut Applications on your AppleWorks
STARTUP disk. By doing that, you never have to search for a separate TimeOut
Applications disk. If you have a hard disk or 3.5" disk, you can place them in
the same directory or subdirectory with your AppleWorks STARTUP program
(APLWORKS.SYSTEM).

If you have more than one disk drive, you may want to dedicate one drive to your
TimeOut Applications. You may specify either Slot and Drive or ProDOS directory
to indicate where the TimeOut applications disk will be. For more information on
ProDOS directories, see the section in your AppleWorks manual called ProDOS,
"prefix for filenames".

LOCATIONS OF APPLEWORKS
-----------------------
The next step is to indicate where your AppleWorks STARTUP program is so TimeOut
can be installed, You may specify either Slot & Drive or ProDOS directory. After
indicating the location of AppleWorks, press a key and your AppleWorks STARTUP
program will be updated with TimeOut.

REINSTALLING TIMEOUT
--------------------
After you have already installed TimeOut, if you need to change the applications
disk location or the order of the menu, you can reinstall TimeOut by following
the same steps for initial installation, This will only work if you have not
installed any other AppleWorks enhancement programs since you installed TimeOut.
If you have, then you may need to completely reconfigure AppleWorks.

INSTALLING ULTRAMACROS
----------------------
If you're already using Super MacroWorks, you may wish to read about the changes
on UltraMacros (Chapter 4) before continuing with this installation.

1. Make sure you have a copy of your AppleWorks STARTUP disk which has already
been modified with TimeOut. If you're using a desktop expander, install it
before installing UltraMacros. Make sure that your AppleWorks disk is functional
with all other modifications installed before attempting to add UltraMacros.

2. Boot the UltraMacros disk and press U for "Install UltraMacros." The macro
program (ULTRA.SYSTEM) will be installed into memory.

3. Remove the UltraMacros disk from the main disk drive, insert the AppleWorks
STARTUP disk and press RETURN.

4. The UltraMacros installation program will attempt to modify your AppleWorks
STARTUP disk. If it can't find it, it will prompt you to enter the pathname
where AppleWorks can be found. You probably won't have AppleWorks in a
subdirectory unless you understand subdirectories and pathnames already. In any
case, complete pathname information can be found in manuals such as the ProDOS
User's Manual. A pathname ALWAYS begins with a "/" followed by the disk name.
Any subdirectories following the disk name are preceded by a "/" as well.

5. Your AppleWorks STARTUP disk will be updated with UltraMacros' macros and new
commands. A message will appear on the screen when the updating is complete.

6. Press RETURN; the built-in macros and commands supplied with the UltraMacros
disk are now ready for use.


COPYING APPLICATIONS TO THE TIMEOUT APPLICATION DISK
----------------------------------------------------
If you are using other TimeOut applications, you will need to copy the
applications of the UltraMacros disk to your TimeOut applications disk.
Otherwise, you can use the UltraMacros disk as your TimeOut applications
disk.

Copy the following files:
     TO.MACRO.OPT
     TO.CLIPBOARD
     TO.UTILITIES
     TO.COMPILER


Note:  You may not need to copy the file TO.UTILITIES or TO.CLIPBOARD if
they're already on your TimeOut application disk.

If you do not have a file copy program, or you are not familiar with the one you
have, there is a new method of easily copying your TimeOut files to your TimeOut
Application disk.

After installing TimeOut on your AppleWorks disk, the installation program will
present a menu allowing you to do this.  Select "Copy files to TimeOut
Application disk" and then specify the location of your TimeOut Application
disk.  All of the TimeOut files will then be copied.


STARTING UP APPLEWORKS WITH TIMEOUT.
------------------------------------
When you start up AppleWorks with TimeOut installed, you should see the
TimeOut title screen before you reach the AppleWorks main menu.  TimeOut will
scan your TimeOut applications disk looking for TimeOut applications.

Note:  If you receive a message indicating that TimeOut is getting
errors trying to load the TimeOut applications, it means that TimeOut is
unable to find the applications.  At this point you must insert your
applications disk if you have not already done so.  If you have inserted your
applications disk and are still getting errors, you either do not have any
applications on the disk or your disk has been damaged.  You will need to
create a new applications disk.

If you do not see a TimeOut title screen, you have not installed TimeOut
correctly.  Go back and start over.

As TimeOut identifies each TimeOut application, they are listed on the
screen.  An asterisk ("*") before the application name indicates that it is
memory-based.  You may press Escape at any time to cancel loading
memory-based applications.

Note:  If you use a program selector such as the Apple Desktop you must
select ULTRA.SYSTEM instead of APLWORKS.SYSTEM.  The APLWORKS.SYSTEM file has
been renamed to APLWORKS.SYS so that booting ProDOS will automatically start
ULTRA.SYSTEM.  If you select APLWORKS.SYS, you will run normal AppleWorks
without any macros.


ACCESSING TIMEOUT APPLICATIONS
------------------------------
While you are using AppleWorks, you may call up the TimeOut menu at any
time by pressing Open Apple-Escape.  A menu similar to the following will
appear (you may have fewer or more applications than this):

                            ________________________
                            |                      |
                            |     TimeOut Menu     |
                            |______________________|
                            |                      |
                            |  1. FileMaster       |
                            |  2. Graph            |
                            |  3. QuickSpell       |
                            |  4. SideSpread       |
                            |  5. SuperFonts       |
                            |  6. Macro Options    |
                            |  7. Utilities        |
                            |______________________|


   Use the up and down arrow keys or type a number to select an application,
then press Return (press Escape if you don't want to make a selection).  If
your applications are not memory-based, be sure your TimeOut applications
disk is in the drive when you press Return.  Otherwise, you will be prompted
to insert your TimeOut application disk.


MEMORY USAGE
------------
You will notice with TimeOut installed that you have slightly less desktop
memory for your AppleWorks documents.  TimeOut itself takes up some of the
memory.

Memory-resident TimeOut applications also take up desktop memory.  If you
are short on desktop memory, reconfigure your applications so they are
disk-based.

However, for maximum speed, make your TimeOut applications memory-based or
run them from a RAM disk.

Note:  UltraMacros is always in memory.  However, it resides in a
special place that doesn't take up any desktop memory.


CONTROL-RESET PATCH
-------------------
When you install TimeOut on your AppleWorks Startup disk, TimeOut makes a
patch to AppleWorks so that Control-Reset will take you to the Main Menu
instead of the machine language monitor.

 -END- Chapter 2

                                   CHAPTER 3


ULTRAMACROS TUTORIAL
--------------------

This section introduces you to some of the new commands included with
UltraMacros.  It assumes that you've already booted AppleWorks and are in a
Word Processor file (UltraMacros works everywhere in AppleWorks, but the Word
Processor is a good place to test things).


USING THE NEW ULTRAMACROS COMMANDS
----------------------------------
UltraMacros adds several new SOLID-APPLE and OPEN-APPLE commands to
AppleWorks.  Try these for starters:

1] Press SOLID-APPLE-'.  The date set when AppleWorks was started up will be
   displayed in the format:  September 27, 1987.  If an error beep happens
   instead, UltraMacros is not installed.

2] Now place the cursor on the first letter of the date that you entered step1
   and press OPEN-APPLE-;.  The letter will be changed to lower case For
   example, "September 27, 1987" would now be "september 27. 1987".

3] Press OPEN-APPLE-:.  The next letter will be switched to upper case.  Get the
   picture?  You can change the case of any letter with the colon/semi-colon
   key.  If you hold down OPEN-APPLE and press the key normally, the letter
   becomes lower case; if you also hold down the shift key, the letters become
   upper case.  The cursor is always changed to overstrike mode so that extra
   letters aren't inserted.

4] Place the cursor in the middle of a word and press OPEN-APPLE-DELETE or
   SOLID-APPLE-DELETE.  The character under the cursor will be gobbled, but the
   cursor will remain at the same spot.  This command actually executes two
   normal AppleWorks keystrokes- a RIGHT-ARROW followed by DELETE.

These new OPEN-APPLE commands can be used anywhere that AppleWorks prompts
you for input.  For example, the OPEN-APPLE-DELETE command can be used to
change a file name after you press OPEN-APPLE-N.  Or you can press
SOLID-APPLE-' to enter the date when the Data Base asks you to "Type report
date" when you're printing a file.


Recording Your Own Macros
-------------------------
This section tells you how to record your keystrokes so that they can be
played back later with one keypress.  It assumes that you've already booted
AppleWorks and are currently in a Word Processor file.

1] Press OPEN-APPLE-X.  The title at the top of the screen changes to RECORD
   A MACRO.  If it doesn't, you didn't install UltraMacros right.

2] The prompt at the bottom tells you to "Select macro key:".  Press the "T"
   key to record a "Test" macro.  SOLID-APPLE-T will be used to activate this
   macro later.  The bottom right side of the screen will show "Recording T"
   and the cursor will stop blinking.

3] You are now in record mode and whatever you type (mouse moves are
   included) will be memorized.  Type your name and press RETURN.

4] Now press CONTROL-@ to end the macro definition.  (On IIgs's and some
   other II's you don't have to press the shift key; on some you do).  The
   cursor will start blinking and the bottom right side of the screen will
   show "Done macro T".

5] You've just recorded you first macro!  To use it, hold down the
   SOLID-APPLE key and press T.  Your name is typed much faster than it was
   entered, unless you're an incredible typist.  This macro can now be used
   anywhere that AppleWorks expects keyboard input:  in a file, naming a
   file, etc.

6] Now press OPEN-APPLE-X and press T again.  This message appears on the
   bottom line:  "Replace global macro T?"  Because you already have a macro
   "T" in your macro set, UltraMacros lets you decide if you want to destroy
   the original macro.  This is a safeguard to avoid accidentally erasing a
   macro.

7] Press Y to replace your "T" macro.  You can now record the new macro.
   This time, press OPEN-APPLE-1 first.  The cursor jumped to the beginning
   of the file.  Any OPEN-APPLE command can be recorded as part of the macro.

8] Now press RETURN followed by the UP-ARROW and enter your name on the top
   line of the file.  Press CONTROL-@ to end the macro.

9] Press OPEN-APPLE-9 to jump to the end of the file, and then press
   SOLID-APPLE-T to try out the modified macro "T".  It will jump to the top
   of the file, insert a line, and enter your name.

You can press OPEN-APPLE-X to start recording macros from virtually
anywhere in AppleWorks or in a TimeOut application.  You may not press
OPEN-APPLE-X when the TimeOut OPEN-APPLE-Escape menu is visible on the
screen, or when you're in the middle of an OPEN-APPLE-O getstring command.
The command will be ignored.  However, you may start a macro within
AppleWorks and then press OPEN-APPLE-ESCAPE or OPEN-APPLE-O as part of the
macro.

Most key can be recorded as macros.  Look down farther for a list of
reserved macros.  Keep in mind that there is no difference between upper and
lower case macro names, and that all "named" keys such as RETURN and TAB have
CONTROL-key equivalents (e.g. TAB is actually CONTROL-I).

Press OPEN-APPLE-X to enter record mode.  Press OPEN-APPLE-T.  The
Recording T message will appear.  Enter something and press CONTROL-@ to end
the macro.  Press SOLID-APPLE-T.  Your name is entered as defined above.
Press BOTH-APPLE-T.  The thing you just entered appears.

All keys can have both SOLID-APPLE and BOTH-APPLE definitions.  Macros
that are reserved SOLID-APPLE commands, such as SOLID-APPLE-RETURN, can be
defined as BOTH-APPLE macros.  The UltraMacros sample includes BOTH-APPLE
definitions for the named keys such as TAB, ESCAPE, etc.  Of course, they can
easily be changed.  It's a good idea to use BOTH-APPLE macros for potentially
dangerous macros (like quit AppleWorks without saving files) that you don't
want to execute accidentally.

You can record a macro for anywhere from 2 to 4,000 or so keystrokes,
depending on how many macro keystrokes are already in memory.  If the macro
table is full, the Done macro message will appear as soon as you press the
new macro key, unless you're replacing an existing macro.  Then you'll be
able to enter as many keystrokes as the original macro contained.

The only exception is macro 0(zero).  You can always enter up to 80
keystrokes, but it also automatically stops recording at 80 keystrokes.

Any macros recorded using OPEN-APPLE-X are lost when you exit AppleWorks.
There are two ways to make the macros permanent.  One way is to use the
Macro Options third option "Save macro table as default set".  This save all
active macros "as-is".  The next section explains how to edit existing macros
and then make them permanent.


Creating Custom Macros
======================
This section tells you how to create custom macros by editing a macro
file, compiling the changed macros, and then saving them on disk.

Built-In Macros
---------------
The built in macros are those macros which are part of ULTRA.SYSTEM and
are available whenever you start AppleWorks.  These macros (except for a few
reserved macros) can be changed at any time to anything you wish.

1] Boot AppleWorks and insert the UltraMacros disk.

2] Add the Word Processor file Macros Ultra to the Desktop from the
   UltraMacros disk and print it for a handy reference.  These are the sample
   macros included with ULTRA.SYSTEM.  All of them are available for use if
   you've added UltraMacros to your AppleWorks disk.

3] Examine the printout while reading the descriptions of how macros are
   made.  You can modify this file to create your own custom macros.
   Modifying existing macros is a good way to learn about writing your own
   macros.

Creating a Macro File
---------------------
A macro file is any AppleWorks Word Processor file which contains macro
definitions.  You can create a custom macro file by adding an existing macro
file to the Desktop and changing the definitions, or by using the Macro
Compiler's Display current macro set option to list the current macros into a
file.  There's nothing magical about the macro definitions in the Word
Processor.  They must be complied into true macro codes to be used by
UltraMacros.

Creating your very own UltraMacro
---------------------------------
Here's a step-by-step look at creating your first custom macro definition
and making it a permanent part of AppleWorks.

1] Start up your UltraMacros version of AppleWorks.
2] Insert the UltraMacros disk and add the file Macros Ultra to the desktop.
   Use OPEN-APPLE-N to change it name to Macros Mine.  Macro file names don't
   have to start with "Macros"; it just makes it easier to find them that
   way.
3] Go back to the AppleWorks Main Menu and then make a new Word Processor
   file called TEST.
4] Press SOLID-APPLE-B to see a sample "begin a memo" macro.
5] Press SOLID-APPLE-N to see the author's daughter's name.
6] Now press OPEN-APPLE-Q and return to the Macros Ultra file.
7] Use the OPEN-APPLE-F command to find "Heather".  You should see the
   following macro definition:

        N:<awp>Heather Brandt! name of a little "Lassie" lover

8] Change Heather Brandt to your name.  Ignore the <awp> for now.  Just make
   sure that your name is immediately after <awp> and is followed by a "!".
   You could cheat and use OPEN-APPLE-R to replace it, but that won't teach
   you anything.
9] Now use the OPEN-APPLE-F command to find "B:<awp".  You should see the
   following macro definition:

        B:<awp><rtn><rtn>
        Date:  <date><rtn><rtn><rtn>
        From:  <sa-n><rtn>
              JEM SOFTWARE<rtn>
              P.O. Box 20920<rtn>
              El Cajon, CA  92021<rtn><rtn><rtn><rtn>
        To:  ! begin a memo

The first line contains special bracketed codes call tokens. Each <rtn>
represents a carriage return.

The second line also contains <date>.  This token will always print the
date which was set when AppleWorks was first started.

   The third line contains <sa-n>.  This is the same as pressing
SOLID-APPLE-N; that's why the macro printed the name given in macro-N.
Switch back to the TEST files and look at what the macro did until you can
see the relationship between the macro definition and the result.

10] Replace the sample address between the From: and To: lines with your own
    address.  Start each line in the same column as the "J" in JEM and end
    with a <rtn>.
11] Now press OPEN-APPLE-ESC and select Macro Compiler.
12] Press RETURN to select Compile a new set of macros.
13] Press RETURN to select No for the Pause each line? prompt.
14] Press RETURN to select Beginning for the Compile from? prompt.
15] The compiler will then scan the entire file, converting the text and
    tokens into UltraMacros' codes.
16] Press OPEN-APPLE-Q and select the TEST file.
17] Press SOLID-APPLE-B to see the memo macro with your name included within
    it.  Now press SOLID-APPLE-N to see just your name.
18] If the macros don't work the way you think they should, go back and
    examine the definition again, comparing it to the samples in steps 7 and
    9.
19] Now press OPEN-APPLE-ESC and select Macro Options.
20] If your AppleWorks Startup disk is not in a drive, remove your Program
    disk and insert the Startup disk.
21] Select Save current macros as default set.
22] Press RETURN to select No for Activate auto-startup macro?
23] The ULTRA.SYSTEM file will be updated with the new macro definitions.
    Re-insert your AppleWorks program disk if necessary and press RETURN to
    return to AppleWorks.
24] Save your "Macros Mine" file and exit AppleWorks.
25] Now restart AppleWorks and make a new Word Processor file.
26] Press SOLID-APPLE-B.  Voila!  Your new definition is in effect along with
    all of the other Macros Ultra sample macros.
27] Press SOLID-APPLE-B again, but this time tap the ESC key immediately
    afterward.  The macro is halted before it finishes.  You can press ESC
    to stop any run-away macros.

 -END- Chapter 3

                                   CHAPTER 4

ULTRAMACROS REFERENCE
---------------------
This chapter explains in excruciating detail the capabilities of UltraMacros. In
fact, it's everything you ever wanted to know about macros - but were afraid to
ask. (No it is not, however, this is all Beagle is offering at this time. stay
tuned to the board of your choice.)


THE ANATOMY OF A MACRO
----------------------
Before you can start creating macros, you need to understand how a macro s
built. The "syntax' of a command is the set of rules governing the organization
and usage of that command. In an English sentence, "He here is" would be
improper syntax because "is" should precede "here". In a like manner, macro
commands must be organized in such a way that UltraMacros can understand what
you want to have accomplished.

TOKENS
------
Take a look at the macros in the Macros Ultra file (the macros come after
the word START and before the word END).  Each macro is made up of a series
of normal characters and special tokens.

A token is a code word enclosed in brackets that represents a special
keystroke or macro command.  For example, the token <rtn> represents the
RETURN key, and the token <left> represents the LEFT-ARROW key.  The macro
compiler converts these readable tokens into the equivalent invisible command
codes within the macro.

Here's a macro a few lines into the Macros Ultra file:

       C:<awp><oa-O>CN<rtn><esc>!   center text

Each macro begins with a character or token that represents the key used
with SOLID-APPLE to activate the macro.  In this example, the character "C"
indicate that this macro is executed by pressing SOLID-APPLE-C.

Next comes a colon, followed by a token that designates where the macro
will work; this macro is for the Word Processor.

Next come the keystrokes and tokens that actually make up the macro.  In
this example there are five keystrokes:  OPEN-APPLE-O, C, N, RETURN, and
ESCAPE.

An exclamation mark signals the end of the macro definition.  Any text
after the "!" is ignored.  In this example the words "center text" describe
what the macro does.  They are not considered part of the macro.

   Here are some of the tokens that you can use to create macros:

<del>               DELETE key
<esc>               ESCAPE key
<rtn>               RETURN key
<tab>                  TAB key
<left>          LEFT-ARROW key
<right>        RIGHT-ARROW key
<up>              UP-ARROW key
<down>          DOWN-ARROW key
<spc>            SPACE BAR key


   The tokens for OPEN-APPLE, SOLID-APPLE, BOTH-APPLE and CONTROL commands
use the abbreviations oa, sa, ba, and ctrl followed by a hyphen and the
appropriate key.  Here are some examples:

<oa-1>              OPEN-APPLE-1
<sa-B>              SOLID-APPLE-B
<ba-right>          BOTH-APPLE-RIGHT-ARROW
<sa-ctrl-C>         SOLID-APPLE-CONTROL-C

UltraMacros adds a number of unchangeable OPEN-APPLE and SOLID-APPLE commands to
AppleWorks (See the "Reserved Macros" heading).

Tokens may be entered in upper or lower case, but no spaces are allowed
between the letters making up the token.  For example, <rtn>, <RTN>, and
<Rtn> are all valid tokens for the RETURN key, but <rtn> is not valid.

Multiple consecutive tokens can be used without brackets around each
individual token.  Just separate the tokens with spaces and/or colons.  For
example, two UP-ARROW commands followed by a LEFT-ARROW can be represented as
<up><up><left>, <up up left>, <up : up : left>, or <up><up left>.

The compiler also allows you to include comments between the <brackets>.
Comments are surrounded by curly {braces}.  The previous example could
include a comment like this:

       <up : up : {this text gets ignored by the compiler} left>

The macro compiler will ignore the curly braces and everything between
them.  No macro table space is wasted by using comments.  The previous sample
will compile into three bytes two UP-ARROW codes and one LEFT-ARROW code. Do NOT
use token <> brackets inside of the {} comment brackets. This is legal: a:<all {
comment } stop>! but this isn't: a:<all { --> see? }>!


Note:  If the curly braces are not between token brackets, they will be
treated as normal text.


LOCAL AND GLOBAL MACROS
-----------------------
Each macro must be classified as either local or global.  A global macro
is one that works anywhere.  A local macro is one that works only within a
specific application.

In a macro definition, the token just after the colon indicates whether
the macro is local or global:

<all>               ALL applications (global)
<awp>               AppleWorks Word Processor
<adb>               AppleWorks Data Base
<asp>               AppleWorks Spreadsheet
<ato>               A TimeOut application only

You can't have more than one global macro with the same name (the second
one will never be used), but you can give the same name to several local
macros as long as they are in different applications.

The order in which macro definitions appear in a file is important.  When
you select a macro, UltraMacros starts at the beginning of the macro table
and searches for the first macro with the specified name. When a match is
found, the application definition is checked.

1] If the macro is type <all>, it is executed regardless of where you are
   within AppleWorks or TimeOut.
2] If the macro is type <ato>, it is executed only if you are currently in a
   TimeOut application.
3] If the macro is an AppleWorks application type, UltraMacros checks to see
   if you're in the specified application.  If so, the macro is executed; if
   not, it keeps searching.

From this you can see that if multiple macros are created with the same
name, the local AppleWorks macros should be first, followed by the TimeOut
macros, followed by the global macros.

TimeOut is part of AppleWorks, so you don't have to use <ato> in macros
which are designed for TimeOut; <ato> just makes sure that the macros will
not run outside of a TimeOut application.

Note:  BOTH-APPLE macros are not considered the same as SOLID-APPLE macros
even if they use the same key.  A key such as "A" could conceivably have
eight completely different definitions; a BOTH-APPLE and SOLID-APPLE command
for <awp>, <adb>, <asp> and <ato>.

Recorder macros (those defined using OPEN-APPLE-X) are global by default.
If you want to make a recorded macro local, list the macros into a file and
use AppleWorks to change the <all> token to a local token.  Then recompile
the macro set.


CALLING OTHER MACROS
--------------------
One macro can call another macro in two different ways:

   y:<all><sa-left oa-M>T<down left rtn>! delete a line
   9:<awp : oa-9 : up : goto sa-y>! delete the last line in a file

   In the first example, SOLID-APPLE-Y calls macro SOLID-APPLE-LEFT to move the
   cursor to the left column; UltraMacros then returns to SOLID-APPLE-Y and the
   current line is moved to the clipboard.

   In the second example, SOLID-APPLE-9 uses the <goto> command to send control
   to macro SOLID-APPLE-Y. UltraMacros never returns to SOLID-APPLE-9 because
   <goto> is a "one-way" command.

Users with BAsic programming experience can think of the first example as
a GOSUB and the second as a GOTO (how fitting).  Just remember that using a
macro NAME will continue the current macro when the called macro is finished,
and that using GOTO means that the macro will never come back.

"Macro nesting" occurs when a macro calls a macro which calls a macro...
UltraMacros has to remember where to back up to when the current level is
finished.  The limit is 18 levels. A macro which calls itself will also
execute 18 times and then stop.

                    1:<all>*<sa-1>! print 18 asterisks

To execute a procedure more often, use <begin> and <rpt> along with
variables (they are explained later).

 <ba-1>:<all : A = 120 :begin : print "*": A = A - 1: if A > 0 then rpt>!
                      print 120 asterisks

CAUTION:  When you're about to delete a macro from a file, make sure the
macro isn't needed by another macro in the file.  Use the OPEN-APPLE-F
command to search for references to the macro.  For example, if you plan to
delete macro F, search for "sa-f".


RESERVED MACROS
---------------
The special macros listed below cannot be re-recorded, changed or deleted;
you must use them "as is".  You can use these macros at any time (unless
otherwise noted): directly from the keyboard (press the appropriate key along
with SOLID-APPLE), while recording a macro (press the appropriate key along
with SOLID-APPLE), or in a macro definition (use the appropriate token).

Macros SOLID-APPLE-CONTROL-@ and SOLID-APPLE-^ are also reserved. They don't do
anything, at least not that you'd care about. You are allowed to use the
BOTH-APPLE equivalents of these two macros, however.

___________________________________________________________________________

<sa-del>            SOLID-APPLE-DELETE
   Deletes the character under the cursor.
___________________________________________________________________________

<ahead>             SOLID-APPLE-.
   Finds the first blank space to the right of the cursor position.  This
macro works wherever AppleWorks allows you to edit characters, including Word
Processor files, Data Base categories, at Find prompts, and when AppleWorks
prompts you to enter names.
___________________________________________________________________________

<back>              SOLID-APPLE-,
   Finds the first blank space to the left of the cursor position.
___________________________________________________________________________

<date>              SOLID-APPLE-'
   Displays the date in this format: September 29, 1987 (handy for dating
letters or Data Base and Spreadsheet reports).

___________________________________________________________________________

<date2>             SOLID-APPLE-"
   Displays the date in this format: 09/29/87 (handy for dating transactions
in the Spreadsheet).

___________________________________________________________________________

<time>              SOLID-APPLE-=
   Displays the time in this format:  6:50 pm.  If you don't have a clock,
the time will always be 12:00 am.
   NOTE:  If you have a //gs and 12:00 am is always given for the time,
you'll need to copy the ProDOS file from the UltraMacros disk to your
AppleWorks startup disk.

___________________________________________________________________________

<time24>            SOLID-APPLE-+
   Take a guess.

 ___________________________________________________________________________

<find>              SOLID-APPLE-RETURN

In the Word Processor:
Moves the cursor to the next carriage return marker. This command only works
when the "Type entry..." message is visible at the bottom of the screen.

At any numbered inverse bar menu or file list:
Searches for the text stored in macro 0 (zero) and leaves the cursor at that
item.  If the text is not found, the macro will stop completely or go into a
continuous loop.

If you're at a file list and want to find a file in a hurry, press OPEN-APPLE-0
to define macro 0 with the name and then press SOLID-APPLE-RETURN to find the
file.  From within a macro, you can use this command to automatically load files
by name.

This command also works with the OPEN-APPLE-Q Desktop Index and the
OPEN-APPLE-ESC TimeOut menu.  Macros can find desktop files by name, or start
TimeOut applications by name.  Define macro 0 ahead of time; you can not use
OPEN-APPLE-0 while the OPEN-APPLE-ESC TimeOut menu is on the screen.

Use the ability to search a menu to find printers by name when you aren't
sure what order they'll be in.

NOTE:  The <find> command only uses the first 15 characters in Macro 0 ($0).
NOTE:  <find> can be used with <store> and <recall> to link files.

The <find> command now works differently with menus. If the item is not found,
the current macro will be ended. If the macro containing <find> was called from
another macro, the calling macro will continue.

This means that any macros containing <find> (if they will be called from other
macros) should end with a <stop>. This way the calling macro is only executed if
the item is not found, and can therefore be used for error-trapping. A macro
could search for a file, and if unsuccessful, it could then change to another
disk and search it. Before you only had one shot at it. See the CONTROL-P phone
macro in Macros Ultra for an example.


___________________________________________________________________________

<findpo>            SOLID-APPLE-^
In the Word Processor only:  Moves the cursor to the next caret.  The
caret may be a printer options caret or a text caret which is part of the
document.  This macro only works when the "Type entry or ..."  message is
visible at the bottom of the screen.

This macro is easier to use for locating printer options in a file than
the OPEN-APPLE-F command, which requires you to know which option you're
searching for (and its two-letter code).  <findpo> simply searches for the
next caret in the file regardless of what it represents.

A macro can use the <screen> command to check what kind of option was
found by <findpo>.  For example, this macro finds the next superscript or
subscript code, but ignores all other printer codes or carets:

   <ctrl-s>:<awp><findpo : $8 = screen 42,24,4 : if $8 = "Subs" then stop
                 else if $8 = "Supe" then stop else rpt>!

___________________________________________________________________________


<print>             BOTH-APPLE-CONTROL-P
   The print token is for use within macros only.
___________________________________________________________________________
___________________________________________________________________________


NEW OPEN-APPLE COMMANDS
-----------------------

   The following commands can be used directly from the keyboard as well as
from within macros.  If you're recording a macro. press the appropriate key
along with OPEN-APPLE.  To use the command in a macro definition, use the
token.

___________________________________________________________________________

no token            OPEN-APPLE-X
   Begin recording a macro.  This command must be used from the keyboard
only; it can't be used within a macro.

___________________________________________________________________________

"sa-del"            OPEN-APPLE-DELETE
   Deletes the character the cursor is on.  This command is identical to
SOLID-APPLE-DELETE.  NOTE:  When recording a macro, you must use
SOLID-APPLE-DELETE.

___________________________________________________________________________

"getstr"            OPEN-APPLE-0 (zero)
   Presents a ">" prompt on the bottom line of the screen, allowing up to 60
characters to be entered for defining macro 0.  This command is used from the
keyboard only.  Do not use it while recording a macro.

___________________________________________________________________________

<oa-ctrl-@>         OPEN-APPLE-CONTROL-@
   Sends a CONTROL-@ to AppleWorks.  Use this while recording or defining a
macro.  If you just use CONTROL-@ the macro will stop at that point.
CONTROL-@ is used only for printer and interface definitions.  NOTE:  Make
sure you used the bug fixer in the main menu of UltraMacros before you use
this.

___________________________________________________________________________

<uc>                OPEN-APPLE-:
   Changes the character at the cursor to upper case.

___________________________________________________________________________

<lc>                OPEN-APPLE-;
   Changes the character at the cursor to lower case.

___________________________________________________________________________

<insert>            OPEN-APPLE-!
   Turns on the insert cursor.  To turn on the overstrike cursor, use this
command followed by an OPEN-APPLE-E command.

___________________________________________________________________________

<zoom>              OPEN-APPLE-@
   Forces zoom OUT.  Follow this command with OPEN-APPLE-Z to zoom in.

___________________________________________________________________________

<read>              OPEN-APPLE-^
   From the keyboard, OPEN-APPLE-^ will read the character at the current
cursor position into macro 0.  You can use the arrow keys to move the cursor
to a new position before reading another character.  While recording a macro,
OPEN-APPLE-^ will read the character at the current cursor position into the
macro being recorded (the character will become text in the macro
definition). In a macro definition, successive <read>'s add to macro 0. If you
want each <read> to reset macro 0, put the <read> in another macro and call that
macro:

a:<all sa-b : if $0 = "." then left else rpt>! go to end of sentence
b:<all read>!

A better way to do the same thing would be to read the cursor character
directly:

c:<all X = peek $10F5 : ifnot X = 174 then right rpt>! go to end of sentence


<cell> can also read the current Word Processor line. It has some problems in
the spreadsheet. See macro <ba--> in Macros Ultra for a macro that reads the
exact screen contents of a cell.


___________________________________________________________________________

<disk>              OPEN-APPLE-&
   Reads the current volume name or subdirectory pathname into macro 0.  This
command can only be used when a list of files is being displayed.  A brief
flash at the top left of the screen indicates that the command was executed.

___________________________________________________________________________

<path>              OPEN-APPLE-*
   Reads the current volume name or subdirectory name and the currently
highlighted file name into macro 0.  This command can only be used when a
list of files is being displayed.  A brief flash at the top left of the
screen indicates that the command was executed.

___________________________________________________________________________

<cell>              OPEN-APPLE--
Reads the contents of the current Spreadsheet cell, Data Base category, or the
current Word Processor line into macro 0.  Move the cursor to the cell and use
the command.  A brief flash at the top left of the screen indicates that the
command was executed. The current layout and display setting do not affect
<cell>.  In the spreadsheet it uses the literal values or label as displayed on
the cell indicator line, and in the Data Base it uses the full category entry as
shown in the single-record layout.  From within a macro, use <cell> as part of
any string definition like this:


           c:<asp : $3 = cell : down : print $3>!  copy a cell

___________________________________________________________________________

<store>             OPEN-APPLE-<
Stores the current contents of macro 0, up to 15 characters, in a special unused
area of a word processor, spreadsheet, or data base file. The name being stored
is displayed at the bottom right of the screen. This command is designed for
linking files, but it may be used for any other purpose you think of.

<store> and <recall> also work with the Data Base.
___________________________________________________________________________

<recall>            OPEN-APPLE->
Sets macro 0 equal to the text stored by the <store> command.  <store>
would be rather useless if the information couldn't be recalled.

<store> and <recall> also work with the Data Base.
___________________________________________________________________________

<inc>               OPEN-APPLE-CONTROL-W
   Increments the character at the current cursor position.  For example, "a"
becomes "b".  It follows the ASCII numbers.

___________________________________________________________________________

<dec>               OPEN-APPLE-CONTROL-A
   Opposite of <inc>; decrements the character at the current cursor
position.

___________________________________________________________________________

<bell>              OPEN-APPLE-CONTROL-G
   Sounds the AppleWorks error bell once.  It's handy for getting someone's
attention.

___________________________________________________________________________

<nosleep>           OPEN-APPLE-CONTROL-N
   Cancels the currently defined "sleeping" macro, if any.  See the
description of <wake> for more information.

___________________________________________________________________________

<clear>             OPEN-APPLE-CONTROL-X
   Clears all numeric variables to 0 and all string variables to no
definition.  A brief flash at the top left of the screen indicates that the
command was executed.  //gs users can press OPEN-APPLE-CLEAR.
___________________________________________________________________________

Macros SOLID-APPLE-CONTROL-@ and SOLID-APPLE-^ are also reserved. They don't do
anything, at least not that you'd care about. You are allowed to use the
BOTH-APPLE equivalents of these two macros, however.

Special UltraMacros Tokens
--------------------------
The following tokens are for use within macro definitions only. None of them are
keyboard commands, and they can not be recorded using the OPEN-APPLE-X command.
They are used as is (i.e. they require no parameters).


<input>
-------
Allows you to enter text or OPEN-APPLE commands until RETURN is pressed (the
RETURN is not passed on to AppleWorks). To exit this command without pressing
RETURN, enter CONTROL-@. The macro will be aborted.


<id>
----
Return the unique id number of the current TimeOut application. If TimeOut is
not active, a zero will be returned. This token can't be used by itself; it must
be part of a variable definition or other numeric expression.

a:<all : A = id# : $1 = "This TimeOut application is #" + str$ A : msg $1>!
               Determine the TimeOut application number.

a<ato: a = id#:if a=7 then msg 'FileMaster' stop else if a = 8 then msg 'Macro
Compiler' stop>! Act differently for each.


<ifkey>
-------
Checks to see if a specific key has been pressed (exact matches only) and if so
continues. This is not part of the if-then-else logic.

a:<all :sa-b rpt>!
b:<a;; " ifkey rtn then print "Return was pressed:>!
or
b:<all : ifkey>A<then print "A was pressed">!

<key>
-----
Pauses until a key is pressed. The keypress is NOT passed along to AppleWorks.
When used by itself, key is simply a pause function.

In an equation, key returns the value of the key pressed. For example:

a:<all : A = key : if a < 128 then print A>!

If the user presses RETURN, A will be 13, and if the user holds down OPEN-APPLE
while pressing the key, 128 will be added to the key value. This example will
only print the keystroke if OPEN-APPLE is not pressed.

<begin>
-------
This does nothing unless used with <rpt>. It marks the restarting point for
repeating part of a macro instead of repeating the entire macro.

<rpt>
-----
Repeats part or all of the current macro by searching backwards from the <rpt>
token until a <begin> is found, or until the beginning of the macro is reached.

No commands after <rpt> will ever be executed (unless they're part of an
IF-THEN-ELSE statement). A conditional command must be used to exit the macro or
it will run continuously. For example:

g:<all : bell : rpt>! could drive you crazy; press Escape to exit.

h<all : print "This part executes once" : begin : bell : rpt>! Prints a message
and then beeps like crazy.

NOTE: Due to a rather obscure unfixable problem, you are not allowed to use some
literal numbers between a begin/rpt sequence. Well, you can use them, but the
macro won't work right. The numbers are 17, and 37121 through 37375 inclusive.
If you must use these numbers, use a variable to represent them inside of any
begin/rpt sequences. (In fact, why not *always* use a variable so there is no
chance of forgetting these rather unremarkable numbers, and getting bitten?)


<stop>
------
Stops all macro activity immediately. Use it to stop a nested macro from
returning to the calling macro, or to get out or a <rpt> situation. For example,
go back to the <findpo> sample.

Special UltraMacros Tokens with Parameters
-------------------------------------------
The next group of tokens require additional parameters. Most parameters involve
variables, so a description of UltraMacros' variables is next. The token
definitions are continued following the variable section.

Defining Numeric Variables
--------------------------
Numeric variables may be defined many different ways. You must be careful that
you don't accidentally redefine a variable if another macro expects to use that
variable later.

We suggest leaving variables U, V, W, X, Y, and Z as "throw away" variables.
Assume that they can be redefined indiscriminately by any and all macros. We
also suggest reserving variable Q for recording the number of a file you leave
via the OPEN-APPLE-Q (get the connection?) and that you will want to return to
later.

Start up AppleWorks and insert the UltraMacros disk. Add the file Macros Ultra
to the Desktop and examine the variable usage in it. See macros SOLID-APPLE-1
and SOLID-APPLE-2 for examples of using variable Q.

Here is a chart showing the various ways to define numeric variables and use
them in conditional macros.


condition   var     operator     operand
-----------------------------------------
                                   X         variable
if          A         >            7         decimal number
(define)    through      =            $10       hexadecimal number
ifnot       Z         <            key       keyboard input
                                   len $1    length of a string
                                   val $2    value of a string
                                   peek      value at an address
                                   id#       TimeOut application #

Remember those crazy mix and match animal cards when you were a kid? This is the
same idea, except that a variable can only be defined using the "equals"
operator. Otherwise you can pick any item out of each category and use them
together in a macro.

Any number of operands can be chained together using the four basic math
operators (+ - / *). No parentheses are allowed. The equations are strictly
evaluated left to right with no other precedence.

Defining String Variables
-------------------------
String variables may be defined in many different ways. Literal strings may be
surrounded by single or double quotation marks:

a:<all : $8 = "This is a literal string"">!
a:<all : $9 = 'This example has "quotation marks" in it'>!

Strings may be defined as the current date or time in these four formats:

a:<all $0 = date: $1 = date2: $2 = time: $3 = time24>!

Strings may be defined as the current Spreadsheet cell or Data Base category:
(Manual update a page or so previous said that <cell> would read the current
Word Processor line. I think this implies that it would work here also.)

a:<all : $8 = cell>!

A portion of the screen may be used to define a string (see the description of
the <screen> a few pages hence. <getstr> must be followed by a space. You can't
use A:<all : $3 = getstr,15>! (When used in the Data Base, always follow
<getstr> with a <rtn> i.e. <all : $3 = getstr 15 : rtn>. See the file "Linking
Samples".)



a:<all: $3 = getstr 15>!

See the description of <getstr> three pages hence for more information.

Finally, a string may be defined exactly like another string. In this example,
$7 is made identical to $2:

a:<all $7 = $2>!

Here is a chart showing the various ways to define string variables and use them
in conditional macros:

condition   str     operator     operand
-----------------------------------------
                                   "text"         A literal string
                                   $2             Another string variable
if          $0         >           date,date2
(define)    through       =           time,time24
ifnot       $9         <           getstr         Keyboard input
                                   cell           db category, ss cell, or
                                                  wp line
                                   screen         80 col text screen
                                   chr$           ASCII value of a variable
                                   str            String equivalent of a var
                                   left           Left portion of a string
                                   right          Right portion of a string

Any number of operands can be chained together using concatenation (+). No
parentheses are allowed. The equations are strictly evaluated left to right with
no other precedence. Any characters beyond 80 are ignored.

Parameters
----------
Here are some of the possible parameters for UltraMacros tokens:

MACRO
A macro name such as SA-B or BA-CTRL-D

NUM            (number)
A literal decimal number from 0 to 65535
A literal hexadecimal number from $0 to $FFFF
A variable name from A to Z (the value of the variable is used)

NUM VAR
A variable name from A to Z (the value of the variable is used)

NUM2
A NUM    (see above)
A <key>  token
A <peek> token
A <len>  token
A <val>  token
A <id#>  token

NUM EXP        (Numeric Expression)
A NUM (see above)

A NUM (see above) if the compiler gives an error, NUM2 is unavailable for This
particular command definition

A NUM or NUM2 equation; NUM's must be connected by +, -, /, or *; the equation
is evaluated from left to right. No other precedence is used.

The range of values is 0 to 65535 and the numbers "wrap around" if the range is
exceeded. For example. 0 - 1 = 65535 and 65534 + 3 = 1. Because only integer
numbers are allowed, division will only return the quotient.

STRING
A literal string surrounded by quotes

STRING VAR
a string name from $0 to $9
(The way to remember all this is to keep firmly in mind that NUM variables are
contained in alphabetic variables named A through Z and strings are contained in
numeric variables named $0 through $9. Makes sense to me, how about you?)

STRING EXP               (string expression)
a STRING (see above)
a <chr$> token
a <str$> token
a <date> token
a <date2> token
a <time> token
a <time24> token
a <cell> token
a <screen> token
a <getstr> token
a STRING expression; STRING EXP's must be connected by "+" only; the equation is
evaluated from left to right until the maximum length of 80 characters is
reached.

___________________________________________________________________________


<chr$ NUM>
----------
Prints the ASCII value of a variable. See the Key Chart for a complete list. For
example, the following macro will print the number 1:

a:<all : X = 49 : print chr$ X>!

As you can see on the chart, 49 is the code for an upper case 1. If X was equal
to 177 (49 + 128), an OPEN-APPLE-1 command would be executed.

This command is handy for sending special codes to your printer along with the
<pr#> token.
___________________________________________________________________________


<getstr NUM>
------------
presents a ">" on the bottom line of the screen, allowing up to 60 characters to
be entered. (This is similar to OPEN-APPLE-0.)

a:<all : $1 = getstr 8 : print $1>! read in 8 characters and print them
___________________________________________________________________________


<asc STRING>
A new token has been added to UltraMacros. <asc> is used to convert a string
character to its ASCII equivalent as shown on the Key Chart. Only the first
character of a string is used. This command complements the <chr$> token.

x:<all $0 = "Test" : print asc $0>!          prints "84"
x:<all $0 = "z" : x = asc $0 + 2: print x>!  prints "124"

Add <asc> to the token list on page 81, and see the sample <asc> macros in
Macros Ultra.

<goto MACRO>
------------
Sends control to the specified macro name, If goto is not used, the second macro
will return to the original macro and continue there. It will behave like a
gosub. Goto just jumps to the named macro and keeps on going. No nesting occurs
when goto is used.

a:<all : sa-b : print "The end">!
b:<all : if A = 4 then goto sa-c else rtn>!
c:<all : print $4>!

Pressing SOLID-APPLE-C will start this macro example. Control passes to
SOLID-APPLE-B. If A is not equal to 4, the macro jumps to SOLID-APPLE-C where
string $4 is printed. Because we used a goto, control does not return to
SOLID-APPLE-B, but rather goes back to SOLID-APPLE-A and "The end" is printed.
___________________________________________________________________________


<highlight NUM EXP, NUM EXP, NUM EXP, NUM EXP>
-----------------------------------------------
Allows you to invert any portion of the AppleWorks screen. This sample will
invert the entire screen:

h:<all : highlight 1,1,80,24>!

The first parameter is the left column (1-80)
The second parameter is the top row (1-24)
The third parameter is the right column (1-80)
The fourth parameter is the bottom row (1-24)

If the first parameter is 0, the specified rows will have all highlighting
cancelled (the text will be changed to normal). The right column value is
ignored if the left column is zero.
___________________________________________________________________________


<left STRING VAR,NUM>
---------------------
Extracts the leftmost numbers of characters specified from a string.

a:<all : "Beagle Bros" : $2 = left $1,6 : print $2>! Prints Beagle (Only the
first six characters.)
___________________________________________________________________________


<len STRING VAR>
----------------
Returns the length of the specified string as part of a variable equation. For
example:

a:<all : A = len $0 : B= len $1 : if A > B then print "$0 is longer">!
___________________________________________________________________________


<msg STRING>
------------
This command prints a message on the screen immediately below the current data
window (i.e. on the dash "-----" or underline "_____" dividing line). The
command syntax is identical to <print?>. Messages are displayed in inverse text
unless the message string is surrounded by double quotation marks:

m:<all : msg "Normal Text" : key {display normal text; wait for key press}
msg 'Inverse message'      : key {Display inverse text; wait for key press}
$9 = date + ""+ time: msg $9:key {Display date & time; wait for key press}
msg "">! do sample messages, then erase all messages.

Whenever a message is displayed, the remainder of the line is filled with the
second to last character that was already on that line (i.e. the character above
the "p" in A-? for help). This automatically erases the vestiges of previous
longer messages. As the example shows, a null message erases the entire line.

The msg token must be followed by a colon. The second msg will result in a
compiler error, but the first msg is legal:

a:<ato : a = id# : if a = 7 then msg ' FileMaster ' : stop else if a = 8 then
msg ' Macro Compiler ' stop>!  act differently for each application
___________________________________________________________________________


<onerr OPTION>
--------------
Allows you some control over what happens if an error occurs. An error is
defined as a keystroke that causes AppleWorks or a TimeOut application to ring
the error bell. Normally a macro continues on without regard to the error (the
error bell is silenced as well). There are three onerr options:

1.<all : onerr stop>! Stop the current macro after an error. If the macro was
called from another macro, control returns to the calling macro. This does not
shut down all macros; only the current macro is ended.

2:<all : onerr off>! Revert to normal; ignore all errors. Resets the onerr
status to normal, so macros ignore the errors, for better or worse.

3:<all : onerr goto sa-h>! On any error, execute the named macro and the return
to calling macro where the error occurred.

The onerr status is always reset to normal when a sequence of macros is done
executing.
___________________________________________________________________________


<posn VAR,VAR>
--------------
Assigns the current cursor position to the two variables following the token.
The AppleWorks application affects the command like this:

                 First Variable      Second Variable
_____________________________________________________
Word Processor      column              line
Data Base           category            record
Spreadsheet         column              row

If the cursor is not in one of these three application, both variables will be
set to zero. <posn> is compatible with TimeOut applications that use the
AppleWorks application. For example, TimeOut Graph works in the Spreadsheet, so
<posn> can be used with it.

Start up AppleWorks and add the file Macros Ultra from the UltraMacros disk to
the Desktop. Examine the cursor-positioning macros for examples of <posn> usage.
___________________________________________________________________________


<pr# NUM EXP>
-------------
determines where the <print> command sends its information.

<pr# 0> sends all <print> characters to AppleWorks. This is the normal state of
affairs.

<pr# 1> sends the characters to the first printer in your AppleWorks printer
list. Because AppleWorks' limit is 3 printers, the <pr#> limit is also 3. You
must use <pr# 0> to reset the <print> command when you're done.

Start AppleWorks and add the file Macros Special from the UltraMacros disk to
the Desktop. Examine it for sample <pr#> usage.

The <pr#> command definitely works with the modem and printer ports on the //gs.
It may not work with all other interface cards. Experiment, but don't be
surprised if you have problems on other machines. I have no idea why.
___________________________________________________________________________


<print>
-------
Print has the most variations of any single UltraMacros command. The compiler
will be happy to point out any errors you might make, but studying this section
will make you much less error-prone.

Printing Text
-------------
Like Applesoft, <print> allows a literal text string to be printed. You may use
either double or single quotes around the text. The limit is 70 characters of
text at a time.

a:<all :print "Literal text <rtn>">!  Prints "Literal text <rtn>"

The <rtn> is NOT converted to an actual RETURN.

a:<all : print '"double" quotes inside "single" quotes'>! will print as "double"
quotes inside "single" quotes

Printing Numeric Variables
--------------------------
Print can be used to display the value of any numeric variable. For example, if
variable Q holds the desktop number of a specific file, this macro sequence
would return you to that file:

2:<all : oa-q : print Q : rtn>!

A text string may precede the variable like this:

a:<all : print :Variable A is now " A>!

When printing numeric variables, a "$" immediately after the print statement
will cause the variable's hexadecimal value to be displayed in either two or
four characters.

a:<all : A = 8 : print$ "Hex A = $" A>! will print "Hex A = $08"
a:<all : X = 61453 : print$ X>!         will print "F00D"

Numeric variables can also be printed as characters rather than numbers, The
<chr$> token converts the numeric value to the equivalent key command. See the
Key Chart for a complete list. Here's a sample.

a:<all : X = 185 : Y = 41 : print chr$ x : print chr$ y>!

The Key Chart shows us that 185 is an OPEN-APPLE-9 and that $41 is an upper case
"A". This sample will hump to the end of the file and then print an "A".

Printing Strings
----------------
The ten string variables may be printed by themselves only. No other options may
be used when printing strings. These strings may contain text or command
keystrokes. To define a string with commands instead of text, just define macro
0 (zero), the same as $0, and then use a macro like this:

a:<all : $2 = $0 : print $2>!  execute macro 0 (zero)

Because macro 0 (zero) and $0 are the same thing,

a:<all : print $0>! is exactly the same as
a:<all : sa-0>!

NOTE:
ALL PRINT STATEMENTS MUST BE FOLLOWED BY A COLON ":" or ">". Other tokens can be
followed by spaces and then another token, but <print> is an exception.
___________________________________________________________________________


<rem STRING>
This command allows you to embed a remark in the middle of a macro. The remark
does not get used in the macro. The command syntax is identical to <print>. Just
surround the remark with single or double quotation marks.

The difference between using <rem> as opposed to just adding a comment after the
"!" mark or by using the curly braces {...} is that <rem>'s are preserved when
the macro is assembled, so they are still present when you use the Macro
Compiler to list the current macros into a Word Processor file. We prefer to use
the curly braces to make sure we keep our Word Processor source files handy, but
it's your option.

Here's a macro from the Macros Ultra file that deletes from the cursor to the
end of the file. Actually, it moves the data to the clipboard so that it can be
undone. It's a simple example, but it does illustrate how to use <rem>'s:

Z:<all : oa-M>T<rem "Move to the clipboard" : oa-9 : rtn : rem "jump to the end
and do it": left>!      zap to the end of the file.

Comments and <rem> make it easier to follow the logic of a macro, especially if
you want to change a macro you wrote last month or last year.
___________________________________________________________________________

<right STRING VAR,NUM>
Extracts the rightmost number of characters specified from a string.

a:<all : $1 = "Beagle Bros" : $2 = right $1,4 : print $2>! prints Bros
___________________________________________________________________________


<screen NUM EXP,NUM EXP,NUM EXP>
Read any part of the AppleWorks screen into a string variable. It is used like
this:

s:<all : $1 = screen 7,1,15>!  Read current file name from top line.

The first parameter is the left column (1,80)
The second parameter is the line (1-24)
The third parameter is the length (1-80)

<screen> treats all characters as normal text, regardless of how they appear on
the screen; it can't be used to tell if something was highlighted. (That is good
news. If there is the slightest chance the cursor is within the range of the
read performed by <screen> you should first switch to the overstrike cursor
(oa-E> or you will have an underscore as part of the string variable. See
sa-SPACE in Ultra Macros for method of properly restoring the insert or
overstrike cursor.)

___________________________________________________________________________

<str$ VAR NAME>
Converts a numeric variable to a decimal character string. It must be used as
part of an equation. Here are some examples:

x:<all : A = 4: $3 = " A = " + str$ A + "": print $3>! prints "A = 4"
y:<all : B = $FF : $1 = str$ B : print $1>! prints "255" because 255 is the
decimal equivalent of the decimal $FF used to define B.

This command is handy for including variables in a message:

a:<ato : I = if# : $1 = "TimeOut ID#" + str$ I : msg $1>! show id#
___________________________________________________________________________


<val STRING VAR>
<val> is the opposite of <str$>. It converts a string variable to a numeric
value and must also be used as part of an equation. If the specified string
starts with a non-numeric character, the value will always be zero. If the first
character is a number, it will (and all other numbers following immediately
after it) will be converted to a numeric value. Here are some examples:

a:<all : $3 = "test4" A = val $3>    A will = 0
a:<all : $2 = "48612" : X = val $2>  X will = 48612
a:<all : $8 = "280Zx" ; V = val $8>  V = 280
a:<all : $0 = "14.88" : B = val $0>  B = 14
___________________________________________________________________________


<wait NUM EXP>
Delays a macro for a set amount of time, or until a key is pressed. The actual
delay will vary depending on your computer. Experiment to find the approximate
delay needed for a second or a minute on your computer. Here's a macro you can
use to calculate delay values:

D:<all : msg "Enter a delay value: : $0 = getstr,5 : D = val $0 : bell : wait D
: bell : rpt>!  Test wait

One suggested use for the <wait> command is to allow a user to browse through a
large document without having to touch the keyboard:

b:<awp : D = 400 : wait D : down : rpt>!  Adjust D as desired.
___________________________________________________________________________


<wake MACRO at NUM EXP:NUM EXP>
Puts a macro to "sleep" and wakes it at a designated 24-hour time. After a
<wake> command has been issued, you can work normally, using macros and any
UltraMacros commands as always. When the clock's time matches the sleeping
macro's, it springs to life. Use it to set alarms, automatically save a file
every few minutes, or everything down at 5:00!

The following example will start macro "A" at noon. then when macro "A" wakes
up, it will set macro "C" to wake up at 5:00PM

a:<all : wake sa-b at 12:00>!
b:<all : bell : bell : bell : msg "It's lunch time!" : wake sa-c at 17:00>!
c:<all : bell : bell : bell : msg ' Quitting time'>!!

Only one macro can be "sleeping" at a time, but as shown in the previous
example, each macro that "wakes up" can put another macro to sleep. The time
must be given in 24-hour format (0:00 to 23:59)); variables may be used:

x:<all : M = 50 : h = 7 : goto sa-s>!
s:<all : oa-s : M = M + 10: if M = 60 then M = 0 : H = H + 1 : elseoff wake sa-s
at H:M>!

When SOLID-APPLE-X is pressed, the hour and minute variables are set. The
current file is saved and macro S is set to wake up at 8:00AM. It will then save
the current file every 10 minutes until the <nosleep> command is used.

Note:
Of course, this command won't be too useful if you don't have a clock in your
Apple.
___________________________________________________________________________


If-Then-Else Logic
------------------
One of UltraMacros' best features is its true conditional capability utilizing
if-then-else logic. Other macro programs may allow a conditional "if" or two
based on keyboard input, but UltraMacros allows a full range of conditional
commands using the numeric and string variables. Five tokens are involved with
conditional logic: if, ifnot, then, else, elseoff.
___________________________________________________________________________


<if>
The key to all conditional macros, <if> is always followed by a numeric string
variable:

a:<all : if A

which is followed by an operator (greater than >, less than <. or equals +)

a:<all : if A =

which is followed by the expression to be evaluated

a:<all : if A = 5

If the statement is true, the macro continues normally. If the statement is not
true, the macro ends (unless an <else> is present later in the macro).

a:<all : if A = 5 goto sa-5>!  If A is not 5 the macro stops here
___________________________________________________________________________


<ifnot>
Same as <if>, except that the statement must be false for the macro to continue
normally.

a:<all : ifnot A = 5 goto sa-5>!  If A *is* 5, then the macro stops here.

all numeric conditionals must start with any valid numeric expression such as:

a:<all : if A = C + 4 then print A : else stop>!

All string conditionals must start with one of these six formats:

if $0 =   or   ifnot $3 =
if $1 >   or   ifnot $4 >
if $2 <   or   ifnot $5 <

The equation is completed with a string expression, which could be another
string variable name, a literal text string, or one of the legal string
definition tokens (date, date2, time, time24, screen):

a:<all : if $0 = "literal: then print $0>!
t:<all : ifnot $6 > time then goto sa-t>!
2:<all : if $2 < screen 1,7,15 then stop>!
8:<all : ifnot $8 = $9 then print "They're not the same.">!
___________________________________________________________________________


<then>
Does absolutely nothing but take up one byte of space. It's used to make macro
if-then logic more readable:

a:<all : if A > 4 then C = 3>! this looks better than:

a:<all : if A > 4 C = 3>!
___________________________________________________________________________


<else>
This part of if-then-else logic reverses the true-false condition of the logic.
If the statement is true, then execute the first part, else execute the second
part. There is no limit to the number of <else's> in one macro.

Whenever an <else> is encountered during a macro, the macro skips ahead to the
next <else> or to the end of the macro, whichever is found first. It can be used
during debugging to keep part of a macro from executing so  a different part can
be properly tested:

a:<all : print " A " : else print "one" : else print "two">! test part 2

This macro will always print "A two". Later the macro could become:

a:<all : print "A " : print "one" : else print "two">! test part one only

Now the macro will always print "A one". When finished, the macro could be:

a:<all : print "A " : if A = 1 then print "one" : else print "two">!

There is no direct connection between if and else, so they can be used
independently, although they make a good team. Here's a sample:

a:<all : if A = 5 then print "five" : else print "Not five">!

This does just what you'd expect. If variable A is equal to 5, the word "five"
is printed. If variable A is not equal to 5, the words "not five" are printed.
___________________________________________________________________________


<elseoff>
---------
Does nothing unless used with else (See above). Its purpose is to cancel the
conditional status of a macro and cause any commands following the <elseoff> to
be executed regardless of any preceding <if> condition.

For example, if a conditional macro is supposed to print a phrase at the end,
regardless of what other text is printed, you'd do this:

a:<all : if A = 5 then print "A is five" : else print " A is not five" : elseoff
print " at this time.">!

If a is five it would print "A is five at this time," and if a is not five, it
would print "A is not five at this time."

If the <elseoff> is removed, the macro will print either "A is five" or "A is
not five at this time."
___________________________________________________________________________


For Experienced 6502 Programmers Only
-------------------------------------
The following three UltraMacros tokens are very specialized and shouldn't be
used unless you understand exactly what you want them to do. The were included
because we thought there might still be a few hackers out there who like to deal
directly with their Apples. Besides that, we can always use them to write pretty
powerful macros ourselves.


See the file Macros Special on the UltraMacros disk for some examples.

CORRECTION TO THE ABOVE:
Macros Special is not on the UltraMacros disk. It will be on the first TimeOut
disk containing sample macros.
___________________________________________________________________________


<call>
The call token is used to run machine language subroutines. It simply does a JSR
to the address specified. It's up to you to make sure that the address is valid
and that the routine will return to the macro via an RTS with all bank switches
set properly.

A good place to poke in machine language subroutines is the AppleWorks temporary
work buffer from $800 to $9FF.

CAUTION:
The buffer is destroyed by AppleWorks disk access and by a few UltraMacros
commands. Be careful!

When a macro is operating, the alternate zero page one is active, as well as the
second bank of $D000 memory. Page  of the 80 column display is active. If you
change any of these, they MUST be restored before your routine returns control
to UltraMacros or AppleWorks will surely die.

The call command is a bonus feature and must be used carefully by experts only.
Know what you are doing before you do this!
___________________________________________________________________________


<poke>
Poke is a handy, albeit dangerous, command. Use it to build machine language
subroutines for use with <call>.

It can also be used to directly change some flags within AppleWorks. For
example, the <insert> token forces the insert cursor on. To force the overstrike
cursor on, you can use this:

O:<all : poke $10F1,1>! Force overstrike cursor active.

The insert cursor continues to blink until another key pressed, and then you see
the cursor is changed. To make it instantly change, add an invalid key like
this:

O:<all : poke $10F1,1 :ctrl-x>! Force overstrike active and make it immediately
obvious.

We aren't authorized to provide a list of AppleWorks addresses. You'll have to
explore on your own. Some information is available from bulletin board systems.
Last time we heard, AppleWorks author Bob Lissnor had an AppleWorks board
somewhere in Nevada with a lot of handy information. Sorry we can't provide a
phone number. (WE CAN! Try (702) 831-1722. Be Nice if you call. How many
developers provide a modem line for you to call in and learn and/or voice your
concerns about their program?)
___________________________________________________________________________


<peek>
Peek returns the value found at the specified address. This example from the
Macros Ultra file uses <peek> to determine the current file number:

1:<all : q = peek $C54 : oa-q esc>! Leave "1" file; go to main menu.
2:<all : oa-q print q : rtn>!       Return "2" the file we left.

___________________________________________________________________________
___________________________________________________________________________

Macro Compiler
--------------
This application allows you to compile new macros. It scans a Word Processor
document containing macro definitions and converts them into a form usable by
TimeOut UltraMacros. It can also display the current macro set by listing the
active macro definitions into a Word Processor file.

If you've been following the manual sequentially, you've already used the
Compiler to include your name in the default macro set. In any case, add a Word
Processor macros file to the Desktop and press OPEN-APPLE-ESCAPE. Select "Macro
Compiler". You will see two options.

Compile a New Set of macros
---------------------------

1. Press RETURN to compile a new set of macro definitions.

2. A "Pause each line?" prompt appears. If you press Y for yes, you will
   "single-step" through the compiling process and will be asked to press a key
   to continue after each line is processed. If you choose N for No, the
   compiler will race along and won't stop until an error occurs or until
   compiling is completed.

3. A "Compile from:" prompt appears. You may choose to compile from the very
   beginning of the file or from whatever line the cursor was on when you
   pressed OPEN-APPLE-ESCAPE to call up TimeOut. If you press "B" to compile
   from the beginning, the compiler will scan the file until it finds the word
   "START" on a line by itself. It then will start compiling with the next line.

4. Each Word Processor line will flash on the screen as it is scanned for tokens
   and text data. The current macro name will be displayed, and a running count
   of the total bytes used will also be shown.

5. If the file is compiled without error, a message will indicate the success
   and you will be prompted to press a key to return to the file.

6. If an error occurs, the compiler will attempt to give you as much information
   as possible. When you press a key and return to the Word Processor the cursor
   will be on or near the error.
___________________________________________________________________________


Macro Compiler Errors
---------------------
There are several errors which stop the compiler. Macros up to the error are
usable, but no macros following the error line are compiled. When you press a
key after reading the error message, you will be returned to the file with the
cursor on or near the error.

No errors
---------
The compiler recognized the entire macro file as a valid macro set. That doesn't
mean that the macros don't contain potential execution errors. It does mean that
all command tokens were used properly.

No Start Found
--------------
The compiler couldn't find the word "START" in the file. The word "START" must
be on a line by itself, immediately preceded and followed by carriage returns
(no spaces). This message can't occur if you select "Compile from cursor".

Reserved Macro Name
-------------------
An attempt was made to define a reserved macro (see page 31). Remember that the
named keys such as RETURN and TAB have control key equivalents.

Incorrect application name
--------------------------
A valid local/global designation couldn't be found. Valid tokens are <all>,
<awp>, <adb>, <asp>, and <ato>. Every macro must start with the macro name,
followed by a colon ":" followed by the application name. (They are not kidding
about the colon. If you don't include it, your macro will probably be ignored
and not compiled with NO error messages. See how long THAT takes you to find the
first time!)

Table full
----------
The entire macro table was used up. This refers to the actual macro bytes
generated and is not referring to the size of the Word Processor file. The only
solution is to create multiple macro files from the one large one or to remove
enough macro definitions so the compiled macros will fit into the table space.
Since the default macros that come with the disk only use half of the table you
can probably rest easy tonight.

Syntax error
------------
The catch-all error message. Anything the compiler doesn't recognize is a syntax
error. This is usually a misspelled token name.

Not enough parameters
---------------------
The UltraMacros' token being compiled requires one or more additional
parameters. See "Special UltraMacros Tokens with parameters" for a description
of all tokens which use additional parameters.

Too many parameters
-------------------
The UltraMacros' token being compiled requires at least one fewer parameter. See
"Special UltraMacros Tokens with parameters" for a description of all tokens
which use additional parameters.

Logic error
-----------
The macro definition was illogical. You might not think so, but guess who's the
boss? Remember that UltraMacros us very strict and limited in its string and
numeric variable usage.

String too long
---------------
A sequence of text characters used in a string definition exceeds the character
limit.

END found in line
-----------------
The compiler was stopped by an END command, not by an error. All macros up to
the END line are usable.

Stopped by an ESCape
--------------------
You pressed the ESCAPE key during compiling to halt the process. All macros
already compiled are usable.

Display current macro set
-------------------------
This option will list all of the current macros into a Word Processor file. The
listing can then be modified and recompiled as desired. The primary purpose of
this option is to display recorded macros.

1. Add an AppleWorks Word Processor file to the Desktop. It can be an existing
   file, or a new one.

2. Press OPEN-APPLE-ESCAPE to call up the TimeOut menu. Select "macro compiler"
   from the menu.

3. Select "Display current macro set".

4. The current set of macros will be added to the file in token format. This
   file can then be changed and recompiled as desired.


Macro Options
-------------
The Macro Options TimeOut application contains UltraMacros' user-definable
options. From within AppleWorks, press OPEN-APPLE-ESCAPE and select "Macro
Options" to get this menu:

     1. Launch a new Task

     2. Create a Task File

     3. Save macro table as default set

     4. Deactivate macros

     5. Reactivate single-stepping

     6. Version

     7. Other Activities

The first two options on this menu deal with Task files. Look beyond explanation
of 1-7 of the options menu followed by 1-7 of the Other Activities menu.
___________________________________________________________________________

1. Launch a new Task
---------------------
When selected, this option reads the AppleWorks disk and looks for Task files.
The names are shown on the screen. Press ESCAPE to return to the "Macro Options"
menu, or select the Task you want to launch.

2. Create a Task file
----------------------
This option takes whatever macros are currently active in AppleWorks and saves
them as a Task file on your AppleWorks STARTUP disk.

First you are prompted to enter a name for the new Task file. Enter a legal
ProDOS name (you know, 1 to 15 characters beginning with a letter and containing
only letters, periods, and numbers).

If the AppleWorks startup disk is not found, you will be prompted to insert it.
At this time you can press ESCAPE to cancel, or you can insert the STARTUP disk
and press Return.

When the Macros have been updated, put the previous disk back in the drive.

3. Save macro table as default set
----------------------------------
This option takes whatever macros are currently active in AppleWorks and saves
them into the file "ULTRA.SYSTEM" on your AppleWorks STARTUP disk. These macros
will be then be available whenever you start AppleWorks. No compiling will be
necessary.

Before the macros are saved you are asked if you want to activate the auto
startup macro. If you choose "Yes", the first macro in the macro set will be
automatically run each time AppleWorks is started.

If the "ULTRA.SYSTEM" file is not found, you will be prompted to insert your
AppleWorks STARTUP disk. At this time you can press ESCAPE to cancel, or you can
insert the STARTUP disk and press RETURN. When the macros have been updated, put
the previous disk back in the drive.

4. Deactivate macros
--------------------
This option completely disconnects UltraMacros from AppleWorks. Choose this
option if you wish to print using the Applied Engineering print buffer. After
deactivating, the menu will appear as "4. Reactivate macros".

5. Reactivate single-stepping
-----------------------------
This option turns on "single-step" mode, which is useful for debugging complex
macros. The menu will change to "5. Deactivate single-stepping".

When a macro sends a character to AppleWorks, this option forces a pause before
each character actually gets to AppleWorks; the character is sent only after you
press a key. If you press ESCAPE the macro will stop, but single-step mode will
remain active.

Select "Deactivate single-stepping" to return to normal speed.

6. Version
----------
This option shows the current version of the UltraMacros package. You will need
to know this number if you ever contact Beagle Bros about UltraMacros.

7. Other Activities
--------------------
Choose this to display the following menu:

     1. Set cursor blink

     2. Set mouse button response

     3. Set mouse response

     4. Deactivate the mouse

     5. Reactivate key-lock

     6. Reactivate screen preserver

     7. Set screen preserver delay

___________________________________________________________________________

Other Activities
----------------
The options on this menu allow you to make changes to how UltraMacros functions.
When you exit this menu by pressing ESCAPE, you will be asked if you want to
save any changes to you AppleWorks STARTUP disk. If your answer is "yes", the
current settings will be in effect every time you start AppleWorks.

1. Set cursor blink
-------------------
Choose this option to adjust the speed at which AppleWorks' cursor flashes. The
current setting is displayed and you're prompted to enter a new value. Enter
numbers from 1-255 where 1 is the fastest and 255 is the slowest.

2. Set mouse button response
-----------------------------
choose this option to adjust how long the mouse button delays after it is used
to select menu options. If you find yourself jumping several menu steps at time
when you press the mouse button, you should increase the delay.

The current setting is displayed and you're prompted to enter a new value. Enter
a number from 1-255 where 1 is the shortest delay available and 255 is the
longest.
___________________________________________________________________________

3. Set mouse response
---------------------
Choose this option to adjust how far the mouse has to travel horizontally or
vertically before the cursor moves.

The current horizontal setting is displayed and you're prompted to enter a new
value. Enter a number from 1-255 where 1 is the most responsive and 255 is the
least responsive. Press ESCAPE when desired number is entered.

The current vertical setting is displayed and the same procedure is used to
change it.

Apple //gs users can also use the Control Panel Options to change the high speed
mouse option to "yes" or "no".

4. Deactivate the mouse
-----------------------
This option makes UltraMacros ignore your mouse card. It is useful for //c users
who don't have a mouse. They do have mouse cards built in, and the cards
sometimes give false readings as though a mouse was being moved. If you
experience sporadic random cursor moves on any kind of Apple ][, give this
option a try.

Select the option; the menu will now be redisplayed as "4. Reactivate the
mouse". Options 1 and 2 will now give "Mouse not found" if selected.

5. Reactivate Key-Lock
----------------------
Key-Lock is a special feature designed primarily for physically disabled
AppleWorks users who have a difficult time pressing the OPEN-APPLE or
SOLID-APPLE keys in combination with other keys. This option makes the
OPEN-APPLE and SOLID-APPLE keys "lock on" until another key is pressed.

Here's how it works. First, select the option. Because Key-Lock is not
activated, the menu option will now be redisplayed as "5. Deactivate Key-Lock".

Press ESC a few times to get back to AppleWorks. Get in a word processor
document and press OPEN-APPLE. An inverse "O" appears in the bottom right corner
of the screen. The cursor stops blinking and UltraMacros waits until you press
another key.

If you press OPEN-APPLE again, the command will be cancelled and the normal
cursor will appear. If you press another key, such 1, the OPEN-APPLE version of
the key will be entered in AppleWorks. In this case, the cursor will jump to the
top of the document. Now press OPEN-APPLE again followed by 9 and you'll jump to
the end.

To execute a macro, press the SOLID-APPLE key. An inverse "S" will appear. As
before, you can press OPEN-APPLE to cancel, or another key to execute a command.
To start a "BA" macro. press the OPEN-APPLE key followed by the SOLID-APPLE key.
The inverse "O" will change to a "B" and the desired macro key can be pressed.

6. Reactivate screen preserver
------------------------------
The screen preserver will automatically blank your screen if there has been no
key press or mouse move for a specified amount of time. This avoids monitor
"burn-in" (i.e. scorching of the phosphors on the monitor screen).

Here's how to use it. First, select the option. Because the preserver is now
activated, the menu option will now be redisplayed as "6. Deactivate screen
preserver".

Now, sit and wait a few seconds. The screen will blank out, but don't despair.
Just press a key to restore it. The screen preserver is tied to the blinking
cursor; if an inverse bar menu such as OPEN-APPLE-C "Copy Text?" is active, the
screen will never be blanked. The screen preserver is also ignored while the
TimeOut OPEN-APPLE-ESCAPE menu is on the screen. It does work within TimeOut
applications, though.

7. Set screen preserver delay
-----------------------------
Choose this option to adjust how long the screen preserver waits before it
blanks the screen. The delay is based on the number of cursor blinks, so you
cursor blink directly affects it.

The current setting is displayed and you're prompted to enter a new value. Enter
a number from 1-255 where 1 is the shortest delay and 255 is the longest.
___________________________________________________________________________


Data Converter
--------------
The TimeOut Data Converter allows you to quickly and easily transfer data
between spreadsheet and data base files.

To transfer data from a spreadsheet to a Data Base file, use the OPEN-APPLE-C
command to copy some Spreadsheet rows to the clipboard. Press OPEN-APPLE-ESCAPE
and select "Data Converter" from the TimeOut menu. The data on the clipboard
will instantly be converted into Data Base data.

Create a new Data Base file or load one in from disk. Place the cursor where you
would like to insert the Spreadsheet data, press OPEN-APPLE-C and select "From
the Clipboard". Each Spreadsheet row will now be inserted into your Data Base
file. Each column from the Spreadsheet will become a Data Base category.

To transfer from a Data Base file to a Spreadsheet file, copy from the Data Base
file to the clipboard, call up the TimeOut menu, select "Data Converter", and
copy from the clipboard to the Spreadsheet file. Each category from the Data
Base will become a Spreadsheet column.

If you're using the AE expander, use UTILITIES to configure Data Converter.

___________________________________________________________________________

Allowing Control-@
-------------------
AppleWorks 2.0 contains a bug which prevents users from entering a CONTROL-@ in
a printer interface definition. Here's a fix:

1. Boot the UltraMacros disk and press "F" for "Fix AppleWorks Bug

2. The CONTROL-@ patch program is run. Follow instructions.

Note: Use OPEN-APPLE-CONTROL-@ to enter the CONTROL-@ code while recording a
macro. If you press CONTROL-@ the macro will stop. Likewise, a macro definition
must use OPEN-APPLE-CONTROL-@ or it will stop.
___________________________________________________________________________

Mouse Control
-------------
Once UltraMacros has been installed on your AppleWorks disk, you can use an
Apple mouse to speed scrolling and menu selections. Here's how:

Move the mouse to position the cursor just like using the arrow keys. Hold down
the OPEN-APPLE key to move the cursor farther and faster within a file.

Press the mouse button to do one of the following:

(a) Select an option from any AppleWorks or TimeOut menu (the same as pressing
    the RETURN key).
(b) Scroll quickly through an AppleWorks file (the direction, up or down, is the
    same as the last vertical mouse movement.

You can adjust mouse sensitivity or deactivate the mouse using the Macro Options
TimeOut application. See previous discussions for details.

Unless you specify otherwise, the mouse is always active (if you have one). If
you have a //e with a mouse interface card but no mouse is plugged in, you must
deactivate the mouse; otherwise you will probably be faced with an out of
control cursor that jumps wildly when you least suspect it. This can also happen
on a //c that doesn't have a mouse plugged in.

Mouse Tip:
The mouse is especially handy for creating Data Base single record layouts. Just
hold down the OPEN-APPLE key and use the mouse to drag categories into position.
___________________________________________________________________________

Linking Files
--------------
You can use the <store> and <recall> commands to link AppleWorks files together.
Linking allows you to do things like print an unlimited number of files with one
keypress, or have a custom set of macros loaded automatically with any
Spreadsheet file.

The <store> command saves the first 15 characters of macro 0 (zero), generally a
name, in an unused area or a Word Processor or Spreadsheet file. The <recall>
command puts the name back in macro 0 (zero).

Start up AppleWorks and insert the UltraMacros disk. Add the Word Processor file
"Linking Samples" to the Desktop and study it for some sample linking macros and
ideas.
___________________________________________________________________________

Startup Menus
--------------
UltraMacros allows you to create handy menus which allow you choose what you
want AppleWorks to do next. You can use Task files (see next section), or create
menus within AppleWorks files.

Start up AppleWorks and insert the UltraMacros disk. Add the word processor file
"Macros Startup" to the Desktop and study it for a sample menu macro set.
___________________________________________________________________________

Task Files
----------
Task files are precompiled sets of macros that have been saved on the AppleWorks
startup disk as system files. They are called "Task" files because they allow
you to quickly and easily execute a specific task.

New tasks can be launched in several ways:

1. From within AppleWorks by using the TimeOut Macro Options application

2. From outside AppleWorks by using a program selector such as Apple Desktop,
   MouseDesk, Alan Bird's program Selector, ProSel, ECP or Squirt.

3. From outside of AppleWorks by typing -TASK.NAME from Basic with the
AppleWorks STARTUP disk in the current drive.

To see a sample task file, start up AppleWorks and insert the UltraMacros disk.
Add the Word Processor file "Task Sample" to the desktop.

When a task is launched from outside of AppleWorks, it first loads ULTRA.SYSTEM,
which in turn loads AppleWorks. The first macro in the set of macros is then
executed. The first macro from "Task Sample" looks like this:

]:<all :rtn : rtn : sa-1>!  get to main menu and run second macro.

The macro enters the two RETURN keystrokes needed to get past the AppleWorks
copyright message and accept the current date. It then jumps to the next macro
in the set.

Note: See "Task Sample" for replacement first macros if you don't have a clock
or if you need to pause to remove the AppleWorks STARTUP disk and insert the
PROGRAM disk.

The second macro should actually begin the task. This is the macro that's
executed when the task is launched from within AppleWorks. The sample second
macro looks like this:

1:<all : oa-q esc rtn down down rtn rtn>Rename Me<rtn>!

It uses the standard <oa-q esc> sequence to jump to the AppleWorks Main Menu.
This is a good technique to make sure your macros work the same no matter where
you are when the SOLID-APPLE is pressed. The macro then executes the necessary
keystrokes to add a new Word Processor file to the Desktop called "Rename Me">

This example is simple, but it illustrates the potential of Task files. Here are
some possible Task file uses:

1. Add a specific group of files to the AppleWorks Desktop
2. Copy a 3.5" disk to a RAM disk using TimeOut FileMaster.
3. Load a Spreadsheet file and graph it TimeOut Graph.
4. Load a Word Processor file and print it with TimeOut SuperFonts.
5. Any complex and repetitive task, such as printing out a weekly report using
   Data base or Spreadsheet Data.

It's a good idea to create a "Default Macros" task file first and save it on
your AppleWorks STARTUP disk. Then when a task is completed, you can quickly get
back to your default st of macros. In fact, a Task File can even do that
automatically after it's completed its task.

NOTE: Programmers interested in licensing a special type of Task File for use on
disks they sell should read the file "Programmer tasks" on the UltraMacros disk.
___________________________________________________________________________

The special Case of Macro 0 (Zero)
----------------------------------
Macro 0 (zero) is a unique macro because it's used by many special UltraMacros
commands. Use macro 0 (zero) only for very temporary macros, because it can be
redefined quite easily before you know it. Here's a list of ways that macro 0
(zero) can be redefined:

  1. Press OPEN-APPLE-X to record up to 80 characters; the keystrokes are passed
     on to AppleWorks as they are entered.
  2. Press OPEN-APPLE-O to enter up to 60 characters; the keystrokes are not
     passed on to AppleWorks.
  3. Press OPEN-APPLE-^ to read the character under the cursor into macro 0
     (zero).
  4. Press OPEN-APPLE-& to read the current disk name into macro 0 (zero).
  5. Press OPEN-APPLE-* to read the current path into macro 0 (zero).
  6. Press OPEN-APPLE-- to read the current Data Base category or Spreadsheet
     cell into macro 0 (zero).
  7. Press OPEN-APPLE-> to recall the STORE'd name file into macro 0 (zero).
  8. It can be redefined from within a macro using <$0 = ...>

Once macro 0 (zero) has been defined, the keystrokes may be sent to AppleWorks
by pressing SOLID-APPLE-0. A handy example is copying a Data Base category and
pasting it into the Word Processor, into the Spreadsheet, or into another Data
Base category.

  1. Press OPEN-APPLE-- while in the Data Base. The current category is read
     into macro 0 (zero).
  2. Move to the new location in the Data Base or anywhere else.
  3. Press SOLID-APPLE-0 (zero) and the category is duplicated.

The contents of macro 0 (zero) are also used by the SOLID-APPLE-RETURN <find>
command to determine what it looks for. If you have a lot of files on a disk,
try this:

  1. Go to the "Add Files" menu.
  2. Press OPEN-APPLE-0. You will be prompted with a >.
  3. Enter the file name you wish to find and press RETURN.
  4. Press SOLID-APPLE-RETURN. The cursor will jump to the specified name or
     stop at the end of the file list if it couldn't find a match.
  5. Press RETURN to load the file.

Examine the Spreadsheet file called "Macro 0 Memo" on the UltraMacros disk for a
handy chart showing the possible macro 0 (zero) uses.
___________________________________________________________________________

A Macro Explained
-----------------
Here's some information about a handy macro that uses just a few of UltraMacros
powerful commands. Hopefully it will give you a better understanding of how
UltraMacros commands can be utilized.

  1. Start AppleWorks and insert the UltraMacros disk in a drive.
  2. Add the Data Base files "Addresses" and "Phone Calls" to the Desktop, along
     with the "Macros Ultra" Word Processing file.
  3. Select "Macros Ultra" and use OPEN-APPLE-F to find Phone Calls.
  4. You'll see a detailed macro description. Examine it briefly.
  5. Switch to the "Addresses" file and put the cursor on a name. Press
     SOLID-APPLE-CONTROL-P. In an instant you'll see a screen something like
     this:


|-------------------------------------------------------------------------|
|File:  Phone Calls            REVIEW/ADD/CHANGE        Escape: Main Menu |
|                                                                         |
|Selection: All Records                                                   |
|                                                                         |
|Record 2 of 2                                                            |
|=========================================================================|
|                                                                          |
|Date: Aug 19 87                                                           |
|Name Bryan Ross                                                           |
|Number: (111) 222-3333                                                    |
|Time St: 5:35 PM                                                          |
|Time End: -                                                               |
|Comment: -                                                                |
|                                                                          |
|                                                                          |
|                                                                          |
|                                                                          |
|                                                                          |
|                                                                          |
|--------------------------------------------------------------------------|
|Type entry or use @ commands                                              |
|==========================================================================|

All you need to do is press SOLID-APPLE-= when the conversation is over (to
enter the time), and you've got a detailed record of the call. How did the macro
do it? Examine it step-by-step. The curly {braces} allow you to embed comments
between the <token brackets>. These comments are not stored in the macro table,
so they don't waste any space.

Nowhere does it tell you that you have to compile the macro file before using
it. You should know that, but we're reminding you here anyway.

___________________________________________________________________________


TimeOut MacroTools
------------------
MacroTools is a TimeOut disk fill of sample macros, TimeOut tips, special
TimeOut applications, and a surprise or two. UltraMacros beginners will
appreciate the powerful ready-to-use macros and instructional macro tips.

Veteran macro maniacs will love the programming ideas and samples on the disk.
They'll especially like "Debug", a TimeOut application that displays all kinds
of useful macro table information that only a macro programmer could enjoy. It
even allows variables to be examined and modified!

Check the "NOTES" file on the UltraMacros disk for more information about
MacroTools.

TimeOut MacroTools will be released during the first quarter of 1988.
___________________________________________________________________________


Changes from Super MacroWorks
-----------------------------
Here is a brief summary of changes for users converting from Super MacroWorks to
UltraMacros. Several obvious differences relate to TimeOut. all compiling,
saving of compiled macros, macro listing, changing mouse options, etc., is done
using the TimeOut applications. The resulting saving of memory space allows the
actual UltraMacros program (ULTRA.SYSTEM) to be more powerful.

The following new tokens have been added to UltraMacros:

ato, begin, call, cell, clear, else, elseoff, getstr, goto, highlight, id#,
left$, nosleep, onerr, peek, poke, posn, print, pr#, rem, right, right$, screen,
then, time24, val, wait, wake

A significant improvement in an existing command is the new ability of <find> to
search any numbered highlighted bar menu. It works with the OPEN-APPLE-Q Desktop
Index, the OPEN-APPLE-ESCAPE TimeOut menu and with any normal menu such as the
list of printers you're given before printing a file.

The following tokens are not available. They are unnecessary because their
functions can be duplicated with existing commands.

end?. menu, resume, swap, OPEN-APPLE-#, OPEN-APPLE-$, :print, compile, save0,
load0, 0=, if0, var=, incvar, decvar, varnot, var

The "var" commands have been replaced with a full set of 26 numeric variables.
The other commands cam be replaced with the new UltraMacros commands as
described in the file "Macros From SMW" on the UltraMacros disk.

The ability to automatically download a Power Print font at startup time was
dropped.

NOTE: You may leave Super MacroWorks on the AppleWorks STARTUP disk. The
UltraMacros installation program will rename SUPER.SYSTEM to SUPER.SYSOLD.

To use UltraMacros, you can then boot your AppleWorks STARTUP disk, choose
"ULTRA.SYSTEM" with a program selector, or type "-ULTRA.SYSTEM" from Basic.

To use Super MacroWorks, type "-SUPER.SYSOLD" from Applesoft BASIC or choose
"SUPER.SYSOLD" with a program selector.
___________________________________________________________________________

Macro Token List
----------------
Here's a complete alphabetical listing of all UltraMacros tokens, along with a
short description.

Token                       Summary
------------------------------------------------------------------------
adb       AppleWorks' Data Base application code
ahead     Find next space
all       Any of AppleWorks' three application types
asc       Convert string character to its ASCII equivalent as shown on the
          Key Chart. Only the first character of a string is used.
asp       AppleWorks' Spreadsheet application code.
ato       TimeOut application code
awp       AppleWorks' Word Processor application code
ba-       Both Apple i.e. OPEN-APPLE and SOLID-APPLE are pushed together
back      Find previous space
begin     Start of repeatable section (see rpt)
bell      Sound the AppleWorks error bell
call      Execute a machine language subroutine
cell      Read current cell, category, or WP line to macro 0 (zero)
chr$      Return ASCII equivalent of a numeric variable
clear     Set all numeric and string variables to 0
ctrl-     Control key
date      Display date in this format: November 26, 1987
date2     Display date in this format: 11/26/87
dec       Decrement the cursor character
del       Delete key
disk      Read disk name to macro 0 (zero)
down      Down arrow key
else      Reverses conditional status of a macro
elseoff   Return to macro being unconditional
esc       Escape key
find      Find a name or carriage RETURN
findpo    Find a printer option
getstr    Define a string from the keyboard
goto      Jump to specified macro
highlight   Invert specified screen portion
id#       Returns TimeOut application number
if        Execute macro if condition is true
ifkey     Checks if specified key was pressed
ifnot     Execute macro if condition is not true
inc       Increment cursor character
input     Accept keystrokes until RETURN is pressed
insert    Force the insert cursor on
key       Wait for keypress and return its value
lc        Force cursor character to lower case
left      Left-arrow key
left$     Return left part of string
len       Return length of a string
msg       Display message on screen
nosleep   Cancel sleeping macro
oa-       OPEN-APPLE key
onerr     Set error handler conditions
path      Read disk and file name to macro 0 (zero)
peek      Return value of memory address
poke      Store data in a memory address
posn      Returns cursor position
print     Print variables
pr#       Send print output to screen or printer
read      Read character under cursor to macro
recall    Recall stored text to macro 0 (zero)
rem       Remark within a macro
right     Right arrow key
right$    Returns the right part of a string
rpt       Repeat the current macro
rtn       Return key
sa-       SOLID-APPLE key
screen    Read screen portion into macro 0 (zero)
spc       Space bar key
stop      Unconditionally stop all macro activity
store     Store macro 0 (zero) in a awp or asp file
str$      Return the string equivalent of a numeric variable
tab       TAB key
then      Filler token, does nothing but look pretty
time      Display time in this format: 7:28 PM
time24    Display time in this format: 19:28
up        Up arrow key
uc        Force cursor character to upper case
val       Return numeric value of a string
wait      Wait until keypress or time is up
wake at   Set sleeping macro
zoom      Force zoom out
___________________________________________________________________________


TIMEOUT UTILITIES

Using the Utilities
-------------------
To use the TimeOut Utilities, make sure that the file TO.UTILITIES has been
copied to your TimeOut applications disk. Start up AppleWorks and press
OPEN-APPLE-ESCAPE to call up the TimeOut menu. Select "Utilities" and you will
see the following screen:

          TimeOut applications utility options

          1. Configure

          2. Load to memory

          3. Dump from memory

          4. Change memory status

          5. Change name

          6. Sort menu

___________________________________________________________________________


Configure
---------
The "Configure" option allows you to set new defaults for your TimeOut
applications. Configurable options might include printer type, default font,
location of files needed by the application, etc. Not all TimeOut applications
have configurable options.

To configure an application, select "Configure" from the Utilities menu. Then
select the application you want to configure. You will see a menu indicating
what options may be configured for that particular application. You should see
the current value for each option in brackets [...].

Select an option that you would like to change. Enter or select the new value
for that option. Make sure that the TimeOut applications disk is in a drive so
that the application can be updated with the new value. The next time you use
the application, it will use the new value you have supplied.

After you are finished updating configurable options, press ESCAPE to return to
the Utilities menu.

Load to Memory
--------------
TimeOut applications are either disk resident or memory resident. If an
application was configured as disk resident when you started up AppleWorks, you
can load it into memory using the "Load to Memory" option. Just select the
option from the Utilities menu and select which application you would like to
load.

Dump from Memory
----------------
If you receive a message from AppleWorks indicating that it was unable to
complete an option because of insufficient Desktop memory, you may need to dump
one or more TimeOut applications that are memory resident. Select "Dump from
memory" from the Utilities menu and select which application you would like to
dump. Notice that the amount of free memory indicated in the lower right hand
portion of the screen increases with each application you dump. Applications
that are dumped are returned to disk resident status for the remainder of the
AppleWorks session.

Change memory status
--------------------
This option allows you to indicate whether a TimeOut application is disk or
memory resident. Note that this only indicates how the application will be
treated when you start up AppleWorks. To load an application into memory or to
return it to the disk for the current AppleWorks session, you will need to use
the "Load to memory" option or the "Dump from memory" option.

Change name
-----------
This option allows you to change the name of the application as it appears in
the TimeOut menu. The Beagle Brothers staff carefully selects a good name for
each application. However, you have the flexibility of renaming it if you wish.

If the new name you enter is longer than the old name, the name change will not
be reflected in the TimeOut menu until the next time you start up AppleWorks.

Sort Menu
---------
When you apply TimeOut to your AppleWorks STARTUP disk, you are given the option
of indicating whether or not you want the TimeOut menu automatically sorted by
application name. If you choose not to have the menu sorted, you can still sort
it after starting up AppleWorks by selecting "Sort menu" from the Utilities
menu.
___________________________________________________________________________

Key Chart
---------
The Key Chart has 128 possible character codes, with each one having a low and a
high value. The high value is 128 greater than the low value. In AppleWorks, the
high value represents an OPEN-APPLE command, and the low value represents normal
text. These numbers bore most people, but they're vital for understanding how
<asc>, <chr$> and <key> work.

A viewpoint from Some Other Guy
-------------------------------
My friend, the cat, states that those keystrokes shown for 0 through 31 are
input conventions that have no force of law in the RS232-c world. By that he
means that we talk of control-M as if it *must* be the RETURN key and control-U
as if it must be the right arrow. The fact is that RS232-c does not state that
at all. Control-M is "cr" (which is turned by UNIX systems into line feed
{cntrl-J which is "nl" i.e. new line}. Is your head starting to hurt? Mine is.
Finally, control-U is really "nak" not the right arrow at all.

It is *convention* that says these keys and those control codes are associated.
Don't fret, Apple abides by those conventions - as do most/all terminal makers.
The point of all this is to teach you that you cannot believe *everything* you
read, no matter what bird brain is the author.


     Low          High     Low      High      Low     High      Low     High
-----------------------------------------------------------------------------
      0   ctrl-@  128       32   spc 160       64  @   192       96  `   224
      1   ctrl-A  129       33   !   161       65  A   193       97  a   225
      2   ctrl-B  130       34   "   162       66  B   194       98  b   226
      3   ctrl-C  131       35   #   163       67  C   195       99  c   227
      4   ctrl-D  132       36   $   164       68  D   196       100 d   228
      5   ctrl-E  133       37   %   165       69  E   197       101 e   229
      6   ctrl-F  134       38   &   166       70  F   198       102 f   230
      7   ctrl-G  135       39   '   167       71  G   199       103 g   231
left  8   ctrl-H  136       40   (   168       72  H   200       104 h   232
tab   9   ctrl-I  137       41   )   169       73  I   201       105 i   233
down  10  ctrl-J  138       42   *   170       74  J   202       106 j   234
up    11  ctrl-K  139       43   +   171       75  K   203       107 k   235
      12  ctrl-L  140       44   ,   172       76  L   204       108 l   236
rtn   13  ctrl-M  141       45       173       77  M   205       109 m   237
      14  ctrl-N  142       46   .   174       78  N   206       110 n   238
      15  ctrl-O  143       47   /   175       79  O   207       111 o   239
      16  ctrl-P  144       48   0   176       80  P   208       112 p   240
      17  ctrl-Q  145       49   1   177       81  Q   209       113 q   241
      18  ctrl-R  146       50   2   178       82  R   210       114 r   242
      19  ctrl-S  147       51   3   179       83  S   211       115 s   243
      20  ctrl-T  148       52   4   180       84  T   212       116 t   244
right 21  ctrl-U  149       53   5   181       85  U   213       117 u   245
      22  ctrl-V  150       54   6   182       86  V   214       118 v   246
      23  ctrl-W  151       55   7   183       87  W   215       119 w   247
      24  ctrl-X  152       56   8   184       88  X   216       120 x   248
      25  ctrl-Y  153       57   9   185       89  Y   217       121 y   249
      26  ctrl-Z  154       58   :   186       90  Z   218       122 z   250
esc   27  [       155       59   ;   187       91  [   219       123 {   251
      28  \       156       60   <   188       92  \   220       124 |   252
      29  ]       157       61   =   189       93  ]   221       125 }   253
      30  ^       158       62   >   190       94  ^   222       126 ~   254
      31  _       159       63   ?   191       95  _   223       127 del 255
___________________________________________________________________________


 Macro Programming Problems 

Please examine all sample macro files on this disk. Use the OPEN-APPLE-F command
to search for samples of a specific command. We don't have the time to teach you
how to use the macro commands; you'll have to learn from the examples and the
manual. There will be more information given with the sample macros on a TimeOut
disk which should be released in early 1988.

If you're having trouble with your own custom macros, exhaust every possibility
before writing. To have me (Randy Brandt) examine your macros for what might be
an UltraMacros problem, send them on a disk to my attention along with a
description of the problem and your hardware/software setup.

Please remember that debugging macros are almost last on my priority list (just
before taking out the trash), but you might catch me on a good day.

There are a few features which are unclear or not mentioned in the manual:


1. String variables can be referenced indirectly by using a numeric variable to
   specify the string to use:

a:<all $0 = "ZERO" : $1 = "ONE" : A = 0 : print $(A) : A = A + 1 :
   print "  " + $(A)>! prints ZERO  ONE

b:<all B = 3 : $(B) = screen 1,1,6 + "TEST" : print $(B)>!


2. String tokens requiring one parameter can not use equations. The following
   macro would be illegal because "getstr 3 + 2" should be "getstr 5" or some
   other single parameter.

a:<all msg "< " + getstr 3 + 2  + screen 1,1,9 + " >">!

Parameters for strictly numeric tokens can be equations:

a:<all highlight 9, L, len $(A) + 10, L>! from "Macros Menu"

 Macros Manual 

Load the file "Macros Manual" from the UltraMacros disk. It contains many of
sample macros described in the manual, as well as a few bonuses.



Customer Support Information
----------------------------
If you have questions or problems, you can contact the Beagle Brothers Technical
Support Staff for expert assistance.

Before calling, check the instruction manual to see if it contains the
information you need. Write down a complete description of the problem, the
version number of the software, and the names and version numbers of any other
AppleWorks enhancement programs you're using.

If you have a modem, you may also receive Tech Support on our 24-hour Customer
Support System. The system provides an electronic mail and conferencing system,
along with the latest information about product updates and changes.

Technical Support:
     (619) 452-5502 8AM to 5PM, weekdays (Pacific time)

Modem Technical support:
     (619) 452-5565 24 hours, everyday

Or, you can write to:

Beagle Bros, Inc.
6215 Ferris Square, Suite 100
San Diego, CA 92121

 -END- Chapter 4 & END OF ULTRAMACROS DOCS

