=================================================================
SHELLMAC.TXT                                             02/14/94
=================================================================

This file documents new changes to macro commands which have 
been introduced since Shell 3.1, the previous version of Shell.  
Some macro commands are new, and others now function differently 
than they did previously.  The final section documents which 
macro commands, although available in Shell 3.1, are not 
supported in Shell 4.0.

All other macro commands should behave the same as they did with
previous versions of Shell.  For more information about macros, 
see Using Shell Macros in the Shell User's Guide.



  {Alt-Shift-*}        This macro command works in a manner 
                       similar to previous versions of Shell.  
                       If no Shell macro by the name exists, 
                       the error message "Error - File not 
                       found:" is displayed.  For example, 
                       playing the command {Alt-Shift-E} when 
                       the macro ALTSHFTE.SHM does not exist will
                       generate the error message.  Shell no 
                       longer tries to hotkey to a program which 
                       has the hotkey assignment {Ctrl-Alt-E}, 
                       as it did in version 3.x.

  {ALT HOTKEY}         If the Hotkey Sequence is set to 
                       "CTRL-ALT, (Letter)" in the Environment 
                       dialog box, then this command can be used 
                       to hotkey to another application.  

                       For example, to hotkey to an application
                       which has a hotkey sequence of 
                       "Ctrl-Alt, w", you would enter the command
                       "{ALT HOTKEY}w." 

                       If the Hotkey Sequence in the Environment
                       dialog box is set to "CTRL-ALT-(Letter)", 
                       the same example displays the Shell 
                       Hotkeys dialog box.

  {Clipboard}          Starts the Screen Copy feature.  Use
                       with {PAUSE} or {PAUSE KEY} to delay 
                       macro execution while the user makes a 
                       selection. 

                       If Shell is not loaded, this command
                       transfers control to the Program of 
                       Choice, and the keystroke Ctrl+Alt+F1 is 
                       executed.  The Program of Choice is 
                       defined as being the first program loaded 
                       by Launcher.  In most cases, this will be 
                       SHELL.EXE, however, it could be anything.  
                       For example, typing MC WP.EXE on the 
                       command line would make WP.EXE the 
                       program of choice.

  {Ctrl-Alt-F6}        If this keystroke is mapped in your
                       application program, this command executes
                       the function associated with Ctrl+Alt+F6.  
                       If this keystroke is not mapped in your
                       application program, the Shell Hotkeys 
                       dialog box is displayed, if Shell is 
                       loaded.

  {Ctrl-Alt-F7}        If this keystroke is mapped in your
                       application program, this command executes
                       the function associated with Ctrl+Alt+F7.  
                       If this keystroke is not mapped in your
                       application program, the Shell Hotkeys 
                       dialog box is displayed, if Shell is 
                       loaded.

  {DISPLAY ON}         Shell will not automatically redisplay 
                       when it receives a {DISPLAY ON} command.
                       You can rewrite the screen by using 
                       Ctrl+F3.

  {EXEC PROG}          This is the same as the {EXEC DOS} command 
  program~             in Shell 3.x.  This command may be 
  parameters~          executed from within another program or 
                       directly from them Shell desktop.

  {File Manager}       Displays the Specify File Manager List 
                       dialog box.  Use with {PAUSE KEY} to delay 
                       macro execution while the user completes a 
                       task. 

                       If Shell is not loaded, this command
                       transfers control to the Program of 
                       Choice, and the keystroke Ctrl+Alt+F5 is 
                       executed.  The Program of Choice is 
                       defined as being the first program loaded 
                       by Launcher.  In most cases, this will be 
                       SHELL.EXE, however, it could be anything.
                       For example, typing MC WP.EXE on the 
                       command line would make WP.EXE the 
                       program of choice.

  {Hotkey List}        Displays the Shell Hotkeys dialog box.  
                       Use with {PAUSE} or {PAUSE KEY} to delay 
                       macro execution while the user makes a 
                       selection.  If Shell is not loaded, this 
                       command transfers control to the Program 
                       of Choice, and the keystroke Ctrl+Alt+F2 
                       is executed.  The Program of Choice is 
                       defined as being the first program loaded 
                       by Launcher.  In most cases, this will be 
                       SHELL.EXE, however, it could be anything.
                       For example, typing MC WP.EXE on the 
                       command line would make WP.EXE the 
                       program of choice.

  {IN MEMORY}umid~     This command checks to see if the program
                       with the indicated Unique Menu IDentifier 
                       is in memory.  If the program is in 
                       memory, one (1) is returned; if not, zero 
                       (0) is returned.  See "Determining UMID 
                       numbers" below for more information on 
                       determining the UMID number for menu 
                       items on your desktop.

  {KTON}               Only valid for WordPerfect 5.1 character 
                       sets

  {MACRO SYSTEM}       The {MACRO SYSTEM} command returns the 
  sysvar~              value of the given Macro Engine system 
                       variable.  These system variables indicate 
                       the current state of the Macro Engine to 
                       the macro. 

                       Valid system variables are listed below.

                       Rather than use the system variable name 
                       in the {MACRO SYSTEM} command, you can 
                       use the number given in parentheses next 
                       to each system variable name below.  
                       Using the number is useful when you want 
                       to use the same macro in different 
                       international versions of Shell.

  Sysvar               Value returned
  ======               ==============

       State (1)       This shows the execution state of the 
                       Macro Engine (see below).
                       Values other than those listed here are
                       undefined.

            1          The Program of Choice is the currently 
                       active program.  The Program of Choice is 
                       defined as being the first program loaded 
                       by Launcher.  In most cases, this will be 
                       SHELL.EXE, however, it could be anything.  
                       For example, typing MC WP.EXE on the 
                       command line would make WP.EXE the program 
                       of choice.

            2          Macro definition is currently active.

            4          Macro execution is currently active (this 
                       is always set while a macro is playing).

            16         The clipboard has data in it.

            32         The clipboard (ELD_CLIP.EXE) is active.

            1024       DOS is the active program (you are at a 
                       DOS prompt).

       CurUMID (3)     This returns the Unique Menu IDentifier 
                       for the currently active program.  The 
                       program must be active, not just resident.
                       See "Determining UMID Numbers" below for 
                       more information.

       TempDir (4)     This returns the path to the temporary
                       directory specified by the /d startup 
                       option.  If the /d startup option was not 
                       used, then the default directory.

       Swap (5)        This returns the Shell swap state.  The
                       values 256, 512, and 1024 denote expanded
                       memory, extended memory, and disk space,
                       respectively.  One or a combination of 
                       these values may be returned, depending on 
                       your system resources. 

                       The values 1, 2, and 4 specify where the
                       current program will be swapped on the 
                       next swap request (expanded memory, 
                       extended memory, or disk, respectively).  
                       Only one of these values will be set at a 
                       time, and may be combined with the values 
                       mentioned above.  For example, if the 
                       value 1028 was returned, then only disk 
                       space is available for swapping, and the 
                       next program to be swapped will be swapped
                       to disk.

       ClipNum (6)     Number of the currently active clipboard
                       (0-79)

       Clipboard       Format of data in the current clipboard 
       (7)             (see below)

            1          ASCII

            2          Binary - no format

            3          WordPerfect 4.2

            4          WordPerfect 5.x

            5          WordPerfect 6.0

            32768      Clipboard (ELD_CLIP.EXE) is resident

       CurDir (8)      Current DOS default directory

       Year (9)        Current DOS year

       Month (10)      Current DOS month.  Inserting the percent
                       symbol (%Month) will pad with a zero (0) 
                       if the value is less than 10.

       DayMonth        Current DOS day of the month.  Inserting
       (11)            the percent symbol (%DayMonth) will pad
                       with a zero (0) if the value is less than
                       10.

       DayWeek (12)    Current DOS day of the week, starting with
                       Monday.  For example, Monday=1,
                       Tuesday=2,...Saturday=6, and Sunday=7. 
                       Inserting the percent symbol (%DayWeek) 
                       will pad with a zero (0).

       UserID (13)     Returns the Login ID (/u-xxxxx, or that is
                       found in USERID.FIL)

       SysMacDir       Path to the System Macros Directory (as
       (14)            specified in Setup)

       PrgMacDir       Macro directory specified in the Define
       (15)            Program dialog for the active program.

       LocMacDir       Path to the Local Macro Files directory 
       (16)            (as specified in Setup)

       Hour (17)       Current DOS hour in military format.
                       Inserting percent symbol (%Hour) will pad
                       with a zero (0) if the value is less than 
                       10.

       Minute (18)     Current DOS minute.
                       Inserting percent symbol (%Minute) will 
                       pad with a zero (0) if the value is less 
                       than 10.

       Second (19)     Current DOS second.
                       Inserting percent symbol (%Second) will 
                       pad with a zero (0) if the value is less 
                       than 10.

       Path (20)       Path of the currently active program.  
                       This system variable is available with 
                       DOS 3.1 and later.  With earlier DOS 
                       versions, nothing is returned.

       Prog (21)       Name of the executed program (DOS 3.1 and
                       later only).

       KBStat (22)     Current keyboard status (see below)

            1          Right shift key depressed

            2          Left shift key depressed

            4          Control key depressed

            8          Alt key depressed

            16         Scroll Lock active

            32         Num Lock active

            64         Caps Lock active

            128        Insert key active

       WorkSpace       Amount of memory (in bytes) allocated for
       (23)            executing macros.  The default value is 
                       5120 unless you use the /w startup option 
                       with MC.EXE.

       FileID (24)     Returns a unique file ID (normally the 
                       user initials) of up to 5 characters

       ProgsRes        Number of programs currently resident
       (25)

       Keystrokes      Number of keystrokes pressed since the
       (26)            Launcher and Macro Engine were loaded.

  {Message Board}      Displays the Shell Message Board dialog 
                       box.  If a directory has not been 
                       specified for Messages under Setup - 
                       Location of Files, then the Message Board
                       Location dialog box is displayed.  After 
                       you specify a directory for messages, the 
                       Shell Message Board will display.  Use 
                       with {PAUSE} or {PAUSE KEY} to delay macro 
                       execution while the user completes a task.
                       If Shell is not loaded, this command
                       transfers control to the Program of 
                       Choice, and the keystroke Ctrl+Alt+F8 is 
                       executed.  The Program of Choice is 
                       defined as being the first program loaded 
                       by Launcher.  In most cases, this will be 
                       SHELL.EXE, however, it could be anything.
                       For example, typing MC WP.EXE on the 
                       command line would make WP.EXE the 
                       program of choice.

  {Message Create}     Displays the New Shell Message dialog box.
                       If a directory has not been specified for
                       Messages under Setup - Location of Files,
                       then the Message Board Location dialog box 
                       is displayed.  Use with {PAUSE} or 
                       {PAUSE KEY} to delay macro execution while 
                       the user completes a task.

                       If Shell is not loaded, this command
                       transfers control to the Program of 
                       Choice, and the keystroke Ctrl+Alt+F9 is 
                       executed.  The Program of Choice is 
                       defined as being the first program loaded 
                       by Launcher.  In most cases, this will be 
                       SHELL.EXE, however, it could be anything.
                       For example, typing MC WP.EXE on the 
                       command line would make WP.EXE the 
                       program of choice.

  {PROG SYSTEM}        Returns a system variable from the 
  sysvar~              currently active program.  The program 
                       must be Shell-aware.  If the program is 
                       Shell 3.x-aware, the Shell 3.x 
                       Compatibility box (in Advanced Options 
                       when you are defining a program) must
                       be marked.  Following are the Shell system
                       variables:

  Sysvar               Value returned
  ======               ==============

       State (1)       Execution state of Shell

            1          Shell main screen

            2          Resolve Hotkey dialog box is displayed

            4          Resolve Mnemonic dialog box is displayed

            8          Help is currently active

            16         The Shell Screen Lock dialog box is
                       displayed, or Screen Lock is active

            32         Administrator Lockout is set

            64         Mnemonics are available only in the active
                       window

            1024       Confirm action.  The macro is at a Yes/No
                       prompt, a Confirm Delete/Undelete prompt, 
                       or a Replace/Append prompt.

       Memory (2)      Amount of available conventional memory 
                       (in bytes)

       EMM (3)         Amount of available expanded memory (in
                       bytes)

       XMS (4)         Amount of available extended memory (in
                       bytes)

       Disk1 (5)       Space available (in bytes) in the 
                       directory specified by either the /d or 
                       the /v-path1 startup option.

       Disk2 (6)       Space available (in bytes) in the 
                       directory specified by the /v-path2 
                       startup option.

       WindowName      The Menu Description for the active menu
       (7)

       EntryDesc       The name of the currently highlighted 
       (8)             item in a menu window

       EntryID (9)     The Unique Menu IDentifier for the 
                       currently highlighted item in a menu 
                       window

       EntryProg       The name of the executed program for the
       (10)            currently highlighted item

       EntryDDir       The default directory for the currently
       (11)            highlighted item


       EntryMDir       The macro directory for the currently
       (12)            highlighted item 

       EntryType
       (13)

            1          Entry is a program

            2          Entry is a menu

            4          Entry is a macro

            8          Entry is a DOS command or batch file

            16         Entry is a title (text)


       EntryFlags      Condition of the highlighted menu option
       (14)

            1          Pause after Exit is marked

            2          Prompt for Command Line is marked

            4          Start Resident is marked

            8          Disable Shell Hotkeys is marked

            16         Shell 3.0 Compatibility is marked

            32         Password is set

            64         Entry is open or resident

            128        The menu is protected and cannot be 
                       modified

       MsgPathP        Personal Message Board path.  If on a 
       (15)            stand-alone configuration, no value 
                       is returned

       MsgPathS        Shared Message Board path.  If on a stand-
       (16)            alone configuration, the path to the 
                       Message Board directory.

       LastID (17)     The Unique Menu Identifier for the last
                       program which was active

       ResCount        Number of programs resident
       (18)

       LockMsgs        Number of messages left since Screen Lock 
       (19)            was turned on.  You must use this command 
                       while Screen Lock is still active.  After 
                       Screen Lock has been turned off, a value 
                       of zero (0) is returned.

       WindowEnts      Number of entries in a menu window
       (20)

       GoToxxxx        Run the program which has the Unique Menu
       (21)            Identifier of xxxx

  {Resident Progs}     If Shell is loaded, the {Resident Progs}
                       macro command displays the Resident 
                       Programs dialog box which allows you to 
                       switch to a program that is already 
                       resident.  Use with {PAUSE} or {PAUSE KEY} 
                       to delay macro execution while the user 
                       makes a selection.

                       If Shell is not loaded, this command
                       transfers control to the Program of 
                       Choice, and the keystroke Ctrl+Alt+F4 is 
                       executed.  The Program of Choice is 
                       defined as being the first program loaded 
                       by Launcher.  In most cases, this will be 
                       SHELL.EXE, however, it could be anything.
                       For example, typing MC WP.EXE on the 
                       command line would make WP.EXE the 
                       program of choice.

  {Screen Lock}        Displays the Shell Screen Lock dialog box.
                       After you exit from Screen Lock, you are
                       returned to the application which was
                       previously active.
                       If Shell is not loaded, this command
                       transfers control to the Program of 
                       Choice, and the keystroke Ctrl+Alt+F3 is 
                       executed.  The Program of Choice is 
                       defined as being the first program loaded 
                       by Launcher.  In most cases, this will be 
                       SHELL.EXE, however, it could be anything.
                       For example, typing MC WP.EXE on the 
                       command line would make WP.EXE the 
                       program of choice.

  {SET CLPBRD          Allows you to specify which clipboard 
  NUM} number~         (0-79) is currently active.

  {Shell Macro}        Displays the Shell Macro dialog box.  Use
                       with {PAUSE} or {PAUSE KEY} to delay macro
                       execution while the user completes a task.
                       If Shell is not loaded, this command
                       transfers control to the Program of 
                       Choice, and the keystroke Ctrl+Alt+F10 is 
                       executed.  The Program of Choice is 
                       defined as being the first program loaded 
                       by Launcher.  In most cases, this will be 
                       SHELL.EXE, however, it could be anything.
                       For example, typing MC WP.EXE on the 
                       command line would make WP.EXE the 
                       program of choice.

  {STATE}              Current state of the current program.  The
                       program must be Shell-aware.  If the 
                       program is Shell 3.x-aware, the Shell 3.x
                       Compatibility box (in Advanced Options 
                       when you are defining a program) must be 
                       marked.  Following are the Shell 4.0 
                       State values:

       1               Shell desktop

       2               Resolve Hotkey dialog box is displayed

       4               Resolve Mnemonic dialog box is displayed

       8               Help is active

       16              Screen Lock is active

       32              Administrator Lockout is set

       64              Mnemonics Only in Active Window is set

       1024            Confirm action.  You are at a Yes/No 
                       prompt, a Confirm Delete/Undelete prompt, 
                       or a Replace/Append prompt.

