Uma

Useful Macros (Version 1.1) Documentation ========================================= What is Useful Macros? ~~~~~~~~~~~~~~~~~~~~~~ Useful Macros is a program that will record and playback key sequences on your PC. Keyboard macros allow you to speed up your work by reducing the number of keystrokes required to perform complex or repetitive tasks. Useful Macros allows you to assign a sequence of keystrokes to one key or key combination. This one key to many keys relationship is called a "macro". Almost any key can be redefined to perform one or more commands. If you were required to use a character string frequently (say the name of your company), you could create a macro that "plays back" that character string at the touch of a single key. You can also create macros that automatically play back at the start of an application. Frequently used macros can be saved to and loaded from disk files. Macros are easy to create. With Useful Macros you can record a series of keystrokes from within your application. When you have finished recording, that macro is immediately available for use. Another way you can generate macros is to create a "macro definition" file with any ASCII text editor (hopefully Useful Editor). Utility programs to convert "macro files" to and from text files are included with the Useful Macros package. Macros are easy to play back. When you press a macro's "hot key" (the key to which the macro has been assigned) each keystroke, command, or instruction is carried out (starting at the current cursor position) just as if you typed them yourself. With Useful Macros another way to invoke a macro is to type the first few keys of any macro then press the "macro completion" key. In either case after the macro has run, you can resume working in the application as you normally would. Features ~~~~~~~~ Useful Macros (Uma) is a small (about 15K) keyboard macro program for IBM PCs and compatibles. Some of Uma's features include: -

run as a TSR or from the command line record and playback keystrokes or use pre-defined macro scripts macro completion support for enhanced keyboards macros can be synchronized with screen events macro files can be loaded and saved "on-the-fly" autostart macro when program loads optionally record the delays between keystrokes optionally record changes to the shift key status macro files can be up to 64K in size easy to use consistent interface user configurable preferences

System Requirements ~~~~~~~~~~~~~~~~~~~ Uma the its are -

runs on any IBM PC or compatible. Uma automatically determines type of video card installed and uses the current text mode for menu. The following video cards (or ones that are compatible) supported: Color Graphics Adapter (CGA) Monochrome Graphics Adapter (MGA) Hercules Graphics Adapter (HGA) Enhanced Graphics Adapter (EGA) Video Graphics Array (VGA) Multi-Color Graphics Array (MCGA)

Any monitor that can display text works with Uma. If you have a color monitor and card, you can change the default colors by running umacfg.exe (see Configuring Uma). In addition Uma supports a 43 line display on EGA systems and a 28 or 50 line display on VGA systems. Uma is very small and runs on systems with as little as 128K of memory. Of course the more memory that you have, the larger the macro files that you are able to work with (up to 64K). Starting Up Uma ~~~~~~~~~~~~~~~ There are two versions of Useful Macros. UMARES will load itself and an associated "macro" file into memory as a "terminate and stay resident" program (TSR). To run Umares, from the DOS prompt, type: umares [<macrofile[.uma]>] then press the Enter key. From this point on, any keyboard macro defined in the "macrofile" will be available to you. To remove Umares from memory you must restart your system. UMARUN can be used to execute another application with an associated "macro" file. To run Umarun, from the DOS prompt, type: umarun <macrofile[.uma]> [<parm1> <parm2>...<parmn>] then press the Enter key. The parms above are the application's (if any) just as you would type them in at the DOS prompt. As long as you remain in the application you will have access to the macros defined in "macrofile.uma". When you exit the application, Umarun will remove itself and the macro file from memory. For both versions if you do not specify an extension on the macrofile name, Uma will assume ".uma".

NOTE: If you already have UMARES in memory it will take override UMARUN.

Command Line Options ~~~~~~~~~~~~~~~~~~~~ There are a number of command line parameters that can be used when running either Umares or Umarun. /A - When this option is used, Uma will immediately "play back" (Auto the FIRST macro found in the macro file. Start) /Bnnnn - Specifies the amount of memory (in characters) to set aside (Buffer for macro files. If this option is omitted, Useful Macros Size) will set aside enough memory to load the macro file plus enough to record about 250 additional keystrokes. In the case of Umares, if /B is not used and there is no macro file, only the 250 key "recording buffer" will be allocated. /D - Instructs Useful Macros to record the delays between (Delay) keystrokes. When you play back a macro recorded in this manner, the keys will appear at the same speed that you typed them in. /E

- Enable extended keyboard services. If you have a newer machine, you will need to set this switch to use the F11, F12, and other extended keys on your keyboard.

