
            The SANSoft Development Environment for OS/2 2.0
                         by A. Donnie Hale, Jr.
              Copyright (C) 1992, 1993 SANSoft Development

                           SANSoft Development
                            4971 Pegasus Ct.
                           Hilliard, OH  43026
                       Voice-mail: (614) 898-2675

                     Original Development done by:
                           Daniel A. S. Baker

 SDE documentation. The complete text of this document is available
 on-line via SDE's help facility.

+General

-Overview

 SDE is a file and directory management system and application
 launcher for OS/2.  It has been specially designed to meet the needs
 of OS/2 developers and power users.

 SDE's menu-driven interface, pop-up help facility, and powerful macro
 language make formerly tedious tasks a breeze.  SDE macros can be
 used to create a menu-driven front-end for any command-line utility,
 and can execute any OS/2 or DOS program in the foreground or background.

 Please browse through the help facility to familiarize yourself with
 the multitude of functions provided by this new release of SDE.

-Release notes

 Special thanks to: 
   Daniel Baker, for permission to take this product forward
   Mike Davis, for testing and excellent enhancement suggestions (EESs?)
   My wife and children, for putting up with the development efforts

 Version 3.0.0 enhancements:

  SDE has been converted to a 32-bit application (save the interface).
  A 'Task List' menu has been added, which mimics the PM Task List;
   great for going straight to another full-screen session or restoring
   and going to a minimized application.
  The 'Select-Directory' menu now allows for speed-searching; the next
   item down the list whose partial-directory name begins with the
   pressed alpha-numeric character will be hilited (but not selected).
  A 'Locate file' option exists which is useful in directories with a
   large number of files. The next file which matches the partial file-
   name is hilited; the search occures in the current directory listing's
   order.
  A 'Copy Tagged to Vol' menu option allows for copying tagged files
   to another volume via a Volume followed by Directory pick list.
  When in 'File details' mode, there are two columns of files (rather
   than one); A '' indicates the Hidden, System, and/or Read-Only
   attribute is set.
  Screen-handling is somewhat improved, and the entry-screen is
   restored at exiting.
  When exiting SDE, confirmation is asked for.

 Version 2.2.1 enhancements:

  The 'File details' option now allows you to configure the file
   display area.
  The 'Ignore case' option now allows you to select whether file
   searches performed by the 'Tag/Untag all containing' options will be
   case-sensitive.
  Volume names, as well as drive identifiers, are now displayed in the
   volume menu unless the /v start-up parameter is supplied.
  A new 'Keyboard speed' option allows you to set the typamatic rate
   of the keyboard, if the hardware configuration supports it.
  Clicking the mouse in the extreme lower left corner of the screen
   (over the drive identifier) will cause the 'Volume' menu to be
   displayed. As always, clicking the mouse over the path will bring up
   the 'Directory' menu.
  A carriage return-line feed combination is no longer automatically
   appended after each @Write function call. Use the @; operator to
   force a cr-lf to be written to the output file.

-Installation

 Pick or create a directory on your hard drive for SDE, and copy the
 SDE zip file to that directory. Unzip the file to create the SDE
 system files.

 Edit your CONFIG.SYS file, and add the statement 'SET SDE=D:\PATH',
 where 'D:' represents the drive and '\PATH' the directory to which you
 copied the SDE system.  Add this drive and directory to your PATH
 statement as well.

 If you will be starting SDE from the WorkStation Shell, you may specify
 that SDE be started in either a full-screen session or Presentation
 Manager text window when you add the SDE program folder.

 Reboot, to make your new CONFIG.SYS take effect.

-Parameters

 SDE has a built-in screen blanker which blacks out the screen after
 five minutes of keyboard and mouse inactivity.  Moving the mouse,
 clicking the mouse, or pressing a key will restore the video to its
 previous state.  To activate this feature, start the program with a
 command-line option of /b or /B.  Note that this feature is only
 useful in full-screen mode, since under PM, only the SDE application
 window is blanked.

 Supplying a command-line option of /r or /R will cause SDE to
 remember the help topic last viewed, and display that topic when the
 F1 key is next pressed.

 The display of volume names in the 'Volume' menu may be supressed by
 supplying a start-up parameter of /v or /V. Use this option if you are
 a network user attached to a large number of volumes and the 'Volume'
 menu consequently comes up slowly.

-Pulldown menus

 Open a pulldown menu by pressing Alt plus the hilited character in the
 menu title, by pressing F10 and then the left or right arrow until the
 desired menu is reached, or by clicking the mouse pointer in the menu
 title.

 A menu option can be selected by pressing the hilited character of the
 option, by moving the hilited bar to the option with the up or down
 arrow keys and then pressing Enter, or by clicking the mouse pointer
 on the option.

 To close an open pulldown menu, press F10, Esc, or click the mouse
 outside the menu's window.

-Navigating

 Use the arrow keys to move the hilite bar around the file list. The
 file list 'snakes' from the top left corner of the first page to the
 bottom right corner of the first page, then to the top left corner of
 the second page, and so on.  By continually pressing the down arrow
 key you will eventually reach the last file in the list, and
 vice-versa for the up arrow key.

 Press the Home key to jump to the top of the current column, again to
 jump to the upper left corner of the current page, and again to jump
 to the first file in the list.  Press the End key to jump to the
 bottom of the current column, again to jump to the bottom right corner
 of the current page, and again to jump to the last file in the list.

 If there are more files than will fit on one screen, a scroll bar will
 be displayed on the right-hand side of the screen. Click the mouse
 below the 'thumb' of the scroll bar (or press PgDn) to view the next
 screen. Click the mouse above the thumb (or press PgUp) to view the
 previous screen.

-Mouse support

 SDE supports the mouse for all operations save changing colors.  The
 mouse may be used to select pulldown menus and options within them, to
 select choices from pop-up menus, and to tag and untag files.

 When selecting options from the pulldown and pop-up-style menus, both
 mouse buttons work the same.  Clicking either button of with the
 pointer on top of a menu option will select that option; clicking
 outside a menu's boundary will cancel the menu.  Pressing a button
 with the mouse pointer at the top or bottom border of a menu will move
 the hilite bar towards the top or bottom, respectively, scrolling the
 menu if appropriate.

 In the file name area, the left mouse button moves the hilite bar and
 tags or untags the file beneath the mouse pointer.

 In the file name area, the right mouse button moves the hilite bar to
 the filename beneath the mouse pointer.  When the button is released,
 and if there is an external macro file named BUTTON.XM in the SDE
 program directory, the BUTTON.XM macro is loaded and executed.  This
 macro may do anything that can be written in a SDE macro.

 The mouse movement speed may be set via the 'Mouse speed' option. This
 changes the mouse speed not only for SDE, but for any full-screen
 program executed from SDE in the SDE screen group that utilizes the
 mouse.  Note that changing the mouse speed with SDE running in a PM
 text window has no effect on the mouse speed, since this is controlled
 by Presentation Manager.

