                                  MACRO SYSTEM
                                   Version 2.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 many repetitive tasks. Each
macro, once written and translated, must be installed and assigned a hotkey.
Afterwards, pressing the hotkey from any application will execute the macro.


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

In order to install MACRO SYSTEM youll need a Psion Series 3a pocket computer
with at least 36K of disk space. When running, MACRO SYSTEM uses 28K of main
system memory while in the foreground and 19K 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 (34851)      Main program file          \APP\
  SYS$PRGM.IMG (1184)    Macro translator           \IMG\

These files are optional:
  MACRO.DBF (20502)      Macro commands reference   \DAT\
  MACRO.HLP (2744)       Macro System help file     \MACRO\SYS\
  SYS$HELP.OPO (4157)    Help driver                \MACRO\SYS\ or \OPO\
  RUNMACRO.OPL (637)     Program to run a macro     \OPL\
                         from the System Screen
  EDITMCR.ALS (608)      Macro editor alias         \APP\
  DEFAULT.M (75)         Template for Macro editor  \WDR\
  DATE.MCR (154)         Example macro              \MACRO\MCR\
  DIAL.MCR (773)         Example macro              \MACRO\MCR\
  DIALOGS.MCR (1341)     Example macro              \MACRO\MCR\
  HELP.MCR (1428)        Example macro              \MACRO\MCR\
  INFO.MCR (410)         Example macro              \MACRO\MCR\
  INSTALL.MCR (2364)     Example macro              \MACRO\MCR\
  LINK.MCR (49)          Example macro              \MACRO\MCR\
  SYMBOL.MCR (278)       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. You may want to copy the rest of the files as well.

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. This
will also remove the \MACRO\SYS\ directory which contains MACRO.INI
initialization file.


Operation
=========

NOTE: MDB files used by Macro System 2.0 are INCOMPATIBLE with those created by
Macro System 1.0. You should delete any old MDB files before using the new
version.

When you first run Macro System you will see a screen with 16 empty slots and
four folder tabs at at the top. Each of the folders can hold 16 macros which
makes 64 macros total.

Position the cursor on any of the slots and 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 a slot
where you would like to install the Date macro, and press Psion-I (or just
Enter) to install it. In the resulting dialog select the translated macro file,
DATE.MCO, and press Enter. The Assign Hotkey dialog will appear. Press a key
combination. It should not be a combination that is in use by some other
program. For example, you might want to assign Control-Shift-D (for Date). Press
Enter to complete the dialog. From now on, if you press Control-Shift-D, 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). You will
have an option of just de-installing the macro or removing both of its files,
MCR and MCO, from disk.

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          Creates a new macro. You will be prompted to enter a name
                    for the macro to be created. Then the Macro editor will open
                    where you can type the source code for the new macro.

Record              Records a new macro. You will be prompted to enter a name
                    for the macro to be created. Switch to the application you
                    wish to record the macro in and press Psion-Menu to start
                    recording. In order to stop recording, press Psion-Menu
                    again. The newly recorded macro will have to be translated
                    and installed before it can be run.

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.

Run                 Allows to run a macro directly from the Macro System screen
                    without using the macros hotkey.

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.

Change hotkey       Allows you to assign a new hotkey to a previously intstalled
                    macro.

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 copyright information about MACRO SYSTEM.

Set preferences     Allows you to change the screen font between Swiss and
                    Roman. Here you can also rename the tab labels.

Zoom in             Increase the screen font size.

Zoom out            Decrease the screen font size.

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.

There are two ways to create macros:
     1. Record
     2. Edit

Recording can be easier in some situations. The functionality of a recorded
macro, however, is limited to emulating keypresses. Recorded macros can then be
edited to provide for much greater functionality.

You can create and edit macros directly from the MACRO SYSTEM screen by
selecting the Create new, Edit or Record 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 for more information.


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.

Thanks to David Wood from Psion for making his KMAC source code available.

Also thanks to beta testers Wolfgang Schirmer and Richard England.


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

1.0 - 3/25/94 - First public release

2.0 - ??/??/94 - Major upgrade.

Changes:

     * Redesigned the interface - added tabs, zoom feature
     * Redesigned hotkey capturing. Abandoned Control-A. Now any possible
     combination can be assigned to any macro. This increased the limit of 22
     macros to (now arbitrary) 64.
     * Added an array of remote dialog functions: dInit, dText, dChoice,
     dChoiceA, dButtons, dEdit, dPosit and Dialog
     * Improved error handling
     * Other added functions: Alert, CurrPid%, Exit, GiPrint, HookDyl, Hotkey,
     Info, Kill, Pid2App$, Pid2Fil$, Pid2Tsk$, PutText, RunAppB, RunAPpC,
     SrvPid%, Tsk2Pid%, UsePid and UseTask.


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.
