OS/2 Professional

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Professional / OS2PRO194.ISO / os2 / prgramer / systemax / sde.doc < prev next >

Wrap

Text File | 1990-08-07 | 59.4 KB | 1,273 lines

======================================================================= SDE - THE SYSTEMAX DEVELOPMENT ENVIRONMENT FOR OS/2 ======================================================================= SysteMAX Development Environment Copyright (C) 1990 SysteMAX Corp. SysteMAX Corp. 12 Westerville Square - Suite 160 Westerville, Ohio 43081 Voice-mail: (614) 447-7038 MCI Mail: SysteMAX ======================================================================= DESCRIPTION ======================================================================= SDE is a file and directory management system and application launcher for OS/2. Its rich macro language is well suited to launching editors, compilers, file-browsers, string-search utilities, and the like. SDE's ability to launch programs in the foreground or background with a single keystroke, the MacroMenu feature - one which allows you to create pop-up menus within a macro, and Autokey keystroke recorder are just a few of the features which make SDE a powerful environment for OS/2 users and developers. For those of you who have used similar utilities before, you should have no trouble tapping SDE's power. If you haven't, SDE's menu-driven interface and context-sensitive help facility should get you up and running in short order. ======================================================================= NEW FEATURES ======================================================================= Version 1.3.0: When a MacroMenu menu is displayed, pressing the first letter of the option's title will select that option as if you had moved the hilite bar to that option and pressed Enter. If two options start with the same character, the first one is selected. The Home and End keys now work differently. When pressed once, the hilite bar is moved to the top/bottom of the current column. When pressed again, the bar is moved to the first/last file on the current page. Press again, and the bar is moved to the first/last file in the current directory. When moving files and copying files to a directory on the same volume, the hilite bar on the directory tree is updated to point to the destination directory (the one to which the files were moved/copied). This makes switching to that directory much easier (two keystrokes, Esc+Enter). In edit fields, the Ctrl-Left and Ctrl-Right keystrokes can now be used to move the cursor 5 characters to the left and right respectively, allowing you to quickly scroll through large edit fields. Version 1.2.3: When the "Volume" menu is displayed (either by pressing Ctrl-V or by selecting "Volume" option from the "Select" menu), you may press the key associated with the desired drive letter to select that drive (e.g. press "C" for the C drive, "D" for the D drive, etc.). After selecting the "Edit macro" option from the "Macro" menu, you may now select a macro to edit by pressing the macro key on the keyboard (e.g. when the macro popup menu is displayed, press the "R" key to edit the "R" macro). When first starting this version, you may notice an immediate difference. The file names (and directory names in the directory tree) will probably appear in lower case letters. There is a new option in the "Misc" menu which allows you to select wheter these names should be displayed in upper or lower case. Your selection will be saved in the configuration file and used by SDE until this setting is changed. Version 1.2.2: The 'Locate' function now remembers the text you enter into its input field. The 'Locate' operation may now be canceled with Control-Break. The Autokey recorder no longer generates the %Q flag when recording keystrokes, since %Q is no longer required (and not desirable in sub-macros). Shows the hilited file's attributes in the status line. The characters 'hsra' are displayed if the respective hidden, system, read-only, and archive bits are set. If not set, a dot appears in place of the character. Version 1.2.1: Options for setting the number of screen lines and mouse speed have been added to the 'Select' pulldown menu. Now enables you to change the disk-write verification mode using the 'Verify' option in the 'Misc' menu. When 'Verify' is on, all data written to disk is checked for integrity. When off, no such check is performed. The back-quote '`' key (below the Esc key) can be used to display the current directory key settings (0 through 9). The 'Copy/Move/Delete tagged' operations, as well as the 'Tag/Untag all containing' operations, may now be canceled with Control-Break. When tagging/untagging files with the mouse in previous versions, some files would be skipped if the mouse was dragged too quickly. This limitation of the mouse driver has been worked around; all files between the start and finish point of a mouse drag will now be tagged/untagged appropriately. The program has been patched to handle differences between native OS/2 file functions and AS/400 shared-folder drivers. The net result is that SDE can now be used on AS/400 shared folders. Improves numeric legibility by displaying file size on status line delineated with commas. Also displays file counts and sizes with commas in 'File Information' dialog. Most lengthy operations, such as directory scanning, file copying, etc. will now begin with a 'Please Wait' dialog. The 'Copy/Move/Delete tagged' operations, as well as the 'Tag/Untag all containing' operations, now display their progress in bar-graph form. The 'Delete tagged' function may be activated with the Delete key as well as the Alt-D key combination. Some minor changes have been made to the %t and %T macro flags. If there are tagged files, their names will be inserted into the macro normally. If, however, there are no tagged files, the name of the hilited file is inserted into the macro. If this effect is not desirable for a particular macro, you should add the %A (abort if none tagged) option to the macro. You may now specify a full path and file name when duplicating a file. If you do not specify a path, the file will be duplicated in the current directory. During a 'Copy tagged' operation, if you choose the option to copy files to a directory on another volume, you may now specify just a drive letter, as in 'h:', to copy all tagged files to the default (current) directory of the 'h:' drive. Previous versions would interpret 'h:' to mean the root directory of that volume. There is a new line in the 'Information' dialog. The 'Tree' line will display the count and cumulative size of any files in the current directory as well as any child directories of the current directory. Pressing the Shift-Tab key combination will bring up this dialog without the Tree information. Version 1.1.0: Now contains the nested MacroMenus capability. Your MacroMenu options may now contain MacroMenus of their own, nested to any depth. The only restriction is the 255 character macro limit. Version 1.0.0: Original release. ======================================================================= SDE FILES ======================================================================= SDE was originally packaged with the following files. If you are missing one or more of these files, please retrieve a complete copy from your favorite RBBS. If you have difficulty obtaining a complete SDE package, please contact SysteMAX Corp. at the address above. SDE.EXE - The SDE executable program. SDE.DOC - This document. SAMPLE.MAC - A sample macro file. REGISTER.FRM - A single-user SDE registration form. REGISTER.SIT - A site-license SDE registration form. PERSONAL.EXE - A utility to personalize your copy of SDE. HEXEDIT.EXE - An ASCII/EBCDIC/HEX file and disk editor. RPNCALC.EXE - A Reverse Polish Notation calculator. ======================================================================= LIMITED-FUNCTION SHAREWARE VERSION ======================================================================= While the SDE system supports 52 macros (a..z, A..Z), the shareware version distributed by SDE only allows six (a..c, A..C) to be used. All other features of the SDE system are completely functional. Once you complete the appropriate registration form (REGISTER.FRM or REGISTER.SIT), send in your registration fee, and receive registration confirmation from SysteMAX Corp., you will be authorized to run the PERSONAL.EXE personalization utility to customize your copy of SDE and remove this six-macro restriction. Do NOT run this program without prior authorization from SDE - your copy of SDE may be damaged! ======================================================================= SYSTEM REQUIREMENTS ======================================================================= SDE requires the following hardware/software: OS/2 Version 1.1 or higher. An IBM PS/2 or other OS/2 compatible 286/386 machine. An IBM VGA or compatible video adapter. An OS/2-supported mouse and appropriate OS/2 driver. While SDE has been subjected to rigorous testing on many different computers, it has obviously not been tested on every possible hardware configuration. We encourage you to report incompatibilites, so that modifications can be made to future releases. ======================================================================= INSTALLATION ======================================================================= To install SDE on your hard disk, perform the following steps: Pick or create a directory on your hard drive for SDE. Copy the SDE files listed above to that directory. Edit your CONFIG.SYS file, and add the statement: SET SDE=D:\PATH where 'D' is the drive and 'PATH' is the path to which you copied the SDE program. Add the SDE path to your PATH statement. Reboot, to make your new CONFIG.SYS take effect. Add SDE to your Start Programs menu, or start SDE from the command line by typing SDE. If you choose to start SDE from Start Programs, you may run SDE in either full-screen or PM window mode. Everything is, we hope, fairly self-explanatory, so you should be able to get right to work. To get help at any time, press the F1 key. ======================================================================= PARAMETERS ======================================================================= SDE has a built-in screen blanker which blacks out the screen after 5 minutes of keyboard and mouse inactivity. Moving or clicking the mouse, or pressing a key, will reset the video to its previous state. To activate this feature, start the program with a command-line option of /b or /B. This feature is only useful in full-screen mode, since under PM, only the application's window is blanked. ======================================================================= THE MOUSE ======================================================================= SDE supports the mouse for all operations save color selection. The mouse can be used to select pulldown menus and options within them, to select choices from popup menus, and to tag and untag files. Clicking the left mouse button moves the hilite bar to the file name beneath the mouse pointer and tags or untags the file. Clicking the right mouse button moves the hilite bar in a similar fashion, but the file is not tagged/untagged. When tagging/untagging files, please note that the OS/2 mouse driver may not keep up if you press the mouse button and drag the mouse too quickly, especially when one of the faster mouse speeds is used. Some files along the way may be skipped. Click the mouse on these files again should this happen. ======================================================================= STATUS LINE ======================================================================= The current directory name, hilited file date, time and size, and the system time are all displayed on the bottommost row of the screen. When moving the hilite bar with the arrow keys, the file information is updated immediately. Otherwise this information is updated along with the system clock once every second. If you are viewing a directory that has a very long path name, the first and last twenty or so characters of the path are displayed, separated by an elipsis... More detailed file and directory information is available in the 'File Information' dialog. ======================================================================= MACRO INTRODUCTION ======================================================================= Macros are the heart (or, more precisely, the personality) of the SDE system. They allow you to launch any program from SDE with a single keystroke. If you choose your macros wisely, and assign them to keys you can easily remember, working in the SDE environment will soon become second nature. When a macro is executed, the SDE macro processor searches your macro for parameters that begin with a percent '%' sign. SDE will take various actions depending on the character which follows %. Wherever possible, this letter has been made a mnemonic of the function the flag performs. The macro processor IS case-sensitive as far as macro flags are concerned. Note: Unless explicitly stated otherwise in the description of the macro flag, all macros flags are operated on immediately (before any program that the macro may call) in the order that they appear in the macro. Here are some sample scenarios in which macros can greatly simplify the task of executing programs. ========================= Let's assume your editor of choice is Q.EXE. Let's also assume your PATH statement in CONFIG.SYS is set up so that it points to the directory where the Q.EXE program resides. The 'q' key on your keyboard can be set to edit all tagged files using the macro: q %t ========================= If you have a program named VIEW that displays files, you can make the 'v' key list all the tagged files with a similar macro: view %t %A The %A (abort if none) parameter ensures that VIEW is not started unless at least one file is tagged. ========================= Let's say you want to jump into a directory and edit all the 'C' language source code files there. You could make the 's' key (for source) do this using the macro: %-*.* %+*.c %+*.h %Xq This macro uses the %- (untag) parameter to untag all files, then uses the %+ (tag) parameter twice to tag all the .C files and then all the .H files. The macro then uses the %X (expand into) flag to add the contents of the macro 'q' to the current macro. Since 'q' was set up to edit all tagged files, all .C and .H files in the current directory will be fed to the Q.EXE editor. Alternately, you could have manually entered the contents of the 'q' macro into this macro, but %Xq is simpler, and requires no changes if the 'q' key macro is edited. Note: The %X flag is primarily intended to be a bridge between side-effect macros (tag-only, for example) and macros which perform an external function (like 'v', which starts an editor). ========================= Some programs handle long file lists (50 or more files) quite well. SDE can, by the way, send up to 8192 bytes worth of command-line data to an application. Some, however, don't handle multiple filenames as input parameters. For these applications, use the %h flag to feed the filename of the hilited file to the program. ========================= If you make projects using the MAKE utility, you could use the 'm' key to execute MAKE thusly: make %n %W The %n (name only) parameter feeds the filename of the hilited file (without an extension) to MAKE. In this way, you can point to any file in your project that has the same primary name as your make file, press the 'm', key, and start MAKE. The %W (wait with prompt) flag makes sure that you don't miss any compile errors by pausing the display until you press a key or click the mouse button. To start MAKE in the background, use the following macro: make %n %L ========================= Making use of the %<?> (comment/prompt) flag is a simple 'p' macro for printing. It reads: print %h %<Print hilited file?> %C The text appearing between the <>'s acts as both a macro comment and as a prompt. This string is read by the %C (confirm) parameter, so that when the 'Continue/Abort' pop-up menu is displayed, the menu has the title 'Print hilited file?' The macro below performs the same function, but demonstrates that the string appearing between the angled brackets is also expanded by the macro processor. print %h %<Print %h?> %C ========================= The GREP utility can be used to locate occurrences of text strings in multiple files. The 'g' key can be made to perform this search using the macro: grep %<Search for...> "%I" %t %A %W Again, a prompt has been established with %<>. The %I (forced input) flag causes SDE to ask the user for input, and will abort the macro if nothing is entered (use %i if you want execution to continue in this case). The input box will have the title 'Search for...', since it, like the 'Continue/Abort' menu, reads the prompt string. The input is encased in double quotes in case the input might contain blanks - in this way, GREP reads the string as a single command-line parameter. The name of each tagged file is appended to the macro - the %A flag makes sure you don't try to search an empty file list. The %W allows you to view the output of GREP before returning to SDE. Note: SDE can search for text strings inside non-binary files. See the description in the NOTES section below. ========================= Let's assume your text editor creates backup files of anything you edit, and also assume the backups always have an extension of .BAK. You can clear your disk of these backups using the following macro: del *.BAK %R %c The %R flag causes SDE to repeat the macro in every directory. Since 'del' is an OS/2 command, not an executable program, the %c must be supplied so that the expanded macro will be fed to the command processor (which is, by default, CMD.EXE). ========================= Some of the programs that do not accept multiple filenames on a command line do accept a single filename parameter which represents a list of files to be processed. You can still send multiple filenames to these programs using the %o and %O macro flags. These flags write the names of all the tagged files, one per line, to the file that appears directly after the flag. Take, for example, the macro: SEARCH %Osearch.lst @search.lst It first erases the file 'search.lst', if it exists, and then writes the name of each tagged file to the file 'search.lst'. The @search.lst parameter is not a SDE flag (because it does not begin with a percent sign), but is instead a parameter for the SEARCH program which tells it that the names of the files to search are contained in the file 'search.lst'. When using %O and %o, the output file is written to before the program called by the macro is executed. The %O flag overwrites the previous contents of the file; the %o flag appends output to the file. ========================= The OS/2 RECEIVE command downloads a file from a host to the PC. In most cases, the file you download will retain the same name on the PC as it does on the host, aside from system file-naming differences. Making use of this assumption is the following macro for the RECEIVE program, which places the contents of the 'PC file name' user input field into a variable named 'r'. The 'Host file name' user input field will automatically be filled with the contents of 'r' when the macro is executed. All you need to do is edit a few characters of the 'Host file name' field, as opposed to typing the entire file name. RECEIVE %<PC file name?> %Ir VMB:%<Host file name?> %Ir %l The program is launched in a separate screen group with the %l flag, which means the file transfer proceeds in the background while you continue working in SDE (or any other program you execute). ========================= Here is a good example of the power of the SDE macro language; a slick 'side-effect only' macro (note that it calls no program). It catalogs the name of every executable program on your hard disk to a file named EXELIST in the root directory. %-*.* %+*.EXE %f\EXELIST %R Just in case you had some files tagged prior to running this macro, the macro untags them with %-*.*. A macro of similar form could catalog source files or data files; the resulting list could then be fed to a program for processing. ========================= If you have a need to run one macro after another, this can be accomplished with the %x macro flag. Simply list the macros to be executed, in the order they are to be executed, after the flag like so: %xTvLqw Note: Up to 255 macros can be scheduled in this manner. ========================= If you want standard (teletype) output to appear in colors other than those in your file list, use the %s and/or %S flags in your macro. These flags must be followed by one of the following color names (case is not significant): BLACK RED GREEN YELLOW BLUE CYAN MAGENTA WHITE For background colors (%S), the color name always specifies a dim color, but foreground (%s) color names may be suffixed with the '+' symbol to specify a bright color, as in: %SBLACK %sMAGENTA+ If you really want to go crazy, you could have different color sets for every program you execute from SDE by using these two flags (providing that the application writes to STDOUT, and doesn't change those colors itself). ======================================================================= AUTOKEY MACROS ======================================================================= An Autokey macro is one that contains recorded keystrokes rather than text commands. To create an Autokey macro, select an unused macro letter from the 'Edit macro' menu. In the input field, enter a question mark '?' and press Enter. SDE will then be in Autokey recording mode. Any keys you press, up to but not including the Ctrl-End combination, will be saved under the key of the macro being edited. Note that your keys are merely being recorded, they will have no immediate effect on the program. There is a limit of approximately 35 keystrokes for each macro key. When you press the macro key on the keyboard, the macro processor will place the keystrokes you recorded for that macro into the SDE keyboard buffer just as if you were typing them directly. Autokey macros will look odd in the 'Edit macro' menu (you will see the private %K flag in use). If an Autokey macro causes an external application to be executed, any pending keystrokes in the macro will be saved until that application terminates. For this reason, standard macros that are to be called by an Autokey macro should not use the %w or %W option, since either will cause the SDE keyboard buffer to be flushed. ======================================================================= MACROMENUS ======================================================================= The MacroMenus feature significantly boosts the power of the SDE macro language. Within a macro, you can build a popup menu with up to 10 options, and take conditional action based on the menu selection. To build a MacroMenu, use the %[ macro flag. The format of the data for the flag is as follows: %[Option{String}Option{String}...Option{String}] 'Option' represents the option text that will appear in the popup menu, and 'String' represents the text that will be inserted into the expanded macro should that option be selected. The title of a MacroMenu will be the prompt established by the %<?> parameter, or 'Macro Options' if none. For example, the OS/2 SEND command is used to transfer files from a PC to a VM host. The parameters required for SEND vary, depending on whether the file being transferred is a binary file or text file. Without MacroMenus, two macros would be required for sending files to the host; one for binary files, and another for text files. These macros would read something like: SEND %h VMB:%n %e A1 %W (for binary files) SEND %h VMB:%n %e A1 (CRLF ASCII %W (for text files) These two can be combined into one macro (like the one below), but the exact options, spelling, order, etc., of the parameters expected by the SEND command would have to be remembered. SEND %h VMB:%n %e A1 %i %W A better solution than either of the above is the following macro: SEND %h VMB:%n %e A1 %<File type?> %[Binary{}Text{(CRLF ASCII}] %W This macro builds and displays a MacroMenu. The %< flag establishes an input/menu prompt so that when the menu is displayed, it will have the title 'File type?'. The first option in the menu will be 'Binary', and, if chosen, the string appearing between the following curly brackets will be inserted. Since nothing appears here, nothing will be added to the expanded macro if this option is selected. If option two, which reads 'Text', is selected, the string '(CRLF ASCII' is appended to the macro. Each option in a MacroMenu must be followed by a string enclosed in curly brackets, even if that string is empty. A close bracket ']' must follow the curly close bracket '}' of the last command string of the last option in the menu. Up to ten options may be so specified. MacroMenu options may themselves contain MacroMenus, if desired. ======================================================================= EXECUTE MENU ======================================================================= The 'Execute' pulldown menu shows you the names of selected macros, and allows you to select a macro directly from this menu. When you first look in the Execute menu, you will probably see the non-selectable message 'No macros'. To remedy this and add a macro to the 'Execute' menu, simply edit an existing macro and enter a comment that begins in the first character of the macro input field. A macro comment looks exactly like a macro prompt and uses the %<?> macro flag. If you already have a macro with a comment/prompt that begins in the first character of the macro, and you don't want the title of the macro to be entered into the 'Execute' menu, just edit the macro and add a space before the %< flag that begins the comment/prompt string. The first twenty or so characters of your title will be added to the 'Execute' menu as an option. The accelerator key for the option will be the key that triggers the macro. Here is the GREP macro with an 'Execute' menu title: %<GREP string search> grep %<Search for...> "%I" %t %A %W %c Autokey macros may also be displayed in the 'Execute' menu. You must must re-edit the Autokey macro after a recording session, and place your title at the front of the macro. Avoid using macro flags in the 'Execute' menu titles, since flags are only expanded at run-time. Also avoid using the tilde '~' character in titles. Titles must NOT begin with a hyphen '-'. ======================================================================= MACRO IMPORT/EXPORT ======================================================================= The 'Import macros' option allows you to read a set of macros from a text file. Each macro in the file must have the form: X - MACRO TEXT X represents the key to which the macro is to be assigned, and MACRO TEXT represents the actual macro. The macros may appear in any order. The maxumim length of an imported macro is 255 bytes. Your Execute menu will automatically be updated to reflect the titles of your new macro set. A macro file must be a standard text (ASCII) file and end with the extension '.MAC'. When you select the Import option, you will be prompted for a macro file name. Enter only the primary name of the file (8 characters maximum); the extension '.MAC' will automatically be appended. The file will be read from the SDE program directory. If your current macro set has changed since the last Export, you will be asked if you want to save (Export) the changes to your macro set. The 'Export macros' option allows you to write your current macro set to a named file. This file can be edited with an ASCII text editor, if necessary, and read back in with the Import feature. Be sure that any macros you add/edit have the form shown above. As with the Import option, enter only the primary name of the macro file when prompted for the name; the extension '.MAC' will be appended automatically. The file will be written to the SDE program directory. ========================= This pair of features allows you to create custom macro sets for working in two or more environments. If, for expample, you frequently work with two different programming lanugues and the utilities you use while working with one language are different from those you use while working with the other, create two sets of macros; one set of macros tailored for one language, and another set for the other language. As you switch between programming languages, you can completely change the 'personality' of your SDE environment in seconds by importing the appropriate macro set. ========================= Note! Some editors may not allow you to edit files with lines 255 bytes long, others may truncate such a line. For this reason, avoid using the maximum space in the macro edit field, and maximum-length Autokey macros, if you experience this problem with your editor. ======================================================================= ADVANCED MACRO TOPICS ======================================================================= The SDE macro processor recursively processes macro commands. In human terms, you may supply a SDE macro flag in place of a hard-coded text string, as in the following expamples: %OFILE.LST (Output tagged filenames to a file named FILE.LST) %O%I (Ask the user for the name of the output file) %(Init) (Tag all files containing the string 'Init') %(%I) (Ask the user to input a search string) %\\SOURCE (Change the current working directory '\SOURCE') %\%I (Ask the user to input a path) %+*.DOC (Tag all files which match the wildcard *.DOC) %+%I (Ask the user to input a wildcard) %-*.* (Untag everything) %-%I (Ask the user to input a wildcard for untagging) %<Edit hilited?> (Hard coded input/menu prompt) %<Edit %h> (More meaningful input/menu prompt) During the processing of an input flag, %i or %I, you may enter macro flags in the input field. If, for example, you are prompted by a macro to input a filename, you may type '%h' to automatically enter the filename of the hilited file. (You could also enter %I for input, and you would be asked once again for input, and you could again type %I, and so on, ad infinitum, until you run out of memory, but that would be silly...) The macro processor also expands the command strings in MacroMenus. Depending on the menu selection, your macro could search tagged files, hilited files, or prompt the user for input as in the following example: LIST %<Which files?> %[Tagged{%t %A}Hilited{%h}Other{%<Filenames?> %I}] Note: MacroMenu options themselves are NOT expanded in this manner, only the command strings that appear between the {}'s in a MacroMenu. ========================= Macros may contain a simple form of a subroutine that is probably best called a 'sub-macro'. Take, for example, a compile macro which would prompt you for the options to use during a compile. There are several combinations of options that would lead to redundant macro 'code'. This can be alleviated by dedicating a macro key to act as a sub-macro. cl %<Memory model?> %[Small{/AS %Xz}Medium{/AM %Xz}Large{/AL %Xz}] The macro fragment above uses a MacroMenu to allow you to choose a memory-model at run-time. The %X flag appears in each command; its function is to take the contents of macro 'z' and insert them into the current macro. If the macro for key 'z' reads: %<Codeview?> %[No{}Yes{/Zi}] then the 'Codeview?' MacroMenu will appear no matter which memory model is selected. There are no limits as to the number of sub-macros that can be called from a single macro, but bear in mind that each sub-macro occupies one macro 'slot'. ========================= The SDE macro flags %i and %I may be suffixed with a single character variable name. There are 52 'variables' available for these two flags named 'a'..'z' and 'A'..'Z' (not to be confused with the 52 macros having the same letters; any variable can be used in any macro). Example: If you suffix an input flag with a variable, as in %Ia, any input typed into the input field when the macro is executed will be saved under the variable 'a'. When the next macro (or an input field that occurs later in the same macro) that uses %Ia is executed, the contents of 'a' will be placed in the input field by default. This implies that any macros which use %i or %I that do not use an input variable must have a blank immediately following the flag. ======================================================================= SAMPLE MACRO FILE ======================================================================= Included with the archive of SDE is a file called SAMPLE.MAC. Please note that these sample macros may not be indentical to the examples in this document. To look at these macros, you will need to perform the following steps: Select the 'Import macros' option from the 'Macro' menu. Type SAMPLE in the input field when prompted for the Import filename. Select the 'Edit macro' option from the 'Macro' menu to view the macros. Open the 'Execute' menu to view selected macro titles. Please note that the programs run from this sample macro set may not be present on your system! ======================================================================= COMPLETE MACRO FLAG DESCRIPTIONS ======================================================================= Many of the flags below are order-independent; they may appear anywhere in the text of the macro. The ones that are position-dependent are those that actually insert text into the expanded macro; the order in which these appear in the macro is dependent on the order in which the application being called expects the text that the flag inserts. %a - If no file is hilited (i.e. there are no files in the current directory), then the macro is aborted immediately upon reaching this flag. %A - Same as %a, but the macro is aborted immediately if no files are tagged. %b - Beeps the PC's speaker after the program called by the macro terminates. %c - Uses the default command processor (CMD.EXE) to execute the program versus direct execution. Use this flag when executing: (1) Programs written for Presentation Manager (or use %l), (2) Programs that may require Control-Break or Control-C, (3) Programs whose output is being redirected. %C - Confirms the execution of a potentially dangerous macro by displaying a 'Continue/Abort' menu. The title of the menu is, by default, 'Continue macro?', but may be changed with the prompt flag, %<>. %d - Used primarily for debugging, this flag dumps the expanded macro to the screen instead of executing the macro. %D - Rescans the current directory after macro execution (the directory is not rescanned by default). Use this flag when the execution of a macro will result in the creation or deletion of files. %e - Inserts the extension (sans period) of the hilited file. For example, 'README.DOC' will be reduced to 'DOC' in the expanded macro. %E - Displays the process termination/error codes of the program being executed. Try using this flag if a program is abending prematurely. This flag is not useful in combination with the %c flag, since the error codes being reported will be those of the command processor and NOT those of the program being executed. %f? - Writes the full file specification of each tagged file to the filename which immediately follows %f. If this is not the last flag in the macro, then a space ' ' character must follow the filename. The specified file is appended to. %F? - Same as %f, but the file is overwritten vs. appended to. %G - Inserts the drive letter (e.g. 'C:') of the current drive into the expanded macro. %h - Inserts the currently hilited filename into the expanded macro. %H - Inserts the full file specification of the hilited file into the expanded macro. %i - Displays an input field for a user-supplied parameter or parameters. Whatever text you type is first expanded (if it contains any % macro flags) and then inserted into the macro. This flag may be suffixed with a single-character 'variable' name in the range 'a'..'z', and 'A'..'Z'. The contents of the variable will be retained until SDE is exited. %I - Same as %i, but the macro is aborted if nothing is entered into the input field. %K - Used exclusively by the Autokey function, this flag pushes the keystroke represented by the next four bytes into the SDE keystroke buffer (not the OS/2 keystroke buffer). If you REALLY (italisize that) need to push a keystroke within a macro, follow these steps: (1) Use a utility which displays OS/2 keystroke character and scancode values and record these two values for the key to be inserted. (2) If the character code is 0x00 or 0xE0, then the SDE keystroke value will be 0x2000 plus the scancode value, otherwise, the SDE keystroke value is the character code itself. (3) Suffix the %K flag immediately with the SDE keystroke value in hexadecimal, padded with leading zeros to four digits if necessary. Omit the usual 0x hexadecimal prefix. (4) Add a space to the end of the %Kxxxx sequence if it is not the last flag in the macro. (5) If you are pushing multiple keystrokes, keep in mind that the SDE keystroke buffer is LIFO, so push keystrokes in REVERSE order. %l - Launches the macro in a separate screen group. The new session will be closed after the program terminates. Post-execution macro flags (including %E, %D, %V, %w, and %W) will be ignored if this parameter is given. Batch files may NOT be launched with this option, since applications are launched directly by SDE. This flag can be used to execute PM programs. %L - Launches the macro in a separate screen group. The new session will remain open after the program terminates. Post-execution macro flags (including %E, %D, %V, %w, and %W) will be ignored if this parameter is given. Batch files may be launched with this option, since the default command processor is used to launch the application. %n - Inserts the filename (sans period, sans extension) of the hilited file into the expanded macro. %o? - Outputs all tagged filenames to the file whose name directly follows %o. The file ? is appended to. Extremely useful for executing arcane programs that do not accept multiple filenames as parameters but do accept a single filename parameter which contains a list of file names (sometimes prefixed with a '@' and referred to as an 'at' file). %O? - Same as %o, but the target file is overwritten vs. appended to. %p - Inserts the current path (without a drive specifier) into the expanded macro, as in '\SOURCE\PROGRAMS'. %P - Inserts the current path (including the drive specifier) into the expanded macro, as in 'C:\SOURCE\PROGRAMS'. %Q - The macro is aborted immediately when this flag is encountered. This flag is not required in macros executed purely for side-effect (tag-only macros, for example). This flag is useful in MacroMenus where one of the menu options calls for the macro to be terminated. %R - Repeats the macro in every directory on current volume. The macro is re-processed on entry to each directory, so it is safe to use tag/untag macro flags, flags which insert the filenames of hilited/tagged files, etc. %s? - Sets the teletype (stdout) foreground color to the color name specified in place of ?. May be suffixed with '+' to indicate a bright color. After the program terminates, the default colors are automatically restored. %S? - Sets the teletype (stdout) background color to the color name specified in place of ?. See above. %t - Inserts the filename of each tagged file into the expanded macro, each separated by spaces. If there are no tagged files, the name of the hilited file is inserted. %T - Inserts the full file specification of each tagged file into the macro, each separated by spaces. If there are no tagged files, the full filespec of the hilited file is inserted. %V - Rescans the current volume after macro execution. Use this flag if the program you are calling will create/delete directories. %w - Causes SDE to wait for a key or mouse click after program execution. No message is displayed. %W - Same as %w, but a 'Click mouse or press a key to continue...' prompt is displayed. %x? - Schedules the macro (or macros) specified in place of ? for execution in order of appearance. Each individual macro will be allowed to complete before the next is processed. The macro '%xVTukL' schedules the macros V, T, u, k, and L for execution. The execution mechanism will pause for user input if required by the macro being executed (an Autokey macro which contained the keystrokes 'VTukL' would not). %X? - Expands the contents of macro ? into the current macro. This flag is useful when used in a side-effect macro (one that tags files, for example) to chain execution to another macro (one that causes a program to be executed). %\? - Changes the current working directory to the path given in place of the ?. This backslash is NOT part of the path. For example, '%\\SOURCE\PROG' changes the CWD to the path '\SOURCE\PROG'. To specify the root directory, use %\\. The current directory (prior to macro execution) will be restored when the program terminates. Do not supply a drive letter; you cannot change the default volume with this flag. %<?> - Any string may replace ?. The string becomes the next input field prompt or menu title. If the flag appears in the first column of the macro, the string is added the the Execute menu as a selectable option. The prompt is expanded at run-time if it contains any SDE macro flags (flags are not expanded in the Execute menu). %+? - Tags all files matching the wildcard given by ?. The standard * and ? wildcard characters are supported. This flag may be used more than once in the same macro. The wildcard must be followed by a blank if it is not the last parameter in the macro. %-? - Untags all files matching the wildcard given by ?. Otherwise, the same as %+. %[?] - Builds a MacroMenu. The data following the flag has the form: '%[option{command}option{command}...option{command}]'. See the MacroMenu topic above for a detailed description of MacroMenus and their applications. %(?) - Tags all files containing the string which appears in place of the question mark. The search string must not contain parentheses, although an input parameter may be placed between the parentheses, as in %(%I), in which case the input is allowed to contain parentheses. %{?} - Untags all files containing the string which appears in place of the question mark. The search string must not contain curly brackets, although an input parameter may be placed between the brackets, as in %{%I}, in which case the input is allowed to contain {}'s. %2 - Puts the display in 25 line mode prior to program execution. The current video state is saved and then restored after the program terminates. %4 - Puts the display in 43 line mode prior to program execution. See the %2 flag. %5 - Puts the display in 50 line mode prior to program execution. See the %2 flag. %@ - Supresses the default screen-clear prior to program execution. Useful only for programs that redraw the entire screen on entry. %! - A nifty, if otherwise useless, way to clear the screen prior to program execution. %% - Inserts a % into the expanded macro, if one is required. ======================================================================= INPUT FIELD EDITING KEYS ======================================================================= When editing a macro (or entering text in any SDE input field), you may use the following editing keys: Insert - Toggles insert/overtype mode Backspace - Deletes character to left Delete - Deletes character beneath cursor Home - Moves cursor to first character End - Moves cursor to end of text Ctrl-Backsp - Deletes to end of field Left - Moves cursor to left Right - Moves cursor to right Esc - Cancels input and any changes Enter - Accepts any changes F1 - Displays help panel(s) ======================================================================= NOTES ======================================================================= The SDE default color set may not be ideal for use on monochrome or gas-plasma displays. If the appearance is not to your liking on start-up, press F4 to enter the color selection panel, and select colors appropriate for your type of display. ========================= The 'Tag/Untag all containing' options in the 'Select' menu allow you to tag/untag files which contain a user-supplied search string. The search mechanism has been optimized for text-file searches and IS case-sensitive. The known binary file types ZIP, ARC, OBJ, EXE, LIB, and DLL are excluded from the search. The search string may contain whole or partial words, as well as blanks, and may be up to 254 characters long. Note: There is a known limitation of the search algorithm implemented in this release of SDE. If the file being searched is larger than 65024 (2^16-512) bytes, and the search string happens to span a byte offset in the file which is a multiple of 2^16-512, the search will return negative. This limitation is not likely to cause many problems (the chance of a missed match for an 8 character search string in a 195Kb text file is less than one in ten thousand), but will be fixed in a forthcoming release. ========================= A directory cannot be removed or renamed if it contains an open file or is the default path for another screen group. ========================= The macro processor has limited error checking built in. If it detects an error in the format of the macro, it will most likely refuse to execute the macro (nothing will happen when you press the macro key, even if the %d (debug) flag is specified). With some syntax errors, however, garbage may be inserted into the expanded macro. These errors can be detected with %d. ========================= Only one executable program can be called per individual macro. However, in a MacroMenu, a single macro can be written to call one of several programs depending on the option selected from the menu. ========================= The maximum length of an expanded macro is 8K bytes. An SDE protection violation error may occur if you attempt to pass more than 8K of data to an application. This translates to approximately 600 file names that can be passed to an application. Please note that some applications may have lower internal limits, and may issue errors if these limits are exceeded. ========================= If you are using KEDIT Version 4.00P1, please note that it has a bug which prevents it from accepting a filename parameter (%h or %H) unless the %c option is also specified in the macro. ========================= While the coded limits for the number of directories and files per directory is quite high (over 2000 for each), SDE will issue a protection violation error if used in a directory that contains more than 1500 or so files (this number varies somewhat with the count of directories and available memory). Although plenty of memory may be available, SDE may run out of memory selectors. Simply restart SDE if this should happen. ========================= When using SDE on an IBM P70 portable without an external monitor attached, avoid using the backslash key to change video modes - the display will get stuck in 43 line mode. ========================= ! A few programs, some Presentation Manager programs in particular, do ! not like to be executed/launched directly. If a program you are ! executing from a macro dies with a segmentation violation error at load ! time, try using the %c or %L option to execute/launch the program. ======================================================================= HINTS ======================================================================= If aren't already using a RAM disk, set up a small one using the VDISK.SYS driver. In your STARTUP.CMD file, copy those list and browse utilities you call most often from SDE to the RAM disk. Make your PATH statement in CONFIG.SYS point to your RAM disk by putting a path to the RAM disk at the very front of the list. Your utilities will be loaded with surprising alacrity. ========================= For OS/2 C programmers: Make your RAM disk larger. Put the include files for PM, the base O/S, and programs like MAKE, LINK, and CL on the RAM disk. The compiler spends a lot of time processing these header files, and this can really cut down on compilation time. Be sure to update your PATH statement, INCLUDE statement, etc. ========================= You can patch SDE to use any command-shell utility instead of the default CMD.EXE using HexEdit II. Open the SDE.CFG file (make a backup first!) and enter the name of your utility begining at byte offset 269 (decimal, zero origined) of the first sector of the file. Omit the EXE extension and make sure the name is immediately followed by a null (0x00) byte. ======================================================================= ACCOMPANYING APPLICATIONS ======================================================================= The SDE Environment is packaged with another SysteMAX utility, Hexedit II. HexEdit II (HEXEDIT.EXE) is an ASCII/EBCDIC/HEX file and disk editor that can be used to view and edit the contents of binary files, data files, and entire volumes. For viewing fixed-length record data files, the record size can be adjusted to that of the file (up to 2K). For binary files and volumes, set the record size to 0x200 (512 decimal) for best performance. To start the HexEdit II program from SDE, use the following macro: hexedit %h This tool will work only when executed from the SDE Environment. ======================================================================= SDE REGISTRATION ======================================================================= For single-user registration, please print and complete the REGISTER.FRM document. For site-license registration, please print and complete the REGISTER.SIT document. ======================================================================= SDE DISTRIBUTION ======================================================================= SysteMAX Corp. retains the sole right to sell the SDE package. Distribution of the SDE Environment is permitted as long as: All program files are distributed intact, unmodified, and en masse. Please distribute the archived form of the SDE package if at all possible. The original, limited-function shareware 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 AND DISCLAIMER ======================================================================= SysteMAX Corp. 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. SysteMAX Corp. will not be liable for any special, incidental, consequential, indirect or similar damages due to loss of data or any other reason, even if SysteMAX or an agent of SysteMAX has been advised of the possibility of such damages. In no event shall SysteMAX Corp.'s liability for any damages ever exceed the price paid 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. ======================================================================= END OF DOCUMENT =======================================================================