-Editing keys

 When entering text into any SDE input field, you may use the
 following editing keys:

 Insert       Toggles insert/overtype mode
 Backspace    Deletes the character to left of the cursor
 Delete       Deletes the character beneath the cursor
 Home         Moves the cursor to the first character in the field
 End          Moves the cursor to the last character in the field
 Ctrl-Backsp  Deletes from the cursor to the end of the field
 Left         Moves the cursor one character to the left
 Right        Moves the cursor one character to the right
 Ctrl-Left    Moves the cursor 5 characters to the left
 Ctrl-Right   Moves the cursor 5 characters to the right
 Esc          Cancels any changes made to the field
 Enter        Accepts any changes made to the field
 F1           Displays help

-Key/mouse shortcuts

 Press:       To:

 Tab          Display file information dialog (same as ^I)
 Shift-Tab    Display file info dialog without tree info
 Enter        Change file mask (same as ^M)
 Esc          Display directory tree (same as ^D)
 Insert       Duplicate hilited file (same as ^P)
 Delete       Delete tagged files (same as @D)
 Backspace    Rescan current directory
 Keypad -     Jump to previous directory in tree
 Keypad +     Jump to next directory in tree

 Click:       To:

 Scroll bar   Display previous/next page (same as PgUp/Dn)
 Volume       Display volume menu (same as ^V)
 Directory    Display directory tree (same as ^D)
 File info    Display file/directory info (same as ^I)
 Time         Display system info (same as @N)

+Menu Options

-File Menu

 About SDE...........: Displays the SDE logo; any key exits
                                 
 Information.........: Displays volume, directory, tree and file info
                                 
 Attributes..........: Allows changing of the hilited file's attributes
                                 
 Locate..............: Searches for files matching input file mask
                                 
 Duplicate hilited...: Duplicates hilited file to specified file name
                                 
 Rename hilited......: Renames hilited file to specified file name
                                 
 Execute hilited.....: Attempts to execute the hilited file
                                 
 Move tagged.........: Moves tagged files to directory selected from tree
                                 
 Copy tagged.........: Copies tagged files to specified location
                                 
 Copy tagged to Vol..: Copies tagged files to selected volume, directory
                                 
 Delete tagged.......: Upon verification, deletes tagged files
                                 
 Quit SDE............: Immediately quits SDE

-Select Menu

 Volume..............: Displays a menu of available volumes for selection
                                 
 Directory...........: Displays a menu of the available directories
                                 
 Mask................: Allows changing of the file mask for file display
                                 
 Tag all.............: Tags all displayed files in current directory
                                 
 Tag by wildcard.....: Tags all files matching specified file mask
                                 
 Tag all containing..: Tags all files containing specified string
                                 
 Untag all...........: Untags all displayed files in current directory
                                 
 Untag by wildcard...: Untags all files matching specified file mask
                                 
 Untag all containing: Untags all files containing specified string
                                 
 Sort method.........: Displays menu for sorting displayed files
                                 
 Screen colors.......: Displays sample screen for selecting colors
                                 
 Screen mode.........: Displays menu of available screen modes
                                 
 Mouse speed.........: Displays menu for selecting mouse sensitivity
                                 
 Keyboard speed......: Displays menu for selecting keyboard repeat rate

-Directory Menu

 Create subdir.......: Creates specified subdirectory below current one
                                 
 Remove current......: Attempts to delete the current subdirectory
                                 
 Rename current......: Renames the current directory as specified

-Macro Menu

 Edit macro set......: Displays a menu of macro keys for editing
                                 
 Debug mode..........: Toggles macro debug mode on / off
                                 
 Import from file....: Imports macros from an ASCII text file
                                 
 Export to file......: Exports macros to an ASCII text file

-Misc Menu

 Help on SDE.........: Displays the help menu
                                 
 Rescan volume.......: Rebuilds the directory tree for the current volume
                                 
 System Info.........: Displays basic information about the system
                                 
 Verify copy.........: Toggles copy verify mode on / off
                                 
 Capitals............: Toggles capitals mode on / off
                                 
 Ignore case.........: Toggles case sensitivity on / off
                                 
 File details........: Toggles file details mode on / off
                                 
 Command input.......: Executes the entered command line
                                 
 Previous commands...: Displays a menu of previously executed commands
                                 
 Command shell.......: Executes a command shell; exit returns to SDE
                                 
 Shell program.......: Enter the desired shell program name
                                 
 Task List...........: Displays a menu of switchable tasks

-Execute Menu

 See the Execute Menu help item under <About macros>

+Files

-Copying

 Tagged files may be copied to a directory on another volume, or to a
 directory on the current volume via the 'Copy tagged' option.

 When this option is selected, you will be presented with an input
 field where you may type the volume and path name of the target
 directory. Enter the target path or simply press the Enter key to
 display the directory tree of the current volume.

 If the target volume should become full during a copy operation, you
 will be given an opportunity to insert a new volume and continue the
 copy procedure.  The file that caused the overflow will be written, in
 its entirety, to the new volume (files are never fragmented across
 volumes).

 If the Verify option is on, all data written to disk during a copy
 operation will be tested for integrity.  If verify is off, no such
 check is performed.

-Moving

 Tagged files may be moved to a directory on the current volume only.
 When the 'Move tagged' is selected, the directory tree of the current
 volume is displayed. When a directory is chosen, the tagged files are
 moved from the current directory to the selected directory.

-Deleting

 When the 'Delete tagged' option is selected, any tagged files in the
 current directory are permanently deleted. You will be given an
 opportunity to verify whether the group of tagged files should indeed
 be deleted.

-Renaming

 The hilited file may be renamed with the 'Rename hilited' option. When
 chosen, an input field will be displayed so that the new file name can
 be entered.

-Locating

 Select the 'Locate' option to find all files on the current volume
 which match a given wildcard file specification or filename. SDE will
 search each directory, starting with the current, for matches.

 When a match is found, you will be given the opportunity to: (1)
 continue the search, (2) stay in the directory where matches were
 found, or, (3) abort the search.

-Duplicating

 The 'Duplicate hilited' option creates a file identical to that of the
 hilited file. An edit field appears so that the new file can be named.

-Attributes

 The hidden, system read-only, and archive attributes of the hilited
 file may be changed with the 'Attributes' option.

 From the menu displayed, you may set the file's hidden, system,
 read-only, and archive bits as desired by pressing the space bar.
 Press Enter to make the changes permanent, or Esc to abort the menu.

-Sorting

 The 'Sort method' option allows you to choose whether the file list
 will be displayed in ascending or descending name, extension,
 date/time, or file size order.

-Tagging/Untagging

 Use the space bar to tag or untag the hilited file. The hilite bar
 will advance to the next file in the list, making it easy to tag
 blocks of files.

 You may also use the mouse to tag/untag files. Press the left mouse
 button to hilite and tag/untag the file beneath the mouse pointer.

 Tagged files are marked by a pair of arrows on either side, and may,
 depending on your color selections, appear in a special color.

 The 'Tag/Untag by wildcard' options allow you to tag/untag any files
 which match a given wildcard file specification. Any number of
 wildcards, separated by spaces, may be entered into the input field
 displayed by these options.

 The 'Tag/Untag all containing' options allow you to tag or untag all
 files which contain a given search string.  When one of these options
 is selected, you will be asked to enter a search string, which may be
 up to 255 characters long. The setting of the 'Ignore case' option
 determines whether the search is case-sensitive.

 Tagged files may be copied, deleted, and moved en masse, as well as
 fed to SDE macros which make use of the @Tagged macro function.

