home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Boot Disc 8
/
boot-disc-1997-04.iso
/
PDA_Soft
/
Psion
/
misc
/
Kmac
/
KMAC.TXT
< prev
next >
Wrap
Text File
|
1994-04-25
|
56KB
|
1,311 lines
KMAC.APP, the keyboard macro record and playback app
====================================================
Introduction
------------
KMAC.APP allows you to automate many features of your S3a. KMAC can
be used to
* record keyboard macros
* play back these keyboard macros later
* edit your keyboard macros to add in extensive control features
* automate "demo" programs
* automate interactive tutorial programs
* simplify automated testing of programs (eg regression testing)
KMAC is designed to work as non-intrusively as possible. It doesn't
have its own "screen"; instead, it shares the screen of the current
foreground application.
There's no need to transfer to another screen to start recording
a macro. Just press Shift-Control-Space ("Space" for "Start
recording" - the same as in the built-in "Record" application), give
the name of the macro you want to record (and, optionally, a hot-key
for it), and then start pressing the keys you want recorded. (As
well as being recorded, the keys also have their normal effect - so
you can see how far you've got through your intended sequence.) When
you're finished, press Shift-Control-Space again. Then when you want
to replay this macro at a later date, just press Shift-Control-Enter
("Enter" for "Start playback" - the same as in the built-in "Record"
application). Hey presto, the key sequence is replicated exactly.
In case you forget these special hot-key combinations, just press
Shift-Control-Help, which brings up KMAC's own Help screen. The only
thing you need to remember is that the KMAC system uses the
Shift-Control modifier pair as its own special prefix. Then as the
Help screen reminds you, you use
Shift-Ctrl-Space to start or stop macro recording
Shift-Ctrl-Enter to play back the last macro recorded
Shift-Ctrl-Diamond to select another macro to play back
Shift-Ctrl-A through Z to play back the macro with this hot-key
Shift-Ctrl-Menu to review existing hot-key assignments
Shift-Ctrl-Esc to interrupt a macro playing back
Shift-Ctrl-Help to show the KMAC Help screen
(You are also asked if you want to see this Help screen every time
you start KMAC, so there's no need even to remember Shift-Ctrl-Help.)
KMAC stores all its macros in a plain text file. You can edit the
contents of this file to add in extra control features, such as
skip the next line if there's no dialog showing
stop unless a certain app (eg the Word Processor) is foreground
make any given application (eg the System Screen) foreground
load in another script file and take commands from that instead
loop back to the top of the present macro or script file
pause briefly (eg to allow the screen to redraw)
pause until the user "nudges" playback forwards again
switch into "single stepping mode" (useful for "debugging")
"bring" data from a background application
display "info messages" in the foreground application
present query or alert dialogs in the foreground application
If you understand Opl, you can write Opl programs that macros can
start, and inside these programs, you can do even more complicated
data manipulations and utilise all the features of Opl to control
macro playback. KMAC can also be used to start programs written in
C, and you can even arrange for the foreground application to start
running code from a specified DYL (which can have some very powerful
results).
Although you can do very powerful things with KMAC (and the length of
this documentation provides something of an indication of this), you
don't need to work hard and long at it before you can achieve some of
these results for yourself. You don't need to know Opl, nor any
other programming language. Nor is there any special requirement for
you ever to look at any of the .KMA (keyboard macro text files)
produced by KMAC. You can record and playback your first macro
literally seconds after copying the KMAC files onto your S3a.
Disclaimers
-----------
KMAC is not an official Psion product. You can not receive any
assistance with it by contacting Psion Technical Support, or any
other department within Psion. However, if you ask a question about
KMAC in the PSION conference on CIX, I will endeavour to answer it
within a few days (within reason).
KMAC is reasonably well tested but I cannot take any responsibility
for any problems you may encounter with your S3a as a result of using
it. KMAC exercises the software system on the S3a very fully and can
sometimes expose limitations of that software that are not otherwise
noticeable. However, despite these shortcomings, I have no doubt
that an S3a running KMAC is an even more powerful "personal
assistant" than one *not* running KMAC.
Files in KMAC091.ZIP
--------------------
KMAC.TXT This documentation
KMAC.APP The app itself
LPC.DYL Local Process Control DYL (used by KMAC)
KMAC.DBF Database of syntax of keywords understood by KMAC
KMACED.ALS Sample text editor for editing KMAC scripts
EGKMA.TXT Discussion of some example macros
KMACLIB.OPO Module to LOADM to access LPC from Opl programs
KMACLIB.OPL Source code for KMACLIB
OPLLPC.TXT Documentation on using LPC.DYL from Opl
For those who would like to look at it, the source code for KMAC.APP
and LPC.DYL is available in separate zip files, KMAC091S.ZIP and
LPC091S.ZIP. (This source code is in C and requires version 2 of the
C SDK to build it. It also assumes, in place, knowledge of the
object-oriented manner of operation of HWIM applications.)
Installing KMAC
---------------
Copy KMAC.APP into an \APP\ directory on your S3a.
Copy LPC.DYL into a \DYL\ directory on your S3a.
These are the only two files that you HAVE to copy onto your S3a,
though you may also find it convenient to copy at the same time
KMAC.DBF into a \DAT\ directory
KMACED.ALS into an \APP\ directory
In the System Screen, use the "Install" option and select "Kmac" from
the disk you copied it onto. An icon will be added to the System
Screen that it similar to (but noticeably different from) the icon of
the sound "Record" application.
Press ENTER with the highlight on "Kmac" under the Kmac icon. The
word "Kmac" will change into bold text, showing that the Kmac
application is running, but the System Screen remains in foreground.
(If you get an error instead, such as "File does not exist", check
that the file LPC.DYL is in a \DYL\ to-level directory.)
A dialog will be shown, displaying
The version number of KMAC, and its release date
A copyright message
A pair of action buttons: Esc for "Continue" and Enter for "Help".
Normally, when starting KMAC you will press Esc to make this dialog
go away. But sometimes you may wish to press Enter to view the Help
screen (described earlier in this document).
Later, when you want to exit KMAC, come back to the System Screen (if
necessary), put the highlight on the word "Kmac" under its icon, and
press Delete.
Recording your first keyboard macro
-----------------------------------
If necessary, start KMAC, and press Esc to clear the start-up dialog.
If you are not there already, go to the System Screen.
Now let's record a macro to set the keyclick volume to "Quiet".
Start by pressing Shift-Ctrl-Space. This brings up a dialog asking
you to give the name for the keyboard macro you want to record. Type
in any name (this can be up to 23 characters long), eg "Set keyclick
quiet", and press ENTER. You are now in recording mode.
Press Psion-s to display the "Set the sound" dialog. Press DOWN
three times, to highlight the "Key click" line. Press Q, to select
"Quiet" from the choice list. (Nothing will change on the screen if,
perchance, the setting is already "Quiet".) Press ENTER to confirm
the dialog.
Now press Shift-Ctrl-Space to finish recording. A special info
message is displayed at the top left corner of the screen, confirming
the name of the macro, and the number of keypresses in it (6 keys in
this case).
Playing back this macro
-----------------------
In order to see the effect of this macro, manually set the keyclick
back to loud. Move the cursor around a bit, and listen to the loud
keyclick.
If necessary, start KMAC, and go to the System Screen. Then press
Shift-Control-Enter. (You don't need to put the highlight back on
"Kmac" first. Kmac captures this key combination, regardless of
where the cursor is.)
There is a flurry of activity in the middle of the screen, and then
an information message is shown at the top left corner: "Playback
successful". Move the cursor around a bit and you'll hear how the
keyclick has indeed gone quiet again.
Revising the hotkey for a macro
-------------------------------
Press Shift-Control-Menu. This brings up the KMAC "Revise hot key"
dialog. This shows a choice list of all the macros you have recorded
so far, together with their hot-key. You'll see that the macro you
have just recorded has the hot key "[M]" shown for it (at the end of
its name). Let's change this to [Q], as follows:
Press ENTER to confirm that we want to change the hotkey of the macro
shown. Then press Q to select "Q" in the choice list of possible
hotkeys shown in the next dialog. Press ENTER to confirm this
choice. If you press Shift-Control-Menu at this stage, you'll see
that the hotkey for your macro has indeed been changed.
By default, all new macros get assigned the hotkey [M]. Since Ctrl-M
and Ctrl-Enter produce identical keycodes (13 in each case) and
have identical modifiers, this means that Shift-Ctrl-Enter runs the
macro with hotkey [M]. (But once you've revised the hotkey from [M]
to [Q], the macro can no longer be played back by Shift-Ctrl-Enter.)
At this stage, you should probably experiment by recording several
other macros and playing them back - either using Shift-Ctrl-Enter,
or using Shift-Ctrl-<hotkey>, or by using Shift-Ctrl-Diamond and then
selecting the macro to playback by name.
Note that you cannot record, in a macro, a keypress that takes you
from one application to another - such as pressing a task key. The
recorder facility within KMAC is limited to recording keypresses in
only one application at a time. (But see later in this document for
how to create macros that DO switch from one application to another.)
Macros are saved to file
------------------------
When you exit KMAC - by pressing Delete with the highlight on "Kmac"
in the System Screen - the macros are written out to a plain text
file. You can, if you wish, create several different files of
macros, eg by using the "New file" option in the System Screen.
You can use the supplied word processor alias KMACED.ALS to look at
these .KMA macro files. (Alternatively, just use the "Create new
list" option in the System Screen to create your own text-mode alias
for the word processor, for \KMA\*.kma files.) You may find it
easiest to set the zoom setting to the smallest font (and then to
save this as the default template for these files - but be sure to
remove the text before you do this).
Note that changes in macros are only written to file when KMAC is
exited (or receives a "switch files" instruction from the System
Screen). Watch out, in particular, that if you have the .KMA file
open in an editor, and then try to exit KMAC, it will not be able to
do so, if there are changes that have to be written to file. Exit
the editor first and then KMAC. Likewise if you want any changes you
make (by hand-editing) in a .KMA file to be picked up by KMAC, you
have to exit KMAC first and then restart it.
The format of .KMA files
------------------------
You'll be able to see that .KMA files consist of a brief header
portion followed by a series of macro definitions.
The header section always starts with the line
KMAC 1.00
and KMAC will refuse to load a KMAC file that does not start in this
way.
After this, one or more of the two following lines may also be present
in the header section:
AUTO x
defines what hot-key, if any, should be given to all new macros. By
default, x has the value "M". You can put "?" instead, to force KMAC
to ask you to supply a hotkey every time, immediately after recording
a new macro. Or you can put "-", so that new macros are left without
any hot key defined for them.
QUIET
specifies that any new macro recorded is automatically "quiet" (see
below for the significance of this).
The definition of an individual macro
-------------------------------------
Individual macro definitions alway start with the line
MACRO <name>
which also specifies the name of the macro.
After this, there can be a few lines specifying additional
information about the macro; then there is the "CONTENTS" section for
the macro.
Before the contents section, the following lines can appear:
KEY x
which specifies the hot key of the macro, eg "KEY T" to specify the
hotkey Shift-Ctrl-T
QUIET
which specifies that the macro is "quiet", meaning that the info
message "Play back successful" does NOT get displayed at the end of
the macro playback
BACKGROUND
which specifies that the macro does not start off by automatically
"attaching" to the foreground application (see below for the
significance of this).
The contents section must always start with the keyword "CONTENTS"
and continues either until there is a blank line or the end of the
file is reached. The contents themselves are sequences of two types
of commands:
1. raw keycodes (together, optionally, with modifiers)
2. alphabetic commands (see below for examples).
In all, there are over 40 different alphabetic commands, such as
"G" to ensure the attached process is in its "ground state"
(without any menu or dialog showing, etc - the macro ensures this is
the case by sending as many Esc keys as are required)
"I" to display a specified information message
"J" to jump a given number of steps in the macro, if a certain
condition is true (for example, if there is a dialog showing)
"S" to send a specified string of keys (this can be easier to
understand than just seeing the raw keycodes)
"s" to adjust the "single stepping state" of the macro.
Evidently, the case of the first letter of the command is
significant. The "S" and the "s" commands are completely different.
The database file KMAC.DBF gives summary info about each of these
"alphabetic" commands. These commands are also discussed in more
detail in the remainder of this documentation.
The only way alphabetic commands can appear in a macro is if they are
edited in via an editor (such as KMACED). There is no facility to
enter them midway through recording a macro (though, clearly, they
can be added in after finishing recording the "basics" of a macro).
You can also add in comments, which are lines starting with the
exclamation mark character, "!".
There is a limit of around 3000 characters for an in-memory macro.
For longer macros, you have to put some of the contents into a
separate file, and then load that file during playback, eg using the
"l" command.
Introducing alphabetic commands
-------------------------------
The macro "Set keyclick quiet" described earlier is saved to file as
follows:
MACRO Set keyclick quiet
KEY Q
CONTENTS
627 8, 257, 257, 257, 113, 13
There is one problem with this macro, however. If you press
Shift-Control-Q when you are in an application other than the System
Screen, it will have quite the wrong effect. There is nothing in the
macro itself to tie it to the System Screen. In fact, by default,
all KMAC macros attempt to "attach" to the application that is in
foreground when they are invoked.
A simple way to fix this would be to edit the macro (using eg KMACED)
to add in the line
gSystem
as the first "contents" of the macro. Thus the macro definition
becomes
MACRO Set keyclick quiet
KEY Q
CONTENTS
gSystem
627 8, 257, 257, 257, 113, 13
(Remember that you will have to restart KMAC for any changes made in
a top-level macro to have an effect.)
If you also have a macro for setting the keyclick loud, you should
make the corresponding change to it as well. Then you can go into an
application such as the calculator, and change the keyclick volume
setting between Quiet and Loud at will, just using a single key
combination each time, without having to task to the System Screen.
This macro uses the "go to" command, with letter "g". It specifies
that the macro should "go to" the first application it finds with the
given name for display in the Status Window. (The operation of "g"
is more subtle than you might at first expect. Eg to "go to" the
instance of the "Data" application that has the file "Data.dbf" open,
you would need to specify "gData.dbf". See later for a fuller
discussion of how the "g" command works.)
Note that if you play back this macro from an application other than
the System Screen, the System Screen does NOT become foreground (ie
come to the front) as a result. The dialog interaction takes place
with the System Screen entirely in the background. Which makes for a
neater screen display.
If you wanted to make the System Screen come to the front, while the
macro was played back, you could follow the "g" command with an "F"
command - the command that brings the attached application to
foreground. In this case, the macro could become
MACRO Set keyclick quiet
KEY Q
CONTENTS
gSystem
F
627 8, 257, 257, 257, 113, 13
As another idea, you could put a "B" at the end of this macro - to
put the System Screen into background again after processing the
string of keys. But frankly, whilst the "F" and "B" commands can be
very useful in many places, this particular macro is not one that
benefits from their presence.
Information messages during macro playback
------------------------------------------
A better suggestion for improving the above macro is to change it to
MACRO Set keyclick quiet
KEY Q
QUIET
CONTENTS
ISetting keyclick to quiet
gSystem
627 8, 257, 257, 257, 113, 13
and its "partner", "Set keyclick loud", could become
MACRO Set keyclick loud
KEY L
QUIET
CONTENTS
ISetting keyclick to loud
gSystem
627 8, 257, 257, 257, 108, 13
This introduces the "I", or "Information message" command. Try these
and see what their effect is.
Note that the keyword "QUIET" has been added to these macros, in
between their name definitions (the "MACRO" line) and the start of
their contents (the "CONTENTS" line). This has the effect of
suppressing the "Play back successful" info message that would
otherwise overwrite the macro's own "Setting keyclick..." information
message.
Clarifying the notion of the "attached process"
---------------------------------------------------
If you go to the Calculator and press Shift-Ctrl-L to play back the
"Set keyclick loud" macro, and immediately start pressing the Up and
Down cursor keys, you will see the "Setting keyclick to loud"
information come up on the screen some time PRIOR to the keyclicks
actually changing to loud. This is because the remainder the macro
only runs when the System Screen application has a chance to respond
to the incoming sequence of keys (and since the System Screen is in
background at this time, any keys typed into the foreground
application will get processed at a higher priority - thereby
delaying the conclusion of the macro playback).
A simple idea to fix this would be to rearrange the macro as follows:
MACRO Set keyclick loud
KEY L
QUIET
CONTENTS
gSystem
627 8, 257, 257, 257, 108, 13
IKeyclick set to loud
The result is that the "I" command only gets acted on when the
preceding sequence of keys has actually finished being processed.
However, if you try this change to the macro, you will find that no
information message appears on the screen. This is because
information messages (created by "I" commands) are always displayed
by the current "attached process". In this case, the attached
process is the System Screen.
To make this new macro work properly, you will need to insert an "f"
command just before the "I" line. Thus
MACRO Set keyclick loud
KEY L
QUIET
CONTENTS
gSystem
627 8, 257, 257, 257, 108, 13
f
IKeyclick set to loud
The effect of the "f" command is to attach KMAC to the current
foreground process. All subsequent KMAC commands will be directed
towards that process - or until such time as another command may
cause another change in which process is the attached one.
For clarity, it should be emphasised that the notion of a process
being in "foreground" is quite distinct from that of a process being
"attached" to KMAC. The foreground process is the one whose screen
is shown, and which receives all standard keys as typed on the
keyboard. The attached process is the one which receives all KMAC
commands.
Note also that all KMAC macros start of, by default, by attaching to
the current foreground process. If this is undesireable, put the
keyword "BACKGROUND" in the header of the macro definition (in
between the "MACRO" keyword and the "CONTENTS" keyword).
Upper-case and lower-case letter commands
-----------------------------------------
Note that the commands "F" and "f" are quite different: the "f"
command causes KMAC to attach to the current foreground process,
whereas the "F" command causes KMAC to move the current attached
process into foreground.
Although there is no strict rule for which commands are represented
by upper case letters and which by lower case letters, the following
guiding principle generally applies: commands have upper case letters
if they involve the active cooperation of the attached process,
whereas they have lower case letters if they only cause changes
within the KMAC process itself.
Thus the "g" command (the "go to" command) simply alters which process
is the one KMAC is attached to. By contrast, the "G" command (the
"Ground state" command) involves setting Esc keypresses to the
attached application, until such time as any dialogs, help screens,
or menus showing have all been cancelled.
Again, the "I" command (the "Information message" command) requests
the attached process to display an information message in the top
left corner of its screen. By contrast, the "i" command (the "image
launcher" command) merely executes a specified image (usually .IMG)
utility program (see later for examples).
Abbreviations are possible
--------------------------
In fact, in the header sections of .KMA files, only the first letters
of keywords are significant, and the remainder of the first word on
the line is always skipped.
This means that instead of typing eg
MACRO Set keyclick loud
KEY L
QUIET
CONTENTS
gSystem
...
you could just type
M Set keyclick loud
K L
Q
C
gSystem
...
Requesting user confirmation during macros
------------------------------------------
Try typing in the following macro definition (remember that you need
to use an editor such as KMACED to edit macro definitions, and that
you need to exit KMAC before you start editing, and then restart it
after you have finished editing):
MACRO Bring
Q
K B
C
QOkay to Bring?
xd0
L24
Restart KMAC, and go to the Agenda and highlight an appointment.
Next go to the Database and press Shift-Ctrl-B.
The effect of the "Q" command, as you will see, is to display a query
dialog. This can have either one or two lines of text - depending on
whether a comma is found in the string after the "Q". Thus
QOkay to Bring?
results in a query dialog with only one line of text, whereas
QOkay to Bring,(press 'N' to cancel)
results in a query dialog with two lines of text. In either case,
the dialog has a No/Yes pair of action buttons.
The way the macro tests the result of this dialog (ie whether the
user chose 'Yes' or 'No') is by testing the value of the so-called
"d-variable" ("d" for "decision"), at some later stage in the macro.
There are various methods of testing the d-variable. In this case,
the "x" command (the "eXit" command) is used.
The "x" command has various formats. You can use "x" all by itself,
to exit macro playback unconditionally. Or you can follow the "x"
with several different test criteria. Here, the "xd" variant is used
(see later for the other possibilities). "xd0" means to exit macro
playback if the d-variable has value 0 (or less).
The prior "Q" dialog sets the d-variable to 1 if the user chose
'Yes', and otherwise to 0.
Placing a "Q" command in a macro can avoid accidents if the user
chooses the wrong macro hotkey by mistake.
A variant on the "Q" command is the "N" command (the "Notify"
command). This has exactly the same syntax, except that the No/Yes
pair of action buttons is replaced by a single "Continue" action
button. Since there is no decision to be made in this case, the
current value of the d-variable is not altered by the "Notify"
dialog. (As for "Q", the "N" command can specify either one or two
lines of text.)
Note: the "L" command (the "Link paste" command) attempts to "Bring"
up to the specified number of characters from the first paragraph of
highlighted text in the application that is currently the "Link paste
server". (The terms "Bring" and "Link paste" are interchangeable.)
If the second parameter - 24 in the above example - is omitted, the
maximum number of characters to bring is set to 128. An error
results if this value is specified as greater than 128.
Interrupting macro playback
---------------------------
Note that you can always interrupt macro playback by pressing the
Shift-Ctrl-Esc key combination. This fact may be helpful if you have
started macro playback in error.
The macro will be interrupted, by KMAC, at the earliest possible
opportunity. Occasionally, this may not be immediate - eg if the
macro is inside a "P" ("pause") or "y" ("yield") command (see below
for more about these commands). Also, if the user presses
Shift-Ctrl-Esc while the macro is waiting for the user to answer an
"N" or "Q" dialog, the macro will be interrupted only after the
dialog is answered.
Sending strings of keys - the "S" command
-----------------------------------------
When you are looking at a macro inside a .KMA file, you may have
difficulty, at times, in discerning the exact meanings of all the
different keys inside a command such as
627 8, 257, 257, 257, 108, 13
For convenience, KMAC also supports the "S" command for sending
sequences of keypresses to an application. This sends a specified
"string" of keys one at a time, where the keys are either
standard printable keys
special "interpretable" keys (prefixed by an ^ character)
psion or shift-psion menu hot keys (prefixed by an @ character).
The "S" command results by default in keypreses with the modifiers
set to zero, though this can be overridden by means of another use of
the @ prefix character: @4 means to use Ctrl as the modifier for the
next key in the sequence, and so on (see below for more details).
The following "S" command will have the same effect as the above
sequence of raw keycodes:
S@s^D^D^DQ^C
At first, this might not seem any clearer, but in time you may well
come to appreciate the power of this command.
In this case:
@s means Psion-s (note that @S would mean Shift-Psion-S)
^D means the Down key
Q is not preceded by either ^ or @, so it just means a Q key
^C means the Enter key (C for "Confirm").
The full range of interpretable keys supported by the "S" command are
Up, Down, Left, Right, Home, End, Tab, and Menu - all specified
by their first letter (eg M for Menu, T for Tab)
C for Return, X for Escape, P for PgUp, Q for PgDn
? for the current drive letter (A or I or B or ...), which can be
useful in macros sending keys to drive selectors in dialogs (the
current drive letter is from the drive KMAC was launched from)
+ for Diamond, - for Delete
Y to Yield CPU until all other background and foreground
processes finish all their pending activity
0 to 9 to pause for 0 to 9 seconds (see below), and % to pause
for half a second.
To send a literal ^ character, put ^^, and to send a literal @
character, put @@.
Put @<digit> to force the modifiers for the following key in the
stream to be <digit> (except that if the next key in the stream is of
type @a or @A, the preceding @<digit> just gets ignored - and the
modifiers are set to PSION and SHIFT-PSION in these two cases). Note
one complication here which is that the value of the PSION modifier
is usually 8, but for these purposes it is changed to 1. This is to
allow @5 to specify modifiers CTRL-PSION, which would not be possible
(using only a single digit) if the PSION modifier were 8 as usual.
Timing issues
-------------
Sooner or later a macro will fail to have to same effect when it is
played back as it had when it was recorded. There are several
possible reasons for this and the next few sections in this document
cover some of these. One thing to watch out for, in particular, is
the issue of *timing*, and the general solution to this kind of
problem is to add in one or other kind of "P" ("pause") or "y"
("yield") commands into a macro.
When a macro is being recorded, other processes generally have a
chance to run on the S3a (within the application and outside the
application) at the same time as when keys are being pressed. But
during macro playback, by default the playback takes place at the
highest priority - which may mean that the macro feeds an application
keypresses before the application is ready to receive them.
For example, a macro that tabs out a file selector will in general
need to insert a pause command before continuing to send keys to that
file selector. You'll find you need this if the file selector starts
beeping at you during playback. The reason here is that it can take
the file selector some time to create its file list, but it remains
responsive to keypresses in the meantime. (This is to remain
responsive to keys such as LEFT and RIGHT which will change the
directory being scanned.)
The "P" command takes an optional parameter, which is how many tenths
of a second playback should be suspended before continuing. By
default (ie if no parameter is given), the playback is just suspended
until all other activity in the application has finished. Note that
in either case, the suspension takes place *within the attached
application* (rather than inside KMAC itself).
Note that you can add pause statements inside an "S" command. Thus
S@m^T
P
256 4
can be shortened, effectively, to
S@m^T^0@4^U
and likewise "P10" is equivalent to "S^1", and so on.
Pauses of longer than zero seconds can be particularly effective in
pacing playbacks intended to demonstrate various aspects of some
software (eg in point-of-sales demos).
An alternative to the "P" command is the "y" command, which has a
rather different effect. This pauses KMAC itself, by means of
setting its process priority to one less than that standardly taken
by background processes. As a result, KMAC will only continue
running when *all* foreground and background processes finish
processing all events pending in them. When this happens, the
priority of KMAC is reset to what it was beforehand.
A sequence of macro commands such as
S@m^T
y
256 4
can be rewritten as
S@m^T^Y@4^U
A note on process priorities
----------------------------
By default, KMAC runs at the rather high process priority of 0xa0.
This is higher than the priorities of any of the standard
applications - higher even than Time, which runs at 0x90 (under the
rationale that an alarm due to sound should always interrupt activity
in other processes).
The reason for running KMAC at such a high priority is so that macro
playback can be as quick as possible - without having to wait for the
attached application to redraw itself unnecessarily between each two
keypresses sent to it.
Working round bugs in system code exposed by KMAC macros
--------------------------------------------------------
Certain macros that you write may expose some shortcomings in the S3a
system code. Ordinarily, these shortcomings do not matter, since the
system software is never normally exercised quite so intensively as
during macro playback. However, some of these problems may
occasionally cause frustration during macro playback - and can even
cause applications to "panic", with loss of data that has not yet
been saved to file.
For this reason, you should always save your data before playing back
a new keyboard macro, until you have confidence in that macro.
One example of a problem you can encounter is in a macro like the
following:
gData.dbf
F
S@m^T
The intention of this macro is to
"go to" the application editing the file "Data.dbf"
make this application foreground
press psion-m to display the "Merge" dialog
press Tab to tab out the file selector
However, if this macro is played back starting from an application
*other* than the specified database, the database panics 73 shortly
after being made foreground. The root cause of this is when an
application becomes foreground when a file selector is showing that
was created when the application was effectively still in background
(and when the file selector hasn't yet finished building its file
list).
In this case, the fix is simple enough: insert a "P" command directly
after the "F" command. This pauses macro playback until all pending
activity within the attached application has been processed. In
particular, the database gets a chance to process the foreground
notification message from the Window Server, prior to going on to
process the keypress messages that cause it to create the file
selector. (Bear in mind that applications process keys from macro
playback at a higher priority than any other input from eg the Window
Server.)
More generally, I try to avoid full-screen file selectors in macro
playback. I prefer to use Control-Tab to jump straight to the
"Specify file list" dialog, and then Control-Enter to jump straight
back to the dialog level, thereby avoiding the full-screen file
selector altogether.
Single stepping macros - the "s" command
----------------------------------------
Inevitably, macros will go wrong for all kinds of reason. To try to
pin down where the blame lies, you can use the "s" command to put your
macro into one of three different "single stepping" states.
By default, all macros operate inside "s0" - which has single
stepping turned off, and thus macro playback proceeds at full speed.
But if the line "s1" is encountered in a macro, the macro will wait
for the user to press Shift-Ctrl-Diamond before each subsequent line
in the macro. This state will continue until either the end of the
macro is reached, or another "s" command is reached. By using "s1"
like this, you can carefully think through what each step in your
macro is doing.
Occasionally, you may forget that KMAC is still waiting for a
Shift-Ctrl-Diamond keypress before being able to do anything else.
But if this happens, and you try to do something else with KMAC, you
will see a notifier explaining the situation.
As an alternative to "s1", you may find "s2" especially useful. In
addition to waiting for the user to press Shift-Ctrl-Diamond in
between each step of the macro, this mode also displays a notifier
containing the text of the line about to be played back, which the
user has to acknowledge by pressing Esc, before the line is actually
processed.
Bear in mind, however, that single stepping can alter the "timing"
features of macros, and therefore can affect their performance.
Waiting for user synchronisation during macros
----------------------------------------------
In some macros, you may wish to pause indefinitely between two lines
of the macro - not for any reason of "debugging", but instead to
allow the user to interact directly with the application before
allowing the macro to continue.
This can be achieved by an "s1" command followed immediately
afterwards by an "s0" command. The macro pauses when it reaches
"s1", and then waits for the user to press Shift-Ctrl-Diamond before
proceeding. In the meantime, the user can type any additional
specific keys.
The single command "n" (the "nudge" command) can be used as an
alternative to "s1" followed by "s0". The effect is exactly the
same.
Keyboard macros and Opl or Hwif applications
--------------------------------------------
Note that KMAC cannot interact with any application written in Opl or
in Hwif. You can only record or playback macros for applications
written using the HWIM object-oriented system. If you try to invoke
KMAC with regard to an application not written using HWIM, KMAC will
present an error notifier.
This is a fundamental limitation of Opl and Hwif applications and
there is no prospect that a future version of KMAC for the S3a will
remove this limitation. For much the same reason, KMAC cannot
operate on an S3 - only on an S3a.
One consequence of this is that some macros will fail, when you
attempt to invoke them from an Opl or Hwif program. Consider again
the "Set keyclick loud" macro:
MACRO Set keyclick loud
KEY L
QUIET
CONTENTS
gSystem
627 8, 257, 257, 257, 108, 13
f
IKeyclick set to loud
By default, this macro starts the same as all macros do, by
attempting to attach to the current foreground process. However, for
this particular macro, this step is unnecessary. Better, therefore,
to add in the keyword "BACKGROUND" in the header of the macro:
MACRO Set keyclick loud
KEY L
QUIET
BACKGROUND
CONTENTS
gSystem
627 8, 257, 257, 257, 108, 13
f
IKeyclick set to loud
This has the effect of letting the macro run at least as far as the
"f" line before it fails. It therefore succeeds in its main purpose,
although it is unable to display an info message at the end to
announce its success.
If you wished to avoid the final error message, you could use the "q"
command (the "query attachable" command) to find out whether it is
possible to attach to the current foreground process. Like the "Q"
command discussed earlier, this sets the "d-variable", that can be
tested eg by a subsequent "x" command. Thus the macro becomes
MACRO Set keyclick loud
KEY L
QUIET
BACKGROUND
CONTENTS
gSystem
627 8, 257, 257, 257, 108, 13
q
xd0
f
IKeyclick set to loud
(q sets the d-variable to 1 if the foreground process is attachable,
and otherwise to 0). The macro only proceeds to its final two lines
if the current foreground process is attachable.
Taking commands from additional .KMA files
------------------------------------------
Several different KMAC commands allow commands to be read from an
auxiliary .KMA file, instead of from the main one loaded into KMAC on
startup.
In each case, the "script" file has the same basic format as the
CONTENTS section of an individual macro definition. For example, the
contents of a file "Delrec.kma" could be the lines
8
P
J2
x
SY
m0
(see later for the meanings of all the commands in this particular
script file) - the same mixture of raw keycodes ("8" being the
keycode for Delete) and alphabetic commands as could belong in the
CONTENTS section of any macro definition.
One way of causing macro control to transfer to a specified script is
by using the "l" (or "Launch script") command. Thus the command
lDelrec
will have the effect of launching the script file "Delrec.kma" from
the same directory as the current top-level KMA file is in. (Specify
the full pathname and/or extension to look in a different place.)
Once control has been transferred to a script like this, it remains
there until it is "returned", using the "r" command. In the
meantime, it is possible for the entire playback to be terminated,
using the "x" ("exit") command.
In addition to the "l" command, there are two other commands that can
cause a script file to be launched: the "d" (or "divert") command,
and the "e" (or "on Error") command.
The "divert" command
--------------------
The "d" command attempts to divert control to a script whose name is
formed from a specified string, together with up to one of the
following "names":
if "%d" is present in the specified string, this gets replaced
by the current value of the d-variable
if "%s" is present, this gets replaced by the "status name" (up to
the extension) of the attached application
if "%f" is present, this gets replaced by the "family name" (or
"alias name") of the attached application
if "%p" is present, this gets replaced by the "process name" of
the attached application.
Eg "dA%f" will look for a script file "Aprog.kma" in the case of the
attached process being the program editor, whereas "dA%p" will look
for a script file "Aword.kma". (On a technical note, the "status
name" is taken from DatStatusNamePtr, the "family name" is taken from
DatProcessNamePtr, and the "process name" is taken from
DatCommandPtr. These three "names" appear in various different KMAC
commands.)
If the script filename specified by a "d" command does not exist,
macro playback simply passes onto the next line of the macro.
The "on error" command
----------------------
The "e" command (the "on error" command) can be used to take
corrective action if an error arises in a particular line in a macro.
In case an error arises, control is diverted to the script specified
in the "e" command.
For example, the sequence of commands
eStartDbf
gLOC::M:\DAT\KMAC.DBF
F
614 8, 27, 9
lDelrec
C
has the following effect:
1. The script name "StartDbf" is lodged as the current error-handler
2. The full form of the "goto" command is used to try to go to the
application editing the specified full path name
3. If such an application exists, the macro passes immediately onto
the next line in the main script - the "F" command
4. Otherwise, control passes to the script file "StartDbf.kma"
instead, and only passes to the "F" command (if ever) when an "r"
command is encountered in "StartDbf.kma".
Some advantages of using script files
-------------------------------------
Some advantages of using script files should be pointed out:
1. They cut down the amount of memory overhead required when running
KMAC. Only the commands in the top-level script are loaded
permanently into memory.
2. Macro details in scripts can be changed without having to exit and
restart KMAC before these changes become effective.
3. Using the "divert" command, more than 26 different macros can, in
effect, be assigned hotkeys. Thus the effect of Shift-Ctrl-A while
in the Program Editor might be quite different (on account of using
the "d" command) from in the Agenda.
4. Scripts can play a very useful role in "error recovery" - as
illustrated above.
5. Scripts can play a very useful role in other "test, jump, and
move" situations - as is discussed below.
Starting applications during macro playback
-------------------------------------------
In the above example, the script file "StartDbf.kma" has to arrange
for the Database application to be running and editing the file
"M:\DAT\Kmac.dbf". This can be arranged by use of the two commands
"c" (set the "command line") and "p" (the "program start" command).
In fact the actual contents of "StartDbf.kma" would be as follows:
cOData#.DBF#LOC::M:\DAT\KMAC.DBF#
pROM::DATA.APP
For a full understanding of this use of the "c" command, you need to
understand about the format of command lines passed to applications
on the S3a. Briefly, there are five portions to such a command line:
1. The very first letter is either 'O' (to "Open" an existing file)
or 'C' (to "Create" a new file with a specified name)
2. Immediately following this comes a zero-terminated string given
the "family name" to be used (note: case is sensitive here) - in fact
the operation of the KMAC "c" command turns all hash ('#') characters
into zeroes
3. After the zero, and up to the next zero or up to the first
full-stop (whichever comes first) is the "alias info" to be used
(this is NULL in the above example)
4. If the alias info was terminated by a full-stop, the text from the
full-stop to the next zero gives the "default extension" to be used
by the application
5. Finally, the full path name of the file to be opened or created
must be passed (and it is important not to omit the final zero).
What the KMAC "c" command actually does is to store the given text,
so that subsequent commands (such as the "p" or "i" commands) can
access it. As mentioned, all hash characters in the specified string
are converted into zeroes before the text is stored.
The KMAC "p" command attempts to launch the specified program name
(the "ROM::" specifies that the program is to be found in the ROM of
the S3a), using the command line stored by the previous "c" command.
If successful, KMAC attaches to this application.
Ways of attaching to programs
-----------------------------
The "p" command (the "program start" command), just discussed, is one
method for attaching KMAC to a specified application. Another
method, also discussed earlier, is the "g" command (the "go to"
command).
There are actually two forms of the "g" command - the "short form"
and the "long form". The distinction is that the "long form" is used
whenever a colon or a backslash is found in the filename specified.
In the long form of the "go to" command, KMAC searches for a process
which has the given full pathname stored at its "DatUsedPathNamePtr".
But in the short form, KMAC only searches for a process which has the
given short-form filename at its "DatStatusNamePtr". Clearly, the
long form is more exact, but the short form will suffice in most
practical cases. (Also, the long form cannot be used for
applications that are not file-based.)
Yet another way of attaching to a process is to use the "a" (or
"attach") command. This works rather differently, treating the
specified string as a "process name identifier". Examples of the use
of "a" would be "aSYS$SHLL.*" or "aWORD.*". ("SYS$SHLL is the name
of the program which users see as the "System Screen".)
Conditional and unconditional exit and return commands
------------------------------------------------------
Mention has already been made of the "r" ("return") and "x" ("exit")
commands. Each of these exist in both unconditional and conditional
forms. Thus the single letter on its own always causes a return or
an exit to take place. However, either letter can be followed with
any of the following four sub-cases:
d - means to return (or exit) if the current value of the
d-variable is less than or equal to the given number (usually used in
"xd0" or "rd0")
p - means to return if the "process name" of the attached process
(read from DatCommandPtr) differs from the string given - eg "xpWORD"
would mean to exit playback unless the attached process was an
instance of the Word Processor
f - means to return if the "family name" of the attached process
(read from DatProcessNamePtr) differs from the string given - eg
"xfPROG" would mean to exit playback unless the attached process was
actually the Program Editor
s - means to return if the "status name" of the attached process
(read from DatStatusNamePtr) differs from the string given - eg
"xsTEST.OPL" would mean to exit playback unless the attached process
was editing a file called "TEST.OPL").
In all cases of the various "names" of the attached process, case is
not sensitive. Thus "xfPROG" and "xfProg" would be identical.
Jumps and moves and tests during macro playback
-----------------------------------------------
The "d", "e", "r", and "x" commands already discussed give various
measures of control over what exactly happens during macro playback.
This section introduces the very important "m", "j", and "J"
commands.
The "m" (or "move") command causes the focus of control to move
inside the current script (or top-level macro definition). If no
additional parameter is given, playback moves past the next command,
skipping it altogether. If an additional parameter is given that is
positive - eg "m3" - the specified number of steps are skipped.
Finally, the command "m0" has the special meaning of rewinding to the
beginning of the current script (or if control is currently in the
top level macro definition, to the beginning of that definition) and
proceeding forwards again from there.
The "j" (or "jump depending on number of dialogs shown") command
allows the macro to count the number of dialogs shown on the screen
of the attached process, and to move past a specified number of steps
depending on this number. The general syntax of the "j" command is
"jm,n", where <n> defaults to 1 and can be omitted, and (also like
the case of the "m" command) can be given as 0, in which case macro
control can rewind to the beginning of the current script or
top-level macro definition. If <m> is positive, the jump is taken if
the number of dialogs shown exceeds m, whereas if <m> is negative,
the jump is taken if the number of dialogs shown is less than (-m).
The "J" command (or "Jump on general condition" command) works very
similar to the "j" command, except that the set of conditions tested
is very general.
For example, the "J2" command in the "Delrec" script given earlier
has the effect of skipping over the next line in the script (actually
an "exit" command) if a dialog is showing on the screen - this is
because the "general status info" of the attached application
contains the value 2 if a dialog is showing. (See the following
section for more details.)
The "J2" command in "Delrec" could in fact be replaced by "j0" in
this case.
The precise syntax of the "J" command is "Jm,n" where <n> has exactly
the same meaning as for "j" (and for "m"). The jump is taken, for
positive <m>, if the "status info" of the attached process, ANDed
with m, is non-zero. If <m> is negative, the jump is taken if the
corresponding AND value is zero.
General status info for the attached process
--------------------------------------------
Bits are set in the "general status info" of the attached process as
follows:
1 is set if a menu is showing
2 is set if a dialog is showing
4 is set if the application is "locked" (ie would report as
"busy" in the System Screen)
8 is set if the application has a keyboard filter active
16 is set if the application has a non-negative i/o semaphore
value (meaning that there is pending activity in the application)
32 is set if the application has called am_start more than once
(meaning that it is in some kind of modal state).
A full explanation of all these terms is beyond the scope of the
present documentation. (The various bits all indicate some kind of
pending activity that it might be better not to interrupt.)
Synchronisation issues with regard to tests
-------------------------------------------
Note that the above "Delrec" script contains the line "P" prior to
making the "J" test. This is important. Otherwise the wrong result
would be obtained. The point is that although the effect of the
previous line in the macro - sending the Delete key - would be to
bring up a "Delete?" query dialog in due course, the "J" test could
be carried out before that dialog was actually created.
The KMAC expression evaluator
-----------------------------
One more aspect of the "names" feature of KMAC deserves explicit
mention. This is used in the "E" (or "Expression evaluate")
command. Despite its name, this command has no scope for evaluating
numerical expressions. Instead, the allowed contents of the
expression to be evaluated are the familiar "names" identifiers "%p",
"%f", and "%s". It turns out that this can be very useful.
The string evaluated in this way is sent to the attached process as a
string of keys.
For example, the command "E%s.txt" would send the string of keys
"Notes.txt" when the file being edited is "Notes.wrd", and would send
the string of keys "Memo.txt" when the file being edited is
"Memo.wrd". This could be exactly the right thing to type into a
filename editor line of a "Save as" dialog in an application.
Transferring control to Opl programs
------------------------------------
Although there is a wide range of control features available to KMAC
programs, some macros may demand additional data manipulation or
tests to be carried out. For this reason, KMAC supports the notion
of launching an Opl program, which can then use many of the features
of KMAC in its own right.
The way this works is that the functionality of KMAC has actually
been split into two different pieces of code. Script file handling
and background key capture, etc, is handled by code in KMAC.APP
itself, but most of the logic for implementing playback is located in
LPC.DYL. The logic in LPC.DYL has been designed in such a way as to
make it accessible from an Opl program as well.
For further details of Opl programs that can use LPC, see the text
file OPLLPC.TXT.
Miscellaneous KMAC commands
---------------------------
For a summary of all the possible alphabetic commands recognised by
KMAC, see the database file KMAC.DBF.
A few features not mentioned so far can be pointed out:
There are "k" ("kill"), "t" ("terminate"), and "C" ("closedown")
commands, which provide various means of exiting the current attached
application.
There is an "i" command, to start a specified utility application,
without any attempt to attach to it. (This uses, for its command
line, anything set up by a prior "c" command.)
There is an "A" command, to cause the attached process to display
"alloc heap information", which can be very useful during program
development (to monitor possible memory leakage).
There is a "B" command, to send the attached program into background.
There is a "v" command, to remember the PID of the current attached
process, and a "u" ("use") command, to attach back to the process
whose PID was remembered earlier.
There is an "H" ("Hook DYL") command, to cause the attached process
to hook a specified DYL (see elsewhere for information on how to
write such a DYL, and for examples of the use of this command). There
is also an "h" command, to cause KMAC itself to hook a specified DYL.
Finally, there is an "o" command, to start a specified Opl program -
eg "o\OPO\TKMACLIB.OPO" - and a "w" command, to wait for the
completion of the Opl program last launched using an "o" command (or
for the completion of the image program last launched using an "i"
command).
Review of the macros in EG.KMA
------------------------------
See the text file EGKMA.TXT for a discussion of the example macros
contained in the file EG.KMA.
These notes prepared by
-----------------------
David Wood, Psion Product Development, 25th April 1994.