/F - Most applications ask the PC's BIOS service routines if a key (Force) has been typed then make a subsequent request for that key if there is one. Think of this as "on demand". Some applications however, "look" directly at the PC's keyboard buffer for keystrokes and "grab" them from the buffer when they appear. Uma defaults to "on demand" mode feeding the applications keys when they are requested. The /F command line option can be used to "force" keys directly into the keyboard buffer where they can be "seen" by the second type of application. If your application does not work in the default mode try the /f option.

Command Line Options (continued) ~~~~~~~~~~~~~~~~~~~~ /S - Instructs Useful Macros to record any changes to the status (Shift of the shift keys (Ctrl, Alt, Left Shift, and Right Shift). Change) EXAMPLES: umares mymacros - Loads Uma and the file "mymacros.uma" permanently into memory with enough extra space to record an additional 250 keys. umarun /b5000 /f cmacros /a ued myfile.c - Loads Uma and the file "cmacros.uma" and then runs the program Ued and passes to it the file name myfile.c. Enough room for about 2500 keystrokes has been set aside. The free space for recording additional keystrokes would be 2500 minus the number of keys in the "cmacros.uma" file. Useful Macros will "force" keys directly into the keyboard buffer and automatically "play back" the first macro from "cmacros.uma". When you quit Ued, Useful Macros will remove itself and the macro file from memory.

Using Uma ~~~~~~~~~ Once Useful Macros has been loaded into memory, you can access the Uma menu by pressing Ctrl-Alt-M (the Ctrl, Alt, and M keys at the same time). You should see the line: Pause

Record

Clear

Load

Save

Useful Macros v1.0

appear at the top of your screen. To "hide" the menu and return to your application press the Esc key. Press the first letter of any command (P,R,C,L,S for the main menu) to invoke that command. The commands are: Pause

- Temporarily suspend the current operation. If you were recording a macro, any keys pressed while "paused" will not be added to the macro buffer. Similarly Pause can be used to suspend the "play back" of a macro. If Pause is invoked at any other time, macro "hot keys" and command completion are temporarily disabled. When the Pause key is pressed you are immediately returned to your application. You must "pop up" the menu again to resume.

Resume - When Useful Macros has been "Paused" the menu will have only one option; P Resume

Status: PAUSED

Press P to resume whatever operation was in effect prior to pausing. Record - Start recording a new macro. You will be prompted for a key to bind the macro to. This "hot key" can be used to "run" the macro at a later time. Once you assign a key, you are immediately returned to your application and recording. You must "pop up" the menu again when you are done. While Useful Macros is "Recording" the only options on the menu will be: Pause

Stop

Status: RECORDING

Pause is as described above. Stop is used to end the macro recording session. Once stopped, the macro you just recorded will be available for use by pressing it's "hot key". Clear

- Clear can be used to erase an existing macro. You will be prompted for the "hot key" of the macro to erase.

Load

- Use the load command to switch to another macro file. You will be prompted for the name of the macro file to load. There must be enough memory set aside when you started up Uma to load the new macro file or you will get an error. The new file is loaded on top of the old file.

Save

- Save is used to save the macros currently in memory to a disk

file. You will be prompted for the disk file name. If you do not include an extension on the file name, ".uma" will be added.

While Running Uma ~~~~~~~~~~~~~~~~~ Here are some other things you should know about running Uma. You can use the Alt+ (Alt and + keys together) as a shortcut to start the Recording of a macro. It's as though you popped up the Uma menu then pressed the R key. Similarly you can use Alt- to stop recording a macro. When you are "playing back" a macros, you can press the Esc key at any time to immediately stop the playback. If the internal buffer becomes full while recording, Useful Macros will "beep" each time you press a key. You should stop the recording, save the macros already recorded to a file, and reload Uma and the macro file with a larger buffer (using the /b command line argument). When a key definition for a "hot key" appears in a macro, the key and NOT the macro it represents will be played back. If you need to use a key that has been defined as a "hot key" (even Ctrl-Alt-M) when Useful Macros is active you can: 1) Temporarily disable Uma by Pausing (Ctrl-Alt-M then P), type the key, then Resume (Ctrl-Alt-M then P again). 2) Enter the key by holding down the Alt key and typing in its "key number" on the keypad. Macro Completion ~~~~~~~~~~~~~~~~ When a macro file has been loaded, the macros within can be run by pressing their "hot keys", or by using macro completion. The ` key (single back quote) is used to invoke macro completion. When ` is pressed Useful Macros looks at the text in front of the current cursor position (up to 10 characters worth by default) and tries to match that text against the beginnings of all of the macros currently in memory. If a match is found, the macro is "completed" as though the "hot key" had been pressed. Useful Macros will look for the best match; the one with the MOST matching characters. If two macros match equally well, the one which appears first in the macro file will be completed. To generate the