-Masking

 The 'Mask' option allows you to enter a wildcard file specification
 which will be used to selectively display only those files in the
 current directory which match the specification.  The standard * and ?
 wildcard characters are supported.

+Directories

-Switching

 The 'Directory' option allows you to change the current working
 directory. When the option is selected, the directory tree of the
 current volume is displayed.

 Note that changing the SDE directory may also be accomplished via the
 @ChDir macro function.

-Creating

 The 'Create subdir' option allows you to create a new sub-directory of
 the current directory.  An input field will be displayed so that the
 new directory can be named.

-Removing

 The 'Remove current' option, valid for empty directories only, removes
 the current directory from the volume.  Note that a directory in use
 by another OS/2 process cannot be removed.

-Renaming

 The 'Rename current' option renames the current directory.  Note that
 a directory in use by another OS/2 process cannot be renamed.

-Rescanning

 The current directory may be rescanned (necessary if files have been
 added to or removed from the directory by programs other than SDE
 since it was entered) by selecting the current directory (denoted by
 an arrow) from the directory tree.  Pressing the Backspace key has the
 same effect.

+Volumes

-Switching

 The 'Volume' option allows you to work on a different volume. When
 this option is chosen, a list of all the currently attached volumes
 (the A: and B: volumes are always considered attached) is displayed in
 a pop-up menu. Note that volume names are not retrieved for volumes A:
 and B:, they will appear as "DISKETTE" in this menu.

 Selecting a volume from this list takes you to the default directory
 of the selected volume.

 If a map for the chosen volume exists in the SDE directory, it will be
 read to speed access to the device.  Otherwise, the volume's directory
 structure will be examined and a map file for that volume will be
 created automatically.

 Note that changing the current SDE volume may also be accomplished via
 the @ChDir macro function.