=================================================================
DETERMINING UMID NUMBERS
=================================================================
To determine an unknown UMID for a program which may or may not 
be in an open window, 

          1.   From the Shell desktop, select Advanced Edit from 
               the Menu menu.

          2.   Select Search, and type either the description or 
               the filename of the program you are searching for 
               (for example, WordPerfect 5.1 or WP.EXE, 
               respectively).

          3.   Select either Search Description or Search Program
               Name, depending on what you entered in step #2 
               above.

          4.   Select Search From Top, then select Search.

     The program or command you are searching for will be 
     highlighted. You can now use the {PROG SYSTEM}EntryID~ macro 
     command to determine the UMID number for this program, and 
     then user {PROG SYSTEM}GoToxxxx~ to start the program.

     The following example documents how you might write a macro 
     to go to WordPerfect from inside another program.

        {;}GototheShelldesktop~
{Ctrl-Alt- }
        {;}DisplaytheEditMenusdialogbox~
{Shift-F8}
        {;}EnterSearchmode~
{F2}
        {;}Typefilenamefordesiredprogram~
wp.exe{Enter}
        {;}Selectappropriateoptions~
4
        {;}executethesearch~
{F2}
        {;}AssigntheUMIDtovariableNewProg~
{ASSIGN}NewProg~GoTo{PROG SYSTEM}EntryID~~
        {;}CanceloutoftheEditMenusdialog~
{Esc}
        {;}Startthedesiredprogram~
{PROG SYSTEM}{VARIABLE}NewProg~~