`

itself in your text file you can:

1) Temporarily disable Uma by Pausing (Ctrl-Alt-M then P). 2) Enter

`

by holding down the Alt key and typing 096 on the keypad.

Creating Macro Files ~~~~~~~~~~~~~~~~~~~~ There are a couple of ways to create a macro file. The easiest way would be to run Umares with a big enough buffer to store all of the macros you want to create. Each keystroke requires 2 characters in the buffer. For example: umares /b1000 would allocate enough memory to record about 500 keystrokes. Using the Record command, create the macro definitions. Save command to copy the definitions to a disk file.

Then use the

Another way to create a macro file is to start with a text description of the macros. A utility program, "TXT2UMA" has been provided to convert properly formatted text files (macro definitions) into macro files. A macro definition file might look something like this: A macro to type out 2 lines of text. Macro:<Shift F1> This is line one.<Enter> This is line two.<Enter> Endmacro A macro to type out column headings. Macro:<Shift F2> Column1Column2Column3<Enter><Enter> Endmacro Any text "outside of" the Macro: and Endmacro lines will be treated as comments. The Macro and Endmacro statements must start in column 1 and leading spaces between these two lines will be treated as part of the macro itself. If the above text file were named "mymacros.txt", the following command line: txt2uma mymacros would create a macro file "mymacros.uma" (with the .txt file unchanged). If you want to alter an existing macro file, the utility "UMA2TXT" will convert it into a text file that can be edited with any text editor (like Useful Editor). To convert the macro file "mymacros.uma" into an editable text file the the following command line: uma2txt mymacros can be used to create the text file "mymacros.txt".

The next 2 sections list the Key Definitions and Key Commands that can be used in a "macro definition" text file.

Key Definitions ~~~~~~~~~~~~~~~ The following key definitions can be used when creating a Macro text file. # # # # # #

#

(SOH) (STX) (ETX) (EOT) (ENQ) (ACK) (BEL) (BS) (TAB) (LF) (VT) (FF) (CR) (SO) (SI) (DLE) (DC1) (DC2) (DC3) (DC4) (NAK) (SYN) (ETB) (CAN)

# # # # # # # # # (SUB) (ESC) # (FS) # (GS) # (RS) # (US) (SP) ! " # $ % & ' ( ) * + , . / 0 1