-Rescanning

 If directories are added or removed from a volume by programs other
 than SDE, a rescan of the volume is required to bring the volume's
 map file (which contains the volume's directory structure) up to date.

 To rebuild the map file, select the 'Rescan volume' option. Note that
 map files are not built for the A: and B: diskette volumes.

+About macros

-Introduction

 Macros are an extremely powerful SDE feature; they allow you to
 launch any program from SDE, and build customized interfaces for
 programs that accept command-line arguments.

 OS/2's standard command-line interface works well enough, but results
 in a good deal of typing on your part.  Macros are a short-hand way of
 entering a commands into the operating system, as you will see in the
 following example:

 Assume you have a program called VIEW, which lets you look at the
 contents of text files.  Also assume that VIEW, like other programs of
 its kind, allows you to specify multiple filenames on the command
 line. A single VIEW command might look like this:

 VIEW FILE1.EXT FILE2.EXT FILE3.EXT FILE4.EXT

 With the following SDE macro assigned to the 'V' key, simply point to
 and tag the files FILE1.EXT, FILE2.EXT, FILE3.EXT, and FILE4.EXT, and
 press 'V'.

 VIEW @Tagged()

 The traditional OS/2 command above, over 40 characters long, has been
 reduced by SDE to four mouse clicks and one keystroke!

 You may have 62 macros (assigned to the keys a-z, A-Z, and 0-9) active
 at one time.  With multiple macro sets (see the Import and Export
 features), you have a virtually unlimited number of macros at your
 disposal.

 To create a macro, select the 'Edit macro set' option. A menu of all
 the macros in your current macro set will be displayed, each preceded
 by the key to which the macro is assigned.  Select a macro to edit,
 then type your macro in the edit field.  Press F1 if you need help
 while editing your macro.  Press Enter to save your macro.  Hereafter,
 your macro may be executed by simply pressing the key to which the
 macro is assigned.

-Evaluation

 When a SDE macro is executed, the SDE macro processor searches your
 macro for macro functions.  Once found, SDE will then take various
 actions depending on the function name given.  If the macro processor
 encounters text which lies outside a macro function, the text is
 copied directly into the expanded macro (which, once processing is
 complete, is the command that will be given to the operating system
 for execution).

 Many SDE macro functions return a result to the point from which they
 are called.  The return value from one of these functions is a string
 of zero or more characters.  This value may be used as input to
 another SDE macro function that accepts parameters (referred to as
 nesting), or, if not nested, the function result is inserted into the
 expanded macro at the point of the function call, replacing the
 function name and function parameters.

 Functions are processed in the order they appear (left to right)
 except in the case where functions are nested.  Nested functions are
 recursively evaluated from the innermost nested to the outermost.
 Such nesting may occur to any depth.

 When all SDE macro functions have been removed from the macro via the
 evaluation process, the expanded macro, if not empty, is fed to the
 operating system for execution. Use the @Options function to set
 execution options that will be applied to the command at run-time.

 Note that a macro need not call a program to be useful; through clever
 use of macro functions, quite useful side-effect-only macros can be
 created. Usually, such macros are written using functions, such as
 @Key, @Write, and @ChDir, that return no value.

 The maximum length of an expanded macro is 8192 bytes. Unpredictable
 (although not dangerous) results may occur if you attempt to pass more
 than 8K of data to an application.

-Debug mode

 When the 'Debug mode' option is turned on, SDE will treat each macro
 as if the DUMP execution option (see the description of the @Options
 macro function) is specified in the macro.  This causes the contents
 of the expanded macro to be dumped to the screen rather than fed to
 the operating system for execution.  To resume normal macro execution,
 turn the mode off by selecting the 'Debug mode' option again.

-Function names

 SDE macro function names always begin with a '@' character. If you
 must use the '@' character in a macro in a way that does not entail
 the start of a macro function name, you must use the syntax '@@' (see
 the 'Special @ uses' topic).

 The macro processor is not case-sensitive as far as function names are
 concerned. For instance, the @Tagged function name may be written as
 either '@tagged', '@Tagged', '@TAGGED', or any other case-wise
 variation of this name.

 Only the minimum number of characters required to insure uniqueness
 are required. The function name @Hilited may be written as just '@H',
 since no other macro function names begin with the letter 'H'.  The
 @External function, however, may be abbreviated to nothing shorter
 than '@Ext', since there is a distinct @Exists function.

 If a function name is abbreviated, the first macro function name (in
 alphabetical order) that matches the abbreviation will be selected, so
 please abbreviate with care.

 Note that in some instances (see the 'Execute menu' topic and the
 @Write macro function description, in particular) a function name may
 not be abbreviated.

-Parameters

 All macro functions require a parameter, enclosed in delimiters, which
 must follow the function name.  The delimiters must be supplied even
 if the parameter is empty. A typical SDE function call will look like
 this:

 @Function(Param)

 For functions that require multiple parameters (such as @Menu and
 @Select), each parameter must be encased in delimiters, as well as the
 entire parameter list, like so:

 @Function((Param1)(Param2)(Param3))

 Delimiters may be any of the open/close symbol pairs: parentheses, (),
 curly brackets, {}, and square brackets, [].  Choose your delimiters
 for a function such that the text between the delimiters does not
 itself contain either of these open/close symbols, unless they encase
 macro parameters (as in the @Menu and @Select functions), or are
 associated with a nested SDE macro function.  The following macro
 fragment is NOT acceptable, because of the left parenthesis embedded
 in the last @Menu parameter:
                                              
 @Prompt(Translation?) @Menu((Binary)()(Text)((CRLF ASCII))

 The proper form of the macro fragment above would use curly brackets
 or square brackets as @Menu function delimiters, as in:

 @Prompt(Translation?) @Menu{{Binary}{}{Text}{(CRLF ASCII}}

-Variables

 Macro variables operate much the same as variables in many programming
 languages; you may set and query the contents of a variable, and use
 the variable in place of hard-coded text. Each variable is associated
 with (or, in other words, has a value of) a text string of zero or
 more characters.

 Variable names and their associated strings may consist of any run of
 ASCII characters, with no restrictions as to length save that the
 length of all variable names plus the length of all variable strings
 remains less than 32K, the size of the heap reserved by SDE for
 variable use.  The setting of any variable which would cause this
 limit to be exceeded is ignored.

 SDE is not case-sensitive with regards to variable names. Therefore,
 the variable names 'User' and 'user' refer to the same variable.

 To set the contents of a variable, use the @Set macro function. To
 recall the value of a variable, use the @Val function.  Examine the
 following macro fragment:

 @Set((name)(@Prompt(Your name?)@Input())) @Abort(Hello, @Val(name)!)

 This macro assigns whatever is typed into the input field displayed by
 the @Input function to the variable 'name'. The macro is then aborted
 with a friendly message.

-External macros

 While relatively short macros (those less than 256 characters in
 length) may be entered into SDE directly via the 'Edit macro set'
 option, longer and more complex macros can be written and executed via
 SDE's external macro facility.

 Use any ASCII text editor to create and edit an external macro. The
 extension of '.XM' is recommended, but SDE will properly load an
 external macro with any extension.  In this file, enter a macro
 exactly as you would in SDE, but the macro may be up to 8192 bytes
 long and may be formatted - spread across any number of lines and
 indented - to your liking.

 Important! All leading spaces, trailing spaces, carriage returns and
 line feeds are stripped from each line of the external macro file.  To
 keep significant spaces at the end of a line, use underscore, '_',
 characters in place of the significant spaces.

 To execute an external macro, create an internal macro that uses the
 @External function to load and execute the external macro file.  If a
 path is specified in the external macro filename, then the file is
 loaded from that directory. Otherwise, SDE looks in the current
 directory for the file. If not found in the current directory, the
 search defaults to the SDE program directory.

 Please see the '.XM' files shipped with SDE for examples of external
 macros.  You are, of course, free to modify or build on these macros
 to suit your needs.

 On start-up, the external macro AUTOEXEC.XM is automatically loaded
 from the SDE program directory, if the file exists. This macro may do
 anything that can be written in a SDE macro.

 See the 'Mouse support' section for information about the BUTTON.XM
 external macro which is called when the right mouse button is pressed.

-Execute menu

 The Execute pulldown menu allows you to view the names of selected
 internal macros, and to execute a macro from the menu.

 To add a macro to the Execute menu, edit the macro and place a prompt
 (using the @Prompt macro function) at the very front of the desired
 macro. The text appearing between the delimiters of the @Prompt
 function will become the macro's title.

 Note! This is one case in which a function name must not be
 abbreviated; for it to be recognized as a macro title, the full
 function name @Prompt must be specified.

 The first twenty or so characters of a macro's title will be added to
 the Execute menu as a selectable option.  The accelerator key for the
 option will be the key to which the macro is assigned.

 Avoid using macro functions inside macro titles, since functions are
 only expanded at run-time.  Also avoid using the tilde '~' character
 in macro titles.  Macro titles must not begin with a hyphen '-'.

-Import from file

 The 'Import from file' option allows you to read a set of macros from
 a text file.  Each macro in this file must reside on its own line, be
 less than 256 bytes long, and have the form:

 KEY - MACRO TEXT

 When you select the 'Import from file' option, you will be prompted
 for a macro file name.  Enter only the primary name of the import
 file; the extension '.MAC' will be appended automatically.  The file
 will be read from the SDE program directory.

 If your current macro set has changed since your last export
 operation, you will be asked if you want to save the changes to your
 current set.

 Once a macro set has been imported, your Execute menu will be updated
 to reflect the titles of your new macro set.

-Export to file

 The 'Export to file' option allows you to write your current macro set
 to a text file.  This file can be edited with an ASCII text editor, if
 necessary, and read back into SDE with the Import feature.

 As with the Import option, enter only the primary name of the macro
 file when prompted for the export file name; the extension '.MAC' will
 be appended automatically.  The file will be saved in the SDE program
 directory.

 The Import and Export features allow you to create custom macro sets
 for working in two or more environments, and give you the flexibility
 to re-configure your entire keyboard in seconds.

-Samples

 The SAMPLE.MAC file shipped with SDE contains several examples of
 both simple and complex macros. To load the macros in this file into
 the SDE environment, first save your current macro set (if you have
 already created one or more macros) by selecting the 'Export to file'
 option. Then, select the 'Import from file' option and enter the macro
 set name 'SAMPLE' in the input field.

 See the SAMPLE.DOC file for complete descriptions of the macros
 contained in the SAMPLE.MAC file.

+Macro functions

-Abort

 Syntax: @Abort(Message)
 Abbrev: @A (Minimum)

 The macro is aborted with an error message, supplied as the sole
 argument, when this function is encountered. The message may be empty,
 if desired, in which case no message is displayed to the user.

 This function has no return value.

-ChDir

 Syntax: @ChDir(Path)
 Abbrev: @C (Minimum)

 Changes the current SDE directory to the path specified in the sole
 argument. The path given may contain a volume identifier, in which
 case the current volume is changed as well.

 This function has no return value.

-Comment

 Syntax: @Comment(Text)
 Abbrev: @CO (Minimum)

 Denotes a comment.  Whatever appears between the parameter delimiters
 of this function is ignored.

 This function has no return value.

-Edit

 Syntax: @Edit(Variable)
 Abbrev: @E (Minimum)

 Displays an input field for a the purpose of editing the contents of a
 macro variable whose name is given as an argument to this function.
 The @Edit function is a short-hand way of coding the following macro
 sequence:

 @Set((var)(@Input(@Val(var)))) @Val(var)

 The title of an input field will be the prompt established by the
 @Prompt function, or 'Input:' if none.

 The post-edit contents of the variable are returned by this function.
 If the field is canceled with the Esc key, the macro is aborted.

-Exists

 Syntax: @Exists(File)
 Abbrev: @EX (Minimum)

 This function indicates whether the specified file exists by returning
 the file name if the file exists, or empty if the file does not exist.

                                 

 The following macro fragment will abort the current macro if the file
 entered into the variable edit field does not exist.

 @Edit(file) @QuitIf((@Exists(@Val(file)))(@Val(file) does not exist!))

-External

 Syntax: @External(File)
 Abbrev: @EXT (Minimum)

 This function loads and executes an external macro. External macros
 are much like the standard internal macros, but they reside in disk
 files, one macro per file.  They are most frequently used when the
 length of a macro exceeds the 256 character limit of internal macros.

 If a path is specified in the external macro filename, then the file
 is loaded from that directory. Otherwise, SDE looks in the current
 directory for the file. If not found in the current directory, the
 search defaults to the SDE program directory.

 See the 'External macros' help topic for additional information on
 external macro use and restrictions.

 The return value of this function is the return value of the external
 macro.

-FDate

 Syntax: @FDate(File)
 Abbrev: @F (Minimum)

 This function returns the date/time stamp of the file given in the
 argument. This information reflects the date and time the file was
 last modified, and has the format:

 YR-MO-DY HR:MN:SC

 This string, since its components are ordered from the most to least
 significant, may be used in less than, greater than, and equal to
 comparisons.

 Note that the date/time stamp of hilited/tagged files is available
 through the @Hilited and @Tagged functions.

 The return value is the date/time string of the specified file, or the
 empty string if the file does not exist.

-FSize

 Syntax: @FSize(File)
 Abbrev: @FS (Minimum)

 This function returns the size in bytes of the file given in the
 argument.

 This string may be used in less than, greater than, and equal to
 comparisons.

 Note that the size of hilited/tagged files is available through the
 @Hilited and @Tagged functions.

 The return value is a string containing the size of the specified
 file, or the empty string if the file does not exist.

-Hilited

 Syntax: @Hilited(Portion)
 Abbrev: @H (Minimum)

 Returns the specified portion of the hilited filename. The argument
 must evaluate to one of the following:

 Name      - Returns the primary filename (sans period and extension)
             of the currently hilited file.
 Extension - Returns the extension (sans period) of the currently
             hilited file.
 Full      - Returns the full file specification (volume, path, and
             filename) of the currently hilited file.
 Date      - Returns the date/time stamp, in YR-MO-DY HR:MN:SC format,
             of the currently hilited file.
 Size      - Returns the size, in bytes, of the currently hilited file.

 The identifiers above may be abbreviated as desired; only the first
 character of the supplied identifier is actually significant.

 If the argument is empty, then the currently hilited filename, both
 primary name and extension, are returned.

                                 

 For example, if the current directory is 'C:\DOCUMENT', and the
 currently hilited file is 'LETTER.DOC':

 @Hilited()  returns LETTER.DOC
 @Hilited(N) returns LETTER
 @Hilited(E) returns DOC
 @Hilited(F) returns C:\DOCUMENT\LETTER.DOC
 @Hilited(D) returns 89-10-08 13:45:26
 @Hilited(S) returns 4096

-If<=>

 Syntax: @If<((Value)(Case1)(Expression1)...(Case2)(Expression2)(Else))
 Abbrev: @IF< (Minimum)
 Syntax: @If>((Value)(Case1)(Expression1)...(Case2)(Expression2)(Else))
 Abbrev: @IF> (Minimum)
 Syntax: @If=((Value)(Case1)(Expression1)...(Case2)(Expression2)(Else))
 Abbrev: @IF= (Minimum)

 These functions allow conditional macro execution based on the value
 of an expression.

 The expression given in the first argument, (Value), is evaluated, as
 is the next expression, (Case1).  If (Value) is:

     less than (Case1) for @If<,
     equal to (Case1) for @If=,
     greater than (Case1) for @If>,

 then next expression, (Expression1), is executed and the function is
 exited.  Otherwise, if another case/expression pair is given, the
 original expression, (Value), is compared with the next expression in
 the list, (Case2).  If (Value) is:

     less than (Case2) for @If<,
     equal to (Case2) for @If=,
     greater than (Case2) for @If>,

 execution branches to the following expression, (Expression2) and the
 condition is exited.  This process continues for as many
 case/expression pairs as are contained in the parameter list.

 If a single trailing argument is supplied, in this case (Else), it is
 executed if all of the preceding comparisons have failed.  This last
 argument is optional.

 Note that the comparison mechanism is not case-sensitive.

                                 

 For example, the following macro sends the hilited file, if it has an
 extension equal to 'DOC', to the 'VIEWDOC' program, if equal to 'PAG'
 to the 'VIEWPAG' program, or to another program, 'VIEWFILE', if
 neither 'DOC' nor 'PAG'.

 @If=((@Hilited(E))(DOC)(VIEWDOC)(PAG)(VIEWPAGE)(VIEWFILE)) @Hilited()

                                 

 The return value of this function is the return value of the first
 expression whose case satisfies the comparison, or the result of the
 else condition if none of the comparisons are satisfied.

-Input

 Syntax: @Input(Text)
 Abbrev: @IN (Minimum)

 Displays an input field for a user-supplied string, and returns the
 text entered into the field.  The text supplied in the parameter is
 placed in the input field as a default.

 The title of an input field will be the prompt established by the
 @Prompt function, or 'Input:' if none.

 The text entered into the input field is returned. If the input is
 canceled with the Esc key, the macro is aborted.

-Internal

 Syntax: @Internal(Macros)
 Abbrev: @INT (Minimum)

 This function executes the internal macros (those created within SDE)
 named in the argument.

 This function allows you to extend the 256 character limit of a single
 macro, but for extremely large and complicated macros, consider using
 an external macro.

                                 

 For example, the following macro fragment calls the macros assigned to
 the 'C' and 'S' keys:

 @Internal(CS) TYPE @Hilited()

 If the macros for the 'C' and 'S' keys read:

 @Options(CMD MSG)
 @Options(FORE:RED BACK:BLACK)

 respectively, then the macro above is identical to one reading:

 @Options(CMD MSG) @Options(FORE:RED BACK:BLACK) TYPE @Hilited()

                                 

 The return value of this function is the return value of the macro(s)
 called.

-Key

 Syntax: @Key(key key ... key)
 Abbrev: @K (Minimum)

 This, the AutoKey function, adds the key names contained in the
 argument to the SDE keystroke buffer (not the OS/2 keyboard buffer)
 in the order they appear.  When keystrokes are fed to the keystroke
 buffer in this manner, SDE will act as if they had been typed at the
 keyboard manually. Note that the actual processing of the keys in the
 keystroke buffer is performed after macro termination.

 Valid key names are as follows (case is not significant):

 F1 thru F12, TAB, SHIFT-TAB, ESCAPE, INSERT, DELETE, HOME, END, PGUP,
 PGDN, UP, DOWN, LEFT, RIGHT, ENTER, BACKSPACE, SPACE, CTRL-A thru
 CTRL-Z, CTRL-F1 thru CTRL-F12, CTRL-BACKSPACE, ALT-A thru ALT-Z, ALT-0
 thru ALT-9, ALT-BACKSPACE, and, of course, single character keys such
 as A thru Z, 0 thru 9, +, -, *, etc.

 Each key name (except single character key names) must be separated by
 a space.  Spaces in this string are not significant; to cause a space
 character to be inserted into the keyboard buffer, use the key name
 SPACE.

 If an AutoKey sequence causes an external application to be executed,
 any pending keystrokes in the keystroke buffer will be saved until
 that application terminates (unless the WAIT or MSG execution option
 is supplied, since either clears the SDE keyboard buffer).

 Note! The ESC, DELETE, and INSERT keys in the SDE interface are
 aliases for the ^V, @D, and ^P keystrokes. These aliases should never
 be used in the @Key function to perform actions associated with the
 ^V, @D and ^P keys; instead, use CTRL-V, ALT-D, or CTRL-P.

                                 

 For example, the following AutoKey sequence changes the current file
 mask to display only those files having the same extension as the
 currently hilited file:

 @Key(enter *.@Hilited(E) enter)

 The next AutoKey sequence copies all currently tagged files to the
 directory 'BACKUP' on the A: drive:

 @Key(alt-c a:\backup enter)

                                 

 This function has no return value.

-Lower

 Syntax: @Lower(String)
 Abbrev: @L (Minimum)

 Returns the lower-case equivalent of the specified string. This
 function is provided for cosmetic purposes only; all SDE comparison
 functions are case-independent.

-Menu

 Syntax: @Menu((Option)(Expression)...(Option)(Expression))
 Abbrev: @M (Minimum)

 This function builds and displays a MacroMenu, which is a pop-up menu
 whose options, and associated actions, are specified by the macro
 author.

 Each option, enclosed in open/close delimiters, represents a single
 line in the pop-up menu. Each must be followed by an expression, also
 enclosed in delimiters, which will be evaluated if the associated
 option is selected.  Up to 16 option/expression pairs may be specified
 in a single MacroMenu.

 MacroMenus may be nested; that is, a MacroMenu may appear inside an
 expression of a higher-level MacroMenu. Such nesting may occur to any
 depth.

 The title of a MacroMenu will be the prompt established by the @Prompt
 function, or 'Options:' if none.

 To select a MacroMenu option, you may press the first letter of the
 option's name, or hilite the option and press the Enter key.

 The return value of this function is the result of the expansion of
 the expression for the selected option.  If the MacroMenu is canceled,
 the current macro is aborted.

-Message

 Syntax: @Message(Message)
 Abbrev: @MES (Minimum)

 This function displays the given text in a one-line window and pauses
 until the user presses a key or clicks a mouse button.

 This function has no return value.

-Options

 Syntax: @Options(option option ... option)
 Abbrev: @O (Minimum)

 Sets the execution options that will be used when the macro's program
 is run. Multiple options, separated by blanks, may be specified.  The
 valid options are (order and case are not significant):

 BACK:COLOR

    Sets the teletype-mode background color to the color name specified
    immediately after the colon. This color will be used by any
    teletype-mode program executed from SDE in the SDE screen group.
    After the program terminates, the default colors (those of the SDE
    file list) are restored. Valid background color names are (case is
    not significant):

    BLACK, RED, GREEN, YELLOW, BLUE, CYAN, MAGENTA, WHITE

 BEEP

    Beeps the PC's speaker after the program called by the macro
    terminates.

 CMD

    Uses the OS/2 command processor, CMD.EXE, to execute the program or
    batch file in the SDE session as opposed to direct SDE execution.
    Use this option when running:

     Presentation Manager programs,
     OS/2 batch (.CMD) files,
     Programs that may require Control-Break or Control-C,
     Programs whose output is being redirected or piped,
     Internal OS/2 commands (like TYPE, DIR, DEL, etc.).

    This option is ignored if the LAUNCH option is also specified in
    the options list.

 DIR

    Rescans the current directory after macro execution (the directory
    is not rescanned by default).  Use this option when the execution
    of a macro will result in the creation or deletion of files.

 DUMP

    Dumps the expanded macro to the screen for debugging instead of
    executing the macro. This option may be turned on globally (for all
    macros) via the 'Debug mode' option. This is generally not useful
    for debugging side-effect only macros (those that call no
    executable program or batch file).

 FORE:COLOR

    Sets the teletype-mode foreground color to the color name specified
    immediately after the colon. This color will be used by any
    teletype-mode program executed from SDE in the SDE screen group.
    After the program terminates, the default colors (those of the SDE
    file list) are restored. Valid foreground color names are (case is
    not significant):

    BLACK, RED, GREEN, YELLOW, BLUE, CYAN, MAGENTA, WHITE

    The foreground color name may be appended with a '+' character to
    indicate a bright color; the color name alone indicates a dim
    color.

 LAUNCH

    Launches the macro's program in a separate screen group. If this
    option is specified, then the following launch options may also
    appear in the @Options parameter list (order and case are not
    significant):

    OPEN, CLOSE, DIRECT

       The OPEN open specifies that the command processor be used to
       launch the specified non-PM program or batch file.  The new
       session will remain open after the program terminates.

       The CLOSE option directs SDE to use the command processor to
       launch the specified non-PM program or batch file.  The new
       session will be closed after the program terminates.

       If the DIRECT option is given, the macro's program is launched
       directly, and not by the command processor. This method is
       slightly faster and somewhat more memory conservative than
       launching via the command processor, but cannot be used to
       execute batch files.

       The OPEN, CLOSE, and DIRECT options are mutually exclusive.

    FS, WIN, PM

       Valid for non-PM programs and batch files only, the FS option
       directs SDE to start the program in a new full-screen session.
       Use this option to force applications that default to PM text
       window operation to run in full-screen mode.

       Valid for non-PM programs and batch files only, the WIN option
       directs SDE to start the program in a Presentation Manager text
       window, if the program allows.

       The PM option is used to specify that the program to be run is a
       Presentation Manager application. This option is usually omitted
       for standard PM programs since the program will be recognized as
       such at load time.

       The FS, WIN, and PM options are mutually exclusive.

    FORE

       If this option is specified, the new session is brought to the
       foreground when executed. Specifying the FS, WIN, or PM option
       in the macro will also cause the new session to be brought to
       the foreground when executed.

    INHERIT

       This option forces the environment for the program to be
       inherited from the environment variables set in CONFIG.SYS as
       opposed to those set in the SDE session's environment.

    The launch options above are ignored if the LAUNCH option is not
    given.  Please note that merely specifying the LAUNCH option by
    itself is sufficient to execute any program or batch file; the
    additional options are provided to accommodate special
    requirements.

    See the @Prompt function description for information on giving a
    custom title to sessions created with LAUNCH.

 MSG

    SDE displays a 'Click mouse or press a key to continue...' message
    and waits for a key or mouse click after the program terminates.

 REPEAT

    Repeats the macro in which this option appears in every directory
    on the current volume. The macro is re-processed on entry to each
    directory.

 VOLUME

    Rescans the current volume after macro execution. Use this option
    if the program being called will create or delete directories.

 WAIT

    Causes SDE to wait for a key or mouse click after the program
    terminates. No message is displayed.

 WIPE

    A nifty, if otherwise useless, way to clear the screen prior to
    program execution.

 25, 43, 50

    Puts the display in 25, 43, or 50 line mode, respectively, prior to
    program execution.  The current video state is saved and then
    restored after the program terminates.

                                 

 Important! If the @Options function is not supplied in a macro, or if
 supplied without the CMD option or LAUNCH option, then SDE, by
 default, loads and directly executes the macro's program in the SDE
 screen group.  Presentation Manager programs and batch files CANNOT be
 run in this manner; the @Options function and either the CMD or LAUNCH
 option must appear in the macro.

                                 

 There is no return value for the @Options function.

-Pad

 Syntax: @Pad(column)
 Abbrev: @P (Minimum)

 All output since the last carriage return/line feed, or the beginning
 of the expanded macro if no cr/lf's have yet been encountered, is
 padded with blanks to the specified column (with column 0 being the
 leftmost column).

                                 

 This function is most effective when used in the output string of the
 @Write function to columnize data, as in the following example:

 @Write((test.fil)(w)(Line 1, column 0@;@Pad(5)Line 2, column 5))

 The macro fragment above results in output to the file 'test.fil'
 which reads:

 Line 1, column 0
      Line 2, column 5

-Parse

 Syntax: @Parse((Filename)(Portion))
 Abbrev: @PAR (Minimum)

 Breaks a filename into its component parts. The filename is supplied
 in the first argument, and an identifier specifying which portion of
 the filename to extract is specified in the second.

 The second argument must evaluate to one of the following:

 Volume    - Directs @Parse to return the volume letter (sans colon).
 Path      - Directs @Parse to return the path name.
 Name      - Directs @Parse to return the file name (sans extension).
 Extension - Directs @Parse to return the file extension (no period).

 The identifiers above may be abbreviated as desired; only the first
 character of the supplied identifier is actually significant.

 The path portion will be the empty string for the root directory -
 that is, it will never terminate in a backslash.

                                 

 Assuming that the variable 'file' has been set to the file name
 'C:\FILES\PROGRAM.EXE':

 @Parse((@Val(file))(V)) returns C
 @Parse((@Val(file))(P)) returns \FILES
 @Parse((@Val(file))(N)) returns PROGRAM
 @Parse((@Val(file))(E)) returns EXE

                                 

 If the filename does not contain the specified component, the return
 value is the empty string. Otherwise, the return value is either the
 volume, path, name, or extension portion of the given filename.

-Path

 Syntax: @Path()
 Abbrev: @PAT (Minimum)

 Returns the current path name, without a volume specifier or colon.
 The name will be the empty string for the root directory; that is, it
 will never terminate in a backslash.

-Prompt

 Syntax: @Prompt(String)
 Abbrev: @PR (Minimum)

 The string specified in the parameter becomes the next input field
 prompt, MacroMenu title, or new session title. This prompt/title is
 used by the @Edit, @Input, and @Menu macro functions, as well as by
 the program launcher.

 If the LAUNCH execution option is specified in the macro, then the
 text of the last @Prompt encountered in the macro will become the
 title of the new session.

 If the @Prompt function appears in the first column of an internal
 macro, the string is added the Execute menu as a selectable option.
 Note that this occurs only if the @Prompt function name is not
 abbreviated.

 This function has no return value.

-QuitIf

 Syntax: @QuitIf((Expression)(Message))
 Abbrev: @Q (Minimum)

 Quits the macro with an error message if the specified expression
 evaluates to empty.  The message may be empty, if desired, in which
 case no message is displayed to the user.

 Note that the given expression is merely tested; it is not returned by
 this function.

                                 

 The @QuitIf function is useful, for example, for exiting a macro that
 requires tagged files if none are tagged, as in:

 @QuitIf((@Tagged())(No tagged files))

                                 

 This function has no return value.

-Schedule

 Syntax: @Schedule(Macros)
 Abbrev: @S (Minimum)

 Schedules the macro (or macros) specified in the argument for
 execution in order of appearance. Each individual macro (including the
 current) will be allowed to complete before the next is processed.

                                 

 For example, the macro fragment below schedules the macros assigned to
 the keys V, T, u, k, and L for execution:

 @Schedule(VTukL)

 The execution mechanism will pause for user input if required by the
 particular macro being executed; an AutoKey macro which contained the
 following keystrokes would not:

 @Key(VTukL)

                                 

 Up to 255 macros can be scheduled in this manner. A macro should not
 schedule itself for execution.

 This function has no return value.

-Select

 Syntax: @Select((Expression)(Expression)...(Expression))
 Abbrev: @SE (Minimum)

 This function allows conditional macro execution by returning the
 first non-empty expression in the list.  Any number of expressions may
 be supplied.  Once a non-empty expression is found, the result is
 returned and the condition is exited; any remaining expressions are
 ignored.

                                 

 Take, for example, the following macro fragment:

 @Select((@Tagged())(@Hilited())(@Abort(No files)))

 If there are files tagged, their names are returned and the @Select
 function is exited. Otherwise, if a file is hilited, its name is
 returned and the function is exited. Otherwise, the macro is aborted
 with an error message.

                                 

 The return value of the @Select function is the first non-empty
 expression in the supplied list.

-Set

 Syntax: @Set((Variable)(Text))
 Abbrev: @SET (Minimum)

 Sets the contents of the variable named in the first argument to the
 text specified in the second.  Setting a variable to the empty string
 removes the variable from the variable heap.

                                 

 Note that variable names which begin with a dollar sign, '$', are
 treated specially. The application of the @Set function to variable
 which begins with this character implies that the text supplied in the
 second argument should not be recursively processed to remove nested
 SDE macro flags, but rather that this processing should be delayed
 until the @Val function is used to retrieve the contents of the
 variable.  This can be beneficial in rare instances where it is
 required that macro code, rather than plain text, be stored 'inside' a
 variable.

                                 

 This function has no return value.

-Tag

 Syntax: @Tag(Wildcard)
 Abbrev: @T (Minimum)

 Tags all files matching the wildcard given in the argument. The
 standard * and ? wildcard characters are supported.  This function may
 be used more than once in the same macro.

 This function has no return value.

-TagCount

 Syntax: @TagCount()
 Abbrev: @TAGC (Minimum)

 This function returns the number of tagged files, useful for verifying
 that the proper number of files are tagged for a specific application.

                                 

 This number may be effectively used in the @If<, @If=, and @If>
 comparison functions, as in the following example:

 @If=((@TagCount())(2)(fc @Tagged())(@Abort(Tag two files, please.)))

-Tagged

 Syntax: @Tagged(Portion)
 Abbrev: @TAGG (Minimum)

 Returns the specified portion of every tagged filename. The argument
 must evaluate to one of the following:

 Name      - Returns the primary filename (sans period and extension)
             of every tagged file, each separated by a space.
 Extension - Returns the extension (sans period) of every tagged file,
             each separated by a space.
 Full      - Returns the full file specification (volume, path, and
             filename) of every tagged file, each separated by a space.
 Date      - Returns the date/time stamp, in YR-MO-DY HR:MN:SC format,
             of every tagged file, each separated by a space.
 Size      - Returns the size, in bytes, of every tagged file, each
             separated by a space.

 The identifiers above may be abbreviated as desired; only the first
 character of the supplied identifier is actually significant.

 If the argument is empty, then every tagged filename, both primary
 name and extension, are returned, each separated by a space.

                                 

 For example, if the current directory is 'C:\DOCUMENT', and the
 currently tagged files are 'LETTER.DOC' and 'RESUME.FIL':

 @Tagged()  returns LETTER.DOC RESUME.FIL
 @Tagged(N) returns LETTER RESUME
 @Tagged(E) returns DOC FIL
 @Tagged(F) returns C:\DOCUMENT\LETTER.DOC C:\DOCUMENT\RESUME.FIL
 @Tagged(D) returns 89-10-23 09:56:01 90-04-16 01:20:45
 @Tagged(S) returns 127 9908

                                 

 Note that the @Tagged function generally should not be abbreviated
 when nested inside the @Write function, since the @Write function
 performs special handling on @Tagged.  See the @Write function
 description for more details.

-Untag

 Syntax: @Untag(Wildcard)
 Abbrev: @U (Minimum)


 Untags all files matching the wildcard given in the argument. The
 standard * and ? wildcard characters are supported.  This function may
 be used more than once in the same macro.

 This function has no return value.

-Upper

 Syntax: @Upper(String)
 Abbrev: @UP (Minimum)

 Returns the upper-case equivalent of the specified string. This
 function is provided for cosmetic purposes only; all SDE comparison
 functions are case-independent.

-Val

 Syntax: @Val(Variable)
 Abbrev: @V (Minimum)

 Returns the value of the variable named in the argument. If the
 variable has not been yet been assigned, or was once assigned and
 subsequently removed from the variable heap, the return value is the
 empty string.

                                 

 Note that variable names which begin with a dollar sign, '$', are
 treated specially. Normally, the text assigned to a variable is
 processed (for removal of nested SDE macro flags) at the time the
 variable is assigned via the @Set function. For a variable that begins
 with a dollar sign, however, this operation is not performed until the
 contents of the variable are retrieved with the @Val function.  This
 can be beneficial in rare instances where it is required that macro
 code, rather than plain text, be stored 'inside' a variable.

-Volume

 Syntax: @Volume()
 Abbrev: @VO (Minimum)

 Returns the volume letter (without colon) of the current volume.  This
 return value will always be a single letter in the range 'A' to 'Z'
 inclusive.

-Write

 Syntax: @Write((File)(Mode)(String))
 Abbrev: @W (Minimum)

 Writes a string to a file. The output file, named in the first
 argument, is opened using the mode given in argument two.  The
 expanded contents of the third argument will be written to the file.

 The mode argument must evaluate to one of the following:

 Write  - Open file in 'write' mode (overwrite any existing data).
 Append - Open file in 'append' mode (append to any existing data).

 The identifiers above may be abbreviated as desired; only the first
 character of the supplied identifier is actually significant.

 The @; character sequence may be used inside the output string to
 force a carriage return-line feed combination to be written to the
 file.

 Important! Never should the @Write function be nested inside another
 @Write function call.

                                 

 Note that this function handles the @Tagged function specially.  For
 example, the following macro fragment:

 @Write((file)(w)(VIEW @Tagged()@;))

 yields the following output to the specified file:

 VIEW FILE1.EXT
 VIEW FILE2.EXT
 VIEW FILE3.EXT
 VIEW FILE4.EXT

 That is, if the @Tagged function appears in the output string, then
 the entire @Write operation is repeated multiple times; once for each
 tagged file name.  Note the use of the @; character sequence (see the
 topic 'Special @ uses' below) to force a carriage return-line feed
 combination into the output file between each instance of the output
 string.

 This special handling is only performed if the full function name
 @Tagged function appears in the output string; it is not if the
 function name is abbreviated.

 If this special treatment of the @Tagged function is not desirable,
 you may:  (1) abbreviate the @Tagged function name, or, (2) assign the
 @Tagged function return to a variable and reference the contents of
 the variable inside the output string, like this:

 @Set((tagvar)(@Tagged())) @Write((file.ext)(w)(VIEW @Val(tagvar)))

                                 

 This function has no return value.

-Special @ uses

 The '@@' character sequence causes a single '@' character to be
 inserted into the expanded macro. This is used if a program being
 called by a macro requires a '@' in its argument list, or if a file
 name that contains an embedded '@' is hard-coded into a macro, as in:

 EDIT @@file.doc

                                 

 The '@;' character sequence causes a carriage return/line feed
 combination to be inserted into the expanded macro. This is most
 commonly used in the output string of the @Write function to write two
 or more lines to the specified output file per instance of the
 function, as in:

 @Write((test.fil)(w)(This is line one@;This is line two@;))

+Notes

-Having problems?

 For network users: If the /v startup parameter is not supplied, SDE
 may appear to lock up when the 'Volume' option is selected if a
 network server you are attached to has gone off-line since log-in.  If
 this should happen, allow SDE to time-out, then quit and re-start SDE
 with the /v option.

 The video modes supported by SDE are those supported by the IBM PS/2
 VGA adapter under Version 1.2 of OS/2. Other adapter/version
 combinations may not support all modes.

 KEDIT Version 4.00P1 has a bug which prevents it from properly
 accepting a filename parameter if executed directly from SDE (i.e. if
 the CMD or LAUNCH execution option is not specified in the macro).

 SDE will abort if used in a directory that contains more than 1300 or
 so files. The exact number will vary depending on the system
 configuration.

-Registration

 To receive a personalized copy of SDE, please send $50.00 and a blank
 disk to the address at the top of the SDE.HLP file. Include a one-line
 personal and/or company name (up to 60 characters) to be embedded in
 your copy of SDE. SANSoft will return the most recent version of SDE,
 personalized as requested.

 Contact SANSoft Development for site licenses or volume purchases of
 SDE.

-Distribution

 SANSoft Development retains the sole right to sell the SDE package. The
 SDE package may, however, be distributed, as long as:

  All program files are distributed unmodified, and en masse.  Please
   distribute the archived form of the SDE package if at all possible.
  The original version is distributed, NOT personalized copies of SDE.
  No attempt is made to profit from the distribution of the SDE
   Environment, or any modification of it, although a duplication fee
   not to exceed $10 may be charged by recognized user's groups.

-Warranty & Disclaimer

 SANSoft Development hereby disclaims all warranties relating to this
 software, whether express or implied, including without limitation any
 implied warranties of merchantability or fitness for a particular
 purpose. SANSoft Development will not be liable for any special,
 incidental, consequential, indirect or similar damages due to loss of
 data or any other reason, even if SANSoft or an agent of SANSoft has
 been advised of the possibility of such damages. In no event shall
 SANsoft Development's liability for any damages ever exceed the price
 for the license to use the software, regardless of the form of the
 claim. The person using the software bears all risk as to the quality
 and performance of the software. Use of this package constitutes
 agreement on the part of the user to this disclaimer.

