OS/2 Shareware BBS: OtherApp

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

/ OS/2 Shareware BBS: OtherApp / OtherApp.zip / FSHL125.LZH / FSHL.DOC < prev next >

Wrap

Text File | 1992-04-03 | 54KB | 1,232 lines

Documentation for FSHL Version 1.25 Oberon Software 518 Blue Earth Street Mankato, MN 56001 Voice Phone: 507/388-7001 BBS: 507/388-1154 FAX: 507/388-7568 MCI Mail: oberon/413-5847 GEnie Mail: B.FLOWERS CIS: 72510,3500 April 3, 1992 ------------------------------------------------------------- Copyright 1990-92, Oberon Software, Mankato, MN - All Rights Reserved ------------------------------------------------------------- ---------------------------------------- Contents ---------------------------------------- 0. Overview I. Invoking FSHL II. Command Line Editor A. File name completion B. Notes on pattern matching III. Command Line Historian IV. Aliases A. Creating an alias on the command line B. Creating an alias in the initialization file C. The scope of aliases D. Limit on number of aliases E. Displaying aliases F. Replacing and clearing aliases G. Temporarily overriding an alias H. Function Key macros (PF Aliases) I. Misc V. FSHL Internal Commands VI. FSHL Command Files A. Restrictions B. Extensions C. Other differences VII. Misc A. Setting COMSPEC B. FSHL and STARTUP.CMD C. Pseudo-Environment Variables VIII. Future Enhancements ---------------------------------------- 0. Overview ======== FSHL (pronounced eff-shell) is meant to enhance the functionality of the default OS/2 command interpreter, CMD.EXE. In it's current incarnation, FSHL is not meant to completely replace CMD.EXE (although this is a future goal, see below). FSHL's features include a replacement command line editor and historian for OS/2 allowing more functionality than the one included in CMD.EXE. As with CMD.EXE, the user may browse through a circular buffer of previously entered commands, edit and reedit command lines, and reexecute previously entered command lines using the cursor movement keys. FSHL goes several steps further however and adds keystrokes allowing the user to delete specific commands from the history buffer (or the entire buffer), review the history and retrieve specific commands without being required to "arrow-back" to them. The command line editing functions are also a superset of those offered by CMD.EXE. In addition to all of this, FSHL also allows you to define "aliases" for commonly typed (or difficult to remember) commands. Aliases can be used to reduce the number of keystrokes you need to execute commonly used commands (for instance, "dir" may become simply "d"). FSHL also introduces it's own set of internal commands, some new features to old friends like "PROMPT" and "PAUSE", special handling of certain batch files, and more. Read on... I. Invoking FSHL ============= You may invoke FSHL directly from an OS/2 (CMD.EXE or FSHL) prompt, via an entry in a PM Desktop Manager Program Group, from a batch file, or from another program if it allows a customizable "Shell to OS/2" function or the ability to execute external, user defined programs. There are a number of command line switches which you may use to define some of FSHL's behavior. All command line switches must be preceded by a slash (/) or a hyphen (-) character and, if the switch has a parameter, it must follow directly after the switch character with no intervening space or tab characters (the -c and -k are exceptions to this rule, see note below). A list of these option switches follows: -a<number> specifies the maximum number of aliases which may be defined. If omitted, defaults to 50. -h<number> specifies the number of command lines to save in the history buffer. If omitted, defaults to 30. -f<filename> specifies a valid file name containing a list if alias commands to load at startup. This file is only read if there are no other instances of FSHL currently running on the system. There is no default value. -i when specified, sets the default edit mode of the command line editor to "insert". If omitted, the default is "overstrike". -d<0 or 1> specifies which delimiter set the command line editor will use for purposes of "word-wise" movement and deleting. If set 0 is specified, only space and tab characters are treated as word delimiters, if set 1 is specified, all non-alphanumeric characters are treated as delimiters. If omitted, defaults to 0. -u if specified, sets the default mode for the "partial command recall" feature of the command line historian such that the CONTROL key is not required to perform a partial command search (see Section III). If omitted, the default keystrokes for this feature are CONTROL+UP and CONTROL+DOWN. -c<command> specifies a command to immediately execute at startup. When the command has finished, FSHL will exit. -k<command> specifies a command to immediately execute at startup. When the command has finished, FSHL will enter normal, command line mode. Note: For the -c and -k parameters, the command may be any legal command which you could otherwise type at the command prompt: an executable file name or batch file name or an OS/2 or FSHL internal command. You may even use aliases in the command. The -c and -k parameters are, of course, mutually exclusive. The entire remainder of the FSHL command line is considered to be part of the -c or -k switch so, if you wish to use -c or -k, all other switches must precede it on the FSHL command line. Installing FSHL in CONFIG.SYS ----------------------------- The preferred alternative to executing FSHL from the CMD.EXE command line or via a special entry in a PM Program Group, is to replace the reference to CMD.EXE in your PROTSHELL statement in CONFIG.SYS. This will cause FSHL to be executed instead of CMD.EXE any time you invoke an OS/2 full screen or windowed session. There are several rules to remember if you elect to use this method however. 1) You may follow the path/name of FSHL.EXE with any valid FSHL parameter as given above; FSHL will be executed with those parameters each time an OS/2 full screen or windowed session is initiated (except as regards STARTUP.CMD; see below). 2) You will want to change your "set COMSPEC=" statement in CONFIG.SYS to refer to FSHL rather than CMD.EXE. 3) You MUST add a line in CONFIG.SYS of the form "set CMD_EXE=" such that the new CMD_EXE variable refers to the actual CMD.EXE file. 4) If you use a STARTUP.CMD file, FSHL will call on CMD.EXE as specified in the environment variable CMD_EXE to execute it. OS/2 invokes FSHL for this purpose without including the default parameters which were specified in the PROTSHELL statement so you won't have access to any aliases from your "-f" configuration file. Please refer to Section VII., Items A. and B. for further information. Examples: These examples all assume that you have FSHL.EXE in a directory named "d:\bin", that your FSHL initialization file is named FSHL.INI and is located in "d:\bin\ini", and you have a startup FSHL-syntax batch file named FSHLINIT.FSH located somewhere on your PATH as specified in CONFIG.SYS. -------------------- 1) Under OS/2 1.3, if you add FSHL to a Program Group, the entry might be: Program Title : FSHL - Full Screen Session Path and Filename: d:\bin\fshl.exe Parameters : -fd:\bin\ini\fshl.ini -kfshlinit.fsh Working Directory: d:\usr Program Type : Other You may specify either a "fullscreen" session or a "windowed" session to run the program. -------------------- 2) Under OS/2 2.0, if you add an FSHL Program Object to a folder or the desktop, after copying a "Program Object Template" to the destination, open the settings notebook and specify: Path and Filename: d:\bin\fshl.exe Parameters : -fd:\bin\ini\fshl.ini -kfshlinit.fsh Working Directory: d:\usr On the "Session" page, you may select either "OS/2 Fullscreen" or "OS/2 Window". -------------------- 3) If you use the "protshell" method under OS/2 1.3 in CONFIG.SYS you would specify: PROTSHELL=c:\os2\pmshell.exe os2.ini os2sys.ini d:\bin\fshl.exe /kfshlinit set COMSPEC=d:\bin\fshl.exe set CMD_EXE=c:\os2\cmd.exe -------------------- 4) If you use the "protshell" method under OS/2 2.0 in CONFIG.SYS you would specify: PROTSHELL=c:\os2\pmshell.exe set USER_INI=c:\os2\os2.ini set SYSTEM_INI=c:\os2\os2sys.ini set OS2_SHELL=d:\bin\fshl.exe -fd:\bin\ini\fshl.cfg -kfshlinit set COMSPEC=d:\bin\fshl.exe set CMD_EXE=c:\os2\cmd.exe II. Command Line Editor =================== The following keystrokes are available for editing the command line; you may use either the keys on the numeric keypad (if NumLock is off!) or the dedicated keypad. Keystroke Function ------------------- -------------------------------------------- LeftArrow Move cursor one character to the left RightArrow Move cursor one character to the right Home Move cursor to the beginning of the line End Move cursor to the end of the line Control-LeftArrow Move cursor one "word" to the left* Control-RightArrow Move cursor one "word" to the right* Insert Toggle insert/overstrike mode Delete Delete one character at the cursor Backspace Delete one character to the left of the cursor Control-Delete Delete one "word" at the cursor* Control-Backspace Delete one "word" to the left of the cursor* Control-Home Delete from beginning of line to cursor Control-End Delete from cursor to end of line Escape Erase entire line Control-Insert Exchange the character at the cursor with the character immediately to the right *For our purpose here, a "word" is a block of characters between two delimiters. The default delimiter set is the beginning and end of the line plus the space and tab characters. This definition may be expanded at startup (see discussion on the "-d" command line parameter in Section I. above) or while FSHL is active (see discussion on the "delimiters" command in Section V. below) to include all of the normal "punctuation" characters, i.e., all characters which are neither a letter nor a digit. A. File name completion -------------------- There are two special keystrokes used by the command line editor that deserve a closer look: Alt-> "Alt-Greater Than" or, if you prefer, "Alt-." Alt-< "Alt-Less Than" or, if you prefer, "Alt-," At any FSHL prompt, if you press Alt-> FSHL will look at the "word" just under the cursor (or just to the left if the cursor is over white space) and expand it into a list of matching file names. If matches are found, the string is replaced immediately with the first match. Subsequent presses of Alt-> will progress through the list. Alt-< will move backwards through the list. Either way, the list will "wrap". That is, when the end is reached the display will start over from the other end. B. Notes on pattern matching ------------------------- If you press Alt-> or Alt-< with the cursor over the string "foo", FSHL will first try to find a file which exactly matches "foo". If the file exists, nothing apparent will happen; you are done. If a SUBDIRECTORY named "foo" exists, however, a backslash will be appending to "foo", making it "foo\" and you will then be able to cycle through all the file names in that subdirectory. If neither of these two events occurred, then FSHL will transform the string into "foo*" and try one more time and you will be able to cycle through your file names like "foolishness" and "food preparation in the 90's". If there are still no matches at this point, FSHL will emit a short beep to inform you of that fact. If the string contains any *'s or ?'s, then only that string will be matched (i.e., FSHL will not test it as a possible subdirectory). If the string ends with a backslash (i.e., "foo\") then FSHL will not try to treat it like a possible file name and will instead match "foo\*". III. Command Line Historian ====================== FSHL maintains a circular buffer of previously entered commands, any of which may be retrieved. The size of this buffer defaults to 30 commands but the user may specify a different size if so desired (see discussion on the "-h" command line parameter in Section I. above). When the buffer becomes "full" the eldest commands are removed as new ones are entered. It is worth noting that the history buffer is shared by any invocation of FSHL occurring in the same screen group. This is to say, that if FSHL is executed from FSHL, or from any program which was itself executed from FSHL, it will share the history buffer with its parent(s) and any changes made to the buffer will remain in effect when the parent FSHL regains control. However, two invocations of FSHL running in different windows or full screen session will each have their own, private history buffers. The latter feature is desirable because, typically, different windows or sessions will be used for different activities. Sharing the buffer within the screen group is desirable because it adds continuity to the activity in the current window. There are several keystrokes which may be used at the command prompt to navigate the history buffer. Important to the concept here is that notion of "current position" in the history buffer. After entering a new command, the current position is just after the newly entered command and (because the buffer is circular) just before the first command in the buffer. Some of the keystroke functions listed below may change the current position. Keystroke Function ------------------- -------------------------------------------- UpArrow recalls one command for reedit just before the current position. Anything currently on the command line is replaced. See exceptions, below (* and **) DownArrow recalls one command for reedit just after the current position. Anything currently on the command line is replaced. See exceptions, below. (* and **) Control-UpArrow searches backward for a command from the history buffer which matches exactly whatever is on the current command line to the left of the current cursor position. Note, if the FSHL invocation line parameter "-u" was specified, or if the "ctrlsearch" mode has been set OFF via the "ctrlsearch" keyword, then the UpArrow, with or without the Control key will behave in this manner. Control-DownArrow searches forward for a command from the history buffer which matches exactly whatever is on the current command line to the left of the current cursor position. Note, if the FSHL invocation line parameter "-u" was specified, or if the "ctrlsearch" mode has been set OFF via the "ctrlsearch" keyword, then the DownArrow, with or without the Control key will behave in this manner. Control-PgDn deletes the currently active command line from the history buffer. Control-PgUp clears the entire history buffer Control-V erases whatever is currently on the command line and displays the contents of the history buffer. Additionally, there are several "pseudo-commands" which may be entered at the command prompt to help manipulate the history buffer. If you type an exclamation point (!) and hit the ENTER key, the history buffer will be displayed. The entries in the history buffer are numbered from zero. If you type an exclamation point (!) plus a number which matches a valid entry in the history buffer and hit the ENTER key, that command will be immediately reexecuted. If the number is invalid, the history buffer will be displayed. * If you type an exclamation point (!) plus a number which matches a valid entry in the history buffer and press and UpArrow or DownArrow, that command will be recalled to the command line allowing you to reedit the line (this is the exception for UpArrow and DownArrow referred to above). Any command which begins with a circumflex character (^) will have that character removed and the command will NOT be added to the history buffer. ** If the "ctrlsearch" mode has been set OFF either via the FSHL invocation switch "-u" or the "ctrlsearch" keyword, then the UpArrow and DownArrow will only behave as described above is there is nothing already entered on the command line or if the only thing entered is an exclamation point plus a number. In all other cases, UpArrow and DownArrow will behave as described for Control-UpArrow and Control-DownArrow. That is, a partial command line recall will be performed. IV. Aliases ======= Simply put, aliases are a redefinition of one string to another. The FSHL command line editor, historian, and batch processor are all aware of these aliases and will translate them behind the scenes into their full equivalents when they are encountered as the first thing on a command line. Aliases may be used to reduce the number of keystrokes needed for invoking frequently-used commands. They may be used to avoid having to remember long, involved command lines that are always the same. They may also be used to mask the difference in command line syntax when you change your text editor or archive utility. A. Creating an alias on the command line ------------------------------------- Use the FSHL internal "alias" command to do this. Simply type: "alias newtoken alias_value" without the quotes on the command line. "newtoken" must be a single word with no embedded spaces or tabs, "alias_value" may be anything you wish. From this point on, until all running copies of FSHL are exited, whenever you type "newtoken" as the first thing on a command line, it will be as if you had typed all of "alias_value". Examples: alias d dir alias type cat alias zip pkzip2 alias ccopy for %f in (*.c *.obj) do copy %f It's worth noting that, in the second example, an FSHL internal command has been aliased. This will work because all aliases are expanded before the command is examined for internal commands and before the disk is searched for external programs. Sample invocations for these example aliases might be: d c:\os2 type read.me zip -v zipfile ccopy a: which would translate into: dir c:\os2 cat read.me pkzip2 -v zipfile for %f in (*.c *.obj) do copy %f a: Note that the remainder of the command line is passed through unchanged in the translation. There are also things called "parameterized aliases" which allow you some positive control over the parameters on the command line also. It is perhaps easiest to think of alias parameters in much the same manner as you would think of .CMD file parameters. A parameter may be referenced using "%n" where "n" is a digit from "1" to "9" and it refers to the parameters position on the command line. You would use parameterized aliasing when you need to change the order of certain parameters or to embed parameters or information anywhere except in the first position. Examples: alias dirmore dir %1 | more alias b@ b %2 -m"goto_line %1" Sample invocations for these example aliases might be: dirmore d:\bigdir b@ 124 file.c which would translate into: dir d:\bigdir | more b file.c -m"goto_line 124" If you were to type "dirmore d:\bigdir e:\stuff" however, the translation would be exactly the same because "e:\stuff" is "%2" which is not mentioned in the alias. You could, of course, expand the alias definition to "dirmore %1 %2 | more" or even out to "dirmore %1 %2 %3 %4 %5 %6 %7 %8 %9 | more". This points out a couple of limitations on parameterized aliases: 1) If parameters are used, unreferenced arguments on the command line are ignored. 2) If parameters are used, you are limited to using only the first nine actual parameters. There is no "shift" command or "%*" syntax as in FSHL command files. B. Creating an alias in the initialization file ------------------------------------------- The file specified via the "-f" FSHL command line parameter (see Section I.) may contain a list of alias commands. The syntax for alias command in this file is exactly the same as that discussed above. Note that this file is only processed by FSHL at startup if there are no other currently executing copies of FSHL on the system. C. The scope of aliases -------------------- All aliases are global to all currently active invocations of FSHL. This is to say that, if an alias is defined in one FSHL session it will immediately be available in ALL FSHL sessions. D. Limit on number of aliases -------------------------- The "-a" FSHL command line parameter defines the maximum size of FSHL's alias list (see Section I.). Note that, except for the first invocation of FSHL, this is not an absolute value. If, for instance, FSHL was invoked with the default alias list size of 30 and a second invocation of FSHL requested 20 aliases ("-a20") the larger size of 30 would remain in effect. If a later invocation requests more aliases however, the alias list size is expanded to honor the request. E. Displaying aliases ------------------ The "alias" command which was used to define the aliases may also be used to display the status of one alias or the status of all aliases. If you type "alias" on the command line with no arguments, the entire list of active aliases is displayed. If you type "alias" with a single argument, the value of that alias is displayed, if one exists, otherwise a message stating that the token is not aliased is printed. You may also use the single keystroke Control-T to display the alias list. When Control-T is used, anything currently on the command line is erased and the alias list is displayed. F. Replacing and clearing aliases ------------------------------ If you redefine an alias (i.e., create an alias for a token that already has an alias), the new alias is added to the list without removing the previous one. When FSHL searches the list it searches from the last to the first, thus, the new alias will take precedence over the old one until it is cleared (see below) at which time the original alias takes effect again. You may remove aliases from the alias list with the "clearalias" command. The syntax is simply "clearalias token". If "token" has an alias, it is removed; otherwise the alias list is redisplayed. G. Temporarily overriding an alias ------------------------------- Let's say you've aliased "d" to "dir" and now you want to test run someone's new program, d.exe. You type "d" on the command line and FSHL faithfully presents you with a directory listing! What to do? Well, there are two things you can do. The first would be to make sure that the first token isn't exactly "d"; ".\d" or "d.exe" would execute the d.exe file for you. The other would be to type a space as the first character on the command line. If FSHL finds a space character at the beginning of a line it performs NO aliasing on that line. So, to execute d.exe you could type " d". Note that you can combine the space character override in conjunction with the "^" character to not enter a command into the history list (see Section III.). To do this, make sure that the circumflex is the first character and the space is second. Thus, "^ d" would execute your d.exe program and NOT add this command to the history list. H. Function Key macros (PF Aliases) -------------------------------- You can assign up to 48 text macros, one to each of the 12 Function Keys (F1 through F12) and one to each "shift state" of each Function Key. The method uses the keywords "pfalias" and "pfalias!" in a similar manner to the use of the "alias" keyword. The syntax is: "pfalias key_number text" or: "pfalias! key_number text" Where "key_number" is an integer number between 1 and 48 which indicates the appropriate function key according to the following table: UnShifted Shift Control Alt +---------------------------------- F1 | 1 13 25 37 F2 | 2 14 26 38 F3 | 3 15 27 39 F4 | 4 16 28 40 F5 | 5 17 29 41 F6 | 6 18 30 42 F7 | 7 19 31 43 F8 | 8 20 32 44 F9 | 9 21 33 45 F10 | 10 22 34 46 F11 | 11 23 35 47 F12 | 12 24 36 48 The keyword "pfalias" assigns the exact text to the function key while the keyword "pfalias!" assigns the text plus a carriage return to the function key. When invoked, the function key macro text will be "played back" onto the command line and will be treated from that point on as though the user had typed the text. Thus, normal aliases and FSHL internal commands can be referenced in a Function key macro. The scope of the function key macros is within the session or screen group rather than global as are aliases. I. Misc ---- Note that there is no eight character restriction on alias tokens. There is absolutely nothing wrong with: "alias pastafazoola dir". V. FSHL Internal Commands ====================== The following is a list of all commands which FSHL will execute internal to itself. The list includes some redefined CMD.EXE functions as well as some new ones which are unique to FSHL. The capsule description provided with each should be fairly explanatory in most cases. Where it is not, it is either covered in a separate section of this document (i.e., "alias" and "clearalias") or is discussed at greater length in the notes following the list. alias see Section IV. "Aliases" cd exactly like the OS/2 command of the same name cdd change drive AND directory with single command chcp exactly like the OS/2 command of the same name chdir exactly like the OS/2 command of the same name clearalias see Section IV. "Aliases" cls exactly like the OS/2 command of the same name ctrlsearch sets default partial command recall mode, see below del some enhancements over the OS/2 equivalent, see below delimiters change the default word-delimiter set, see below echo exactly like the OS/2 command of the same name erase some enhancements over the OS/2 equivalent, see below fexit exit FSHL for like the OS/2 command of the same name but nestable fshlinfo display information about FSHL and current status fshlinsert sets default command line editor insert mode, see below fshllogo display FSHL logo and copyright notice fver display FSHL version if like the OS/2 command but see Section VI. installdll install 3rd party DLL, see below md exactly like the OS/2 command of the same name mdd make a directory and chdir to it in one command mkdir exactly like the OS/2 command of the same name oberon display information about Oberon Software path exactly like the OS/2 command of the same name pause some enhancements over the OS/2 equivalent, see below pfalias see Section IV. "Aliases" pfalias! see Section IV. "Aliases" prompt some enhancements over the OS/2 equivalent, see below prty set program priority, see below rd some enhancements over the OS/2 equivalent, see below rem exactly like the OS/2 command of the same name restorehistory saves history buffer to file, see below rmdir some enhancements over the OS/2 equivalent, see below savehistory retrieves saved history from file, see below set exactly like the OS/2 command of the same name sweep see discussion below type some enhancements over the OS/2 equivalent, see below ver exactly like the OS/2 command of the same name vol some enhancements over the OS/2 equivalent, see below window alter VIO window from command line, see below The "ctrlsearch" command: ------------------------- Sets or queries the default method for searching the history buffer for a partial match. The default in ON, meaning that to search for a partial command line, you must use the Control key with either the up or down arrow to initiate the search and the regular arrow keys will cycle through each entry in the history buffer. When this mode is set OFF then the control key is NOT required to search for partial command lines. The only way to search the entire buffer is to clear the command line before using the up or down arrows. In this case, you must also be aware that the cursor will remain at the beginning of the command as each is displayed instead of at the end. If the parameter is omitted, the current state of this setting will be reported. You can set this mode OFF on the FSHL command line with the switch: "-u". The "delimiters" command: ------------------------- This command allows you to query or set the delimiter set used by the command line editor for purposes of "word-wise" movement. If set to "standard", the delimiters are the beginning and ending of the line plus any block of space or tab characters. If set to "extended", all of the punctuation characters are added to the set (i.e., any character which is neither numeric or alphabetic). The syntax is, then: "delimiters argument" where "argument" is one of "standard" or "extended". Type "delimiters" with no argument to view the current setting. Any other argument will display a brief help message and the current setting. Please refer to Section I. regarding setting the default delimiter set on the FSHL command line via the "-d" switch. See Section II. regarding the behavior of the command line editor with respect to the delimiter setting. Extensions to DEL and ERASE are: -------------------------------- Like the CMD.EXE equivalent, you may provide a list of ambiguous filespecs for DEL and ERASE and the list will be processed in order. In addition, FSHL provides the following switch settings to modify the behavior. Switches are preceded with a slash (/) or a hyphen (-) and are not case sensitive. Switches may appear at any place on the command line and are in effect for the remainder of the command line or until reset. -v Verify. User will be asked for each, individual file whether or not it should be deleted. Turn this option off with "-v-" or "/v-". -d Display. Show the name of each file as it is deleted. Turn this option off with "-d-" or "/d-". -y Yes. If the target of the del or erase command is a directory name or the wildcard is "*" or "*.*", the user is queried for verification unless this option is specified in which case, the prompt is NOT displayed and a "Yes" answer is assumed. Turn this option off with "-y-" or "/y-". USE THIS OPTION WITH EXTREME CARE! The "fshlinsert" command: ------------------------- Sets or queries the default insert/overstrike mode for the command line editor. If the parameter is 'ON', FSHL will default to insert mode on the command line, if it is 'OFF' it will default to overstrike mode. If the parameter is omitted, the current state of this setting will be reported. You can set this mode ON on the FSHL command line with the switch: "-i". The "installdll" command: ------------------------- Allows the installation of a DLL (user or third party written) which may contain actions to be executed for the listed tokens. Thereafter any of the tokens in the token list will act in a similar fashion to a normal 'alias' except that the DLL routine will be called. If the "token list' is omitted, the DLL will be removed from memory. This DLL MUST have the following entry point: USHORT APIENTRY PROCESS(PCHAR, PCHAR); The two parameters will be the token which initiated this call to the DLL and its command line parameters respectively. The return value from the function will placed into the ERRORLEVEL. The DLL may optionally have one or both of the following two entry points: USHORT APIENTRY INIT(VOID); USHORT APIENTRY CLEANUP(VOID); INIT will be called immediately after loading the DLL to allow it to allocated resources or perform whatever action it feels it must. If INIT returns nonzero, the DLL will immediately be unloaded and an error message printed. CLEANUP is called when the DLL is unloaded under normal conditions. This will allow the DLL to free any allocated resources and/or perform any other actions it deems necessary at this point. See the supplied source code for TestDLL for a very contrived example. Note that the token lists for the installed DLLs are checked first before any other FSHL alias, FSHL internal, or OS/2 internal command. After FSHL aliases are expanded, the list is rechecked. Also note that installed DLLs are inherited by child invocations of FSHL but not vice versa. If a child uninstalls an inherited DLL, it will still be installed for the parent. This behavior is analogous to the way SET environment variables behave with respect to parent and child processes. Extensions to PROMPT are: ------------------------- All of the special dollar-sign codes which are traditionally allowed in the PROMPT string to modify the appearance of the system prompt are supported with the following enhancements and exceptions: $f -- prints FSHL version $s -- prints current screen group number $i -- is completely ignored The "prty" command: ------------------- "prty idle|normal|timecrit|foreground command [args]" Allows execution of "command" at the specified priority level. Whatever priority FSHL itself is running at is restored after execution of the command. Extensions to RD and RMDIR are: ------------------------------- Like the CMD.EXE equivalent, you may provide a list of directory specs for RD and RMDIR and the list will be processed in order. In addition, FSHL provides the following switch settings to modify the behavior. Switches are preceded with a slash (/) or a hyphen (-) and are not case sensitive. Switches may appear at any place on the command line and are in effect for the remainder of the command line or until reset. -f Files. All files in the indicated subdirectory will be deleted prior to attempting to remove the directory. -s Subdirs. All files in the indicated subdirectory and all nested subdirectories will be deleted and all nested subdirectories removed prior to attempting to remove the directory. -r Restore. Negate the effects of any previously specified "-f" or "-s" switches. -y Yes. If "-f" or "-s" has been specified, the user is queried for verification unless this option is specified in which case, the prompt is NOT displayed and a "Yes" answer is assumed. Turn this option off with "-y-" or "/y-". USE THIS OPTION WITH EXTREME CARE! The "savehistory" and "restorehistory" commands: ------------------------------------------------ "savehistory filename" saves the current history buffer to a file for later use with the FSHL "restorehistory" command. "restorehistory filename" reads a file, created previously by the FSHL "savehistory" command and replaces the entire history buffer with the saved buffer. The "sweep" command: -------------------- Use sweep to execute a given command in the current directory and recursively over all nested subdirectories. Example: sweep del *.bak Extensions to TYPE are: ----------------------- Like the CMD.EXE equivalent, you may provide a list of ambiguous filespecs and the list will be processed in order. In addition, FSHL provides the following switch settings to modify the behavior. Switches are preceded with a slash (/) or a hyphen (-) and are not case sensitive. Switches may appear at any place on the command line and are in effect for the remainder of the command line or until reset. -p[number] Pause. If supplied, the numeric parameter specifies the number of lines to display between "More?" prompts. If zero (0) is given, prompting is disabled (this is the default). If the number is omitted, the current screen length is used. Extensions to VOL are: ---------------------- Like the CMD.EXE equivalent, you may provide a list of drive letters and the list will be processed in order. In addition, FSHL provides the following switch settings to modify the behavior. Switches are preceded with a slash (/) or a hyphen (-) and are not case sensitive. Switches may appear at any place on the command line and are in effect for the remainder of the command line or until reset. -i Info. If supplied, the total disk space and the total available disk space will be displayed in addition the standard information. Turn this option off with "-i-" or "/i-". The "window" command: --------------------- "window min|max|restore|size|move|tasklist" Min, max, restore, size, and move perform the equivalent of selecting that item from the window's System menu. Tasklist brings the system Task List to the foreground as if Ctrl+ESCAPE were keyed at the keyboard. Note that "window min" and "window tasklist" will work in either a full screen session or a windowed session; in both cases, it will cause the PM Desktop and the Tasklist to surface. "Max", "restore", "size", and "move" are only valid in windowed sessions. VI. FSHL Command Files ================== OS/2 command files, which have the extension ".cmd", are all routed by FSHL back through the OS/2 command processor, CMD.EXE. This has some benefits and some problems. The benefits are that the syntax and behavior of these command files are nearly exactly what we would expect. The word "nearly" is used because of one effect which could be considered either a problem or a benefit based on one's point of view. This effect is that all .cmd command files behave as if they had a "setlocal" command at the very beginning (and no "endlocal"). That is, the entire environment including the current drive and directory will be restored to its original value once the command file has finished executing. This makes it not possible to change environment strings, your command prompt, the current path setting, or the current drive and/or directory in a command file and have those remain in effect after execution of the file. FSHL command files, which have the extension ".fsh", are executed directly by FSHL and they have a different set of features and limitations. You MAY change the environment for the current session in an FSHL command file and have it remain in effect. The syntax of an FSHL command file is almost exactly the same as that of an OS/2 command file with the following restrictions and extensions. A. Restrictions ------------ "SETLOCAL" and "ENDLOCAL" statements are not supported. Do not use "GOTO" in a statement that contains redirection characters (>, <, or |) or command chaining (&, &&, or ||). If a "GOTO" is executed as a result of a "FOR" statement, the "GOTO" is executed and the "FOR" loop is exited immediately. B. Extensions ---------- You may use any FSHL internal command or defined alias in a command file with the desired results. Lines in the command file are NOT added to the history buffer however and you may not use the "!" or "^" command prefixes as you would on the command line. The syntax on "IF" statements is extended to include all of the following constructs: if errorlevel == n ... if errorlevel != n ... if errorlevel > n ... if errorlevel < n ... if errorlevel >= n ... if errorlevel <= n ... if fullscreen ... if foreground ... Note that "if errorlevel n ..." behaves as always. Any of the "IF" statement conditions may be preceded with the keyword "NOT" with the desired effect. Anywhere that you may use "errorlevel" in an "IF" statement, you may substitute the actual command for which you wish to check. The command must be in parentheses; it may contain aliases. For example: rem ---- The next two lines: chkdsk d: if errorlevel > 1 echo Chkdsk had problems rem ---- Are equivalent this one line: if (chkdsk d:) > 1 echo Chkdsk had problems Unlike the CMD.EXE batch processor, "FOR" loops may be nested in .fsh files. New keywords: "COMPARECASE" and "COMPARENOCASE" effect the results of string comparisons in "IF" statements. By default, all string comparisons are case sensitive. Case sensitivity for these comparisons is turned off using "COMPARENOCASE" and turned back on using "COMPARECASE". This state pervades until the end of the command file but is NOT inherited by nested command files. You are not limited to %0 through %9 when referencing command line parameters, %10, %11, indeed, %278 may be used. The "SHIFT" keyword works as expected. You may reference all command line parameters in a single string using the construct "%*". Note that this includes %0. You may reference all command line parameters from a given parameter in a single string using "%*n" where "n" is the number of the parameter to begin at, for example, "%*3" results in the entire command tail beginning at (and including) "%3". Examples: echo My ENTIRE command line was [%*] rem Reverse the first two parameters and pass the rest echo %2 %1 %*3 The EXIT statement may have an optional parameter. If this parameter is numeric, the ERRORLEVEL is set to that value, if it is non-numeric, ERRORLEVEL will be set to zero. Examples: exit 5 exit %3 if not fullscreen exit 1 C. Other differences ----------------- "EXIT" ends the current command file ("FEXIT" exits FSHL). Any nested FSHL command file, whether executed directly or via the "CALL" keyword, are treated as if the "CALL" were present. That is, execution will always return to the calling command file. The ECHO state is not inherited by nested command files, it must be explicitly turned off if this is desired. VII. Misc ==== A. Setting COMSPEC --------------- FSHL currently uses CMD.EXE for the execution of some internal OS/2 commands and for the execution of .CMD files. For this reason, it needs to know where to locate CMD.EXE and the COMSPEC environment variable is the obvious place to look. You may have reason, however, to desire COMSPEC to point to FSHL itself so that certain programs which allow you to shell to OS/2 will automatically invoke FSHL (i.e., Brief, Codeview). If you want to set COMSPEC to refer to FSHL, you must make sure to set an environment variable "CMD_EXE" to refer to the actual CMD.EXE. FSHL will look for the CMD_EXE variable first before defaulting to COMSPEC. VERY IMPORTANT: If you wish to set COMSPEC to refer to FSHL, it is VERY IMPORTANT that you set the environment variable CMD_EXE as outlined in the paragraph above! If you have COMSPEC pointing to FSHL and CMD_EXE undefined, FSHL will enter into an endless recursion attempting to execute certain commands which could result in wildly unpredictable behavior. B. FSHL and STARTUP.CMD -------------------- Due to special handling of STARTUP, the command "fshl /k STARTUP.CMD" will behave as if the "/k" were a "/c" (i.e., FSHL WILL exit after executing this command). This includes the command line if you type it at a prompt! If you really must execute STARTUP.CMD through a second invocation of FSHL with the "/k" parameter, all you need to do is either leave off the ".CMD" portion or include a drive and/or path specification; the string must be exactly "STARTUP.CMD" (upper, lower, or mixed case) for this special handling to be triggered. If you have elected to replace CMD.EXE in the PROTSHELL statement of your CONFIG.SYS file with FSHL, take care that any START commands in the STARTUP.CMD file do NOT execute a session through a secondary command processor if that session is to persist (i.e., STARTing a Clock program or a BBS). This will cause another copy of FSHL to be loaded without your initialization file which will effectively block any subsequent invocations of FSHL from reading this file. You should refer to the OS/2 documentation for the START command for further details; however, when in doubt, include a "/N" parameter on the START command line. C. Pseudo-Environment Variables ---------------------------- Reference these on the command line or in command files as always using percent signs (%) before and after. They do NOT show up when you type "set" with no parameters. You may "set" them in your environment but FSHL will preferentially use the pseudo-variable. _DATE_ The current date: "Day mm-dd-yyyy" _DATEYMD_ The current date: "yymmdd" _WEEKDAY_ The current weekday: "Sunday", "Monday", ... _MONTHDAY_ The current day of the month: "1", "2", .. "31" _MONTH_ The current month: "1", "2", ... "12" _MONTHNAME_ The current month: "January", "February", ... _YEAR_ The current year: i.e., "1992" _TIME_ The current time: "hh:mm:ss.hh" _FSHL_ The current FSHL version _ERRORLEVEL_ The current errorlevel _SCREENGROUP_ The current screen group number _SCREENTYPE_ The current screen type: "Full" or "Windowed" _OSVERSION_ The OS/2 version string _CODEPAGE_ The current code page setting _GREETING_ The greeting time: "Morning", "Afternoon", "Evening" VIII. Programming APIs ================ There are now two methods for you to programmatically extend and/or access FSHL features. One method is the 'InstallDLL' interface (see above under 'installdll' for information regarding programming add-on DLLs and also see the source for TestDLL for a simple example). The second is via the supplied FSHLCALL.DLL module. This module contains two entry points which you may access from your program: USHORT FindFshl(void); Returns the version number of the parent FSHL process or zero if you are not running as a child of FSHL. USHORT CallFshl(PSZ pszCmd, PUSHORT pusRetCode); 'pszCmd' is a pointer to a buffer containing any arbitrary command line. It will be submitted to the invocation of FSHL which is your most immediate predecessor which will treat it in all respects as though it were typed at the command line. This is to say, alias expansion and expansion of environment variables will take place as normal. 'pusRetCode' will be set to the return code (i.e., the ERRORLEVEL) from the command after its successful completion. The return value is zero on success, 0xffff on failure (if, for instance FSHL is not an ancestor of the current process). A header file, FSHLCALL.H and an import library, FSHLCALL.LIB, are also supplied for your use. It is recommended, however, that you dynamically load FSHLCALL.DLL via DosLoadModule() rather than link with the import library so that your program may continue to function properly should it find itself in the situation where FSHL is not a parent process. THE DIFFERENCE BETWEEN THE TWO APIS ----------------------------------- 1) Use the "InstallDLL" interface to create new built-in FSHL commands or to enhance old ones. 2) Use the CALLFSHL interface if your program needs to change something in the parent FSHL's environment such as the current working directory, disk drive, setting of an environment variable, etc. 3) The CALLFSHL interface could also be used as an alternative to "shelling out" to an operating system command from your program to avoid starting another process. IX. Future Enhancements =================== It is hoped that, in the near future, FSHL may be used as a complete replacement for CMD.EXE. This would involve FSHL internal processing for all CMD.EXE functions. Of course, as this work is performed, we'll take every opportunity to enhance the commands where appropriate (much like the enhancements already made to DEL, TYPE, and PROMPT). FSHL command file syntax will be enhanced to include block IF and FOR statements and the syntax of the FOR statement expanded. A .fsh file compiler and REXX compatibility are also planned. We also intend to allow a formalized interface to user written dynamic link libraries so that programmers may write their own "internal" command set and tailor the environment to their preferences. Such dynamic link libraries, once created, could be made available to others to enhance their environment. Let Oberon Software know what YOU would like. Mice? History buffers that pop up point-and-shoot lists? More *ix like commands? Let us know. Oberon Software is located at: 518 Blue Earth Street Mankato, MN 56001 Various other methods of reaching Oberon Software are: BBS: 507/388-1154 (HST 14.4, 24hrs/day) Voice Phone: 507/388-7001 FAX: 507-388-7568 GEnie: B.FLOWERS CIS: 72510,3500