5 6 7 8 9 : ; < = > ? @ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z [ \ ] ^ _ ` a b c d e

i j k l m n o p q r s t u v w x y z { | } ~  � � � � � � � � � � � � � � � � � � � � � � � � � �

� � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � �

� � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � �

(255)

2 3 4

f g h

� � �

� � �

Key Definitions (Continued) ~~~~~~~~~~~~~~~
' rel="nofollow"> ,> -> .> / NumPad> /> 0> 1> 2> 3> 4> 5> 6> 7> 8> 9> ;> => a> b> Backspace> c> d> e> Enter NumPad> Enter> F10> F11> F12> F1> F2> F3> F4> F5> F6> F7> F8> F9> f> g> Gray *> Gray +> Gray -> Gray Delete> Gray Down Arrow> Gray End> Gray Home> Gray Insert> Gray Left Arrow> Gray Page Down> Gray Page Up> Gray Right Arrow>



<End> <Enter NumPad> <Enter> <Esc>


Gray Up Arrow rel="nofollow"> h> i> j>


F7> F8> F9> f>



Key Definitions (Continued) ~~~~~~~~~~~~~~~ <Shift . NumPad> <Shift 0 NumPad> <Shift 1 NumPad> <Shift 2 NumPad> <Shift 3 NumPad> <Shift 4 NumPad> <Shift 5 NumPad> <Shift 6 NumPad> <Shift 7 NumPad> <Shift 8 NumPad> <Shift 9 NumPad> <Shift Backspace> <Shift Enter NumPad> <Shift Enter> <Shift Esc> <Shift F10> <Shift F11> <Shift F12> <Shift F1> <Shift F2> <Shift F3> <Shift F4> <Shift F4>

<Shift F9> <Shift Gray +> <Shift Gray -> <Shift Gray /> <Shift Gray Delete> <Shift Gray Down Arrow> <Shift Gray End> <Shift Gray Home> <Shift Gray Insert> <Shift Gray Left Arrow> <Shift Gray Page Down> <Shift Gray Page Up> <Shift Gray Right Arrow> <Shift Gray Up Arrow> <Shift Key 45 [5]> <Shift Space> <Space> **** for the HP95 only **** <Setup> <Appt> <Memo> <123> <+-*/> <Menu> <Shift Menu> ***************************�

<Shift <Shift <Shift <Shift

F5> F6> F7> F8>

Key Commands ~~~~~~~~~~~~ In addition to the above key definitions the following key commands are supported by Useful Macros:

- When this command is encountered within a macro, Uma will simulate and empty keyboard buffer. This is necessary for some applications that periodically "flush" the keyboard buffer. Can also be used as a "hot key" if the Macro definition will only be used in "macro completion" mode. You cannot "Clear" a macro that has for a "hot key".



- Delay for "n" tics before playing back the next key. A tic is the "heartbeat" unit of time used by PCs and is about 1/18 of a second.

- Delay for "n" tics after playing back each key. This command can be used to "pace" the playback of keystrokes or can be helpful for debugging purposes. You can disable by specifying a value of 0 for "n". <Pause>

- Pause the playback until ANY key is pressed.

<Pause Until:n>... - Pause the playback until ONE of the "n" keys that follow are pressed. All other keys pressed are passed through to the application. - Do a screen dump of the current screen.

Key Commands (Continued) ~~~~~~~~~~~~

- Change the shift status to simulate an Alt key being pressed.



- Change the shift status to simulate a Ctrl key being pressed.

- Change the shift status to simulate a Left Shift key being pressed. - Change the shift status to simulate a Right Shift key being pressed. <Shift Clear> - Clear the shift status. <Match Screen:row,column,text> - Wait until the "text" appears on the screen at the location specified by "row" and "column". The top row and leftmost column of the screen are 1,1 and columns are assumed to be 80 characters wide. Everything between the second , and the closing > including spaces will be treated as the "text" string to be matched. This feature can be especially useful for applications that clear out the keyboard buffer while waiting for specific events to occur.

A Useful Macros Example ~~~~~~~~~~~~~~~~~~~~~~~ If you want to give Useful Macros a test drive, you might try the file "mkmacro.uma". This is a macro file to help you make macro definition files. Here's what to do. 1) Type in the following command at the DOS prompt: umarun mkmacro In other words have Umarun load the macro file "mkmacro.uma" then run your favorite text editor. 2) Type the letters ma then press the ` (single back quote) key. You should see the letters ma replaced with the word Macro: . The ` key you will recall is the "macro completion" key. 3) Now select a "hot key", say Shift F1. When you press the key you will notice that it's full text description is typed. If you choose Shift F1 you should see the line Macro:<Shift F1> . 4) Press the Enter key to advance to the next line. Notice that the definition <Enter> is NOT typed. For the convenience of editing the text, the Enter and Backspace keys are not mapped to their key definitions in "mkmacro". You can however generate an <Enter> by typing en then pressing the "completion" key (`). Likewise a can be generated by using the bs short form. 5) Type in the body of the macro. Regular text keys (alpha, digits, and punctuation) appear as typed. Special keys (functions, cursor controls, and editing) generate their text key definitions. If you want to enter a key command, you can use one of the following short forms (along with the "macro completion" feature): nk - de - The macro will wait after the : is typed for you to key in the delay time (1-255) then press Enter. pa - <Pause> pu - <Pause Until:n> The macro will wait after the : is typed for you to key in number of keys to pause for (1-255) then press Enter. ps - sc - <Shift Clear> al - ct - ls - rs - ma - Macro: em - Endmacro 6) When you are done, use the em short form to end the macro. Remember the Endmacro must appear at the beginning of a seperate line.

7) Try playing back the macro you have created. You might want to look at the file "mkmacro.txt" to see how the "short forms" and other macros above were created.

Configuring Uma ~~~~~~~~~~~~~~~ A separate program (umacfg.exe) is provided to modify Umares and/or Umarun with some of your own preferences. When you run this Uma Configuration, you must ensure that Umares.exe and/or Umarun.exe are in the current directory. Follow the prompts for the configuration program. When you have answered the last question the executable(s) will be updated with your selections. The following user preferences can be configured within Uma: -

video display mode (snowchecked or not) color of normal text color of inverse text number of characters to check for macro completion

