                                  MACRO SYSTEM
                                   Version 1.0
                         Copyright (c) Tom Dolbilin 1994


Introduction
============

MACRO SYSTEM is an application written for a Psion Series 3a pocket computer
which allows the user to create cross-application macros. Macros are
preprogrammed series of commands that help automate repetitive tasks. Each
macro, once written and translated, must be installed and assigned a hotkey.
Afterwards, pressing the hotkey from any application executes the macro.


System Requirements
===================

In order to run MACRO SYSTEM you need a Psion Series 3a pocket computer with at
least 25K of disk space. When running, MACRO SYSTEM uses 23K of main system
memory while in the foreground and 13K while in the background.


Installation/Removal
====================

Here are the files stored in MACSYS.ZIP and where they should go on your S3a:

  File (size)            Description                Target directory
  -----------------------------------------------------------------
  MACRO.OPA (19160)      Main program file          \APP\
  SYS$PRGM.IMG (1184)    Macro translator           \IMG\

These files are optional:
  MACRO.DBF (8598)       Macro commands reference   \DAT\
  DEFAULT.M (75)         Template for Macro editor  \WDR\
  DATE.MCR (161)         Example macro              \MACRO\MCR\
  HELP.MCR (916)         Example macro              \MACRO\MCR\
  INSTALL.MCR (744)      Example macro              \MACRO\MCR\
  TOMACRO.MCR (84)       Example macro              \MACRO\MCR\
  MACRO.TXT              This file

The above directories can be created on any local drive (Internal, A or B).
1. Install MACRO.OPA on the System Screen.
2. Copy SYS$PRGM.IMG to any \IMG\ directory.
3. Copy the files MACRO.DBF, DEFAULT.M and the example macros (*.MCR) to their
respective directories.

To remove MACRO SYSTEM from your machine, undo all of the above operations and
remove the \MACRO\ directory with all files and subdirectories it contains.
MACRO SYSTEM does not create any initialization or temporary files.


Operation
=========

When you first run Macro System you will see a screen with 22 empty slots each
preceded by a letter. Each slot can hold one macro and the letter will be the
hotkey for that macro.

Select "Edit" from the Macro menu. The dialog box will ask you to select the
macro name to edit. Select DATE.MCR and press Enter. The Macro editor will open
with DATE.MCR in it. Use Psion-T to translate the macro and Psion-X to exit the
editor.

You should now be back on the MACRO SYSTEM screen. Position the cursor on the
desired slot, say D for Date, and press Psion-I or Enter to install a macro. In
the resulting dialog, select the translated macro file DATE.MCO and press Enter.
From now on, if you press Control-A and then, while still holding Control down,
press D (the hotkey), the Date macro will be run. It will have no effect if you
are still on the MACRO SYSTEM screen, but try opening Word and pressing the key
combination from there and youll see the today's date and time being inserted.
You can, of course, customize the format of the text inserted by editing
DATE.MCR and retranslating the macro. You don't have to reinstall it on the
MACRO SYSTEM screen afterwards.

To remove a macro, select it first and then press Psion-R or Delete. This
doesnt delete the macro from disk, just removes it from the screen and disables
its hot-key.

You can also Disable macros without removing them from the screen. This will
keep them from running when a hotkey is pressed. Disabled macros have a line
drawn across their name. This could be done to macros that are rarely used as a
protection against accidental use. A macro that is sending a series of
keypresses is totally unaware of the state of the target application. Therefore,
careless usage of such macros can be disastrous.

The layout of MACRO SYSTEM screen is originally saved in the file
\MACRO\MACRO.MDB. You can have more than one layout, or "case" of macros. Use
File New menu option to create a new case. Only one case, however, can be open
(active) at any one time.

Pressing the Menu button brings up the MACRO SYSTEM menu. The arrangement of the
commands and their descriptions are listed in the following table.

FILE menu

New file            Creates a new file (case).

Open file           Opens an existing file (case).

MACRO menu

Create new          Runs the Macro editor where you can type the source code for
                    a new macro.

Edit                Used to edit the currently selected macro. It switches to
                    the Macro editor if the macro is already being edited or
                    launches it otherwise. If no macro was selected, you'll be
                    prompted for a macro name to edit.

Install             Installs a new macro in the currently selected slot or
                    replaces the existing one if the slot is already used.

Remove              Removes the macro from the currently selected slot.

Disable/Enable      Disables and enables the currently selected macro. Disabled
                    macros have a line drawn across their name and do not run if
                    their hotkey is pressed.

LOG menu

Log on/off          Turns the log on/off. Turning log on creates a text file to
                    which all errors and messages are written while a macro is
                    being executed.

View log            Used to view the log file. Logging is automatically turned
                    off.

Show error          Shows the most recent error, if any. No matter what
                    application youre in, the screen will blink if an error has
                    occurred during macro execution. Then you can switch to the
                    MACRO SYSTEM screen and use this option to find out which
                    error it was.

SPECIAL menu

About               Displays the information about MACRO SYSTEM.

Key codes           Used to determine the correct parameters for the SendKey
                    macro command. For example, the standard method of sending a
                    Ctrl-B keystoke to an app will fail:
                         CtrlDn:
                         Key:(%b)
                         CtrlUp:
                    The 'Key codes' menu option will give you the correct way to
                    accomplish this:
                         SendKey:(4,4,1)

Exit                Exits MACRO SYSTEM.


Creating Macros
===============

Macros are simple OPL programs that can use, but not limited to, the special
macro functions. You do not need to know OPL in order to write macros, but it
always helps to have some general idea.

You can create and edit macros directly from the MACRO SYSTEM screen by
selecting the Create new or Edit menu options. Macro source files are plain text
files having the MCR extension stored in the \MACRO\MCR\ directory. Use Psion-T
to translate macros from within the Macro editor. Translated macros will have
the same name, except their extension will be changed to MCO and they will be
put into the \MACRO\MCO\ directory.

Each macro MUST have a procedure called MACRO, like this:

     PROC Macro:
      ...
      macro functions
      ...
     ENDP

The complete reference for all macro functions is contained in the file
MACRO.DBF which can be viewed directly on the Series 3a with the Data
application. Refer to the example macros


Creating Macros
===============

Once again, once a macro has been created and installed, it can be executed from
any application (provided that MACRO SYSTEM is running in the background):
1. Hold down Control
2. Press A
3. While still holding Control down, press the letter of the slot where the
macro is installed

Credits
=======

I would like to thank John Boyce for his great help with RunApp: macro function,
for providing various programming information I had no way of getting otherwise,
for testing Macro at early stages and for giving helpful suggestions.


Version history
===============

1.0 - 3/25/94 - First public release


Disclaimer
==========

The author of this software is not responsible for any damage due to use of this
program. This software is provided without warranty of any kind.
