OS/2 Shareware BBS: 10 Tools

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

/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / SDE_300.ZIP / SDE.HLP < prev next >

Wrap

Text File | 1993-01-22 | 68KB | 1,777 lines

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.