Licensing ~~~~~~~~~ The programs and documentation in this archive are Copyright (c) 1991-92 by Useful Software Uma is a shareware keyboard utility. This means that you only pay for it if you decide to continue using it. If you don't think that it is worth the asking price, delete the program, or better yet give it to someone who might find it useful. However if you do decide to keep Uma after a 2 week trial period, please send $10 (see REGISTRATION FORM on next page) to: Useful Software 340 Dale Crescent Waterloo, Ontario Canada, N2J 3Y3 The shareware fee pays for unlimited use of Uma by a single person. You are allowed (and encouraged) to give away copies of Uma with the understanding that each person receiving a copy is under the same obligation as you are to send in the shareware fee if they decide to keep it. You can upload THIS VERSION ONLY of Uma to other computer systems, either free or commercial, as long as this archive remains intact, with the copyright and shareware notices unchanged. Useful Macros can be installed on LANS. In such situations I ask only that the LAN Administrator estimate the maximum number of people that will be making "simultaneous" use of Uma and pay the shareware fee based on that estimate. I do not expect that the limit be closely monitored or enforced (I appreciate how much trouble that would be), but I do expect that the estimate will be revised (and additional fees paid) should a substantial increase in the number of nodes on the LAN and Uma usage occur. No guarantee is made as to the functionality of this software; however it has been tested quite thoroughly by a large number of people. If it doesn't do what you want, don't keep it and send no money. Please support the shareware concept. Shareware means useful programs at a fraction of the cost you might pay for them commercially. You can try-before-you-buy, and you are not subjected to copy protection or other atrocities that many software vendors inflict on their customers. Software updates can also be distributed much faster than is possible through normal channels. Any questions, suggestions, or bug reports, can be mailed to the above address, or send electronic mail to: GEnie: CompuServe: Enjoy,

M.GARDI 70242,3102

Useful Software

Registration Information (What do I get if I register!) ~~~~~~~~~~~~~~~~~~~~~~~~ All registered users of Useful Macros will receive one update with the most recent version of the program. Subsequent updates are available for $3.00 shipping and handling on request. In addition you will receive the latest versions of other Useful Software products for your consideration. Registered users will have access to the Useful Software Support BBS, and telephone support. Discounts are available if you register Useful Macros along with other Useful Software products (see price schedule below). If you are already a registered user of another Useful Software product, pay only $5.00 to register Useful Macros. Useful Macros Price Schedule ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1-99 100+

copies copies

- $10 per copy - One time fee of $1000

With each purchased copy of Useful Editor or Useful Notes, the price for a copy of Useful Macros is only $5.00. Useful Editor or Notes Price Schedule ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1-9 10-49 50-99 100+

copies copies copies copies

-

$20 $15 $10 One

per copy per copy per copy time fee of $1000

Useful Editor/Notes Bundled Price Schedule ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1-9 10-49 50-99 100+

copies copies copies copies

-

$30 $25 $15 One

per bundle per bundle per bundle time fee of $1500

Printed Documentation ~~~~~~~~~~~~~~~~~~~~~ Printed copies of the documentation are available for all Useful Software products at a cost of $5.00/copy.

REGISTRATION FORM (English Uma) ================= TO:

FROM:

Useful Software 340 Dale Crescent Waterloo, Ontario Canada, N2J 3Y3

Name: ___________________________________ (Company): ___________________________________ (Title): ___________________________________ Address: ___________________________________ City,State: ___________________________________ (Prov.) Telephone: ___________________________________

I AM ALREADY USING: Useful Editor Version ___.___ Useful Notes

Version ___.___

Useful Macros Version ___.___ I WOULD LIKE TO REGISTER: ____ copies of Useful Macros V1.1

X

$______ per copy = $________

____ copies of Useful Editor V1.9d

X

$______ per copy = $________

____ copies of Useful Notes

X

$______ per copy = $________

V1.4

I WOULD ALSO LIKE TO RECEIVE: ____ printed copies of the Macros documentation X $5.00 = $________ ____ printed copies of the Editor documentation X $5.00 = $________ ____ printed copies of the Notes

documentation X $5.00 = $________ TOTAL ENCLOSED = $ ========

Signature: ____________________________________

Update Log ~~~~~~~~~~ The following changes were made in Version 1.1 - added command - modified the command to simulate an empty keyboard buffer - added support for keys generated via the Alt-keypad (ie. keys with a scan code of 0) - fixed an infrequent "hanging" problem with one of the interrupt handlers - fixed a problem with UMARUN thinking there were parameters to the application being run when there were not - UMA2TXT and TXT2UMA now understand extended HP95 keystrokes Planned Enhancements ~~~~~~~~~~~~~~~~~~~~ - add number of keystrokes left in the buffer to the RECORDING status - add "call" and "chain" key commands so that macros can be combined