**Note: If you are using numeric equivalents in the above 
macro, the fourteenth line would need to have a space before
the {PROG SYSTEM} command.  For example:

{ASSIGN}NewProg~Goto{PROG SYSTEM}EntryID~~    would become
{ASSIGN}NewProg~21 {PROG SYSTEM}9~~
The following table documents Shell 3.x {SHELL SYSTEM} variables 
which are no longer supported.  Some of these commands have been 
replaced by other commands, while others do not apply to Shell 
4.0.


            Shell 3.1 System Variables No Longer Supported

Number    Description                Reason

2    {SHELL SYSTEM}MenuLtr~  replaced by {MACRO SYSTEM}MenuID~

3    {SHELL                  replaced by {PROG SYSTEM}EntryDesc~
     SYSTEM}MenuName~

4    {SHELL                  replaced by {PROG SYSTEM}EntryProg~
     SYSTEM}ProgName~

6    {SHELL SYSTEM}MenuLev~  no longer applies

9    {SHELL SYSTEM}WorkLog~  no longer applies

10    {SHELL SYSTEM}LogName~  no longer applies

11    {SHELL SYSTEM}Project~  no longer applies

12    {SHELL                  no longer applies
      SYSTEM}ProjectID~

13    {SHELL SYSTEM}User~     no longer applies

14    {SHELL SYSTEM}UserJob~  no longer applies

16    {SHELL SYSTEM}Memory~   replaced by {PROG SYSTEM}Memory~

17    {SHELL SYSTEM}EMM~      replaced by {PROG SYSTEM}EMM~

18    {SHELL SYSTEM}Disk1~    replaced by {PROG SYSTEM}Disk1~

19    {SHELL SYSTEM}Disk2~    replaced by {PROG SYSTEM}Disk2~

25    {SHELL SYSTEM}Time~     replaced by
                              {MACRO SYSTEM}%Hour~
                              {MACRO SYSTEM}%Minute~
                              {MACRO SYSTEM}%Second~

26    {SHELL SYSTEM}Date~     replaced by
                              {MACRO SYSTEM}Year~
                              {MACRO SYSTEM}%Month~
                              {MACRO SYSTEM}%DayMonth~
                              {MACRO SYSTEM}DayWeek~

The following macro commands are not supported by Shell 4.0, but 
were supported in Shell 3.x:
{EXEC ADD}
{EXEC DOS}
{EXEC RPL}
{FIND PROG}
{MENU DESC}