═══ 1. About Take Command for OS/2 Help ═══ Take Command for OS/2 Version 2.03 Help System Text by Hardin Brothers, Tom Rawson, and Rex Conn Program and Help Text Copyright 1988 - 2001, JP Software Inc., All Rights Reserved. Take Command and 4DOS are registered trademarks of JP Software Inc. 4DOS, 4OS2, and 4NT are JP Software Inc.'s trademarks for its family of character-mode command processors. JP Software, jpsoft.com, and all JP Software designs and logos are also trademarks of JP Software Inc. Other product and company names are trademarks of their respective owners. [12/01 - 2.03A] ═══ 2. Using Take Command ═══ We developed Take Command to bring the power and convenience of our popular 4DOS, 4NT, and 4OS2 programs to the Windows and OS/2 desktops. Whether you are a computer novice or an experienced user, Take Command will help you get the most out of your computer system. You're probably already familiar with graphical applications running under Windows or OS/2, and with the command line, but you may not be used to seeing them combined in one product. Most graphical applications offer limited command-line capability at best, and most command-line utilities aren't designed for a graphical environment like Windows or the OS/2 desktop. We designed Take Command to give you the best of both worlds. You'll probably find it most useful when you need to perform tasks like managing your hard disk, scripting a series of steps with an alias or batch file, or starting applications. There are graphical utilities that perform some of these tasks, but often you may find it more convenient or productive to perform them from the command line. Take Command can use fewer resources than starting a traditional character-mode command-line session, and, unlike a traditional command line session, it looks and feels like the other graphical programs you use. Take Command also offers a host of features that couldn't exist at all in a command-line utility. For example, you can pop up simple dialogs from a batch file, pass keystrokes to other graphical applications, and use a dialog to find files or text on any of your disks. In this section, you'll find a wealth of information about using Take Command, including: Using the Take Command Interface Using the Command Line File Selection Directory Navigation Other Features ═══ 2.1. Using the Take Command Interface ═══ In this section, you'll find general information about using the Take Command interface, including: Using an OS/2 "Graphical" Command Line Starting Applications The Take Command Screen Take Command for 4DOS and 4OS2 Users ═══ 2.1.1. Using an OS/2 "Graphical" Command Line ═══ Take Command for OS/2 is a new environment that lets you perform tasks easily under OS/2. You can use it to execute commands, start applications, and perform other work at the command line. In the past you may have accomplished some of these tasks by starting an OS/2 character-mode session or running 4OS2, JP Software's replacement character- mode command processor. In either case -- and especially if you are an experienced user of 4OS2 -- you'll find plenty of familiar features in Take Command. You'll also find a lot that's new and different. While Take Command includes most of the command-line, batch file, and other capabilities provided by 4OS2, and goes well beyond those provided by CMD.EXE, the OS/2 environment places a few limitations on how Take Command operates. These limitations are minor -- for example, some keystrokes are interpreted differently to conform more closely to OS/2 conventions, and there are some considerations when running batch files or OS/2 aliases designed to work in character mode under a graphical program like Take Command. All of these differences are covered in more detail under Take Command for 4DOS and 4OS2 Users. Take Command also offers a wide range of new OS/2 PM-related features which are not available in 4OS2 or CMD.EXE, including: * A built-in scrollback buffer that lets you look back through the output from past commands. * A standard OS/2 menu bar for access to many commonly-used Take Command features. * A status bar showing memory and resource usage. * A customizable tool bar that gives you quick access to commands and applications. * Dialogs (accessible from the Options and Utilities menus) for editing environment variables, aliases, file descriptions, and startup parameters. * High-speed, dialog-based file and text search (see "Search Files/Text" on the Utilities menu). The new FFIND command gives you the same capabilities at the Take Command prompt. * Commands like ACTIVATE, MSGBOX, and QUERYBOX that allow you to use OS/2 features and control OS/2 applications from your batch files. ═══ 2.1.2. Starting Applications ═══ Take Command offers several ways to start applications. (For special considerations related to starting character-mode applications, see the next topic). First, you can simply type the name of any OS/2, DOS, or Windows application at the Take Command prompt. As long as the application's executable file is in one of the standard search directories (see below), Take Command will find it and start it. If you type the full path name of the executable file at the prompt the application will be started even if it is not in one of the standard search directories. Take Command offers two methods to simplify and speed up access to yourapplications. One is to create an alias, for example: [c:\] alias myapp d:\apps\myapp.exe You can also use the Tool Bar To start frequently-used applications. For example, a tool bar button named MyApp which invokes the command d:\apps\myapp.exe would accomplish the same thing as the alias shown above. You can use these methods together. For example, if you define the alias shown above you can set up a tool bar button called MyApp and simply use the command myapp, which would then invoke the previously-defined alias. You can also start an application by typing the name of a data file associated with the application. Take Command will examine the file's extension and run the appropriate application, based on Take Command's executable extensions. For additional flexibility, you can also start applications with the START command. START provides a number of switches to customize the way an application is started. Searching for Applications When you start an application without specifying a path, Take Command searches for the application in the current directory and then all directories on the PATH. (If you do enter an explicit path, Take Command will only look in the directory you specified.) If you enter a file name with no extension, Take Command will search each directory for a matching .COM, .EXE, .BTM, or .CMD file, then for a file matching a Take Command executable extension. If no such file is found Take Command will move on to the next directory in the search sequence. Waiting for Applications to Finish When you start an application from the prompt, normally Take Command does not wait for the application to finish before returning to the prompt. This allows you to continue your work in Take Command while the application is running. You can change this default behavior for applications started from the prompt, using the ExecWait directive in TCMDOS2.INI, or the Wait for Completion option on the Options 2 page of the configuration notebook. These options do not affect batch files; Take Command always waits for applications started from batch files. Character-mode applications which run inside the Take Command window are an exception to this rule. Take Command always waits for such applications to finish before displaying a new prompt, regardless of the ExecWait setting. For more information see the next section, on starting character-mode applications. You can also force Take Command to wait for an application to finish with the START command with the /WAIT switch. START can also control many other aspects of how your applications are started. ═══ 2.1.3. Starting Character-Mode Applications ═══ Take Command for OS/2 starts OS/2 "graphical" applications in their own windows, just as if you had started them from the desktop. By default, it also creates a separate character-mode window to run each DOS or OS/2 character mode application you start. If you prefer, you can run some DOS and OS/2 character-mode applications within the Take Command window, using an OS/2 facility called "named pipes." When you use this option, output from the application is displayed in the Take Command window, and no separate window is created. Because not all applications work properly with named pipes, you must specify which TTY applications should be run within the Take Command window. To do so, use the TTY Applications Dialog (accessible from the Setup menu). The dialog lets you specify the application name, whether the application is a DOS or OS/2 character-mode program, and whether or not the application is currently enabled to run within the Take Command window. See the section on the TTY Applications dialog for details of the dialog fields and their meanings. Information entered in this dialog is stored in the [TTYApps] section of TCMDOS2.INI. Your copy of Take Command comes with a list of applications which can be run within the Take Command window. The list is visible when you open the dialog. However, all applications in the list are initially disabled to ensure maximum compatibility. This prevents problems if you have a program with the same name as one we tested, but which is not the same program. To enable any application, select it and check the Enable box. Us the Add button to add your own applications to the list. When you include an application name in the dialog, you can use an executable file name (e.g., CHKDSK.COM), or a full path name (e.g., C:\OS2\CHKDSK.COM). If you use the full path name, the entry will apply only to that specific file. If you use just the file name, the entry will apply to any file of that name, regardless of its location. If you use both, the full path name entry will be used when you execute that specific file, and the file name entry will be used for other files of the same name. As an advanced option, you can also enter a path without a filename into the dialog (e.g. C:\OS2UTILS). This will tell Take Command to treat all DOS or OS/2 character-mode programs in the specified directory as TTY applications. This approach is useful if you have many applications of the same type in a single directory, but before you use it you should review the contents of the directory carefully to be sure all the character-mode programs stored there are compatible with Take Command's TTY application support. If you do choose to configure an entire directory for TTY application support, you can create exceptions by entering specific filenames from that directory into the dialog as well. For example, if you enable the directory C:\OS2UTILS for TTY support, you could also add a listing for C:\OS2UTILS\MYAPP.EXE (or simply for MYAPP.EXE, with no path), and make sure the Enable box in the dialog is not checked for the MYAPP entry. This would prevent MYAPP.EXE from being treated as a TTY application despite the entry for the directory as a whole. If you use this approach, the two listings can appear in any order. Once an application is listed in the dialog and enabled, it will run within the Take Command window whenever you start it from the command line. However, if you start the application with the START command (without the /TTY switch, see below), the program will start in its own window. You can explicitly start any character-mode application within the Take Command window by using the START command's /TTY switch. For example: start /tty c:\os2\chkdsk.com Using this switch is the same as entering the application in the TTY Applications dialog and enabling it. Using START /TTY is a convenient way to experiment with your DOS and OS/2 character-mode applications to see if they are compatible with Take Command's TTY application support. See the START command or Reference Manual for additional details. The only character-mode programs which will run properly within the Take Command window are those which can handle input and output delivered through pipes. In technical terms, these are programs which read all input from the DOS or OS/2 "standard input" device, and write output to the "standard output" or "standard error" device. Applications which use command-line parameters (rather than user input or "question and answer" dialogs), and which use simple scrolling (TTY-style) output, are the ones most likely to work well. Common applications which run successfully in the Take Command window include program development software like compilers and linkers, and some command-line utilities. Programs which use "direct video" output to write complex screen displays, require dialog with the user, or display graphics, must be run in their own window. Many OS/2 character-mode programs meet this test, as do some DOS programs. However, some programs -- especially DOS programs which appear to work this way may in fact use internal tricks or contain internal restrictions which are not compatible with piped input and output. For this reason, you will need to experiment to determine which of your DOS and OS/2 character-mode applications can run successfully within the Take Command window. If you try an application and it does not work, first try using Ctrl-C or Ctrl-Break to interrupt the application. If this does not work you can close the Take Command window with the mouse to clean up the offending application, then restart Take Command from your desktop. Applications which do not run properly within the Take Command window can still be run from Take Command, but will have to use their own window. TTY application support for DOS programs depends on the TCNPDOS.COM file distributed with Take Command. This file must be available in the same directory as TCMDOS2.EXE. If it is not, Take Command will display an error message if you try to run a DOS application within the Take Command window. ═══ 2.1.4. The Take Command Screen ═══ The Take Command screen has five parts: the title bar, menu bar, toolbar, command window, and status bar. The Title Bar is the same as the one used in most OS/2 applications, with a control menu button on the left and the maximize and minimize buttons on the right. You can change the text that appears on the Title Bar, and adjust the size of the Take Command window, with the WINDOW command. The command window accepts your input at the prompt, and displays Take Command's output. You can use the scroll bars or the up arrow and down arrow keys to view text that has scrolled off the window. You can also save the contents of the command window and scrollback buffer to a file, copy text from the command window to the clipboard, and copy text from the clipboard or the command window to the command line. If you use a laptop or LCD screen and find the "I-Beam" cursor in the Take Command window difficult to see, use an IBeamCursor = No directive in the [TakeCommand] section of the TCMDOS2.INI file to force the use of an arrow cursor in all parts of the window. The next few sections discuss the menu bar, tool bar, and status bar portions of the Take Command screen. ═══ 2.1.4.1. Take Command Menus ═══ Like all OS/2 PM applications, Take Command displays a menu bar along the top of the Take Command window. To select a particular menu item, click once on the menu heading, or use Alt+x where x is the underlined letter on the menu bar (for example, Alt+F displays the File menu). The items on the menu bar allow you to select a variety of Take Command features: File Menu Edit Menu Apps Menu Options or Setup Menu Utilities Menu Help Menu ═══ 2.1.4.1.1. File Menu ═══ The File menu allows you to save or print the screen buffer, or exit Take Command. Save to File... Saves the contents of the screen buffer to a file. A Save As dialog box appears in which you can enter the name of the file that you wish to use. Print... Sends the contents of the screen buffer to the printer. A Print dialog box appears in which you can select print options. Refresh Redraws everything on the Take Command window (use this selection if the display appears incorrect, for example if it is not repainted properly after another application exits). You can also press F5 at the Take Command prompt to refresh the screen. Shutdown Shuts down OS/2. Exit Ends the current Take Command session. ═══ 2.1.4.1.2. Edit Menu ═══ The Edit menu allows you to copy text between the Take Command window and the OS/2 clipboard. To use the the Copy command you must first select a block of text with the mouse or with the Select All command, below. If you hold down the mouse button 2 while you select a block of text, that block will be copied to the clipboard automatically when you release the button. Note that you can also access the clipboard with redirection to or from the CLIP: device, or with the @CLIP variable function. For more information on copying text see Highlighting and Copying Text. Cut Removes selected text from the command line and copies it to the OS/2 clipboard. This option is only available when you have selected text on the command line; it does not apply to selections anywhere else on the screen, or in the scrollback buffer. Copy Copies selected text from the Take Command screen buffer to the OS/2 clipboard. Paste Copies text from the OS/2 clipboard to the Take Command command line. If the text you insert contains a line feed or carriage return, the command line will be executed just as if you had pressed Enter. If you insert multiple lines, each line will be treated like a command typed at the prompt. Delete Removes selected text from the command line. Like Cut, this option is only available when you have selected text on the command line. Copy + Paste Copies the selected text directly to the command line. Select All Marks the entire contents of the Take Command scrollback buffer as selected text. ═══ 2.1.4.1.3. Apps Menu ═══ The Apps menu allows you to start applications or switch to the desktop. Run Displays the run dialog from which you can run an application or batch file. Take Command remembers the commands you have run from this dialog in the current session. To select from this list click on the drop-down arrow to the right of the "Command Line" field, or press Alt-down arrow [Alt-]. To scroll through the list line by line press the down arrow []. Goto Desktop Minimizes the Take Command window and switches the input focus to the OS/2 desktop. OS/2 window Starts an OS/2 text-mode window (using the command processor defined in the SET OS2_SHELL statement in CONFIG.SYS). DOS window Starts a windowed DOS text-mode window (using the command processor defined in the SHELL statement in CONFIG.SYS). Win 3.x Window Starts a seamless WinOS2 window in 386 enhanced mode, running your Windows shell (e.g., Program manager or Take Commad/16). ═══ 2.1.4.1.4. Options or Setup Menu ═══ The Setup menu lets you control the configuration of Take Command. Configure Take Command Opens the configuration notebook which you can use to change the configuration of Take Command. Configure Tool Bar Opens the toolbar dialog, to allow you to create or modify buttons for the Take Command tool bar. Configure TTY Apps Opens the TTY applications dialog in which you can specify character-mode DOS and OS/2 applications to run under Take Command's TTY application support. Font Displays a font selection submenu which allows you to choose the font for the command window, tool bar, or status bar. The command window is restricted to monospaced fonts (having the same fixed width for all characters, rather than varying the width based on each character's shape), but the tool bar and status bar can use any installed font. Command window: Selects the font for the main Take Command window. You can choose any monospaced font that has been properly installed in OS/2. (A monospaced font is one which uses the same fixed width for all characters, rather than varying the width based on each character's shape.) When you change the font, everything in the command window is displayed in the new font. You cannot mix fonts in the Take Command command window. Note: Some fonts will not display all of the characters used by Take Command. In particular, the DRAWBOX, DRAWHLINE, and DRAWVLINE commands use line-drawing characters which are not included in many standard fonts. The standard OS/2 monospaced fonts (Courier, System Monospaced, and System VIO) do include these characters when an English language character set is used. You can experiment with different fonts by using DRAWBOX or a similar command to display line drawing characters in the command window. Then use Select Font to choose a different font. When you leave the dialog, the new font will be used to display the entire command window, including the line drawing characters. You can select different fonts until you find one that satisfies you. Tool bar: Selects the font for the tool bar. Status bar: Selects the font for the status bar. Logging Controls logging via a submenu with two choices (see the LOG command for more details on logging): Command: Enables or disables command logging using the default OS2LOG file or the file you have chosen with the LOG command or the LogName directive in the TCMDOS2.INI file. History: Enables or disables command history logging using the default OS2HLOG file or the file you have specified with the LOG /H command or the HistLogName directive in the TCMDOS2.INI file. Show Tool Bar Select this item to enable or disable the Take Command tool bar, which appears near the top of the Take Command window. The tool bar will not appear unless at least one item has been defined for it with the Configure Tool Bar command, above. Show Status Bar Select this item to enable or disable the Take Command status bar, which appears near the bottom of the Take Command window. ═══ 2.1.4.1.5. Utilities Menu ═══ The Utilities menu invokes dialogs to search for files and text or to set up Take Command aliases, environment variables, or file descriptions. It can also start your editor. Search Files/Text Opens the search files dialog which lets you search for files or text interactively (see FFIND to search from the command line). Once Take Command has created a list of files based on your specifications, you can double-click on a file name and Take Command will display an information box about the file. From the information box, you can choose to list, edit, or run the file. Descriptions Opens the descriptions dialog in which you can view and change the descriptions of files in any directory available on your system. See DESCRIBE for details on file descriptions. Aliases Opens the aliases dialog in which you can view and change the list of current aliases. You can also use this window to import aliases from a file or save all current aliases in a file. Any changes you make will take effect as soon as you close the Aliases window. For more information on aliases see the ALIAS command. Environment Opens the environment dialog in which you can view and change the current environment. Any changes you make will be immediately recorded in Take Command's environment. Editor Starts the OS/2 E editor or any other editor you have specified with the Editor directive in TCMDOS2.INI or on the Commands page of the Configuration Notebook. ═══ 2.1.4.1.6. Help Menu ═══ Help Index Displays the index for the Take Command help. General Help Displays the table of contents for the Take Command help. Keys Help Displays help for the Take Command command line. From this help page you can select a subtopic which covers the keystroke information you need (e.g. command line editing, command history window, etc.). Product Information Displays Take Command version, copyright, and license information. ═══ 2.1.4.2. Tool Bar ═══ The Take Command screen has an optional Tool Bar that you can use to execute internal or external commands, aliases, batch files, and applications with the click of a mouse. To create buttons for the Tool Bar, select Configure Tool Bar from the Setup menu. This selection displays the tool bar dialog. You can define up to 24 Tool Bar buttons. When you first install Take Command a sample tool bar is included. Use the tool bar dialog to remove or modify any of the sample buttons, or add buttons of your own. To enable or disable the Tool Bar, use the ToolBarOn directive in TCMDOS2.INI, the Tool Bar Enable setting on the Display page in the configuration notebook, or the Show Tool Bar command in the Setup menu . The configuration dialog and TCMDOS2.INI settings are modified when you enable and disable the tool bar from the Setup menu. This preserves the tool bar state when you close Take Command, and restores it the next time you start a Take Command session. ═══ 2.1.4.3. Status Bar ═══ The Take Command screen has an optional Status Bar that shows information about your system. To enable or disable the Status Bar, use the StatusBarOn directive in TCMDOS2 .INI, the Status Bar Enable setting on the Display page in the configuration notebook, or the Show Status Bar command in the Setup menu. The configuration dialog and TCMDOS2.INI settings are modified when you enable and disable the status bar from the Setup menu. This preserves the tool bar state when you close Take Command, and restores it the next time you start a Take Command session. The Status Bar shows 5 pieces of information: The Date, based on the OS/2 clock. The Time, based on the OS/2 clock. The size of the OS/2 swap file. The state of the Caps Lock key on the keyboard. The state of the Num Lock key on the keyboard. If the OS/2 swap file is not stored in the \OS2\SYSTEM directory of the boot drive, you must use the SwapFilePath directive in TCMDOS2.INI or Take Command will not be able to display the swap file size in the status bar. ═══ 2.1.4.4. Dialogs ═══ The Take Command menus invoke several dialog boxes: Save To File Dialog Print Dialog Run Dialog Configuration Notebook Toolbar Dialog TTY Apps Dialog Search Files Dialog Descriptions Dialog Aliases Dialog Environment Dialog ═══ 2.1.4.4.1. Save To File Dialog ═══ This standard "Save As" dialog box allows you to select the file to use to save the contents of the screen buffer. ═══ 2.1.4.4.2. Print Dialog ═══ This dialog allows you to print the contents of the screen buffer. You can select the printer to use, the print priority, and the number of copies. The Properties button will take you to the properties dialog for the printer you have selected. If you have selected some text in the buffer, the Selection checkbox is automatically marked. If you leave it marked, Take Command prints only the selected text. If you remove the check mark, the entire buffer is printed. ═══ 2.1.4.4.3. Run Dialog ═══ The Apps/Run menu leads to the Run Program dialog. In the Command Line edit box, you can enter the name of any executable program plus command-line parameters. If you click on the arrow to the right of the edit box, the dialog displays a list of previous commands you have entered during the current Take Command session. The Normal, Minimized, and Maximized radio buttons determine the type of window that will be used for the program. If you select Minimized, the program will start as an icon on the desktop or in the Minimized Window Viewer (depending on your system default location for minimized window icons). Maximized starts the program in a full-screen window. Normal lets the operating system select the size and position of the program's window. The Browse button leads to a standard file browser, from which you can select any executable program. Your choice will be placed in the Command Line edit box, and you can add parameters before pressing Enter or selecting OK to run the program. ═══ 2.1.4.4.4. Toolbar Dialog ═══ This dialog allows you to define or modify buttons on the tool bar . Select the button you want to define or modify in the box on the left. Enter the button's label and the command to be executed when you select the button in the fields at the bottom of the dialog box. You can enter multiple commands in the Command field by separating them with the command separator character [&]. You can use the Browse button to find a path and filename to be entered at the beginning of the Command field. Before entering a command to start an application program, be sure to check whether the application must be started in a particular directory. If so, you should use a CDD command in the Command field before the application name, for example: cdd d:\source & d:\os2\apps\epm.exe If the command line begins with an at-sign [@] the command will not be added to the command history. Otherwise, all commands executed from the tool bar are stored in the history. Use the radio buttons to select how you want the command to be executed: * Echo means display the tool bar command on the command line, but do not execute it. You can add additional text to the line if you wish, then press Enter to execute the command. This is the default setting. * Echo & Execute means display the tool bar command on the command line, then execute it immediately, without waiting for you to press Enter. * Execute w/o Echo means execute the tool bar command immediately, without waiting for you to press Enter, and without displaying the command. The Font Size setting applies to all of the buttons on the tool bar. If you make the font size too large (or make the Take Command window too small), buttons on the right hand end of the toolbar may not be visible even if the Take Command window is expanded to fill the screen. If you exit by choosing the OK button, any changes you have made will be saved in the TCMDOS2.INI file, and reloaded automatically the next time you start Take Command. If you use the Cancel button, your changes will be discarded. If you don't specify a label for a button, a small space is created on the tool bar. For example, if you define buttons 5 and 7 but leave button 6 blank, Take Command will leave a space between buttons 5 and 7 when the tool bar is displayed. You can use this feature to separate groups of buttons on the tool bar; however, the total number of buttons, including empty buttons, cannot exceed 24. If you want to rearrange the order of the buttons on the tool bar, use an editor (e.g. OS/2's E editor) to edit the [Buttons] section of the .INI file. Simply rearrange the lines into the order you wish, and renumber the buttons accordingly. ═══ 2.1.4.4.5. TTY Apps Dialog ═══ This dialog allows you to specify which character-mode applications can be run within the Take Command window. If you are not familiar with the issues involved in running character-mode applications inside the Take Command window, read the separate section on Starting Character-Mode Applications before using this dialog. The list box on the left shows currently defined TTY applications. The Command field shows the command line for the currently selected application. You can specify an executable file name (e.g. CHKDSK.COM), or a full path name (e.g. C:\OS2\CHKDSK.COM). If you use a full path name, the entry will apply only to that specific file. If you use just the file name, the entry will apply to any file of that name, regardless of its location. (For advanced use of this field to name an entire directory of TTY applications, see the end of this section.) The OS/2 and DOS radio buttons control whether Take Command treats the application as a DOS or OS/2 program. The Enable checkbox enables or disables an application. If the box is checked, the application will be run within the Take Command window. If the box is not checked, the entry will be ignored. This allows you to temporarily disable an application (without removing it from the list) in order to test its compatibility with Take Command's TTY application support. Your copy of Take Command comes with a list of applications which can be run within the Take Command window. The list is visible when you open the dialog, and is also included in the README.DOC file. However, all applications in the list are initially disabled to ensure maximum compatibility. This prevents problems if you have a program with the same name as one we tested, but which is not the same program or the same version. To enable any application, select it and check the Enable box. To modify an entry which is already in the TTY applications list, select the application in the box on the left and press Enter (or double-click). Modify the Command field, the application type (DOS or OS/2), and the Enable checkbox as desired. To add a new entry, select the Add button. Fill in the Command field, set the application type, and check the Enable button if desired. You can use the Browse button to find a path and filename to be entered at the beginning of the Command field. After creating a new entry you must press Enter to copy the new entry to the listbox. If you do not, the information about the new application will be discarded. To delete an entry, select it in the list box, then select the Delete button. If you exit by choosing the OK button, any changes you have made will be saved in the [TTYApps] of TCMDOS2.INI, and reloaded automatically the next time you start Take Command. If you use the Cancel button, your changes will be discarded. In addition to the options described above, you can also enter a path without a filename in the Command field (e.g., C:\OS2UTILS). This will tell Take Command to treat all DOS or OS/2 character-mode programs in the specified directory as TTY applications. If you use this option the OS2, DOS, and Enable buttons apply to all applications in the specified directory. This approach is useful if you have many applications of the same type in a single directory, but before you use it you should review the content of the directory carefully to be sure all the character-mode programs stored there are compatible with Take Command's TTY application support. If you do choose to configure an entire directory for TTY application support, you can create exceptions by entering specific filenames from that directory into the dialog as well. For example, if you enable the directory C:\OS2UTILS for TTY support, you could also add a listing for C:\OS2UTILS\MYAPP.EXE (or simply for MYAPP.EXE, with no path), and make sure the Enable box is not checked for the MYAPP entry. This would prevent MYAPP.EXE from being treated as a TTY application despite the entry for the directory as a whole. If you use this approach, the two listings can appear in any order. TTY application support for DOS programs depends on the TCNPDOS.COM file distributed with Take Command. This file must be available in the same directory as TCMDOS2.EXE. If it is not, Take Command will display an error message if you try to run a DOS application within the Take Command window. ═══ 2.1.4.4.6. Search Files Dialog ═══ The Search Files/Text dialog box gives you the same features as the FFIND command, in dialog form. Enter the file name or names you wish search in the Files field. You can use wildcards and include lists as part of the file name. To select files from previous searches in the same Take Command session, click on the down arrow beside the Files field, or press the up arrow [] or down arrow [] while the input cursor is in the Files field. You can also use the Browse button to find files to include in the search. Enter the text (or hexadecimal values) you are searching for in the Text field. You can use extended wildards in the search string to increase the flexibility of the search. Use back-quotes [`] around the text if you want to search for characters which would otherwise be interpreted as wildcards, such as the asterisk [*], question mark [?], or square brackets. For example, to search for an A, followed by some number of other characters, followed by a B, enter the A*B as your search string. To search for the literal string A*B (A, followed by an asterisk, followed by B), enter `A*B` as your search string search string (the closing back-quote is optional). Enter the drive(s) you want to search in the Disks field. This field is ignored unless Entire Disk is selected in the Search portion of the dialog. If you select All Hard Disks, this field is set automatically to include all hard disk drive letters Take Command finds on your system. The Match Case box, when it is selected, makes the search case- sensitive. To search for specific hexadecimal values (for example, to look for non-printing characters), check Hex Search and enter the string in the Text field as a series of one- or two-digit hexadecimal characters, separated by spaces (e.g., 42 6F 70). See the ASCII Table for hexadecimal values of ASCII and extended ASCII characters. If you enable All Lines, every line from every file that contains the search text will be displayed. If this option is not enabled, only the first line from such a file will be displayed. Unless you enable the Hidden Files option, files with the hidden attribute will not be included in the search. The radio buttons in the Search area let you specify where you want Take Command to look for files. If you select Dir Only or Dir & Subdirs, the search will begin in the current default directory, shown above the Files box. If you select Entire Disk, Take Command will use the drives that you specified in the Disks field. If you select All Hard Disks, Take Command will search all the hard disk drives it finds on your system. To start the search, press the Find button. Once the search has started the Find button changes to a Stop button, which can use to interrupt the search before it is finished. Once Take Command has finished searching, you can save the list of matching files with the Export button. As you move the cursor over the list of matching files, information about each file appears below the file list. If you select one of the matching files in the list (by double-clicking on it, or selecting it with the cursor and pressing Enter), Take Command will display another dialog with complete directory information about the file. From this second dialog you can Run the file (if it is an executable file, a batch file, or has an executable extension), display the file with the LIST command, or Edit the file. If you choose List, the cursor will be placed on the first matching text within the file. When you exit from LIST or the editor, the original list of matching files will still be available. ═══ 2.1.4.4.7. Descriptions Dialog ═══ This dialog allows you to create, modify, or delete file descriptions (if you are not familiar with Take Command file descriptions, see the DESCRIBE command for details). A list of files in the current directory is shown in the pane on the left side of the dialog. As you move the cursor in the pane, the description for the file (if any) is shown in the Description field. You can use this field to edit or create the selected file's description. After changing a description you must press Enter (or select the OK button and close the dialog) to record your changes on the disk. If you do not (for example, if you change a description, then select another file without first pressing Enter), your changes will be discarded. If you click Cancel any changes to the current description are discarded, and the dialog is closed. Cancel does not undo previous changes which were saved by pressing the Enter key as described above. To delete a description, select the file, move to the description field and delete all of the description text, then press Enter or click OK. To work in a different drive or directory, use the Drive and/or Directory fields on the right side of the dialog to select the desired location. The dialog automatically includes all files in the list. To select a specific group of files of your own choosing, type a new filename in the Filename box. File descriptions can also be entered or changed with the DESCRIBE command, and are visible when you use the DIR and SELECT commands. ═══ 2.1.4.4.8. Aliases Dialog ═══ The current list of aliases is shown in the pane on the left of this dialog box. As you move the cursor in the pane, the name of the alias under the cursor is shown in the Name field and its definition is shown in the Value field. You can use these fields to edit the alias name or value. To add a new alias to the list, use the Add button. The Name and Value fields will be cleared so you can enter new values in each. To save the new entry, switch to a different entry or press Enter. The Delete button deletes the highlighted alias. The Import button reads a list of aliases from a file (similar to the ALIAS /R command). The Export button writes the current list to a file. Changes you make in this dialog are not saved in the alias list until you click the OK button. If you click Cancel the changes are discarded. ═══ 2.1.4.4.9. Environment Dialog ═══ The current environment variables are shown in the pane on the left of this dialog box. As you move the cursor in the pane, the name of each entry appears in the Name field and its value appears in the Value field. You can use these fields to edit the environment entry. To add a entry to the list, use the Add button. The Name and Value fields will be cleared so you can enter new values in each. To save the new entry, switch to a different entry or press Enter. The Delete button deletes the highlighted environment variable. The Import button reads a list of environment variables from a file (similar to the SET /R command). The Export button writes the current list to a file. Changes you make in this dialog are not saved in the environment until you click the OK button. If you click Cancel the changes are discarded. ═══ 2.1.5. Scrollback Buffer ═══ Take Command retains the text displayed on its screen in a "scrollback buffer". You can scroll through this buffer using the mouse and the vertical scroll bar at the right side of the Take Command window, just as you can in any OS/2 GUI application. You can also use the up-arrow [] and down-arrow [] keys to scroll the display one line at a time from the keyboard, and the PgUp and PgDn keys to scroll one page at a time. If you scroll back through the buffer to view previous output, and then enter text on the command line, Take Command will automatically return to the bottom of the buffer to display the text. If you prefer to use the arrow and PgUp keys to access the command history (as in 4DOS and 4OS2), see the SwapScrollKeys directive in the TCMDOS2.INI file, or the corresponding option on the Command Line page of the configuration dialogs. SwapScrollKeys switches the keystroke mapping so that the , , and PgUp Keys manipulate the command history, and Ctrl-, Ctrl-, Ctrl-PgUp, and Ctrl-PgDn are used to control the scrollback buffer. For more details see Scrolling and History Keystrokes. You can set the size of the scrollback buffer on the Display page of the configuration notebook (available from the Setup menu), or with the ScreenBufSize directive in TCMDOS2.INI. To clear the entire scrollback buffer, use the CLS /C command. ═══ 2.1.6. Resizing the Take Command Window ═══ You can resize the Take Command window at any time with standard OS/2 techniques (e.g., by dragging a corner with the mouse). Resizing the window changes the number of rows and columns of text which will fit in the command window (the actual number of rows and columns for any given window size depends on the font you are using). Take Command reacts to these changes using two sets of rules: one for the height and one for the width. When the height of the command window changes, future commands simply use the new height as you see it on the screen. For example, if you reduce the window to three rows high and do a DIR /P (display a directory of files and pause at the bottom of each visual "page"), DIR will display two lines of output, a prompt ("Press any key to continue..."), and then pause. If you expand the window to 40 lines high and repeat the same command, DIR will display 39 lines, a prompt, and then pause. However, when the width of the window changes, Take Command must check the current "virtual screen width". The virtual width is the maximum number of characters on each line in Take Command's internal screen buffer. You can think of it as the width of the data which can be displayed in the Take Command window, including an invisible portion to the right of the window's right-hand edge. When the virtual width is larger than the actual width, a standard horizontal scroll bar is displayed to allow you to see any hidden output. The screen height normally starts at 25 lines; you can alter this default with the ScreenRows directive in the .INI file, or the Height setting on the Display page of the configuration dialogs. The _ROWS internal variable can be used to determine the current screen height. The virtual screen width starts at 80 columns or the number of columns which fit into the startup Take Command window, whichever is larger. You can alter the default minimum width of 80 columns with the ScreenColumns directive in the .INI file, or the Width setting on the Display page of the configuration dialogs. The _COLUMNS internal variable can be used to determine the current virtual screen width. If you use keyboard commands or the mouse to expand the Take Command window beyond its previous virtual width, the virtual width is automatically increased. This ensures that the internal buffer can hold lines which will fill the newly enlarged window. If you contract the window, the virtual width is not reduced because this might require removing output already on the screen or in the scrollback buffer. As a result, widening the window will make future commands use the new enlarged size (for example, as the window is widened DIR /W, which displays a "wide" directory listing, will display additional columns of file names). However, if the window is narrowed future commands will still remember the enlarged virtual width, and display data to the right of the window edge. The horizontal scroll bar will make this data visible. When the font is changed, Take Command will recalculate the virtual screen width. The new virtual width will be the width set by the Screen Columns directive or on the Display page of the configuration dialogs, or the current width of the window in the new font, whichever is larger. ═══ 2.1.7. Highlighting and Copying Text ═══ While you are working at the Take Command prompt you can use common keystrokes to edit commands, and use the OS/2 clipboard to copy text between Take Command and other applications. You can also select all of the text in the Take Command screen buffer by using the Select All command on the Edit menu. To copy text from the Take Command window to the clipboard, first use the mouse to highlight the text, then press Ctrl-Ins, or use the Copy command on the Edit menu. If you double-click on a word in the Take Command window, the entire word is highlighted or selected. You can also mark the text using mouse button 2 (normally, the right mouse button); in this case the text will be copied to the clipboard immediately when you release the mouse button. To highlight text on the command line use the Shift key in conjunction with the Left, Right, Ctrl-Left, Ctrl-Right, Home, and End cursor movement keys. The Del key will delete any highlighted text on the command line, or you can type new text to replace the highlighted text. While the Take Command window contains text, it is not a document window like those used by word processors and other similar software, and you cannot move the cursor throughout the window as you can in text processing programs. As a result, you cannot use the OS/2 shortcut keys like Shift-Left or Shift-Right to highlight text in the window. These keys work only at the command line; to highlight text elsewhere in the window you must use the mouse. To copy text from the clipboard to the command line use Shift-Ins, or the Paste command on the Edit menu. To paste text from elsewhere in the Take Command window directly onto the command line, highlight the text with the mouse and press Ctrl-Shift- Ins, or use the Copy+Paste command on the Edit menu. This is equivalent to highlighting the text and pressing Ctrl-Ins followed by Shift-Ins. It's a convenient way to copy a filename from a previous DIR or other command directly to the command line. You should use caution when pasting text containing carriage return or line feed characters onto the command line. If the text you insert contains one of these characters the command line will be executed just as if you had pressed Enter. If you insert multiple lines, the text will be treated just like multiple lines of commands typed at the prompt. You can also use OS/2's Drag and Drop facility to paste a filename from another application onto the command line. ═══ 2.1.8. Using Drag and Drop ═══ Take Command is compatible with the OS/2 Drag-and-Drop facility. To add a filename to the command line using drag and drop, simply drag the file from another application using the mouse and release the mouse button with the file icon anywhere inside the Take Command window. The full name of the file will be pasted onto the command line at the current cursor position. Take Command is a drag and drop "client," which means it can accept files dragged in from other applications and paste their names onto the command line as described above. It is not a drag and drop "server," so you cannot drag filenames from the Take Command window into other applications. However, you can copy filenames and other text from the Take Command screen to other applications using the clipboard; see Highlighting and Copying Text for details. ═══ 2.1.9. Cursor Display on LCD Screens ═══ If you use a laptop or LCD screen and find the "I-Beam" cursor in the Take Command window difficult to see, use an IBeamCursor = No directive in the [TakeCommand] section of TCMDOS2.INI to force the use of an arrow cursor in all parts of the window. ═══ 2.1.10. Take Command for 4DOS and 4OS2 Users ═══ If you're a 4DOS or 4OS2 user, many of the features in Take Command will seem very familiar. Because the underlying command processing in Take Command is based on 4DOS and 4OS2, you'll find the features of those products are readily accessible. All the commands and switches you're familiar with work the same way and have the same meaning in Take Command; the only exceptions are those that don't make sense in the OS/2 GUI environment. Other 4DOS and 4OS2 features are included in Take Command as well -- you'll find support for command line editing, command and directory histories, aliases, .BTM files, and virtually all the other features you already know. Even if you've never used 4DOS or 4OS2, you'll notice plenty of familiar items in Take Command. Like these products, Take Command is compatible with the default OS/2 command processor (CMD.EXE), which you've probably used from the objects in the OS/2 Command Prompts folder. There are also a few differences between running under 4DOS and 4OS2 (or CMD.EXE) and running under Take Command. In order to support the Take Command screen scrollback buffer, some Take Command keystrokes are different from what you may be used to in 4DOS or 4OS2. See Scrolling and History Keystrokes for more details. Some command-line editing defaults have also been changed to conform more closely to OS/2 GUI conventions. In Take Command the default editing mode is insert, not overstrike, and the default insert-mode cursor is a line, not a block. You can change these defaults with statements in TCMDOS2.INI or via the Command Line page of the configuration notebook, accessible from the Setup menu. Before using your 4DOS or 4OS2 batch files and aliases under Take Command, see Using 4OS2 Batch Files and Aliases. What's new in Take Command are OS/2 GUI-related features, including: * A built-in scrollback buffer that lets you look back through the output from past commands. * A standard menu bar for access to many commonly-used Take Command features. * A status bar showing memory and resource usage. * A customizable tool bar that gives you quick access to commands and applications. * Dialogs, accessible from the Options and Utilities menus, for editing environment variables, aliases, file descriptions, and startup parameters (the TCMDOS2.INI file). * High-speed, dialog-based file and text search (see "Search Files/Text" on the Utilities menu). The new FFIND command gives you the same capabilities at the Take Command prompt. * Commands like ACTIVATE, MSGBOX, and QUERYBOX that allow you to use OS/2 features and control OS/2 applications from your batch files. ═══ 2.2. Using the Command Line ═══ Take Command displays a [c:\] prompt when it is waiting for you to enter a command. (The actual text depends on the current drive and directory as well as your PROMPT settings.) This is called the command line and the prompt is asking you to enter a command, an alias or batch file name, or the instructions necessary to begin an application program. This section explains the features that will help you while you are typing in commands and how keystrokes are interpreted when you enter them at the command line. The keystrokes discussed here are the ones normally used by Take Command. If you prefer using different keystrokes to perform these functions, you can assign new ones with key mapping directives in the .INI file. The command line features documented in this section are: Command-Line Editing Command History and Recall Command History Window Command Names and Parameters Filename Completion Automatic Directory Changes Directory History Window (includes details about local and global directory histories) Multiple Commands Expanding and Disabling Aliases Command-Line Length Limits Additional command-line features are documented under File Selection, Directory Navigation, and Other Features. ═══ 2.2.1. Command-Line Editing ═══ The command line works like a single-line word processor, allowing you to edit any part of the command at any time before you press Enter to execute it, or Esc to erase it. The command line extends to a maximum of 1023 characters. You can use the following editing keys when you are typing a command (the words Ctrl and Shift mean to press the Ctrl Or Shift key together with the other key named): Cursor Movement Keys:  Move the cursor left one character.  Move the cursor right one character. Ctrl- Move the cursor left one word. Ctrl- Move the cursor right one word. Home Move the cursor to the beginning of the line. End Move the cursor to the end of the line. Insert and Delete: Ins Toggle between insert and overtype mode. Del Delete the character at the cursor. Backspace Delete the character to the left of the cursor. Ctrl- Delete the word or partial word to the left of the cursor. Ctrl- or Ctrl-Bksp Delete the word or partial word to the right of the cursor. Ctrl-Home Delete from the beginning of the line to the cursor. Ctrl-End Delete from the cursor to the end of the line. Esc Delete the entire line. Shift-Ins Insert the text from the clipboard at the current cursor postion on the command line. Ctrl-Shift-Ins Insert the highlighed text (from anywhere in the window) at the current cursor postion on the command line. Execution: Ctrl-C or Ctrl-Break Cancel the command line. Enter Execute the command line. To highlight text on the command line use the mouse, or hold down the Shift key and use any of the cursor movement keys listed above. You can select a complete word by placing the cursor anywhere in the word and double-clicking with the mouse. Once you have selected or highlighted text on the command line, any new text you type will replace the highlighted text. If you press Bksp or Del while there is text highlighted on the command line, the highlighted text will be deleted. While you are working at the Take Command prompt, you can use the OS/2 clipboard to copy text between Take Command and other applications (see Highlighting and Copying Text. You can also use Drag and Drop to paste a filename from another application onto the command line. Most of the command-line editing capabilities are also available when Take Command prompts you for a line of input. For example, you can use the command-line editing keys when DESCRIBE prompts for a file description, when INPUT prompts for input from an alias or batch file, or when LIST prompts you for a search string. If you want your input at the command line to be in a different color from the command processor's prompts or output, you can use the Display page of the configuration notebook, or the InputColors directive in the TCMDOS2.INI file. Take Command will prompt for additional command-line text when you include the escape character as the very last character of a typed command line. The default escape character is the caret [^]. For example: [c:\] echo The quick brown fox jumped over the lazy^ More? sleeping dog. > alphabet Sometimes you may want to enter one of the command line editing keystrokes on the command line instead of performing the key's usual action. For example, suppose you have a program that requires a Ctrl-R character on its command line. Normally you couldn't type this keystroke at the prompt, because it would be interpreted as a "Delete word right" command. To get around this problem, use the special keystroke Alt-255. You enter Alt-255 by holding down the Alt key while you type 255 on the numeric keypad, then releasing the Alt key (you must use the number keys on the numeric pad; the row of keys at the top of your keyboard won't work). This forces Take Command to interpret the next keystroke literally and places it on the command line, ignoring any special meaning it would normally have as a command-line editing or history keystroke. You can use Alt-255 to suppress the normal meaning of command-line editing keystrokes even if they have been reassigned with key mapping directives in the TCMDOS2.INI file, and Alt-255 itself can be reassigned with the CommandEscape directive. ═══ 2.2.2. Command History and Recall ═══ Each time you execute a command, the entire command line is saved in a command history list. You can display the saved commands, search the list, modify commands, and rerun commands. The command history is available at the command prompt and in a special command history window. Command History Keys: Ctrl- Recall the previous (or most recent) command, or the most recent command that matches a partial command line. Ctrl- Recall the next (or oldest) command, or the oldest command that matches a partial command line. F3 Fill in the rest of the command line from the previous command, beginning at the current cursor position. Ctrl-D Delete the currently displayed history list entry, erase the command line, and display the previous (matching) history list entry. Ctrl-E Display the last entry in the history list. Ctrl-K Save the current command line in the history list without executing it, and then clear the command line. Ctrl-Enter Copy the current command line to the end of the history list even it has not been altered, then execute it. @ As the first character in a line: Do not save the current line in the history list when it is executed, and do not store it in the CMDLINE environment variable. Use the Ctrl- key repeatedly to scan back through the history list. When the desired command appears, press Enter to execute it again. After you have found a command, you can edit it before pressing Enter. The history list is normally "circular". If you move to the last command in the list and then press the Ctrl- one more time, you'll see the first command in the list. Similarly, if you move to the first command in the list and then press the Ctrl- one more time, you'll see the last command in the list. You can disable this feature and make command history recall stop at the beginning or end of the list by turning off History Wrap on the Command Line 1 page of the configuration notebook, or setting HistWrap to No in TCMDOS2.INI. If you prefer to use the arrow keys to access the command history with having to press Ctrl (as in 4OS2 and 4DOS), see the SwapScrollKeys directive in TCMDOS2.INI, or the corresponding option on the Command Line 1 page of the configuration notebook. SwapScrollKeys switches the keystroke mapping so that the , , and PgUp keys manipulate the command history, and Ctrl-, Ctrl-, Ctrl-PgUp, and Ctrl-PgDn are used to control the scrollback buffer. For more details see Scrolling and History Keystrokes. You can search the command history list to find a previous command quickly using command completion. Just enter the first few characters of the command you want to find and press Ctrl-. You only need to enter enough characters to identify the command that you want to find. If you press the Ctrl-  key a second time, you will see the previous command that matches. The system will beep if there are no matching commands. The search process stops as soon as you type one of the editing keys, whether or not the line is changed. At that point, the line you're viewing becomes the new line to match if you press Ctrl- again. You can specify the size of the command history list on the Startup page of the Configuration notebook, or with the History directive in TCMDOS2.INI. When the list is full, the oldest commands are discarded to make room for new ones. You can also use the Command Line 1 page of the configuration notebook HistMin directive in the .INI file to enable or disable history saves and to specify the shortest command line that will be saved. When you execute a command from the history, that command remains in the history list in its original position. The command is not copied to the end of the list (unless you modify it). If you want each command to be copied or moved to the end of the list when it is re-executed, set HistCopy or HistMove to Yes in TCMDOS2.INI or select Copy to End or Move to End on the Command Line 1 page of the configuration notebook. If you select either of these options, the list entry identified as "current" (the entry from which commands are retrieved when you press Ctrl-Up Arrow) is also adjusted to refer to the end of the history list after each recalled command is executed. Local and Global Command History The command history can be stored in either a "local" or "global" list. With a local history list, any changes made to the history will only affect the current copy of Take Command. They will not be visible in other shells, or other sessions. With a global history list, all copies of Take Command will share the same command history, and any changes made to the history in one copy will affect all other copies. Global lists are the default for Take Command. You can control the type of history list with the LocalHistory directive in TCMDOS2.INI, and with the /L and /LH options of the START command. If you select a global history list for Take Command you can share the history among all copies of Take Command running in any session. When you close all Take Command sessions, the memory for the global history list is released, and a new, empty history list is created the next time you start Take Command. If you want the command history to be retained in memory even when no Take Command session is running, see the SHRALIAS command, which retains the global alias, command history, and directory history lists. SHRALIAS retains the command history in memory, but cannot preserve it when OS/2 itself is shut down. To save history list when restarting OS/2, you must store it in a file and reload it after the system restarts. For details on how to do so, see the HISTORY command. ═══ 2.2.3. Command History Window ═══ You can view the command history in a scrollable command history window, and select the command to re-execute or modify from those displayed in the window. Command History Window Keys: Ctrl-PgUp (from the command line) Open the command history window. or Ctrl-PgDn  Scroll the display up one line.  Scroll the display down one line.  Scroll the display left 4 columns.  Scroll the display right 4 columns. PgUp Scroll the display up one page. PgDn Scroll the display down one page. Ctrl-PgUp Go to the beginning of the history list. or Home Ctrl-PgDn Go to the end of the history list. or End Ctrl-D Delete the selected line from the history list. Enter Execute the selected line. Ctrl-Enter Move the selected line to the command line for editing. or Ctrl-Double Click To activate the command history window press Ctrl-PgUp or Ctrl-PgDn at the command line. A window will appear in the upper right corner of the screen, with the command you most recently executed marked with a highlight. (If you just finished re-executing a command from the history, then the next command in sequence will be highlighted.) Once you have selected a command in the history window, press Enter or double-click with the mouse to execute it immediately. Press Ctrl- Enter or hold down the Ctrl key while you double-click with the mouse to move the line to the prompt for editing (you cannot edit the line directly in the history window). You can view a "filtered" history window by typing some characters on the command line, then pressing Ctrl-PgUp or Ctrl-PgDn. Only those commands matching the typed characters will be displayed in the window. See Popup Windows for information on customizing window position and size. If you prefer to use the PgUp key to access the command history without having to press Ctrl (as in 4OS2 and 4DOS), see the SwapScrollKeys directive in TCMDOS2.INI, or the corresponding option on the Command Line page of the configuration notebook. SwapScrollKeys switches the keystroke mapping so that the  and PgUp keys manipulate the command history, and Ctrl-, Ctrl-, Ctrl-PgUp, and Ctrl-PgDn are used to control the scrollback buffer. For more details see Scrolling and History Keystrokes. ═══ 2.3. Command Names and Parameters ═══ When you enter a command you type its name at the prompt, followed by a space and any parameters for the command. For example, all of these could be valid commands: [c:\] dir [c:\] copy file1 file2 d:\ [c:\] f:\util\mapmem /v [c:\] "c:\my programs\jp software\take command\tcmdos2.exe" /l The last three commands above include both a command name, and one or more parameters. There are no spaces within the command name (except in quoted file names), but there is a space between the command name and any parameeters, and there are spaces between the parameters. Some commands may work when parameters are entered directly after the command (without an intervening space, e.g. dir/p), or when several parameters are entered without spaces between them (e.g. dir /2/p). A very few older programs may even require this approach. However leaving out spaces in this way is usually technically incorrect, and is not recommended as a general practice, as it may not work for all commands. If the command name includes a path, the elements must be separated with backslashes (e.g. f:\util\mapmem). If you are accustomed to Unix syntax where forward slashes are used in command paths, and want Take Command to recognize this approach, you can set UnixPaths to Yes in TCMDOS2.INI. For more information on command entry see Multiple Commands and Command-Line Length Limits. ═══ 2.3.1. Filename Completion ═══ Filename completion can help you by filling in a complete file name on the command line when you only remember or woant to type part of the name. Filename completion can be used at the command line, which is explained here, and in a filename completion window. Filename Completion Keys: F8 Get the previous matching filename. or Shift-Tab F9 Get the next matching filename. or Tab Ctrl-Shift-Tab Keep the current matching filename and display the next matching name immediately after the current one. or F11 For example, if you know the name of a file begins AU but you can't remember the rest of the name, type: [c:\] copy au and then press the Tab key or F9 key. Take Command will search the current directory for filenames that begin AU and insert the first one onto the command line in place of the AU that you typed. If this is the file that you want, simply complete the command. If Take Command didn't find the file that you were looking for, press Tab or F9 again to substitute the next filename that begins with AU. When there are no more filenames that match your pattern, the system will beep each time you press Tab or F9. If you go past the filename that you want, press Shift-Tab or F8 to back up and return to the previous matching filename. After you back up to the first filename, the system will beep each time you press Shift-Tab or F8. If you want to enter more than one matching filename on the same command line, press Ctrl-Shift-Tab or F11 when each desired name appears. This will keep that name and place the next matching filename after it on the command line. You can then use Tab (or F9) and Shift-Tab (or F8) and Ctrl-Shift-Tab (or F11) to move through the remaining matching files. The pattern you use for matching may contain any valid filename characters, as well as wildcard characters and extended wildcards. For example, you can copy the first matching .TXT file by typing [c:\] copy *.txt and then pressing Tab. If you don't specify part of a filename before pressing Tab, the matching pattern will be *.*. If you type a filename without an extension, Take Command will add "*.*" to the name. It will also place a "*" after a partial extension. If you are typing a group of file names in an Include Lists, the part of the include list at the cursor will be used as the pattern to match. When filename completion is used at the start of the command line, it will only match directories, executable files, and files with executable extensions , since these are the only file names that it makes sense to use at the start of a command. If a directory is found, a "\" will be appended to it to enable an automatic directory change. Several topics are related to filename completion. See Appending Backslashes to Directory Names Customizing Filename Completion Filename Completion Window ═══ 2.3.1.1. Appending Backslashes to Directory Names ═══ If you set the AppendToDir directive in the TCMDOS2.INI file, or the corresponding option on the Command Line 1 page of the configuration dialogs, Take Command will add a trailing backslash [\] to all directory names. This feature can be especially handy if you use filename completion to specify files that are not in the current directory -- a succession of Tab (or F9) and Ctrl-Shift-Tab keystrokes can build a complete path to the file you want to work with. The following example shows the use of this technique to edit the file C:\DATA\FINANCE\MAPS.DAT. The lines which include "" show where F9 (or Tab) is pressed; the other lines show how the command line appears after the previous F9 or Tab (the example is displayed on several lines here, but all appears at a single command prompt when you actually perform the steps): 1 [c:\] edit \da 2 [c:\] edit \data\ 3 [c:\] edit \data\f 4 [c:\] edit \data\frank.doc 5 [c:\] edit \data\finance\ 6 [c:\] edit \data\finance\map 7 [c:\] edit \data\finance\maps.dat Note that F9 was pressed twice in succession on lines 3 and 4, because the file name displayed on line 3 was not what was needed Ч we were looking for the FINANCE directory, which came up the second time F9 was pressed. In this example, filename completion saves about half the keystrokes that would be required to type the name in full. If you are using long file or directory names, the savings can be much greater. ═══ 2.3.1.2. Customizing Filename Completion ═══ You can customize filename completion for any internal or external command or alias. This allows the command processor to display filenames intelligently based on the command you are entering. For example, you might want to see only .TXT files when you use filename completion in the EDIT command. To customize filename completion you can use the Command Line 1 page of the configuration dialogs, or set the FileCompletion directive manually in the TCMDOS2.INI file. You can also use the FILECOMPLETION environment variable. If you use both, the environment variable will override the settings in your .INI file. You may find it useful to use the environment variable for experimenting, then create permanent settings with the configuration dialogs or the FileCompletion directive. The format for both the environment variable and the TCMDOS2.INI file is: cmd1:ext1 ext2 ...; cmd2: ... where "cmd" is a command name and "ext" is a file extension (which may include wildcards) or one of the following file types: DIRS Directories RDONLY Read-only files HIDDEN Hidden files SYSTEM System files ARCHIVE Files modified since the last backup The command name is the internal command, alias command, or executable file name (without a path). For example, to have file completion return only directories for the CD command and only .C and .ASM files for a Windows editor called WinEdit, you would use this setting for filename completion in the configuration dialogs: FileCompletion=cd:dirs; winedit:c asm To set the same values using the environment variable, you would use this line: [c:\] set filecompletion=cd:dirs; winedit:c asm With this setting in effect, if you type "CD " and then pressed Tab, Take Command will return only directories, not files. If you type "B " and press Tab, you will see only names of .C and .ASM files. Take Command does not check your command line for aliases before matching the commands for customized file completion. Instead, it ignores any path or file extension information in the first word of the command, and then searches the FILECOMPLETION environment variable and the FileCompletion directive the TCMDOS2.INI file to find a match that will limit the files selected for filename completion ═══ 2.3.1.3. Filename Completion Window ═══ You can view filenames in a scrollable filename completion window and select the file you want to work with. To activate the window, press F7 or Ctrl-Tab at the command line. You will see a window in the upper-right corner of the screen, with a sorted list of files that match any partial filename you have entered on the command line. If you haven't yet entered a file name, the window will contain the name of all files in the current directory. You can search for a name by typing the first few characters; see Popup Windows for details. (Ctrl-Tab will work only if your keyboard and keyboard driver support it. If it does not work on your system, use F7 instead.) See Popup Windows for information on customizing window position and size. Filename Completion Window Keys: F7 (from the command line) Open the filename completion window. or Ctrl-Tab  Scroll the display up one line.  Scroll the display down one line. Scroll the display left 4 columns. Scroll the display right 4 columns. PgUp Scroll the display up one page. PgDn Scroll the display down one page. Ctrl-PgUp Go to the beginning of the filename list. or Home Ctrl-PgDn Go to the end of the filename list. or End Enter Insert the selected filename into the command line. or Double click ═══ 2.3.2. Automatic Directory Changes ═══ [Automatic directory changes are part of a set of comprehensive directory navigation features built into Take Command. For a summary of these features, and more information on the Extended Directory Searches and CDPATH features mentioned below, see the Directory Navigation section.] The automatic directory change feature lets you change directories quickly from the command prompt, without entering an explicit CD or CDD command. To do so, simply type the name of the directory you want to change to at the prompt, with a backslash [\] at the end. For example: [c:\] tcmd\ [c:\tcmd] This feature can make directory changes very simple when it's combined with Extended Directory Searches or CDPATH. If you have enabled either of those features, Take Command will use them in searching for any directory you change to with an automatic directory change (see Directory Navigation for more information on CDPATH and Extended Directory Searches). For example, suppose Extended Directory Searches are enabled, and the directory WIN exists on drive E:. You can change to this directory with a single word on the command line: [c:\tcmd] win\ [e:\win] (Depending on the way Extended Directory Changes are configured, and the number of subdirectories on your disk whose names contain the string WIN, when you execute such a command you may see an immediate change as shown above, or a popup window which contains a list of subdirectories named WIN to choose from.) The text before the backslash can include a drive letter, a full path, a partial path, or a UNC name. Commands like "....\" can be used to move up the directory tree quickly (see Extended Parent Directory Names). Automatic directory changes save the current directory, so it can be recalled with a "CDD -" or "CD -" command. For example, any of the following are valid automatic directory change entries: [c:\] d:\data\finance\ [c:\] archives\ [c:\] ...\util\os2\ [c:\] \\server\vol1\george\ The first and last examples change to the named directory. The second changes to the ARCHIVES subdirectory of the current directory, and the third changes to the UTIL\OS2 subdirectory of the directory which is two levels "up" from the current directory in the tree. ═══ 2.3.3.  Directory History Window ═══ [The directory history window is part of a set of compreshensive directory navigation features built into Take Command. For a summary of thse features, and more information on enhanced directory navigation features, see Directory Navigation.] Directory History Window Keys: F6 Open the directory history window.  Scroll the display up one line.  Scroll the display down one line. Scroll the display left 4 columns. Scroll the display right 4 columns. PgUp Scroll the display up one page. PgDn Scroll the display down one page. Ctrl-PgUp Go to the beginning of the directory list. or Home Ctrl-PgDn Go to the end of the directory list. or End Ctrl-D Delete the selected line from the directory list. Enter Change to the selected drive and directory. Ctrl-Enter Move the selected line to the command line for editing. See Popup Windows for information on customizing window position and size. The current directory is recorded automatically in the directory history list just before each change to a new directory or drive. You can view the directory history from a directory history window and change to any drive and directory on the list. To activate the directory history window, press F6 at the command line. You can then select a new directory with the Enter key or by double-clicking with the mouse. If the directory history list becomes full, old entries are deleted to make room for new ones. You can set the size of the list from the Startup page of the configuration dialogs, or with the DirHistory directive in the TCMDOS2.INI file or with the corresponding itmes on the Startup and Command Line pages of the configuration notebook. You can change the keys used in the window with key mapping directives in the TCMDOS2.INI file. In order to conserve space, each directory name is recorded just once in the directory history, even if you move into and out of that directory several times. The directory history can be stored in either a "local" or "global" list; see below for details. When you switch directories the original directory is saved in the directory history list, regardless of whether you change directories at the command line, from within a batch file, or from within an alias. However, directory changes made by external directory navigation utilities or other external programs are not recorded by Take Command. Local and Global Directory History The directory history can be stored in either a local or global list. With a local directory history list, any changes made to the list will only affect the current Take Command session. They will not be visible in other sessions. With a global list, all Take Command sessions will share the same directory history, and any changes made to the list in one copy will affect all other copies. Global lists are the default. You can control the type of directory history list with the LocalDirHistory directive in TCMDOS2.INI and with the /L and /LD options of the START command. When you close all Take Command sessions, the memory for the global directory history list is released, and a new, empty directory history list is created the next time you start Take Command. If you want the directory histy list to be retained in memory even when no copy Take Command is running, you need to execute the SHRALIAS command, which performs this service for the global command history, directory history, and alias lists. There is no fixed rule for deciding whether to use a local or global directory history list. Depending on your work style, you may find it most convenient to use one type, or a mixture of types in different sessions. We recommend that you start with a global directory history, then modify it if you find a situation where the default is not convenient. ═══ 2.3.4. Multiple Commands ═══ You can type several commands on the same command line, separated by an ampersand [&]. For example, if you know you want to copy all of your .TXT files to drive A: and then run CHKDSK to be sure that drive A's file structure is in good shape, you could enter the following command: [c:\] copy *.txt a: & chkdsk a: You may put as many commands on the command line as you wish, as long as the total length of the command line does not exceed 1023 characters. You can use multiple commands in alias definitions and batch files and as well as from the command line. If you don't like using the default command separator, you can pick another character using the SETDOS /C command or the CommandSep directive in the TCMDOS2.INI file. If you plan to share aliases or batch files between Take Command and 4DOS, 4OS2, or 4NT, see Special Character Compatibility for details about choosing compatible command separators for two or more products. ═══ 2.3.5. Expanding and Disabling Aliases ═══ A few command line options are specifically related aliases, and are documened briefly here for completeness. If you are not familiar with alises, see Aliases and the ALIAS command for complete details. You can expand an alias on the command line and view or edit the results by pressing Ctrl-F before the command is executed. Doing so is especially useful when you are developing and debugging a complex alias or if you want to make sure that an alias that you may have forgotten won't change the intent of your command. At times, you may want to temporarily disable an alias that you have defined. To do so, precede the command with an asterisk [*]. For example, if you have an alias for DIR which changes the display format, you can use the following command to bypass the alias and display the directory in the standard format: [c:\] *dir ═══ 2.3.6. Command-Line Length Limits ═══ When you first enter a command at the prompt or in an alias or batch file, it can be up to 1,023 characters long. As Take Command scans the command line and substitutes the contents of aliases and environment variables for their names, the line usually gets longer. This expanded line is stored in an internal buffer which allows each individual command to grow to 1,023 characters during the expansion process. In addition, if you have multiple commands on a single line, during expansion the entire line can grow to as much as 2,047 characters. If your use of aliases or environment variables causes the command line to exceed either of these limits as it is expanded, you will see a "Command line too long" error message and the remainder of the line will not be executed. ═══ 2.4. File Selection ═══ Most internal commands (like COPY, DIR, etc.) work on a file or a group of files. Besides typing the exact name of the file you want to work with, you can use several shorthand forms for naming or selecting files and the applications associated with them. Most of these features apply to Take Command commands only, and can not be used to pass file names to external programs unless those programs were specifically written to support these features. The file selection features are: Extended Parent Directory Names Wildcards Date, Time, and Size Ranges File Exclusion Ranges Multiple Filenames Include Lists Executable Extensions ═══ 2.4.1. Extended Parent Directory Names ═══ Take Command allows you to extend the traditional syntax for naming the parent directory, by adding additional [.] characters. Each additional [.] represents an additional directory level above the current directory. For example, .\FILE.DAT refers to a file in the current directory, ..\FILE.DAT refers to a file one level up (in the parent directory), and ...\FILE.DAT refers to a file two levels up (in the parent of the parent directory). If you are in the C:\DATA\FINANCE\JANUARY directory and want to copy the file LETTERS.DAT from the directory C:\DATA to drive A: [C:\DATA\FINANCE\JANUARY] copy ...\LETTERS.DAT A: ═══ 2.4.2. Wildcards ═══ Wildcards let you specify a file or group of files by typing a partial filename. The appropriate directory is scanned to find all of the files that match the partial name you have specified. Wildcards are usually used to specify which files should be processed by a command. If you need to specify which files should not be processed see File Exclusion Ranges (for internal commands), or EXCEPT (for external commands). Most internal commands accept filenames with wildcards anywhere that a full filename can be used. There are two wildcard characters, the asterisk [*] and the question mark [?], plus a special method of specifying a range of permissible characters. An asterisk [*] in a filename means "any zero or more characters in this position." For example, this command will display a list of all files in the current directory: [c:\] dir *.* If you want to see all of the files with a .TXT extension, you could type this: [c:\] dir *.txt If you know that the file you are looking for has a base name that begins with ST and an extension that begins with .D, you can find it this way. Filenames such as STATE.DAT, STEVEN.DOC, and ST.D will all be displayed: [c:\] dir st*.d* Take Command also lets you use the asterisk to match filenames with specific letters somewhere inside the name. The following example will display any file with a .TXT extension that has the letters AM together anywhere inside its base name. It will, for example, display AMPLE.TXT, STAMP.TXT, CLAM.TXT, and AM.TXT: [c:\] dir *am*.txt A question mark [?] matches any single filename character. You can put the question mark anywhere in a filename and use as many question marks as you need. The following example will display files with names like LETTER.DOC, LATTER.DAT, and LITTER.DU: [c:\] dir l?tter.d?? The use of an asterisk wildcard before other characters, and of the character ranges discussed below, are enhancements to the standard wildcard syntax, and are not likely to work properly with software other than Take Command, 4DOS, 4OS2, and 4NT. Advanced Wildcards "Extra" question marks in your wildcard specification are ignored if the file name is shorter than the wildcard specification. For example, if you have files called LETTER.DOC, LETTER1.DOC, and LETTERA.DOC, this command will display all three names: [c:\] dir letter?.doc The file LETTER.DOC is included in the display because the "extra" question mark at the end of "LETTER?" is ignored when matching the shorter name LETTER. In some cases, the question mark wildcard may be too general. You can also specify what characters you want to accept (or exclude) in a particular position in the filename by using square brackets. Inside the brackets, you can put the individual acceptable characters or ranges of characters. For example, if you wanted to match LETTER0.DOC through LETTER9.DOC, you could use this command: [c:\] dir letter[0-9].doc You could find all files that have a vowel as the second letter in their name this way. This example also demonstrates how to mix the wildcard characters: [c:\] dir ?[aeiouy]*.* You can exclude a group of characters or a range of characters by using an exclamation mark [!] as the first character inside the brackets. This example displays all filenames that are at least 2 characters long except those which have a vowel as the second letter in their names: [c:\] dir ?[!aeiouy]*.* The next example, which selects files such as AIP, BIP, and TIP but not NIP, demonstrates how you can use multiple ranges inside the brackets. It will accept a file that begins with an A, B, C, D, T, U, or V: [c:\] dir [a-dt-v]ip You may use a question mark character inside the brackets, but its meaning is slightly different than a normal (unbracketed) question mark wildcard. A normal question mark wildcard matches any character, but will be ignored when matching a name shorter than the wildcard specification, as described above. A question mark inside brackets will match any character, but will not be discarded when matching shorter filenames. For example: [c:\] dir letter[?].doc will display LETTER1.DOC and LETTERA.DOC, but not LETTER.DOC. A pair of brackets with no characters between them [], or an exclamation point and question mark together [!?], will match only if there is no character in that position. For example, [c:\] dir letter[].doc will not display LETTER1.DOC or LETTERA.DOC, but will display LETTER.DOC. This is most useful for commands like [c:\] dir /I"[]" *.btm which will display a list of all .BTM files which don't have a description, because the empty brackets match only an empty description string (DIR /I selects files to display based on their descriptions). You can repeat any of the wildcard characters in any combination you desire within a single file name. For example, the following command lists all files which have an A, B, or C as the third character, followed by zero or more additional characters, followed by a D, E, or F, followed optionally by some additional characters, and with an extension beginning with P or Q. You probably won't need to do anything this complex, but we've included it to show you the flexibility of extended wildcards: [c:\] dir ??[abc]*[def]*.[pq]* You can also use the square bracket wildcard syntax to work around a conflict between HPFS filenames containing semicolons [;], and the use of a semicolon to indicate an include list . For example, if you have a file on an HPFS drive named C:\DATA\LETTER1;V2 and you enter this command: [c:\] del \data\letter1;v2 you will not get the results you expect. Instead of deleting the named file, Take Command will attempt to delete LETTER1 and then V2, because the semicolon indicates an include list. However, if you use square brackets around the semicolon it will be interpreted as a filename character, and not as an include list separator. For example, this command would delete the file named above: [c:\] del \data\letter1[;]v2 ═══ 2.4.3. Ranges ═══ Date, Time, and Size Ranges File Exclusion Ranges ═══ 2.4.3.1. Date, Time, and Size Ranges ═══ Most internal commands which accept wildcards also allow date, time, and size ranges to further define the files that you wish to work with. Take Command will examine each file's size and timestamps (a record of when the file was created, last modified, or last accessed) to determine which files meet the range criteria that you have specified. (Take Command for OS/2 also supports File Exclusion Ranges to exclude files from a command. These are similar to date, time, and size ranges, but have a slightly different purpose and therefore are documented separately.) A range begins with the switch character (/), followed by a left square bracket ("[") and a character that specifies the range type: "s" for a size range, "d" for a date range, or "t" for a time range. The "s", "d", or "t" is followed by a start value, and an optional comma and end value. The range ends with a right square bracket ("]"). For example, to select files between 100 and 200 bytes long you could use the range /[s100,200]. See the individual range types for details on specifying ranges: Date Ranges Time Ranges Size Ranges Using Ranges All ranges are inclusive. For example, a size range which selects files from 10,000 to 20,000 bytes long will match files that are exactly 10,000 bytes and 20,000 bytes long, as well as all sizes in between; a date range that selects files last modified between 10-27-97 and 10-30-97 will include files modified on each of those dates, and on the two days in between. If you reverse range start and end values, Take Command will recognize the reversal, and will use the second (lower) value as the start point of the range and the first (higher) value as its end point. For example, the range above for files between 10 and 200 bytes long could also be entered as /[s200,100]. If you combine two types of ranges, a file must satisfy both ranges to be included. For example, /[d2-8-97,2-9-97] /[s1024,2048] means files last modified between February 8 and February 9, 1997, which are also between 1,024 and 2,048 bytes long. When you use a date, time, or size range in a command, it should immediately follow the command name. Unlike some command switches which apply to only part of the command line, the range usually applies to all file names specified for the command. Any exceptions are noted in the descriptions of individual commands. For example, to get a directory of all the *.C files dated October 1, 1997, you could use this command: [c:\] dir /[d10-1-97,+0] *.c To delete all of the 0-byte files on your hard disk, you could use this command: [c:\] del /[s0,0] *.* /s And to copy all of the non-zero byte files that you changed yesterday or today to your floppy disk, you can use this command: [c:\] copy /[d-1] /[s1] *.* a: File systems which support long filenames maintain 3 sets of dates and times for each file: creation, last access, and last modification. By default, date and time ranges work with the last modification time stamp. You can use the "last access" (a) or "created" (c) time stamp in a date or time range with the syntax: /[da...] or /[dc...] or /[ta...] or /[tc...] For example, to select files that were last accessed yesterday or today: /[da-1] Date, time, and size ranges can be used with the ATTRIB, COPY, DEL, DESCRIBE, DIR, EXCEPT, FFIND, FOR, LIST, MOVE, RD, REN, SELECT, and TYPE commands. They cannot be used with filename completion or in filename arguments for variable functions. ═══ 2.4.3.1.1. Date Ranges ═══ Date ranges select files that were created or last modified at any time between the two dates. For example, /[d12-1-97,12-5-97] selects files that were last modified between December 1, 1997, and December 5, 1997. The time for the starting date defaults to 00:00:00 and the time for the ending date defaults to 23:59:59. You can alter these defaults, if you wish, by including a start and stop time inside the date range. The time is separated from the date with an at sign [@]. For example, the range /[d7-1-97@8:00a,7-3-97@6:00p] selects files that were modified at any time between 8:00 am on July 1, 1997 and 6:00 PM on July 3, 1997. If you prefer, you can specify the times in 24-hour format (e.g., @18:00 for the end time in the previous example). The date format and the separator character used in the time may vary depending upon your country information. If you omit the second argument in a date range, Take Command substitutes the current date and time. For example, /[d10-1-97] selects files dated between October 1, 1997 and today. You can use an offset value for either the beginning or ending date, or both. An offset begins with a plus sign [+] or a minus sign [- ] followed by an integer. If you use an offset for the second value, it is calculated relative to the first. If you use an offset for the first (or only) value, the current date is used as the basis for calculation. For example: Specification Selects Files /[d10-27-97,+3] modified between 10-27-97 and 10-30-97 /[d10-27-97,-3] modified between 10-24-97 and 10-27-97 /[d-0] modified today (from today minus zero days, to today) /[d-1] modified yesterday or today (from today minus one day, to today) /[d-1,+0] modified yesterday (from today minus one day, to zero days after that) As a shorthand way of specifying files modified today, you can also use /[d]; this has the same effect as the /[d-0] example shown above. To select files last modified n days ago or earlier, use /[d- n,1/1/80]. For example, to get a directory of all files last modified 3 days or more before today (i.e., those files not modified within the last 3 days), you could use this command: [c:\] dir /[d-3,1/1/80] This reversed date range (with the later date given first) will be handled correctly by Take Command. It takes advantage of the facts that an offset in the start date is relative to today, and that the base or "zero" point for PC file dates is January 1, 1980, or earlier. You cannot use offsets in the time portion of a date range (the part after an at sign), but you can combine a time with a date offset. For example, /[d12-8-97@12:00,+2@12:00] selects files that were last modified between noon on December 8 and noon on December 10, 1997. Similarly, /[d-2@15:00,+1] selects files last modified between 3:00 PM the day before yesterday and the end of the day one day after that, i.e., yesterday. The second time defaults to the end of the day because no time is given. OS/2 HPFS partitions keep track of the date a file was created, the date it was last modified (written), and the date it was last accessed. You can specify which date and time is used in a date range by adding a (access), c (creation), or w (write) after the d in the range. For example, to select all files created between February 1, 1997 and February 7, 1997 you would use /[dc2-1-97,2-7- 97]. If you don't specify which date and time to use, Take Command will use the date the file was last modified (written). ═══ 2.4.3.1.2. Time Ranges ═══ A time range specifies a file modification time without reference to the date. For example, to select files modified between noon and 2:00 PM on any date, use /[t12:00p,2:00p]. The times in a time range can either be in 12-hour format, with a trailing "a" for AM or "p" for PM, or in 24-hour format. If you omit the second argument in a time range, you will select files that were modified between the first time and the current time, on any date. You can also use offsets, beginning with a plus sign [+] or a minus sign [-] for either or both of the arguments in a time range. The offset values are interpreted as minutes. Some examples: Specification Selects Files /[t12:00p,+120] modified between noon and 2:00 PM on any date /[t-120,+120] modified between two hours ago and the current time on any date /[t0:00,11:59] modified in the morning on any date The separator character used in the time may vary depending upon your country information. OS/2 HPFS partitions keep track of the time a file was created, the time it was last modified (written), and the time it was last accessed. You can specify which time is used in a time range by adding a (access), c (creation), or w (write) after the d in the range. For example, to select all files created between noon and 2 pm, you would use /[tc12:00p,2:00p]. If you don't specify which time to use, Take Command will use the time the file was last modified (written). ═══ 2.4.3.1.3. Size Ranges ═══ Size ranges simply select files whose size is between the limits given. For example, /[s10000,20000] selects files between 10,000 and 20,000 bytes long. Either or both values in a size range can end with "k" to indicate thousands of bytes, "K" to indicate kilobytes (1,024 bytes), "m" to indicate millions of bytes, or "M" to indicate megabytes (1,048,576 bytes). For example, the range above could be rewritten as /[s10k,20k]. All ranges are inclusive. Both examples above will match files that are exactly 10,000 bytes and 20,000 bytes long, as well as all sizes in between. The second argument of a size range is optional. If you use a single argument, like /[s10k], you will select files of that size or larger. You can also precede the second argument with a plus sign [+]; when you do, it is added to the first value to determine the largest file size to include in the search. For example, /[s10k,+1k] selects files from 10,000 through 11,000 bytes in size. Some further examples of size ranges: Specification Selects Files /[s0,0] of length zero(empty) /[s1M] 1 megabyte or more in length /[s10k,+200] between 10,000 and 10,200 bytes ═══ 2.4.3.2. File Exclusion Ranges ═══ Most internal commands which accept wildcards also accept file exclusion ranges to further define the files that you wish to work with. Take Command examines each file name and excludes files that match the names you have specified in a file exclusion range. A file exclusion range begins with the switch character (usually a slash), followed by a left square bracket and an exclamation mark ("[!") The range ends with a right square bracket ("]"). Inside the brackets, you can list one or more filenames to be excluded from the command. The filenames can include wildcards and extended wildcards, but cannot include path names or drive letters. The following example will display all files in the current directory except backup files (files with the extension .BAK or .BK!): [c:\] dir /[!*.bak *.bk!] *.* You can combine file exclusion ranges with date, time, and size ranges. This example displays all files that are 10K bytes or larger in size and that were created in the last 7 days, except .C and .H files: [c:\] dir /[s10k] /[d-7] /[!*.c *.h] *.* File exclusion ranges will only work for internal commands. The EXCEPT command can be used to exclude files from processing by many external commands. ═══ 2.4.4. Multiple Filenames ═══ Most file processing commands can work with multiple files at one time. To use multiple file names, you simply list the files one after another on the command line, separated by spaces. You can use wildcards in any or all of the filenames. For example, to copy all .TXT and .DOC files from the current directory to drive A, you could use this command: [c:\] copy *.txt *.doc a: If the files you want to work with are not in the default directory, you must include the full path with each filename: [c:\] copy a:\details\file1.txt a:\details\file1.doc c: Multiple filenames are handy when you want to match a group of files which cannot be defined with a single filename and wildcards. They let you be very specific about which files you want to work with in a command. When you use multiple filenames with a command that expects both a source and a destination, like COPY or MOVE, be sure that you always include a specific destination on the command line. If you don't, the command will assume that the last filename is the destination and may overwrite important files. Like extended wildcards and include lists, the multiple filename feature will work with internal commands but not with external programs, unless those programs have been written to handle multiple file names on the command line. If you have a list of files to process that's too long to put on the command line or too time-consuming to type, see the FOR and SELECT commands for other ways of passing multiple file names to a command. ═══ 2.4.5. Include Lists ═══ Any internal command that accepts multiple filenames will also accept one or more include lists. An include list is simply a group of filenames, with or without wildcards, separated by semicolons [;]. All files in the include list must be in the same directory. You may not add a space on either side of the semicolon. For example, you can shorten this command which uses multiple file names: [c:\] copy a:\details\file1.txt a:\details\file1.doc c: to this using an include list: [c:\] copy a:\details\file1.txt;file1.doc c: Include lists are similar to multiple filenames, but have three important differences. First, you don't have to repeat the path to your files if you use an include list, because all of the included files must be in the same directory. Second, if you use include lists, you aren't as likely to accidentally overwrite files if you forget a destination path for commands like COPY, because the last name in the list will be part of the include list, and won't be seen as the destination file name. (Include lists can only be used as the source parameter -- the location files are coming from -- for COPY and other similar commands. They cannot be used to specify a destination for files.) Third, multiple filenames and include lists are processed differently by the DIR and SELECT commands. If you use multiple filenames, all of the files matching the first filename are processed, then all of the files matching the second name, and so on. When you use an include list, all files that match any entry in the include list are processed together, and will appear together in the directory display or SELECT list. You can see this difference clearly if you experiment with both techniques and the DIR command. For example, [c:\] dir *.txt *.doc will list all the .TXT files with a directory header, the file list, and a summary of the total number of files and bytes used. Then it will do the same for the .DOC files. However, [c:\] dir *.txt;*.doc will display all the files in one list. Like extended wildcards and multiple filenames, the include list feature will work with internal commands, but not with external programs (unless they have been programmed especially to support it). The maximum length of an include list is 260 characters. ═══ 2.4.6. Executable Extensions ═══ Normally, when you type a filename (as opposed to an alias or internal command name) as the first word on the command line, Take Command looks for a file with that name to execute. The file's extension may be .EXE or .COM to indicate that it contains a program, it may have a batch file extension like .BTM, or the file's contents may indicate that it is executable. (To change the default list of extensions see the PATHEXT environment variable and the PathExt setting in TCMDOS2.INI.) You can add to this default list of extensions, and have Take Command take the action you want with files that are not executable programs or batch files. The action taken is always based on the file's extension. For example, you could start your text editor whenever you type the name of a .DOC file, or start your database manager whenever you type the name of a .DAT file. You can use environment variables to define the internal command, external program, batch file, or alias to run for each defined file extension. To create an executable extension use the SET command to create a new environment variable. An environment variable is recognized as an executable extension if its name begins with a period. The syntax for creating an executable extension is: set .ext=command [options] This tells Take Command to run the specified command whenever you name a file with the extension .ext at the prompt. .EXT is the executable file extension; command is the name of the internal command, external program, alias, or batch file to run; and [options] are any command-line startup options you want to specify for the program, batch file, or alias. For example, if you want to run a word processor called EDITOR whenever you type the name of a file that has an extension of .EDT, you could use this command: [c:\] set .edt=c:\edit\editor.exe If the command specified in an executable extension is a batch file or external program, Take Command will search the PATH for it if necessary. However, you can make sure that the correct program or batch file is used, and speed up the executable extension, by specifying the full name including drive, path, filename, and extension. To remove an executable extension, use the UNSET command to remove the corresponding variable. Once an executable extension is defined, any time you name a file with that extension the corresponding program, batch file, or alias is started, with the name of your file passed to it as a parameter. This example defines B.EXE (the Boxer text editor) as the processor for .C files: [c:\] set .c=c:\boxer\b.exe -Mxyz Now, if you have a file called HELLO.C and enter the command [c:\] hello -i30 This will be expanded to: c:\brief\b.exe -Mxyz hello.c -i30 Notice that the text from the .C environment variable is inserted at the beginning of the line, including any options, followed by the original file name plus its extension, and then the remainder of the original command line. In order for executable extensions to work, the command, program, batch file, or alias must be able to interpret the command line properly. For example, if a program you want to run doesn't accept a file name on its command line as shown in these examples, then executable extensions won't work with that program. Executable extensions may include wildcards, so you could, for example, run your text editor for any file with an extension beginning with T by defining an executable extension called .T*. Extended wildcards (e.g., DO[CT] for .DOC and .DOT files) may also be used. To remove an executable extension, use the UNSET command to remove the corresponding variable. ═══ 2.5.  Directory Navigation ═══ Take Command and OS/2 remember both a current or default drive for your system as a whole, and a current or default directory for every drive in your system. The current directory on the current drive is sometimes called the current working directory. With traditional command processors, you change the current drive by typing the new drive letter plus a colon at the prompt, and you change the current working directory with the CD command. Take Command supports those standard features, and offers a number of enhancements to make directory navigation much simpler and faster. This section begins with a summary of all Take Command directory navigation features. It also provides detailed documentation on the enhanced directory search features: Extended Directory Searches and the CDPATH. The Take Command directory navigation features are in three groups: features which help Take Command find the directory you want, methods for initiating a directory change with a minimal amount of typing, and methods for returning easily to directories you've recently used. Each group is summarized below. Finding Directories Traditional command processors require you to explicitly type the name of the directory you want to change to. Take Command supports this method, and also offer two significant enhancements: Extended Directory Searchesallow Take Command to search a "database" of all the directories on your system to find the one you want. The CDPATH allows you to enter a specific list of directories to be searched, rather than searching a database. Use CDPATH instead of Extended Directory Searches if you find the extended searches too broad, or your hard drive has too many directories for an efficient search. Initiating a Directory Change Take Command supports the traditional methods of changing directories, and also offer several more flexible approaches: Automatic directory changes allow you to type a directory name at the prompt and switch to it automatically, without typing an explicit CD or similar command. The CD command can change directories on a single drive, and can return to the most recently used directory. The CDD command changes drive and directory at the same time, and can return to the most recently used drive and directory. The PUSHD command changes the drive and directory like CDD, and records the previous directory in a directory "stack." You can view the stack with DIRS and return to the directory on the top of the stack with POPD. CDD, PUSHD, and automatic directory changes can also change to a network drive and directory mapped to a drive letter or specified with a UNC name. Returning to a Previous Directory Traditional command processors do not remember previously-used directories, and can only "return" to a directory by changing back to it with a standard drive change or CD command. Take Command supports three additional methods for returning to a previous directory: The CD - and CDD - commands can be used to return to the previous working directory (the one you used immediately before the current directory). Use these commands if you are working in two directories and alternating between them. The directory history window allows you to select one of several recently-used directories from a popup list and return to it immediately. The window displays the contents of the directory history list. The POPD command will return to the last directory saved by PUSHD. The directory stack holds 511 characters, enough for 20 to 40 typical drive and directory entries. ═══ 2.5.1. Extended Directory Searches ═══ When you change directories with an automatic directory change, CD, CDD, or PUSHD command, Take Command must find the directory you want to change to. To do so, it first uses the traditional method to find a new directory: it checks to see whether you have specified either the name of an existing subdirectory below the current directory, or the name of an existing directory with a full path or a drive letter. If you have, Take Command changes to that directory, and does no further searching. This traditional search method requires that you navigate manually through the directory tree, and type the entire name of each directory you want to change to. Extended Directory Searches speed up the navigation process dramatically by allowing Take Command to find the directory you want, even if you only enter a small part of its name. When the traditional search method fails, Take Command tries to find the directory you requested via the CDPATH, then via an Extended Directory Search. This section covers only Extended Directory Searches, which are more flexible and more commonly used than CDPATH. Extended Directory Searches use a database of directory names to facilitate changing to the correct directory. The database is used only if Extended Directory Searches are enabled, and if the explicit directory search and CDPATH search fail to find the directory you requested. An extended directory search automatically finds the correct path to the requested directory and changes to it if that directory exists in your directory database. If more than one directory in the database matches the name you have typed, a popup window appears and you can choose the directory you want. You can control the position and size of the popup directory search window from the Command Line 2 page of the configuration dialogs, or with the CDDWinLeft, CDDWinTop, CDDWinWidth, and CDDWinHeight directives in the .INI file. You can also change the keys used in the popup window with key mapping directives in the .INI file. To use extended directory searches, you must explicitly enable them (see below) and also create the directory database. The Extended Search Database To create or update the database of directory names, use the CDD /S command. When you create the database with CDD /S, you can specify which drives should be included. If you enable Extended Directory Searches and do not create the database, it will be created automatically the first time it is required, and will include all local hard drives. The database is stored in the file JPSTREE.IDX, which is placed in the root directory of drive C: by default. The same tree file is used by all JP Software command processors. You can specify a different location for this file on the Command Line 2 page of the configuration notebook or the TreePath directive in the TCMDOS2.INI file. If you are using two or more of our products on your computer and want to have different drives stored in the database for each, use the dialogs or the TreePath directive to place their database directories in different locations. If you use an internal command to create or delete a directory, the directory database is automatically updated to reflect the change to your directory structure. The updates occur if Take Command can find the JPSTREE.IDX file in the root directory of drive C: or in the location specified by the TreePath directive. The internal commands which can modify the directory structure and cause automatic updates of the file are MD, RD, COPY /S, DEL /X, MOVE /S, and REN. The MD /N command can be used to create a directory without updating the directory database. This is useful when creating a temporary directory which you do not want to appear in the database. Enabling Extended Searches To enable extended directory searches and control their operation, you must set the FuzzyCD directive in the TCMDOS2.INI file. You can set FuzzyCD either from the Command Line 2 page of the configuration notebook, or by editing the .INI file manually. If FuzzyCD = 0, extended searches are disabled, the JPSTREE database is ignored, and CD, CDD, PUSHD, and automatic directory changes search for directories using only explicit names and CDPATH. This is the default. If FuzzyCD = 1 and an extended search is required, then Take Command will search the JPSTREE database for directory names which exactly match the name you specified. If FuzzyCD = 2 and an extended search is required, Take Command will search the database for exact matches first, just as when FuzzyCD = 1. If the requested directory is not found, it will search the database a second time looking for directory names that begin with the name you specified. If FuzzyCD = 3 and an extended search is required, the command processor will search the database for exact matches first, just as when FuzzyCD = 1. If the requested directory is not found, it will search the database a second time looking for directory names that contain the name you specified anywhere within them. For example, suppose that you have a directory called C:\DATA\MYDIR, CDPATH is not set, and C:\DATA is not the current directory on drive C:. The following chart shows what CDD command you might use to change to this directory. FuzzyCD Setting CDD Command 0 cdd c:\data\mydir 1 cdd mydir 2 cdd myd 3 cdd yd An extended directory search is not used if you specify a full directory path (one beginning with a backslash [\], or a drive letter and a backslash). If you use a name which begins with a drive letter (e.g. C:MYDIR), the extended search will examine only directories on that drive. Forcing an Extended Search with Wildcards Normally you type a specific directory name for Take Command to locate, and the search proceeds as described in the preceding sections. However, you can also force the command processor to perform an extended directory search by using wildcard characters in the directory name. If you use a wildcard, an extended search will occur whether or not extended searches have been enabled. When Take Command is changing directories and it finds wildcards in the directory name, it skips the explicit search and CDPATH steps and goes directly to the extended search. If a single match is found, the change is made immediately. If more than one match is found, a popup window is displayed with all matching directories. Wildcards can only be used in the final directory name in the path (after the last backslash in the path name). For example you can find COMM\*A*.* (all directories whose parent directory is COMM and which have an A somewhere in their names), but you cannot find CO?M\*A*.* because it uses a wildcard before the last backslash. If you use wildcards in the directory name as described here, and the extended directory search database does not exist, it will be built automatically the first time a wildcard is used. You can update the database at any time with CDD /S. Internally, extended directory searches use wildcards to scan the directory database. If FuzzyCD is set to 2, an extended search looks for the name you typed followed by an asterisk (i.e., DIRNAME*). If FuzzyCD is set to 3, it looks for the name preceded and followed by an asterisk (i.e., *DIRNAME*). These internal wildcards will be used in addition to any wildcards you use in the name. For example if you search for ABC?DEF (ABC followed by any character followed by DEF) and FuzzyCD is set to 3, Take Command will actually search the directory database for *ABC?DEF*. Disabling Extended Searches in Batch Files When writing batch files you may want to use the CD or CDD command to switch directories without triggering an extended search. For example, you may need the search to fail (rather than search the extended search database) if a directory does not exist, or you may want to ensure that the extended search popup window does not appear in a batch file designed to run in unattended mode. To disable extended searches, use the /N option of CD or CDD. When this option is used and a directory does not exist below the current directory or on the CDPATH, the command will fail with an error message, and will not search the extended search database. For example this command might trigger an extended search: cdd testdir but this one will not: cdd /n testdir Note that this option is not available for PUSHD. To perform the same function when using PUSHD, save the current directory with PUSHD (without parameters) and then use CDD /N to change directories, for example: pushd cdd /n testdir ═══ 2.5.2. CDPATH ═══ When you change directories with an automatic directory change or the CD, CDD, or PUSHD command, Take Command must find the directory you want to change to. To do so, it first uses the traditional method to find a new directory. When the traditional search method fails, Take Command tries to find the directory you requested via the CDPATH, then via an Extended Directory Search. This section covers only the CDPATH. Enabling both CDPATH and Extended Directory Searches can yield confusing results, so we recommend that you do not use both features at the same time. If you prefer to explicitly list where Take Command should look for directories, use CDPATH. If you prefer to have Take Command look at all of the directory names on your disk, use Extended Directory Searches. CDPATH is an environment variable, and is similar to the PATH variable used to search for executable files: it contains an explicit list of directories to search when attempting to find a new directory. Take Command appends the specified directory name to each directory in CDPATH and attempts to change to that drive and directory. It stops when it finds a match or when it reaches the end of the CDPATH list. CDPATH is ignored if a complete directory name (one beginning with a backslash [\]) is specified, or if a drive letter is included in the name. It is only used when a name is given with no drive letter or leading backslash. CDPATH provides a quick way to find commonly used subdirectories in an explicit list of locations. You can create CDPATH with the SET command. The format of CDPATH is similar to that of PATH: a list of directories separated by semicolons [;]. For example, if you want the directory change commands to search the C:\DATA directory, the D:\SOFTWARE directory, and the root directory of drive E:\ for the subdirectories that you name, you should create CDPATH with this command: [c:\] set cdpath=c:\data;d:\software;e:\ Suppose you are currently in the directory C:\WP\LETTERS\JANUARY, and you'd like to change to D:\SOFTWARE\UTIL. You could change directories explicitly with the command: [c:\wp\letters\january] cdd d:\software\util However, because the D:\SOFTWARE directory is listed in your CDPATH variable as shown in the previous example (we'll assume it is the first directory in the list with a UTIL subdirectory), you can simply enter the command [c:\wp\letters\january] cdd util or, using an automatic directory change: [c:\wp\letters\january] util\ to change to D:\SOFTWARE\UTIL. As it handles this request, Take Command looks first in the current directory, and attempts to find the C:\WP\LETTERS\JANUARY\UTIL subdirectory. Then it looks at CDPATH, and appends the name you entered, UTIL, to each entry in the CDPATH variable Ч in other words, it tries to change to C:\DATA\UTIL, then to D:\SOFTWARE\UTIL. Because this change succeeds, the search stops and the directory change is complete. ═══ 2.6. Other Features ═══ This section includes details these Take Command features: Page and File Prompts Redirection and Piping Using the Keystack ANSI Support Critical Errors Conditional Commands Command Grouping The Escape Character ═══ 2.6.1. Page and File Prompts ═══ Several Take Command commands can generate prompts, which wait for you to press a key to view a new page or to perform a file activity. When Take Command is displaying information in page mode, for example with a DIR /P or SET /P command, it displays the message Press Esc to Quit or any other key to continue... At this prompt, you can press Esc, Ctrl-C, or Ctrl- Break if you want to quit the command. You can press almost any other key to continue with the command and see the next page of information. During file processing, if you have activated prompting with a command like DEL /P, you will see this prompt before processing every file: Y/N/R ? You can answer this prompt by pressing Y for "Yes, process this file;" N for "No, do not process this file;" R for "process the Remainder of the files without further prompting; or Esc for "cancel further processing for this argument." You can also press Ctrl-C or Ctrl-Break at this prompt to cancel the remainder of the command. If you press Ctrl-C or Ctrl-Break while a batch file is running, you will see a "Cancel batch job" prompt. For information on responses to this prompt see Interrupting a Batch File. ═══ 2.6.2. Redirection and Piping ═══ This section covers redirection and piping. You can use these features to change how Take Command and some application programs handle input and output. Internal commands and many external programs get their input from the computer's standard input device and send their output to the standard output device. Some programs also send special messages to the standard error device. Normally, the keyboard is used for standard input and the video screen for both standard output and standard error. Redirection and piping allow you to change these assignments temporarily. Redirection changes the standard input, standard output, or standard error device for a program or command from the default device (the keyboard or screen), to another device or to a file. Piping changes the standard output and / or standard error device so that the output of one command becomes the standard input for another program or command. ═══ 2.6.2.1. Redirection ═══ Redirection can be used to reassign the standard input, standard output, and standard error to a device like the printer or serial port, to a file or to the OS/2 clipboard. You must use some discretion when you use redirection with a device; there is no way to get input from the printer, for example. Redirection always applies to a specific command, and lasts only for the duration of that command. When the command is finished, the assignments for standard input, standard output, and standard error revert to whatever they were before the command. In the descritpions below, filename means either the name of a file or of an appropriate device (PRN, LPT1, LPT2, or LPT3 for printers; COM1 to COM4 for serial ports; CON for the keyboard and screen; CLIP for the clipboard, NUL for the "null" device, etc.). Here are the standard redirection options supported by Take Command (see below for additional redirection options using numeric file handles): < filename To get input from a file or device instead of from the keyboard > filename Redirect standard output to a file or device >& filename Redirect standard output and standard error to a file or device >&> filename Redirect standard error only to a file or device If you want to append output to the end of an existing file, rather than creating a new file, replace the first ">" in the output redirection symbol with ">>" (use >>, >>&, and >>&>). To use redirection, place the redirection symbol and filename at the end of the command line, after the command name and any parameters. For example, to redirect the output of the DIR command to a file called DIRLIST, you could use a command line like this: [c:\] dir /b *.dat > dirlist You can use both input and output redirection for the same command, if both are appropriate. For example, this command sends input to SORT from the file DIRLIST, and sends output from SORT to the file DIRLIST.SRT: [c:\] sort < dirlist > dirlist.srt You can redirect text to or from the OS/2 clipboard by using the pseudo-device name CLIP: (the colon is required). If you redirect the output of a single internal command like DIR, the redirection ends automatically when that command is done. If you start a batch file with redirection, all of the batch file's output is redirected, and redirection ends when the batch file is done. Similarly, if you use redirection at the end of a command group, all of the output from the command group is redirected, and redirection ends when the command group is done. Advanced Redirection Options When output is directed to a file with >, >&, or >&>, if the file already exists, it will be overwritten. You can protect existing files by using the SETDOS /N1 command, the "Protect redirected output files" setting on the Options 1 page of the configuration notebook, or the NoClobber directive in the TCMDOS2.INI file. When output is appended to a file with >>, >>&, or >>&>, the file will be created if it doesn't already exist. However, if NoClobber is set as described above, append redirection will not create a new file; instead, if the output file does not exist a "File not found" or similar error will be displayed. You can temporarily override the current setting of NoClobber by using an exclamation mark [!] after the redirection symbol. For example, to redirect the output of DIR to the file DIROUT, and allow overwriting of any existing file despite the NoClobber setting: [c:\] dir >! dirout Redirection is fully nestable. For example, you can invoke a batch file and redirect all of its output to a file or device. Output redirection on a command within the batch file will take effect for that command only; when the command is completed, output will revert to the redirected output file or device in use for the batch file as a whole. You can use redirection if you need to create a zero-byte file. To do so, enter >filename as a command, with no actual command before the > character. In addition to the redirection options above, Take Command also supports the OS/2 CMD.EXE syntax: n>file Redirect handle n to the named file n>&m Redirect handle n to the same place as handle m [n] and [m] are one-digit file handles between 0 and 9. You may not put any spaces between the n and the >, or between the >, &, and m in the second form. Take Command defines "0" as standard input, "1" as standard output, and "2" as standard error. Handles 3 to 9 will probably not be useful unless you have an application which uses those handles for a specific, documented purpose, or have opened a file with the %@FILEOPEN variable function and the file handle is between 3 and 9. The n>file syntax redirects output from handle n to a file. You can use this form to redirect two handles to different places. For example: [c:\] dir > outfile 2> errfile sends normal output to a file called OUTFILE and any error messages to a file called ERRFILE. The n>&m syntax redirects handle n to the same location as the previously assigned handle m. For example, to send standard error to the same file as standard output, you could use this command: [c:\] dir > outfile 2>&1 Notice that you can perform the same operations by using standard Take Command redirection features. The two examples above could be written as [c:\] dir > outfile >&> errfile and [c:\] dir >&outfile ═══ 2.6.2.2. Piping ═══ You can create a "pipe" to send the standard output of one command to the standard input of another command: command1 | command2 Send the standard output of command1 to the standard input of command2 command1 |& command2 Send the standard output and standard error of command1 to the standard input of command2 For example, to take the output of the SET command (which displays a list of your environment variables and their values) and pipe it to the SORT utility to generate a sorted list, you would use the command: [c:\] set | sort To do the same thing and then pipe the sorted list to the internal LIST command for full-screen viewing: [c:\] set | sort | list /s The TEE and Y commands are "pipe fittings" which add more flexibility to pipes. Like redirection, pipes are fully nestable. For example, you can invoke a batch file and send all of its output to another command with a pipe. A pipe on a command within the batch file will take effect for that command only; when the command is completed, output will revert to the pipe in use for the batch file as a whole. You may also have 2 or more pipes operating simultanesoulsy if, for example, you have the pipes running in different sessions. Take Command implements pipes by starting a new process for the receiving program instead of using temporary files. The sending and receiving programs run simultaneously; the sending program writes to the pipe and the receiving program reads from the pipe. When the receiving program finishes reading and processing the piped data, it ends automatically. When you use pipes with Take Command make sure you think about any possible consequences that can occur from using a separate process to run the receiving program. If you want to pipe information to a command inside an IFF, use command grouping around the IFF command. If you do not, piping will affect on the first command after the IFF. ═══ 2.6.3. Using the Keystack ═══ The Keystack overcomes two weaknesses of input redirection: some programs ignore standard input and read the keyboard through the operating system, and input redirection doesn't end until the program or command terminates. You can't, for example, use redirection to send the opening commands to a program and then type the rest of the commands yourself. But the Keystack lets you do exactly that. The Keystack sends keystrokes to an application program. Once the Keystack is empty, the program will receive the rest of its input from the keyboard. The Keystack is useful when you want a program to take certain actions automatically when it starts. It is most often used in batch files and aliases. The Keystack is invoked with the KEYSTACK command. To place the letters, digits, and punctuation marks you would normally type for your program into the keystack, enclose them in double quotes: [c:\] keystack "myfile" Many other keys can be entered into the Keystack using their names. This example puts the F1 key followed by the Enter key in the keystack: [c:\] keystack F1 Enter See Keys and Keynames for details on how key names are entered. See the KEYSTACK command for information on using numeric key values along with or instead of key names, and other details about using the Keystack. You must start or activate the window for the program that will receive the characters before you place them into the Keystack. See KEYSTACK for additional details; see ACTIVATE for information on activating a specific window. ═══ 2.6.4. ANSI Support ═══ ANSI control sequences are standardized sequences of text characters which allow you to control colors on the screen, manipulate the cursor, and redefine keys. You may have used ANSI sequences to display text or control the color and appearance of your prompt in DOS or OS/2 character mode. Take Command includes built-in support for most standard ANSI color and cursor control sequences (key substitutions are not supported). To use Take Command's ANSI support you must enable it on the Display page of the configuration notebook, with the ANSI directive in the TCMDOS2.INI file, or with the SETDOS /A command. You can determine whether ANSI support is enabled with the _ANSI internal variable. Several Take Command features provide simpler ways to accomplish the tasks usually performed with ANSI control sequences. For example, there are commands to set the screen colors, display text in specific colors, and position the cursor. These commands are generally easier to understand and use than the corresponding ANSI control sequences. However, we have included ANSI support in Take Command for situations where it is useful, such as when using the ECHO command, or in the PROMPT. See the ANSI Reference for more details on ANSI strings, and a reference list of ANSI sequences supported by Take Command for OS/2. ═══ 2.6.5. Critical Errors ═══ OS/2 watches for physical errors during input and output operations. Physical errors are those due to hardware problems, such as trying to read a floppy disk while the drive door is open. These errors are called critical errors because OS/2, Take Command, or your application program may not be able to proceed until the error is resolved. When a critical error occurs, you will see a popup window asking you to choose an error handling option. The message comes from OS/2, and will typically offer you three choices: Return error code to program Tell the program that the operation failed. This option returns an error code to Take Command or to the application program that was running when the error occurred. Take Command generally stops the current command when an operation fails. End program/command/operation Terminate the program which generated the error. Use this option with caution as it is likely to close Take Command or any other program which caused an error. Retry command or operation Choose this option if you have corrected the problem. ═══ 2.6.6. Conditional Commands ═══ When an internal command or external program finishes, it returns a result called the exit code. Conditional commands allow you to perform tasks based upon the previous command's exit code. Many programs return a 0 if they are successful and a non-zero value if they encounter an error. If you separate two commands by && (AND), the second command will be executed only if the first returns an exit code of 0. For example, the following command will only erase files if the BACKUP operation succeeds: [c:\] backup c:\ a: && del c:\*.bak;*.lst If you separate two commands by || (OR), the second command will be executed only if the first returns a non-zero exit code. For example, if the following BACKUP operation fails, then ECHO will display a message: [c:\] backup c:\ a: || echo Error in the backup! All internal commands return an exit code, but not all external programs do. Conditional commands will behave unpredictably if you use them with external programs which do not return an explicit exit code. To determine whether a particular external program returns a meaningful exit code use an ECHO %? command immediately after the program is finished. If the program's documentation does not discuss exit codes you may need to experiment with a variety of conditions to see how the exit code changes. ═══ 2.6.7. Command Grouping ═══ Command grouping allows you to logically group a set of commands together by enclosing them in parentheses. The parentheses are similar in function to the BEGIN and END block statements in some programming languages. There are two primary uses for command grouping. One is to execute multiple commands in a place where normally only a single command is allowed. For example, suppose you wanted to execute two different REN commands in all subdirectories of your hard disk. You could do it like this: [c:\] global ren *.wx1 *.wx0 [c:\] global ren *.tx1 *.tx0 But with command grouping you can do the same thing in one command: [c:\] global (ren *.wx1 *.wx0 & ren *.tx1 *.tx0) The two REN commands enclosed in the parentheses appear to GLOBAL as if they were a single command, so both commands are executed for every directory, but the directories are scanned only once, not twice. This kind of command grouping is most useful with the EXCEPT, FOR, GLOBAL, and IF commands. When you use this approach in a batch file you must either place all of the commands in the group on one line, or place the opening parenthesis at the end of a line and place the commands on subsequent lines. For example, the first two of these sequences will work properly, but the third will not: for %f in (1 2 3) (echo hello %f & echo goodbye %f) for %f in (1 2 3) ( echo hello %f echo goodbye %f ) for %f in (1 2 3) (echo hello %f echo goodbye %f) You can also use command grouping to redirect input or output for several commands without repeatedly using the redirection symbols. For example, consider the following batch file fragment which places some header lines (including today's date) and directory displays in an output file using redirection. The first ECHO command creates the file using >, and the other commands append to the file using >>: echo Data files %_date > filelist dir *.dat >> filelist echo. >> filelist echo Text files %_date >> filelist dir *.txt >> filelist Using command grouping, these commands can be written much more simply: (echo Data files %_date & dir *.dat & echo. & echo Text files %_date & dir *.txt) > filelist The redirection, which appears outside the parentheses, applies to all the commands within the parentheses. Because the redirection is performed only once, the commands will run slightly faster than if each command was entered separately. The same approach can be used for input redirection and for piping. You can also use command grouping in a batch file or at the prompt to split commands over several lines. This last example is like the redirection example above, but is entered at the prompt. Note the "More?" prompt after each incomplete line. None of the commands are executed until the command group is completed with the closing parenthesis. This example does not have to be entered on one line: [c:\] (echo Data files %_date More? dir *.dat More? echo. More? echo Text files %_date More? dir *.txt) > filelist [c:\] A group of commands in parentheses is like a long command line. The total length of the group may not exceed 2,047 characters, whether the commands are entered from the prompt, an alias, or a batch file. The limit includes the space required to expand aliases and environment variables used within the group. In addition, each line you type at the normal prompt or the More? prompt, and each individual command within the line, must meet the usual 1,023-character line length limit. ═══ 2.6.8. Escape Character ═══ Take Command recognizes a user-definable escape character. This character gives the following character a special meaning; it is not the same as the ASCII ESC that is often used in ANSI and printer control sequences. The default escape character is a caret [^]. If you don't like using the default escape character, you can pick another character using the SETDOS /E command, the Options 1 page of the configuration dialogs, or the EscapeChar directive in the TCMDOS2.INI file. If you plan to share aliases or batch files between 4DOS, 4OS2, 4NT and Take Command, see Special Character Compatibility for details about choosing compatible escape characters for two or more products. Ten special characters are recognized when they are preceded by the escape character. The combination of the escape character and one of these characters is translated to a single character, as shown below. These are primarily useful for redirecting codes to the printer. The special characters which can follow the escape character are: b backspace c comma e the ASCII ESC character (ASCII 27) f form feed k back quote n line feed q double quote r carriage return s space t tab character If you follow the escape character with any other character, the escape character is removed and the second character is copied directly to the command line. This allows you to suppress the normal meaning of special characters (such as ? * / \ | " ` > < and &). For example, to display a message containing a > symbol, which normally indicates redirection: [c:\] echo 2 is ^> 4 To send a form feed followed by the sequence ESC Y to the printer, you can use this command: [c:\] echos ^f^eY > prn The escape character has an additional use when it is the last character on any line of a .BAT or .BTM batch file. Take Command recognizes this use of the escape character to signal line continuation: it removes the escape character and appends the next line to the current line before executing it. ═══ 3. Commands ═══ The following topics are a complete guide and reference to the commands that are available from the command line, in aliases, and in batch files. Most of these commands are internal, which means that Take Command performs the activity you have requested without running another program. (See internal and external commands.) Take Command offers over 90 internal commands. These neither replace nor interfere with external commands like BACKUP, DISKCOPY, SCANDISK, or XCOPY. You can continue to use those utilities like you always have. Take Command has been designed to be compatible with virtually all traditional internal commands, and to enhance most of those commands with additional options and capabilities. Once you have installed Take Command, you can continue using the commands that you already know and get the same results. Most of these commands are either enhanced traditional commands or are entirely new (a few are the same as traditional commands). If you are comfortable using traditional commands, you can switch to Take Command without making any changes in your habits. But you will be missing a lot of the power of these enhancements and new commands unless you take a few minutes to see what's available here. Make sure you don't skip a section of this reference just because you already know how to use a traditional command with the same name. If you come across terms or concepts in this section that you are unsure about, please refer to the Reference Information topic and its subtopics. The subtopics included in this topic are: How to Use the Command Descriptions includes an explanation of the command descriptions, the formating conventions we use, and how to use the options available with each command. Command Categories is a list of the available commands, organized so you can find the command you are looking for most easily. Commands by Name is an alphabetic list of the available commands. ═══ 3.1. How to Use the Command Descriptions ═══ Each of the internal commands is described in detail in the following topics. The descriptions are arranged alphabetically, and each includes examples that will help you learn to use the commands. The name of each command is followed by a sentence or two that briefly describes the command's purpose or major function. That sentence should help you determine quickly whether you have found the command you are seeking. The next part of each description shows the command's format or syntax. The format line uses certain conventions to describe how the command should be entered and to create reference points for the text describing the command:  Words in UPPER CASE must be spelled exactly as they are shown (although you can type them in either upper or lower case, or a combination). If a word is shown partly in upper case (for example BRIght), only the upper case portion is required, the rest is optional.  Words shown in italics (for example source or filename) are meant to be replaced by other words or values. Each of these words is explained directly beneath the format line and discussed in more detail in the text description of the command. When the word stands for a file name, you can use a simple name like MYFILE.TXT, or include a drive letter and/or a full path, like C:\MYDIR\MYFILE.TXT.  Items followed by an ellipsis (three periods [...]) may be repeated. For example, filename... means you may enter one or more file names at this point in the command.  Text shown in [square brackets] is optional. Text outside of square brackets must be entered literally (if it is capitalized) or replaced by other words or values (if it is in italics). For example, in this hypothetical command: DOIT [/A /W] filename [NOW] the switches /A and /W and the keyword NOW are optional. The filename should be replaced by the appropriate name for the operation you want to perform. The switches and the keyword NOW at the end must be entered as shown, if they are used. For example, you could use "NOW", "Now", or "now", but you could not abbreviate NOW to NO.  Vertical bars [|] represent a choice; you can pick one option or another but not both. For example, the following format shows that the command may be followed by the word ON or the word OFF, but not both: COMMAND [ ON | OFF ]  A slash followed by a letter, like [/X], is an "option" or "switch" which controls the effect of a command. Many commands have several switches, and you are usually free to use none, one, or several to make a command behave as you wish. If you use a single switch, you must precede it with a slash. If you use several switches, in most cases you can put them together with one slash or use separate slashes. For example, if you wanted to use switches X, Y, and Z for a command, you could type them three different ways: command /x /y /z command /x/y/z command /xyz  A few switches, particularly in the DIR, SELECT, and START commands, use two or more characters. If you need to follow a multi-letter switch with another switch, the second switch must have its own slash to avoid ambiguity. For example, you could use DIR /oa /d to force an alphanumeric sort (/oa) and suppress directory colors (/d). However, if you try to put all the switches together (DIR /oad) Take Command will not do what you want because the "d" will be interpreted as part of the /o switch, where it would mean sort by date and time. The second slash eliminates this ambiguity. Included in the format section is an explanation of each replaceable argument and a one or two word explanation of each switch. Many descriptions also list related commands to help you find the exact command you want. For file handling commands, a section called File Selection appears immediately after the format section. This section lists the file-handling features that the command supports. The list may include mention of extended wildcards; multiple file names; include lists; and date, time, and size ranges and file exclusion ranges. Next, you'll find a description of the command's usage. This description normally starts with the basic functions of a command and gradually adds more details. We've also included many examples to help you see the command in action. The last part of each description is a detailed explanation of the options or switches available for each command, in alphabetical order. Occasionally, we've included more examples in this section to demonstrate how a switch is used or how multiple switches interact. ═══ 3.2. Commands by Category ═══ The best way to learn about commands is to experiment with them. The lists below categorize the available commands by topic and will help you find the ones that you need. System configuration: CHCP CLS COLOR DATE DIRHISTORY FREE HISTORY KEYBD KEYS LOG MEMORY OPTION PROMPT REBOOT SETDOS TIME VER VERIFY VOL File and directory management: ATTRIB COPY DEL DESCRIBE FFIND LIST MOVE REN SELECT TOUCH TREE TYPE Subdirectory management: CD CDD DIR DIRS MD POPD PUSHD RD Input and output: DRAWBOX DRAWHLINE DRAWVLINE ECHO ECHOERR ECHOS ECHOSERR INKEY INPUT KEYSTACK MSGBOX QUERYBOX SCREEN SCRPUT VSCRPUT Commands primarily for use in or with batch files and aliases (some work only in batch files; see the individual commands for details): ALIAS BEEP CALL CANCEL DELAY DO ENDLOCAL FOR GLOBAL GOSUB GOTO IF IFF LOADBTM ON PAUSE QUIT REM RETURN SETLOCAL SHIFT SWITCH TEXT UNALIAS Environment and path commands: DPATH ESET PATH SET UNSET Window Management ACTIVATE TITLE WINDOW Other commands: ? DETACH EXCEPT EXIT HELP SHRALIAS START TEE TIMER Y ═══ 3.3. Commands by Name ═══ The following topics contain an explanation of each of Take Command's internal commands, arranged alphabetically by name. You can browse through the list or jump directly to one of the following commands: ? - List internal commands ACTIVATE - Activate or change window state ALIAS - Create or display aliases ATTRIB - Change file attributes BEEP - Beep the speaker CALL - Execute one batch file from another CANCEL - End all batch files CD - Change directory CDD - Change drive and directory CHCP - Change the current code page CLS - Clear the screen COLOR - Change display colors COPY - Copy files DATE - Set the date DEL - Delete files DELAY - Pause for a specified time DESCRIBE - Create file description DETACH - Start a program in "detached" mode DIR - Display directories DIRHISTORY - Display the directory history DIRS - Display the directory stack DO - Loop in batch files DPATH - Set data search path DRAWBOX - Draw a box DRAWHLINE - Draw horizontal line DRAWVLINE - Draw a vertical line ECHO - Display a message ECHOS - Display a message with no CR/LF ENDLOCAL - Restore saved environment ESET - Edit variable or alias EXCEPT - Exclude files from command EXIT - Exit Take Command FFIND - Search for files or text FOR - Repeat a command FREE - Display total and free disk space GLOBAL - Execute command in all subdirectories GOSUB - Call subroutine GOTO - Branch within batch file HELP - Call online help HISTORY - Manage command history list IF - Test condition IFF - IFF / THEN / ELSE conditional test INKEY - Input a character INPUT - Input a string KEYBD - Set keyboard toggles KEYS - Enable/disable history list KEYSTACK - Feed keystrokes to programs LIST - Display file LOADBTM - Switch batch file mode LOG - Log commands to file MD - Create a subdirectory MEMORY - Display memory status MOVE - Move files to another directory MSGBOX - Display a message box prompt ON - Trap errors in batch files OPTION - Configure Take Command PATH - Set the executable search path PAUSE - Suspend batch file execution POPD - Restore previous directory PROMPT - Change command-line prompt PUSHD - Save current directory QUERYBOX - Popup dialog for input QUIT - Exit batch file RD - Remove subdirectory REBOOT - Reboot or shutdown the computer REM - Add comment to batch file REN - Rename files RETURN - Return from GOSUB SCREEN - Position cursor SCRPUT - Display text in color SELECT - Select files for a command SET - Set environment variables SETDOS - Set the Take Command configuration SETLOCAL - Save the environment SHIFT - Shift batch parameters SHRALIAS - Retain global lists START - Start application in new session SWITCH - Select commands to execute TEE - "Tee" pipe fitting TEXT - Display text in batch file TIME - Set the system time TIMER - Start or stop a stopwatch TITLE - Set window title TOUCH - Change date and time stamps TREE - Display directory tree TYPE - Display a file UNALIAS - Remove aliases UNSET - Remove environment variables VER - Display version levels VERIFY - Disk write verification VOL - Display drive label VSCRPUT - Display text in color vertically WINDOW - Change the window state or title Y - "Y" pipe fitting ═══ 3.3.1. ? - List internal commands ═══ Purpose: Display a list of internal commands or prompt for a command. Format: ? ["prompt" command] prompt : Prompt text about whether to execute the command. command : Command to be executed if the user answers Y. Usage: ? has two functions When you use the ? command by itself, it displays a list of internal commands. For help with any individual command, see the HELP command. If you have disabled a command with SETDOS /I, it will not appear in the list. The second function of ? is to prompt the user before executing a specific line in a batch file. If you add a prompt and a command, ? will display the prompt followed by "(Y/N)?" and wait for the user's response. If the user presses "Y" or "y", the line will be executed. If the user presses "N" or "n", the line will be ignored. For example, the following command might be used in a batch file: ? *Load the network* call netstart.btm When this command is executed, you will see the following prompt; if you answer "Y", the CALL command will be executed: Load the network (Y/N)? ═══ 3.3.2. ACTIVATE - Activate or change window state ═══ Purpose: Activate a window, change its state, or change its title. Format: ACTIVATE "window" [MAX | MIN | RESTORE | CLOSE ] window : Current title of window to work with. See also: START, TITLE, and WINDOW. Usage: Both the current name of the window and the new name, if any, must be enclosed in double quotes. The quotes will not appear as part of the title bar text. If no options are used, the window named in the command will become the active window and be able to receive keystrokes and mouse commands. The MAX option expands the window to its maximum size, the MIN option reduces the window to an icon, and the RESTORE option returns the window to its default size and location on the desktop. The CLOSE option closes the window and ends the session running in the window. This example maximizes and then renames the window called "Take Command": [c:\] activate "Take Command" max [c:\] activate "Take Command" "TCMD" You can use wildcards, in the window parameter. This is useful with applications that change their window title to reflect the file currently in use. ACTIVATE is often used before KEYSTACK to make sure the proper window receives the keystrokes. ACTIVATE works by sending the appropriate messages to the named window. If the window ignores or misinterprets the messages, ACTIVATE may not have the effect you want. - ═══ 3.3.3. ALIAS - Create or display aliases ═══ Purpose: Create new command names that execute one or more commands or redefine default options for existing commands; assign commands to keystrokes; load or display the list of defined alias names. Format: ALIAS [/P /R file...] [name [=][value ]] file : One or more files to read for alias definitions. name : Name for an alias, or for the key to execute the alias. value : Text to be substituted for the alias name. /P(ause) /R(ead alias file) See also: UNALIAS and Aliases. Usage: The ALIAS command lets you create new command names or redefine internal commands. It also lets you assign one or more commands to a single keystroke. An alias is often used to execute a complex series of commands with a few keystrokes or to create "in memory batch files" that run much faster than disk-based batch files. For example, to create a single-letter command D to display a wide directory, instead of using the longer DIR /W, you could use the command: [c:\] alias d = dir /w Now when you type a single d as a command, it will be translated into a DIR /W command. You can also define or modify aliases with the Alias dialog. The dialog allows you to enter the alias name and value into separate fields in a dialog box, rather than using the ALIAS command. All of the information in this section also applies to aliases defined via the dialog, unless otherwise noted. If you define aliases for commonly used application programs, you can often remove the directories they're stored in from the PATH. For example, if you use Microsoft Word for Windows and had the C:\WINWORD directory in your path, you could define the following alias: [c:\] alias ww = c:\winword\winword.exe With this alias defined, you can probably remove C:\WINWORD from your path. Word for Windows will now load much faster than it would if Take Command had to search the PATH for it. In addition, the PATH can be shorter, which will speed up searches for other programs. If you apply this technique for each application program, you can often reduce your PATH to just two or three directories containing utility programs, and significantly reduce the time it takes to load most software on your system. Before removing a directory from the PATH, you will need to define aliases for all the executable programs you commonly use which are stored in that directory. Aliases are stored in memory, and are not saved automatically when you turn off your computer or end your current session. See below for information on saving and reloading your aliases. Multiple Commands and Special Characters in Aliases An alias can represent more than one command. For example: [c:\] alias letters = `cd \letters & tedit` creates a new command called LETTERS. The command first uses CD to change to a subdirectory called \LETTERS and then runs a program called TEDIT. The ampersand [&] is the command separator and indicates that the two commands are distinct and should be executed sequentially. Aliases make extensive use of the command separator, and the parameter character, and may also use the escape character. These characters differ between 4OS2, 4DOS, and Take Command. In the text and examples below, we use the Take Command characters. If you want to use the same aliases under different command processors, see Special Character Compatibility. When an alias contains multiple commands, the commands are executed one after the other. However, if any of the commands run an external Windows or OS/2 application, you must be sure the alias will wait for the application to finish before continuing with the other commands. This behavior is controlled by the Wait for completion setting on the Options 2 page of the configuration notebook or the ExecWait directive in the TCMDOS2.INI file. When you type alias commands at the command line or in a batch file, you must use back quotes [`] around the definition if it contains multiple commands, parameters (discussed below), environment variables, redirection, or piping. The back quotes prevent premature expansion of these arguments. You may use back quotes around other definitions, but they are not required. (You do not need back quotes when your aliases are loaded from an ALIAS /R file; see below for details.) You also do not need back-quotes when entering an alias in the Aliases dialog box.) The examples in this section include back-quotes only when they are required. Nested Aliases Aliases may invoke internal commands, external commands, or other aliases. (However, an alias may not invoke itself, except in special cases where an IF or IFF command is used to prevent an infinite loop.) The two aliases below demonstrate alias nesting (one alias invoking another). The first line defines an alias which runs Word for Windows in the E:\WINWORD subdirectory. The second alias changes directories with the PUSHD command, runs the WP alias, and then returns to the original directory with the POPD command: [c:\] alias wp = e:\wp60\wpinword\winword.exe [c:\] alias w = `pushd c:\wp & wp & popd` The second alias above could have included the full path and name of the WINWORD.EXE program instead of calling the WP alias. However, writing two aliases makes the second one easier to read and understand, and makes the first alias available for independent use. If you rename the WINWORD.EXE program or move it to a new directory, only the first alias needs to be changed. Temporarily Disabling Aliases If you put an asterisk [*] immediately before a command in the value of an alias definition (the part after the equal sign), it tells Take Command not to attempt to interpret that command as another (nested) alias. An asterisk used this way must be preceded by a space or the command separator and followed immediately by an internal or external command name. By using an asterisk, you can redefine the default options for any internal or external command. For example, suppose that you always want to use the DIR command with the /2 (two column) and /P (pause at the end of each page) options. The following line will do just that: [c:\] alias dir = *dir /2/p If you didn't include the asterisk, the second DIR on the line would be the name of the alias itself, and Take Command would repeatedly re- invoke the DIR alias, rather than running the DIR command. This would cause an "Alias loop" or "Command line too long" error. An asterisk also helps you keep the names of internal commands from conflicting with the names of external programs. For example, suppose you have a program called DESCRIBE.EXE. Normally, the internal DESCRIBE command will run anytime you type DESCRIBE. But two simple aliases will give you access to both the DESCRIBE.EXE program and the DESCRIBE command: [c:\] alias describe = c:\winutil\describe.exe [c:\] alias filedesc = *describe The first line above defines DESCRIBE as an alias for the DESCRIBE.EXEprogram. If you stopped there, the external program would run every time you typed DESCRIBE and you would not have easy access to the internal DESCRIBE command. The second line renames the internal DESCRIBE command as FILEDESC. The asterisk is needed in the second command to indicate that the following word means the internal command DESCRIBE, not the DESCRIBE alias which runs your external program. Another way to understand the asterisk is to remember that a command is always checked for an alias first, then for an internal or external command, or a batch file (see Internal and External Commands). The asterisk at the beginning of a command name simply skips over the usual check for aliases when processing that command, and allows Take Command to go straight to checking for an internal command, external command, or batch file. You can also use an asterisk before a command that you enter at the command line or in a batch file. If you do, that command won't be interpreted as an alias. This can be useful when you want to be sure you are running the true, original command and not an alias with the same name, or temporarily defeat the purpose of an alias which changes the meaning or behavior of a command. For example, above we defined an alias for DIR which made directories display in 2-column paged mode by default. If you wanted to see a directory display in the normal single-column, non-paged mode, you could enter the command *DIR and the alias would be ignored during that one command. You can also disable aliases temporarily with the SETDOS /X command. Partial Alias Names You can also use an asterisk in the name of an alias. When you do, the characters following the asterisk are optional when you invoke the alias command. (Use of an asterisk in the alias name is unrelated to the use of an asterisk in the alias value discussed above.) For example, with this alias: [c:\] alias wher*eis = dir /sp the new command, WHEREIS, can be invoked as WHER, WHERE, WHEREI, or WHEREIS. Now if you type: [c:\] where myfile.txt The WHEREIS alias will be expanded to the command: dir /sp myfile.txt Keystroke Aliases If you want to assign an alias to a keystroke, use the key name on the left side of the equal sign, preceded by an at sign [@]. For example, to assign the command DIR /W to the F4 key, type [c:\] alias @F4 = dir /w See Keys and Key Names for a complete listing of key names and a description of the key name format. You can not use Alt key names (e.g., Alt-D) for keystroke aliases because these names are used by OS/2 for "accelerator" (shortcut) keys for menu items. If you define a keystroke alias with a single at sign as shown above, then, when you press the F4 key, the value of the alias (DIR /W above) will be placed on the command line for you. You can type additional parameters if you wish and then press Enter to execute the command. With this particular alias, you can define the files that you want to display after pressing F4 and before pressing Enter to execute the command. If you want the keystroke alias to take action automatically without waiting for you to edit the command line or press Enter, you can begin the definition with two at signs [@@]. Take Command will execute the alias "silently," without displaying its text on the command line. For example, this command will assign an alias to the F11 key that uses the CDD command to take you back to the previous default directory: [c:\] alias @@f11 = cdd - When you define keystroke aliases, the assignments will only be in effect at the command line, not inside application programs. Be careful not to assign aliases to keys that are already used at the command line (like F1for Help). The command-line meanings take precedence and the keystroke alias will never be invoked. If you want to use one of the command- line keys for an alias instead of its normal meaning, you must first disable its regular use with the NormalKey or NormalEditKey directives in your .INI file. You can also define a keystroke alias by using "@" or "@@" plus a scan code for one of the permissible keys (see the Key Code Tables for a list of scan codes). In most cases it will be easier to use key names. Scan codes should only be used with unusual keyboards where a key name is not available for the key you are using. Displaying Aliases If you want to see a list of all current ALIAS commands, type: [c:\] alias You can also view the definition of a single alias. For example, if you want to see the definition of the alias LIST, you can type: [c:\] alias list Saving and Reloading Your Aliases You can save your aliases to a file called ALIAS.LST this way: [c:\] alias > alias.lst You can then reload all the alias definitions in the file the next time you boot up with the command: [c:\] alias /r alias.lst This is much faster than defining each alias individually in a batch file. If you keep your alias definitions in a separate file which you load when your system starts, you can edit them with a text editor, reload the edited file with ALIAS /R, and know that the same alias list will be loaded the next time you boot your computer. When you define aliases in a file that will be read with the ALIAS /R command, you do not need back quotes around the value, even if back quotes would normally be required when defining the same alias at the command line or in a batch file. You can also save and reload your aliases using the Aliases dialog. The Export button in the dialog box is equivalent to the ALIAS > filename command shown above, and the Import button is equivalent to the ALIAS /R command. To remove an alias, use the UNALIAScommand. Alias Parameters Aliases can use command-line arguments or parameters like those in batch files. The command-line arguments are numbered from %0 to % 127. %0 contains the alias name. It is up to the alias to determine the meaning of the other parameters. You can use quotation marks to pass spaces, tabs, commas, and other special characters in an alias parameter; see Argument Quotingfor details. Parameters that are referred to in an alias, but which are missing on the command line, appear as empty strings inside the alias. For example, if you put two parameters on the command line, any reference in the alias to %3 or any higher-numbered parameter will be interpreted as an empty string. The parameter %n$ has a special meaning. Take Command interprets it to mean "the entire command line, from argument n to the end." If n is not specified, it has a default value of 1, so %$means "the entire command line after the alias name." The special parameter %# contains the number of command-line arguments. For example, the following alias will change directories, perform a command, and return to the original directory: [c:\] alias in = `pushd %1 & %2$ & popd` When this alias is invoked as: [c:\] in c:\comm mycomm zmodem /56K the first parameter, %1, has the value c:\comm. %2 is mycomm, %3is zmodem, and %4 is /56K. The command line expands into these three separate commands: pushd c:\comm mycomm zmodem /56K popd This next example uses the IFF command to redefine the defaults for SET. It should be entered on one line: [c:\] alias set = `iff %# == 0 then & *set /p & else & *set %$ & endiff` This modifies the SET command so that if SET is entered with no arguments, it is replaced by SET /P (pause after displaying each page), but if SET is followed by an argument, it behaves normally. Note the use of asterisks (*set) to prevent alias loops. If an alias uses parameters, command-line arguments will be deleted up to and including the highest referenced argument. For example, if an alias refers only to %1 and %4, then the first and fourth arguments will be used, the second and third arguments will be discarded, and any additional arguments beyond the fourth will be appended to the expanded command (after the value portion of the alias). If an alias uses no parameters, all of the command- line arguments will be appended to the expanded command. Aliases also have full access to all variables in the environment, internal variables, and variable functions. For example, you can create a simple command-line calculator this way: [c:\] alias calc = `echo The answer is: %@eval[%$]` Now, if you enter: [c:\] calc 5 * 6 the alias will display: The answer is: 30 Expanding Aliases at the Prompt You can expand an alias on the command line and view or edit the results by pressing Ctrl-F after typing the alias name, but before the command is executed. This replaces the alias with its contents, and substitutes values for each alias paramter, just as if you had pressed the Enter key. However, the command is not executed; it is simply redisplayed on the command line for additional editing. Ctrl-F is especially useful when you are developing and debugging a complex alias, or if you want to make sure that an alias that you may have forgotten won't change the effect of your command. Local and Global Aliases The aliases can be stored in either a "local" or "global" list. With a local alias list, any changes made to the aliases will only affect the current copy of Take Command. They will not be visible in other sessions. With a global alias list, all copies of Take Command will share the same alias list, and any changes made to the aliases in one copy will affect all other copies. This is the default. You can control the type of alias list from the Startup page of the configuration dialogs, with the LocalAliases directive in the TCMDOS2.INI file, with the /L and /LA options of the START commandand with the /L and /LA startup options. There is no fixed rule for determining whether to use a local or global alias list. Depending on your work style, you may find it most convenient to use one type, or a mixture of types in different sessions or shells. We recommend that you start with the default approach, then modify it if you find a situation where the default is not convenient. Whenever you start a second copy of Take Command which uses a local alias list, it inherits a copy of the aliases from the previous copy.. However, any changes to the alias made in the second copy will affect only that copy. If you want changes made in a second copy of Take Command to affect the previous copy, use a global alias list in both. Retaining Global Aliases with SHRALIAS If you select a global alias list you can share the aliases among all copies of Take Command running in any session. When you close all Take Command sessions, the memory for the global alias list is released, and a new, empty alias list is created the next time you start Take Command. If you want the aliases to be retained in memory even when no Take Command session is running, you need to execute the SHRALIAS command, which loads a program to perform this service for the global alias list, the global command history list, and the global directory history list. You may find it convenient to execute SHRALIAS from your TCSTART file SHRALIAS retains the alias list in memory, but cannot preserve it when OS/2 itself is shut down. To save your aliases when restarting OS/2, you must store them in a file and reload them after the system restarts. For details on how to do so, see Saving and Reloading Your Aliases (above). The UNKNOWN_CMD Alias If you create an alias with the name UNKNOWN_CMD, it will be executed any time Take Command would normally issue an "Unknown command" error message. This allows you to define your own "handler" for unknown commands. When the UNKNOWN_CMD alias is executed, the command line which generated the error is passed to the alias for possible processing. For example, to display the command that caused the error: alias unknown_cmd `echo Error in command "%&"` Use caution when you create the UNKNOWN_CMD alias. If the alias contains an unknown command, it will be called repeatedly and Take Command will loop up to 10 times, then display an "UNKNOWN_CMD loop" error. Options: /P (Pause) This option is only effective when ALIAS is used to display existing definitions. It pauses the display after each page and waits for a keystroke before continuing (see Page and File Prompts). /R (Read file) This option loads an alias list from a file. The format of the file is the same as that of the ALIAS display: name=value where name is the name of the alias and value is its value. You can use an equal sign [=] or space to separate the name and value. Back quotes are not required around the value. You can add comments to the file by starting each comment line with a colon [:]. You can load multiple files with one ALIAS /R command by placing the names on the command line, separated by spaces: [c:\] alias /r alias1.lst alias2.lst Each definition in an ALIAS /R file can be up to 2,047 characters long. The definitions can span multiple lines in the file if each line, except the last, is terminated with an escape character. ═══ 3.3.4. ATTRIB - Change file attributes ═══ Purpose: Change or view file and subdirectory attributes. Format: ATTRIB [/A:[[-]rhsda] /D /E /P /Q /S] [+|-[AHRS]] files ... files : A file, directory, or list of files or directories on which to operate. /A: (Attribute select) /P(ause) /D(irectories) /Q(uiet) /E (No error messages) /S(ubdirectories) Attribute flags: +A Set the archive attribute -A Clear the archive attribute +H Set the hidden attribute -H Clear the hidden attribute +R Set the read-only attribute -R Clear the read-only attribute +S Set the system attribute -S Clear the system attribute File Selection: Supports extended wildcards, ranges, multiple file names, and include lists. Usage: Every file and subdirectory has 4 attributes that can be turned on (set) or turned off (cleared): Archive, Hidden, Read- only, and System. The ATTRIB command lets you view, set, or clear attributes for any file, group of files, or subdirectory. You can view file attributes by entering ATTRIB without specifying new attributes (i.e., without the [+|-[AHRS]] part of the format). (You can also view file attributes with the DIR /T command. The primary use of ATTRIB is to set attributes. For example, you can set the read-only and hidden attributes for the file MEMO: [c:\] attrib +rh memo Attribute options apply to the file(s) that follow the options on the ATTRIB command line. The example below shows how to set different attributes on different files with a single command. It sets the archive attribute for all .TXT files, then sets the system attribute and clears the archive attribute for TEST.COM: [c:\] attrib +a *.txt +s -a test.com When you use ATTRIB on an HPFS drive, you must quote any file names which contain whitespace or special characters. To change directory attributes, use the /D switch. If you give ATTRIB a directory name instead of a file name, and omit /D, it will append "\*.*" to the end of the name and act on all files in that directory, rather than acting on the directory itself. OS/2 also supports "D" (subdirectory) and "V" (volume label) attributes. These attributes cannot be altered with ATTRIB; they are designed to be controlled only by the operating system itself. ATTRIB will ignore underlines in the new attribute (the [+|- [AHRS]] part of the command). For example, ATTRIB sees these 2 commands as identical: [c:\] attrib +a filename [c:\] attrib +__A_ filename This allows you to use a string of attributes from either the @ATTRIB variable function or from ATTRIB itself (both of which use underscores to represent attributes that are not set) and send that string back to ATTRIB to set attributes for other files. For example, to clear the attributes of FILE2 and then set its attributes to match those of FILE1 (enter this on one line): [c:\] attrib -arhs file2 & attrib +%@attrib[file1] file2 Options: /A: (Attribute select): Select only those files that have the specified attribute(s) set. Preceding the attribute character with a hyphen [-] will select files that do not have that attribute set. The colon [:] after /A is required. The attributes are: R Read-only H Hidden S System D Subdirectory A Archive If no attributes are listed at all (e.g., /A:), ATTRIB will select all files and subdirectories including hidden and system files. If attributes are combined, all the specified attributes must match for a file to be selected. For example, /A:RHS will select only those files with all three attributes set. This switch specifies which files to select, not which attributes to set. For example, to remove the archive attribute from all hidden files, you could use this command: [c:\] attrib /a:h -a *.* /D (Directories) If you use the /D option, ATTRIB will modify the attributes of subdirectories in addition to files (yes, you can have a hidden subdirectory): [c:\] attrib /d +h c:\mydir /E (No error messages) Suppress all non-fatal error messages, such as "File Not Found." Fatal error messages, such as "Drive not ready," will still be displayed. This option is most useful in batch files and aliases. /P (Pause) Wait for a key to be pressed after each screen page before continuing the display. Your options at the prompt are explained in detail under Page and File Prompts. /Q (Quiet) This option turns off ATTRIB's normal screen output. It is most useful in batch files. /S (Subdirectories) If you use the /S option, the ATTRIB command will be applied to all matching files in the current or named directory and all of its subdirectories. ═══ 3.3.5. BEEP - Beep the speaker ═══ Purpose: Beep the speaker or play simple music. Format: BEEP [frequency duration ...] frequency : The beep frequency in Hertz (cycles per second). duration : The beep length in 1/18th second intervals. Usage: BEEP generates a sound through your computer's speaker. It is normally used in batch files to signal that an operation has been completed, or that the computer needs attention. Because BEEP allows you to specify the frequency and duration of the sound, you can also use it to play simple music or to create different kinds of signals for the user. You can include as many frequency and duration pairs as you wish. No sound will be generated for frequencies less than 20 Hz, allowing you to insert short delays. The default value for frequency is 440 Hz; the default value for duration is 2. This batch file fragment runs a program called DEMO, then plays a few notes and waits for you to press a key: demo beep 440 4 600 2 1040 6 pause Finished with the demo - hit a key The following table gives the frequency values for a five octave range (middle C is 262 Hz): ╔════════╤═══════╤═══════╤═══════╤════════╤═══════╗ ║ C │ 131 │ 262 │ 523 │ 1046 │ 2093 ║ ║ C#/Db │ 139 │ 277 │ 554 │ 1108 │ 2217 ║ ║ D │ 147 │ 294 │ 587 │ 1175 │ 2349 ║ ║ D#/Eb │ 156 │ 311 │ 622 │ 1244 │ 2489 ║ ║ E │ 165 │ 330 │ 659 │ 1318 │ 2637 ║ ║ F │ 175 │ 349 │ 698 │ 1397 │ 2794 ║ ║ F#/Gb │ 185 │ 370 │ 740 │ 1480 │ 2960 ║ ║ G │ 196 │ 392 │ 784 │ 1568 │ 3136 ║ ║ G#/Ab │ 208 │ 415 │ 831 │ 1662 │ 3322 ║ ║ A │ 220 │ 440 │ 880 │ 1760 │ 3520 ║ ║ A#/Bb │ 233 │ 466 │ 932 │ 1866 │ 3729 ║ ║ B │ 248 │ 494 │ 988 │ 1973 │ 3951 ║ ╚════════╧═══════╧═══════╧═══════╧════════╧═══════╝ ═══ 3.3.6. CALL - Execute one batch file from another ═══ Purpose: Execute one batch file from within another. Format: CALL [/Q] file file : The batch file to execute. /Q(uiet) See also: CANCEL and QUIT. Usage: CALL allows batch files to call other batch files (batch file nesting). The calling batch file is suspended while the called (second) batch file runs. When the second batch file finishes, the original batch file resumes execution at the next command. If you execute a batch file from inside another batch file without using CALL, the first batch file is terminated before the second one starts. The following batch file fragment compares an input line to "wp" and calls another batch file if it matches: input Enter your choice: %%option if "%option" == "wp" call wp.bat Take Command supports batch file nesting up to ten levels deep. The current ECHO state is inherited by a called batch file, except when the /Q switch is used. The called batch file should always either return (by executing its last line, or using the QUIT command), or terminate batch file processing with CANCEL. Do not restart or CALL the original batch file from within the called file as this may cause an infinite loop or a stack overflow. CALL returns an exit code which matches the batch file return code. You can test this exit code with the %_? or %? environment variable, and use it with conditional commands (&& and ||). Option: /Q (Quite): Starts the new batch file with echo off, regardless of the current batch file's echo state. This switch is provided for compatibility with CMD.EXE. ═══ 3.3.7. CANCEL - End all batch files ═══ Purpose: Terminate batch file processing. Format: CANCEL [value] value : The numeric exit code to return to Take Command. See also: CALL and QUIT. Usage: The CANCEL command ends all batch file processing, regardless of the batch file nesting level. Use QUIT to end a nested batch file and return to the previous batch file. You can CANCEL at any point in a batch file. If CANCEL is used from within an alias it will end execution of both the alias and any batch files which are running at the time. The following batch file fragment compares an input line to "end" and terminates all batch file processing if it matches: input Enter your choice: %%option if "%option" == "end" cancel If you specify a value, CANCEL will set the ERRORLEVEL or exit code to that value (see the IF command, and the %? variable). ═══ 3.3.8. CD - Change directory ═══ Purpose: Display or change the current directory. Format: CD [/N] [ path | - ] or CHDIR [/N] [ path | - ] path : The directory to change to, including an optional drive name. /N(o extended search) See also: CDD, MD, PUSHD, RD, and Directory Navigation. Usage: CD and CHDIR are synonyms. You can use either one. CD lets you navigate through a drive's subdirectory structure by changing the current working directory. If you enter CD and a directory name, the named directory becomes the new current directory. For example, to change to the subdirectory C:\FINANCE\MYFILES: [c:\] cd \finance\myfiles [c:\finance\myfiles] Every disk drive on the system has its own current directory. Specifying both a drive and a directory in the CD command will change the current directory on the specified drive, but will not change the default drive. For example, to change the default directory on drive A: [c:\] cd a:\utility [c:\] Notice that this command does not change to drive A:. Use the CDD command to change the current drive and directory at the same time. When you use CD to change to a directory on an HPFS drive, you must quote the path name if it contains whitespace or special characters. You can change to the parent directory with CD ..; you can also go up one additional directory level with each additional [.]. For example, CD .... will go up three levels in the directory tree (see Extended Parent Directory Names). You can move to a sibling directory -- one that branches from the same parent directory as the current subdirectory -- with a command like CD ..\newdir. If you enter CD with no argument or with only a disk drive name, it will display the current directory on the default or named drive. If CD cannot change to the directory you have specified it will attempt to search the CDPATH and the extended directory search database in order to find a matching directory and switch to it. You can use wildcards in the path to force an extended directory search. Read the section on Directory Navigation for complete details on these and other directory navigation features. To disable extended directory searches for the current command (e.g. in a batch file) see the /N option below. CD saves the current directory before changing to a new directory. You can switch back to the previous directory by entering CD -. (There must be a space between the CD command and the hyphen.) You can switch back and forth between two directories by repeatedly entering CD -. The saved directory is the same for both the CD and CDD commands. Drive changes and automatic directory changes also modify the saved directory, so you can use CD - to return to a directory that you exited with an automatic directory change. Directory changes made with CD are also recorded in the directory history list and can be displayed in the directory history window, which allows you to return quickly to a recently-used directory. CD never changes the default drive. If you change directories on one drive, switch to another drive, and then enter CD -, the directory will be restored on the first drive but the current drive will not be changed. Option /N: (No extended search) This option prevents CD from searching the extended directory search database or displaying the related popup window. If /N is used and the specified directory is not found via other methods (i.e. without an extended search), CD will display an error. This option is primarily intended for use in batch files where you do not want CD to use "fuzzy" directory searching or display an extended search popup window. ═══ 3.3.9. CDD - Change drive and directory ═══ Purpose: Change the current disk drive and directory. Format: CDD [/A /N /S[drive ...]] [path | - ] path : The name of the directory (or drive and directory) to change to. drive : A drive or list of drives to include in the extended directory search database. /A(ll drives) /N(o extended search) /S(earch tree) See also: CD, MD, PUSHD, RD, and Directory Navigation. Usage: CDD is similar to the CD command, except that it also changes the default disk drive if one is specified. CDD will change to the directory and drive you name. To change from the root directory on drive A to the subdirectory C:\WP: [a:\] cdd c:\wp [c:\wp] You can change to the parent directory with CDD ..; you can also go up one additional directory level with each additional [.]. For example, CDD .... will go up three levels in the directory tree (see Extended Parent Directory Names for details). CDD can also change to a network drive and directory specified with a UNC name. When you use CDD to change to a directory on an NTFS drive, you must quote the path name if it contains whitespace or special characters. If CDD cannot change to the directory you have specified it will attempt to search the CDPATH and the extended directory search database in order to find a matching directory and switch to it. You can also use wildcards in the path to force an extended directory search. Read the section on Directory Navigation for complete details on these and other directory navigation features. To disable extended directory searches for the current command (e.g. in a batch file) see the /N option below. CDD saves the current drive and directory before changing to a new directory. You can switch back to the previous drive and directory by entering CDD - (there must be a space between the CDD command and the hyphen). You can switch back and forth between two drives and directories by repeatedly entering CDD -. The saved directory is the same for both the CD and CDD commands. Drive changes and automatic directory changes also modify the saved directory, so you can use CDD - to return to a directory that you exited with a drive change or an automatic directory change. Directory changes made with CDD are also recorded in the directory history list and can be displayed in the directory history window, which allows you to return quickly to a recently-used directory. Options: /A (All drives) When CDD is used with this option, it displays the current directory on all drives from C: to the last drive in the system. You cannot move to a new drive and directory and use /A in the same command. /N: (No extended search) This option prevents CD from searching the extended directory search database or displaying the related popup window. If /N is used and the specified directory is not found via other methods (i.e. without an extended search), CD will display an error. This option is primarily intended for use in batch files where you do not want CD to use "fuzzy" directory searching or display an extended search popup window. /S (Search tree) Builds or rebuilds the Extended Directory Search database, JPSTREE.IDX. You cannot move to a new drive and directory and use /S in the same command. To include all local hard drives in the database, use the command: cdd /s To limit or add to the list of drives included in the database, list the drives and network volume names after the /S switch. For example, to include drives C, D, E, and the network volume \\server\dir1 in the database, use this command: cdd /s cde \\server\dir1 All non-hidden directories on the listed drives will be indexed; you cannot restrict the database to certain directories within a drive. Each time you use /S, everything in the previous directory database is replaced by the new database that is created. ═══ 3.3.10. CHCP - Change the current code page ═══ Purpose: Display or change the current system code page. Format: CHCP [n ] n : A system code page number. Usage: Code page switching allows you to select different character sets for language support. If you enter CHCP without a number, the current active code page is displayed, along with a list of all active code pages : [c:\] chcp Active code page: 437 Prepared code pages: 273 274 277 278 280 282 284 285 297 437 500 850 860 863 865 932 942 852 857 861 870 871 1026 1004 If you enter CHCP plus a code page number, the system code page is changed. For example, to set the code page to multilingual: [c:\] chcp 850 CHCP only affects the current Take Command for OS/2 session, and any new programs started from within that session; the active code page in other sessions remains unchanged. CHCP accepts one of the prepared system code pages. An error message is displayed if a code page is selected that has not been prepared for the system. See your OS/2 documentation for more information on CHCP. ═══ 3.3.11. CLS - Clear the screen ═══ Purpose: Clear the window and move the cursor to the upper left corner; optionally change the default display colors. Format: CLS [/C] [[BRIght] fg ON [BRIght] bg] fg : The new foreground color bg : The new background color /C Clear scrollback buffer Usage: CLS can be used to clear the screen without changing colors, or to clear the screen and change the screen colors simultaneously. These two examples show how to clear the screen to the default colors, and to bright white letters on a blue background: [c:\] cls [c:\] cls bright white on blue CLS is often used in batch files to clear the screen before displaying text. See Colors and Color Names for details about colors. Option: /C (Clear buffer) Clears the entire scrollback buffer. If /C is not used, only the visible portion of the Take Command screen is cleared. ═══ 3.3.12. COLOR - Change display colors ═══ Purpose: Change the default display colors. Format: COLOR [BRIght] fg ON [ BRIght] bg fg : The new foreground color bg : The new background color See also: CLS, and Colors and Color Names for details about using colors. Usage: COLOR is normally used in batch files before displaying text. For example, to set screen colors to bright white on blue, you can use this command: [c:\] color bright white on blue ═══ 3.3.13. COPY - Copy files ═══ Purpose: Copy data between disks, directories, files, or physical hardware devices (such as your printer or serial port). Format: COPY [/A:[[-]rhsda] /C /E /F /H /K /M /N /P /Q /R /S /T /U /V /X /Z] source [+] ... [/A /B] destination [/A /B] source : A file or list of files or a device to copy from. destination : A file, directory, or device to copy to. /A(SCII) /P(rompt) /A:(ttribute select) /Q(uiet) /B(inary) /R(eplace) /C(hanged) /S(ubdirectories) /E (No error messages) /T(otals) /F(ail on EA error) /U(update) /H(idden) /V(erify) /K(eep attributes) /X (clear archive) /M(odified) /Z (overwrite) /N(othing) See also: ATTRIB, MOVE, and REN. File Selection: Supports extended wildcards, ranges, multiple file names, and include lists, and the clipboard device (CLIP:). Date, time, size, or exclude ranges anywhere on the line apply to all source files. Usage: The COPY command accepts all traditional syntax and options and adds several new features. The simplest use of COPY is to make a copy of a file, like this example which makes a copy of a file called FILE1.ABC: [c:\] copy file1.abc file2.def You can also copy a file to another drive and/or directory. The following command copies FILE1 to the \MYDIR directory on drive E: [c:\] copy file1 e:\mydir When you COPY files to or from an HPFS drive, you must quote any file names which contain whitespace or special characters. Copying Files You can copy several files at once by using wildcards: [c:\] copy *.txt e:\mydir You can also list several source files in one command. The following command copies 3 files from the current directory to the \MYDIR directory on drive E: [c:\] copy file1 file2 file3 e:\mydir COPY also understands include lists, so you can specify several different kinds of files in the same command. This command copies the .TXT, .DOC, and .BAT files from the E:\MYDIR directory to the root directory of drive A: [c:\] copy e:\mydir\*.txt;*.doc;*.bat a:\ If there is only one argument on the line, COPY assumes it is the source, and uses the current drive and directory as the destination. For example, the following command copies all the .DAT files on drive A to the current directory on drive C: [c:\data] copy a:*.dat If there are two or more arguments on the line, separated by spaces, then COPY assumes that the last argument is the destination and copies all source files to this new location. If the destination is a drive, directory, or device name then the source files are copied individually to the new location. If the destination is a file name, the first source file is copied to the destination, and any additional source files are then appended to the new destination file. For example, the first of these commands copies the .DAT files from the current directory on drive A individually to C:\MYDIR (which must already exist as a directory); the second appends all the .DAT files together into one large file called C:\DATA (assuming C:\DATA is not a directory): [c:\] copy a:*.dat c:\mydir\ [c:\] copy a:*.dat c:\data When you copy to a directory, if you add a backslash [\] to the end of the name as shown in the first example above, COPY will display an error message if the name does not refer to an existing directory. You can use this feature to keep COPY from treating a mistyped destination directory name as a file name and attempting to append all your source files to a destination file, when you really meant to copy them individually to a destination directory. To copy a file to a device such as the printer, use the device name as the destination, for example: [c:\] copy schedule.txt prn To copy to or from the clipboard use CLIP: as the device name. Using CLIP: with non-text data will produce unpredictable results. Appending Files A plus [+] tells COPY to append two or more files to a single destination file. If you list several source files separated with [+] and don't specify a destination, COPY will use the name of the first source file as the destination, and append each subsequent file to the first file. For example, the following command will append the contents of C:\MEMO2 and C:\MEMO3 to C:\MEMO1 and leave the combined contents in the file named C:\MEMO1: [c:\] copy memo1+memo2+memo3 To append the same three files but store the result in BIGMEMO: [c:\] copy memo1+memo2+memo3 bigmemo If no destination is specified, the destination file will always be created in the current directory even if the first source file is in another directory or on another drive. For example, this command will append C:\MEM\MEMO2 and C:\MEM\MEMO3 to D:\DATA\MEMO1, and leave the result in C:\MEM\MEMO1: [c:\mem] copy d:\data\memo1+memo2+memo3 You cannot append files to a device (such as a printer); if you try to do so, COPY will ignore the [+] signs and copy the files individually. If you attempt to append several source files to a destination directory or disk, COPY will append the files and place the copy in the new location with the same name as the first source file. Advanced Features If your destination has wildcards in it, COPY will attempt to match them with the source names. For example, this command copies the .DAT files from drive A to C:\MYDIR and gives the new copies the extension .DX: [c:\] copy a:*.dat c:\mydir\*.dx This feature can give you unexpected results if you use it with multiple source file names. For example, suppose that drive A contains XYZ.DAT and XYZ.TXT. The command: [c:\] copy a:\*.dat a:\*.txt c:\mydir\*.dx will copy A:XYZ.DAT to C:\MYDIR\XYZ.DX. Then it will copy A:XYZ.TXT to C:\MYDIR\XYZ.DX, overwriting the first file it copied. You can use date, time, and size ranges to further define the files that you want to copy. This example copies every file in the E:\MYDIR directory, which was created or modified yesterday, and which is also 10,000 bytes or smaller in size, to the root directory of drive A: [c:\] copy /[d-1] /[s0,10000] e:\mydir\*.* a:\ You can also use file exclusion ranges to restrict the list of files that would normally be selected with wildcards. This example copies every file in the E:\MYDIR directory except backup (.BAK or .BK!) files: [c:\] copy /[!*.bak;*.bk!] e:\mydir\*.* a:\ COPY will normally process source files which do not have the hidden or system attribute, and will ignore the read-only and archive attributes. It will always set the archive attribute and clear the read-only attribute of destination files. In addition, if the destination is an existing file with the read-only attribute, COPY will generate an "Access Denied" error and refuse to overwrite the file. You can alter some of these behaviors with switches (see the individual switch descriptions below for complete details): /A: Forces COPY to process source files with the attributes you specify. /H Forces COPY to process hidden and system source files, and preserves the hidden and system attributes when creating destination files. /K Retains the read-only attribute from each source file when creating the destination file. /Z Forces COPY to overwrite an existing read-only destination file. Use caution with /A:, /H, or /K when both the source and destination directories contain file descriptions. If the source specification matches the description file name (normally DESCRIPT.ION), and you use a switch which tells COPY to process hidden files, the DESCRIPT.ION file itself will be copied, overwriting any existing descriptions in the destination directory. For example, if the \DATA directory contains file descriptions this command would overwrite any existing descriptions in the \SAVE directory: [c:\data] copy /h d*.* \save\ If you copy a file from a FAT volume to an HPFS volume, and you do not give an explicit destination name (i.e., you are moving the file to the current directory, or your destination name is made up entirely of wildcards), COPY will look for a .LONGNAME extended attribute for the source file. If it finds that attribute, it will use the long filename for the destination file; otherwise, it will use the short name. Similarly, if you COPY files with long filenames from an HPFS volume to a FAT volume, Take Command will create the destination files with short, FAT-compatible names and save the long filenames in the .LONGNAME extended attribute. The short name is created by replacing special characters with underscores, adding numeric digits to the filename (if necessary) to make the new name unique, and truncating the name to fit with in the "8.3" FAT name structure. Options: The /A(SCII) and /B(inary) options apply to the preceding filename and to all subsequent filenames on the command line until the file name preceding the next /A or /B, if any. The other options (/A:, /C, /E, /H, /K, /M, /N, /P, /Q, /R, /S, /T, /U, /V, /X, /Z) apply to all filenames on the command line, no matter where you put them. For example, either of the following commands could be used to copy a font file to the printer in binary mode: [c:\] copy /b myfont.dat prn [c:\] copy myfont.dat /b prn Some options do not make sense in certain contexts, in which case COPY will ignore them. For example, you cannot prompt before replacing an existing file when the destination is a device such as the printer -- there's no such thing as an "existing file" on the printer. If you use conflicting output options, like /Q and /P, COPY will generally take a "conservative" approach and give priority to the option which generates more prompts or more information. /A (ASCII) If you use /A with a source filename, the file will be copied up to, but not including, the first Ctrl-Z (Control-Z or ASCII 26) character in the file (some application programs use the Ctrl-Z to mark the end of a file). If you use /A with a destination filename, a Ctrl-Z will be added to the end of the file. /A is the default when appending files, or when the destination is a device like NUL or PRN, rather than a disk file. /A: (Attribute select): Select only those files that have the specified attribute(s) set. Preceding the attribute character with a hyphen [-] will select files that do not have that attribute set. The colon [:] after /A is required. The attributes are: R Read-only H Hidden S System D Subdirectory A Archive If no attributes are listed at all (e.g., COPY /A:), COPY will select all files and subdirectories including hidden and system files (this is equivalent to COPY /H). If attributes are combined, all the specified attributes must match for a file to be selected. For example, /A:RHS will select only those files with all three attributes set. See the cautionary note under Advanced Features above before using /A: when both source and destination directories contain file descriptions. /B (Binary) If you use /B with a source filename, the entire file is copied; Ctrl-Z characters in the file do not affect the copy operation. Using /B with a destination filename prevents addition of a Ctrl-Z to the end of the destination file. /B is the default for normal file copies. /C (Changed files) Copy files only if the destination file exists and is older than the source (see also /U). This option is useful for updating the files in one directory from those in another without copying any newly created files. /E (No error messages) Suppress all non-fatal error messages, such as "File not found." Fatal error messages, such as "Drive not ready," will still be displayed. This option is most useful in batch files and aliases. /F (Fail on EA error) Fail if the source file has extended attributes and the destination file system doesn't support extended attributes. /H (Hidden) Copy all matching files including those with the hidden and/or system attribute set. See the cautionary note under Advanced Features above before using /H when both source and destination directories contain file descriptions. /K (Keep attribute) To maintain compatibility with COMMAND.COM, CMD.EXE, and Netware, COPY normally maintains the hidden and system attributes, sets the archive attribute, and removes the read-only attribute on the target file. /K tells COPY to also maintain the read-only attribute on the destination file. However, if the destination is on a Novell Netware volume, this option will fail to maintain the read-only attribute. This is due to the way Netware handles file attributes, and is not a problem in COPY. /M (Modified) Copy only those files with the archive attribute set, i.e., those which have been modified since the last backup. The archive attribute of the source file will not be cleared after copying; to clear it use the /X switch, or use ATTRIB. /N (Nothing) Do everything except actually perform the copy. This option is useful for testing what the result of a complex COPY command will be. /N does not prevent creation of destination subdirectories when it is used with /S. /P (Prompt) Ask the user to confirm each source file. Your options at the prompt are explained in detail under Page and File Prompts. /Q (Quiet) Don't display filenames or the total number of files copied. This option is most often used in batch files. /R (Replace) Prompt the user before overwriting an existing file. Your options at the prompt are explained in detail under Page and File Prompts. /S (Subdirectories) Copy the subdirectory tree starting with the files in the source directory plus each subdirectory below that. The destination must be a directory; if it doesn't exist, COPY will attempt to create it. COPY will also attempt to create needed subdirectories on the tree below the destination, including empty source directories. If COPY /S creates one or more destination directories, they will be added automatically to the extended directory search database. If you attempt to use COPY /S to copy a subdirectory tree into part of itself, COPY will detect the resulting infinite loop, display an error message. and exit. /T (Totals) Turns off the display of filenames, like /Q, but does display the total number of files copied. /U (Update) Copy each source file only if it is newer than a matching destination file or if a matching destination file does not exist (see also /C). This option is useful for keeping one directory matched with another with a minimum of copying. /V (Verify) Verify each disk write. This is the same as executing the VERIFY ON command, but is only active during the COPY. /V does not read back the file and compare its contents with what was written; it only verifies that the data written to disk is physically readable. /X (Clear archive) Clears the archive attribute from the source file after a successful copy. This option is most useful if you are using COPY to maintain a set of backup files. /Z (Overwrite) Overwrites read-only destination files. Without this option, COPY will fail with an "Access denied" error if the destination file has its read-only attribute set. This option allows COPY to overwrite read-only files without generating any errors. ═══ 3.3.14. DATE - Set the date ═══ Purpose: Display and optionally change the system date. Format: DATE [mm-dd- yy] mm : The month (1 - 12). dd : The day (1 - 31). yy : The year (80 - 99 = 1980 - 1999, or a 4-digit year). See also: TIME. Usage: If you simply type DATE without any parameters, you will see the current system date and time, and be prompted for a new date. Press Enter if you don't wish to change the date. If you type a new date, it will become the current system date, which is included in the directory entry for each file as it is created or altered: [c:\] date Mon Dec 22, 1997 9:30:06 Enter new date (mm-dd-yy): You can also enter a new system date by typing the DATE command plus the new date on the command line: [c:\] date 10-16-97 You can use hyphens, slashes, or periods to separate the month, day, and year entries. The year can be entered as a 2-digit or 4-digit value. Two-digit years between 80 and 99 are interpreted as 1980 - 1999; values between 00 and 79 are interpreted as 2000 - 2079. DATE adjusts the format it expects depending on your country settings. When entering the date, use the correct format for the country setting currently in effect on your system. ═══ 3.3.15. DEL - Delete files ═══ Purpose: Erase one file, a group of files, or entire subdirectories. Format: DEL [/A:[[-]rhsda] /E /F /N /P /Q /S /T /W /X /Y /Z] file... or ERASE [/A:[[-]rhsda] /E /F /N /P /Q /S /T /W /X /Y /Z] file... file : The file, subdirectory, or list of files or subdirectories to erase. /A: (Attribute select) /S(ubdirectories) /E (No error messages) /T(otal) /F(orce delete) /W(ipe) /N(othing) /X (remove empty subdirectories) /P(rompt) /Y(es to all prompts) /Q(uiet) /Z(ap hidden and read-only files) File Selection: Supports extended wildcards, ranges, multiple file names, and include lists. Usage: DEL and ERASE are synonyms; you can use either one. Use the DEL and ERASE commands with caution; the files and subdirectories that you erase may be impossible to recover without specialized utilities and a lot of work. To erase a single file, simply enter the file name: [c:\] del letters.txt You can also erase multiple files in a single command. For example, to erase all the files in the current directory with a .BAK or .PRN extension: [c:\] del *.bak *.prn When you use DEL on an NTFS drive, you must quote any file names which contain whitespace or special characters. To exclude files from a DEL command, use a file exclusion range. For example, to delete all files in the current directory except those whose extension is .TXT, use a command like this: [c:\] del /[!*.TXT] *.* When using exclusion ranges or other more complex options you may want to use the /N switch first, to preview the effects of the DEL without actually deleting any files. If you enter a subdirectory name, or a filename composed only of wildcards (* and/or ?), DEL asks for confirmation (Y or N) unless you specified the /Y option. If you respond with a Y, DEL will delete all the files in that subdirectory (hidden, system, and read-only files are only deleted if you use the /Z option). DEL displays the amount of disk space recovered, unless the /Q option is used (see below). It does so by comparing the amount of free disk space before and after the DEL command is executed. This amount may be incorrect if you are using a deletion tracking system which stores deleted files in a hidden directory, or if another program performs a file operation while the DEL command is executing. Remember that DEL removes file descriptions along with files. Most deletion tracking systems will not be able to save or recover a file's description, even if they can save or recover the data in a file. When a file is deleted, its disk space is returned to the operating system for use by other files. However, the contents of the file remain on the disk until they are overwritten by another file. If you wish to obliterate a file or wipe its contents clean, use DEL /W, which overwrites the file with zeros before deleting it. Use this option with caution. Once a file is obliterated, it is impossible to recover. DEL returns a non-zero exit code if no files are deleted, or if another error occurs. You can test this exit code with the %_? environment variable, and use it with conditional commands (&& and ||). Options: /A: (Attribute select): Select only those files that have the specified attribute(s) set. Preceding the attribute character with a hyphen [-] will select files that do not have that attribute set. The colon [:] after /A is required. The attributes are: R Read-only H Hidden S System D Subdirectory A Archive If no attributes are listed at all (e.g., DEL /A:), DEL will delete all files and subdirectories including hidden and system files. If attributes are combined, all the specified attributes must match for a file to be selected for deletion. For example, /A:RHS will select only those files with all three attributes set. /E (No error messages) Suppress all non-fatal error messages, such as "File Not Found." Fatal error messages, such as "Drive not ready," will still be displayed. This option is most useful in batch files and aliases. /F (Force delete) This option forces deletion of the file without saving it to the DELDIR directory (if DELDIR is not in use, /F has no effect). /N (Nothing) Do everything except actually delete the file(s). This is useful for testing what the result of a DEL would be. /P (Prompt) Prompt the user to confirm each erasure. Your options at the prompt are explained in detail under Page and File Prompts. /Q (Quiet) Don't display filenames as they are deleted, or the number of files deleted or bytes freed. See also /T. /S (Subdirectories) Delete the specified files in this directory and all of its subdirectories. This can be used to delete all the files in a subdirectory tree or even a whole disk. It should be used with caution! /T (Total) Don't display filenames as they are deleted, but display the total number of files deleted plus the amount of free disk space recovered. /W (Wipe) Clear the file to zeros before deleting it. Use this option to completely obliterate a file's contents from your disk. Once you have used this option it is impossible to recover the file even if you are using an undelete utility, because the contents of the file are destroyed before it is deleted. /W overwrites the file only once; it does not adhere to security standards which require multiple overwrites with varying data when destroying sensitive information. /X (Remove empty subdirectories) Remove empty subdirectories after deleting (only useful when used with /S). If DEL deletes one or more directories, they will be removed automatically from the extended directory search database. /Y (Yes) The reverse of /P -- it assumes a Y response to everything, including deleting an entire subdirectory tree. Take Command normally prompts before deleting files when the name consists only of wildcards or a subdirectory name ( see above); /Y overrides this protection, and should be used with extreme caution! /Z (Zap) Delete read-only, hidden, and system files as well as normal files. Files with the read-only, hidden, or system attribute set are normally protected from deletion; /Z overrides this protection, and should be used with caution. Because EXCEPT works by hiding files, /Z will override an EXCEPT command. However, files specified in a file exclusion range will not be deleted by DEL /Z. For example, to delete the entire subdirectory tree starting with C:\UTIL, including hidden and read-only files, without prompting (use this command with CAUTION!): [c:\] del /sxyz c:\util\ ═══ 3.3.16. DELAY - Pause for a specified time ═══ Purpose: Pause for a specified length of time. Format: DELAY [seconds ] seconds : The number of seconds to delay. Usage: DELAY is useful in batch file loops while waiting for something to occur. To wait for 10 seconds: delay 10 DELAY is most useful when you need to wait a specific amount of time for an external event, or check a system condition periodically. For example, this batch file checks the battery status (as reported by your Advanced Power Management drivers) every 15 seconds, and gives a warning when battery life falls below 30%: do forever iff %_apmlife lt 30 then beep 440 4 880 4 440 4 880 4 echo Low Battery!! endiff delay 15 enddo The seconds value can be as large as about 268 thousand seconds (8.5 years!). For delays shorter than one second, use the BEEP command with an inaudible frequency (below 20 Hz). Take Command uses the minimum possible processor time during a DELAY, in order to allow other applications full use of system resources. You can cancel a delay by pressing Ctrl-C or Ctrl-Break. ═══ 3.3.17. DESCRIBE - Create file description ═══ Purpose: Create, modify, or delete file and subdirectory descriptions. Format: DESCRIBE [/A:[[-]rhsda]] file [[/D]"description "] ... file : The file, directory, or list of files and directories to operate on. "description" : The description to attach to the file. /A: (Attribute select)/D(escription follows) File Selection: Supports extended wildcards, ranges, multiple file names, and include lists. Usage: DESCRIBE adds descriptions to files and subdirectories. The descriptions are displayed by DIR in single-column mode and by SELECT. Descriptions let you identify your files in much more meaningful ways than you can in an eight- character filename. You can also enter or modify descriptions with the Descriptions dialog. The dialog allows you to select a single file and modify its description using a dialog box, rather than using the DESCRIBE command. The information in this section also applies to descriptions created via the dialog, unless otherwise noted. You enter a description on the command line by typing the DESCRIBE command, the filename, and the description in quotation marks, like this: [c:\] describe memo.txt "Memo to Bob about party" If you don't put a description on the command line, DESCRIBE will prompt you for it: [c:\] describe memo.txt Describe "memo.txt" : Memo to Bob about party If you use wildcards or multiple filenames with the DESCRIBE command and don't include the description text, you will be prompted to enter a description for each file. If you do include the description on the command line, all matching files will be given the same description. If you use DESCRIBE on an HPFS drive, you must quote the file name if it contains whitespace or special characters. See File Names for additional details. If you enter a quoted description on the command line, and the text matches the name of a file in the current directory, the command processor will treat the string as a quoted file name, not as description text as you intended. To resolve this problem use the /D switch immediately prior to the quoted description (with no intervening spaces). For example, if the current directory contains the files DATA.TST and "Test File", the first of these commands will work as intended, but the second will not (in the second example the string "test file" will be treated as a second file name, when it is intended to be description text): [c:\] describe data.tst /D"test file" [c:\] describe data.tst "test file" On HPFS drives you will not see file descriptions in a normal DIR display, because DIR must leave space for the long filenames. To view the descriptions, use DIR /Z to display the directory in FAT format. See the DIR command for more details. Each description can be up to 511 characters long. You can change this limit on the Options 1 page of the configuration notebook, or with the DescriptionMax directive in TCMDOS2.INI. In order to fit your descriptions on a single line in a standard DIR display, keep them to 40 characters or less (longer descriptions are wrapped in the DIR output). DESCRIBE can edit descriptions longer than DescriptionMax, but will not allow you to lengthen the existing text. The descriptions are stored in each directory in a hidden file called DESCRIPT.ION. Use the ATTRIB command to remove the hidden attribute from this file if you need to copy or delete it. (DESCRIPT.ION is always created as a hidden file, but will not be re-hidden by Take Command if you remove the hidden attribute.) You can change the description file name with the INI_DescriptionName directive in the TCMDOS2.INI file or the SETDOS command, and retrieve it with the _DNAME internal variable. Use caution when changing the description file name, as changing the name from the default will make it difficult to transfer file descriptions to another system. The description file is modified appropriately whenever you perform an internal command which affects it (such as COPY, MOVE, DEL, or RENAME), but not if you use an external program (such as XCOPY or a visual shell). You can disable description processing on the Options 1 page of the configuration notebook, with the Descriptions directive in the TCMDOS2.INI file, or with SETDOS/D. When you COPY or MOVE files between two directories, both of which have descriptions, and you use switches which enable processing of hidden files (or you have removed the hidden attribute from DESCRIPT.ION), you must use caution to avoid overwriting existing file descriptions in the destination directory with the DESCRIPT.ION file from the source directory. See the notes under the Advanced Features sections of COPY and MOVE for additional details. Options: /A: (Attribute select): Select only those files that have the specified attribute(s) set. Preceding the attribute character with a hyphen [-] will select files that do not have that attribute set. The colon [:] after /A is required. The attributes are: R Read-only H Hidden S System D Subdirectory A Archive If no attributes are listed at all (e.g., /A:), DESCRIBE will select all files and subdirectories including hidden and system files. If attributes are combined, all the specified attributes must match for a file to be selected. For example, /A:RHS will select only those files with all three attributes set. /D: (Description follows) The quoted string immediately following this switch is a description, not a file name. Use /D to avoid any ambiguity in the meaning of quoted strings. See the Usage section above for details. ═══ 3.3.18. DETACH - Start a program in "detached" mode ═══ Purpose: Start a DOS application or an OS/2 text-mode program in "detached" mode. Format: DETACH command command : The name of a command to execute, including an optional drive and path specification. The name must be enclosed in quotation marks if it contains whitespace or special characters. See also: START. Usage: When you start a program with DETACH, that program cannot use the keyboard, mouse, or video display. It is "detached" from the normal means of user input and output. However, you can redirect the program's standard I/O to other devices if necessary, using redirection symbols. In most cases, you should only DETACH text-mode programs, since most graphical applications cannot run without a screen or keyboard, or have their input and output redirected. The command can be an internal command, external command, alias, or batch file. If it is not an external command, Take Command will detach a copy of itself to execute the command. For example, the following command will detach a copy of Take Command to run the batch file XYZ.BTM: [c:\] detach xyz.btm Once the program has started, Take Command returns to the prompt immediately. It does not wait for a detached program to finish. There is no standard way to stop a detached program. If the program does not terminate on its own you must reboot the system or use an appropriate task manager or external utility to stop it. Due to limitations in the way OS/2 starts detached processes, Take Command cannot perform a true detach operation like that available from a character-mode command processor such as 4OS2 or CMD.EXE. Instead, it starts the program in an invisible window. If you require a true detached process you must use a character-mode command processor to start it. ═══ 3.3.19. DIR - Display directories ═══ Purpose: Display information about files and subdirectories. Format: DIR [/1 /2 /4 /A[[:][-]rhsda] /B /C /D /E /F /G /H /I"text" /J /K /L /M /N /O[[:][-]adeginrsu] /P /R /S /T[:acw] /U /V /W /Z] [file...] file : The file, directory, or list of files or directories to display. /1 (one column) /L(ower case) /2 (two columns) /M (suppress footer) /4 (four columns) /N(ew format) /A(ttribute select) /O(rder) /B(are) /P(ause) /D(isable color coding) /R (disable wRap) /E (use upper case) /S(ubdirectories) /F(ull path) /T (aTtribute) or (Time) /G (allocated size) /U (sUmmary information) /H(ide dots) /V(ertical sort) /I (match descriptions) /W(ide) /J(ustify names) /Z (use FAT format) /K (suppress header) See also: ATTRIB, DESCRIBE, SELECT, and SETDOS. File Selection: Supports extended wildcards, ranges, multiple file names, and include lists. Usage: DIR can be used to display information about files from one or more of your disk directories, in a wide range of formats. Depending on the options chosen, you can display the file name, attributes, and size; the time and date of the last change to the file; and the file description. You can also display information in 1, 2, 4, or 5 columns, sort the files several different ways, use color to distinguish file types, and pause after each full screen. The various DIR displays are controlled through options or switches. The best way to learn how to use the many options available with the DIR command is to experiment. You will soon know which options you want to use regularly. You can select those options permanently by using the ALIAS command. For example, to display all the files in the current directory, in 2 columns, sorted vertically (down one column then down the next), and with a pause at the end of each page: [c:\] dir /2/p/v To set up this format as the default, using an alias: [c:\] alias dir=*dir /2/p/v When you use DIR on an NTFS drive, you must quote any file names which contain whitespace or special characters. The following sections group DIR's features together in several categories. Many of the sections move from a general discussion to more technical material. If you find some of the information in a category too detailed for your needs, feel free to skip to the beginning of the next section. The sections are: Selecting Files Default DIR Output Format Switching Formats Multiple Column Displays Color-Coded Directories Redirected Output Other Notes Options Selecting Files DIR can display information about a single file or about several, dozens, hundreds, or thousands of files at once. To display information about a single file, just add the name of the file to the DIR command line: [c:\] dir january.wks The simplest way to view information about several files at once is to use wildcards. DIR can work with traditional wildcard caracters (* and ?) and the extended wildcards. For example to display all of the .WKS files in the current directory: [c:\] dir *.wks To display all .TXT files whose names begin with A, B, or C: [c:\] dir [abc]*.txt If you don't specify a filename, DIR defaults to *.* on traditional FAT drives, and * NTFS drives. This default displays all non-hidden files and subdirectories in the current directory. If you link two or more filenames together with spaces, DIR will display all of the files that match the first name and then all of the files that match the second name. You may use a different drive and path for each filename. This example lists all of the .WKS and then all of the .WK1 files in the current directory: [c:\] dir *.wks *.wk1 If you use an include list to link multiple filenames, DIR will display the matching filenames in a single listing. Only the first filename in an include list can have a path; the other files must be in the same path. This example displays the same files as the previous example, but the .WKS and .WK1 files are intermixed: [c:\] dir *.wks;*.wk1 You can include files in the current or named directory plus all of its subdirectories by using the /S option. This example displays all of the .WKS and .WK1 files in the D:\DATA directory and each of its subdirectories: [c:\] dir /s d:\data\*.wks;*.wk1 You can also select files by their attributes by using the /A option. For example, this command displays the names of all of the subdirectories of the current directory: [c:\] dir /a:d Finally, with the /I option, DIR can select files to display based on their descriptions (see the DESCRIBE command for more information on file descriptions). DIR will display a file if its description matches the text after the /I switch. The search is not case sensitive. You can use wildcards and extended wildcards as part of the text. For example, to display any file described as a "Test File" you can use this command: [c:\] dir /i"test file" If you want to display files that include the words "test file" anywhere in their descriptions, use extended wildcards like this: [c:\] dir /i"*test file*" To display only those files which do not have descriptions, use: [c:\] dir /I"[]" In addition, you can use ranges to select or exclude specific sets of files. For example, to display all files modified in the last week, all files except those with a .BAK extension, and all files over 500 KB in size: [c:\] dir /[d-7] [c:\] dir /[!*.bak] [c:\] dir /[s500K] You can, of course, mix any of these file selection techniques in whatever ways suit your needs. Default DIR Output Format DIR's output varies based on the the type of volume or drive on which the files are stored. If the volume supports long file names (HPFS volumes), the default DIR format contains 4 columns: the date of the last file modification or write, the time of last write, the file size in bytes, and the file name. The name is displayed as it is stored on the disk, in upper, lower, or mixed case. DIR will wrap filenames from one line to the next if they are too long to fit the width of the display. The standard output format is: Volume in drive C is C - BOOTUP Serial ... Directory of C:\TCOS2201\*.* 10-24-96 12:17 . 10-24-96 12:17 .. 10-28-96 7:57 967 tcmd 3.txt 10-21-96 18:08 212,854 TCMDOS2.EXE 11-02-96 10:08 45 TCMDOS2.INI (See Switching Formats below for information on changing the standard long filename format to allow room for file descriptions.) On FAT volumes which do not support long file names, the default DIR format contains 5 columns: the file name, the file size in bytes, the date of the last write, the time of the last write, and the file's description. File names are listed in lower-case; directory names in upper case: Volume in drive C is C - BOOTUP Serial ... Directory of C:\4DOS60\*.* . 10-24-96 12:17 .. 10-24-96 12:17 TEST 11-01-96 16:21 4dos6.pif 967 10-28-96 7:57 4DOS PIF file 4dos.com 212854 10-21-96 18:08 4DOS exe ... 4dos.ini 45 11-02-96 10:08 4DOS conf ... DIR's output is normally sorted by name, with directories listed first. You can change the sort order with the /O option. For example, these two commands sort the output by date Ч the first command lists the oldest file first; the second command lists the oldest file last: [c:\] dir /o:d [c:\] dir /o:-d When displaying file descriptions, DIR wraps long lines to fit on the screen. DIR displays a maximum of 40 characters of text in each line of a description, unless your screen width allows a wider display. If you disable description wrapping with the /R option, the description is truncated at the right edge of the screen, and a right arrow [] is added at the end of the line to alert you to the existence of additional description text. Regardless of the volume type, DIR's default output is sorted. It displays directory names first, with "" inserted instead of a file size, and then filenames. DIR assumes that sequences of digits should be sorted numerically (for example, the file DRAW2 is listed before DRAW03 because 2 is numerically smaller than 03), rather than strictly alphabetically (where DRAW2 would come second because "2" is after "0" in alphanumeric order). You can change the sort order with the /O option. When DIR displays file names in a multi-column format, it sorts file names horizontally unless you use the /V option to display vertically sorted output. DIR's display can be modified in many ways to meet different needs. Most of the following sections describes the various ways you can change DIR's output format. Switching Formats On HPFS volumes, which support long file names, you can force DIR to use a FAT-like format (file name first, followed by file information) with the /Z option. With this option, DIR truncates long file names, if necessary, and adds a right arrow [] to show that the name contains additional characters. The standard long file name output format does not provide enough space to show descriptions along with file names. Therefore, if you wish to view file descriptions as part of the DIR listing on a volume which supports long file names, you must use the /Z option. If you use the /B option, DIR displays just file names and omits the file size, time stamp, and description for each file, for example: [c:\] dir w* /b WINDOWS WINNT win311 WINALIAS WINENV.BTM ..... There are several ways to modify the display produced by /B. The /F option is similar to /B, but displays the full path and name of each file, instead of just its name. To view the same information for a directory and its subdirectories use /B /S or /F /S. Multiple Column Displays DIR has three options, /2, /4, and /W, that create multi-column displays. The /2 option creates a 2-column display. On HPFS drives, only the name of each file is displayed, with directory names placed in square brackets to distinguish them from file names. On drives which do not support long filenames, or when /Z or /X is used (see below), the display includes the short name, file size, and time stamp for each file. The /4 option is similar to /2, but displays directory information in 4 columns. On drives which do not support long filenames, or when /Z or /X is used (see below), the display shows the file name and the file size in kilobytes (KB) or megabytes (MB), with "" in the size column for directories. The /W option displays directory information in 5 or more columns, depending on your screen width. Each entry in a DIR /W display contains either the name of a file or the name of a directory. Directory names are placed in square brackets to distinguish them from file names. If you use one of these options on an HPFS drive, and do not select an alternate display format with /Z or /X, the actual number of columns will be based on the longest name to be displayed and your screen width, and may be less than the number you requested (for example, you might see only three columns even though you used /4). If the longest name is too long to fit in on a single line the display will be reduced to one column, and each name will be wrapped, with "extra" blank lines added so that each name takes the same number of lines. Color-Coded Directories The DIR command can display each file name and the associated file information in a different color, depending on the file's extension. To choose the display colors, you must either use the SET command to create an environment variable called COLORDIR, use the Commands page of the configuration notebook, or use the ColorDir directive in your TCMDOS2.INI file. If you do not use the COLORDIR variable or the ColorDir directive, DIR will use the default screen colors for all files. If you use both the COLORDIR variable and the ColorDir directive, the environment variable will override the settings in your TCMDOS2.INI file. You may find it useful to use the COLORDIR variable for experimenting, then to set permanent directory colors with the ColorDir directive. The format for both the COLORDIR environment variable and the ColorDir directive in the .INI file is: ext ... :ColorName; ... where "ext" is a file extension (which may include wildcards) or one of the following file types: DIRS Directories RDONLY Read-only files HIDDEN Hidden files SYSTEM System files ARCHIVE Files modified since the last backup and "ColorName" is any valid color name (see Colors and Color Names). Unlike most color specifications, the background portion of the color name may be omitted for directory colors. If you don't specify a background color, DIR will use the current screen background color. For example, to display the .COM and .EXE files in red on the current background, the .C and .ASM files in bright cyan on the current background, and the read-only files in green on white (this should be entered on one line): [c:\] set colordir=com exe:red; c asm:bright cyan; rdonly:green on white Extended wildcards can be used in directory color specifications. For example, to display .BAK, .BAX, and .BAC files in red: [c:\] set colordir=BA[KXC]:red Redirected Output The output of the DIR command, like that of most other internal commands, can be redirected to a file, printer, serial port, or other device. However, you may need to take certain DIR options into account when you redirect DIR's output. DIR wraps both long file names and file descriptions at the width of your display. Its redirected output will also wrap at the screen width. Use the /R option if you wish to disable wrapping of long descriptions. If you redirect a color-coded directory to a file, DIR will remove the color data as it sends the directory information to a file. It will usually do the same if you redirect output to a character device such as a printer or serial port. However, it is not always possible for DIR to tell whether or not a device is a character device. If you notice that non-colored lines are being sent to the output device and colored lines are appearing on your screen, you can use the /D option to temporarily disable color-coding when you redirect DIR's output. To redirect DIR output to the clipboard, use CLIP: as the output device name, for example: [c:\] dir *.exe > clip: Other Notes If you have selected a specific country code for your system, DIR will display the date in the format for that country. The default date format is U.S. (mm- dd-yy). The separator character in the file time will also be affected by the country code. Thousands and decimal separators in numeric displays are affected by the country code, and by the ThousandsChar and DecimalChar settings selected on the Options 1 page of the configuration notebook, or in the TCMDOS2.INI file. DOS networks with large server volumes (over 2 GB) may report incorrect free disk space values at the end of the DIR display. If this occurs, it is because the network software does not report the proper values to Take Command. Options: Options on the command line apply only to the filenames which follow the option, and options at the end of the line apply to the preceding filename only. This allows you to specify different options for different groups of files, yet retains compatibility with the traditional DIR command when a single filename is specified. /1 Single column display - display the filename, size, date, time; also displays the description on drives which do not support long filenames. This is the default. If /T is used the attributes are displayed instead of the description. This option is most useful if you wish to override a default /2, /4, or /W setting stored in an alias. /2 Two column display - display just the name on HPFS drives, or display the filename, size, date, and time on other drives. See Multiple Column Displays above for more details. /4 Four column display - display just the name on HPFS drives the filename and size, in K (kilobytes) or M (megabytes) on other drives, with files between 1 and 9.9 megabytes in size displayed in tenths (i.e., "2.4M"). See Multiple Column Displays above for more details. /A (Attribute select): Display only those files that have the specified attribute(s) set. Preceding the attribute character with a hyphen [-] will select files that do not have that attribute set. The colon [:] after /A is optional. The attributes are: R Read-only H Hidden S System D Subdirectory A Archive If no attributes are listed at all (e.g., DIR /A), DIR will display all files and subdirectories including hidden and system files. If attributes are combined, all the specified attributes must match for a file to be included in the listing. For example, /A:RHS will display only those files with all three attributes set. /B (Bare) Suppress the header and summary lines, and display file or subdirectory names only, in a single column. This option is most useful when you want to redirect a list of names to a file or another program. If you use /B with /S, DIR will show the full path of each file (the same display as /F) instead of simply its name and extension. /D (Disable color coding) Temporarily disable directory color coding. May be required when color-coded directories are used and DIR output is redirected to a character device like the printer (e.g., PRN or LPT1) or serial port (e.g., COM1 or COM2). /D is not required when DIR output is redirected to a file. /E Display filenames in upper case; also see SETDOS /U and the UpperCase directive in TCMDOS2.INI. /F (Full path) Display each filename with its drive letter and path in a single column, without other information. /G (Allocation size) Display the allocated disk space instead of the actual size of each file. /H (Hide dots) Suppress the display of the "." and ".." directories. /I Display filenames by matching text in their descriptions. The text can include wildcards and extended wildcards. The search text must be enclosed in quotation marks. You can select all filenames that have a description with /I"[?]*" or all filenames that do not have a description with /I"[]". The /I option may be used to select files even if descriptions are not displayed (for example, if /2 is used). /J (Justify names) Justify (align) filename extensions and display them in the traditional format. /K Suppress the header (disk and directory name) display. /L (Lower case) Display file and directory names in lower case; also see SETDOS /U and the UpperCase directive in TCMDOS2.INI. /M Suppress the footer (file and byte count totals) display. /N (New format) Use the long filename display format, even if the files are stored on a volume which does not support long filenames. See also /Z. /O (Order) Set the sorting order. You may use any combination of the following sorting options; if multiple options are used, the listing will be sorted with the first sort option as the primary key, the next as the secondary key, and so on: - Reverse the sort order for the next option a Sort in ASCII order, not numerically, when there are digits in the name d Sort by date and time (oldest first); for HPFS drives also see /T e Sort by extension g Group subdirectories first, then files i Sort by file description n Sort by filename (this is the default) r Reverse the sort order for all options s Sort by size u Unsorted /P (Pause) Wait for a key to be pressed after each screen page before continuing the display. Your options at the prompt are explained in detail under Page and File Prompts. /R (disable wRap) Forces long descriptions to be displayed on a single line, rather than wrapped onto two or more lines. Use /R when output is redirected to a character device, such as a serial port or the printer; or when you want descriptions truncated, rather than wrapped, in the on-screen display. /S (Subdirectories) Display file information from the current directory and all of its subdirectories. DIR will only display headers and summaries for those directories which contain files that match the filename(s), ranges, and attributes that you specify on the command line. /T (aTtribute display) Display the filenames, attributes, and descriptions. The descriptions will be wrapped onto the next line, if necessary, unless you also use the /R (truncate) option. If you use both /T and /R, descriptions are truncated after 34 characters on an 80-column display. The attributes are displayed in the format RHSDA, with the following meanings: R Read-only H Hidden S System D Directory A Archive If you wish to add another option after /T, you must start the next option with a forward slash. If you don't, Take Command will interpret the /T as the /T:acw time display switch (see below) and the following character as a valid or invalid time selector. For example: [c:\] dir /tz incorrect, will display error [c:\] dir /t/z correct /T:acw (Time display) Specify which of the date and time fields on an HPFS drive should be displayed and used for sorting: a Last access time c Creation time w Last write time (default) /U (sUmmary information) Only display the number of files, the total file size, and the total amount of disk space used. /V (Vertical sort) Display the filenames sorted vertically rather than horizontally (use with the /2, /4 or /W options). /W (Wide) Display filenames only, horizontally across the screen. On drives which do not support long filenames, /W displays as many columns as it can fit into the Take Command window, using 16 characters in each column. Otherwise (i.e., when long filenames are displayed) the number of columns depends on the width of the longest name in the listing. See Multiple Column Displays above for more details. /Z Display a directory on an HPFS drive in the tradtional FAT format, with the filename at the left and the description at the right. Long names will be truncated to 12 characters unless /X is also used; if the name is longer than 12 characters, it will be followed by a right arrow [] to show that one or more characters have been truncated. ═══ 3.3.20.  DIRHISTORY - Display the directory history list ═══ Purpose: Display, add to, clear, or read the directory history list. Format: DIRHISTORY [ /A directory /F /P /R filename ] directory : The name of a directory to add to the directory history. filename : The name of a file containing entries to be added to the directory history. /A(dd): pd./P(ause) /F(ree) /R(ead file) Usage: Every time you change to a new directory or drive, Take Command records the current directory in an internal directory history list. The directory history window allows you to use the list to return to a previous directory. For general information, also see Directory Navigation. The DIRHISTORY command lets you view and manipulate the directory history list directly. If no parameters are entered, DIRHISTORY will display the current directory history list: [c:\] dirhistory With the options explained below, you can clear the list, add new directories to the list without changing to them, save the list in a file, or read a new list from a file. The number of directories saved in the directory history list depends on the length of each directory name. The list size can be specified at startup from 256 to 32767 characters by using the DirHistory directive in the .INI file. The default size is 256 characters. Your directory history list can be stored either locally (a separate history list for each copy of Take Command) or globally (all copies of Take Command share the same list). For full details see the discussion of local and global directory history lists in Directory History Window. You can save the directory history list by redirecting the output of DIRHISTORY to a file. This example saves the history to a file called DIRHIST and reads it back again. [c:\] dirhistory > dirhist ..... [c:\] dirhistory /r dirhist Because the directory history stores each name only once, you don't have to delete its contents before reading back the file unless you want to delete the directories that were visited by the intervening commands. If you need to save your directory history at the end of each day's work, you might use the first of these commands in your TCSTART.BTM or other startup file, and the second in TCEXIT.BTM: if exist c:\dirhist dirhistory /r c:\dirhist dirhistory > c:\dirhist This restores the previous history list if it exists, and saves the history when Take Command exits. Options: /A (Add) Add a directory to the directory history list. /F (Free): Erase all entries in the directory history list. /P (Prompt): Wait for a key after displaying each page of the list. Your options at the prompt are explained in detail under Page and File Prompts. /R (Read): Read the directory history from the specified file and append it to the list currently held in memory. ═══ 3.3.21. DIRS - Display the directory stack ═══ Purpose: Display the current directory stack. Format: DIRS See also: PUSHD, POPD, and Directory Navigation. Usage: The PUSHD command adds the current default drive and directory to the directory stack, a list that Take Command maintains in memory. The POPD command removes the top entry of the directory stack and makes that drive and directory the new default. The DIRS command displays the contents of the directory stack, with the most recent entries on top (i.e., the next POPD will retrieve the first entry that DIRS displays). For example, to change directories and then display the directory stack: [c:\] pushd c:\database [c:\database] pushd d:\wordp\memos [d:\wordp\memos] dirs c:\database c:\ The directory stack holds 511 characters, enough for 20 to 40 typical drive and directory entries. ═══ 3.3.22. DO - Loop in batch files ═══ DO Purpose: Create loops in batch files. Format: DO [n | FOREVER] or DO varname = start TO end [BY n ] or DO [WHILE | UNTIL] condition or DO varname IN [ @ ] set commands [ITERATE] [LEAVE] commands ENDDO varname : The environment variable that will hold the loop counter, filename, or line from a file. n, start, end : Integers between 0 and 2,147,483,647 inclusive, or an internal variable or variable function that evaluates to such a value. condition : A test to determine if the loop should be executed. set : A set of values for the variable. commands : One or more commands to execute each time through the loop. If you use multiple commands, they must be separated by command separators or be placed on separate lines. File Selection: Supports extended wildcards, ranges, and include lists for the set. Usage: DO can only be used in batch files. DO can be used to create 4 different kinds of loops. The first, introduced by DO n, is a counted loop. The batch file lines between DO and ENDDO are repeated n times. For example: do 5 beep enddo You can also specify "forever" for n if you wish to create an endless loop (you can use LEAVE or GOTO to exit such a loop; see below for details). The second type of loop is similar to a "for loop" in programming languages like BASIC. DO creates an environment variable, varname, and sets it equal to the value start (if varname already exists in the environment, it will be overwritten). DO then begins the loop process by comparing the value of varname with the value of end. If varname is less than or equal to end, DO executes the batch file lines up to the ENDDO. Next, DO adds 1 to the value of varname, or adds the value n if BY n is specified, and repeats the compare and execute process until varname is greater than end. This example displays the even numbers from 2 through 20: do i = 2 to 20 by 2 echo %i enddo DO can also count down, rather than up. If n is negative, varname will decrease by n with each loop, and the loop will stop when varname is less than end. For example, to display the even numbers from 2 through 20 in reverse order, replace the first line of the example above with: do i = 20 to 2 by -2 The third type of loop is called a "while loop" or "until loop." DO evaluates the condition, which can be any of the tests supported by the IF command, and executes the lines between DO and ENDDO as long as the condition is true. The loop ends when the condition becomes false. WHILE tests the condition at the start of the loop. Therefore, if the condition is false when the loop starts, the statements within the loop will never be executed, and the batch file will continue with the statement after the ENDDO. UNTIL tests the condition at the end of the loop. Therefore, if the condition is false when the loop starts, the statements within the loop will still be executed at least once. The fourth type of loop executes the lines between DO and ENDDO once for every member of a set (this is similar to the set used in the FOR command). Normally, the set is a list of files specified with wildcards. For example: do x in *.txt will execute the loop once for every .TXT file in the current directory; each time through the loop the variable x will be set to the name of the next file that matches the file specification. If, between DO and ENDDO, you create a new file that could be included in the list of files, it may or may not appear in an iteration of the DO loop. Whether the new file appears depends on its physical location in the directory structure, a condition over which Take Command has no control. You can also execute the loop once for each line of text in a file by placing an [@] in front of the file name. If you have a file called DRIVES.TXT that contains a list of drives on your computer, one drive name per line, you can execute the loop once for each drive this way: do x in @drives.txt To execute the loop once for each line of text in the clipboard, use CLIP: as the file name (e.g. DO X IN @CLIP:). CLIP: will not return any data unless the clipboard contains text. Two special commands, ITERATE and LEAVE, can be used inside a DO / ENDDO loop. ITERATE ignores the remaining lines inside the loop and returns to the beginning of loop for another iteration (unless DO determines that the loop is finished). LEAVE exits from the current DO loop and continues with the line following ENDDO. Both ITERATE and LEAVE are most often used in an IF or IFF command: do while "%var" != "%val1" ... if "%var" == "%val2" leave enddo You can nest DO loops up to 15 levels deep. The DO and ENDDO commands must be on separate lines, and cannot be placed within a command group, or on the same line as other commands (this is the reason DO cannot be used in aliases). However, commands within the DO loop can use command groups or the command separator in the normal way. You can exit from all DO / ENDDO loops by using GOTO to a line past the last ENDDO. However, be sure to read the cautionary notes about GOTO and DO under the GOTO command before using a GOTO inside any DO loop. ═══ 3.3.23. DPATH - Set data search path ═══ Purpose: Specify the subdirectories which applications will search to find files that are not in the current directory. Format: DPATH [directory [;directory...]] directory : The full name of a directory to include in the DPATH (data path) setting. See also: PATH, SET, and ESET. Usage: When most OS/2 applications try to open a data file, they look for the file in the current directory first. If they fail to find the file there, they search each of the directories in the DPATH setting in the order that they are included. Internal commands like TYPE do not search the DPATH directories for files. For example, the following DPATH command directs applications to look for files in this order: the current directory, the INIT directory on C, and the CONFIG directory on D: [c:\] dpath c:\init;d:\config The listing of directories to be searched can be set or viewed with DPATH. The list is stored as an environment string with the variable name DPATH, and can also be set or viewed with the SET command and edited with the ESET command. Directory names in the DPATH must be separated with semicolons [;]. Take Command will not shift directory names in the DPATH to upper case as it does with those in the PATH setting. If you want the names in the DPATH to be in upper case you must enter them that way. If you enter DPATH with no parameters, Take Command displays the current DPATH search list. ═══ 3.3.24. DRAWBOX - Draw a box ═══ Purpose: Draw a box on the screen. Format: DRAWBOX ulrow ulcol lrrow lrcol style [BRIght] fg ON [BRIght] bg [FILL [BRIght] bgfill] [ZOOm] [SHAdow] ulrow: Row for upper left corner ulcol: Column for upper left corner lrrow: Row for lower right corner lrcol: Column for lower right corner style: Box drawing style: 0 No lines (box is drawn with blanks) 1 Single line 2 Double line 3 Single line on top and bottom, double on sides 4 Double line on top and bottom, single on sides fg: Foreground character color bg: Background character color bgfill: Background fill color (for the inside of the box) See also: DRAWHLINE and DRAWVLINE. Usage: DRAWBOX is useful for creating attractive screen displays in batch files. For example, to draw a box around the edge of an 80x25 window with bright white lines on a blue background: drawbox 0 0 24 79 1 bri whi on blu fill blu See Colors and Color Names for details about colors. If you use ZOOM, the box appears to grow in steps to its final size. The speed of the zoom operation depends on the speed of your video system. If you use SHADOW, a drop shadow is created by changing the characters in the row under the box and the 2 columns to the right of the box to normal intensity text with a black background (this will make characters displayed in black disappear entirely). The row and column values are zero-based, so on a standard 25 line by 80 column display, valid rows are 0 - 24 and valid columns are 0 - 79. The maximum row value is determined by the current height of the Take Command window. The maximum column value is determined by the current virtual screen width. DRAWBOX checks for valid row and column values, and displays a "Usage" error message if any values are out of range. Unlike DRAWHLINE and DRAWVLINE, DRAWBOX does not automatically connect boxes to existing lines on the screen with the proper connector characters. If you want to draw lines inside a box and have the proper connectors drawn automatically, draw the box first, then use DRAWHLINE and DRAWVLINE to draw the lines. DRAWBOX uses the standard line and box drawing characters in the U.S. English extended ASCII character set. These characters are included in the English language versions of standard monospaced fonts typically available under OS/2 (e.g. Courier, System Monospaced, or System VIO). However, if your system is configured for a different font, character set (code page), or country, or you have replaced or modified the OS/2 default fonts, the box may not appear on your screen as you expect. ═══ 3.3.25. DRAWHLINE - Draw horizontal line ═══ Purpose: Draw a horizontal line on the screen. Format: DRAWHLINE row column len style [BRIght] fg ON [BRIght] bg row: Starting row column: Starting column len: Length of line style: Line drawing style: 1 Single line 2 Double line fg: Foreground character color bg: Background character color See Colors and Color Names for details about colors. See also: DRAWBOX and DRAWVLINE. Usage: DRAWHLINE is useful for creating attractive screen displays in batch files. It detects other lines and boxes on the display, and creates the appropriate connector characters when possible (not all types of lines can be connected with the available characters). For example, the following command draws a double line along the top row of the display with green characters on a blue background: drawhline 0 0 80 2 green on blue The row and column values are zero-based, so on a standard 25 line by 80 column display, valid rows are 0 - 24 and valid columns are 0 - 79. The maximum row value is determined by the current height of the Take Command window. The maximum column value is determined by the current virtual screen width. DRAWHLINE checks for a valid row and column, and displays a "Usage" error message if either value is out of range. See Colors and Color Names for details about colors. DRAWHLINE uses the standard line and box drawing characters in the U.S. English extended ASCII character set. These characters are included in the English language versions of standard monospaced fonts typically available under OS/2 (e.g. Courier, System Monospaced, or System VIO). However, if your system is configured for a different font, character set (code page), or country, or you have replaced or modified the OS/2 default fonts, the line may not appear on your screen as you expect. ═══ 3.3.26. DRAWVLINE - Draw a vertical line ═══ Purpose: Draw a vertical line on the screen. Format: DRAWVLINE row column len style [BRIght] fg ON [BRIght] bg row: Starting row column: Starting column len: Length of line style: Line drawing style: 1 Single line 2 Double line fg: Foreground character color bg: Background character color See also: DRAWBOX and DRAWHLINE. Usage: DRAWVLINE is useful for creating attractive screen displays in batch files. It detects other lines and boxes on the display, and creates the appropriate connector characters when possible (not all types of lines can be connected with the available characters). For example, to draw a double width line along the left margin of the display with bright red characters on a black background: drawvline 0 0 25 2 bright red on black The row and column values are zero-based, so on a standard 25 line by 80 column display, valid rows are 0 - 24 and valid columns are 0 - 79. The maximum row value is determined by the current height of the Take Command window. The maximum column value is determined by the current virtual screen width. DRAWVLINE checks for a valid row and column, and displays a "Usage" error message if either value is out of range. See Colors and Color Names for details about colors. DRAWVLINE uses the standard line and box drawing characters in the U.S. English extended ASCII character set. These characters are included in the English language versions of standard monospaced fonts typically available under OS/2 (e.g. Courier, System Monospaced, or System VIO). However, if your system is configured for a different font, character set (code page), or country, or you have replaced or modified the OS/2 default fonts, the line may not appear on your screen as you expect. ═══ 3.3.27. ECHO - Display a message ═══ Purpose: Display a message, enable or disable batch file or command-line echoing, or display the echo status. Format: ECHO [ON | OFF | message ] ECHOERR message message : Text to display. See also: ECHOS, SCREEN, SCRPUT, SETDOS and TEXT. Usage: Take Command has a separate echo capability for batch files and for the command line. The command-line ECHO state is independent of the batch file ECHO state; changing ECHO in a batch file has no effect on the display at the command prompt, and vice versa. To see the current echo state, use the ECHO command with no arguments. This displays either the batch file or command-line echo state, depending on where the ECHO command is performed. In a batch file, if you turn ECHO on, each line of the file is displayed before it is executed. If you turn ECHO off, each line is executed without being displayed. ECHO can also be used in a batch file to display a message on the screen. Regardless of the ECHO state, a batch file line that begins with the [@] character will not be displayed. To turn off batch file echoing, without displaying the ECHO command, use this line: @echo off ECHO commands in a batch file will send messages to the screen while the batch file executes, even if ECHO is set OFF. For example, this line will display a message in a batch file: echo Processing your print files... If you want to echo a blank line from within a batch file, enter: echo. You cannot use the command separator character [&], or the redirection symbols [| > <] in an ECHO message, unless you enclose them in quotes (see Argument Quoting) or precede them with the escape character. ECHO defaults to ON in batch files. The current ECHO state is inherited by called batch files. You can change the default setting to ECHO OFF with the SETDOS /V0 command or with the BatchEcho directive in the TCMDOS2.INI file. If you turn the command-line ECHO on, each command will be displayed before it is executed. This will let you see the command line after expansion of all aliases and variables. The command-line ECHO is most useful when you are learning how to use advanced features. This example will turn command-line echoing on: [c:\] echo on ECHO defaults to OFF at the command line. ECHOERR acts like ECHO but sends its output to the standard error device STDERR (usually the screen) instead of the standard output device. If the standard output of a batch file is redirected to a file or another device with >, ECHOERR will still generate a screen message. See Redirection and Piping for more information about the standard output and standard error devices and redirection. ═══ 3.3.28. ECHOS - Display a message with no CR/LF ═══ Purpose: Display a message without a trailing carriage return and line feed. Format: ECHOS message ECHOSERR message See also: ECHO, SCREEN, SCRPUT, TEXT, and VSCRPUT. Usage: ECHOS is useful for text output when you don't want to add a carriage return / linefeed pair at the end of the line. For example, you can use ECHOS when you need to redirect control sequences to your printer; this example sends the sequence Esc P to the printer on LPT1 (%= is translated to the Take Command escape character, and %=e to an ASCII Esc; see Escape Character and = for additional details): [c:\] echos %=eP > lpt1: You cannot use the command separator character [&] or the redirection symbols [| > <] in an ECHOS message, unless you enclose them in quotes (see Argument Quoting) or precede them with the escape character. ECHOS does not translate or modify the message text. For example, carriage return characters are not translated to CR/LF pairs. ECHOS sends only the characters you enter (after escape character and back quote processing). The only character you cannot put into an ECHOS message is the NUL character (ASCII 0). ECHOSERR acts like ECHOS but sends its output to the standard error device (usually the screen) instead of the standard output device. If the standard output of a batch file is redirected to a file or another device with >, ECHOSERR will still generate a screen message. See Redirection and Piping for more information about the standard output and standard error devices and redirection. ═══ 3.3.29. ENDLOCAL - Restore saved environment ═══ Purpose: Restore the saved disk drive, directory, environment, and alias list. Format: ENDLOCAL See also: SETLOCAL. Usage: The SETLOCAL command in a batch file saves the current disk drive, default directory, all environment variables, the alias list, and the command separator, escape character, parameter character, decimal separator, and thousands separator. ENDLOCAL restores everything that was saved by the previous SETLOCAL command. For example, this batch file fragment saves everything, removes all aliases so that user aliases will not affect batch file commands, changes the disk and directory, changes the command separator, runs a program, and then restores the original values: setlocal unalias * cdd d:\test setdos /c~ program ~ echo Done! endlocal SETLOCAL and ENDLOCAL are not nestable within a batch file. However, you can have multiple, separate SETLOCAL / ENDLOCAL pairs within a batch file, and nested batch files can each have their own SETLOCAL / ENDLOCAL. You cannot use SETLOCAL and ENDLOCAL in an alias or at the command line. An ENDLOCAL is performed automatically at the end of a batch file if you forget to do so. If you invoke one batch file from another without using CALL, the first batch file is terminated, and an automatic ENDLOCAL is performed; the second batch file inherits the settings as they were prior to any SETLOCAL. ═══ 3.3.30. ESET - Edit variable or alias ═══ Purpose: Edit environment variables and aliases. Format: ESET [/A] variable name... variable name : The name of an environment variable or alias to edit. /A(lias) See also: ALIAS, UNALIAS, SET, and UNSET. Usage: ESET allows you to edit environment variables and aliases using line editing commands (see Command-Line Editing). For example, to edit the executable file search path: [c:\] eset path path=c:\;c:\dos;c:\util To create and then edit an alias: [c:\] alias d = dir /d/j/p [c:\] eset d d=dir /d/j/p ESET will search for environment variables first and then aliases. If you have an environment variable and an alias with the same name, ESET will edit the environment variable and ignore the alias unless you use the /A option. Environment variable and alias names are normally limited to 80 characters, and their contents to 1,023 characters. However, if you use special techniques to create a longer environment variable, ESET will edit it provided the variable contains no more than 2,047 characters of text. If you have enabled global aliases (see ALIAS), any changes made to an alias with ESET will immediately affect all other copies of Take Command which are using the same alias list. Option: /A (Alias) Edit the named alias even if an environment variable of the same name exists. If you have an alias and an environment variable with the same name, you must use this switch to be able to edit the alias. ═══ 3.3.31. EXCEPT - Exclude files from command ═══ Purpose: Perform a command on all available files except those specified. Format: EXCEPT (file ) command file : The file or files to exclude from the command. command : The command to execute, including all appropriate arguments and switches. See also: ATTRIB and File Exclusion Ranges. File Selection: Supports extended wildcards, ranges, multiple file names, and include lists. Ranges must appear immediately after the EXCEPT keyword. Usage: EXCEPT provides a means of executing a command on a group of files and/or subdirectories, and excluding a subgroup from the operation. The command can be an internal command or alias, an external command, or a batch file. You may use wildcards to specify the files to exclude from the command. The first example erases all the files in the current directory except those beginning with MEMO, and those whose extension is .WKS. The second example copies all the files and subdirectories on drive C to drive D except those in C:\MSC and C:\DOS, using the COPY command: [c:\] except (memo*.* *.wks) erase *.* [c:\] except (c:\msc c:\dos) copy c:\*.* d:\ /s When you use EXCEPT on a HPFS drive, you must quote any file names inside the parentheses which contain whitespace or special characters. EXCEPT prevents operations on the specified file(s) by setting the hidden attribute, performing the command, and then clearing the hidden attribute. If the command is aborted in an unusual way, you may need to use the ATTRIB command to remove the hidden attribute from the file(s). Caution: EXCEPT will not work with programs or commands that ignore the hidden attribute or which work explicitly with hidden files, including DEL /Z, and the /H (process hidden files) switch available in some Take Command file processing commands. File exclusion ranges provide a faster and more flexible method of excluding files from internal commands, and do not manipulate file attributes, as EXCEPT does. However, exclusion ranges can only be used with internal commands; you must use EXCEPT for external commands. Date, time,and size ranges can be used immediately after the word EXCEPT to further qualify which files should be excluded from the command. If the command is an internal command that supports ranges, an independent range can also be used in the command itself. You can also use a file exclusion range within the EXCEPT command; however, this will select files to be excluded from EXCEPT, and therefore included in execution of the command. You can use command grouping to execute multiple commands with a single EXCEPT. For example, the following command copies all files in the current directory whose extensions begin with .DA, except the .DAT files, to the D:\SAVE directory, then changes the first two characters of the extension of the copied files to .SA: [c:\data] except (*.dat) (copy *.da* d:\save & ren *.da* *.sa*) If you use filename completion to enter the filenames inside the parentheses, type a space after the open parenthesis before entering a partial filename or pressing Tab. Otherwise, the command-line editor will treat the open parenthesis as the first character of the filename to be completed. ═══ 3.3.32. EXIT - Exit Take Command ═══ Purpose: Exit the current Take Command session. Format: EXIT [value ] value : The exit code to return. Usage: EXIT terminates the current copy of Take Command. To close the session, or to return to the application that started Take Command, type: [c:\] exit If you specify a value, EXIT will return that value to the program that started Take Command. For example: [c:\] exit 255 The value is a number you can use to inform the program of some result, such as the success or failure of a batch file. It can range from 0 - 4,294,967,295. ═══ 3.3.33. FFIND - Search for files or text ═══ Purpose: Search for files by name or contents. Format: FFIND [/A:[[-]rhsda] /B /C /D[list] /E /I /K /L /M /O[[:][-]adeginrsu] /P /R /S /[ T | X ]"xx" /V file... list : A list of disk drive letters (without colons). file : The file, directory, or list of files or directories to display. /A(ttribute select) /M (no footers) /B(are) /O(rder) /C(ase sensitive) /P(ause) /D(rive) /R(everse) /E (upper case display) /S(ubdirectories) /I(gnore wildcards) /T(ext search string) /K (no headers) /V(erbose) /L(ine numbers) /X["xx"] (hex display/search string) File Selection: Supports extended wildcards, ranges, multiple file names, and include lists. Usage: FFIND is a flexible search command that looks for files based on their names and their contents. Depending on the options you choose, FFIND can display filenames, matching text, or a combination of both in a variety of formats. Most of the functions provided by FFIND are also available in the Find Files / Text dialog, accessible from the Utilities menu. You can use the FFIND command, the dialog, or both, depending on your needs. If you want to search for files by name, FFIND works much like the DIR command. For example, to generate a list of all the .BTM files in the current directory, you could use the command [c:\] ffind *.btm The output from this command is a list of full pathnames, followed by the number of files found. If you want to limit the output to a list of *.BTM files which contain the string color, you could use this command instead: [c:\] ffind /t"color" *.btm The output from this command is a list of files that contain the string color along with the first line in each file that contains that string. By default, FFIND uses a case-insensitive search, so the command above will include files that contain COLOR, Color, color, or any other combination of upper-case and lower-case letters. If you would rather see the last line of each file that contains the search string, use the /R option, which forces FFIND to search from the end of each file to the beginning. This option will also speed up searches somewhat if you are looking for text that will normally be at the end of a file, such as a signature line: [c:\] ffind /r /t"Sincerely," *.txt You can use Take Command's extended wildcards in the search string to increase the flexibility of FFIND's search. For example, the following command will find .TXT files which contain either the string June or July (it will also find Juny and Jule). The /C option makes the search case-sensitive: [c:\] ffind /c/t"Ju[nl][ey]" *.txt If you want to search for text that contains wildcard characters (*, ?, [, or ]), you can use the /I option to force FFIND to interpret these as normal characters instead of wildcards. The following command, for example, finds all .TXT files that contain a question mark: [c:\] ffind /i/t"?" *.txt At times, you may need to search for data that cannot be represented by ASCII characters. You can use FFIND's /X option to represent the search string in hexadecimal format (this option also changes the output to show hexadecimal offsets rather than text lines). With /X, the search must be represented by pairs of hexadecimal digits separated by spaces; a search of this type is always case-sensitive (in the example below, 41 63 65 is the hex code for "Ace"): [c:\] ffind /b"41 63 65" *.txt You can use FFIND's other options to further specify the files for which you are searching and to modify the way in which the output is displayed. When you use FFIND on an HPFS drive, you must quote any file names which contain whitespace or special characters. Options: /A: (Attribute select) Select only those files that have the specified attribute(s) set. Preceding the attribute character with a hyphen [-] will select files that do not have that attribute set. The colon [:] after /A is required. The attributes are: R Read-only H Hidden S System D Subdirectory A Archive If no attributes are listed at all (e.g., FFIND /A: ...), FFIND will select all files and subdirectories including hidden and system files. If attributes are combined, all the specified attributes must match for a file to be selected. For example, /A:RHS will select only those files with all three attributes set. /B (Bare) Display file names only and omit the text that matches the search. This option is only useful in combination with /T or /X, which normally force FFIND to display file names and matching text. /C (Case sensitive) Perform a case-sensitive search. This option is only valid with /T, which defaults to a case-insensitive search. It is not needed with a /X hexadecimal search, which is always case-sensitive. /D (Drive) Search all files on one or more drives. If you use /D without a list of drives, FFIND will search the drives specified in the list of files. If no drive letters are listed, FFIND will search all of the current drive. You can include a list of drives or a range of drives to search as part of the /D option. For example, to search drives C:, D:, E:, and G:, you can use either of these commands: [c:\] ffind /dcdeg ... [c:\] ffind /dc-eg ... Drive letters listed after /D will be ignored when processing file names which also include a drive letter. For example, this command displays all the .BTM files on C: and E:, but only the .BAT files on D: [c:\] ffind /s /dce *.btm d:\*.bat /E Display filenames in the traditional upper case; also see SETDOS /U and the UpperCase directive in TCMDOS2.INI. /I (Ignore wildcards) Only meaningful when used in conjunction with the /T "text" option. Suppresses the recognition of wildcard characters in the search text. This option is useful if you need to search for characters that would normally be interpreted as wildcards: *, ?, [, and ]. /K (No headers) Suppress the display of the header or filename for each matching text line. /L: (Line numbers) Include the line number for each text line displayed. FFIND numbers lines beginning with 1, unless ListRowStart is set to 0 in TCMDOS2.INI. A new line is counted for every CR or LF character (FFIND determines automatically which character is used for line breaks in each file), or when line length reaches 511 characters, whichever comes first. /M (No footers) Suppress the footer (the number of files and number of matches) at the end of FFIND's display. /O (Order) Set the sorting order. You may use any combination of the following sorting options; if multiple options are used, the listing will be sorted with the first sort option as the primary key, the next as the secondary key, and so on: - Reverse the sort order for the next option a Sort in ASCII order, not numerically, when there are digits in the name d Sort by date and time (oldest first); for HPFS drives also see /T e Sort by extension g Group subdirectories first, then files i Sort by file description (ignored if /C or /O:c is used) n Sort by filename (this is the default) r Reverse the sort order for all options s Sort by size u Unsorted /P (Pause) Wait for a key to be pressed after each screen page before continuing the display. Your options at the prompt are explained in detail under Page and File Prompts. /R (Reverse search) Only meaningful when used in conjunction with the /T "text" or /X options. Searches each file from the end backwards to the beginning. This option is useful if you want to display the last occurrence of the search string in each file instead of the first (the default). It may also speed up searches for information that is normally at the end of a file, such as a signature. /S (Subdirectories) Display matches from the current directory and all of its subdirectories. /T"text"(Text search) Specify the text search string. /T must be followed by a text string in double quotes (e.g., /t"color"). FFIND will perform a case- insensitive search unless you also use the /C option. For a hexadecimal search and/or hexadecimal display of the location where the search string is found, see /X. You can specify a search string with either /T or /X, but not both. /V (Verbose) Show every matching line. FFIND's default behavior is to show only the first matching line then and then go on to the next file. This option is only valid with /T or /X. /X["xx"](Hexadecimal display / search) Specify hexadecimal display and an optional hexadecimal search string. If /X is followed by one or more pairs of hexadecimal digits in quotes (e.g., /x"44 63 65"), FFIND will search for that exact sequence of characters or data bytes without regard to the meaning of those bytes as text. If those bytes are found, the offset is displayed (in both decimal and hexadecimal). A search of this type will always be case-sensitive. If /X is not followed by a hexadecimal search string it must be used in conjunction with /T, and will change the output format to display offsets (in both decimal and hexadecimal) rather than actual text lines when the search string is found. For example, this command uses /T to display the first line in each .BTM file containing the word hello: [c:\] ffind /t"hello" *.btm ---- c:\test.btm: echo hello 1 line in 1 file If you use the same command with /X, the offset is displayed instead of the text: [c:\] ffind /t"hello" /x *.btm ---- c:\test.btm: Offset: 26 (1Ah) 1 line in 1 file You can specify a search string with either /T or /X, but not both. ═══ 3.3.34. FOR - Repeat a command ═══ Purpose: Repeat a command for several values of a variable. Format: FOR [/A:[[-]rhsda] /F["options"] /H /L /R [path]] %var IN ([@] set | start, step, end) [DO] command ... options : Parsing options for a "file parsing" FOR. path : The starting directory for a "recursive" FOR. %var : The variable to be used in the command ("FOR variable"). set : A set of values for the variable. start : The starting value for a "counted" FOR. step : The increment value for a "counted" FOR. end : The limit value for a "counted" FOR. command : A command or group of commands to be executed for each value of the variable. /A: (Attribute select) /L (counted loop) /F(ile parsing) /R(ecursive) /H(ide dots) File Selection: Supports extended wildcards, ranges, multiple file names, and include lists. Ranges must appear immediately after the FOR keyword. Usage: FOR begins by creating a set. It then executes a command for every member of the set. The command can be an internal command, an alias, an external command, or a batch file. The members of the set can be a list of file names, text strings, a group of numeric values, or text read from a list of files. When the set is made up of text or several separate file names (not an include list), the elements must be separated by spaces, tabs, commas, or the switch character (normally a slash [/]). FOR includes a large number of options, some of which duplicate functions available in other commands, and / or do not follow conventions you may find in our other commands. Most of these extra options are included for compatibility with Windows NT 4.0's CMD.EXE. However, we make them available in all three of our products so that aliases and batch files which use them can work under all products. The first three sections below (Working with Files, Working with Text, and Retrieving Text from Files) describe the traditional FOR command and the enhancements to it which are part of Take Command. The sections on Parsing Text from Files and Counted FOR Loops describe features added for compatibility with Windows NT 4.0. The section entitled Other Notes contains information you may need if you use any aspect of the FOR command extensively. Working with Files Normally, the set is a list of files specified with wildcards. For example, if you use this line in a batch file: for %x in (*.txt) do list %x then LIST will be executed once for each file in the current directory with the extension .TXT. The FOR variable %x is set equal to each of the file names in turn, then the LIST command is executed for each file. (You could do the same thing more easily with a simple LIST *.TXT. We used FOR here so you could get a feel for how it operates, using a simple example. Many of the examples in this section are constructed in the same way.) The set can include multiple files or an include list, like this: for %x in (d:\*.txt;*.doc;*.asc) do type %x FOR supports wildcards and extended wildcards, as well as extended parent directory names (e.g., ...\*.txt to process all of the .TXT files that are contained in the directory 2 levels above the current directory). When you use FOR on a HPFS drive, you must quote any file names within the set which contain whitespace or special characters. The same restriction applies to names returned in the FOR variable, if you pass them to internal commands, or other commands which require quoting filenames with whitespace. FOR does not quote returned names automatically, even if you included quotes in the set. If the set includes filenames, the file list can be further refined by using date, time, size and file exclusion ranges. The range or ranges must be placed immediately after the word FOR. Ranges will be ignored if no wildcards are used inside the parentheses. For example, this set is made up of all of the *.TXT files that were created or updated on October 4, 1997: for /[d10-4-97,+0] %x in (*.txt) do ... If the command is an internal command that supports ranges, an independent range can also be used in the command itself. You can also refine the list by limiting it with the /A: option to select only files that have specific attributes. By default, FOR works only with files in the current directory or a specified directory. With the /R option, FOR will also search for files in subdirectories. For example, to work with all of the .TXT files in the current directory and its subdirectories: for /r %x in (*.txt) do ... If you specify a directory name immediately after /R, FOR will start in that directory and then search each of its subdirectories. This example works with all of the .BAK files on drive D: for /r d:\ %x in (*.bak) do ... When you use wildcards to specify the set, FOR scans the directory and finds each file which matches the wildcard name(s) you specified. If, during the processing of the FOR command, you create a file that could be included in the set, it may or may not appear in a future iteration of the same FOR command. Whether the new file appears depends on its physical location in the directory structure. For example, if you use FOR to execute a command for all .TXT files, and the command also creates one or more new .TXT files, those new files may or may not be processed during the current FOR command, depending on where they are placed in the physical structure of the directory. This is an operating system constraint over which Take Command has no control. Therefore, in order to achieve consistent results you should construct FOR commands which do not create files that could become part of the set for the current command. Working with Text The set can also be made up of text instead of file names. For example, to create three files named file1, file2, and file3, each containing a blank line: for %suffix in (1 2 3) do echo. > file%suffix You could also use the names of environment variables as the text. This example displays the name and content of several variables from the environment (see Environment Variables and Functions for details on the use of square brackets when expanding environment variables). Enter this on one line: for %var in (path prompt comspec) do echo %var=%[%var] Retrieving Text from Files FOR can extract text from files in two different ways. The first method extracts each line from each file in the set and places it in the variable. To use this method, place an [@] at the beginning of the set, in front of the file name or names. For example, if you have a file called DRIVES.TXT that contains a list of drives on your computer, one drive name per line (with a ":" after each drive letter), you can print the free space on each drive this way: for %d in (@drives.txt) do free %d > prn Because the [@] is also a valid filename character, FOR first checks to see if the file exists with the [@] in its name (i.e., a file named @DRIVES.TXT). If so, the filename is treated as a normal argument. If it doesn't exist, FOR uses the filename (without the [@]) as the file from which to retrieve text. If you use @CON as the filename, FOR will read from standard input (a redirected input file) or from a pipe (see Redirection and Piping for more information). IF you use @CLIP: as the filename, FOR will read any text available from the OS/2 clipboard. Parsing Text from Files The second method of working with text from files is to have FOR parse each line of each file for you. To begin a "file-parsing" FOR, you must use the /F option and then include one or more file names in the set. When you use this form of FOR, the variable must be a single letter, for example, %a. This method of parsing, included for compatibility with Windows NT 4.0's CMD.EXE, can be cumbersome and inflexible. For a more powerful method, use FOR with @filename as the set to retrieve each line from the file, as described in the previous section. Then use variable functions like @INSTR, @LEFT, @RIGHT, and @WORD to parse the line. By default, FOR will extract the first word or token from each line and return it in the variable. For example, to display the first word on each line in the file FLIST.TXT: for /f %a in (flist.txt) do echo %a You can control the way FOR /F parses each line by specifying one or more parsing options in a quoted string immediately after the /F. The available options are: skip=n: FOR /F will skip "n" lines at the beginning of each file before parsing the remainder of the file. tokens=n, m, ...:By default, FOR /F returns just the first word or "token" from each parsed line in the variable you named. You can have it return more than one token in the variable, or return tokens in several variables, with this option. This option is followed by a list of numbers separated by commas. The first number tells FOR /F which token to return in the first variable, the second number tells it which to return in the second variable, etc. The variables follow each other alphabetically starting with the variable you name on the FOR command line. This example returns the first word of each line in each text file in %d, the second in %e, and the third in %f: for /f "tokens=1,2,3" %d in (*.txt) do ... You can also indicate a range of tokens by separating the numbers with a hyphen [-]. This example returns the first word of each line in %p, the second through fifth words in %q, and the eighth word in %r: for /f "tokens=1,2-5,8" %p in (*.txt) do ... To return the rest of the line in a variable, use a range that ends with a number higher than the last token in any line, such as 999. This final example returns the first word of each line in %a and the remainder of each line (assuming that no line has more than 999 words!) in %b: for /f "tokens=1,2-999" %a in (*.txt) do ... eol=c: If FOR /F finds the character "c" in the line, it will assume that the character and any text following it are part of a comment and ignore the rest of the line. delims=xxx..:By default, FOR /F sees spaces and tabs as word or token delimiters. This option replaces those delimiters with all of the characters following the equal sign to the end of the string. This option must therefore be the last one used in the quoted options string. You can also use FOR /F to parse a single string instead of each line of a file by using the string, in quotes, as the set. For example, this command will assign variable A to the string "this", B to "is", etc., then display "this" (enter the command on one line): for /f "tokens=1,2,3,4" %a in ("this is a test") do echo %a "Counted" FOR Loop The "counted FOR" loop is included only for compatibility with Windows NT 4.0's CMD.EXE. In most cases, you will find the DO command more useful for performing counted loops. In a counted FOR command, the set is made up of numeric values instead of text or file names. To begin a counted FOR command, you must use the /L option and then include three values, separated by commas, in the set. These are the start, step, and end values. During the first iteration of the FOR loop, the variable is set equal to the start value. Before each iteration, the variable is increased by the step value. The loop ends when the variable exceeds the end value. This example will print the numbers from 1 to 10: for /l %val in (1,1,10) do echo %val This example will print the odd numbers from 1 to 10 (1, 3, 5, 7, and 9): for /l %val in (1,2,10) do echo %val The step value can be negative. If it is, the loop will end when the variable is less than the end value. Other Notes You can use either % or %% in front of the variable name. Either form will work, whether the FOR command is typed from the command line or is part of an alias or batch file (some traditional command processors require a single % if FOR is used at the command line, but require %% if FOR is used in a batch file). The variable name can be up to 80 characters long. The word DO is optional. If you use a single-character FOR variable name, that name is given priority over any environment variable which starts with the same letter, in order to maintain compatibility with the traditional FOR command. For example, the following command tries to add a: and b: to the end of the PATH, but will not work as intended: [c:\] for %p in (a: b:) do path %path;%p The "%p" in "%path" will be interpreted as the FOR variable %p followed by the text "ath", which is not what was intended. To get around this, use a different letter or a longer name for the FOR variable, or use square brackets around the variable name seeThe Environment. The following example uses FOR with variable functions to delete the .BAK files for which a corresponding .TXT file exists in the current directory: [c:\docs] for %file in (*.txt) do del %@name[%file].bak The above command would not work properly on a HPFS drive, because the returned FILE variable might contain whitespace. To correct this problem, you would need two sets of quotes, one for DEL and one for %@NAME: [c:\docs] for %file in (*.txt) do del "%@name["%file"].bak" You can use command grouping to execute multiple commands for each element in the set. For example, the following command copies each .WKQ file in the current directory to the D:\WKSAVE directory, then changes the extension of each file in the current directory to .SAV: [c:\text] for %file in (*.wkq) do (copy %file d:\wksave\ & ren %file *.sav) In a batch file you can use GOSUB to execute a subroutine for every element in the set. Within the subroutine, the FOR variable can be used just like any environment variable. This is a convenient way to execute a complex sequence of commands for every element in the set without CALLing another batch file. One unusual use of FOR is to execute a collection of batch files or other commands with the same parameter. For example, you might want to have three batch files all operate on the same data file. The FOR command could look like this: [c:\] for %cmd in (filetest fileform fileprnt) do %cmd datafile This line will expand to three separate commands: filetest datafile fileform datafile fileprnt datafile The variable that FOR uses (the %CMD in the example above) is created in the environment and then erased when the FOR command is done. For compatibility with COMMAND.COM and CMD.EXE, a single- character FOR variable is created in a special way that does not overwrite an existing environment variable with the same name. When using a multi- character variable name you must be careful not to use the name of one of your environment variables as a FOR variable. For example, a command that begins [c:\] for %path in ... will write over your current path setting, then erase the path variable completely when FOR is done. FOR statements can be nested. Options: /A: (Attribute select) Select only those files that have the specified attribute(s) set. /A: will be used only when processing wildcard file names in the set. It will be ignored for filenames without wildcards or other items in the set. Preceding the attribute character with a hyphen [-] will select files that do not have that attribute set. The colon [:] after /A is required. The attributes are: R Read-only H Hidden S System D Subdirectory A Archive If no attributes are listed (e.g., FOR /A:...), FOR will process all files including hidden and system files. If attributes are combined, all the specified attributes must match for a file to be included. For example, /A:RHS will include only those files with all three attributes set. For example, to process only those files with the archive attribute set: for /a:a %f in (*.*) echo %f needs a backup! /F (File parsing) Return one or more words or tokens from each line of each file in the set. The /F option can be followed by one or more options in a quoted string which control how the parsing is performed. See the details under Parsing Text From Files, above. /H (Hide dots) Suppress the assignment of the "." and ".." directories to the FOR variable. /L (counted loop) Interpret the three values in the set as the start, step, and end values of a counted loop. See the details under Counted FOR Loop, above. /R (Recursive) Look in the current directory and all of its subdirectories for files in the set. If the /R is followed by a directory name, look for files in that directory and all of its subdirectories. ═══ 3.3.35. FREE - Display total and free disk space ═══ Purpose: Display the total disk space, total bytes used, and total bytes free on the specified (or default) drive(s). Format: FREE [drive: ... ] drive : One or more drives to include in the report. See also: MEMORY. Usage: FREE provides the same disk information as the external command CHKDSK, but without the wait, since it does not check the integrity of the file and directory structure of the disk. A colon [:] is required after each drive letter. This example displays the status of drives A and C: [c:\] free a: c: If the volume serial number is available, it will appear after the drive label or name. ═══ 3.3.36. GLOBAL - Execute command in all subdirectories ═══ Purpose: Execute a command in the current directory and its subdirectories. Format: GLOBAL [/H /I /P /Q] command command : The command to execute, including arguments and switches. /H(idden directories) /P(rompt) /I(gnore exit codes) /Q(uiet) Usage: GLOBAL performs the command first in the current directory and then in every subdirectory under the current directory. The command can be an internal command, an alias, an external command, or a batch file. This example copies the files in every directory on drive A to the directory C:\TEMP: [a:\] global copy *.* c:\temp If you use the /P option, GLOBAL will prompt for each subdirectory before performing the command. You can use this option if you want to perform the command in most, but not all subdirectories of the current directory. You can use command grouping to execute multiple commands in each subdirectory. For example, the following command copies each .TXT file in the current directory and all of its subdirectories to drive A. It then changes the extension of each of the copied files to .SAV: [c:\] global (copy *.txt a: & ren *.txt *.sav) Options: /H (Hidden directories) Forces GLOBAL to look for hidden directories. If you don't use this switch, hidden directories are ignored. /I (Ignore exit codes) If this option is not specified, GLOBAL will terminate if the command returns a non-zero exit code. Use /I if you want command to continue in additional subdirectories even if it returns an error in one subdirectory. Even if you use /I, GLOBAL will normally halt execution if Take Command receives a Ctrl-C or Ctrl-Break. /P (Prompt) Forces GLOBAL to prompt with each directory name before it performs the command. Your options at the prompt are explained in detail under Page and File Prompts. /Q (Quiet) Do not display the directory names as each directory is processed. ═══ 3.3.37. GOSUB - Call subroutine ═══ Purpose: Execute a subroutine in the current batch file. Format: GOSUB label label : The batch file label at the beginning of the subroutine. See also: CALL, GOTO and RETURN. Usage: GOSUB can only be used in batch files. Take Command allows subroutines in batch files. A subroutine must start with a label (a colon [:] followed by a label name) which appears on a line by itself. Case differences are ignored when matching labels. Labels may be one or more words long. The subroutine must end with a RETURN statement. The subroutine is invoked with a GOSUB command from another part of the batch file. After the RETURN, processing will continue with the command following the GOSUB command. For example, the following batch file fragment calls a subroutine which displays the directory and returns: echo Calling a subroutine gosub subr1 echo Returned from the subroutine quit :subr1 dir /a/w return GOSUB begins its search for the label on the next line of the batch file (after the GOSUB command). If the label is not found between the current position and the end of the file, GOSUB will restart the search at the beginning of the file. If the label still is not found, the batch file is terminated with the error message "Label not found." GOSUB saves the IFF and DO states, so IFF and DO statements inside a subroutine won't interfere with statements in the part of the batch file from which the subroutine was called. Subroutines can be nested. ═══ 3.3.38. GOTO - Branch within batch file ═══ Purpose: Branch to a specified line inside the current batch file. Format: GOTO [/I] label label : The batch file label to branch to. /I(FF and DO continue) See also: GOSUB. Usage: GOTO can only be used in batch files. After a GOTO command in a batch file, the next line to be executed will be the one immediately after the label. The label must begin with a colon [:] and appear on a line by itself. The colon is required on the line where the label is defined, but is not required in the GOTO command itself. Case differences are ignored when matching labels. Labels may be one or more words long. This batch file fragment checks for the existence of the file CONFIG.OS2. If the file exists, the batch file jumps to C_EXISTS and copies all the files from the current directory to the root directory on A:. Otherwise, it prints an error message and exits. if exist config.os2 goto C_EXISTS echo CONFIG.OS2 doesn't exist - exiting. quit :C_EXISTS copy *.* a:\ GOTO begins its search for the label on the next line of the batch file (after the GOTO command). If the label is not found between the current position and the end of the file, GOTO will restart the search at the beginning of the file. If the label still is not found, the batch file is terminated with the error message "Label not found." To avoid errors in the processing of nested statements and loops, GOTO cancels all active IFF statements and DO / ENDDO loops unless you use /I. This means that a normal GOTO (without /I) may not branch to any label that is between an IFF and the corresponding ENDIFF or between a DO and the corresponding ENDDO. For compatibility with Windows NT's CMD.EXE, the command GOTO :EOF will end processing of the current batch file if the label :EOF does not exist. However, this is less efficient than using the QUIT or CANCEL command to end a batch file. Options: /I (IFF and DO continue) Prevents GOTO from canceling IFF statements and DO loops. Use this option only if you are absolutely certain that your GOTO command is branching entirely within any current IFF statement and any active DO / ENDDO block. Using /I under any other conditions will cause an error later in your batch file. You cannot branch into another IFF statement, another DO loop, or a different IFF or DO nesting level, whether you use the /I option or not. If you do, you will eventually receive an "unknown command" error (or execution of the UNKNOWN_CMD alias) on a subsequent ENDDO, ELSE, ELSEIFF, or ENDIFF statement. ═══ 3.3.39. HELP - Call online help ═══ Purpose: Display help for internal commands, and optionally for external commands. Format: HELP [topic ] topic : A help topic or internal command. Usage: Online help is available for Take Command. The Take Command help system uses the OS/2 help facility. See The Take Command Help System for detailed information about getting help at the command line and customizing Help for your system. If you type the command HELP by itself (or press F1 when the command line is empty), the table of contents is displayed. If you type HELP plus a topic name, that topic is displayed. For example: help copy displays information about the COPY command and its options. You can configure the HELP command to display only the Take Command help (the default), or to display other help "books" as well. For details see the HelpBook directive and your Introduction and Installation Guide. For help on system errors enter the message number in the HELP command, for example: help 3 help sys0003 Take Command will invoke OS/2's HELPMSG program to process these requests, and HELPMSG will display any available information on the message number given. In order for HELPMSG to work properly with Take Command you must define it as a 'TTY' application; see Starting Character-Mode Applications for details. ═══ 3.3.40. HISTORY - Manage command history list ═══ Purpose: Display, add to, clear, or read the history list. Format: HISTORY [/A command /F /P /R filename ] command : A command to be added to the history list. filename : The name of a file containing entries to be added to the history list. /A(dd) /P(ause) /F(ree) /R(ead) See also: DIRHISTORY and LOG. Usage: Take Command keeps a list of the commands you have entered on the command line. See Command History and Recall for additional details. The HISTORY command lets you view and manipulate the command history list directly. If no parameters are entered, HISTORY will display the current command history list: [c:\] history With the options explained below, you can clear the list, add new commands to the list without executing them, save the list in a file, or read a new list from a file. The number of commands saved in the history list depends on the length of each command line. The history list size can be specified at startup from 256 to 32767 characters (see the History directive). The default size is 1024 characters. Your history list can be stored either locally (a separate history list for each copy of Take Command) or globally (all copies of Take Command share the same list). For full details see the discussion of local and global history lists under Command History and Recall. You can use the HISTORY command as an aid in writing batch files by redirecting the HISTORY output to a file and then editing the file appropriately. However, it is easier to use the LOG /H command for this purpose. You can disable the history list or specify a minimum command-line length to save from the Command Line 1 page of the configuration notebook, or with the HistMin directive in the TCMDOS2.INI file. You can save the history list by redirecting the output of HISTORY to a file. This example saves the command history to a file called HISTFILE and reads it back again immediately. If you leave out the HISTORY /F command on the second line, the contents of the file will be appended to the current history list instead of replacing it: [c:\] history > histfile [c:\] history /f [c:\] history /r histfile If you need to save your command history at the end of each day's work, you might use the first of these commands in your TCSTART.BTM or other startup file, and the second in TCEXIT.BTM: if exist c:\histfile history /r c:\histfile history > c:\histfile This restores the previous history list if it exists, and saves the history when Take Command exits. Options: /A (Add) Add a command to the history list. This performs the same function as the Ctrl-K key at the command line (see Command History and Recall ). /F (Free) Erase all entries in the command history list. /P (Prompt) Wait for a key after displaying each page of the list. Your options at the prompt are explained in detail under Page and File Prompts. /R (Read) Read the command history from the specified file and append it to the history list currently held in memory. Each line in the file must fit within the command-line length limit). If you are creating a HISTORY /R file by hand, and need to create an entry that spans multiple lines in the file, you can do so by terminating each line, except the last, with an escape character. However, you cannot use this method to exceed the command- line length limit. ═══ 3.3.41. IF - Test condition ═══ Purpose: Execute a command if a condition or set of conditions is true. Format: IF [NOT] condition [.AND. | .OR. | .XOR. [NOT] condition ...] command condition : A test to determine if the command should be executed. command : The command to execute if the condition is true. See also: IFF and @IF. Usage: IF is normally used only in aliases and batch files. It is always followed by one or more conditions and then a command. First, the conditions are evaluated. If they are true, the command is executed. Otherwise, the command is ignored. If you add a NOT before a condition, the command is executed only when the condition is false. You can link conditions with .AND., .OR., or .XOR., and you can group conditions with parentheses (see Combining Tests below). You can also nest IF statements. The conditions can test strings, numbers, the existence of a file or subdirectory, the exit code returned by the preceding external command, and the existence of aliases and internal commands. The command can be an alias, an internal command, an external command, or a batch file. The entire IF statement, including all conditions and the command, must fit on one line. Some examples of IF conditions and commands are included below; additional examples can be found in the EXAMPLES.BTM file which came with Take Command. You can use command grouping to execute multiple commands if the condition is true. For example, the following command tests if any .TXT files exist. If they do, they are copied to drive A: and their extensions are changed to .TXO: if exist *.txt (copy *.txt a: & ren *.txt *.txo) (Note that the IFF command provides a more structured method of executing multiple commands if a condition or set of conditions is true.) When an IF test fails, the remainder of the command is discarded, and the command processor normally continues with the next command on the line, or the next line. This behavior is not compatible with CMD.EXE, which discards all remaining commands on the line when an IF test fails, including those after a command separator or pipe character. To change the behavior so that IF affects all commands on the line, as in CMD.EXE, set DuplicateBugs to Yes in the TCMDOS2.INI file. For example, if DuplicateBugs is set to Yes (the default), the following command will display nothing, because the second ECHO command is discarded along with the first when the condition fails. If DuplicateBugs is set to No, it will display "hello": [c:\] if 1 == 2 echo Wrong! & echo hello Conditions The conditional tests listed in the following sections are available in both the IF and IFF commands. They fit into two categories: string and numeric tests, and status tests. The tests can use environment variables, internal variables and variable functions, file names, literal text, and numeric values as their arguments. String and Numeric Tests Six test conditions can be used to test character strings. The same conditions are available for both numeric and normal text strings (see below for details). In each case you enter the test as: string1 operator string2 The operator defines the type of test (equal, greater than or equal, and so on). You should always use spaces on both sides of the operator. The operators are: EQ or == string1 equal to string2 NE or != string1 not equal to string2 LT string1 less than string2 LE string1 less than or equal to string2 GE string1 greater than or equal to string2 GT string1 greater than string2 When IF compares two character strings, it will use either a numeric comparison or a string comparison. A numeric comparison treats the strings as numeric values and tests them arithmetically. A string comparison treats the strings as text. The difference between numeric and string comparisons is best explained by looking at the way two values are tested. For example, consider comparing the values 2 and 19. Numerically, 2 is smaller, but as a string it is "larger" because its first digit is larger than the first digit of 19. So the first of these conditions will be true, and the second will be false: if 2 lt 19 ... if "2" lt "19" ... IF determines which kind of test to do by examining the first character of each string. If both strings begin with a numeric character (a digit, sign, or decimal point), a numeric comparison is used. (If a string begins with a decimal separator it is not considered numeric unless the next character is a digit, and there are no more decimal separators within the string. For example, ".07" is numeric, but ".a" and ".07.01" are not.) If either value is non-numeric, a string comparison is used. To force a string comparison when both values are or may be numeric, use double quotes around the values you are testing, as shown above. Because the double quote is not a numeric character, IF performs a string comparison. Case differences are ignored in string comparisons. If two strings begin with the same text but one is shorter, the shorter string is considered to be "less than" the longer one. For example, "a" is less than "abc", and "hello_there" is greater than "hello". When you compare text strings, you should always enclose the arguments in double quotes in order to avoid syntax errors which may occur if one of the argument values is empty. Numeric comparisons work with both integer and decimal values. The values to be compared must contain only numeric digits, decimal points, and an optional sign (+ or -). The number may may contain up to 16 digits to the left of the decimal point, and 8 digits to the right. Internal variables and variable functions are very powerful when combined with string and numeric comparisons. They allow you to test the state of your system, the characteristics of a file, date and time information, or the result of a calculation. You may want to review the variables and variable functions when determining the best way to set up an IF test. This batch file fragment runs a program called WEEKLY if today is Monday: if "%_dow" == "mon" weekly This batch file fragment tests for a string value: input "Enter your selection : " %%cmd if "%cmd" == "WP" goto wordproc if "%cmd" NE "GRAPHICS" goto badentry This example calls GO.BTM if the first two characters in the file MYFILE are "GO": if "%@left[2,%@line[myfile,0]]" == "GO" call go.btm Status Tests These conditions test the system or command processor status. You can use internal variables and variable functions to test many other parts of the system status. ERRORLEVEL [operator] n This test retrieves the exit code of the preceding external program. By convention, programs return an exit code of 0 when they are successful and a number between 1 and 255 to indicate an error (depending on the program you are running, the maximum return value may be larger). The condition can be any of the operators listed above (EQ, !=, GT, etc.). If no operator is specified, the default is GE. The comparison is done numerically. Not all programs return an explicit exit code. For programs which do not, the behavior of ERRORLEVEL is undefined. EXIST filename If the file exists, the condition is true. You can use wildcards in the filename, in which case the condition is true if any file matching the wildcard name exists. ISALIAS aliasname If the name is defined as an alias, the condition is true. ISDIR | DIREXIST path If the subdirectory exists, the condition is true. For compatibility with Novell DOS / OpenDOS, DIREXIST may be used as a synonym for ISDIR. ISINTERNAL command If the specified command is an active internal command, the condition is true. Commands can be activated and deactivated with the SETDOS /I command. ISLABEL label If the specified batch file label exists, the condition is true. Labels may be one or more words long. ISWINDOW "title" If the window with the title exists, the condition is true. Double quotes must be used around the title, which may contain wildcards and extended wildcards. The first batch file fragment below tests for the existence of A:\JAN.DOC before copying it to drive C (this avoids an error message if the file does not exist): if exist a:\jan.doc copy a:\jan.doc c:\ This example tests the exit code of the previous program and stops all batch file processing if an error occurred: if errorlevel == 0 goto success echo "External Error -- Batch File Ends!" cancel Combining Tests You can negate the result of any test with NOT, and combine tests of any type with .AND., .OR., and .XOR. When two tests are combined with .AND., the result is true if both individual tests are true. When two tests are combined with .OR., the result is true if either (or both) individual tests are true. When two tests are combined with .XOR., the result is true only if one of the tests is true and the other is false. This example runs a program called DATALOAD if today is Monday or Tuesday: if "%_dow" == "Mon" .or. "%_dow" == "Tue" dataload Test conditions are always scanned from left to right; there is no implied order of precedence, as there is in some programming languages. You can, however, force a specific order of testing by grouping conditions with parentheses, for example: if (%a == 1 .or. (%b == 2 .and. %c == 3)) echo something Parentheses can only be used when the portion of the condition inside the parentheses contains at least one ".and.", ".or.", or ".xor.". Parentheses on a simple condition which does not combine two or more tests will be taken as part of the string to be tested, and will probably make the test fail. For example, the first of these IF tests would fail; the second would succeed: if (a == a) ... if (a == a .and. b == b) ... Parentheses can be nested. ═══ 3.3.42. IFF - IFF / THEN / ELSE conditional test ═══ Purpose: Perform IF / THEN / ELSE conditional execution of commands. Format: IFF [NOT] condition [.AND. | .OR. | .XOR. [NOT] condition ...] THEN & commands [ELSEIFF condition THEN & commands ] ... [ELSE & commands ] ENDIFF condition : A test to determine if the command(s) should be executed. commands : One or more commands to execute if the condition(s) is true. If you use multiple commands, they must be separated by command separators or be placed on separate lines of a batch file. See also: IF and @IF. Usage: IFF is similar to the IF command, except that it can perform one set of commands when a condition or set of conditions is true and a different set of commands when the conditions are false. IFF can execute multiple commands when the conditions are true or false; IF normally executes only one command. IFF imposes no limit on the number of commands and is generally a "cleaner" and more structured command than IF. IFF is always followed by one or more conditions. If they are true, the commands that follow the word THEN are executed. Additional conditions can be tested with ELSEIFF. If none of these conditions are true, the commands that follow the word ELSE are executed. After the selected commands (if any) are executed, processing continues after the word ENDIFF. If you add a NOT before the condition, the THEN commands are executed only when the condition is false and the ELSE commands are executed only when the condition is true. The commands may be separated by command separators, or may be on separate lines of a batch file. You should include a command separator or a line break after a THEN, before an ELSEIFF, and before and after an ELSE. You can link conditions with .AND., .OR., or .XOR., and you can group conditions with parentheses. You can nest IFF statements up to 15 levels deep. The conditions can test strings or numbers, the existence of a file or subdirectory, the errorlevel returned from the preceding external command, and the existence of aliases and internal commands. See the IF command for a list of the possible conditions and details on using .AND, .OR, .XOR, and parentheses. The commands can include any internal command, alias, external command, or batch file. The alias in this example checks to see if the argument is a subdirectory. If so, the alias deletes the subdirectory's files and removes it: [c:\] alias prune `iff isdir %1 then & del /sxz %1 & else & echo Not a directory! & endiff` Be sure to read the cautionary notes about GOTO and IFF under the GOTO command before using a GOTO inside an IFF statement. If you pipe data to an IFF, the data will be passed to the command(s) following the IFF, not to IFF itself. ═══ 3.3.43. INKEY - Input a character ═══ Purpose: Get a single keystroke from the user and store it in an environment variable. Format: INKEY [/C /D /K"keys" /P /Wn /X] [prompt ] %%varname prompt : Optional text that is displayed as a prompt. varname : The variable that will hold the user's keystroke. /C(lear buffer) /D(igits only) /K(valid keystrokes) /P(assword) /W(ait) /X (no carriage return) See also: INPUT, KEYSTACK, MSGBOX, and QUERYBOX. Usage: INKEY optionally displays a prompt. Then it waits for a specified time or indefinitely for a keystroke, and places the keystroke into an environment variable. It is normally used in batch files and aliases to get a menu choice or other single-key input. Along with the INPUT command, INKEY allows great flexibility in reading input from within a batch file or alias. If prompt text is included in an INKEY command, it is displayed while INKEY waits for input. INKEY works within the command line window. If you prefer to use a dialog for user input, see the MSGBOX and QUERYBOX commands. The following batch file fragment prompts for a character and stores it in the variable NUM: inkey Enter a number from 1 to 9: %%num INKEY reads standard input for the keystroke, so it will accept keystrokes from a redirected file or from the KEYSTACK. You can supply a list of valid keystrokes with the /K option. Standard keystrokes with ASCII values between 1 and 255 are stored directly in the environment variable. Extended keystrokes (for example, function keys and cursor keys) are stored as a string in decimal format, with a leading @ (for example, the F1 key is @59). The Enter key is stored as an extended keystroke, with the code @28. See the Key Code Tables for a list of extended key codes. To test for a non-printing ASCII keystroke returned by INKEY use the @ASCII function to get the numeric value of the key. For example, to test for Esc, which has an ASCII value of 27: inkey Enter a key: %%key if "%@ascii[%key]" == "27" echo Esc pressed If you press Ctrl-C or Ctrl-Break while INKEY is waiting for a key, execution of an alias will be terminated, and execution of a batch file will be suspended while you are asked whether to cancel the batch job. A batch file you can handle Ctrl-C and Ctrl-Break itself with the ON BREAK command. Options: /C (Clear buffer) Clears the keyboard buffer before INKEY accepts keystrokes. If you use this option, INKEY will ignore any keystrokes which you type, either accidentally or intentionally, before it is ready to accept input. /D (Digits only): Prevents INKEY from accepting any keystroke except a digit from 0 to 9. /K"keys"Specify the permissible keystrokes. The list of valid keystrokes should be enclosed in double quotes. For alphabetic keys the validity test is not case sensitive. You can specify extended keys by enclosing their names in square brackets (within the quotes). Enter this example on one line: inkey /k"ab[Ctrl-F9]" Enter A, B, or Ctrl-F9 %%var See Keys and Key Names for a complete listing of the key names you can use within the square brackets, and a description of the key name format. If an invalid keystroke is entered, Take Command will echo the keystroke if possible, beep, move the cursor back one character, and wait for another keystroke. /P (Password) Prevents INKEY from echoing the character. /W (Wait) Time-out period, in seconds, to wait for a response. If no keystroke is entered by the end of the time-out period, INKEY returns with the variable unchanged. This allows you to continue the batch file if the user does not respond in a given period of time. You can specify /W0 to return immediately if there are no keys waiting in the keyboard buffer. For example, the following batch file fragment waits up to 10 seconds for a character, then tests to see if a "Y" was entered: set netmon=N inkey /K"YN" /w10 Network monitor (Y/N)? %%net iff "%netmon" == "Y" then rem Commands to load the monitor program endiff /X (No carriage return) Prevents INKEY from displaying a carriage return and line feed after the user's entry. ═══ 3.3.44. INPUT - Input a string ═══ Purpose: Get a string from the keyboard and save it in an environment variable. Format: INPUT [/C /D /E /Ln /N /P /Wn /X] [prompt ] %%varname prompt : Optional text that is displayed as a prompt. varname : The variable that will hold the user's input. /C(lear buffer) /N(o colors) /D(igits only) /P(assword) /E(dit) /W(ait) /L(ength) /X (no carriage return) See also: INKEY, KEYSTACK, MSGBOX, and QUERYBOX. Usage: INPUT optionally displays a prompt. Then it waits for a specified time or indefinitely for your entry. It places any characters you type into an environment variable. INPUT is normally used in batch files and aliases to get multi-character input (for single-keystroke input, see INKEY). INPUT works within the command line window. If you prefer to use a dialog for user input, see the MSGBOX and QUERYBOX commands. If prompt text is included in an INPUT command, it is displayed while INPUT waits for input. Standard command-line editing keys may be used to edit the input string as it is entered. If you use the /P password option, INPUT will echo asterisks instead of the keys you type. All characters entered up to, but not including, the carriage return are stored in the variable. The following batch file fragment prompts for a string and stores it in the variable FNAME: input Enter the file name: %%fname INPUT reads standard input, so it will accept text from a re-directed file or from the KEYSTACK. If you press Ctrl-C or Ctrl-Break while INPUT is waiting for input, execution of an alias will be terminated, and execution of a batch file will be suspended while you are asked whether to cancel the batch job. A batch file you can handle Ctrl-C and Ctrl-Break itself with the ON BREAK command. Options: /C (Clear buffer) Discard any keystrokes pending in the keyboard buffer before INPUT begins accepting characters. /D (Digits only): Prevents INPUT from accepting any keystrokes except digits from 0 to 9. /E (Edit) Allows you to edit an existing value. If there is no existing value for varname, INPUT proceeds as if /E had not been used, and allows you to enter a new value. /Ln (Length) Sets the maximum number of characters which INPUT will accept to "n". If you attempt to enter more than this number of characters, INPUT will beep and prevent further input (you will still be able to edit the characters typed before the limit was reached). /N (No color) Disables the display colors set by InputColor in the TCMDOS2.INI file. With this option, INPUT will use the default display colors instead. /P (Password) Tells INPUT to echo asterisks, instead of the characters you type. /W (Wait) Time-out period, in seconds, to wait for a response. If no keystroke is entered by the end of the time-out period, INPUT returns with the variable unchanged. This allows you to continue the batch file if the user does not respond in a given period of time. If you enter a key before the time-out period, INPUT will wait indefinitely for the remainder of the line. You can specify /W0 to return immediately if there are no keys waiting in the keyboard buffer. /X (No carriage return) Prevents INPUT from displaying a carriage return and line feed after the user's entry. ═══ 3.3.45. KEYBD - Set keyboard toggles ═══ Purpose: Set the state of the keyboard toggles: Caps Lock, Num Lock, and Scroll Lock. Format: KEYBD [/Cn /Nn /Sn] n : 0 to turn off the toggle, or 1 to turn on the toggle. /C(aps lock) /S(croll lock) /N(um lock) Usage: Most keyboards have 3 toggle keys, the Caps Lock, Num Lock, and Scroll Lock. The toggle key status is usually displayed by three lights at the top right corner of the keyboard. This command lets you turn any toggle key on or off. It is most useful in batch files and aliases if you want the keys set a particular way before collecting input from the user. For example, to turn off the Num Lock and Caps Lock keys, you can use this command: [c:\] keybd /c0 /n0 If you use the KEYBD command with no switches, it will display the present state of the toggle keys. The toggle key state is typically the same for all sessions and changes made with KEYBD in one session will therefore affect all other sessions. Options: /C (Caps lock) Turn the Caps Lock key on or off. /N (Num lock) Turn the Num Lock key on or off. /S (Scroll lock) Turn the Scroll Lock key on or off. ═══ 3.3.46. KEYS - Enable/disable history list ═══ Purpose: Enable, disable, or display the history list. Format: KEYS [ON | OFF | LIST] See also: HISTORY. Usage: This command is provided for compatibility with KEYS command in CMD.EXE, which controls the history list in OS/2. The same functions are available by setting the HistMin directive in the .INI file, and by using the HISTORY command. The history list collects the commands you type for later recall, editing, and viewing. You can view the contents of the list through the history list window or by typing any of the following commands: [c:\] history [c:\] history /p [c:\] keys list The first command displays the entire history list. The second displays the entire list and pauses at the end of each full screen. The third command produces the same output as the first, except that each line is numbered. You can disable the collection and storage of commands in the history list by typing: [c:\] keys off You can turn the history back on with the command: [c:\] keys on If you issue the KEYS command without any parameters, Take Command will show you the current status of the history list. ═══ 3.3.47. KEYSTACK - Feed keystrokes to programs ═══ Purpose: Feed keystrokes to a program or command automatically. Format: KEYSTACK [!] [/Wn] ["abc"] [keyname[n]] ... .br ! Signal to clear the Keystack and the keyboard buffer. "abc": Literal characters to be placed in the Keystack. keyname: Name for a key to be placed in the Keystack. n: Number of times to repeat the named key. /W(ait) See also: Using the Keystack. Usage: KEYSTACK takes a series of keystrokes and feeds them to a program or command as if they were typed at the keyboard. When the program has used all of the keystrokes sent by KEYSTACK, it will begin to read the keyboard for input, as it normally would. KEYSTACK will send the keystrokes to the current active window. If you want to send keystrokes to another program (rather than have them function with Take Command itself), you must start the program or ACTIVATE its window so it can receive the keystrokes. You must do this before executing the KEYSTACK command. KEYSTACK is most often used for programs started from batch files. In order for KEYSTACK to work in a batch file, you must start the program with the START command, then use the KEYSTACK command. If you start the program directly Ч without using START Ч the batch file will wait for the application to complete before continuing and running the KEYSTACK command, and the keystrokes will be placed in the buffer too late. If you use KEYSTACK in an alias executed from the prompt, the considerations are essentially the same, but depend on whether ExecWait is set. If ExecWait is not set, you can use KEYSTACK immediately after an application is started. However, if ExecWait is set, the KEYSTACK command will not be executed until the program has finished, and the keystrokes will be placed in the buffer too late. You may not be able to use KEYSTACK effectively if you have programs running in the background which change the active window (for example, by popping up a dialog box). If a window pops up in the midst of your KEYSTACK sequence, keystrokes stored in the KEYSTACK buffer may go to that window, and not to the application you intended. KEYSTACK will only work if the file KEYSTACK.EXE is in the same directory as TCOS2.EXE, or a directory listed in your PATH. If KEYSTACK.EXE cannot be found, the KEYSTACK command will display an error message. KEYSTACK can send keystrokes to Presentation Manager applications and to character-mode applications running in a window. It cannot send keystrokes to DOS applications, nor to character-mode applications running in a full-screen session. Characters entered within double quotes ("abc") will be stored "as is" in the buffer. The only items allowed outside double quotes are key names, the ! and /W options, and a repeat count. See Keys and key names for a complete listing of key names and a description of the key name and numeric key code format. If you want to send the same key name or numeric code several times, you can follow it with a repeat count in square brackets. For example, to send the Enter key 4 times, you can use this command: keystack enter [4] The repeat count works only with individual keystrokes, or numeric keystroke or character values. It cannot be used with quoted strings. An exclamation mark [!] will clear all pending keystrokes in the KEYSTACK buffer. For example, to start a word processor called Word and select the second item on the second menu n the menu bar, you could use the command: [d:\doc] keystack F10 Right Down "1" ^ word This places the keystrokes for F10 (change to the menu bar), right arrow (move to the File menu), down arrow (display the file menu), and "1" (open the most recently used file) into the buffer, then runs Word. When Word starts it receives these keystrokes and performs the appropriate actions. You can store a maximum of 1,023 characters in the KEYSTACK buffer. A delay takes two character "slots" in the buffer. A repeated character takes one character slot per repetition. Each time the KEYSTACK command is executed, it will clear any remaining keystrokes stored by a previous KEYSTACK command. You may need to experiment with your programs and insert delays (see the /W option) to find the window activation and keystroke sequence that works for a particular program. Options: /W (Wait): Delay the next keystroke in the KEYSTACK buffer by a specified number of clock "ticks". A clock tick is approximately 1/18 second. The number of clock ticks to delay should be placed immediately after the W, and must be between 1 and 65535 (65535 ticks is about 1 hour). You can use the /W option as many times as desired and at any point in the string of keystrokes except within double quotes. Some programs may need the delays provided by /Win order to receive keystrokes properly from KEYSTACK. The only way to determine what delay is needed is to experiment. ═══ 3.3.48. LIST - Display file ═══ Purpose: Display a file, with forward and backward paging and scrolling. Format: LIST [/A:[[-]rhsda] /H /I /R /S /T /W /X] file... file : A file or list of files to display. /A: (Attribute select) /S(tandard input) /H(igh bit off) /T (search for Text) /I(gnore wildcards) /W(rap) /R(everse) /X (heX display mode) See also: TYPE. File Selection: Supports extended wildcards, ranges, multiple file names, and include lists. Usage: LIST provides a fast and flexible way to view a file, without the overhead of loading and using a text editor. For example, to display a file called MEMO.DOC: [c:\] list memo.doc LIST is most often used for displaying ASCII text files. It can be used for other files which contain non-alphabetic characters, but you may need to use hex mode (see below) to read these files. LIST displays files in the Take Command window. The standard tool bar and scroll bars are replaced with the LIST tool bar and scroll bars. Use the scroll bars or cursor pad to scroll through the file. You can select the LIST commands either with the mouse (on the tool bar and scrollbars) or from the keyboard. LIST recognizes the following keys and buttons: Home Display the first page of the file. End Display the last page of the file. Esc (Cont) Exit the current file. Ctrl-C (Quit) Quit LIST. Ctrl-PgUp. Display previous file. Ctrl-PgDn. Display next file.  Scroll up one line.  Scroll down one line. Scroll left 8 columns. Scroll right 8 columns. Ctrl Scroll left 40 columns. Ctrl Scroll right 40 columns. F1 Display online help B (Back) Go back one file to the previous file in the current group of files. F (Find) Prompt and search for a string or a sequence of hexadecimal values. Ctrl-F Prompt and search for a string, searching backward from the end of the file. G (Goto) Go to a specific line, or, in hex mode, to a specific hexadecimal offset. H (High) Toggle the "strip high bit" (/H) option. I (Info) Display information on the current file (the full name, size, date, and time). N (Next) Find next matching string. Ctrl-N Find the previous matching string in the file. O (Open) Open a new file P (Print) Print selected text, the current page, or the entire file. W (Wrap) Toggle the "line wrap" (/W) option. X (heX) Toggle the hex-mode display (/X) option. Text searches performed with F, N, Ctrl-F, and Ctrl-N, or with the corresponding buttons, are not case- sensitive unless you check the "Match case" box in the search dialog. LIST remembers the search strings you have used in the current Take Command session; to select a previous string, use the drop-down arrow to the right of the string entry field (the N key and the Next button search for the top item in this drop-down list). When the search string is found LIST displays the line containing the string at the top of the window, and highlights the string it found. Any additional occurrences of the string on the same display page are also highlighted. Highlighting is intended for use with text files; in binary files the search string will be found, but may not be highlighted properly. If you want to search for specific hexadecimal values check the "Hex search" box, and enter the search string as a sequence of 2-digit hexadecimal numbers separated by spaces, for example 41 63 65 (these are the ASCII values for the string "Ace"; see the ASCII Table for a complete list of standard ASCII codes). Hexadecimal searches are case-sensitive, and search for exactly the string you enter. You can use extended wildcards in the search string. For example, you can search for the string "to*day" to find the next line which contains the word "to" followed by the word "day" later on the same line, or search for the numbers "101" or "401" with the search string "[14]01". If you begin the search string with a back-quote [`], or enclose it in back-quotes, wildcard characters in the string will be treated as normal text with no special wildcard meaning. You can use the /T switch to specify search text for the first file. When you do so, LIST begins a search as soon as the file is loaded. Use /I to ignore wildcards in the initial search string, and /R to make the initial search go backwards from the end of the file. When you LIST multiple files with a single LIST command, these switches affect only the first file; they are ignored for the second and subsequent files. You can use the G key to go to a specific line number in the file (or to a specified hexadecimal offset in hex mode). LIST numbers lines beginning with 1, unless ListRowStart is set to 0. A new line is counted for every CR or LF character (LIST determines automatically which character is used for line breaks in each file), or when line length reaches 511 characters, whichever comes first. LIST normally allows long lines in the file to extend past the right edge of the screen. You can use the horizontal scrolling keys (see above) to view text that extends beyond the screen width. If you use the W command or /W switch to wrap the display, each line is wrapped when it reaches the right edge of the screen, and the horizontal scrolling keys are disabled. To view text from the clipboard, use CLIP: as the file to be listed. CLIP: will not return any data unless the clipboard contains text. If you print the file which LIST is displaying, the print format will match the display format. If you have switched to hexadecimal or wrapped mode, that mode will be used for the printed output as well. If you print in wrapped mode, long lines will be wrapped at the width of the display. If you print in normal display mode without line wrap, long lines will be wrapped or truncated by the printer, not by LIST. Regardless of the display mode, LIST will bring up a standard print dialog which allows you to print selected text, the current page, or the entire file. Advanced Features If you specify a directory name instead of a filename as an argument, LIST will display each of the files in that directory. Most of the LIST keystrokes can be reassigned with TCMDOS2.INI file key mapping directives. You can set the colors used by LIST with the ListColors directive in the TCMDOS2.INI file, or the LIST Colors selection on the Commands page of the configuration notebook. If ListColors is not used, the LIST display will use the current default colors. By default, LIST sets tab stops every 8 columns. You can change this behavior with the TabStops directive in the TCMDOS2.INI file. Options: /A: (Attribute select): Select only those files that have the specified attribute(s) set. Preceding the attribute character with a hyphen [-] will select files that do not have that attribute set. The colon [:] after /A is required. The attributes are: R Read-only H Hidden S System D Subdirectory A Archive If no attributes are listed at all (e.g., LIST /A:), LIST will select all files and subdirectories including hidden and system files. If attributes are combined, all the specified attributes must match for a file to be selected. For example, /A:RHSwill select only those files with all three attributes set. /H (High bit off) Strip the high bit from each character before displaying. This is useful when displaying files created by some word processors that turn on the high bit for formatting purposes. You can toggle this option on and off from within LIST with the H key. /I (Ignore wildcards) Only meaningful when used in conjunction with the /T" text" option. Direct LIST to interpret characters such as *, ?, [, and ] as literal characters instead of wildcard characters. /I affects only the initial search started by /T, not subsequent searches started from within LIST. /R (Reverse) Only meaningful when used in conjuction with the /T "text" option. Directs LIST to search for text from the end of the file instead of from the beginning of the file. Using this switch can speed up searches for text that is normally near the end of the file, such as a signature. /R affects only the initial search started by /T, not subsequent searches started from within LIST. /S (Standard input) Read from standard input rather than a file. This allows you to redirect command output and view it with LIST. Normally, LIST will detect input from a redirected command and adjust automatically. However, you may find circumstances when /S is required. For example, to use LIST to display the output of DIR you could use either of these commands: [c:\] dir | list [c:\] dir | list /s /T (Text) Search for text in the first file. This option is the same as pressing F, but it allows you to specify the search text on the command line. The text must be contained in quotation marks if it contains spaces, punctuation, or wildcard characters. For example, to search for the string Take Command in the file README.DOC, you can use this command: [c:\] list /t"Take Command" readme.doc The search text may include wildcards and extended wildcards. For example, to search for the words Hello and John on the same line in the file LETTER.DAT: [c:\] list /t"Hello*John" letter.dat When you LIST multiple files with a single LIST command, /T only initiates a search in the first file. It is ignored for the second and subsequent files. Also see /I and /R. /W (Wrap) Wrap the text at the right edge of the screen. This option is useful when displaying files that don't have a carriage return at the end of each line. The horizontal scrolling keys do not work when the display is wrapped. You can toggle this option on and off from within LIST with the W key or the Wrap button on the tool bar. /X (hex mode): Display the file in hexadecimal (hex) mode. This option is useful when displaying executable files and other files that contain non-text characters. Each byte of the file is shown as a pair of hex characters. The corresponding text is displayed to the right of each line of hexadecimal data. You can toggle this mode on and off from within LIST with the X key or the heX button on the tool bar. ═══ 3.3.49. LOADBTM - Switch batch file mode ═══ Purpose: Switch a batch file to or from BTM mode. Format: LOADBTM [ON | OFF] Usage: Take Command recognizes two kinds of batch files: .CMD and .BTM. Batch files executing in BTM mode run two to ten times faster than in CMD mode. (However, BTM mode should not be used for self-modifying batch files.) Batch files automatically start in the mode indicated by their extension. The LOADBTM command turns BTM mode on and off. It can be used to switch modes in either a .CMD or .BTM file. If you use LOADBTM with no argument, it will display the current batch mode: LOADBTM ON or LOADBTM OFF. Using LOADBTM to repeatedly switch modes within a batch file is not efficient. In most cases the speed gained by running some parts of the file in BTM mode will be more than offset by the speed lost through repeated loading of the file each time BTM mode is invoked. LOADBTM can only be used within a batch file. It is most often used to convert a .CMD file to BTM mode without changing its extension. ═══ 3.3.50. LOG - Log commands to file ═══ Purpose: Save a log of commands to a disk file. Format: LOG [/H /W file ] [ON | OFF | text ] file : The name of the file to hold the log. text : An optional message that will be added to the log. /H(istory log) /W(rite to) See also: HISTORY. Usage: LOG keeps a record of all internal and external commands you use, whether they are executed from the prompt or from a batch file. Each entry includes the current system date and time, along with the actual command after any alias or variable expansion. You can use the log file as a record of your daily activities. LOG with the /H option keeps a similar record called a "history log". The history log records only commands entered at the prompt; it does not record batch file commands. In addition, the history log does not record the date and time for each command, and it records commands before aliases and variables are expanded. The two logging options are independent. You can have both a regular log and a history log enabled simultaneously. By default, LOG writes to the file OS2LOG in the root directory of the boot drive. The default file name for LOG /H is OS2HLOG. You can set the default log file names from the Options 2 page of the configuration notebook, or with the LogName and HistLogName directives in the TCMDOS2.INI file. Entering LOG or LOG /H with no parameters displays the name of the log file and the log status (ON or OFF): [c:\] log LOG (C:\COS2LOG) is OFF To enable or disable logging, add the word "ON" or "OFF" after the LOG command: [c:\] log on or [c:\] log /h on Entering LOG or LOG /H with text writes a message to the log file, even if logging is set OFF. This allows you to enter headers in the log file: [c:\] log "Started work on the database system" The LOG file format looks like this: [mm-dd-yy hh:mm:ss] command The LOG /H output can be used as the basis for writing batch files. Start LOG /H, then execute the commands that you want the batch file to execute. When you are finished, turn LOG /H off. The resulting file can be turned into a batch file that performs the same commands with little or no editing. Options: /H (History log) This option makes the other options on the command line (after the /H) apply to the history log. For example, to turn on history logging and write to the file C:\LOG\HLOG: [c:\] log /h /w c:\log\hlog /W (Write) This switch specifies a different filename for the LOG or LOG /H output. It also automatically performs a LOG ON command. For example, to turn logging on and write the log to C:\LOG\LOGFILE: [c:\] log /w c:\log\logfile Once you select a new file name with the LOG /W or LOG /H/W command, LOG will use that file until you issue another LOG /W or LOG /H/W command, or until you reboot your computer. Turning LOG or LOG /H off or on does not change the file name. ═══ 3.3.51. MD - Create a subdirectory ═══ Purpose: Create a subdirectory. Format: MD [/N /S] path... or MKDIR [/N /S] path... path : The name of one or more directories to create. /N(o update) /S(ubdirectories) See also: RD. Usage: MD and MKDIR are synonyms. You can use either one. MD creates a subdirectory anywhere in the directory tree. To create a subdirectory from the root, start the path with a backslash [\]. For example, this command creates a subdirectory called MYDIR in the root directory: [c:\] md \mydir If no path is given, the new subdirectory is created in the current directory. This example creates a subdirectory called DIRTWO in the current directory: [c:\mydir] md dirtwo To create a directory from the parent of the current directory (that is, to create a sibling of the current directory), start the pathname with two periods and a backslash [..\]. When creating a directory on a HPFS drive, you must quote any path which contains whitespace or special characters. If MD creates one or more directories, they will be added automatically to the extended directory search database unless the /N option is specified. Option: /N(No update) Do not update the extended directory search database, JPSTREE.IDX. This is useful when creating a temporary directory which you do not want to appear in the extended search database. /S(Subdirectories) Allows you to create more than one directory at a time. For example, if you need to create the directory C:\ONE\TWO\THREE and none of the named directories exist, you can use /S to have MD create all of the necessary subdirectories in a single command (without the /S, this command will fail because the parent directory C:\ONE\TWO does not exist): [c:\] md /s \one\two\three ═══ 3.3.52. MEMORY - Display memory status ═══ Purpose: Display the amount and status of Take Command and OS/2 memory. Format: MEMORY Usage: MEMORY lists the total physical and resident RAM, the largest free block in RAM, the swap file size, the total and free environment and alias space, and the total history space. If the OS/2 swap file is not stored in the \OS2\SYSTEM directory of the boot drive, you must use the SwapFilePath directive in TCMDOS2.INI or MEMORY will not be able to display the swap file size. ═══ 3.3.53. MOVE - Move files to another directory ═══ Purpose: Move files to a new directory and drive. Format: MOVE [/A:[[-]rhsda] /C /D /E /F /H /M /N /P /Q /R /S /T /U /V] source... destination source : A file or list of files to move. destination : The new location for the files. /A:(ttribute select) /P(rompt) /C(hanged) /Q(uiet) /D(irectory) /R(eplace) /E (No error messages) /S(ubdirectory tree) /F(orce delete) /T(otal) /H(idden and system) /U(pdate) /M(odified files) /V(erify) /N(othing) See also: COPY and RENAME. File Selection: Supports extended wildcards, ranges, multiple file names, and include lists. Ranges anywhere on the line apply to all source files. Usage: The MOVE command moves one or more files from one directory to another, whether the directories are on the same drive or not. It has the same effect as copying the files to a new location and then deleting the originals. Like COPY and RENAME, MOVE works with single files, multiple files, and sets of files specified with an include list. The simplest MOVE command moves a single source file to a new location and, optionally, gives it a new name. These two examples both move one file from drive C: to the root directory on drive A: [c:\] move myfile.dat a:\ [c:\] move myfile.dat a:\savefile.dat In both cases, MYFILE.DAT is removed from drive C: after it has been copied to drive A:. If a file called MYFILE.DAT in the first example, or SAVEFILE.DAT in the second example, already existed on drive A:, it would be overwritten. (This demonstrates the difference between MOVE and RENAME. MOVE will move files between drives and will overwrite the destination file if it exists; RENAME will not.) When you move a single file, the destination can be a directory name or a file name. If it is a directory name, and you add a backslash [\] to the end of the name, MOVE will display an error message if the name does not refer to an existing directory. You can use this feature to keep MOVE from treating a mistyped destination directory name as a file name, and attempting to move the source file to that name. If you MOVE multiple files, the destination must be a directory name. MOVE will move each file into the destination directory with its original name. If the destination is not a directory, MOVE will display an error message and exit). For example, if C:\FINANCE\MYFILES is not a directory, this command will display an error; otherwise, the files will be moved to that directory:: [c:\] move *.wks *.txt c:\finance\myfiles The /D option can be used for single or multiple file moves; it checks to see whether the destination is a directory, and will prompt to see if you want to create the destination directory if it doesn't exist. If MOVE creates one or more destination directories, they will be added automatically to the extended directory search database. Be careful when you use MOVE with the SELECT command. If you SELECT multiple files and the target is not a directory (for example, because of a misspelling), MOVE will assume it is a file name. In this case each file will be moved in turn to the target file, overwriting the previous file, and then the original will be erased before the next file is moved. At the end of the command, all of the original files will have been erased and only the last file will exist as the target file. You can avoid this problem by using square brackets with SELECT instead of parentheses (be sure that you don't allow the command line to get too long -- watch the character count in the upper left corner while you're selecting files). MOVE will then receive one list of files to move instead of a series of individual filenames, and it will detect the error and halt. You can also add a backslash [\] to the end of the destination name to ensure that it is the name of a subdirectory (see above). Advanced Features and Options MOVE first attempts to rename the file(s), which is the fastest way to move files between subdirectories on the same drive. If that fails (e.g., because the destination is on a different drive or already exists), MOVE will copy the file(s) and then delete the originals. If MOVE must physically copy the files and delete the originals, rather than renaming them (see above), then some disk space may be freed on the source drive. The free space may be the result of moving the files to another drive, or of overwriting a larger destination file with a smaller source file. MOVE displays the amount of disk space recovered unless the /Q option is used (see below). It does so by comparing the amount of free disk space before and after the MOVE command is executed. However, this amount may be incorrect if you are using a deletion tracking system which retains deleted files for later recovery, or if another program performs a file operation while the MOVE command is executing. When physically copying files, MOVE preserves the hidden, system, and read- only attributes of the source files, and sets the archive attribute of the destination files. However, if the files can be renamed, and no copying is required, then the source file attributes are not changed. Use caution with the /A: and /H switches (both of which can allow MOVE to process hidden files) when you are physically moving files and both the source and destination directories contain file descriptions. If the source file specification matches the description file name (normally DESCRIPT.ION), and you tell MOVE to process hidden files, the DESCRIPT.ION file itself will be moved, overwriting any existing descriptions in the destination directory. For example, if the C:\DATA directory contains file descriptions this command would overwrite any existing descriptions in the D:\SAVE directory: [c:\data] move /h d*.* d:\save\ (If you remove the hidden attribute from the DESCRIPT.ION file the same caution applies even if you do not use /A: or /H, as DESCRIPT.ION is then treated like any other file.) If you move a file from a FAT volume to an HPFS volume, and you do not give an explicit destination name (i.e., you are moving the file to the current directory, or your destination name is made up entirely of wildcards), MOVE will look for a .LONGNAME extended attribute for the source file. If it finds that attribute, it will use the long filename for the destination file. If it does not, it will use the short name. Similarly, if you MOVE files with long filenames from an HPFS volume to a FAT volume, Take Command will create the destination files with short, FAT-compatible names and save the long filenames in the .LONGNAME extended attribute. The short name is created by replacing special characters with underscores, adding numeric digits to the filename (if necessary) to make the new name unique, and truncating the name to fit with in the "8.3" FAT name structure. Options: /A: (Attribute select) Select only those files that have the specified attribute(s) set. Preceding the attribute character with a hyphen [-] will select files that do not have that attribute set. The colon [:] after /A is required. The attributes are: R Read-only H Hidden S System D Subdirectory A Archive If no attributes are listed at all (e.g., MOVE /A: ...), MOVE will select all files and subdirectories including hidden and system files. If attributes are combined, all the specified attributes must match for a file to be selected. For example, /A:RHS will select only those files with all three attributes set. See the cautionary note under Advanced Features and Options above before using /A: when both source and destination directories contain file descriptions. /C (Changed files) Move files only if the destination file exists and is older than the source (see also /U). This option is useful for updating the files in one directory from those in another without moving any newly-created files. /D (Directory) Requires that the destination be a directory. If the destination does not exist, MOVE will prompt to see if you want to create it. If the destination exists as a file, MOVE will fail with an "Access denied" error. Use this option to avoid having MOVE accidentally interpret your destination name as a file name when it's really a mistyped directory name. /E (No error messages) Suppress all non-fatal error messages, such as "File Not Found." Fatal error messages, such as "Drive not ready," will still be displayed. This option is most useful in batch files and aliases. /F (Force delete) This option forces deletion of the source file without saving it to the DELDIR directory (if DELDIR is not in use, /F has no effect). /F is only effective when MOVE must copy the source file(s) and delete the originals (i.e., if the destination is on a different drive or the destination file already exists). If the files are simply renamed, /F has no effect. /H (Hidden) Move all files, including hidden and system files. See the cautionary note under Advanced Features and Options above before using /H when both source and destination directories contain file descriptions. /M (Modified files) Move only files that have the archive bit set. The archive bit will remain set after the MOVE; to clear it use ATTRIB. /N (Nothing) Do everything except actually move the file(s). This option is most useful for testing what a complex MOVE command will do. /N does not prevent creation of destination subdirectories when it is used with /S. /P (Prompt) Prompt the user to confirm each move. Your options at the prompt are explained in detail under Page and File Prompts. /Q (Quiet) Don't display filenames, the total number of files moved, or the amount of disk space recovered, if any. This option is most often used in batch files. See also /T. /R (Replace) Prompt for a Y or N response before overwriting an existing destination file. /S (Subdirectories) Move an entire subdirectory tree to another location. MOVE will attempt to create the destination directories if they don't exist, and will remove empty subdirectories after the move. When /D is used with /S, you will be prompted if the first destination directory does not exist, but subdirectories below that will be created automatically by MOVE. If MOVE /S creates one or more destination directories, they will be added automatically to the extended directory search database. If you attempt to use /S to move a subdirectory tree into part of itself, MOVE will detect the resulting infinite loop, display an error message and exit. /T (Total) Don't display filenames as they are moved, but display the total number of files deleted and the amount of free disk space recovered, if any. /U (Update) Move each source file only if it is newer than a matching destination file or if a matching destination file does not exist (also see /C). This option is useful for moving new or changed files from one directory to another. /V (Verify) Verify each disk write. This is the same as executing the VERIFY ON command, but is only active during the MOVE. /V does not read back the file and compare its contents with what was written; it only verifies that the data written to disk is physically readable. ═══ 3.3.54. MSGBOX - Display a message box prompt ═══ Purpose: Display a message box and return the user's response. Format: MSGBOX OK | OKCANCEL | YESNO | YESNOCANCEL ["title"] prompt title : Text for the title of the message box. prompt : Text that will appear inside the message box. See also: INKEY, INPUT, and QUERYBOX. Usage: MSGBOX can display one of 4 kinds of message boxes and wait for the user's response. You can use title and prompt to display any text you wish. If no title is specified, the program name ("Take Command for OS/2") is used as the title. Take Command automatically sizes and locates the box on the screen. The message box may have 1, 2, or 3 response buttons. The command MSGBOX OK creates a single-button box; the user must simply acknowledge the prompt text. The OKCANCEL and YESNO forms have 2 buttons each. The YESNOCANCEL form has 3 buttons. The button the user chooses is returned in the Take Command variable %_?. Be sure to save the return value in another variable or test it immediately, because the value of %_? changes with every internal command. The following list shows the value returned for each selection: Yes: 10 No: 11 OK: 10 Cancel: 12 If you exit the message box without selecting one of these options, MSGBOX will set %_? to 0. If there is an error in the MSGBOX command itself, %_? will be set to 1 for a syntax error or 2 for any other error. For example, to display a Yes or No message box and take action depending on the result, you could use commands like this: msgbox yesno "Copy" Copy all files to A:? if %_? == 10 copy *.* a: MSGBOX creates a popup dialog box. If you prefer to retrieve input from inside the command line window, see the INKEY and INPUT commands. ═══ 3.3.55. ON - Trap errors in batch files ═══ Purpose: Execute a command in a batch file when a specific condition occurs. Format: ON BREAK [command ] or ON ERROR [command ] or ON ERRORMSG [command ] Usage: ON can only by used in batch files. ON sets a "watchdog" that remains in effect for the duration of the current batch file. Whenever a BREAK or ERROR condition occurs after ON has been executed, the command is automatically executed. ON sets a "watchdog" that remains in effect for the duration of the current batch file. Whenever a BREAK or ERROR condition occurs after ON has been executed, the corresponding command is automatically executed. ON BREAK will execute the command if the user presses Ctrl-C or Ctrl-Break. ON ERROR and ON ERRORMSG will execute the command after any critical error, operating system error (such as a disk write error, or a Take Command error (such as a COPY command that fails to copy any files, or the use of an invalid command option). ON ERROR executes the command immediately after the error occurs, without displaying any command processor error message (operating system errors may still be displayed). ON ERRORMSG displays the appropriate error message, then executes the command. If both are specified, ON ERROR will take precedence, and ON ERRORMSG will be ignored. The remainder of this section discusses both settings, using the term "ON ERROR[MSG]". ON BREAK and ON ERROR[MSG] are independent of each other. You can use either one, or both, in any batch file. Each time ON BREAK or ON ERROR[MSG] is used, it defines a new command to be executed for a break or error, and any old command is discarded. If you use ON BREAK or ON ERROR[MSG] with no following command, that type of error handling is disabled. Error handling is also automatically disabled when the batch file exits. ON BREAK and ON ERROR[MSG] only affect the current batch file. If you CALL another batch file, the first batch file's error handling is suspended, and the CALLed file must define its own error handling. When control returns to the first batch file, its error handling is reactivated. The command can be any command that can be used on a batch file line by itself. Frequently, it is a GOTO or GOSUB command. For example, the following fragment traps any user attempt to end the batch file by pressing Ctrl-C or Ctrl-Break. It scolds the user for trying to end the batch file, then continues: on break gosub gotabreak do i = 1 to 1000 echo %i enddo quit :gotabreak echo Hey! Stop that!! return You can use a command group as the command if you want to execute multiple commands, for example: on break (echo Oops, got a break! & quit) ON BREAK and ON ERROR[MSG] always assume that you want to continue executing the batch file. After the command is executed, control automatically returns to the next command in the batch file (the command after the one that was interrupted by the break or error). To avoid continuing the batch file after a break or error is for the command can transfer control with GOTO, end the batch file with QUIT or CANCEL, or start another batch file (without CALLing it). When handling an error condition with ON ERROR[MSG], you may find it useful to use internal variables, particularly %_? and %_SYSERR, to help determine the cause of the error. The ON ERROR[MSG] command will not be invoked if an error occurs while reading or writing redirected input, output, or a pipe. Caution: If a break or error occurs while the command specified in ON BREAK or ON ERROR[MSG] is executing, the command will be restarted. This means you must use caution to avoid or handle any possible errors in the commands invoked by ON ERROR[MSG], since such errors can cause an infinite loop. ═══ 3.3.56. OPTION - Configure Take Command ═══ Purpose: Modify Take Command configuration. Format: OPTION [//optname=value ...] optname : An INI file directive to set or modify. value : A new value for that directive. See also: The TCMDOS2.INI file. Usage: OPTION displays a settings notebook which allows you to modify many of the configuration options stored in the TCMDOS2.INI file. When you exit from the notebook, you can select Save to save your changes in the .INI file for use in the current session and all future sessions, select OK to use your changes in the current session only, or select Cancel to discard the changes. OPTION does not preserve comments when saving modified settings in the .INI file. To be sure .INI file comments are preserved, put them on separate lines in the file. See TCMDOS2.INI for additional details. Setting Individual Options If you follow the OPTION command with one or more sequences of a double slash mark [//] followed by an option=value setting, the OPTION notebook will not appear. Instead, the new settings will take effect immediately, and will be in effect for the current session only. This example turns off batch file echo and changes the input colors to bright cyan on black: [c:\] option //BatchEcho = No //InputColors = bri cya on bla Option names and values may contain whitespace. However, you cannot enter an option value which contains the "//" string. This feature is most useful for testing settings quickly, and in aliases or batch files which depend on certain options being in effect. Changes made with // are temporary. They will not be saved in the .INI file, even if you subsequently load the option notebook and select Save. ═══ 3.3.57. PATH - Set the executable search path ═══ Purpose: Display or alter the list of directories that Take Command will search for executable files, batch files, and files with executable extensions that are not in the current directory. Format: PATH [directory[;directory ...]] directory : The full name of a directory to include in the path setting. See also: ESET and SET. Usage: When Take Command is asked to execute an external command, it first looks for the file in the current directory. If it fails to find an executable file in the current directory, it then searches each of the directories specified in the PATH setting. For example, after the following PATH command, Take Command will search for an executable file in four directories: the current directory, then the root directory on drive C, then the BIN subdirectory on C, and then the UTIL subdirectory on C: [c:\] path c:\;c:\bin;c:\util The list of directories to search is stored as an environment string, and can also be set or viewed with SET, and edited with ESET. Directory names in the path must be separated by semicolons [;]. Each directory name is shifted to upper case to maintain compatibility with programs which can only recognize upper case directory names in the path. If you modify your path with the SET or ESET command, you may include directory names in lower case. These may cause trouble with some programs, which assume that all path entries have been shifted to upper case. On HPFS drives, some directory names may include spaces or other special characters. Unlike other commands where quotes are required, such names should not be quoted in the PATH. If you enter PATH with no parameters, the current path is displayed: [c:\] path PATH=C:\;C:\BIN;C:\UTIL Entering PATH and a semicolon clears the search path so that only the current directory is searched for executable files (this is the default at system startup). Some applications also use the PATH to search for their data files. Take Command normally searches the path for files with the extensions .COM, .EXE, .BTM, .CMD, and .BAT (in that order). However, if you include an explicit file extension on a command name (for example, WP.EXE), the search will find files with that name and extension in the current directory and every directory in the path. It will not locate other executable files with the same base name (e.g., WP.COM). If you have an entry in the path which consists of a single period [.], the current directory will not be searched first, but instead will be searched when Take Command reaches the "." in the path. This allows you to delay the search of the current directory for executable files and files with executable extensions. In rare cases, this feature may not be compatible with applications which use the path to find their files; if you experience a problem, you will have to remove the "." from the path while using any such application. To create a path longer than the command-line length limit, use PATH repeatedly to append additional directories to the path: path [first list of directories] path %path;[second list of directories] ... You cannot use this method to extend the path beyond 2,042 characters (the internal buffer limit, with room for "PATH "). It is usually more efficient to use aliases to load application programs than to create a long PATH. See ALIAS for details. If you specify an invalid directory in the path, it will be skipped and the search will continue with the next directory in the path. ═══ 3.3.58. PAUSE - Suspend batch file execution ═══ Purpose: Suspend batch file or alias execution. Format: PAUSE [text ] text : The message to be displayed as a user prompt. Usage: A PAUSE command will suspend execution of a batch file or alias, giving you the opportunity to change disks, turn on the printer, etc. PAUSE waits for any key to be pressed and then continues execution. You can specify the text that PAUSE displays while it waits for a keystroke, or let it use the default message: Press any key when ready... For example, the following batch file fragment prompts the user before erasing files: pause Press Ctrl-C to abort, any other key to erase all .LST files erase *.lst If you press Ctrl-C or Ctrl-Break while PAUSE is waiting for a key, execution of an alias will be terminated, and execution of a batch file will be suspended while you are asked whether to cancel the batch job. A batch file can handle Ctrl-C and Ctrl-Break itself with the ON BREAK command. ═══ 3.3.59. POPD - Restore previous directory ═══ Purpose: Return to the disk drive and directory at the top of the directory stack. Format: POPD [*] See also: DIRS , PUSHD and Directory Navigation. Usage: Each time you use the PUSHD command, it saves the current disk drive and directory on the internal directory stack. POPD restores the last drive and directory that was saved with PUSHD and removes that entry from the stack. You can use these commands together to change directories, perform some work, and return to the starting drive and directory. Directory changes made with POPD are recorded in the directory history list and can be displayed in the directory history window. Read the section on Directory Navigation for complete details on this and other directory navigation features. This example saves and changes the current disk drive and directory with PUSHD, and then restores it. The current directory is shown in the prompt: [c:\] pushd d:\database\test [d:\database\test] pushd c:\wordp\memos [c:\wordp\memos] pushd a:\123 [a:\123] popd [c:\wordp\memos] popd [d:\database\test] popd [c:\] You can use the DIRS command to see the complete list of saved drives and directories (the directory stack). The POPD command followed by an asterisk [*] clears the directory stack without changing the current drive and directory. If the directory on the top of the stack is not on the current drive, POPD will switch to the drive and directory on the top of the stack without changing the default directory on the current drive. ═══ 3.3.60. PROMPT - Change command-line prompt ═══ Purpose: Change the command-line prompt. Format: PROMPT [text ] text : Text to be used as the new command-line prompt. Usage: You can change and customize the command-line prompt at any time. The prompt can include normal text, and system information such as the current drive and directory, the time and date, and the amount of memory available. You can create an informal "Hello, Bob!" prompt or an official-looking prompt full of impressive information. The prompt text can contain special commands in the form $?, where ? is one of the characters listed below: b The vertical bar character [|]. c The open parenthesis [(]. d Current date, in the format: Fri 12-12- 97 (the month, day, and year are formatted according to your current country settings). D Current date, in the format: Fri Dec 12, 1997. e The ASCII ESC character (decimal 27). f The close parenthesis [)]. g The > character. h Backspace over the previous character. l The < character. m Time in hours and minutes using 24-hour format. M Time in hours and minutes using the default country format. n Current drive letter. p Current directory on drive (lower case): (including drive letter), in lower case. P Current directory on drive (upper case on drives which do not support long file names, directory names shown in mixed case as stored on HPFS drives).: (including drive letter), in upper case. q The = character. r The numeric exit code of the last external command. s The space character. t Current 24-hour time, in the format hh:mm:ss. T Current 12-hour time, in the format hh:mm:ss[a|p]. v Operating system version number, in the format 3.10. xd: Current directory on drive d:, in lower case, including the drive letter. (Uses the actual case of the directory name as stored on the disk for HPFS drives). Xd: Current directory on drive d:, in upper case, including the drive letter. z Current shell nesting level. The first copy of Take Command is shell 0, and each subsequent copy increments the level by 1. + Display one + character for each directory on the PUSHD directory stack. $ The $ character. _ CR/LF (go to beginning of a new line). For example, to set the prompt to the current date and time, with a ">" at the end: [c:\] prompt $d $t $g Fri Jun 6, 1997 10:29:19 > The Take Command prompt can be set in TCSTART, or in any batch file that runs when Take Command starts. The Take Command default prompt is [$n](drive name in square brackets) on floppy drives, and [$p] (current drive and directory in square brackets) on all other drives. If you enter PROMPT with no arguments, the prompt will be reset to its default value. The PROMPT command sets the environment variable PROMPT, so to view the current prompt setting use the command: [c:\] set prompt (If the prompt is not set at all, the PROMPT environment variable will not be used, in which case the SET command above will give a "Not in environment" error.) Along with literal text and special characters, you can include the text of any environment variable, internal variable, or variable function in a prompt. For example, if you want to include the size of the largest free memory block in the command prompt, plus the current drive and directory, you could use this command: [c:\] prompt (%%@dosmem[K]K) [$p] (31043K) [c:\data] Notice that the @DOSMEM function is shown with two leading percent signs [%]. If you used only one percent sign, the @DOSMEM function would be expanded once when the PROMPT command was executed, instead of every time the prompt is displayed. As a result, the amount of memory would never change from the value it had when you entered the PROMPT command. You can also use back quotes to delay expanding the variable function until the prompt is displayed: [c:\] prompt `(%@dosmem[K]K) [$p]` You can use this feature along with the @EXEC variable function to create a complex prompt which not only displays information but executes commands. For example, to execute an alias which checks battery status each time the prompt is displayed (enter the alias on one line): [c:\] alias cbatt `if %_apmlife lt 30 beep 440 4 880 4 440 4 880 4` [c:\] prompt `%@exec[@cbatt]$p$g` You can include ANSI escape sequences in the PROMPT text using Take Command's built-in ANSI support. This example uses ANSI sequences to set a prompt that displays the shell level, date, time and path in color on the top line of the screen (enter the command as one line): [c:\] prompt $e[s$e[1;1f$e[41;1;37m$e[K[$z] $d Time: $t$h$h$h Path: $p$e[u$e[0;32m$n$g ═══ 3.3.61. PUSHD - Save current directory ═══ Purpose: Save the current disk drive and directory, optionally changing to a new drive and directory. Format: PUSHD [path ] path : The name of the new default drive and directory. See also: CD, CDD, DIRS, POPD, and Directory Navigation. Usage: PUSHD saves the current drive and directory on a "last in, first out" directory stack. The POPD command returns to the last drive and directory that was saved by PUSHD. You can use these commands together to change directories, perform some work, and return to the starting drive and directory. The DIRS command displays the contents of the directory stack. To save the current drive and directory, without changing directories, use the PUSHD command by itself, with no path. If a path is specified as part of the PUSHD command, the current drive and directory are saved and PUSHD changes to the specified drive and directory. If the path includes a drive letter, PUSHD changes to the specified directory on the new drive without changing the current directory on the original drive. This example saves the current directory and changes to C:\WORDP\MEMOS, then returns to the original directory: [c:\] pushd \wordp\memos [c:\wordp\memos] popd [c:\] When you use PUSHD to change to a directory on an HPFS drive, you must quote the path name if it contains whitespace or special characters. PUSHD can also change to a network drive and directory specified with a UNC name. If PUSHD cannot change to the directory you have specified it will attempt to search the CDPATH and the extended directory search database. You can also use wildcards in the path to force an extended directory search. Read the section on Directory Navigation for complete details on these and other directory navigation features. Directory changes made with PUSHD are also recorded in the directory history list and can be displayed in the directory history window. The directory stack can hold up to 511 characters, or between 20 and 40 typical entries (depending on the length of the names). If you exceed this limit, the oldest entry is removed before adding a new entry. The /N option available in CD and CDD to disable extended directory searches is not available in PUSHD. To disable extended searches when using PUSHD, save the current directory with PUSHD (without parameters) and then use CDD /N to change directories, for example: pushd cdd /n testdir ═══ 3.3.62. QUERYBOX - Popup dialog for input ═══ Purpose: Use a dialog box to get an input string from the user and save it in an environment variable. Format: QUERYBOX /E /Ln ["title"] prompt %%varname title: Text for the title bar of the dialog box. prompt: Text that will appear inside the dialog box. box. varname : Variable name where the input will be saved. /E (dit existing value) /L (maximum Length) See also: INKEY, INPUT, and MSGBOX. Usage: QUERYBOX displays a dialog box with a prompt, an optional title, and a string input field. Then it waits for your entry, and places any characters you type into an environment variable. QUERYBOX is normally used in batch files and aliases to get string input. QUERYBOX is similar to INPUT, except that it appears as a popup dialog box. If you prefer to work within the command line window, see the INKEY and INPUT commands. Standard command-line editing keys may be used to edit the input string as it is entered. All characters entered up to, but not including, the carriage return are stored in the variable. This example prompts for a string and store it in the variable NAME: querybox "File Name" Enter a name: %%name If you press Ctrl-C or Ctrl-Break while QUERYBOX is waiting for input, execution of an alias will be terminated, and execution of a batch file will be suspended while you are asked whether to cancel the batch job. A batch file can handle Ctrl-C and Ctrl-Break itself with ON BREAK. Options: /E (Edit existing value) Allows you to edit an existing value. If there is no existing value for varname, QUERYBOX allows you to enter a new value. /Ln (Length) Sets the maximum number of characters which QUERYBOX will accept to "n". ═══ 3.3.63. QUIT - Exit batch file ═══ Purpose: Terminate the current batch file. Format: QUIT [value ] value : The numeric exit code to Take Command or to the previous batch file. See also: CANCEL. Usage: QUIT provides a simple way to exit a batch file before reaching the end of the file. If you QUIT a batch file called from another batch file, you will be returned to the previous file at the line following the original CALL. This example batch file fragment checks to see if the user entered "quit" and exits if true. input Enter your choice : %%option if "%option" == "quit" quit QUIT only ends the current batch file. To end all batch file processing, use the CANCEL command. If you specify a value, QUIT will set the ERRORLEVEL or exit code to that value. For information on exit codes see the IF command, and the %? variable. You can also use QUIT to terminate an alias. If you QUIT an alias while inside a batch file, QUIT will end both the alias and the batch file and return you to the command prompt or to the calling batch file. ═══ 3.3.64. RD - Remove subdirectory ═══ Purpose: Remove one or more subdirectories. Format: RD path... or RMDIR path... path : The name of one or more subdirectories to remove. See also: MD. File Selection: Supports extended wildcards, ranges, multiple file names, and include lists. Usage: RD and RMDIR are synonyms. You can use either one. RD removes directories from the directory tree. For example, to remove the subdirectory MEMOS from the subdirectory WP, you can use this command: [c:\] rd \wp\memos Before using RD, you must delete all files and subdirectories (and their files) in the path you want to remove. Remember to remove hidden and read-only files as well as normal files (you can use DEL /Z to delete hidden and read-only files). You cannot use wildcards in the path. When removing a directory on an HPFS drive, you must quote any path which contains whitespace or special characters. If RD deletes one or more directories, they will be deleted automatically from the extended directory search database. You cannot remove the root directory, the current directory (.), any directory above the current directory in the directory tree, or any directory in use by another process. ═══ 3.3.65. REBOOT - Reboot or shutdown the computer ═══ Purpose: Do a system reboot. Format: REBOOT [/S /V] /S(hutdown) /V(erify) Usage: REBOOT will restart your computer. It normally performs a warm reboot, which is comparable to pressing Ctrl-Alt-Delete. The following example prompts you to verify the reboot, then does a warm boot: [c:\] reboot /v REBOOT defaults to performing a warm boot, with no prompting. REBOOT flushes the disk buffers, resets the drives, and waits one second before rebooting, to allow disk caching programs to finish writing any cached data. Take Command issues the proper commands to shut down OS/2 before rebooting. Options: /S (Shutdown) Shut down the system, but do not reboot. This option is equivalent to clicking the "Shutdown" choice on the OS/2 Workplace Shell popup menu. /V (Verify) Prompt for confirmation (Y or N) before rebooting or taking the action specified by other REBOOT options. ═══ 3.3.66. REM - Add comment to batch file ═══ Purpose: Put a comment in a batch file. Format: REM [comment ] comment : The text to include in the batch file. Usage: The REM command lets you place a remark or comment in a batch file. Batch file comments are useful for documenting the purpose of a batch file and the procedures you have used. For example: rem This batch file provides a rem menu-based system for accessing rem word processing utilities. rem rem Clear the screen and get selection cls REM must be followed by a space or tab character and then your comment. Comment lines can be up to 1,023 characters long. Take Command will normally ignore everything on the line after the REM command, including quote characters, redirection symbols, and other commands (see below for the exception to this rule). If ECHO is ON, the comment is displayed. Otherwise, it is ignored. If ECHO is ON and you don't want to display the line, preface the REM command with an at sign [@]. You can also place a comment in a batch file by starting the comment line with two colons [::]. In essence this creates a batch file "label" without a valid label name. Such comments are processed slightly faster than those entered with REM, because they do not require the command processor to handle a command. When debugging a batch file, you may find it convenient to use REM to temporarily disable certain commands. Simply add "REM " at the start of any command to convert it temporarily to a comment. You can use REM to create a zero-byte file if you use a redirection symbol immediately after the REM command. For example, to create the zero-byte file C:\FOO: [c:\] rem>foo (This capability is included for compatibility with traditional command processors. A simpler method for creating a zero-byte file with Take Command is to use >filename as a command, with no actual command before the [>] redirection character.) ═══ 3.3.67. REN - Rename files ═══ Purpose: Rename files or subdirectories. Format: REN [/A:[[-]rhsda] /E /N /P /Q /S /T] old_name... new_name or RENAME [/A:[[-]rhsda] /E /N /P /Q /S /T] old_name... new_name old_name : Original name of the file(s) or subdirectory. new_name : New name to use, or new path on the same drive. /A: (Attribute select) /Q(uiet) /E (No error messages) /S(ubdirectory) /N(othing) /T(otal) /P(rompt) See also: COPY and MOVE. File Selection: Supports extended wildcards, ranges, multiple file names, and include lists. Usage: REN and RENAME are synonyms. You may use either one. REN lets you change the name of a file or a subdirectory, or move one or more files to a new subdirectory on the same drive. (If you want to move files to a different drive, use MOVE.) In its simplest form, you simply give REN the old_name of an existing file or subdirectory and then a new_name. The new_name must not already exist -- you can't give two files the same name (unless they are in different directories). The first example renames the file MEMO.TXT to MEM.TXT. The second example changes the name of the \WORD directory to \WP: [c:\] rename memo.txt mem.txt [c:\] rename \word \wp If you use REN to rename a directory, the extended directory search database will be automatically updated to reflect the change. When you rename files on an HPFS drive, you must quote any file names which contain whitespace or special characters. You can also use REN to rename a group of files that you specify with wildcards, as multiple files, or in an include list. When you do, the new_name must use one or more wildcards to show what part of each filename to change. Both of the next two examples change the extensions of multiple files to .SAV: [c:\] ren config.sys autoexec.bat tcstart.btm *.sav [c:\] ren *.txt *.sav REN can move files to a different subdirectory on the same drive. When it is used for this purpose, REN requires one or more filenames for the old_name and a directory name for the new_name: [c:\] ren memo.txt \wp\memos\ [c:\] ren oct.dat nov.dat \data\save\ The final backslash in the last two examples is optional. If you use it, you force REN to recognize the last argument as the name of a directory, not a file. The advantage of this approach is that if you accidentally mistype the directory name, REN will report an error instead of renaming your files in a way that you didn't intend. Finally, REN can move files to a new directory and change their name at the same time if you specify both a path and file name for new_name. In this example, the files are renamed with an extension of .SAV as they are moved to a new directory: [c:\] ren *.dat \data\save\*.sav Also, you cannot rename a subdirectory to a new location on the directory tree. REN does not change a file's attributes. The new_namefile(s) will have the same attributes as old_name. Options: /A: (Attribute select) Select only those files that have the specified attribute(s) set. Preceding the attribute character with a hyphen [-] will select files that do not have that attribute set. The colon [:] after /A is required. The attributes are: R Read-only H Hidden S System D Subdirectory A Archive If no attributes are listed at all (e.g., REN /A: ...), REN will select all files and subdirectories including hidden and system files. If attributes are combined, all the specified attributes must match for a file to be selected. For example, /A:RHS will select only those files with all three attributes set. /E (No error messages) Suppress all non-fatal error messages, such as "File Not Found." Fatal error messages, such as "Drive not ready," will still be displayed. This option is most useful in batch files. /N (Nothing) Do everything except actually rename the file(s). This option is useful for testing what a REN command will actually do. /P (Prompt) Prompt the user to confirm each rename operation. Your options at the prompt are explained in detail under Page and File Prompts. /Q (Quiet) Don't display filenames or the number of files renamed. This option is most often used in batch files. See also /T. /S (Subdirectory) Normally, you can rename a subdirectory only if you do not use any wildcards in the new_name. This prevents subdirectories from being renamed inadvertently when a group of files is being renamed with wildcards. /S will let you rename a subdirectory even when you use wildcards. /S does not cause REN to process files in the current directory and all subdirectories as it does in some other file processing commands. To rename files throughout a directory tree, use a GLOBAL REN. /T (Total) Don't display filenames as they are renamed, but report the number of files renamed. See also /Q. ═══ 3.3.68. RETURN - Return from GOSUB ═══ Purpose: Return from a GOSUB (subroutine) in a batch file. Format: RETURN [value] value : The exit code from 0 to 255 to return to the command processor or to the previous batch file. See also: GOSUB. Usage: Take Command allows subroutines in batch files. A subroutine begins with a label (a colon followed by one or more words) and ends with a RETURN command. The subroutine is invoked with a GOSUB command from another part of the batch file. When a RETURN command is encountered the subroutine terminates, and execution of the batch file continues on the line following the original GOSUB. If RETURN is encountered without a GOSUB, Take Command will display a "Missing GOSUB" error. The following batch file fragment calls a subroutine which displays the files in the current directory: echo Calling a subroutine gosub subr1 echo Returned from the subroutine quit :subr1 dir /a/w return If you specify a value, RETURN will set the ERRORLEVEL or exit code to that value. For information on exit codes see the IF command, and the %? variable. ═══ 3.3.69. SCREEN - Position cursor ═══ Purpose: Position the cursor on the screen and optionally display a message. Format: SCREEN row column [text] row : The new row location for the cursor. column : The new column location for the cursor. text : Optional text to display at the new cursor location. See also: ECHO, SCRPUT, TEXT, and VSCRPUT. Usage: SCREEN allows you to create attractive screen displays in batch files. You use it to specify where a message will appear on the screen. You can use SCREEN to create menu and other similar displays, logos, etc. The following batch file fragment displays a menu: @echo off cls screen 3 10 Select a number from 1 to 4: screen 6 20 1 - Word Processing ... SCREEN does not change the screen colors. To display text in specific colors, use SCRPUT or VSCRPUT. SCREEN always leaves the cursor at the end of the displayed text. The row and column values are zero-based, so on a 25 line by 80 column display, valid rows are 0 - 24 and valid columns are 0 - 79. The maximum row value is determined by the current height of the Take Command window. The maximum column value is determined by the virtual screen width. SCREEN checks for a valid row and column, and displays a "Usage" error message if either value is out of range. You can also specify the row and column as offsets from the current cursor position. Begin the value with a plus sign [+] to move the cursor down or to the right, or with a minus sign [-] to move the cursor up or to the left. This example prints a string 3 lines above the current position, in absolute column 10: screen -3 10 Hello, World! If you specify 999 for the row, SCREEN will center the text vertically on the display. If you specify 999 for the column, SCREEN will center the text horizontally. This example prints a message at the center of the Take Command window: screen 999 999 Hello, World ═══ 3.3.70. SCRPUT - Display text in color ═══ Purpose: Position text on the screen and display it in color. Format: SCRPUT row col [BRIght] fg ON [BRIght] bg text row: Starting row col: Starting column fg: Foreground text color bg: Background text color text: The text to display See also: ECHO, SCREEN, TEXT, and VSCRPUT. Usage: SCRPUT allows you to create attractive screen displays in batch files. You use it to specify where a message will appear on the screen and what colors will be used to display the message text. You can use SCRPUT to create menu displays, logos, etc. SCRPUT works like SCREEN, but allows you to specify the display colors. See Colors and Color Names for details about colors. The row and column are zero-based, so on a 25 line by 80 column display, valid rows are 0 - 24 and valid columns are 0 - 79. The maximum row is determined by the current height of the Take Command window; the maximum column is determined by the current virtual screen width. SCRPUT displays an error if either the row or column is out of range. You can also specify the row and column as offsets from the current cursor position. Begin the value with a plus sign [+] to move down the specified number of rows or to the right the specified number of columns, or with a minus sign [-] to move up or to the left. If you specify 999 for the row, SCRPUT will center the text vertically in the Take Command window. If you specify 999 for the column, SCRPUT will center the text horizontally. SCRPUT does not move the cursor when it displays the text. The following batch file fragment displays part of a menu, in color: cls white on blue scrput 6 20 bri red on blu 1 - Word Processing scrput 7 20 bri yel on blu 2 - Spreadsheet ═══ 3.3.71. SELECT - Select files for a command ═══ Purpose: Interactively select files for a command. Format: SELECT [/A[[:][-]rhsda] /E /H /I"text" /J /L /O[:] [-]adeginrsu /T:acw /Z] [command ] ... (files ...)... command : The command to execute with the selected files. files : The files from which to select. File names may be enclosed in either parentheses or square brackets. The difference is explained below. /A(ttribute select) /J(ustify names) /D(isable color coding) /L(ower case) /E (use upper case) /O(rder) /H(ide dots) /T(ime) /I (match descriptions) /Z (use FAT format) File Selection: Supports extended wildcards, ranges, multiple file names, and include lists. Ranges must appear immediately after the SELECT keyword. Usage: SELECT allows you to select files for internal and external commands by using a full-screen "point and shoot" display. You can have SELECT execute a command once for each file you select, or have it create a list of files for a command to work with. The command can be an internal command, an alias, an external command, or a batch file. If you use parentheses around the files, SELECT executes the command once for each file you have selected. During each execution, one of the selected files is passed to the command as an argument. If you use square brackets around files, the SELECTed files are combined into a single list, separated by spaces. The command is then executed once with the entire list presented as part of its command-line arguments. Using the SELECT File List When you execute the SELECT command, the file list is displayed in a full- window format which includes a top-line status bar and shows the command to be executed, the number of files marked, and the number of Kbytes in those files. SELECT uses the cursor up, cursor down, PgUp, and PgDn keys to scroll through the file list. You can also use character matching to find specific files, just as you can in any popup window. While the file list is displayed you can enter any of the following keys to select or unselect files, display files, execute the command, or exit: + or space Select a file, or unselect a marked file. - Unselect a marked file. * Reverse all of the current marks (except those on subdirectories). If no files have been marked you can use * to mark all of the files. / Unselect all files. Enter Execute the command with the marked files, or with the currently highlighted file if no files have been marked. Esc Skip the files in the current display and go on to the next file specification inside the parentheses or brackets (if any). Ctrl-C Cancel the current SELECT command entirely. or Ctrl-Break On FAT drives the file list is shown in standard FAT directory format, with names at the left an descriptions at the right. On HPFS drives the format is similar but more space is allowed for the name, and the description is not shown. In this format long names are truncated if they do not fit in the allowable space. For a short-name format (including descriptions) on HPFS drives, use the /Z switch. When displaying descriptions in the short filename format, SELECT adds a right arrow [] at the end of the line if the description is too long to fit on the screen. This symbol will alert you to the existence of additional description text. You can use the left and right arrow keys to scroll the description area of the screen horizontally and view the additional text. You can set the default colors used by SELECT on the Commands page of the configuration notebook, or with the SelectColors directive in the TCMDOS2.INI file. If SelectColors is not used, the SELECT display will use the current default colors. Creating SELECT Commands In the simplest form of SELECT, you merely specify the command and then the list of files from which you will make your selection(s). For example: [c:\] select copy (*.com *.exe) a:\ will let you select from among the .COM files on the current drive, and will then invoke the COPY command to copy each file you select to drive A:. After the .COM files are done, the operations will be repeated for the .EXE files. If you want to select from a list of all the .COM and .EXE files mixed together, create an include list inside the parentheses by inserting a semicolon: [c:\] select copy (*.com;*.exe) a:\ Finally, if you want the SELECT command to send a single list of files to COPY, instead of invoking COPY once for each file you select, put the file names in square brackets instead of parentheses: [c:\] select copy [*.com;*.exe] a:\ If you use brackets, you have to be sure that the resulting command (the word COPY, the list of files, and the destination drive in this example) does not exceed the command line length limit of 1,023 characters for all commands. The current line length is displayed by SELECT while you are marking files to help you to conform to these limits. The parentheses or brackets enclosing the file name(s) can appear anywhere within the command; SELECT assumes that the first set of parentheses or brackets it finds is the one containing the list of files from which you wish to make your selection. When you use SELECT on an HPFS drive, you must quote any file names inside the parentheses which contain whitespace or special characters. For example, to copy selected files from the "Program Files" directory to the E:\SAVE directory: [c:\] select copy ("Program Files\*.*") e:\save\ File names passed to the command will be quoted automatically if they contain whitespace or special characters. The list of files from which you wish to select can be further refined by using date, time, size, and file exclusion ranges. The range(s) must be placed immediately after the word SELECT. If the command is an internal command that supports ranges, an independent range can also be used in the command itself. You cannot use command grouping to make SELECT execute several commands, because SELECT will assume that the parentheses are marking the list of files from which to select, and will display an error message or give incorrect results if you try to use parentheses for command grouping instead. (You can use a SELECT command inside command grouping parentheses, you just can't use command grouping to specify a group of commands for SELECT to execute.) Advanced Topics If you don't specify a command, the selected filename(s) will become the command. For example, this command defines an alias called UTILS that selects from the executable files in the directory C:\UTIL, and then executes them in the order marked: [c:\] alias utils select (c:\util\*.com;*.exe;*.btm;*.bat) If you want to use filename completion to enter the filenames inside the parentheses, type a space after the opening parenthesis. Otherwise, the command-line editor will treat the open parenthesis as the first character of the filename. With the /I option, you can select files based on their descriptions. SELECT will display files if their description matches the text after the /I switch. The search is not case sensitive. You can use wildcards and extended wildcards as part of the text. When sorting file names and extensions for the SELECT display, Take Command normally assumes that sequences of digits should be sorted numerically (for example, the file DRAW2 would come before DRAW03 because 2 is numerically smaller than 03), rather than strictly alphabetically (where DRAW2 would come second because "2" comes after "0"). You can defeat this behavior and force a strict alphabetic sort with the /O:a option. Options: /A (Attribute select) Select only those files that have the specified attribute(s) set. Preceding the attribute character with a hyphen [-] will select files that do not have that attribute set. The colon [:] after /A is optional. The attributes are: R Read-only H Hidden S System D Subdirectory A Archive If no attributes are listed at all (e.g., SELECT /A ...), SELECT will display all files and subdirectories including hidden and system files. If attributes are combined, all the specified attributes must match for a file to be included in the listing. For example, /A:RHS will display only those files with all three attributes set. /E (use upper case) Display filenames in upper case; also see SETDOS /U and the UpperCase directive in the TCDMOS2.INI file. /H (Hide dots) Suppress the display of the "." and ".." directories /I (match descriptions) Display filenames by matching text in their descriptions. The text can include wildcards and extended wildcards. The search text must be enclosed in quotation marks. You can select all filenames that have a description with /I"[?]*", or all filenames that do not have a description with /I"[]". /J (Justify names) Justify (align) filename extensions and display them in the traditional format. /L (Lower case) Display file and directory names in lower case; also see SETDOS /U and the UpperCase directive in the TCMDOS2.INI file. /O (Order) Set the sort order for the files. The order can be any combination of the following options: - Reverse the sort order for the next option a Sort in ASCII order, not numerically, when there are digits in the name d Sort by date and time (oldest first); for HPFS drives also see /T e Sort by extension g Group subdirectories first, then files i Sort by file description n Sort by filename (this is the default) r Reverse the sort order for all options s Sort by size u Unsorted /T:acw (Time display) Specify which of the date and time fields on an HPFS drive should be displayed and used for sorting: a last access date and time c creation date and time w last write date and time (default) /Z Display HPFS filenames in the traditional FAT format, with the filename at the left and the description at the right. Long names will be truncated to 12 characters; if the name is longer than 12 characters, it will be followed by a right arrow []. ═══ 3.3.72. SET - Set environment variables ═══ Purpose: Display, create, modify, or delete environment variables. Format: SET [/P /R file...] [name [=][value]] file : One or more files containing variable definitions. name : The name of the environment variable to define or modify. value : The new value for the variable. /R(ead from file) /P(ause) See also: ESET and UNSET. Usage: Every program and command inherits an environment, which is a list of variable names, each of which is followed by an equal sign and some text. Many programs use entries in the environment to modify their own actions. Take Command itself uses several environment variables. You can also create or modify environment variables with the Environment dialog. The dialog allows you to enter the variable name and value into separate fields in a dialog box, rather than using the SET command. All of the information in this section also applies to variables defined via the dialog, unless otherwise noted. If you simply type the SET command with no options or arguments, it will display all the names and values currently stored in the environment. Typically, you will see an entry called PATH, an entry called CMDLINE, and whatever other environment variables you and your programs have established: [c:\] set PATH=C:\;C:\OS2;C:\OS2\SYSTEM;C:\UTIL CMDLINE=C:\TCMD201\TCSTART.CMD To add a variable to the environment, type SET, a space, the variable name, an equal sign, and the value: [c:\] set mine=c:\finance\myfiles The variable name is converted to upper case by Take Command. The text after the equal sign will be left just as you entered it. If the variable already exists, its value will be replaced with the new text that you entered. Normally you should not put a space on either side of the equal sign. A space before the equal sign will become part of the name ; a space after the equal sign will become part of the value. If you use SET to create a variable with the same name as one of the Take Command internal variables, you will disable the internal variable. If you later execute a batch file or alias that depends on that internal variable, it may not operate correctly. To display the contents of a single variable, type SET plus the variable name: [c:\] set mine You can edit environment variables with the ESET command. To remove variables from the environment, use UNSET, or type SET plus a variable name and an equal sign: [c:\] set mine= The variable name is limited to a maximum of 80 characters. The name and value together cannot be longer than 1,023 characters. The size of the environment is set automatically and increased as necessary as you add variables. You do not need to specify the size as you do under 4DOS or some traditional command processors. Take Command for OS/2 supports the "pseudo-variables" BeginLIBPath and EndLIBPath introduced in OS/2 Warp. If you use either of these as a variable name, Take Command will pass the commands on to the operating system, but the variables will not appear in the environment. See your OS/2 documentation for more information about these variables. Options: /P (Pause) Wait for a key to be pressed after each screen page before continuing the display. Your options at the prompt are explained in detail under Page and File Prompts. /R (Read) Read environment variables from a file. This is much faster than loading variables from a batch file with multiple SET commands. Each entry in the file must fit within the 1,023-byte command-line length limit for Take Command. The file is in the same format as the SET display (i.e., name=value), so SET /R can accept as input a file generated by redirecting SET output. For example, the following commands will save the environment variables to a file, and then reload them from that file: set > varlist set /r varlist You can load variables from multiple files by listing the filenames individually after the /R. You can add comments to a variable file by starting the comment line with a colon [:]. If you are creating a SET /R file by hand, and need to create an entry that spans multiple lines in the file, you can do so by terminating each line, except the last, with an escape character. However, you cannot use this method to exceed the command- line length limit. ═══ 3.3.73. SETDOS - Set the Take Command configuration ═══ Purpose: Display or set the Take Command configuration. Format: SETDOS [/A? /C? /D? /E? /Fn.n /G?? /I+|- command /M? /N? /P? /R? S?:? /U? /V? /X[+|-]n /Y?] /A(NSI) /N(o clobber) /C(ompound) /P(arameter character) /D(escriptions) /S(hape of cursor) /E(scape character) /U(pper case) /F(@EVAL format) /V(erbose) /G (numeric separators) /X (expansion) /I(nternal commands) /Y (debug batch file) /M(ode for editing) Usage: SETDOS allows you to customize certain aspects of Take Command to suit your personal tastes or the configuration of your system. Each of these options is described below. You can display the value of all SETDOS options by entering the SETDOS command with no parameters. Most of the SETDOS options can be initialized when Take Command executes the TCMDOS2.INI file, and can also be changed from the configuration notebook. The name of the corresponding directive and the Configuration Notebook page is listed in square brackets [ ] with each option below; if none is listed, that option cannot be set from the TCMDOS2.INI file and / or the dialogs. You can also define the SETDOS options in your TCSTART or other startup file (see Automatic Batch Files), in aliases, or at the command line. Options: /A (ANSI) [ANSI, Display page] The ANSI option determines whether Take Command's ANSI support is enabled. /A1 enables ANSI string processing in the Take Command window; the default of /A0 disables ANSI strings. /C (Compound character) [CommandSep, Options 1 page] This option sets the character used for separating multiple commands on the same line. The default is the ampersand [&]. You cannot use any of the redirection characters (| > <), or the blank, tab, comma, or equal sign as the command separator. The command separator is saved by SETLOCAL and restored by ENDLOCAL. The following example changes the separator to a tilde [~]: [c:\] setdos /c~ If you want to share batch files or aliases among several 4DOS, 4OS2, 4NT, and Take Command, see the %+ variable, which retrieves the current command separator, and Special Character Compatibility for details on using compatible command separators for all the products you use. /D (Descriptions) [Descriptions and DescriptionName, Options 1 page] This option controls whether file processing commands like COPY, DEL, MOVE, and REN process file descriptions along with the files they belong to. /D1 turns description processing on, which is the default. /D0 turns description processing off. You can also use /D to set the name of the hidden file in each directory that contains file descriptions. To do so, follow /D with the filename in quotes: [c:\] setdos /d"files.bbs" Use this option with caution because changing the name of the description file will make it difficult to transfer file descriptions to another system. This option is provided for bulletin board system operators and others who have special needs. /E (Escape character) [EscapeChar, Options 1 page] This option sets the character used to suppress the normal meaning of the following character. Any character following the escape character will be passed unmodified to the command. The default escape character is a caret [^]. You cannot use any of the redirection characters (| > <) or the blank, tab, comma, or equal sign as the escape character. The escape character is saved by SETLOCAL and restored by ENDLOCAL. Certain characters (b, c, e, f, k, n, r, s, and t) have special meanings when immediately preceded by the escape character. If you want to share batch files or aliases among 4DOS, 4OS2, 4NT, and Take command, see the %= variable, which retrieves the current escape character, and Special Character Compatibility for details on using compatible escape characters for all the products you use. /F (Format for @EVAL) [EvalMax, EvalMin, Options 2 page] This option lets you set default decimal precision for the @EVAL variable function. The maximum precision is 16 digits to the left of the decimal point and up to 8 digits to the right of the decimal point. The general form of this option is /Fx.y, where the x value sets the minimum number of digits to the right of the decimal place and the y value sets the maximum number of digits. You can use =x,y instead of =x.y if the comma is your decimal separator. Both values can range from 0 to 8; if x is greater than y, it is ignored. You can specify either or both values: /F2.5, /F2, and /F.5 are all valid entries. See the @EVAL function if you want to set the precision for a single computation. /G (Numeric separators) [DecimalChar, ThousandsChar, Options 1 page] This option sets the decimal and thousands separator characters. The format is /Gxy where x is the new decimal separator and y is the new thousands separator. Both characters must be included. The only valid settings are /G., (period is the decimal separator, comma is the thousands separator); /G,. (the reverse); or /G0 to remove any custom setting and use the default separators associated with your current country code (this is the default). The decimal separator is used for @EVAL, numeric IF and IFF tests, version numbers, and other similar uses. The thousands separator is used for numeric output, and is skipped when performing calculations in @EVAL. /I (Internal) This option allows you to disable or enable internal commands. To disable a command, precede the command name with a minus [-]. To re-enable a command, precede it with a plus [+]. For example, to disable the internal LIST command to force Take Command to use an external command: [c:\] setdos /i-list /M (Mode) [EditMode, Command Line 1 page] This option controls the initial line editing mode. To start in overstrike mode at the beginning of each command line, use /M0 (the default). To start in insert mode, use /M1. /N (No clobber) [NoClobber, Options 1 page] This option controls output redirection). /N0 means existing files will be overwritten by output redirection (with >) and that appending (with >>) does not require the file to exist already. This is the default. /N1 means existing files may not be overwritten by output redirection, and that when appending the output file must exist. A /N1 setting can be overridden with the [!] character. /P (Parameter character) [ParameterChar, Options 1 page] This option sets the character used after a percent sign to specify all or all remaining command-line arguments in a batch file or alias (e.g., %$ or %n$). The default is the dollar sign [$]. If you want to share batch files or aliases among 4DOS, 4OS2, 4NT, and Take Command, see Special Character Compatibility for details on selecting compatible parameter characters for all the products you use. /S (Shape) [CursorOver, CursorIns, Command Line 1 page] The SHAPE option sets the cursor width. The format is /So:i where o is the width for overstrike mode, and i is the width for insert mode. The width is entered as a percentage of the total character width. The default values are 100:15 (a 100% or block cursor for overstrike mode, and a 15% or thin line cursor for insert mode). Because of the way video drivers remap the cursor shape, you may not get a smooth progression in the cursor size from 0% - 100%. You can retrieve the current cursor shape values with the %_CI and %_CO internal variables. /U (Upper) [UpperCase, Options 1 page] This option controls the default case (upper or lower) for filenames displayed by internal commands like COPY and DIR. /U0 displays file names in lower case (the default). /U1 displays file names in the traditional upper case. The /U setting is ignored for filenames on HPFS drives. Names on such drives are always displayed in the case in which they are stored. /V (Verbose) [BatchEcho, Options 1 page] The VERBOSE option controls the default for command echoing in batch files. /V0 disables echoing of batch file commands unless ECHO is explicitly set ON. /V1, the default setting, enables echoing of batch file commands unless ECHO is explicitly set OFF. /V2 forces echoing of all batch file commands, even if ECHO is set OFF or the line begins with an "@". This allows you to turn echoing on for a batch file without editing the batch file and removing the ECHO OFF command(s) within it. /V2 is intended for debugging, and can be set with SETDOS, but not with the BatchEcho directive in TCMDOS2.INI. See also Batch File Debugging and the /Y option below. /X[+|-]n(expansion and special characters) This option enables and disables alias and environment variable expansion, and controls whether special characters have their usual meaning or are treated as text. It is most often used in batch files to process text strings which may contain special characters. See Batch File String Processing for further details on string processing in batch files, and Internal and External Commands for details on alias expansion, variable expansion, and special characters. The features enabled or disabled by /X are numbered. All features are enabled when Take Command starts, and you can re-enable all features at any time by using /X0. To disable a particular feature, use /X-n, where n is the feature number from the list below. To re-enable the feature, use /X+n. To enable or disable multiple individual features, list their numbers in sequence after the + or - (e.g., /X-345 to disable features 3, 4, and 5). The features are: 1 All alias expansion. 2 Nested alias expansion only. 3 All variable expansion (environment variables and batch and alias parameters) 4 Nested variable expansion only. 5 Multiple commands, conditional commands, and piping (affects the command separator, ||, &&, |, and &). 6 Redirection (affects <, >, >&, >&>, etc.). 7 Quoting (double back-quotes [`] and double quotes ["]) and square brackets. 8 Escape character. If nested alias expansion is disabled, the first alias of a command is expanded but any aliases it invokes are not expanded. If nested variable expansion is disabled, each variable is expanded once, but variables containing the names of other variables are not expanded further. For example, to disable all features except alias expansion while you are processing a text file containing special characters: setdos /x-35678 ... [perform text processing here] setdos /x0 /Y (debug batch file) /Y1 enables the built-in batch file debugger. The debuggger allows you to "single-step" through a batch file line by line, with the file displayed in a popup window as it executes. For complete details on using the debugger see Batch File Debugging (this topic also covers additional debugging techniques which do not require stepping through each line individually). To start the debugger, insert a SETDOS /Y1 command at the beginning of the portion of the batch file you want to debug, and a SETDOS /Y0 command at the end. You cannot use the batch debugger with REXX files or EXTPROC files. It can only be used with normal Take Command batch files. You can also invoke SETDOS /Y1 from the prompt, but because the debugger is automatically turned off whenever the command processor returns to the prompt, you must enter the SETDOS command and the batch file name on the same line, for example: [c:\] setdos /y1 & mybatch.btm ═══ 3.3.74. SETLOCAL - Save the environment ═══ Purpose: Save a copy of the current disk drive, directory, environment, alias list, and special characters. Format: SETLOCAL See also: ENDLOCAL. Usage: SETLOCAL is used in batch files to save the default disk drive and directory, the environment, the alias list, and the command separator, escape character, parameter character, decimal separator, and thousands separator. You can then change their values and later restore the original values with ENDLOCAL. For example, this batch file fragment saves everything, removes all aliases so that user aliases will not affect batch file commands, changes the disk, changes the command separator, runs a program, and then restores the original values: setlocal unalias * cdd d:\test setdos /c~ program ~ echo Done! endlocal SETLOCAL and ENDLOCAL are not nestable within a batch file. However, you can have multiple SETLOCAL / ENDLOCAL pairs within a batch file, and nested batch files can each have their own SETLOCAL / ENDLOCAL. You cannot use SETLOCAL in an alias or at the command line. An ENDLOCAL is performed automatically at the end of a batch file if you forget to do so. If you invoke one batch file from another without using CALL, the first batch file is terminated, and an automatic ENDLOCAL is performed; the second batch file inherits the settings as they were prior to any SETLOCAL. ═══ 3.3.75. SHIFT - Shift batch parameters ═══ Purpose: Allows the use of more than 127 parameters in a batch file. Format: SHIFT [n | /n] n : Number of positions to shift. Usage: SHIFT is provided for compatibility with older batch files, where it was used to access more than 10 parameters. Take Command supports 128 parameters (%0 to %127), so you may not need to use SHIFT for batch files running exclusively under JP Software command processors. SHIFT moves each of the batch file parameters n positions to the left. The default value for n is 1. SHIFT 1 moves the parameter in %1 to position %0, the parameter in %2 becomes %1, etc. You can reverse a SHIFT by giving a negative value for n(i.e., after SHIFT -1, the former %0 is restored, %0 becomes %1, %1 becomes %2, etc.). SHIFT also affects the parameters %n$ (command-line tail) and %# (number of command arguments). For example, create a batch file called TEST.BAT: echo %1 %2 %3 %4 shift echo %1 %2 %3 %4 shift 2 echo %1 %2 %3 %4 shift -1 echo %1 %2 %3 %4 Executing TEST.BAT produces the following results: [c:\] test one two three four five six seven one two three four two three four five four five six seven three four five six If you add a slash before the value n, the value determines the postion at which to begin the shift. For example: shift /2 leaves parameters %0 and %1 unchanged, and moves the value of %3 to postion %2, %4 to %3, etc. The value after the slash cannot be negative. and shifts performed with the slash cannot be undone later in the batch file. ═══ 3.3.76. SHRALIAS - Retain global lists ═══ Purpose: Retains global command history, directory history, and alias lists in memory when the command processor is not running. Format: SHRALIAS [/U] /U(nload) Usage: When you close all Take Command sessions, the memory for the global command history, global directory history, and global alias list is released. If you want the lists to be retained in memory even when Take Command is not running, you need to execute SHRALIAS. The SHRALIAS command starts and initializes SHRALIAS.EXE, a small program which remains active and retains global lists when Take Command is not running. In order to start the program, SHRALIAS must be able to find SHRALIAS.EXE either in the same directory as Take Command, or in a directory in your path. You cannot run SHRALIAS.EXE directly, it must be run by the SHRALIAS command. Once SHRALIAS has been executed, the global lists will be retained in memory until you use SHRALIAS /U to unload the lists, or until you shut down your operating system. SHRALIAS will not work unless you have at least one copy of Take Command running with global alias, command history, and directory history lists enabled. If the required global lists are not found, SHRALIAS will display an error. If you start SHRALIAS from a temporary Take Command session which exits after starting SHRALIAS, the Take Command session may terminate and discard the shared lists before SHRALIAS can attach to them. In this case SHRALIAS.EXE will not be loaded. If you experience this problem, add a short delay with the DELAY command after SHRALIAS is loaded and before your session exits. For more information about global history and alias lists, see the relevant sections in Command History and Recall, Directory History Window, and the ALIAS command. Option: /U (Unload) Shuts down SHRALIAS.EXE. If SHRALIAS is not loaded again, the memory used by global command history, directory history, and alias lists will be released when the last copy of Take Command exits. ═══ 3.3.77. START - Start application in new session ═══ Purpose: Start a program in another session or window. Format: START ["program title"] [/B[G] /C /DOS[=optfile] /F[G] /FS /I /ICON=iconfile /INV /K /L /LA /LD /LH /MAX /MIN /N /PGM progname /PM /POS=row,col,width,height /TTY /WAIT /WIN /WIN3[=optfile] /WIN3S[=optfile]] [command] program title : Title to appear on title bar. optfile : Option settings file. iconfile : Name of icon (.ICO ) file. progname : Program name (not the session name). command : Command to be executed. /B[G] (background session) /LH (local history list) /C(lose when done) /MAX(imized) /DOS (DOS session) /MIN(imized) /F[G] (foreground session) /N(o command processor) /FS (full screen) /PGM (program name) /I(nherit environment) /PM (PM application) /ICON (.ICO file) /POS(ition of window) /INV(isible) /TTY (run in TCMD window) /K(eep when done) /WAIT(for session to finish) /L(ocal lists) /WIN (dowed session) /LA (local aliases) /WIN3 (Windows enhanced mode) /LD (local dir history) /WIN3S (Windows standard mode) See also: DETACH. Usage: START is used to begin a new OS/2 session, and optionally run a program in that session. If you use START with no parameters, it will begin a new Take Command session. If you add a command, START will begin a new session or window and execute that command. START will return to the Take Command prompt immediately (or continue a batch file), without waiting for the program to complete, unless you use /WAIT. The program title, if it is included, will appear on the title bar, and on the OS/2 Window List. The program title must be enclosed in quotation marks and cannot exceed 60 characters. If the program title is omitted, the program name will be used as the title. START always assumes that the first quoted string on the command line is the program title; if there is a second quoted string it is assumed to be the command. As a result, if the name of the program you are starting is a long filename containing whitespace (and must therefore be quoted), you cannot simply place it on the command line. If you do, as the first quoted string it will be interpreted as the program title, not the command. To address this, use the /PGM switch to indicate explicitly that the quoted string is the program name, or include a title before the program name. For example, to start the program "C:\Program Files\Proc.Exe" you could use either of the first two commands below, but the third command would not work: [c:\] start /PGM "C:\Program Files\Proc.Exe" [c:\] start "test" "C:\Program Files\Proc.Exe" [c:\] start "C:\Program Files\Proc.Exe" /MAX, /MIN, and /POS allow you to start a character-mode windowed session in a maximized window, a minimized window, or a window with a specified position and size. The default is to let the operating environment choose the position and size of the window. /C allows you to close the session when the command is finished (the default for graphical sessions); /K allows you to keep the session open and go to a prompt (the default for character mode sessions). Options: /BG (BackGround session) The session is started as a background session. /BG may be abbreviated to /B. /C (Close) The session or window is closed when the application ends. /DOS[=filename] (DOS session) Start a DOS session. If you include the =filename, OS/2 will load DOS settings from the specified file. You can also alter the DOS settings for a session with environment variables of the form DosSetting.name=value, without using a settings file. Starting a session with specific DOS settings is an undocumented feature which was implemented within OS/2 with little error checking. It is included in START because it substantially eases a complex task, but you must experiment carefully to ensure that the settings you select will work properly on the systems on which you plan to use them. Incorrect settings may be ignored, but they may also hang your session or stop the entire system. Be sure your experiments are not conducted while critical tasks are in process. Each line in the file must have a name, an equal sign [=], and a value. The names are those shown in OS/2's DOS Settings dialog box. Do not use spaces on either side of the equal sign. The names in the DOS Settings dialog box will vary depending on the device drivers and other settings in your CONFIG.SYS file, though many are available on all systems. You must ensure that the names you use are valid for the systems on which you use them. For example, if you replace IBM's COM.SYS and VCOM.SYS with different communications drivers, the COM_ settings will probably not be valid for the new drivers. If you have a settings file which contains settings defined by a particular driver, and use it on a system where the corresponding driver is not loaded, the results are undefined. The values in your settings file must be numeric for settings which show a numeric value under DOS Settings (e.g., DOS_FILES=30), and must be text strings for settings shown with a string (e.g., DOS_SHELL=C:\4DOS.COM C:\4DOS /P). Strings should be entered without trailing blanks. For values shown as multiple choice on the DOS Settings page you must specify a numeric value, typically "0" for Off and "1" for On (e.g., DOS_HIGH=1). Items with choices other than Off and On may use different values, or may not work at all; experimentation is usually required to find out what works. Using strings for choice items (e.g., DOS_HIGH=ON) will not work, and can hang your system. This is due to the internal operation of OS/2, and is not a problem in Take Command. A typical DOS settings file might look like this: DOS_FILES=30 DOS_HIGH=1 DOS_SHELL=C:\4DOS\4DOS.COM C:\4DOS /P MOUSE_EXCLUSIVE_ACCESS=0 VIDEO_FASTPASTE=1 You can include comments in a settings file by beginning any line with a colon [:]. /FG (ForeGround session) Start the session as the foreground session. /FG may be abbreviated to /F. /FS (Full Screen) Start the session as a full-screen session. /I (Inherit environment) Inherit the default environment specified in CONFIG.SYS, if any, rather than the current environment. /ICON=filenameUse the specified icon file. If you don't use /ICON, the displayed icon will be the one found or assigned by OS/2. /INV (Invisible) Start the session or window as invisible. No icon will appear and the session will only be accessible through the Window List. /K (Keep session or window at end) Continue the session or window after the application program ends. Use the EXIT command to end the session. /L (Local lists) Start Take Command with local alias, history, and directory history lists. This option combines the effects of /LA, /LD, and /LH (below). /LA (Local Alias list) Start Take Command with a local alias list. See ALIAS for information on local and global aliases. /LD (Local Directory history) Start Take Command with a local directory history list. See Directory History Window for more information. /LH (Local History list) Start Take Command with a local history list. See Command History and Recall for information on local and global history lists. /MAX (Maximized) Start the session or window maximized. /MIN (Minimized) Start the session or window minimized. /N (No command processor) Start an OS/2 program directly, without a command processor. The command cannot be an internal command or batch file. This is the default for PM applications. /PGM (Program name) The string following this option is the program name. Use /PGM to allow START to differentiate between a quoted long filename and a quoted title for the session. /PM (Presentation Manager) Start a program in the PM session. /POS (Position) Start the window at the specified screen position. The syntax is /POS=x, y, width, height where the values are specified in pixels or pels. x and y refer to the position of the bottom left corner of the window relative to the bottom left corner of the screen. /TTY (TTY Application) Run a DOS or character-mode OS/2 program under Take Command's TTY Application support. Use this option to force an application to run under Take Command's TTY application support, even if the program has not been specifically enabled as a TTY application. For complete details on TTY applications see your Introduction and Installation Guide, and Starting Character-Mode Applications. /WAIT Wait for the new session or window to finish before continuing. This switch is ignored when starting DOS programs under WIN-OS/2, because there is no way for Take Command to determine when a DOS program run under WIN-OS/2 has finished. /WIN (Windowed) Start the session in a window. /WIN3[=filename] (Windows enhanced mode) Run the program in an enhanced-mode Windows 3.x session. The session will run seamless (on the OS/2 desktop). (To start a Windows application in full-screen mode, use /FS rather than /WIN3.) You can include an equal sign and the name of an options file to set options for the specific session and application (see /DOS= above for details). The setting names in the file should be taken from those shown in OS/2's WIN-OS/2 Settings dialog box. /WIN3S[=filename] (Windows standard mode) Equivalent to /WIN3, but runs the program in standard mode rather than enhanced mode. ═══ 3.3.78. SWITCH - Select commands to execute ═══ Purpose: Select commands to execute based on a value. Format: SWITCH expression CASE value1 [.OR. value2] ... commands CASE value3 commands [DEFAULT commands] ENDSWITCH expression : An environment variable, internal variable, variable function, text string, or a combination of these elements, that is used to select a group of commands. value1, value2, etc. : A value to test or multiple values connected with .OR. commands : One or more commands to execute if the expression matches the value. If you use multiple commands, they must be separated by command separators or placed on separate lines of a batch file. See also: IF and IFF Usage: SWITCH can only be used in batch files. It allows you to select a command or group of commands to execute based on the possible values of a variable or a combination of variables and text. The SWITCH command is always followed by an expression created from environment variables, internal variables, variable functions, and text strings, and then by a sequence of CASE statements matching the possible values of that expression. If one of the values in a CASE statement matches the expression, the commands following that CASE statement are executed, and all subsequent CASE statements and the commands which follow them are ignored. If no matches are found, the commands following the optional DEFAULT statement are executed. If there are no matches and there is no DEFAULT statement, no commands are executed by SWITCH. After all of the commands following the CASE or DEFAULT statement are executed, the batch file continues with the commands that follow ENDSWITCH. You must include a command separator or new line after the expression, before each CASE or DEFAULT statement, before each command, and before ENDSWITCH. You can link values in a CASE statement only with .OR. (but not with .AND. or .XOR.). For example, the following batch file fragment displays one message if the user presses A, another if user presses B or C, and a third if the user presses any other key: inkey Enter a keystroke: %%key switch %key case A echo It's an A case B .or. C echo It's either B or C default echo It's not A, B, or C endswitch In the example above, the value of a single environment variable was used for the expression. You will probably find that this is the best method to use in most situations. However, you can use other kinds of expressions if necessary. The first example below selects a command to execute based on the length of a variable, and the second bases the action on a quoted text string stored in an environment variable: switch %@len[%var1] case 0 echo Missing var1 case 1 echo Single character ... endswitch switch "%string1" case "This is a test" echo Test string case "The quick brown fox" echo It's the fox ... endswitch The SWITCH and ENDSWITCH commands must be on separate lines, and cannot be placed within a command group, or on the same line as other commands (this is the reason SWITCH cannot be used in aliases). However, commands within the SWITCH block can use command groups or the command separator in the normal way. SWITCH commands can be nested. You can exit from all SWITCH / ENDSWITCH processing by using GOTO to a line past the last ENDSWITCH. ═══ 3.3.79. TEE - "Tee" pipe fitting ═══ Purpose: Copy standard input to both standard output and a file. Format: TEE [/A] file... file : One or more files that will receive the "tee- d" output. /A(ppend) See also: Y and the redirection options. Usage: TEE is normally used to "split" the output of a program so that you can see it on the display and also save it in a file. It can also be used to capture intermediate output before the data is altered by another program or command. TEE gets its input from standard input (usually the piped output of another command or program), and sends out two copies: one goes to standard output, the other to the file or files that you specify. TEE is not likely to be useful with programs which do not use standard output, because these programs cannot send output through a pipe. For example, to search the file DOC for any lines containing the string "Take Command", make a copy of the matching lines in TC.DAT, sort the lines, and write them to the output file TCS.DAT (enter this on one line): [c:\] find "Take Command" doc | tee tc.dat | sort > tcs.dat If you are typing at the keyboard to produce the input for TEE, you must enter a Ctrl-Z to terminate the input. When using TEE with a pipe under Take Command, the programs on the two ends of the pipe run simultaneously, not sequentially as in 4DOS. See Piping for more information on pipes. Option: /A (Append) Append the output to the file(s) rather than overwriting them. ═══ 3.3.80. TEXT - Display text in batch file ═══ Purpose: Display a block of text in a batch file. Format: TEXT . . . ENDTEXT See also: ECHO, SCREEN, SCRPUT, and VSCRPUT. Usage: TEXT can only be used in batch files. The TEXT command is useful for displaying menus or multi-line messages. TEXT will display all subsequent lines in the batch file until terminated by ENDTEXT. Both TEXT and ENDTEXT must be entered as the only command on the line. To redirect the entire block of text, use redirection on the TEXT command itself, but not on the actual text lines or the ENDTEXT line. No environment variable expansion or other processing is performed on the lines between TEXT and ENDTEXT; they are displayed exactly as they are stored in the batch file. You can use a CLS or COLOR command to set the screen color before executing the TEXT command. The following batch file fragment displays a simple menu: @echo off & cls screen 2 0 text Enter one of the following: 1 - Spreadsheet 2 - Word Processing 3 - Utilities 4 - Exit endtext inkey /k"1234" Enter your selection: %%key ═══ 3.3.81. TIME - Set the system time ═══ Purpose: Display or set the current system time. Format: TIME [hh [:mm[:ss]]] [AM | PM] hh : The hour (0 - 23). mm : The minute (0 - 59). ss : The second (0 - 59). See also: DATE. Usage: If you don't enter any parameters, TIME will display the current system time and prompt you for a new time. Press Enter if you don't wish to change the time; otherwise, enter the new time:. [c:\] time Mon Dec 22, 1997 9:30:10 New time (hh:mm:ss): TIME defaults to 24-hour format, but you can optionally enter the time in 12- hour format by appending "a", "am", "p", or "pm" to the time you enter. For example, to enter the time as 9:30 am: [c:\] time 9:30 am OS/2 adds the system time and date to the directory entry for every file you create or modify. If you keep both the time and date accurate, you will have a record of when you last updated each file. ═══ 3.3.82. TIMER - Start or stop a stopwatch ═══ Purpose: TIMER is a system stopwatch. Format: TIMER [ON] [/1 /2 /3 /S] ON: Force the stopwatch to restart /1 (stopwatch #1) /3 (stopwatch #3) /2 (stopwatch #2) /S(plit) Usage: The TIMER command turns a system stopwatch on and off. When you first run TIMER, the stopwatch starts: [c:\] timer Timer 1 on: 12:21:46 When you run TIMER again, the stopwatch stops and the elapsed time is displayed: [c:\] timer Timer 1 off: 12:21:58 Elapsed time: 0:00:12.06 There are three stopwatches available (1, 2, and 3) so you can time multiple overlapping events. By default, TIMER uses stopwatch #1. TIMER is particularly useful for timing events in batch files. For example, to time both an entire batch file, and an intermediate section of the same file, you could use commands like this: rem Turn on timer 1 timer rem Do some work here rem Turn timer 2 on to time the next section timer /2 rem Do some more work echo Intermediate section completed rem Display time taken in intermediate section timer /2 rem Do some more work rem Now display the total time timer The smallest interval TIMER can measure depends on the operating system you are using, your hardware, and the interaction between the two. However, it should never be greater than .06 second. The largest interval is 23 hours, 59 minutes, 59.99 seconds. Options: /1 Use timer #1 (the default). /2 Use timer #2. /3 Use timer #3. /S (Split) Display a split time without stopping the timer. To display the current elapsed time but leave the timer running: [c:\] timer /s Timer 1 elapsed: 0:06:40.63 ON: Start the timer regardless of its previous state (on or off). Otherwise the TIMER command toggles the timer state (unless /S is used). ═══ 3.3.83. TITLE - Set window title ═══ Purpose: Change the window title. Format: TITLE "title" title: The new window title. See also: ACTIVATE and WINDOW. Usage: TITLE changes the text that appears in the caption bar at the top of the Take Command window. It is included for compatibility with traditional character- mode command processors (like CMD.EXE). You can also change the window title with the WINDOW command or the ACTIVATE command. To change the title of the current window to "Take Command Test": [c:\] title "Take Command Test" ═══ 3.3.84. TOUCH - Change date and time stamps ═══ Purpose: Change a file's date and time stamps. Format: TOUCH [/C /D[acw][mm-dd-yy] /E /F /Q /T[acw][hh:mm]] file... file : One or more files whose date and/or time stamps are to be changed. /C(reate file) /F(orce read-only files) /D(ate) /Q(uiet) /E (No error messages) /T(ime) File Selection: Supports extended wildcards, ranges, multiple file names, and include lists. Usage: TOUCH is used to change the date and / or time of a file. You can use it to be sure that particular files are included or excluded from an internal command, backup program, compiler MAKE utility , or other program that selects files based on their time and date stamps, or to set a group of files to the same date and time for consistency. TOUCH should be used with caution, and in most cases should only be used on files you create. Many programs depend on file dates and times to perform their work properly. In addition, many software manufacturers use file dates and times to signify version numbers. Indiscriminate changes to date and time stamps can lead to confusion or incorrect behavior of other software. TOUCH normally works with existing files, and will display an error if the file you specify does not exist, or has the read-only attribute set. To create the file if it does not already exist, use the /C switch. To force a date and time change for read-only files, use the /F switch. TOUCH displays the date, time, and full name of each file whose timestamp is modified. To disable this output, use /Q. If you don't specify a date or a time, TOUCH will default to the current date and time. For example, to set the time stamp of all .C files in the current directory to the current date and time: [d:\] touch *.c 6-12-97 11:13:58 D:\SOURCE\MAIN.C 6-12-97 11:13:58 D:\SOURCE\INIT.C ... If you specify a date but not a time, the time will default to the current time from your system clock. Similarly, if you specify a time but not a date, the date will be obtained from the system clock. On HPFS volumes, TOUCH sets the "modified" or "last write" date and time by default. By adding an a, c, or w to the /D or /T switch, you can set the last access, creation, or last write date and time stamps that are maintained for each file; see the Options section below for additional details. Options: /C (Create file) Create the file (as a zero-byte file) if it does not already exist. You cannot use wildcards with /C, but you can create multiple files by listing them individually on the command list. /D (Date) Specify the date that will be set for the selected files. If the date is not specified, TOUCH will use the current date. For HPFS files use /Da, /Dc, or /Dw, followed by the date, to specify the last access, creation, or last write date stamp. The date must be entered using the proper format for your current country settings. /E (No error messages) Suppress all non-fatal error messages, such as "File not found." Fatal error messages, such as "Drive not ready," will still be displayed. This option is most useful in batch files. /F (Force read-only files) Remove the read-only attribute from each file before changing the date and time, and restore it afterwards. Without /F, attempting to change the date and time on a read-only file will usually cause an error. /Q (Quiet) Do not display the new date and time and the full name for each file. /T (Time) Specify the time that will be set for the selected files in hh:mm format. If the time is not specified, TOUCH will use the current time. For HPFS files, you can use /Ta, /Tc, or /Tw, followed by the time, to specify the last access, creation, or last write time stamp. ═══ 3.3.85. TREE - Display directory tree ═══ Purpose: Display a graphical directory tree. Format: TREE [/A /B /F /H /P /S /T[:acw]] dir... dir : The directory to use as the start of the tree. If more than one directory is specified, TREE will display a directory tree for each. /A:(SCII) /P(ause) /B(are) /S (file size) /F(iles) /T(time and date) /H(idden directories) File Selection: Supports extended wildcards, ranges, multiple directory names, and include lists. Usage: The TREE command displays a graphical representation of the directory tree using standard or extended ASCII characters. For example, to display the directory structure on drive C: c:\ tree c:\ TREE uses the standard line drawing characters in the U.S. English extended ASCII character set. If your system is configured for a different country or language, or if you use a font which does not include these line drawing characters, the connecting lines in the tree display may not appear correctly on your screen. To correct the problem, use /A, or configure Take Command to use a font, such as System VIO, which contains standard extended ASCII characters. You can print the display, save it in a file, or view it with LIST by using standard redirection symbols. Be sure to review the /A option before attempting to print the TREE output. The options, discussed below, specify the amount of information included in the display. Options: /A (ASCII) Display the tree using standard ASCII characters. You can use this option if you want to save the directory tree in a file for further processing or print the tree on a printer which does not support the graphical symbols that TREE normally uses. /B (Bare) Display the full pathname of each directory, without any of the line-drawing characters. /F (Files) Display files as well as directories. If you use this option, the name of each file is displayed beneath the name of the directory in which it resides. /H (Hidden) Display hidden as well as normal directories. If you combine /H and /F, hidden files are also displayed. /P (Pause) Wait for a key to be pressed after each screen page before continuing the display. Your options at the prompt are explained in detail under Page and File Prompts. /S (Size) Display the size of each file. This option is only useful when combined with /F. /T (Time and date) Display the time and date for each directory. If you combine /T and /F, the time and date for each file will also be displayed. For HPFS files, the time and date of the last write will be shown by default. You can select a specific time and date stamp by using the following variations of /T: /T:a last access date and time (access time is not saved on LFN volumes) /T:c creation date and time /T:w last write date and time (default) ═══ 3.3.86. TYPE - Display a file ═══ Purpose: Display the contents of the specified file(s). Format: TYPE [/A:[[-]rhsda] /L /P] file... file : The file or list of files that you want to display. /A: (Attribute select) /P(ause) /L(ine numbers) See also: LIST. File Selection: Supports extended wildcards, ranges, multiple file names, and include lists. Usage: The TYPE command displays a file. It is normally only useful for displaying ASCII text files. Executable files (.COM and .EXE ) and many data files may be unreadable when displayed with TYPE because they include non-alphanumeric characters. To display the files MEMO1 and MEMO2: [c:\] type /p memo1 memo2 You can press Ctrl-S to pause TYPE's display and then any key to continue. To display text from the clipboard use CLIP: as the file name. CLIP: will not return any data if the clipboard does not contain text. You will probably find LIST to be more useful for displaying files on the screen. However, the TYPE /L command used with redirection is useful if you want to add line numbers to a file, for example: [c:\] type /l myfile > myfile.num Options: /A: (Attribute select) Select only those files that have the specified attribute(s) set. Preceding the attribute character with a hyphen [-] will select files that do not have that attribute set. The colon [:] after /A is required. The attributes are: R Read-only H Hidden S System D Subdirectory A Archive If no attributes are listed at all (e.g., TYPE /A: ...), TYPE will select all files and subdirectories including hidden and system files. If attributes are combined, all the specified attributes must match for a file to be selected. For example, /A:RHS will select only those files with all three attributes set. /L (Line numbers) Display a line number preceding each line of text. /P (Pause) Prompt after displaying each page. Your options at the prompt are explained in detail under Page and File Prompts. ═══ 3.3.87. UNALIAS - Remove aliases ═══ Purpose: Remove aliases from the alias list. Format: UNALIAS [/Q /R file...] alias... or UNALIAS * alias : One or more aliases to remove from memory. file : One or more files to read for alias definitions. /Q(uiet) /R(ead file) See also: ALIAS and ESET. Usage: Take Command maintains a list of the aliases that you have defined. The UNALIAS command will remove aliases from that list. You can remove one or more aliases by name, or you can delete the entire alias list by using the command UNALIAS *. For example, to remove the alias DDIR: [c:\] unalias ddir To remove all the aliases: [c:\] unalias * If you keep aliases in a file that can be loaded with the ALIAS /R command, you can remove the aliases by using the UNALIAS /R command with the same file name: [c:\] unalias /r alias.lst This is much faster than removing each alias individually in a batch file, and can be more selective than using UNALIAS *. You can also remove individual aliases with the Alias dialog. Options: /Q (Quiet) Prevents UNALIAS from displaying an error message if one or more of the aliases does not exist. This option is most useful in batch files, for removing a group of aliases when some of the aliases may not have been defined. /R (Read) Read the list of aliases to remove from a file. The file format should be the same format as that used by the ALIAS /R command. You can use multiple files with one UNALIAS /R command by placing the names on the command line, separated by spaces: [c:\] unalias /r alias1.lst alias2.lst ═══ 3.3.88. UNSET - Remove environment variables ═══ Purpose: Remove variables from the environment. Format: UNSET [/Q /R file...] name... or UNSET * file : One or more files containing variable definitions. name : One or more variables to remove from the environment. /Q(uiet) /R(ead from file) See also: ESET and SET. Usage: UNSET removes one or more variables from the environment. For example, to remove the environment variable CMDLINE: [c:\] unset cmdline If you use the command UNSET *, all of the environment variables will be deleted: [c:\] unset * You can also remove individual variables from the environment with the Environment dialog. UNSET can be used in a batch file, in conjunction with the SETLOCAL and ENDLOCAL commands, to clear the environment of variables that may cause problems for applications run from that batch file. For more information on environment variables, see the SET command and the general discussion of the environment. Use caution when removing environment variables, and especially when using UNSET *. Many programs will not work properly without certain environment variables; for example, Take Command uses PATH and CDPATH. Options: /Q (Quiet) Prevents UNSET from displaying an error message if one or more of the variables does not exist. This option is most useful in batch files, for removing a group of variables when some of the variables may not have been defined. /R (Read) Read environment variables to UNSET from a file. This much faster than using multiple UNSET commands in a batch file, and can be more selective than UNSET *. The file format should be the same format as that used by the SET /R command. ═══ 3.3.89. VER - Display version levels ═══ Purpose: Display the current command processor and operating system versions. Format: VER [/R] /R(evision level) Usage: Version numbers consist of a one-digit major version number, a period, and a one- or two-digit minor version number. VER uses the default decimal separator defined by the current country information. The VER command displays both version numbers: [c:\] ver Take Command for OS/2 2.03A OS/2 Version is 4.00 Option: /R (Revision level) Display the Take Command and OS/2 internal revision levels, plus your Take Command serial number and registered name. ═══ 3.3.90. VERIFY - Disk write verification ═══ Purpose: Enable or disable disk write verification or display the verification state. Format: VERIFY [ON | OFF] Usage: OS/2 maintains an internal verify flag. When the flag is on, OS/2 attempts to verify each disk write by making sure that the data written to the disk can be read back successfully into the computer. It does not compare the data in memory with the data actually placed on disk to fully verify the disk write process. If used without any parameters, VERIFY will display the state of the verify flag: [c:\] verify VERIFY is OFF VERIFY is off when the system boots up. Once it is turned on with the VERIFY ON command, it stays on until you use the VERIFY OFF command or until you reboot. Verification will slow your disk write operations slightly (the effect is not usually noticeable). ═══ 3.3.91. VOL - Display drive label ═══ Purpose: Display disk volume label(s). Format: VOL [d :] ... d: The drive or drives to search for labels. Usage: Each disk may have a volume label, created when the disk is formatted or with the external LABEL command. Also, every floppy disk formatted with DOS version 4.0 or above or with OS/2 has a volume serial number. The VOL command will display the volume label and, if available, the volume serial number of a disk volume. If the disk doesn't have a volume label, VOL will report that it is "unlabeled." If you don't specify a drive, VOL displays information about the current drive: [c:\] vol Volume in drive C: is MYHARDDISK If available, the volume serial number will appear after the drive label or name. To display the disk labels for drives A and B: [c:\] vol a: b: Volume in drive A: is unlabeled Volume in drive B: is BACKUP_2 ═══ 3.3.92. VSCRPUT - Display text in color vertically ═══ Purpose: Display text vertically in the specified color. Format: VSCRPUT row col [BRIght] fg ON [BRIght] bg text row : Starting row. col : Starting column. fg : Foreground text color. bg : Background text color. text : The text to display. See also: SCRPUT. Usage: VSCRPUT writes text vertically on the screen rather than horizontally. It can be used for simple graphs and charts generated by batch files. Like the SCRPUT command, VSCRPUT uses the colors you specify to write the text. See Colors and Color Names for details about colors and color names. The row and column are zero-based, so on a 25 line by 80 column display, valid rows are 0 - 24 and valid columns are 0 - 79. The maximum row value is determined by the current height of the Take Command window; the maximum column value is determined by the current virtual screen width. VSCRPUT displays an error if either the the row or the column is out of range. You can also specify the row and column as offsets from the current cursor position. Begin the value with a plus sign [+] to move down the specified number of rows or to the right the specified number of columns before displaying text, or with a minus sign [-] to move up or to the left. If you specify 999 for the row, VSCRPUT will center the text vertically in the Take Command window. If you specify 999 for the column, VSCRPUT will center the text horizontally. VSCRPUT does not move the cursor when it displays the text. The following batch file fragment displays an X and Y axis and labels them: cls bright white on blue drawhline 20 10 40 1 bright white on blue drawvline 2 10 19 1 bright white on blue scrput 21 20 bright red on blue X axis vscrput 8 9 bright red on blue Y axis ═══ 3.3.93. WINDOW - Change the window state or title ═══ Purpose: Minimize or maximize the current window, restore the default window size, or change the window title. Format: WINDOW [MIN | MAX | RESTORE | /POS=row,col,width,height | "title"] title : A new title for the window. /POS(ition) See also: ACTIVATE and TITLE. Usage: The WINDOW command is used to control the appearance and title of the current window. WINDOW can only be used to specify one change to the current window at a time; to perform more than one operation, you must use multiple WINDOW commands (see examples below). WINDOW MIN reduces the window to an icon, WINDOW MAX enlarges it to its maximum size, and WINDOW RESTORE returns the window to its default size and location on the desktop. You can use the /POS option to set the location and size of the window on the desktop. The row and column values of the /POS option select the window's origin while the width and height values determine its size. If you specify a new title, the title text must be enclosed in double quotes. The quotes will not appear as part of the actual title. For example, to maximize the current window and change it's title, you must perform two WINDOW commands: [c:\] window max [c:\] window "JP Software / Take Command" Option: /POS (Position) Set the window screen position and size. The syntax is /POS=row, col, width, height, where the values are specified in pixels or pels. row and col refer to the position of the bottom left corner of the window relative to the bottom left corner of the screen. ═══ 3.3.94. Y - "Y" pipe fitting ═══ Purpose: Copy standard input to standard output, and then copy the specified file(s) to standard output. Format: Y file ... file : The file or list of files to send to standard output. See also: TEE. Usage: The Y command copies input from standard input (usually the keyboard) to standard output (usually the screen). Once the input ends, the named files are appended to standard output. For example, to get text from standard input, append the files MEMO1 and MEMO2 to it, and send the output to MEMOS: [c:\] y memo1 memo2 > memos The Y command is most useful if you want to add redirected data to the beginning of a file instead of appending it to the end. For example, this command copies the output of DIR, followed by the contents of the file DIREND, to the file DIRALL: [c:\] dir | y dirend > dirall If you are typing at the keyboard to produce input text for Y, you must enter a Ctrl-Z to terminate the input. When using Y with a pipe you must take into account that the programs on the two ends of the pipe run simultaneously, not sequentially as they would under 4DOS. See Piping for more information on pipes. ═══ 4. Aliases ═══ Much of the power of Take Command comes together in aliases, which give you the ability to create your own commands. An alias is a name that you select for a command or group of commands. Simple aliases substitute a new name for an existing command. More complex aliases can redefine the default settings of internal or external commands, operate as very fast in-memory batch files, and perform commands based on the results of other commands. This section shows you some examples of the power of aliases. See the ALIAS command for complete details about writing your own aliases. You can create aliases either from the command line, as described in this section, or with the Aliases dialog which is available from the Utilities menu. The simplest type of alias gives a new name to an existing command. For example, you could create a command called R (for Root directory) to switch to the root directory this way: [c:\] alias r = cd \ After the alias has been defined this way, every time you type the command R, you will actually execute the command CD \. Aliases can also create customized versions of commands. For example, the DIR command can sort a directory in various ways. You can create an alias called DE that means "sort the directory by filename extension, and pause after each page while displaying it" like this: [c:\] alias de = dir /oe /p Aliases can be used to execute sequences of commands as well. The following command creates an alias called MUSIC which saves the current drive and directory, changes to the SOUNDS directory on drive C, runs the program E:\MUSIC\PLAYER.EXE, and, when the program terminates, returns to the original drive and directory (enter this on one line): [c:\] alias music = `pushd c:\sounds & e:\music\player.exe & popd` This alias is enclosed in back-quotes because it contains multiple commands. You must use the back-quotes whenever an alias contains multiple commands, environment variables, parameters (see below), redirection, or piping. See the ALIAS command for full details. When an alias contains multiple commands, the commands are executed one after the other. However, if any of the commands runs an external OS/2 application (such as the fictitious PLAYER.EXE shown above), you must be sure the alias will wait for the application to finish before continuing with the other commands. See Waiting for Applications to Finish under Starting Applications for additional details. Aliases can be nested; that is, one alias can invoke another. For example, the alias above could also be written as: [c:\] alias play = e:\music\player.exe [c:\] alias music = `pushd c:\sounds & play & popd` If you enter MUSIC as a command, Take Command will execute the PUSHD command, detect that the next command (PLAY) is another alias, and execute the program E:\MUSIC\PLAYER.EXE, and Ч when the program exits Ч return to the first alias, execute the POPD command, and return to the prompt. You can use aliases to change the default options for both internal commands and external commands. Suppose that you always want the DEL command to prompt before it erases a file: [c:\] alias del = *del /p An asterisk [*] is used in front of the second "del" to show that it is the name of an internal command, not an alias. See Temporarily Disabling Aliases for more information about this use of the asterisk. You may have a program on your system that has the same name as an internal command. Normally, if you type the command name, you will start the internal command rather than the program you desire, unless you explicitly add the program's full path on the command line. For example, if you have a program named DESCRIBE.COM in the C:\UTIL directory, you could run it with the command C:\UTIL\DESCRIBE.EXE. However, if you simply type DESCRIBE, the internal DESCRIBE command will be invoked instead. Aliases give you two ways to get around this problem. First, you could define an alias that runs the program in question, but with a different name: [c:\] alias desc = c:\util\describe.exe Another approach is to rename the internal command and use the original name for the external program. The following example renames the DESCRIBE command as FILEDESC and then uses a second alias to run DESCRIBE.EXE whenever you type DESCRIBE: [c:\] alias filedesc = *describe [c:\] alias describe = c:\winutil\describe.exe You can also assign an alias to a key, so that every time you press the key, the command will be invoked. You do so by naming the alias with an at sign [@] followed by a key name. After you enter this next example, you will see a 2-column directory with paging whenever you press Shift-F5, then Enter: [c:\] alias @Shift-F5 = *dir /2/p This alias will put the DIR command on the command line when you press Shift-F5, then wait for you to enter file names or additional switches. You must press Enter when you are ready to execute the command. To execute the command immediately, without displaying it on the command line or waiting for you to press Enter, use two at signs at the start of the alias name: [c:\] alias @@Shift-F5 = *dir /2/p The next example clears the Take Command window whenever you press Ctrl- F1: [c:\] alias @@Ctrl-F1 = cls Aliases have many other capabilities as well. This example creates a simple command-line calculator. Once you have entered the example, you can type CALC 4*19, for example, and you will see the answer: [c:\] alias calc = `echo The answer is: %@eval[%$]` Our last example in this section creates an alias called IN. It will temporarily change directories, run an internal or external command, and then return to the current directory when the command is finished: [c:\] alias in = `pushd %1 & %2& & popd` Now if you type: [c:\] in c:\sounds play furelise.wav you will change to the C:\SOUNDS subdirectory, execute the command PLAY FURELISE.WAV, and then return to the current directory. The above example uses two parameters: %1 means the first argument on the command line, and %2& means the second and all subsequent arguments. Parameters are explained in detail under the ALIAS command. Your copy of Take Command includes a sample alias file called ALIASES which contains several useful aliases and demonstrates many alias techniques. Also, see the ALIAS and UNALIAS commands for more information and examples. ═══ 5. Batch Files ═══ A batch file is a file that contains a list of commands to execute. Take Command reads and interprets each line as if it had been typed at the keyboard. Like aliases, batch files are handy for automating computing tasks. Unlike aliases, batch files can be as long as you wish. Batch files take up separate disk space for each file, and can't usually execute quite as quickly as aliases, since they must be read from the disk. The topics included in this section are: .BAT, .CMD, and .BTM Files Echoing in Batch Files Batch File Parameters Using Environment Variables Batch File Commands Interrupting a Batch File Automatic Batch Files Detecting Take Command Using Aliases in Batch Files Debugging Batch Files Batch File String Processing Batch File Compression Argument Quoting Batch File Line Continuation REXX Support EXTPROC Support Also see Special Character Compatibility, Using 4DOS and 4OS2 Batch Files, and The Environment, Internal Variables, and Variable Functions for related information. ═══ 5.1. .BAT, .CMD, and .BTM Files ═══ A Take Command batch file can run in two different modes. In the first, traditional mode, each line of the batch file is read and executed individually, and the file is opened and closed to read each line. In the second mode the batch file is opened once, the entire file is read into memory, and the file is closed. The second mode can be 5 to 10 times faster, especially if most of the commands in the batch file are internal commands. However, only the first mode can be used for self-modifying batch files. The batch file's extension determines its mode. Files with a .BAT or .CMD extension are run in the slower, traditional mode. Files with a .BTM extension are run in the faster, more efficient mode. You can change the execution mode inside a batch file with the LOADBTM command. ═══ 5.2. Echoing in Batch Files ═══ By default, each line in a batch file is displayed or "echoed" as it is executed. You can change this behavior, if you want, in several different ways: Any batch file line that begins with an [@] symbol will not be displayed. The display can be turned off and on within a batch file with the ECHO OFF and ECHO ON commands. The default setting can be changed with the SETDOS /V command or the BatchEcho directive in the TCMDOS2.INI file. For example, the following line turns off echoing inside a batch file. The [@] symbol keeps the batch file from displaying the ECHO OFF command: @echo off Take Command also has a command line echo that is unrelated to the batch file echo setting. See ECHO for details about both settings. ═══ 5.3. Batch File Line Continuation ═══ Take Command will combine multiple lines in the batch file into a single line for processing when you include the escape character as the very last character of each line to be combined (except the last). The default escape character is a caret [^]. For example: [c:\] echo The quick brown fox jumped over the lazy^ sleeping^ dog. > alphabet You cannot use this technique to extend a batch file line beyond the normal line length limit of 1,023 characters. ═══ 5.4. Batch File Parameters ═══ Like aliases and application programs, batch files can examine the command line that is used to invoke them. The command tail (everything on the command line after the batch file name) is separated into individual parameters (also called arguments or batch variables) by scanning for the spaces, tabs, and commas that separate the parameters. A batch file can work with the individual parameters or with the command tail as a whole. These parameters are numbered from %1 to %127. %1 refers to the first parameter on the command line, %2 to the second, and so on. It is up to the batch file to determine the meaning of each parameter. You can use quotation marks to pass spaces, tabs, commas, and other special characters in a batch file parameter; see Argument Quoting for details. Parameters that are referred to in a batch file, but which are missing on the command line, appear as empty strings inside the batch file. For example, if you start a batch file and put two parameters on the command line, any reference in the batch file to %3, or any higher-numbered parameter, will be interpreted as an empty string. A batch file can also work with three special parameters: %0 contains the name of the batch file as it was entered on the command line, %# contains the number of command line arguments, and %n$ contains the complete command-line tail starting with argument number n (for example,%3$ means the third parameter and all those after it). The default value of n is 1, so %$ contains the entire command tail. The values of these special parameters will change if you use the SHIFT command. For example, if your batch file interprets the first argument as a subdirectory name then the following line would move to the specified directory: cd %1 A friendlier batch file would check to make sure the directory exists and take some special action if it doesn't: iff isdir %1 then cd %1 else echo Subdirectory %1 does not exist! quit endiff (See the IF and IFF commands.) Batch files can also use environment variables, internal variables, and variable functions. ═══ 5.5. Using Environment Variables ═══ Batch files can also use environment variables, internal variables, and variable functions. You can use these variables and functions to determine system status (e.g., the type of CPU in the system), resource levels (e.g., the amount of free disk space), file information (e.g., the date and time a file was last modified), and other information (e.g., the current date and time). You can also perform arithmetic operations (including date and time arithmetic), manipulate strings and substrings, extract parts of a filename, and read and write files. To create temporary variables for use inside a batch file, just use the SET command to store the information you want in an environment variable. Pick a variable name that isn't likely to be in use by some other program (for example, PATH would be a bad choice), and use the UNSET command to remove these variables from the environment at the end of your batch file. You can use SETLOCAL and ENDLOCAL to create a "local" environment so that the original environment will be restored when your batch file is finished. Environment variables used in a batch file may contain either numbers or text. It is up to you to keep track of what's in each variable and use it appropriately; if you don't (for example, if you use %@EVAL to add a number to a text string), you'll get an error message. ═══ 5.6. Batch File Commands ═══ Several commands are particularly suited to batch file processing. Each command is explained in detail in the Command Reference. Here is a list of some of the commands you might find most useful:  ACTIVATE activates another window.  BEEP produces a sound of any pitch and duration through the computer's speaker.  CALL executes one batch file from within another.  CANCEL terminates all batch file processing.  CLS and COLOR set the Take Command display colors.  DO starts a loop. The loop can be based on a counter, or on a conditional test like those used in IF and IFF.  DRAWBOX draws a box on the screen.  DRAWHLINE and DRAWVLINE draw horizontal and vertical lines on the screen.  ECHO and ECHOS print text on the screen (the text can also be redirected to a file or device). ECHOERR and ECHOSERR print text to the standard error device.  GOSUB executes a subroutine inside a batch file. The RETURN command terminates the subroutine.  GOTO branches to a different location in the batch file.  FOR executes commands for each file that matches a set of wildcards, or each entry in a list.  IF and IFF execute commands based on a test of string or numeric values, program exit codes, or other conditions.  INKEY and INPUT collect keyboard input from the user and store it in environment variables.  KEYSTACK sends keystrokes to applications.  LOADBTM changes the batch file operating mode.  MSGBOX displays a dialog box with standard buttons like Yes, No, OK, and Cancel, and returns the user's selection.  ON initializes error handling for Ctrl- C / Ctrl-Break, or for program and command errors.  PAUSE displays a message and waits for the user to press a key.  QUERYBOX displays a dialog box for text input.  QUIT ends the current batch file and optionally returns an exit code.  REM places a remark in a batch file.  SCREEN positions the cursor on the screen and optionally prints a message at the new location.  SCRPUT displays a message in color.  SETLOCAL saves the current disk drive, default directory, environment, alias list, and special character settings. ENDLOCAL restores the settings that were saved.  SHIFT changes the numbering of the batch file parameters.  START starts another session or window.  SWITCH selects a group of statements to execute based on the value of a variable.  TEXT displays a block of text. ENDTEXT ends the block.  TIMER starts or reads a stopwatch.  TITLE changes the window title.  VSCRPUT displays a vertical message in color. These commands, along with the internal variables and variable functions, make the enhanced batch file language extremely powerful. Your copy of Take Command includes a sample batch file, in the file EXAMPLES.BTM, that demonstrates some of the things you can do with batch files. ═══ 5.7. Interrupting a Batch File ═══ You can usually interrupt a batch file by pressing Ctrl-C or Ctrl-Break. Whether and when these keystrokes are recognized will depend on whether Take Command or an application program is running, how the application (if any) was written, and whether the ON BREAK command is in use. If Take Command detects a Ctrl-C or Ctrl-Break (and ON BREAK is not in use), it will display a prompt, for example: Cancel batch job C:\CHARGE.BTM ? (Y/N/A) : Enter N to continue, Y to terminate the current batch file and continue with any batch file which called it, or A to end all batch file processing regardless of the batch file nesting level. Answering Y is similar to the QUIT command; answering A is similar to the CANCEL command. ═══ 5.8. Automatic Batch Files (TCSTART & TCEXIT) ═══ Take Command supports two "automatic" batch files, files that run without your intervention, as long as Take Command can find them. Each time Take Command starts, it looks for an automatic batch file called TCSTART.BTM, TCSTART.CMD or TCSTART.BAT. If the TCSTART batch file is not in the same directory as Take Command itself, you should use the Startup page of the configuration notebook, or the TCSTARTPath directive in your TCMDOS2.INI file to specify its location. TCSTART is optional, so Take Command will not display an error message if it cannot find the file. TCSTART is a convenient place to change the color or content of the prompt for each session, LOG the start of a session, or execute other special startup or configuration commands. It is also one way to set aliases and environment variables. With the exception of some initialization switches, the entire startup command line passed to Take Command is available to TCSTART via batch file parameters (%1, %2, etc.). This can be useful if you want to see the command line passed to Take Command. For example, to pause if any parameters are passed you could include this command in TCSTART: if "%1" != "" pause Starting Take Command with parameters [%$] Whenever a Take Command session ends, it runs a second automatic batch file called TCEXIT.BTM, TCEXIT.CMD or TCEXIT.BAT. This file, if you use it, should be in the same directory as your TCSTART batch file. Like TCSTART, TCEXIT is optional. It is not necessary in most circumstances, but it is a convenient place to put commands to save information such as a history list before Take Command ends, or LOG the end of the session. Pipes, Transient Sessions, and TCSTART When you set up the TCSTART file, remember that it is executed every time Take Command starts, including when running a pipe, or a transient copy of Take Command started with the /C startup option. For example, suppose you enter a command line like this, which uses a pipe: [c:\data] myprog | sort > out.txt Normally this command would create the output file C:\DATA\OUT.TXT. However, if you have a TCSTART file which changes to a different directory, the output file will be written there -- not in C:\DATA. This is because Take Command starts a second command processor session to run the commands on the right hand side of the pipe, and that new copy runs 4START before processing the commands from the pipe. If 4START changes directories, the command from the pipe will be executed in the new directory. The same problem can occur if you use a transient session started with /C to run an individual command, then exit -- the session will execute in the directory set by TCSTART, not the directory in which it was originally started. For example, suppose you set up a desktop object with a command line like this, which starts a transient session: Command: d:\tcmd\tcmd.exe /c list myfile.txt Working Directory: c:\data Normally this command would LIST the file C:\DATA\MYFILE.TXT. However, if TCSTART changes to a different directory, Take Command will look for MYFILE.TXT there -- not in C:\DATA. Similarly, any changes to environment variables or other settings in TCSTART will affect all copies of Take Command, including those used for pipes and transient sessions. You can work around these potential problems with the IF or IFF command and the internal variables _PIPE and _TRANSIENT. For example, to skip all TCSTART processing when running in a pipe or transient session, you could use a command like this at the beginning of TCSTART: if %_pipe != 0 .or. %_transient != 0 quit ═══ 5.9. Detecting Take Command ═══ From a batch file, you can determine if Take Command, 4DOS, 4OS2, or 4NT is loaded by testing for the variable function @EVAL, with a test like this: if "%@eval[2 + 2]%" == "4" echo TCMD is loaded! This test can never succeed in COMMAND.COM or CMD.EXE. Other variable functions could also be used for the same purpose. ═══ 5.10. Using Aliases in Batch Files ═══ One way to simplify batch file programming is to use aliases to hide unnecessary detail inside a batch file. For example, suppose you want a batch file to check for certain errors, and display a message and exit if one is encountered. This example shows one way to do so: setlocal unalias * alias error `echo. & echo ERROR: %$ & goto dispmenu` alias fatalerror `echo. & echo FATAL ERROR: %$ & quit` alias in `pushd %1 & %2$ & popd` if not exist setup.btm fatalerror Missing setup file! call setup.btm cls :dispmenu text 1. Word Processing 2. Spreadsheet 3. Communications 4. Exit endtext echo. inkey Enter your choice: %%userchoice switch %userchoice case 1 input Enter the file name: %%fname if not exist fname error File does not exist in d:\letters c:\wp60\wp.exe case 2 in d:\finance c:\quattro\q.exe case 3 in d:\comm c:\comsw\pcplus.exe case 4 goto done default error Invalid choice, try again endswitch goto dispmenu :done endlocal The first alias, ERROR, simply displays an error message and jumps to the label DISPMENU to redisplay the menu. The "%$" in the second ECHO command displays all the text passed to ERROR as the content of the message. The similar FATALERROR alias displays the message, then exits the batch file. The last alias, IN, expects 2 or more command-line arguments. It uses the first as a new working directory and changes to that directory with a PUSHD command. The rest of the command line is interpreted as another command plus possible command line parameters, which the alias executes. This alias is used here to switch to a directory, run an application, and switch back. It could also be used from the command line. The following 9 lines print a menu on the screen and then get a keystroke from the user and store the keystroke in an environment variable called userchoice. Then the SWITCH command is used to test the user's keystroke and to decide what action to take. There's another side to aliases in batch files. If you're going to distribute your batch files to others, you need to remember that they may have aliases defined for the commands you're going to use. For example, if the user has aliased CD to CDD and you aren't expecting this, your file may not work as you intended. There are two ways to address this problem. The simplest method is to use SETLOCAL, ENDLOCAL, and UNALIAS to clear out aliases before your batch file starts, and restore them at the end, as we did in the previous example. Remember that SETLOCAL and ENDLOCAL will save and restore not only the aliases but also the environment, the current drive and directory, and various special characters. If this method isn't appropriate or necessary for the batch file you're working on, you can also use an asterisk [*] before the name of any command. The asterisk means the command that follows it should not be interpreted as an alias. For example the following command redirects a list of file names to the file FILELIST: dir /b > filelist However, if the user has redefined DIR with an alias this command may not do what you want. To get around this just use: *dir /b > filelist The same can be done for any command in your batch file. If you use the asterisk, it will disable alias processing, and the rest of the command will be processed normally as an internal command, external command, or batch file. Using an asterisk before a command will work whether or not there is actually an alias defined with the same name as the command. If there is no alias with that name, the asterisk will be ignored and the command will be processed as if the asterisk wasn't there. ═══ 5.11. Debugging Batch Files ═══ Take Command includes a built-in batch file debugger, invoked with the SETDOS /Y1 command. The debuggger allows you to "single-step" through a batch file line by line, with the file displayed in a popup window as it executes. You can execute or skip the current line, continue execution with the debugger turned off, view the fully-expanded version of the command line, or exit the batch file. The batch debugger can also pop up a separate window to view or edit current environment variables and aliases, and can pop up the LIST command to display the contents of any file. To start the debugger, insert a SETDOS /Y1 command at the beginning of the portion of the batch file you want to debug, and a SETDOS /Y0 command at the end. You can also invoke SETDOS /Y1 from the prompt, but because the debugger is automatically turned off whenever Take Command returns to the prompt, you must enter the SETDOS command and the batch file name on the same line, for example: [c:\] setdos /y1 & mybatch.btm If you use the debugger regularly you may want to define a simple alias to invoke it, for example: [c:\] alias trace `setdos /y1 & %$` This alias simply enables the debugger, then runs whatever command is passed to it. You can use the alias to debug a batch file with a command like this: [c:\] trace mybatch.btm When the debugger is running you can control its behavior with keystrokes. Debugging continues after each keystroke unless otherwise noted: T(race), Enter, or F8 Execute the current command. If it calls a subroutine with GOSUB, or another batch file with CALL, single-step into the called subroutine or batch file. S(tep) or F10 Execute the current command, but execute any subroutine or CALLed batch file without single-stepping. J(ump) Skip the current command and proceed to the next command. X (Expand) Display the next command to be executed, after expansion of aliases and environment variables. L(ist) Prompt for a file name and then view the file with the LIST command. V(ariables) Open a popup window to display the current environment, in alphabetical order. A(liases) Open a popup window to display the current aliases, in alphabetical order. O(ff) or Esc Turn off the debugger and continue with the remainder of the batch file. Q(uit) Quit the debugger and the current batch file, without executing the remainder of the file. The debugger highlights each line of the batch file as it is executed. It executes the commands on the line one at a time, so when a line contains more than one command, the highlight will not move as each command is executed. To see the individual commands, use the X key to expand each command before it is executed. If you use a "prefix" command like EXCEPT, FOR, GLOBAL, or SELECT, the prefix command is considered one command, and each command it invokes is another. For example, this command line executes four commands Ч the FOR and three ECHO commands: for %x in (a b c) do echo %x You cannot use the batch debugger with REXX files or EXTPROC files. It can only be used with normal Take Command batch files. The debugger gives you a detailed, step-by-step view of batch file execution, and will help solve particularly difficult batch file problems. However, in some cases you will find it easier to diagnose these problems with techniques that allow you to review what is happening at specific points in the batch file without stepping through each line individually. There are several tricks you can use for this purpose.. Probably the simplest is to turn ECHO on at the beginning of the file while you're testing it, or use SETDOS /V2 to force ECHO on even if an ECHO OFF command is used in the batch file. This will give you a picture of what is happening as the file is executed, without stopping at each line. It will make your output look messy of course, so just turn it off once things are working. You can also turn ECHO on at the beginning of a group of commands you want to "watch", and off at the end, just by adding ECHO commands at the appropriate spots in your file. If an error occurs in a batch file, the error message will display the name of the file, the number of the line that contained the error, and the error itself. For example: e:\test.bat [3] Invalid parameter "/d" tells you that the file E:\TEST.BAT contains an error on line 3. The first line of the batch file is numbered 1. Another trick, especially useful in a fast-moving batch file or one where the screen is cleared before you can read messages, is to insert PAUSE commands wherever you need them in order to be able to watch what's happening. You can also use an ON ERRORMSG command to pause if an error occurs, then continue with the rest of the file (the first command below), or to quit if an error occurs (the second command): on errormsg pause on errormsg quit If you can't figure out how your aliases and variables are expanded, try turning LOG on at the start of the batch file. LOG keeps track of all commands after alias and variable expansion are completed, and gives you a record in a file that you can examine after the batch file is done. You must use a standard LOG command; LOG /H (the history log) does not work in batch files. You may also want to consider using redirection to capture your batch file output. Simply type the batch file name followed by the redirection symbols, for example: [c:\] mybatch >& testout This records all batch file output, including error messages, in the file TESTOUT, so you can go back and examine it. If you have ECHO ON in the batch file you'll get the batch commands intermingled with the output, which can provide a very useful trace of what's happening. Of course, output from full-screen commands and programs that don't write to the standard output devices can't be recorded, but you can still gain a lot of useful information if your batch file produces any output. If you're using redirection to see the output, remember that any prompts for input will probably go to the output file and not to the screen. Therefore, you will need to know in advance the sequence of keystrokes required to get through the entire batch file, and enter them by hand or with KEYSTACK. You can also use the TEE command to both view the output while the batch file is running and save it in a file for later examination. ═══ 5.12. Batch File String Processing ═══ As you gain experience with batch files, you're likely to find that you need to manipulate text strings. You may need to prompt a user for a name or password, process a list of files, or find a name in a phone list. All of these are examples of string processing -- the manipulation of lines of readable text. Take Command includes several features that make string processing easier. For example, you can use the INKEY, INPUT, MSGBOX, and QUERYBOX commands for user input; the ECHO, SCREEN, SCRPUT, and VSCRPUT commands for output; and the FOR command or the @FILEREAD function to scan through the lines of a file. In addition, variable functions offer a wide range of string handling capabilities. For example, suppose you need a batch file that will prompt a user for a name, break the name into a first name and a last name, and then run a hypothetical LOGIN program. LOGIN expects the syntax /F:first /L:last with both the first and last names in upper case and neither name longer than 8 characters. Here is one way to write such a batch file: @echo off setlocal unalias * querybox "Name" Enter your name (no initials): %%name set first=%@word[0,%name] set flen=%@len[%first] set last=%@word[1,%name] set llen=%@len[%last] iff %flen gt 8 .or. %llen gt 8 then echo First or last name too long quit endiff login /F:%@upper[%first] /L:%@upper[%last] endlocal The SETLOCAL command at the beginning of this batch file saves the environment and aliases. Then the UNALIAS * command removes any existing aliases so they won't interfere with the behavior of the commands in the remainder of the batch file. The first block of lines ends with a QUERYBOX command which asks the user to enter a name. The user's input is stored in the environment variable NAME. The second block of lines extracts the user's first and last names from the NAME variable and calculates the length of each. It stores the first and last name, along with the length of each, in additional environment variables. Note that the @WORD function numbers the first word as 0, not as 1. The IFF command in the third block of lines tests the length of both the first and last names. If either is longer than 8 characters, the batch file displays an error message and ends. (QUERYBOX can limit the length of input text more simply with its /L switch. We used a slightly more cumbersome method above in order to demonstrate the use of string functions in batch files.) Finally, in the last block, the batch file executes the LOGIN program with the appropriate parameters, then uses the ENDLOCAL command to restore the original environment and alias list. At the same time, ENDLOCAL discards the temporary variables that the batch file used (NAME, FIRST, FLEN, etc.). When you're processing strings, you also need to avoid some common traps. The biggest one is handling special characters. Suppose you have a batch file with these two commands, which simply accept a string and display it: input Enter a string: %%str echo %str Those lines look safe, but what happens if the user enters the string "some > none" (without the quotes). After the string is placed in the variable STR, the second line becomes echo some > none The ">" is a redirection symbol, so the line echoes the string "some" and redirects it to a file called NONE -- probably not what you expected. You could try using quotation marks to avoid this kind of problem, but that won't quite work. If you use back-quotes (ECHO `%STR`), the command will echo the four-character string %STR. Environment variable names are not expanded when they are inside back-quotes. If you use double quotes (ECHO "%STR"), the string entered by the user will be displayed properly, and so will the quotation marks. With double quotes, the output would look like this: "some > none" As you can imagine, this kind of problem becomes much more difficult if you try to process text from a file. Special characters in the text can cause all kinds of confusion in your batch files. Text containing back-quotes, double quotes, or redirection symbols can be virtually impossible to handle correctly. One way to overcome these potential problems is to use the SETDOS /X command to temporarily disable redirection symbols and other special characters. The two-line batch file above would be a lot more likely to produce the expected results if it were rewritten this way: setdos /x-15678 input Enter a string: %%str echo %str setdos /x0 The first line turns off alias processing and disables several special symbols, including the command separator and all redirection symbols. Once the string has been processed, the last line re-enables the features that were turned off in the first line. If you need advanced string processing capabilities beyond those provided by Take Command, you may want to consider using the REXX language. Our products support external REXX programs for this purpose. ═══ 5.13. Batch File Compression ═══ You can compress your .BTM files with a program called BATCOMP.EXE, which is distributed with Take Command. This program condenses batch files by about a third and makes them unreadable with the LIST command and similar utilities. Compressed batch files run at approximately the same speed as regular .BTM files. You may want to consider compressing batch files if you need to distribute them to others and keep your original code secret or prevent your users from altering them. You may also want to consider compressing batch files to save some disk space on the systems where the compressed files are used. The full syntax for the batch compression program is BATCOMP [/O] input file [output file ] You must specify the full name of the input file, including its extension, on the BATCOMP command line. If you do not specify the output file, BATCOMP will use the same base name as the input file and add a .BTM extension. BATCOMP will also add a .BTM extension if you specify a base name for the output file without an extension. For example, to compress MYBATCH.CMD and save the result as MYBATCH.BTM, you can use any of these three commands: [c:\] batcomp mybatch.cmd [c:\] batcomp mybatch.cmd mybatch [c:\] batcomp mybatch.cmd mybatch.btm If the output file (MYBATCH.BTM in the examples above) already exists, BATCOMP will prompt you before overwriting the file. You can disable the prompt by including /O on the BATCOMP command line immediately before the input file name. Even if you use the /O option, BATCOMP will not compress a file into itself. JP Software does not provide a utility to decompress batch files. If you use BATCOMP.EXE, make sure that you also keep a copy of the original batch file for future inspection or modification. BATCOMP is a DOS and OS/2 character-mode application designed to run in any environment where our command processors run. Normally it can be run successfully from within Take Command without manually starting a separate DOS or OS/2 session. Each of our command processors includes the same version of BATCOMP.EXE, and a batch file compressed with any copy of BATCOMP can be used with any current JP Software command processor. If you plan to distribute batch files to users of different platforms, see Special Character Compatibility. ═══ 5.14. Argument Quoting ═══ As it parses the command line, Take Command looks for the ampersand [&] command separator, conditional commands (|| or &&), white space (spaces, tabs, and commas), percent signs [%] which indicate variables or batch file arguments to be expanded, and redirection and piping characters (>, <, or |). Normally, these special characters cannot be passed to a command as part of an argument. However, you can include any of the special characters in an argument by enclosing the entire argument in single back quotes [`] or double quotes ["]. Although both back quotes and double quotes will let you build arguments that include special characters, they do not work the same way. No alias or variable expansion is performed on an argument enclosed in back quotes. Redirection symbols inside the back quotes are ignored. The back quotes are removed from the command line before the command is executed. No alias expansion is performed on expressions enclosed in double quotes. Redirection symbols inside double quotes are ignored. However, variable expansion is performed on expressions inside double quotes. The double quotes themselves will be passed to the command as part of the argument. For example, suppose you have a batch file CHKNAME.BTM which expects a name as its first parameter (%1). Normally the name is a single word. If you need to pass a two-word name with a space in it to this batch file you could use the command: [c:\] chkname `MY NAME` Inside the batch file, %1 will have the value MY NAME, including the space. The back quotes caused Take Command to pass the string to the batch file as a single argument. The quotes keep characters together and reduce the number of arguments in the line. For a more complex example, suppose the batch file QUOTES.BAT contains the following commands: @echo off echo Arg1 = %1 echo Arg2 = %2 echo Arg3 = %3 and that the environment variable FORVAR has been defined with this command: [c:\] set FORVAR=for Now, if you enter the command [c:\] quotes `Now is the time %forvar` all good the output from QUOTES.BAT will look like this: Arg1 = Now is the time %forvar Arg2 = all Arg3 = good But if you enter the command [c:\] quotes "Now is the time %forvar" all good the output from QUOTES.BAT will look like this: Arg1 = "Now is the time for" Arg2 = all Arg3 = good Notice that in both cases, the quotes keep characters together and reduce the number of arguments in the line. The following example has 7 command-line arguments, while the examples above only have 3: [c:\] quotes Now is the time %%forvar all good (The double percent signs are needed in each case because the argument is parsed twice, once when passed to the batch file and again in the ECHO command.) When an alias is defined in a batch file or from the command line, its argument can be enclosed in back quotes to prevent the expansion of replaceable parameters, variables, and multiple commands until the alias is invoked. See ALIAS for details. You can disable and re-enable back quotes and double quotes with the SETDOS /X command. ═══ 5.15. REXX Support ═══ REXX is a a powerful file and text processing language developed by IBM, and available on many PC and other platforms. REXX is an ideal extension to the Take Command batch language, especially if you need advanced string processing capabilities. The REXX language is not built into Take Command, and must be obtained separately. REXX support is built in to IBM OS/2. You can also purchase add-on REXX software such as Enterprise Alternatives' Enterprise REXX, available for Windows 3.x, Windows 95, and Windows NT; or Quercus's Personal REXX, available for OS/2, Windows 3.x, Windows 95, and Windows NT. (If you want to learn about or purchase one of these REXX packages, contact JP Software's sales department for more information.) Take Command for OS/2 supports REXX programs stored in .CMD files. Take Command checks to see if the first two characters on the first line of a .CMD file are [/*], the beginning of a REXX comment. If so, it passes the file to OS/2's built-in REXX facility for processing. If Personal REXX for OS/2 is installed, it automatically replaces OS/2's built-in REXX, and handles all REXX commands passed by Take Command for OS/2. Take Command's REXX support will also work with other REXX processors such as PMREXX and VX-REXX. It does not work with IBM's VREXX, because the internal design of VREXX does not permit reliable execution of REXX scripts from Presentation Manager programs like Take Command. When working with a REXX processor, Take Command automatically handles all input and output for the REXX program, and any standard REXX processor window for input and output is not displayed. If you need to run a REXX program inside your REXX processor's window, and not under Take Command, you should start the REXX processor s executable file explicitly, then load and run the REXX program from there. All of the REXX processors described above (Enterprise REXX, Personal REXX, and OS/2's built-in REXX) extend the interface between REXX and the command processor by allowing you to invoke Take Command commands from within a REXX program. When you send a command from a REXX program back to the command processor to be executed (for example, if you execute a DIR command within a REXX script), the REXX software must use the correctaddre for the command processor. In most cases it is best to use the default address of CMD, which is set up automatically by Take Command. If you choose to use an explicit address via the REXX ADDRESS command, you can use either CMD or TCMD. For details on communication between REXX and the command processor, or for more information on any aspect of REXX, see your REXX documentation. ═══ 5.16. EXTPROC Support ═══ For compatibility with CMD.EXE, Take Command offers an external processor (EXTPROC) option for batch files that lets you define an external program to process a particular .CMD file. To identify a .CMD file to be used with an external processor, place the string "EXTPROC" as the first word on the first line of the file, followed by the name of the external program that should be called. Take Command will start the program and pass it the name of the .CMD file and any command- line arguments that were entered. For example, suppose GETDATA.CMD contains the following lines: EXTPROC D:\DATAACQ\DATALOAD.EXE OPEN PORT1 READ 4000 DISKWRITE D:\DATAACQ\PORT1\RAW Then if you entered the command: [d:\dataacq] getdata /p17 Take Command would read the GETDATA.CMD file, determine that it began with an EXTPROC command, read the name of the processor program, and then execute the command: D:\DATAACQ\DATALOAD.EXE D:\DATAACQ\GETDATA.CMD /p17 The hypothetical DATALOAD.EXE program would then be responsible for reopening the GETDATA.CMD file, ignoring the EXTPROC line at the start, and interpreting the other instructions in the file. It would also have to respond appropriately to the command-line parameter entered (/p17). Do not try to use Take Command or 4OS2 as the external processor named on the EXTPROC line in the .CMD file. It will interpret the EXTPROC line as a command to re-open itself. The result will be an infinite loop that will continue until the computer runs out of resources and locks up. ═══ 6. Environment Variables and Functions ═══ The environment is a collection of information about your computer that every program receives. Each entry in the environment consists of a variable name, followed by an equal sign and a string of text. You can automatically substitute the text for the variable name in any command. To create the substitution, include a percent sign [%] and a variable name on the command line or in an alias or batch file. You can create, alter, view, and delete environment variables with the Environment dialog (available from the Utilities menu) as well as with the SET, ESET, and UNSET commands. The following environment variables have special meanings in Take Command: CDPATH CMDLINE COLORDIR COMSPEC FILECOMPLETION PATH PATHEXT PROMPT Also see COPYCMD DIRCMD Take Command also supports two special types of variables. Internal variables are similar to environment variables, but are stored internally within Take Command, and are not visible in the environment. They provide information about your system for use in batch files and aliases. Variable functions are referenced like environment variables, but perform additional functions like file handling, string manipulation and arithmetic calculations. The SET command is used to create environment variables. For example, you can create a variable named BACKUP like this: [c:\] set BACKUP=*.bak;*.bk!;*.bk If you then type [c:\] del %BACKUP it is equivalent to the following command: del *.bak;*.bk!;*.bk The variable names you use this way may contain any alphabetic or numeric characters, the underscore character [_], and the dollar sign [$]. You can force acceptance of other characters by including the full variable name in square brackets, like this: %[AB##2]. You can also "nest" environment variables using square brackets. For example, %[%var1] means "the contents of the variable whose name is stored in VAR1". A variable referenced with this technique cannot contain more than 255 characters of information. Nested variable expansion can be disabled with the SETDOS /X command. In Take Command the size of the environment is set automatically, and increased as needed when you add variables. You do not need to specify the size as you do under 4DOS or some traditional command processors. The trailing percent sign that was traditionally required for environment variable names is not usually required in Take Command, which accepts any character that cannot be part of a variable name as the terminator. However, the trailing percent can be used to maintain compatibility. The trailing percent sign is needed if you want to join two variable values. The following examples show the possible interactions between variables and literal strings. First, create two environment variables called ONE and TWO this way: [c:\] set ONE=abcd [c:\] set TWO=efgh Now the following combinations produce the output text shown: %ONE%TWOabcdTWO ("%ONE%" + "TWO") %ONE%TWO%abcdTWO ("%ONE%" + "TWO%") %ONE%%TWOabcdefgh ("%ONE%" + "%TWO") %ONE%%TWO%abcdefgh ("%ONE%" + "%TWO%") %ONE%[TWO]abcd[TWO] ("%ONE%" + "[TWO]") %ONE%[TWO]%abcd[TWO] ("%ONE%" + "[TWO]%") %[ONE]%TWOabcdefgh ("%[ONE]" + "%TWO") %[ONE]%TWO%abcdefgh ("%[ONE]" + "%TWO%") If you want to pass a percent sign to a command, or a string which includes a percent sign, you must use two percent signs in a row. Otherwise, the single percent sign will be seen as the beginning of a variable name and will not be passed on to the command. For example, to display the string "We're with you 100%" you would use the command: echo We're with you 100%% You can also use back quotes around the text, rather than a double percent sign. See Argument Quoting for details. Environment variables may contain alias names. Take Command will substitute the variable value for the name, then check for any alias name which may have been included within the value. For example, the following commands would generate a 2-column directory of the .TXT files: [c:\] alias d2 dir /2 [c:\] set cmd=d2 [c:\] %cmd *.txt ═══ 6.1. CDPATH ═══ CDPATH tells Take Command where to search for directories specified by the CD, CDD, and PUSHD commands and in automatic directory changes. (_CDPATH can be used as an alternative to CDPATH if you are using Microsoft Bookshelf, which uses a CDPATH variable for its own purposes.) CDPATH is composed of a list of directories, separated by semicolons [;]. See CDPATH for more information about using this variable. ═══ 6.2. CMDLINE ═══ CMDLINE is the fully expanded text of the currently executing command line. CMDLINE is set just before invoking any .COM, .EXE, .BTM, .BAT, or .CMD file. If a command line is prefaced with an "@" to prevent echoing, it will not be put in CMDLINE, and any previous CMDLINE variable will be removed from the environment. ═══ 6.3. COLORDIR ═══ COLORDIR controls directory display colors used by DIR. See the Color-Coded Directories section of the DIR command for a complete description of the format of this variable. ═══ 6.4. COMSPEC ═══ COMSPEC contains the full path and name of the character-mode command processor. Take Command uses it to start character-mode OS/2 sessions. ═══ 6.5. COPYCMD ═══ COPYCMD is used by some versions of COMMAND.COM and CMD.EXE to hold default options for the COPY command. Take Command does not support this variable, but you can achieve the same effect with an alias. For example, if you want the COPY command to default to prompting you before overwriting an existing file, you could use this alias: [c:\] alias copy = `*copy /r` If you wish to use COPYCMD for compatibility with systems that do not use Take Command, you can define the alias this way: [c:\] alias copy = `*copy %copycmd` ═══ 6.6.  DIRCMD ═══ DIRCMD is used by some versions of COMMAND.COM and CMD.EXE to hold default options for the DIR command. Take Command does not support this variable, but you can achieve the same effect with an alias. For example, if you want the DIR command to default to a 2-column display with a vertical sort and a pause at the end of each page, you could use this alias: [c:\] alias dir = `*dir /2/p/v` If you wish to use DIRCMD for compatibility with systems that do not use Take Command, you can define the alias this way: [c:\] alias dir = `*dir %dircmd` ═══ 6.7. FILECOMPLETION (variable) ═══ FILECOMPLETION sets the files made available during filename completion for selected commands. See Customizing Filename Completion for a complete description of the format of this variable. ═══ 6.8. PATH (variable) ═══ PATH is a list of directories that Take Command will search for executable files that aren't in the current directory. PATH may also be used by some application programs to find their own files. See the PATH command for a full description of this variable. ═══ 6.9. PATHEXT ═══ PATHEXT can be used to select the extensions to look for when searching the PATH for an executable file. It consists of a list of extensions, separated by semicolons. For example, to replicate the default extension list used by Take Command: set pathext=.com;.exe;.btm;.cmd;.bat PATHEXT is ignored unless the PathExt setting is set to Yes in TCMDOS2.INI. Once PATHEXT is enabled the standard path search for .COM, .EXE, .BTM, .CMD, and .BAT files is replaced by a search for files with the extensions listed in PATHEXT, in the order listed there. Enabling PATHEXT affects only the standard path search, it does not affect the subsequent searches for files with executable extensions. PATHEXT is supported for compatibility reasons but should not generally be used as a substitute for executable extensions, which are much more flexible. For more details on path searches, see the PATH command. CAUTION: If you set PathExt = Yes in TCMDOS2.INI and then fail to set the PATHEXT variable, path searches will fail as there will be no extensions for which to search! ═══ 6.10. PROMPT (variable) ═══ PROMPT defines the command-line prompt. It can be set or changed with the PROMPT command. ═══ 6.11. Internal Variables ═══ Internal variables are special environment variables built into Take Command to provide information about your system. They are not actually stored in the environment, but can be used in commands, aliases, and batch files just like any environment variable. The values of these variables are stored internally in Take Command, and cannot be changed with the SET, UNSET, or ESET command. However, you can override any of these variables by defining a new variable with the same name. These internal variables are often used in batch files and aliases to examine system resources and adjust to the current computer settings. You can examine the contents of any internal variable (except %= and %+) from the command line with a command like this: [c:\] echo %variablename On disk volumes which do not support long filenames, variables which return a path or file name will return their result in upper or lower case depending on the value of the SETDOS /U switch or the UpperCase directive in the TCMDOS2.INI file. On volumes which do support long filenames, these variables will return names as they are stored on the disk and no case shifting will be performed. Returned filename values which include long filenames are not quoted automatically; you must add quotes yourself if they are required for your use of the variable value. Some variables return values based on information provided by your operating system. These variables will only return correct information if the operating system provides it. For example, _APMBATT will not return accurate results if OS/2 and your Advanced Power Management drivers do not provide correct information on battery status to Take Command. Internal Variable Categories The list below gives a one-line description of each variable, and a cross- reference which selects a short help topic on that variable. Most of the variables are simple enough that the one-line description is sufficient. However, for those variables marked with an asterisk [*], the cross-reference topic contains some additional information you may wish to review. You can also obtain help on any variable with a HELP variable name command at the prompt (this is why each variable has its own topic, in addition to its appearance in the list below). See the discussion after the variable list for some additional information, and examples of how these variables can be used. For a more comprehensive set of examples see the EXAMPLES.BTM file which came with your copy of Take Command. Hardware status _APMAC Advanced Power Management AC Line status (on-line or off-line) _APMBATT APM battery status (high, low, critical, charging, unknown) _APMLIFE APM remaining battery life (0 - 100 or unknown) _CPU CPU type (86, 186, 200, 386, 486, 586) _KBHIT Returns 1 if a keyboard input character is waiting. _NDP Coprocessor type (0, 87, 287, 387) Operating system and software status _ANSI ANSI status (1 if enabled, 0 if not) _BOOT Boot drive letter, without a colon _CODEPAGE Current code page number _COUNTRY Current country code _DOS * Operating system (OS2, PM, DOS, etc.) _DOSVER * Operating system version (2.1, 3.0, etc.) _MOUSE Mouse driver flag (always 1) _WINTITLE Current window title Command processor status _4VER Take Command for OS/2 version (2.02, 2.03, etc.) _BATCH Batch nesting level _BATCHLINE Current line number in current batch file _BATCHNAME Name of current batch file _CMDPROC Command processor name _DNAME Name of file used to store file descriptions _HLOGFILE Current history log file name _LOGFILE Current log file name _PID Take Command for OS/2 process ID (numeric) _PIPE Whether running in a pipe (0 or 1) _PPID Parent process ID (numeric) _PTYPE OS/2 process type (PM) _SHELL Shell level (0, 1, 2, ...) _SID Current OS/2 session ID _TRANSIENT * Transient shell flag (0 or 1) Screen, color, and cursor _BG Background color _CI Current cursor shape in insert mode _CO Current cursor shape in overstrike mode _COLUMN Current cursor column _COLUMNS Screen width _FG Foreground color _ROW Current cursor row _ROWS Screen height _SELECTED First line of highliged text. _XPIXELS Physical screen horizontal size in pixels. _YPIXELS Physical screen vertical size in pixels. Drives and directories _CWD Current drive and directory (d:\path) _CWDS Current drive and directory with trailing \ (d:\path\) _CWP Current directory (\path) _CWPS Current directory with trailing \ (\path\) _DISK Current drive (C, D, etc.) _LASTDISK Last possible drive (E, F, etc.) Dates and times _DATE * Current date (mm-dd-yy) _DAY Day of the month (1 - 31) _DOW Day of the week (Mon, Tue, Wed, etc.) _DOWI Day of the week as an integer (1=Sunday, 2-Monday, etc.) _DOY Day of the year (1 - 366) _HOUR Hour (0 - 23) _MINUTE Minute (0 - 59) _MONTH Month of the year (1 - 12) _SECOND Second (0 - 59) _TIME * Current time (hh:mm:ss) _YEAR Year (1980 - 2099) Error codes ? * Exit code, last external program _? * Exit code, last internal command _SYSERR * Last OS/2 error code Compatibility = * Substitutes escape character + * Substitutes command separator Examples You can use these variables in a wide variety of ways depending on your needs. Here are just a couple of examples; for a more comprehensive set see the EXAMPLES.BTM file which came with your copy of Take Command. Store the current date and time in a file, then save the output of a DIR command in the same file: echo Directory as of %_date %_time > dirsave dir >> dirsave Use the IFF command to check whether there are enough resources free before running an application: iff %_GDIFREE lt 40 then echo Not enough GDI resources! quit else d:\mydir\myapp endiff Call another batch file if today is Monday: if "%_DOW" == "Mon" call c:\cleanup\weekly.bat ═══ 6.11.1.  ? - Exit code, last external program ═══ ? contains the exit code of the last external command. Many programs return a "0" to indicate success and a non-zero value to signal an error. However, not all programs return an exit code. If no explicit exit code is returned, the value of %? is undefined. ═══ 6.11.2. _? - Exit code, last internal command ═══ _? contains the exit code of the last internal command. It is set to "0" if the command was successful, "1" if a usage error occurred, "2" if another command processor error or an operating system error occurred, or "3" if the command was interrupted by Ctrl-C or Ctrl-Break. You must use or save this value immediately, because it is set by every internal command. ═══ 6.11.3. = - Substitutes escape character ═══ = returns the current escape character. Use this variable, instead of the actual escape character, if you want your batch files and aliases to work regardless of how the escape character is defined. For example, if the escape character is a caret [^] (the default in Take Command for OS/2) both of the commands below will send a form feed to the printer. However, if the escape character has been changed, the first command will send the string "^f" to the printer, while the second command will continue to work as intended. echos ^f > prn echos %=f > prn ═══ 6.11.4. + - Substitutes command separator ═══ + returns the current command separator. Use this variable, instead of the actual command separator, if you want your batch files and aliases to work regardless of how the command separator is defined. For example, if the command separator is an ampersand [&] (the default in Take Command for OS/2) both of the commands below will display "Hello" on one line and "world" on the next. However, if the command separator has been changed the first command will display "Hello & echo world", while the second command will continue to work as intended. echo Hello & echo world echo Hello %+ echo world ═══ 6.11.5. _4VER - Take Command for OS/2 version (for example, 3.0) ═══ _4VER is the current Take Command for OS/2 version (for example, "3.0"). The version number is in decimal and uses the appropriate decimal separator for your country (to allow numeric comparisons with IF and IFF) ═══ 6.11.6. _ANSI - ANSI status ═══ _ANSI returns "1" if Take Command's ANSI support is enabled, or "0" if it is disabled. For more details on ANSI support see SETDOS /A, the ANSI directive in TCMDOS2.INI, or the ANSI Support topic. ═══ 6.11.7. _APMAC - AC Line Status ═══ _APMAC is the Advanced Power Management AC line status ("on-line", "off-line", or "unknown"). An empty string is returned if APM is not installed on your system. ═══ 6.11.8. _APMBATT - Battery Status ═══ _APMBATT is the Advanced Power Management battery status ("high", "low", "critical", "charging", or "unknown"). An empty string is returned if APM is not installed. ═══ 6.11.9. _APMLIFE - Remaining Battery Life ═══ _APMLIFE is the Advanced Power Management remaining battery life (0 - 100 or "unknown"). An empty string is returned if APM is not installed. ═══ 6.11.10. _BATCH - Batch nesting level ═══ _BATCH is the current batch nesting level. It is "0" if no batch file is currently being processed. ═══ 6.11.11. _BATCHLINE - Current line number in current batch file ═══ _BATCHLINE is the current line number in the current batch file. It is "-1" if no batch file is currently being processed. ═══ 6.11.12. _BATCHNAME - Name of current batch file ═══ _BATCHNAME is the full pathname of the current batch file. It is an empty string if no batch file is currently being processed. ═══ 6.11.13. _BG - Background color ═══ _BG is a string containing the first three letters of the current background screen output color (for example, "Bla"). ═══ 6.11.14. _BOOT - Boot drive letter, without a colon ═══ _BOOT is the boot drive letter, without a colon (for example, "C"). ═══ 6.11.15. _CI - Current cursor shape in insert mode ═══ _CI is the current shape of the cursor in insert mode, as a percentage (see SETDOS /S and CursorIns). ═══ 6.11.16. _CMDPROC - Command processor name ═══ _CMDPROC is the name of the current command processor. Each JP Software command processor returns a different value, as follows: Product Returns 4DOS "4DOS" 4OS2 "4OS2" 4NT "4NT" Take Command/16 "TCMD" Take Command/32 "TCMD32" Take Command for OS/2 "TCMDOS2" This variable is useful if you have batch files running in more than one environment, and need to take different actions depending on the underlying command processor. If you also need to determine the operating system, see _DOS. ═══ 6.11.17. _CO - Current cursor shape in overstrike mode ═══ _CO is the current shape of the cursor in overstrike mode, as a percentage (see SETDOS /S and CursorOver). ═══ 6.11.18. _CODEPAGE - Current code page number ═══ _CODEPAGE is the current code page number (see CHCP). ═══ 6.11.19. _COLUMN - Current cursor column ═══ _COLUMN is the current cursor column (for example, "0" for the left side of the screen). ═══ 6.11.20. _COLUMNS - Screen width ═══ _COLUMNS is the current number of screen columns (for example, "80"). See Resizing the Take Command Window for additional details on screen size. ═══ 6.11.21. _COUNTRY - Current country code ═══ _COUNTRY is the current country code. ═══ 6.11.22. _CPU - CPU type (386, 486, 586) ═══ _CPU is the CPU type: 386 i386 486 i486 586 Pentium ═══ 6.11.23. _CWD - Current drive and directory (d:\path) ═══ _CWD is the current working directory in the format d:\pathname. ═══ 6.11.24. _CWDS - Current drive and directory with trailing backslash ═══ (d:\path\) _CWDS has the same value as _CWD, except it ends the pathname with a backslash [\]. ═══ 6.11.25. _CWP - Current directory (\path) ═══ _CWP is the current working directory in the format \pathname. ═══ 6.11.26. _CWPS - Current directory with trailing backslash (\path\) ═══ _CWPS has the same value as _CWP, except it ends the pathname with a backslash [\]. ═══ 6.11.27. _DATE - Current date (mm-dd-yy) ═══ _DATE contains the current system date, in the format mm-dd-yy (U.S.), dd-mm-yy (Europe), or yy-mm-dd (Japan). ═══ 6.11.28. _DAY - Day of the month (1 - 31) ═══ _DAY is the day of the month (1 to 31). ═══ 6.11.29. _DISK - Current drive (C, D, etc.) ═══ _DISK is the current disk drive, without a colon (for example, "C"). ═══ 6.11.30. _DNAME - Name of file used to store file descriptions ═══ _DNAME is the name of the file used to store file descriptions. It can be changed with the DescriptionName directive in TCMDOS2.INI or the SETDOS /D command. ═══ 6.11.31. _DOS - Operating system (OS2, PM, DOS, etc.) ═══ _DOS is the operating system and command processor type. Each JP Software command processor returns a different value depending on the operating system, as follows: ┌─────────────────────┬───┬────┬───────┬───────┬───────┬───────┐ │ │DOS│OS/2│Windows│Windows│Windows│Windows│ │ │ │ │3.x │95 │98 │NT │ ├─────────────────────┼───┼────┼───────┼───────┼───────┼───────┤ │4DOS │DOS│DOS │DOS │DOS │DOS │ │ ├─────────────────────┼───┼────┼───────┼───────┼───────┼───────┤ │4OS2 │ │OS2 │ │ │ │ │ ├─────────────────────┼───┼────┼───────┼───────┼───────┼───────┤ │4NT │ │ │ │WIN95C │WIN98C │NT │ ├─────────────────────┼───┼────┼───────┼───────┼───────┼───────┤ │Take Command/16 │ │WIN │WIN │ │ │ │ ├─────────────────────┼───┼────┼───────┼───────┼───────┼───────┤ │Take Command/32 │ │ │ │WIN95 │WIN98 │WIN32 │ ├─────────────────────┼───┼────┼───────┼───────┼───────┼───────┤ │Take Command for OS/2│ │PM │ │ │ │ │ └─────────────────────┴───┴────┴───────┴───────┴───────┴───────┘ This variable is useful if you have batch files running in more than one environment, and need to take different actions depending on the underlying operating environment or command processor. If you want the current command processor name, use _CMDPROC. ═══ 6.11.32. _DOSVER - Operating system version (2.1, 3.0, etc.) ═══ _DOSVER is the current operating system version (for example, "4.0"). The version number is in decimal and uses the appropriate decimal separator for your country (to allow numeric comparisons with the IF and IFF commands.) ═══ 6.11.33. _DOW - Day of the week (Mon, Tue, Wed, etc.) ═══ _DOW is the first three characters of the current day of the week ("Mon", "Tue", "Wed", etc.). ═══ 6.11.34. _DOWI - Day of the week as an integer ═══ _DOW is the current day of the week as an integer (1=Sunday, 2=Monday, etc.). ═══ 6.11.35. _DOY - Day of the year (1 - 366) ═══ _DOY is the day of the year (1 to 366). ═══ 6.11.36. _FG - Foreground color ═══ _FG is a string containing the first three letters of the current foreground screen output color (for example, "Whi"). ═══ 6.11.37. _HLOGFILE - Current history log file name ═══ _HLOGFILE returns the name of the current history log file (or an empty string if LOG /H is OFF). See LOG for details on logging. ═══ 6.11.38. _HOUR - Hour (0 - 23) ═══ _HOUR is the current hour (0 - 23). ═══ 6.11.39. _KBHIT - Keystroke waiting in buffer (0 or 1) ═══ _KBHIT returns 1 if one or more keystrokes are waiting in the keyboard buffer, or 0 if the keyboard buffer is empty. ═══ 6.11.40. _LASTDISK - Last possible drive (E, F, etc.) ═══ _LASTDISK is the last valid drive letter, without a colon. ═══ 6.11.41. _LOGFILE - Current log file name ═══ _LOGFILE returns the name of the current log file (or an empty string if LOG is OFF). See LOG for details on logging. ═══ 6.11.42. _MINUTE - Minute (0 - 59) ═══ _MINUTE is the current minute (0 - 59). ═══ 6.11.43. _MONTH - Month of the year (1 - 12) ═══ _MONTH is the month of the year (1 to 12). ═══ 6.11.44. _MOUSE - Mouse driver flag (always 1 in Take Command for OS/2) ═══ _MOUSE always returns "1" in Take Command for OS/2. ═══ 6.11.45. _NDP - Coprocessor type (0, 387) ═══ _NDP is the coprocessor type: 0 no coprocessor is installed 387 80387, 80486DX, 80487, Pentium, or Pentium Pro ═══ 6.11.46. _PID - Take Command for OS/2 process ID (numeric) ═══ _PID is the current process ID number. ═══ 6.11.47. _PIPE - Whether running in a pipe (0 or 1) ═══ _PIPE returns 1 if the current process is running inside a pipe or 0 otherwise. ═══ 6.11.48. _PPID - Parent process ID (numeric) ═══ _PPID is the process ID number of the parent process. ═══ 6.11.49. _PTYPE - OS/2 process type (PM) ═══ _PTYPE is the current OS/2 process type. It is included for compatibility with 4OS2, but will always return PM in Take Command for OS/2. ═══ 6.11.50. _ROW - Current cursor row ═══ _ROW is the current cursor row (for example, "0" for the top of the screen). ═══ 6.11.51. _ROWS - Screen height ═══ _ROWS is the current number of screen rows (for example, "25"). See Resizing the Take Command Window for additional details on screen size. ═══ 6.11.52. _SECOND - Second (0 - 59) ═══ _SECOND is the current second (0 - 59). ═══ 6.11.53. _SELECTED - Highlighed Text ═══ _SELECTED returns the first line of text highlighted in the Take Command window. If no text has been highlighted, _SELECTED returns an empty string. ═══ 6.11.54. _SHELL - Shell level (0, 1, 2, ...) ═══ _SHELL is the current shell nesting level. The primary shell is level "0", and each subsequent secondary shell increments the level by 1. ═══ 6.11.55. _SID - Current OS/2 session ID ═══ _SID is the session ID number. ═══ 6.11.56. _SYSERR - Last OS/2 error code ═══ _SYSERR is the error code of the last operating system error. You will need a technical or programmer's manual to understand these error values. ═══ 6.11.57. _TIME - Current time (hh:mm:ss) ═══ _TIME contains the current system time in the format hh:mm:ss. The separator character may vary depending upon your country information. ═══ 6.11.58. _TRANSIENT - Transient shell flag (0 or 1) ═══ _TRANSIENT is "1" if the current shell is transient (started with a /C, see Startup Options for details), or "0" otherwise. ═══ 6.11.59. _WINTITLE - Current window title ═══ _WINTITLE returns the title of the current window. ═══ 6.11.60. _XPIXELS - Horizontal screen size in pixels ═══ _XPIXELS is the physical screen horizontal size in pixels. ═══ 6.11.61. _YEAR - Year (1980 - 2099) ═══ _YEAR is the current year (1980 to 2099). ═══ 6.11.62. _YPIXELS - Vertical screen size in pixels ═══ _YPIXELS is the physical screen vertical size in pixels. ═══ 6.12. Variable Functions ═══ Variable functions are like internal variables, but they take one or more arguments (which can be environment variables or even other variable functions) and they return a value. Like all environment variables, these variable functions must be preceded by a percent sign in normal use (%@EVAL, %@LEN, etc.). All variable functions must have square brackets enclosing their argument(s). The argument(s) to a variable function cannot exceed 255 characters in length for all arguments taken as a group. The variable functions are useful in aliases and batch files to check on available system resources, manipulate strings and numbers, and work with files and filenames. The list below gives a one-line description of each function, and a cross- reference which selects a separate help topic on that function. A few of the variables are simple enough that the one-line description is sufficient, but in most cases you should check for any additional information in the cross- referenced explanation if you are not already familiar with a function. You can also obtain help on any function with a HELP @functionname command at the prompt. Many functions return values based on information provided by your operating system. Such functions will only return correct information if the operating system provides it. For example, @READY will not return accurate results if your operating system does not provide correct disk drive status information to Take Command. Several functions return filenames or parts of filenames. On HPFS drives the strings returned by these functions may contain whitespace or other special characters. To avoid problems which could be caused by these characters, quote the returned name before you pass it to other commands, for example (either of these methods would work): set fname="%@findfirst[pro*.*]" echo First PRO file contains: type %fname ..... set fname=%@findfirst[pro*.*] echo First PRO file contains: type "%fname" ..... If you don't use the quotes in the SET or TYPE command in this example, TYPE will not interpret any whitespace or special characters in the name properly. See the discussion after the function list for some additional information, and examples of how these functions can be used. For a more comprehensive set of examples see the EXAMPLES.BTM file which came with your copy of Take Command. The variable functions are: System status @DOSMEM[b|k|m] Size of largest free memory block @READSCR[row,col,len] Read characters from the screen Drives and devices @CDROM[d:] CD-ROM drive detection (0 or 1) @DEVICE[name] Character device detection @DISKFREE[d:, b|k|m] Free disk space @DISKTOTAL[d:,b|k|m] To tal disk space @ DISKUSED[d:,b|k|m] Used disk space @FSTYPE[d:] File system type (FAT, HPFS, CDFS, etc.) @LABEL[d:] Volume label @READY[d:] Drive ready status (0 or 1) @REMOTE[d:] Remote (network) drive detection (0 or 1) @REMOVABLE[d:] Removable drive detection (0 or 1) Files @ATTRIB[filename,[nrhsda]] File attribute test (0 or 1) @DESCRIPT[filename] File description @EAREAD[filename,EAname] Reads extended attribute @EAWRITE[filename,EAname,[value]] Writes extended attribute @EXETYPE[filename] Executable file type (DOS, PM, WIN, etc.) @FILEAGE[filename[,acw]] File age (date and time) @FILECLOSE[n] Close a file @FILEDATE[filename[,acw]] File date @FILEOPEN[filename,mode[,type]] Open a file @FILEREAD[n [,length]] Read next line from a file @FILES[filename[,-nrhsda]] Count files matching a wildcard @FILESEEK[n,offset,start] Move a file pointer @FILESEEKL[n,line] Move a file pointer to a specified line @FILESIZE[filename,b|k|m] Size of files matching a wildcard @FILETIME[filename[,acw]] File time @FILEWRITE[n,text] Write next line to a file @FILEWRITEB[n,length,text] Write data to a file @FINDCLOSE[filename] Terminate an @FINDFIRST / @FINDNEXT scan @FINDFIRST[filename,nrhsda] Find first matching file @FINDNEXT[filename,nrhsda] Find next matching file @LINE[filename,n] Read a random line from a file @LINES[filename] Count lines in a file @SEARCH[filename] Path search @UNIQUE[d:\path] Create file with unique name File names @EXPAND[filename,nrhsda] Returns all names that match filename. @EXT[filename] File extension @FILENAME[filename] File name and extension @FULL[filename] Full file name with path @NAME[filename] File name without path or extension @PATH[filename] File path without name Strings and characters @ASCII[c] Numeric ASCII value for a character @CHAR[n] Character value for numeric ASCII @FORMAT[[- ][x][.y],string] Reformat a string @INDEX[string1,string2] Position of one string in another @INSERT[n,string1,string2] Inserts string1 into string2 @INSTR[start,length,string] Extract a substring @LEFT[n,string] Leftmost n characters of string @LEN[string] Length of a string @LOWER[string] Convert string to lower case @REPEAT[c,n] Repeat a character @REPLACE[str1,str2,text] Replace str1 with str2 in text. @RIGHT[n,string] Rightmost n characters of substring @STRIP[chars,string] Strips all chars from string. @SUBSTR[string,start,length] Extract a substring @TRIM[string] Remove blanks from a string @UPPER[string] Convert string to upper case @WILD[str1,str2] Compares strings using wildcards. @WORD[["sep",]n,string] Extract a word from a string @WORDS[["sep",]string] Counts words in a string Numbers and arithmetic @COMMA[n] Inserts commas in a number @CONVERT[input,output,value] Convert from input base to output base. @DEC[%var] Decremented value of a variable @EVAL[expression] Arithmetic calculations @INC[%var] Incremented value of a variable @INT[n] Integer part of a number @NUMERIC[string] Test if a string is numeric @RANDOM[min,max] Generate a random integer Dates and times @DAY[mm-dd-yy] Returns day of the month for date. @DATE[mm-dd-yy] Convert date to number of days @DOW[mm-dd-yy] Returns day of the week for date @DOWI[mm-dd-yy] Returns day of the week as integer @DOY[mm-dd-yy] Returns day of the year for date @MAKEAGE[n] Convert date to file timestamp format @MAKEDATE[n] Convert number of days to date @MAKETIME[n] Convert number of seconds to time @MONTH[mm-dd-yy] Returns month for date @TIME[hh:mm:ss] Convert time to number of seconds @YEAR[mm-dd-yy] Returns year for date Utility @ALIAS[name] Value of an alias @CLIP[n] Returns line n from clipboard @EXEC[command] Execute a command @EXECSTR[command] Execute, return string @IF[condition,true,false] Evaluates an expression @REXX[expr] Execute a REXX expression @SELECT[file,t,l,b,r,title] Menu selection @TIMER[n] Elapsed time of specified timer Examples You can use variable functions in a wide variety of ways depending on your needs. We've included a few examples below to give you an idea of what's possible. For a more comprehensive set of examples see the EXAMPLES.BTM file which came with your copy of Take Command. To set the prompt to show the amount of free memory (see PROMPT for details on including variable functions in your prompt): [c:\] prompt (%%@dosmem[K]K) $p$g Set up a simple command-line calculator. The calculator is used with a command like CALC 3 * (4 + 5): [c:\] alias calc `echo The answer is: %@eval[%&]` The following batch file uses variable functions to implement a "once a day" execution of a group of commands. It works by constructing a 6-digit number "yymmdd" from today's date, and comparing that to a number of the same type stored in the file C:\ONCEADAY.DAT. If today's date is numerically larger than the saved date, and the time is after 6:00 AM, then the "once a day" commands are run, and today's date is saved in the file as the new date for comparison. Otherwise, no action is taken. You can make this file simpler using the %@DATE and %@TIME functions instead of using %@INSTR to extract substrings of the %_DATE and %_TIME variables; we used the approach shown to demonstrate the use of %@INSTR. rem Temporary variables used to shorten example lines: rem DD is _date, DY is yymmdd date, TM is _time set dd=%_date set dy=%@instr[6,2,%dd]%@instr[0,2,%dd]%@instr[3,2,%dd] set lastdate=0 iff exist c:\onceaday.dat then set lastdate=%@line[onceaday.dat,0] endiff iff %dy gt %lastdate then set tm=%_time iff "%@instr[0,2,%tm]%@instr[3,2,%tm]" gt "0600" then rem Commands to be executed once a day go here echo %dy > c:\onceaday.dat endiff endiff ═══ 6.12.1. @ALIAS - Value of an alias ═══ @ALIAS[name] Returns the contents of the specified alias as a string, or a null string if the alias doesn't exist. When manipulating strings returned by @ALIAS you may need to disable certain special characters with the SETDOS /X command. Otherwise, command separators, redirection characters, and other similar "punctuation" in the alias may be interpreted as part of the current command, rather than part of a simple text string. ═══ 6.12.2. @ASCII - Numeric ASCII value for a character ═══ @ASCII[c]: Returns the numeric value of the specified ASCII character as a string. For example %@ASCII[A] returns 65. You can put an escape character [^] before the actual character to process. This allows quotes and other special characters as the argument (e.g., %@ASCII[^`]). ═══ 6.12.3. @ATTRIB - File attribute test (0 or 1) ═══ @ATTRIB[filename[,-nrhsda[,p]]]: Returns a "1" if the specified file has the matching attribute(s); otherwise returns a "0". The attributes are: N Normal (no attributes set) R Read-only H Hidden S System D Directory A Archive The attributes (other than N) can be combined (for example %@ATTRIB[MYFILE,HS]). Normally ATTRIB will only return a "1" if all of the attributes match. However, if a final ,p is included (for partial match), then @ATTRIB will return a "1" if any of the attributes match. For example, %@ATTRIB[MYFILE,HS,p] will return a "1" if MYFILE has the hidden, system, or both attributes. Without ,p the function will return a "1" only if MYFILE has both attributes. You can prefix an attribute with "-" to mean "this attribute must be off". For example, %@ATTRIB[MYFILE,H-R] will return a "1" if MYFILE has the hidden attribute but not the read-only attribute. If you do not specify any attributes, @ATTRIB will return the attributes of the specified file in the format RHSAD, rather than a "0" or "1". Attributes which are not set will be replaced with an underscore. For example. if SECURE.DAT has the read-only, hidden, and archive attributes set, %@ATTRIB[SECURE.DAT] would return "RH_A_" (without the quotes). If the file does not exist, @ATTRIB will return an empty string. The filename must be in quotes if it contains whitespace or special characters. ═══ 6.12.4. @CDROM - CD-ROM drive detection (0 or 1) ═══ @CDROM[d:]: Returns "1" if the drive is a CD-ROM or "0" otherwise. The drive letter must be followed by a colon. ═══ 6.12.5. @CHAR - Character value for numeric ASCII ═══ @CHAR[n]: Returns the character corresponding to an ASCII numeric value. For example %@CHAR[65] returns A. ═══ 6.12.6. @CLIP - Returns line from the clipboard ═══ @CLIP[n]: Returns line n from the clipboard. The first line is numbered 0. "**EOC**" is returned for all line numbers beyond the end of the clipboard. ═══ 6.12.7. @COMMA - Inserts commas in a number ═══ @COMMA[n]: Returns the number n with commas (or the appropriate thousands separator for your current country setting) inserted where appropriate. ═══ 6.12.8. @CONVERT - Converts between number bases ═══ @CONVERT[input,output,value]: Converts a numeric string (value) from one number base (input) to another (output). Valid bases range from 2 to 36. The value must be between 0 and 2**32-1 (2,147,483,647). No error is returned if value is outside that range. For example, to convert "1010101" from binary to decimal, use this command: %@convert[2,10,1010101] ═══ 6.12.9. @DATE - Convert date to number of days ═══ @DATE[mm-dd-yy]: Returns the number of days since January 1, 1980 for the specified date. DATE uses the date format and separators mandated by your country code (for example dd.mm.yy in Germany, or yy-mm-dd in Japan). The year can be entered as a 4-digit or 2-digit value. Two-digit years between 80 and 99 are interpreted as 1980-1999; values between 00 and 79 are interpreted as 2000 - 2079. ═══ 6.12.10. @DAY - Convert date to number of days ═══ @DATE[mm-dd-yy]: Returns the numeric day of the month for the specified date. DAY uses the date format and separators mandated by your country code (for example dd.mm.yy in Germany, or yy-mm-dd in Japan). The year can be entered as a 4-digit or 2-digit value. Two-digit years between 80 and 99 are interpreted as 1980-1999; values between 00 and 79 are interpreted as 2000 - 2079. ═══ 6.12.11. @DEC - Decremented value of a variable ═══ @DEC[%var]: Returns the same value as @EVAL[%var-1]. That is, it retrieves and decrements the value of a variable. The variable itself is not changed; to do so, use a command like this: set var=%@dec[%var] ═══ 6.12.12. @DESCRIPT - File description ═══ @DESCRIPT[filename] Returns the file description for the specified filename (see DESCRIBE). The filename must be in quotes if it contains whitespace or special characters. ═══ 6.12.13. @DEVICE - Character device detection ═══ @DEVICE[name]: Returns "1" if the specified name is a character device (such as a printer or serial port), or "0" if not. ═══ 6.12.14. @DISKFREE - Free disk space ═══ @DISKFREE[d:,b|k|m]: Returns the amount of free disk space on the specified drive. The drive letter must be followed by a colon. DOS networks with large server disk drives (over 2 GB) may report disk space values that are too small when @DISKFREE is used. If this occurs, it is because the network software does not report the propoer value to Take Command. The "b|k|m" argument specified the format of the returned value: b return the number of bytes K return the number of kilobytes (bytes / 1,024) k return the number of thousands of bytes (bytes / 1,000) M return the number of megabytes (bytes / 1,048,576) m return the number of millions of bytes (bytes / 1,000,000) You can include commas in the results from a "b|k|m" function by appending a "c" to the argument. For example, to add commas to a "b" or number of bytes result, enter "bc" as the argument. ═══ 6.12.15. @DISKTOTAL - Total disk space ═══ @DISKTOTAL[d:,b|k|m]: Returns the total disk space on the specified drive. The drive letter must be followed by a colon. The "b|k|m" argument specified the format of the returned value: b return the number of bytes K return the number of kilobytes (bytes / 1,024) k return the number of thousands of bytes (bytes / 1,000) M return the number of megabytes (bytes / 1,048,576) m return the number of millions of bytes (bytes / 1,000,000) You can include commas in the results from a "b|k|m" function by appending a "c" to the argument. For example, to add commas to a "b" or number of bytes result, enter "bc" as the argument. ═══ 6.12.16. @DISKUSED - Used disk space ═══ @DISKUSED[d:,b|k|m]: Returns the amount of disk space in use by files and directories on the specified drive. The drive letter must be followed by a colon. The "b|k|m" argument specified the format of the returned value: b return the number of bytes K return the number of kilobytes (bytes / 1,024) k return the number of thousands of bytes (bytes / 1,000) M return the number of megabytes (bytes / 1,048,576) m return the number of millions of bytes (bytes / 1,000,000) You can include commas in the results from a "b|k|m" function by appending a "c" to the argument. For example, to add commas to a "b" or number of bytes result, enter "bc" as the argument. ═══ 6.12.17. @DOSMEM - Size of largest free memory block ═══ @DOSMEM[b|k|m]: Returns the size of the largest free memory block (either in physical or virtual memory). The "b|k|m" argument specified the format of the returned value: b return the number of bytes K return the number of kilobytes (bytes / 1,024) k return the number of thousands of bytes (bytes / 1,000) M return the number of megabytes (bytes / 1,048,576) m return the number of millions of bytes (bytes / 1,000,000) You can include commas in the results from a "b|k|m" function by appending a "c" to the argument. For example, to add commas to a "b" or number of bytes result, enter "bc" as the argument. ═══ 6.12.18. @DOW - Day of the week ═══ @DOW[mm-dd-yy]: Returns the first three characters of the day of the week for the specified date ("Mon", "Tue", "Wed", etc.). DOW uses the date format and separators mandated by your country code (for example dd.mm.yy in Germany, or yy-mm-dd in Japan). The year can be entered as a 4- digit or 2-digit value. Two-digit years between 80 and 99 are interpreted as 1980-1999; values between 00 and 79 are interpreted as 2000 - 2079. ═══ 6.12.19. @DOWI - Day of the week as an integer ═══ @DOWI[mm-dd-yy]: Returns the day of the week for the specified date as an integer (1 = Sunday, 2 = Monday, etc.). DOWI uses the date format and separators mandated by your country code (for example dd.mm.yy in Germany, or yy-mm-dd in Japan). The year can be entered as a 4-digit or 2- digit value. Two-digit years between 80 and 99 are interpreted as 1980-1999; values between 00 and 79 are interpreted as 2000 - 2079. ═══ 6.12.20. @DOY - Day of the year ═══ @DOY[mm-dd-yy]: Returns the day of the year for the specified date (1 - 366). DOY uses the date format and separators mandated by your country code (for example dd.mm.yy in Germany, or yy-mm-dd in Japan). The year can be entered as a 4-digit or 2-digit value. Two-digit years between 80 and 99 are interpreted as 1980-1999; values between 00 and 79 are interpreted as 2000 - 2079. ═══ 6.12.21. @EAREAD - Reads Extended Attribute ═══ @EAREAD[filename,EAname]: Returns the specified extended attribute (EAname) for a file, or an empty string if the extended attribute does not exist. This function can only read EAs stored as text; it cannot read binary EAs. Wildcards cannot be used in the filename. The filename must be in quotes if it contains whitespace or special characters. For example, to read the .SUBJECT extended attribute for README.TXT: set subject=%@earead[readme.txt,.subject] ═══ 6.12.22. @EAWRITE - Writes Extended Attribute ═══ @EAWRITE[filename, EAname, [value]]: Creates or updates the extended attribute named EAname for the specified file. If the value is not included, the extended attribute is deleted. Returns "0" for success or "-1" for failure. This function can only write EAs stored as text; it cannot write binary EAs. Wildcards cannot be used in the file name and the filename must be in quotes if it contains whitespace or special characters. For example, to set the .SUBJECT extended attribute for README.TXT (enter this on one line): if %@eawrite[readme.txt,.subject,Installation notes for latest version] != 0 echo EAWRITE failed! ═══ 6.12.23. @EVAL - Arithmetic calculations ═══ @EVAL[expression]: Evaluates an arithmetic expression. @EVAL supports addition (+), subtraction (-), multiplication (*), division (/), integer division (\, returns the integer part of the quotient), modulo (%%), and integer exponentiation (**). The expression can contain environment variables and other variable functions. @EVAL also supports parentheses, commas, and decimals. Parentheses can be nested. @EVAL will strip leading and trailing zeros from the result. When evaluating expressions, **, *, /, and %% take precedence over + and -. For example, 3 + 4 * 2 will be interpreted as 3 + 8, not as 7 * 2. To change this order of evaluation, use parentheses to specify the order you want. To insure that your @EVAL expressions are interpreted correctly, spaces should be placed on both sides of an operator, for example: %@eval[(20 %% 3) + 4] The maximum precision is 16 digits to the left of the decimal point and 0 to 8 digits to the right of the decimal point. You can alter the default precision to the right of the decimal point from the Options 2 page of the configuration notebook, with the EvalMax and EvalMin directives in TCMDOS2.INI, and with the SETDOS /F command. You can alter the decimal character with the configuration notebook, the DecimalChar directive, or the SETDOS /G command. You can alter the precision for a single evaluation with the construct @EVAL[expression=x.y]. The x value specifies the the minimum decimal precision (the minimum number of decimal places displayed); the y value sets the maximum decimal (rounding) precision. If x is greater than y, it is ignored. You can specify either or both arguments. For example: @EVAL[3 / 7=.4] returns 0.4286 @EVAL[3 / 7=2] returns 0.42857143 @EVAL[3 / 7=2.4] returns 0.50 Also see @DEC and @INC. ═══ 6.12.24. @EXEC - Execute a command ═══ @EXEC[command]: Execute the command and return the numeric exit code. The command can be an alias, internal command, external command, .BTM file, .CMD file, or .BAT file. If you preface the command name with an '@' then @EXEC will return an empty string. @EXEC is primarily intended for running a program from within the PROMPT. It is a "back door" entry into command processing and should be used with extreme caution. Incorrect or recursive use of @EXEC may hang your system. By default, @EXEC returns the result code from the command; if you preface the command name with an '@' then @EXEC will return an empty string. ═══ 6.12.25. @EXECSTR - Execute a command and return output ═══ @EXECSTR[command]: Runs the specified command and returns the first line written to STDOUT by that command. @EXECSTR is a "back door" entry into command processing and should be used with extreme caution. Incorrect or recursive use of @EXECSTR may hang your system. @EXECSTR is useful for retrieving a result from an external utility -- for example, if you have an external utility called NETTIME.EXE which retireves the time of day from your network server and writes it to standard output, you could save it in an environment variable using a command like this: set server_time=%@execstr[d:\path\nettime.exe] If the same utility reurned a result properly formatted for the TIME command you could also use it to set the time on your system: [c:\] time %@execstr[d:\path\nettime.exe] ═══ 6.12.26. @EXETYPE - Executable file type (DOS, PM, WIN, etc.) ═══ @EXETYPE[filename]: Returns the application type as a string: DOS DOS .COM, .EXE, or .BAT file AVIO OS/2 Character mode, windowed FS OS/2 Character mode, full-screen PM OS/2 Presentation Manager WIN Windows 3 UNKNOWN Any other file ═══ 6.12.27. @EXPAND - All files that match wildcard ═══ @EXPAND[filename[-nrhsda]]: Returns, on a single line, the names of all files and directories that match the filename, which may contain wildcards and include lists. Returns an empty string if no files match. If the file list is longer than the allowed command line length, it will be truncated without an error message. The second argument, if included, defines the attributes of the files that will be included in the search. The attributes are: N Normal (no attributes set) R Read-only H Hidden S System D Directory A Archive The attributes (other than N) can be combined. You can prefix an attribute with "-" to mean "this attribute must be off". If the attribute argument is not used, hidden files, system files, and directories will be excluded from the returned list; all other files which match the filename will be included. The filename must be in quotes if it contains whitespace or special characters. On an HPFS drive, the returned filenames may contain whitespace or special characters. To avoid problems which could be caused by these characters, quote the returned names before you pass them to other commands. ═══ 6.12.28. @EXT - File extension ═══ @EXT[filename]: Returns the extension from a file name, without a leading period. On volumes which support long file names, the extension can be up to 64 characters long. On traditional FAT drives it can be up to 3 characters long. The filename must be in quotes if it contains whitespace or special characters. On an HPFS drive, the returned extension may contain whitespace or special characters. To avoid problems which could be caused by these characters, quote the returned extension before you pass it to other commands. ═══ 6.12.29. @FILEAGE - File age (date and time) ═══ @FILEAGE[filename[,acw]]: Returns the date and time of the file as a single numeric value. The number can be used to compare the relative ages of two or more files, but can not be used for date and time calculations as it is not returned in identifiable units. The optional second argument selects which date field is returned for files on an HPFS drive: a means the last access date, c means the creation date, and w means the last modification (write) date, which is the default. Also see @MAKEAGE. ═══ 6.12.30. @FILECLOSE - Close a file ═══ @FILECLOSE[n]: Closes the file whose handle is n. You cannot close handles 0, 1 or 2. Returns "0" if the file closed OK or "-1" if an error occurred. This function should only be used with file handles returned by @FILEOPEN! If you use it with any other number you may damage other files opened by Take Command (or by the program which started Take Command), or hang your system. ═══ 6.12.31. @FILEDATE - File date ═══ @FILEDATE[filename[,acw]]: Returns the date a file was last modified, in the default country format (mm-dd-yy for the US). The filename must be in quotes if it contains whitespace or special characters. The optional second argument selects which date field is returned for files on an HPFS drive: a means the last access date, c means the creation date, and w means the last modification (write) date, which is the default. ═══ 6.12.32. @FILENAME - File name and extension ═══ @FILENAME[filename]: Returns the name and extension of a file, without a path. The filename must be in quotes if it contains whitespace or special characters. On HPFS drives, the returned filename may contain whitespace or other special characters. To avoid problems which could be caused by these characters, quote the returned name before you pass it to other commands. ═══ 6.12.33. @FILEOPEN - Open a file ═══ @FILEOPEN[filename, read | write | append[,b|t]]: Opens the file in the specified mode and returns the file handle as an integer. The optional third parameter controls whether the file is opened in binary or text mode. Text mode (the default) should be used to read text using @FILEREAD without a "length", and to write text using @FILEWRITE. Binary mode should be used to read binary data with @FILEREAD with a "length", and to write binary data with @FILEWRITEB. Returns "-1" if the file cannot be opened. The filename must be in quotes if it contains whitespace or special characters. @FILEOPEN can also open named pipes. The pipe name must begin with \\.\pipe\. @FILEOPEN first tries to open an existing pipe; if that fails it tries to create a new pipe. Pipes are opened in blocking mode, duplex access, byte- read mode, and inheritable. For more information on named pipes see your OS/2 documentation. ═══ 6.12.34. @FILEREAD - Read data from a file ═══ @FILEREAD[n[,length]]: Reads data from the file whose handle is n. Returns "**EOF**" if you attempt to read past the end of the file. If length is not specified, @FILEREAD reads up to the next CR or LF character. If length is specified, @FILEREAD reads the specified number of bytes regardless of any end of line characters. This function should only be used with file handles returned by @FILEOPEN! If you use it with any other number you may damage other files opened by Take Command (or by the program which started Take Command), or hang your system. ═══ 6.12.35. @FILES - Count files matching a wildcard ═══ @FILES[filename[,-nrhsda]]: Returns the number of files that match the filename, which may contain wildcards and include lists. The filename must refer to a single directory; to check several directories, use @FILES once for each directory, and add the results together with @EVAL. The filename must be in quotes if it contains whitespace or special characters. The second argument, if included, defines the attributes of the files that will be included in the search. The attributes are: N Normal (no attributes set) R Read-only H Hidden S System D Directory A Archive The attributes (other than N) can be combined. You can prefix an attribute with "-" to mean "everything except files with this attribute." ═══ 6.12.36. @FILESEEK - Move a file pointer to an offset ═══ @FILESEEK[n,offset,start]: Moves the file pointer offset bytes in the file whose handle is n. Returns the new position of the pointer, in bytes from the start of the file. Set start to 0 to seek relative to the beginning of the file, 1 to seek relative to the current file pointer, or 2 to seek relative to the end of the file. The offset value may be negative (seek backward), positive (seek forward), or zero (return current position, but do not change it). This function should only be used with file handles returned by @FILEOPEN! If you use it with any other number you may damage other files opened by Take Command (or by the program which started Take Command), or hang your system. ═══ 6.12.37. @FILESEEKL - Move a file pointer to a line number ═══ @FILESEEKL[n,line]: Moves the file pointer to the specified line in the file whose handle is n. The first line in the file is numbered 0. Returns the new position of the pointer, in bytes from the start of the file. @FILESEEKL must read each line of the file up to the target line in order to position the pointer, and will therefore cause significant delays if used in a long loop or on a large file. This function should only be used with file handles returned by @FILEOPEN! If you use it with any other number you may damage other files opened by Take Command (or by the program which started Take Command), or hang your system. ═══ 6.12.38. @FILESIZE - Size of files matching a wildcard ═══ @FILESIZE[filename,b|k|m[,a]]: Returns the size of a file, or "-1" if the file does not exist. If the filename includes wildcards or an include list, returns the combined size of all matching files. The filename must be in quotes if it contains whitespace or special characters. The optional third argument a (allocated), if used, instructs @FILESIZE to return the amount of space allocated for the file(s) on the disk, rather than the amount of data in the file. Network drives and compressed drives may not always report allocated sizes accurately, depending on the way the network or disk compression software is implemented. The "b|k|m" argument specified the format of the returned value: b return the number of bytes K return the number of kilobytes (bytes / 1,024) k return the number of thousands of bytes (bytes / 1,000) M return the number of megabytes (bytes / 1,048,576) m return the number of millions of bytes (bytes / 1,000,000) You can include commas in the results from a "b|k|m" function by appending a "c" to the argument. For example, to add commas to a "b" or number of bytes result, enter "bc" as the argument. ═══ 6.12.39. @FILETIME - File time ═══ @FILETIME[filename[,acw]]: Returns the time a file was last modified, in hh:mm format. The filename must be in quotes if it contains whitespace or special characters. The optional second argument selects which time field is returned for files on HPFS drive: a means the last access time, c means the creation time, and w means the last modification (write) time, which is the default. ═══ 6.12.40. @FILEWRITE - Write next line to a file ═══ @FILEWRITE[n,text]: Writes a line to the file whose handle is n. Returns the number of bytes written, or "-1" if an error occurred. n must be a handle returned by @FILEOPEN; or 1 (for standard output) or 2 (for standard error). This function should only be used with file handles returned by @FILEOPEN! If you use it with any other number you may damage other files opened by Take Command (or by the program which started Take Command), or hang your system. ═══ 6.12.41. @FILEWRITEB - Write bytes from a string to a file ═══ @FILEWRITEB[n,length,string]: Writes the specified number of bytes from the string to the file whose handle is n. Returns the number of bytes written, or "-1" if an error occurred. This function should only be used with file handles returned by @FILEOPEN! If you use it with any other number you may damage other files opened by Take Command (or by the program which started Take Command), or hang your system. ═══ 6.12.42. @FINDCLOSE - Terminate a find first / find next scan ═══ @FINDCLOSE[filename]: Signals the end of a @FINDFIRST / @FINDNEXT sequence. You must use this function to release the directory search handle. ═══ 6.12.43. @FINDFIRST - Find first matching file ═══ @FINDFIRST[filename [,[-]nrhsda]]: Returns the name of the first file that matches the filename, which may include wildcards and/or an include list. Returns an empty string if no files match. The second argument, if included, defines the attributes of the files that will be included in the search. The attributes are: N Normal (no attributes set) R Read-only H Hidden S System D Directory A Archive The attributes (other than N) can be combined. @FINDFIRST will only find a file if all of the attributes match. You can prefix an attribute with "-" to mean "everything except files with this attribute." After @FINDFIRST or the last @FINDNEXT, you must use @FINDCLOSE to avoid running out of directory search handles. ═══ 6.12.44. @FINDNEXT - Find next matching file ═══ @FINDNEXT[[filename [,[-]nrhsda]]]: Returns the name of the next file that matches the filename(s) in the previous @FINDFIRST call. Returns an empty string when no more files match. @FINDNEXT should only be used after a successful call to @FINDFIRST. You do not need to include the filename parameter, because it must be the same as the previous @FINDFIRST call, unless you also want to specify file attributes for @FINDNEXT. The second argument, if included, defines the attributes of the files that will be included in the search. The attributes are: N Normal (no attributes set) R Read-only H Hidden S System D Directory A Archive The attributes (other than N) can be combined. @FINDFIRST will only find a file if all of the attributes match. You can prefix an attribute with "-" to mean "everything except files with this attribute." After the last @FINDNEXT, you must use @FINDCLOSE to avoid running out of directory search handles. ═══ 6.12.45. @FORMAT - Formats (justifies) a string ═══ @FORMAT[[-][x][.y],string]: Reformats a string, truncating it or padding it with spaces as necessary. If you use the minus [- ], the string is left-justified; otherwise, it is right-justified. The x value is the minimum number of characters in the result. The y value is the maximum number of characters in the result. You can combine the options as necessary. For example, Echo %@format[7,Hello] displays " Hello" while Echo %@format[.3,Hello] displays "Hel". ═══ 6.12.46. @FSTYPE - File system type (FAT, HPFS, CDFS, etc.) ═══ @FSTYPE[d:]: Returns the file system type for the specified drive. @FSTYPE will return "FAT" for a DOS-compatible drive with a file allocation table, "HPFS" for a drive that uses the OS/2 high performance file system, or "CDFS" for a CD-ROM drive. It may return other values if additional file systems have been installed. ═══ 6.12.47. @FULL - Full file name with path ═══ @FULL[filename]: Returns the fully qualified path name of a file. The filename must be in quotes if it contains whitespace or special characters. On an HPFS drive, the returned filename may contain whitespace or other special characters. To avoid problems which could be caused by these characters, quote the returned name before you pass it to other commands. ═══ 6.12.48. @IF - Evaluates a test condition ═══ @IF[condition,true,false]: Evaluates the condition and returns a string based on the result. The condition can include any of the tests allowed in the IF command. If the condition is true, @IF returns the first result string; if it is false, @IF returns the second string. For example, %IF[2==2,Correct!,Oops!] returns "Correct!" ═══ 6.12.49. @INC - Incremented value of a variable ═══ @INC[%var]: Returns the same value as %@EVAL[%var + 1]. That is, it retrieves and increments the value of a variable. The variable itself is not changed; to do so, use a command like this: set var=%@inc[%var] ═══ 6.12.50. @INDEX - Position of one string in another ═══ @INDEX[string1,string2] Returns the position of string2 within string1, or "-1" if string2 is not found. The first position in string1 is numbered 0. ═══ 6.12.51. @INSERT - Insert one string into another ═══ @INSERT[n, string1, string2]: Inserts string1 into string2 starting at position n. The first position in the string is postion 0. For example, %@insert[1,arm,wing] returns the string "warming." ═══ 6.12.52. @INSTR - Extract a substring ═══ @INSTR[start, length, string]: Returns a substring, starting at the position start and continuing for length characters. If the length is omitted, it will default to the remainder of the string. If the length is negative, the start is relative to the right side of the string. The first character in the string is numbered 0; if the length is negative, the last character is numbered 0. For example, %@INSTR[0,2,%_TIME] gets the current time and extracts the hour; %@INSTR[1,-2,%_TIME] extracts the seconds. If the string includes commas, it must be quoted with double quotes ["] or back-quotes [`]. The quotes do count in calculating the position of the substring. @SUBSTR is an older version of the same function. ═══ 6.12.53. @INT - Integer part of a number ═══ @INT[n]: Returns the integer part of the number n. ═══ 6.12.54. @LABEL - Volume label ═══ @LABEL[d:]: Returns the volume label of the specified disk drive. The drive letter must be followed by a colon. ═══ 6.12.55. @LEFT - Returns leftmost characters of a string ═══ @LEFT[n,string]: Returns the leftmost n characters from the string. If n is greater than the length of the string, returns the entire string. For example, %@LEFT[2,jpsoft] returns the string "jp." ═══ 6.12.56. @LEN - Length of a string ═══ @LEN[string]: Returns the length of a string. ═══ 6.12.57. @LINE - Read a line from a file ═══ @LINE[filename,n]: Returns line n from the specified file. The filename must be in quotes if it contains whitespace or special characters. The first line in the file is numbered 0. "**EOF**" is returned for all line numbers beyond the end of the file. @LINE works with files having lines of no more than 1023 characters; longer lines will not be counted accurately. The @LINE function must read each line of the file to find the line you request, and will therefore cause significant delays if used in a long loop or on a large file. For a more efficient method of processing each line of a file in sequence use the FOR command, or @FILEOPEN and a sequence of @FILEREADs. You can retrieve input from standard input if you specify CON as the filename. If you are redirecting input to @LINE using this feature, you must use command grouping or the redirection will not work properly (you can pipe to @LINE without a command group; this restriction applies only to input redirection). For example: (echo %@line[con,0]) < myfile.dat ═══ 6.12.58. @LINES - Count lines in a file ═══ @LINES[filename] Returns the line number of the last line in the file, or "-1" if the file is empty. The first line in the file is numbered 0, so (for example) @LINES will return 0 for a file containing one line. To get the actual number of lines, use %@INC[%@LINES[filename]]. @LINES must read each line of the file in order to count it, and will therefore cause significant delays if used in a long loop or on a large file. @LINES works with files having lines of no more than 1023 characters; longer lines will not be counted accurately. The filename must be in quotes if it contains whitespace or special characters. ═══ 6.12.59. @LOWER - Convert string to lower case ═══ @LOWER[string]: Returns the string converted to lower case. ═══ 6.12.60. @MAKEAGE - Convert date/time to file date/time ═══ @MAKEAGE[date[,time]]: Returns the date and time (if included) as a single value in the same format as @FILEAGE. @MAKEAGE can be used to compare the time stamp of a file with a specific date and time, for example: if %@fileage[myfile] lt %@makeage[1/1/85] echo OLD! The value returned by @MAKEAGE can be used for comparisons, but can not be used for date and time calculations because it is not in identifiable units. ═══ 6.12.61. @MAKEDATE - Convert number of days to date ═══ @MAKEDATE[n]: Returns a date (formatted according to the current country settings). n is the number of days since 1/1/80. This is the inverse of @DATE. ═══ 6.12.62. @MAKETIME - Convert number of seconds to time ═══ @MAKETIME[n]: Returns a time (formatted according to the current country settings). n is the number of seconds since midnight. This is the inverse of @TIME. ═══ 6.12.63. @MONTH - Month for specified date ═══ @MONTH[mm-dd-yy]: Returns the month number for the specified date (1-12). @MONTH uses the date format and separators mandated by your country code (for example dd.mm.yy in Germany, or yy-mm-dd in Japan). The year can be entered as a 4-digit or 2-digit value. Two-digit years between 80 and 99 are interpeted as 1980-1999; values between 00 and 79 are interpreted as 2000 - 2079. ═══ 6.12.64. @NAME - File name without path or extension ═══ @NAME[filename]: Returns the base name of a file, without the path or extension. The filename must be in quotes if it contains whitespace or special characters. On HPFS drives, the returned name may contain whitespace or other special characters. To avoid problems which could be caused by these characters, quote the returned name before you pass it to other commands. ═══ 6.12.65. @NUMERIC - Test if a string is numeric ═══ @NUMERIC[string]: Returns "1" if the string is composed entirely of digits (0 to 9), signs (+ or -), and the thousands and decimal separators. Otherwise, returns "0". ═══ 6.12.66. @PATH - File path without name ═══ @PATH[filename]: Returns the path from a filename, including the drive letter and a trailing backslash but not including the base name or extension. The filename must be in quotes if it contains whitespace or special characters. On HPFS drives, the returned path may contain whitespace or other special characters. To avoid problems which could be caused by these characters, quote the returned path before you pass it to other commands. ═══ 6.12.67. @RANDOM - Generate a random integer ═══ @RANDOM[min, max]: Returns a random value between min and max, inclusive. Min, max, and the returned value are all integers. The random number generator is initialized from the system clock the first time it is used after the command processor starts, so it will produce a different sequence of random numbers each time you use it. ═══ 6.12.68. @READSCR - Read characters from the screen ═══ @READSCR[row,col,length]: Returns the text displayed in the Take Command window at the specified location. The upper left corner of the screen is location 0,0. The row and column can be specified as an offset from the current cursor location by preceding either value with a [+] or [-]. For example: %@readscr[-2,+2,10] returns 10 characters from the screen, starting 2 rows above and 2 columns to the right of the current cursor position. You can also specify the row and column as offsets from the current cursor position. Begin the value with a plus sign [+] to read the screen the specified number of rows below (or columns to the right of) the current position, or with a minus sign [-] to read the screen above (or to the left of) the current position. ═══ 6.12.69. @READY - Drive ready status ═══ @READY[d:]: Returns "1" if the specified drive is ready; otherwise returns "0". The drive letter must be followed by a colon. ═══ 6.12.70. @REMOTE - Remote (network) drive detection ═══ @REMOTE[d:]: Returns "1" if the specified drive is a remote (network) drive; otherwise returns "0". The drive letter must be followed by a colon. ═══ 6.12.71. @REMOVABLE - Removable drive detection ═══ @REMOVABLE[d:]: Returns "1" if the specified drive is removable (i.e., a floppy disk or removable hard disk); otherwise returns "0". The drive letter must be followed by a colon. ═══ 6.12.72. @REPEAT - Repeat a character ═══ @REPEAT[c,n]: Returns the character c repeated n times. ═══ 6.12.73. @REPLACE - Replaces parts of a string ═══ @REPLACE[str1, str2, text]: Replaces all occurrences of str1 in the text string with str2. For example, %@replace[w,ch,warming] returns the string "charming." The search is case-sensitive. ═══ 6.12.74. @REXX - Execute a REXX expression ═══ @REXX[expr]: Calls the REXX interpreter to execute the expression. Returns the result string from REXX; if the REXX expression does not return a string, @REXX returns the REXX numeric result code. See REXX for more information. ═══ 6.12.75. @RIGHT - Returns rightmost characters of a string ═══ @RIGHT[n,string]: Returns the rightmost n characters from the string. If n is greater than the length of the string, returns the entire string. For example, %@right[4,jpsoft] returns the string "soft." ═══ 6.12.76. @SEARCH - Path search ═══ @SEARCH[filename[,path]]: Searches for the filename using the PATH environment variable or the specified path, appending an extension if one isn't specified. (See Executable Files and File Searches for details on the default extensions used when searching the PATH and the order in which the search proceeds.) Returns the fully-expanded name of the file including drive, path, base name, and extension, or an empty string if a matching file is not found. If wildcards are used in the filename, @SEARCH will search for the first file that matches the wildcard specification, and return the drive and path for that file plus the wildcard filename (e.g., E:\UTIL\*.COM). The filename and path must be in quotes if they contain whitespace or special characters. On HPFS drives, the returned path may contain whitespace or other special characters. To avoid problems which could be caused by these characters, quote the returned path before you pass it to other commands. ═══ 6.12.77. @SELECT - Menu selection ═══ @SELECT[filename,top,left,bottom,right,title[,1]]: Pops up a selection window with the lines from the specified file, allowing you to display menus or other selection lists from within a batch file. You can move through the selection window with standard popup window navigation keystrokes, including character matching. @SELECT returns the text of the line the scrollbar is on if you press Enter, or an empty string if you press Esc. The filename must be in quotes if it contains whitespace or special characters. The file size is limited only by available memory. To select from lines passed through input redirection or a pipe, use CON as the filename. If you use the optional 1 argument after the window title, the list will be sorted alphabetically. ═══ 6.12.78. @STRIP - Remove characters from a string ═══ @STRIP[chars,string]: Removes the characters in chars from the string and returns the result. For example, %@STRIP[AaEe,All Good Men] returns "ll Good Mn". The test is case sensitive. To include a comma in the chars string, enclose the entire first argument in quotes. @STRIP will remove the quotes before processing the string. ═══ 6.12.79. @SUBSTR - Extract a substring ═══ @SUBSTR[string,start,length]: An older version of @INSTR. The string parameter is at the start of the @SUBSTR argument list, and therefore cannot contain commas (because any commas in the string would be taken as argument separators). @INSTR, which has the string argument last, does not have this restriction. ═══ 6.12.80. @TIME - Convert time to number of seconds ═══ @TIME[hh:mm:ss]: Returns the number of seconds since midnight for the specified time. The time must be in 24-hour format; "am" and "pm" cannot be used. ═══ 6.12.81. @TIMER - Elapsed time of specified timer ═══ @TIMER[n]: Returns the current split time for a stopwatch started with the TIMER command. The value of n specifies the timer to read and can be 1, 2, or 3. ═══ 6.12.82. @TRIM - Remove blanks from a string ═══ @TRIM[string]: Returns the string with the leading and trailing white space (space and tab characters) removed. ═══ 6.12.83. @UNIQUE - Create file with unique name ═══ @UNIQUE[d:\path]: Creates a zero-length file with a unique name in the specified directory, and returns the full name and path. If no path is specified, the file will be created in the current directory. The file name will be FAT-compatible (8 character name and 3- character extension) regardless of the type of drive on which the file is created. This function allows you to create a temporary file without overwriting an existing file. The path must be in quotes if it contains whitespace or special characters. ═══ 6.12.84. @UPPER - Convert string to upper case ═══ @UPPER[string]: Returns the string converted to upper case. ═══ 6.12.85. @WILD - Compare strings using wildcards ═══ @WILD[str1,str2]: Performs a comparison of the two strings, and returns "1" if they match or "0" if they don't match. The second argument, str2, may contain wildcards or extended wildcards; the first argument, str1, may not. The test is not case sensitive. The following example tests whether the \UTIL directory (or any directory that begins with the characters UTIL) is included in the PATH: if %@wild[%path,*\UTIL*] == 1 command ═══ 6.12.86. @WORD - Extract a word from a string ═══ @WORD[["xxx",]n,string]: Returns the nth word in a string. The first word is numbered 0. If n is negative, words are returned from the end of the string. You can use the first argument, "xxx" to specify the separators that you wish to use. If you want to use a double quote as a separator, prefix it with an escape character. If you don't specify a list of separators, @WORD will consider only spaces, tabs, and commas as word separators. For example: %@WORD[2,NOW IS THE TIME] returns "THE" %@WORD[-0,NOW IS THE TIME] returns "TIME" %@WORD[-2,NOW IS THE TIME] returns "IS" %@WORD["=",1,2 + 2=4] returns "4" ═══ 6.12.87. @WORDS - Count words in a string ═══ @WORDS[["xxx"],string] Returns the number of words in the string. You can use the first argument, "xxx" to specify the separators that you wish to use. If you want to use a double quote as a separator, prefix it with an escape character. If you don't specify a list of separators, @WORD will consider only spaces, tabs, and commas as word separators. If the string argument is enclosed in quotation marks, you must enter a list of delimiters as well. ═══ 6.12.88. @YEAR - Return the year for a date. ═══ @YEAR[mm-dd-yy]: Returns the year for the specified date. The year can be specified as two digits or four digits; @YEAR returns the same number of digits included in its argument. @YEAR uses the date format and separators mandated by your country code (for example dd.mm.yy in Germany, or yy-mm-dd in Japan). The year can be entered as a 4-digit or 2-digit value. Two-digit years between 80 and 99 are interpeted as 1980-1999; values between 00 and 79 are interpreted as 2000 - 2079. ═══ 7. Configuring Take Command ═══ You can alter Take Command to match your style of computing. Most of the configuration of Take Command is controlled through a file of initialization information called TCMDOS2.INI. The information in this file can be controlled in two ways: with the configuration notebook and by editing the TCMDOS2.INI file with any ASCII editor. Both methods are discussed in this section. We also discuss many ways of configuring Take Command in other parts of the online help: With aliases you can set default options for internal commands and create new commands (see Aliases and the ALIAS command.). With executable extensions you can associate data files with the applications you use to open them. With the FILECOMPLETION environment variable and the FileCompletion .INI directive you can customize filename completion to match the command you are working with. With the COLORDIR environment variable and the ColorDir .INI directive you can set the colors used by the DIR command. With the SETDOS command you can change some aspects of Take Command's operation "on the fly." With command-line options you can specify where Take Command looks for its startup files and how it operates for a specific session. ═══ 7.1. Configuration Notebook ═══ The dialogs in the Take Command for OS/2 configuration notebook control the configuration of Take Command. Each option on one of the notebook pages a corresponding directive in TCMDOS2.INI. You can start the configuration notebook with the Configure Take Command selection on the Setup menu. When you exit from the dialogs, you can select the Save button to save your changes in the .INI file for use in the current session and all future sessions, select the OK button to use your changes in the current session only, or discard the changes you have made by selecting the Cancel button. Note that if you exit the dialogs with OK, changes will not be saved in the .INI file at that time. However, if you use the dialogs later, and exit with Save, any earlier changes will automatically be saved in the .INI file along with any new changes from your most recent use of the dialogs. Most changes you make in the configuration notebook will take effect immediately. Changes made on the Startup page, if saved, will take effect the next time you start Take Command, but will not affect the current Take Command session. While you are using the dialogs, you can move between sets of configuration options with the tabs on the right hand side of the notebook. The sets of options available in the notebook are: Startup Options Display Options Command Line 1 Options Command Line 2 Options General Options 1 General Options 2 Command Options ═══ 7.1.1. Startup Options Page ═══ You can use this page to set startup options in TCMDOS2.INI. If you return to Take Command by selecting the OK button, new settings will only stay in effect until you end the current Take Command session. If you return to Take Command by selecting Save, the changes will be recorded in TCMDOS2.INI and will be in effect each time you start Take Command. Changes made on the Startup page, if saved, will take effect the next time you start Take Command, but will not affect the current Take Command session. The TCSTART and TCEXIT Path field lets you set the path to TCSTART and TCEXIT if they aren't in the same directory as Take Command, and sets the TCStartPath directive. In the Buffer Sizes section: * Command History sets the size of the command history list, and the value of the History directive. * Directory History sets the size of the directory history list. The Cursor section sets the shape of the cursor and the IBeamCursor directive. Use the I-Beam shape for normal systems, and the Arrow shape for laptop or other systems where the I-Beam cursor is hard to see. The Display section sets the size and location of Take Command's window when it starts up: * Standard, Max, Min, and Custom set the WindowState directive. * The window position and size fields set the WindowX, WindowY, WindowHeight, and WindowWidth directives. Use these if you want Take Command to start up at a specific location on your desktop. These fields are ignored unless the item above is set to Custom. The Options section sets the Local History, Local Aliases, and Local Directory History flags. ═══ 7.1.2. Display Options Page ═══ You can use this page to set display-related options in TCMDOS2.INI. Most changes you make will take effect immediately. If you return to Take Command by selecting the OK button, new settings will only stay in effect until you end the current Take Command session. If you return to Take Command by selecting Save, the changes will be recorded in TCMDOS2.INI and will be in effect each time you start Take Command. The Text Dimensions section configures the way that text appears in Take Command's main window: * Width sets the number of columns that Take Command uses for its displays and sets the ScreenColumns directive. * Tabs selects the location of tab stops and sets the TabStops directive. The Window Configuration section controls the appearance of the Tool Bar (sets the ToolBarOn directive) and the Status Bar (sets the StatusBarOn directive), and enables or disables ANSI support (sets the ANSI directive). The tool bar and status bar settings are also modified when you enable and disable the corresponding option on the Setup menu. The Scrolling section controls Take Command's screen scrollback buffer: * Buffer Size sets the size of the screen buffer, and the value of the ScreenBufSize directive. Valid sizes are from 16,000 to 256,000 bytes. * Scroll Lines controls how much the screen scrolls when Take Command's text has reached the bottom of the window, and sets the ScrollLines directive. Lower values produce slower but smoother scrolling. The Colors section sets default screen colors: * Output establishes the default colors Take Command uses for the text it displays, and sets the StdColors directive. * Input establishes the colors for echoing the commands you type, and sets the InputColors directive. ═══ 7.1.3. Command Line 1 Options Page ═══ You can use this page to set command line options in TCMDOS2.INI. Most changes you make will take effect immediately. If you return to Take Command by selecting the OK button, new settings will only stay in effect until you end the current Take Command session. If you return to Take Command by selecting Save, the changes will be recorded in TCMDOS2.INI and will be in effect each time you start Take Command. The Editing section controls command-line editing: * Default Mode selects whether you begin editing in Overstrike or Insert mode, and sets the EditMode directive. * Cursor sets the width of the cursor for both Overstrike and Insert modes, and sets the CursorIns and CursorOver directives. The width is expressed as a percentage of the width of a character cell. In the Filename Completion section: * Add "\" to directories determines if a backslash should be added to directory names when doing filename completion, and sets the AppendToDir directive. * The Options field sets the files made available during filename completion for selected commands, and sets the FileCompletion directive. In the Command History section: * The Scroll / History keys setting controls whether Take Command or 4OS2 defaults are used for scrolling through the scrollback buffer and the command history. The Normal setting uses the arrow and PgUp / PgDn keys for the scrollback buffer, and the corresponding control keys (Ctrl-Up, Ctrl-Down, etc.) for the command history. The Swapped setting reverses these assignments. For more details see Scrolling and History Keystrokes. This option sets the value of the SwapScrollKeys directive. * Minimum saved characters sets the size of the shortest line that will be saved in the command history, and sets the value of the HistMin directive. * Copy to end, if checked, copies a recalled command to the end of the history list each time it is executed, and sets the HistCopy directive. * Move to end, if checked, moves a recalled command from it's position in the history list the end. * Wrap, if checked, the history will "wrap" when you reach the top or bottom of the list. ═══ 7.1.4. Command Line 2 Options Page ═══ You can use this page to set command line options in TCMDOS2.INI. Most changes you make will take effect immediately. If you return to Take Command by selecting the OK button, new settings will only stay in effect until you end the current Take Command session. If you return to Take Command by selecting Save, the changes will be recorded in TCMDOS2.INI and will be in effect each time you start Take Command. The Popup Windows section sets the position and size of the popup windows for the command-line, directory history, and filename completion windows, and most other popup windows by changing the PopupWinLeft, PopupWinTop, PopupWinWidth, and PopupWinHeight directives. You can also set the size of the Extended Directory Search popup window by changing the CDDWinLeft, CDDWinTop, CDDWinWidth, CDDWinHeight directives. The Extended Directory Search section controls Extended Directory Searches. * Search Level selects the Extended Directory Search mode and sets the FuzzyCD directive. * Tree Path contains the path for the Extended Directory Search database, JPSTREE.IDX and sets the TreePath directive. ═══ 7.1.5. Options 1 Page ═══ You can use this page to set options in TCMDOS2.INI. Most changes you make will take effect immediately. If you return to Take Command by selecting the OK button, new settings will only stay in effect until you end the current Take Command session. If you return to Take Command by selecting Save, the changes will be recorded in TCMDOS2.INI and will be in effect each time you start Take Command. The Descriptions section sets the way that Take Command handles file descriptions entered with the DESCRIBE command: * The Enable checkbox enables or disables the display and processing of descriptions, and sets the Descriptions directive. * The Maximum Length field determines the maximum size of file descriptions and sets the DescriptionMax directive. The value can range from 20 to 512 characters. This value sets the size of the internal description buffers; the actual description limit is 1 character less. For example, if you set the limit to 512, the longest description you can use is 511 characters. The Special Characters section sets the characters that have special meaning for Take Command. See Special Character Compatibility for information on how to change these to make Take Command more compatible with 4DOS, 4OS2, and 4NT. * Separator is the character that separates multiple commands. It can also be set with the CommandSep directive or SETDOS /C. * Escape sets the character used to suppress the normal meaning of the following character. It can also be set with the EscapeChar directive or SETDOS /E. * Parameter sets the character used after a percent sign to specify all or all remaining command-line arguments in a batch file or alias. It can also be set with the ParameterChar directive or with SETDOS /P. * Decimal sets the character used as a decimal separator for @EVAL and other operations. It can be set with the DecimalChar directive or with SETDOS /G. * Thousands sets the character used as a thousands separator for @EVAL and other operations. It can be set with the DecimalChar directive or with SETDOS /G. Default Beep sets defaults for the BEEP command and for "error" beeps. To disable error beeps, set the beep length to 0, and be sure to specify an explicit length each time you use the BEEP command. * Length sets the length of the beep in timer ticks that are approximately 1/18 of a second each. It also sets the BeepLength directive. * Frequency sets the frequency of the beep in Hz. It also sets the BeepFreq directive. The Options section sets miscellaneous options: * Force upper case, when selected, forces Take Command to display file names in upper case in internal commands like DIR and COPY. You can use the UpperCase directive or the SETDOS /U command achieve the same result. Force upper case has no effect on filenames from volumes which support long filenames. * Default batch echo, if selected, turns on echoing in batch files by default. You can use the BatchEcho directive or the SETDOS /V command to achieve the same result. * Protect redirected output files, if selected, keeps Take Command from overwritng an existing file with redirected (>) output or from creating a new file with output redirected in append (>>) mode. You can achieve the same result with the NoClobber directive or the SETDOS /N command. * The Time options determine how Take Command displays times. If you select Country, the time display is based on your country settings in OS/2. The am/pm setting forces a 12-hour display with a trailing "a" or "p." The 24-hour setting forces a standard 24-hour display. You can also set the time display with the AmPm directive. ═══ 7.1.6. Options 2 Page ═══ You can use this page to set options in TCMDOS2.INI. Most changes you make will take effect immediately. If you return to Take Command by selecting the OK button, new settings will only stay in effect until you end the current Take Command session. If you return to Take Command by selecting Save, the changes will be recorded in TCMDOS2.INI and will be in effect each time you start Take Command. The Logging section enables or disables Command and History logging (see the LOG command) and sets the file name to use for each. It also sets the LogName and HistLogName directives. The Eval Precision sets the minimum and maximum number of digits after the decimal point that @EVAL will display. You can achieve the same results with the EvalMin and EvalMax directives or with the SETDOS /F command. The External Programs setting controls whether Take Command waits for applications to complete before displaying the prompt. This setting applies only to applications started from the Take Command prompt, including DOS applications. Take Command will always wait for applications run from batch files. It also has no effect on "TTY" applications run within the Take Command window, or on applications started with the START command, which has its own separate /WAIT switch. This option sets the ExecWait directive. ═══ 7.1.7. Command Options Page ═══ You can use this page to set options related to specific commands in TCMDOS2.INI. Most changes you make will take effect immediately. If you return to Take Command by selecting the OK button, new settings will only stay in effect until you end the current Take Command session. If you return to Take Command by selecting Save, the changes will be recorded in TCMDOS2.INI and will be in effect each time you start Take Command. The DIR Colors field sets the colors used by DIR. You can achieve the same effect with the ColorDir directive or by setting the COLORDIR environment variable. See the Color Coded Directories section of the DIR command for details. The LIST section sets the foreground and background colors for the LIST command. It also sets the ListColors directive. The SELECT section sets the foreground and background colors for the SELECT command. It also sets the SelectColors directive. The Editor Filename sets the path and name of the program you want to use when you use when you select Editor from the Utilities menu. It also sets the Editor directive. ═══ 7.2. TCMDOS2.INI ═══ Part of the power of Take Command is its flexibility. You can alter its configuration to match your style of computing. Most of the configuration of Take Command is controlled through a file of initialization information called TCMDOS2.INI. This topic contains general information on TCMDOS2.INI. For information on specific directives see the separate topic for each type of directive: Initialization Directives Configuration Directives Color Directives Key Mapping Directives Advanced Directives These topics list the directives, with a one-line description of each, and a cross-reference which selects a full screen help topic on that directive. A few of the directives are simple enough that the one-line description is sufficient, but in most cases you should check for any additional information in the cross-reference topic if you are not already familiar with the directive. Modifying the TCMDOS2.INI File You can create, add to, and modify the TCMDOS2.INI file in 3 ways: with the configuration notebook, via the OPTION command, and by editing the file with any ASCII editor. The configuration notebook allow you to modify the settings that are used most often. When you exit from the notebook, you can select the Save button to save your changes in the .INI file for use in the current session and all future sessions, select the OK button to use your changes in the current session only, or discard the changes you have made by selecting the Cancel button. When you exit the configuration notebook, Save saves all changes since the last Save, or since the last time you started the command processor. If you open the notebook and exit with OK, changes will not be saved in the .INI file at that time. However, if you use the notebook later, and exit with Save, any earlier changes will automatically be saved in the .INI file along with any new changes from your most recent use of the notebook. Changes you make in the Startup section of the configuration notebook will only take effect when you restart Take Command. The notebook handles most standard .INI file settings. The Advanced directives, the Key Mapping directives, and a few other individual directives noted below do not have corresponding fields in the configuration notebook, and must be entered manually. Take Command reads its .INI file when it starts, and configures itself accordingly. The .INI file is not re-read when you change it manually. For manual changes to take effect, you must restart Take Command. If you edit the .INI file manually, make sure you save the file in ASCII format. Each item that you can include in the .INI file has a default value. You only need to include entries in the file for settings that you want to change from their default values. The .INI file has several sections. All of the directives described here go into the [TakeCommand] section, which is usually first in the file. You can edit this section manually. Take Command uses the other sections to record information you set while you are using it, including its window size and position, the font you are using, and the buttons you create on the tool bar. You should use Take Command's menu commands to change the settings in these other sections of the .INI file instead of editing them directly. Using the .INI File Some settings in the .INI file are initialized when you install Take Command and others (such as window size and position) are modified as you use Take Command, so you will probably have an TCMDOS2.INI file even if you didn't create one yourself. You should not delete this file. Take Command searches for TCMDOS2.INI in two places: * If there is an "@d:\path\inifile" option on the Take Command startup command line Take Command will use the path and file name specified there, and will not look elsewhere. * If there is no .INI file name on the startup command line, the search proceeds to the same directory where the Take Command program file (TCMDOS2.EXE ) is stored. This is the "normal" location for the .INI file. Take Command determines this directory automatically. .INI File Directives Most lines in the .INI file consist of a one-word directive, an equal sign [=], and a value. For example, in the following line, the word "History" is the directive and "2048" is the value: History = 2048 Any spaces before or after the equal sign are ignored. If you have a long string to enter in the .INI file (for example, for the ColorDir directive), you must enter it all on one line. Strings cannot be "continued" to a second line. Each line may be up to 1,023 characters long. The format of the value part of a directive line depends on the individual directive. It may be a numeric value, a single character, a choice (like "Yes" or "No"), a color setting, a key name, a path, a filename, or a text string. The value begins with the first non-blank character after the equal sign and ends at the end of the line or the beginning of a comment. Blank lines are ignored in the .INI file and can be used to separate groups of directives. You can place comments in the file by beginning a line with a semicolon [;]. You can also place comments at the end of any line except one containing a text string value. To do so, enter at least one space or tab after the value, a semicolon, and your comment, like this: History = 2048 ;set history list size If you try to place a comment at the end of a string value, the comment will become part of the string and will probably cause an error. If you use the OPTION dialogs to modify the .INI file, comments on lines modified from within the dialogs will not be preserved when the new lines are saved. To be sure .INI file comments are preserved, put them on separate lines in the file When Take Command detects an error while processing the .INI file, it displays an error message and prompts you to press a key to continue processing the file. This allows you to note any errors before the startup process continues. The directive in error will retain its previous or default value. If you need to test different values for an .INI directive without repeatedly editing the .INI file, use the OPTION command or see INIQuery directive. If you want to include the text of one .INI file within another (for example, if you have a set of common directives used by several JP Software products), see the Include directive. The SETDOS command can override several of the .INI file directives. For example, the cursor shape used by Take Command can be adjusted either with the CursorIns and CursorOver directives or the SETDOS /S command. The correspondence between SETDOS options and .INI directives is noted under each directive below, and under each option of the SETDOS command. Types of Directives There are 8 types of directives in the .INI file. The different types of directives are shown in the lists below as follows: Name = nnnn ( 1234): This directive takes a numeric value which replaces the "nnnn." The default value is shown in parentheses. Name = c (X): This directive accepts a single character as its value. The default character is shown in parentheses. You must type in the actual character; you cannot use a key name. Name = CHOICE1 | Choice2 | ... : This directive takes a choice value. The possible choices are listed, separated by vertical bars. The default value is shown in all upper case letters in the directive description, but in your file any of the choices can be entered in upper case or lower case. For example, if the choices were shown as "YES | No" then "YES" is the default. Name = Color: This directive takes a color specification. See Colors and Color Names for the format of color names. Name = Key (Default): This directive takes a key specification. See Keys and Keynames for the format of key names. Name = Path: This directive takes a path specification, but not a filename. The value should include both a drive and path (e.g., C:\TCMD) to avoid any possible ambiguities. A trailing backslash [\] at the end of the path name is acceptable but not required. Any default path is described in the text. Name = File: This directive takes a filename. We recommend that you use a full filename including the drive letter and path to avoid any possible ambiguities. Any default filename is described in the text. Name = String: This directive takes a string in the format shown. The text describes the default value and any additional requirements for formatting the string correctly. No comments are allowed. Take Command contains a fixed-length area for storing strings entered in the .INI file, including file names, paths, and other strings. This area is large and is unlikely to overflow; if it does, you will receive an error message. If this occurs, reduce the complexity of your .INI file or contact our technical support department for assistance. ═══ 7.2.1. Initialization Directives ═══ The directives in this section control how Take Command starts and where it looks for its files. The initialization directives are: DirHistory Size of directory history list DuplicateBugs Emulate CMD.EXE bugs HelpBook Books to load in help system History Size of history list IBeamCursor Select I- beam or arrow cursor INIQuery Query for each line in TCMDOS2.INI LocalAliases ehp1. Local vs. global aliases LocalHistory Local vs. global history LocalDirHistory Local vs. global directory history ScreenBufSize Size of screen buffer TCStartPath Path for TCSTART and TCEXIT TreePath Path for directory database, JPSTREE.IDX WindowState Initial state for the Take Command window WindowX, WindowY, WindowWidth, WindowHeightInitial size and position of the Take Command window ═══ 7.2.1.1.  DirHistory (directive) ═══ DirHistory = nnnn (256): Sets the amount of memory allocated to the directory history list in bytes. The allowable range of values is 256 to 32767. If you use a global directory history list (see Directory History Window), the DirHistory value is ignored in all sessions except that which first establishes the global list. ═══ 7.2.1.2. DuplicateBugs ═══ DuplicateBugs = Yes | NO: Tells the Take Command parser to duplicate certain well-known bugs in CMD.EXE. The only bug currently replicated is in the IF command. ═══ 7.2.1.3. HelpBook ═══ HelpBook = String: Sets the names of the "books" to be loaded with the HELP command or theF1 key. The default is TCMDOS2 which loads only the Take Command for OS/2 help. This directive allows you to load other help "books" at the same time: see the Take Command for OS/2 Introduction and Installation Guide for additional details. ═══ 7.2.1.4.  History (directive) ═══ History = nnnn (1024): Sets the amount of memory allocated to the command history list in bytes. The allowable range of values is 256 to 32767 bytes. If you use a global history list (see Command History and Recall), the History value is ignored in all sessions except the session which first establishes the global list. ═══ 7.2.1.5. IBeamCursor ═══ IBeamCursor = YES | No: If set to Yes, Take Command will display the standard "I-Beam" cursor in text areas of its window. If IBeamCursor is set to No, an arrow is used in all areas of the window (this can be helpful on laptop systems where the I-Beam cursor is hard to see). ═══ 7.2.1.6. INIQuery ═══ INIQuery = Yes | NO: If set to Yes, a dialog box will be displayed before execution of each subsequent line in the current .INI file. This allows you to modify certain directives when you start Take Command in order to test different configurations. INIQuery can be reset to No at any point in the file. Normally INIQuery = Yes is only used during testing of other .INI file directives. The dialog generated by INIQuery = Yes is: Yes Executes the directive No Skips the directive Cancel Executes the directive and all remaining directives the the [TakeCommand] section of the .INI file (i.e., cancels the INIQuery=Yes setting) ═══ 7.2.1.7. LocalAliases ═══ LocalAliases = Yes | NO: No forces all copies of Take Command to share the same alias list. Yes keeps the lists for each shell separate. See ALIAS for more details on local and global alias lists. ═══ 7.2.1.8. LocalDirHistory ═══ LocalDirHistory = Yes | NO: No forces all copies of Take Command to share the same directory history list. Yes keeps the list for each session separate. See directory history window for more details on local and global directory history. ═══ 7.2.1.9. LocalHistory ═══ LocalHistory = Yes | NO: No forces all copies of Take Command to share the same history list. Yes keeps the lists for each shell separate. See Command History and Recall for more details on local and global history lists. ═══ 7.2.1.10. ScreenBufSize ═══ ScreenBufSize = nnnn (64000): Sets the size of the screen scrollback buffer in bytes. The allowable range is from 16000 to 512000 bytes. ═══ 7.2.1.11. TCStartPath ═══ TCStartPath = Path: Sets the drive and directory where the TCSTART and TCEXIT batch files (if any) are located. ═══ 7.2.1.12. TreePath ═══ TreePath = Path: Sets the location of JPSTREE.IDX, the file used for the extended directory search database. By default, the file is placed in the root directory of drive C:\. ═══ 7.2.1.13. WindowState ═══ WindowState = STANDARD | Maximize | Minimize | Custom: Sets the initial state of the Take Command window. Standard puts the window in the default position on the OS/2 desktop, and is the default setting. Maximize maximizes the window; Minimize minimizes it, and Custom sets it to the position specified by the WindowX, WindowY, WindowWidth, WindowHeight directives. ═══ 7.2.1.14. WindowX, WindowY, WindowWidth, WindowHeight ═══ WindowX = nnnn, WindowY = nnnn, WindowWidth = nnnn, WindowHeight = nnnn: These 4 directives set the initial size and position of the Take Command window. The measurements are in pixels or pels. WindowX and WindowY refer to the position of the bottom left corner of the window relative to the bottom left corner of the screen. These directives will be ignored unless WindowState is set to Custom. ═══ 7.2.2. Configuration Directives ═══ These directives control the way that Take Command operate. Some can be changed with the SETDOS command while Take Command is running. Any corresponding SETDOS command is listed in the description of each directive. The configuration directives are: AmPm Time display format ANSI Enables ANSI support AppendToDir "\" on directory names in filename completion BatchEcho Default batch file echo state BeepFreq Default beep frequency BeepLength Default beep length CDDWinLeft, CDDWinTop, CDDWinWidth, CDDWinHeightInitial size and position of the extended directory search window CommandSep Multiple command separator character CursorIns Cursor width in insert mode CursorOver Cursor width in overstrike mode DecimalChar Decimal separator for @EVAL, etc. DescriptionMax Maximum length of file descriptions DescriptionName Name of file to hold file descriptions Descriptions Enable / disable description processing EditMode Editing mode (insert / overstrike) Editor Program to run for "Editor" menu choice EscapeChar Take Command escape character EvalMax Maximum precision returned by @EVAL EvalMin Minimum precision returned by @EVAL ExecWait Forces Take Command to wait for external programs to complete FileCompletion Files selected for filename completion FuzzyCD Selects Extended Directory Search mode HistCopy History copy mode HistLogName History log file name HistMin Minimum command length to save HistMove Move recalled commands to end of history HistWrap Behavior of the command history list ListRowStart Starting row number for LIST and FFIND LogName Log file name NoClobber Overwrite protection for output redirection ParameterChar Alias / batch file parameter character PathExt Enable or disable the PATHEXT variable PopupWinLeft, PopupWinTop, PopupWinWidth, PopupWinHeightInitial size and position of the popup windows ScreenColumns Virtual screen width ScreenColumns Virtual screen height ScrollLines Number of lines to scroll up when at the bottom of the window StatusBarOn Set status bar mode at startup SwapFilePath Path to OS/2 swap file SwapScrollKeys Use the 4OS2-style keys for history recall TabStops Sets the tab positions for Take Command's output ThousandsChar Thousands separator for @EVAL, etc. ToolBarOn Set toolbar mode at startup UnixPaths Enable or disable slash in command paths UpperCase Force file names to upper case ═══ 7.2.2.1. AmPm ═══ AmPm = Yes | NO | Auto: Yes displays times in 12-hour format with a trailing "a" for AM or "p" for PM. The default of No forces a display in 24-hour time format. Auto formats the time according to the country code set for your system. AmPm controls the time displays used by DIR and SELECT, in LOG files, and the output of the TIMER, DATE, and TIME commands. It has no effect on %_TIME, %@MAKETIME, the $t and $T options of PROMPT, or date and time ranges. ═══ 7.2.2.2. ANSI ═══ ANSI = YES | No: Sets the initial state of ANSI support. Yes enables ANSI string processing in the Take Command window (for example, ANSI strings can be displayed in the prompt, or with the ECHO command) No disables ANSI strings. Also see SETDOS /A. You can test whether ANSI support is enabled with the _ANSI internal variable. See the ANSI Reference for more details on ANSI strings, and a reference list of ANSI sequences supported by Take Command for OS/2. ═══ 7.2.2.3. AppendToDir ═══ AppendToDir = Yes | NO: Yes appends a trailing "\" to directory names when doing filename completion. Regardless of the setting of this directive, a trailing backslash is always appended to a directory name at the beginning of the command line to enable automatic directory changes. ═══ 7.2.2.4. BatchEcho ═══ BatchEcho = YES | No: Sets the default batch echo mode. Yes enables echoing of all batch file commands unless ECHO is explicitly set off in the batch file. No disables batch file echoing unless ECHO is explicitly set on. Also see SETDOS /V. ═══ 7.2.2.5. BeepFreq ═══ BeepFreq = nnnn (440): Sets the default BEEP command frequency in Hz. This is also the frequency for "error" beeps (for example, if you press an illegal key). To disable all error beeps set this or BeepLength to 0. If you do, the BEEP command will still be operable, but will not produce sound unless you explicitly specify the frequency and duration. ═══ 7.2.2.6. BeepLength ═══ BeepLength = nnnn (2): Sets the default BEEP length in system clock ticks (approximately 1/18 of a second per tick). BeepLength is also the default length for "error" beeps (for example, if you press an illegal key). ═══ 7.2.2.7. CDDWinLeft, CDDWinTop, CDDWinWidth, CDDWinHeight ═══ CDDWinLeft, CDDWinTop, CDDWinWidth, CDDWinHeight = nnnn: These values set the position and size of the popup window used by extended directory searches, in characters, including the border. The defaults are 3, 3, 72, and 16, respectively (i.e., a window beginning in column 3, row 3, 72 columns wide and 16 rows high). The position is relative to the top left corner of the screen. The width and height values include the space required for the window border. The window cannot be smaller than than 10 columns wide by 5 rows high (including the border). The values you enter will be adjusted if necessary to keep a minimum-size window visible on the screen. ═══ 7.2.2.8. CommandSep ═══ CommandSep = c: This is the character used to separate multiple commands on the same line. The default for Take Command is the ampersand [&]. You cannot use any of the redirection characters (| > < ) or any of the whitespace characters (space, tab, comma, or equal sign). The command separator is saved by SETLOCAL and restored by ENDLOCAL. Also see SETDOS /C, the %+ internal variable, and Special Character Compatibility for information on using compatible command separators for two or more products. ═══ 7.2.2.9. CursorIns ═══ CursorIns = nnnn (15): This is the width of the cursor for insert mode during command-line editing and all commands which accept line input (DESCRIBE, ESET, etc.). The size is a percentage of the total character cell size, between 0% and 100%. Because of the way video drivers map the cursor shape, you may not get a smooth progression in cursor shapes as CursorIns and CursorOver change. If you set CursorIns and CursorOver to -1, the cursor shape won't be modified at all. If you set them to 0, the cursor will be invisible. Also see SETDOS /S. ═══ 7.2.2.10. CursorOver ═══ CursorOver = nnnn (100): This is the width of the cursor for overstrike mode during command-line editing and all commands which accept line input. The size is a percentage of the total character cell size, between 0% and 100%. For more details see the CursorIns directive; also see SETDOS /S. ═══ 7.2.2.11. DecimalChar ═══ DecimalChar = . | , | AUTO: Sets the character used as the decimal separator for @EVAL, numeric IF and IFF tests, version numbers, and other similar uses. The only valid settings are period [.], comma [,], and Auto (the default). A setting of Auto tells the command processor to use the decimal separator associated with your current country code. If you change the decimal character you must also adjust the thousands character (with ThousandsChar, see below) so that the two characters are different. Also see SETDOS /G. ═══ 7.2.2.12. DescriptionMax ═══ DescriptionMax = nnnn (511): Controls the description length limit for DESCRIBE. The allowable range is 20 to 511 characters. ═══ 7.2.2.13. DescriptionName ═══ DescriptionName = [File | EA]: Sets the file name in which to store file descriptions. The default file name is DESCRIPT.ION. Use this directive with caution because changing the name from the default will make it difficult to transfer file descriptions to another system. Also see SETDOS /D. If you set DescriptionName = EA, Take Command will use the ".SUBJECT" extended attribute (EA) for file descriptions instead of a separate file. Note that using EAs will slow the DIR and SELECT commands noticeably. On a FAT volume, performance may be substantially slower, depending on whether the system has cached the extended attributes. ═══ 7.2.2.14. Descriptions ═══ Descriptions = YES | No: Turns description handling on or off during the file processing commands COPY, DEL, MOVE, and REN. If set to No, Take Command will not update the description file when files are moved, copied, deleted or renamed. Also see SETDOS /D. ═══ 7.2.2.15. EditMode ═══ EditMode = INSERT | Overstrike: This directive lets you start the command-line editor in either insert or overstrike mode. Also see SETDOS /M. ═══ 7.2.2.16. Editor ═══ Editor = File: Specifies the path and filename of the program that Take Command will execute when you select "Editor" from the Utilities menu. The default is the standard OS/2 editor E.EXE. ═══ 7.2.2.17. EscapeChar ═══ EscapeChar = c: Sets the character used to suppress the normal meaning of the following character. The default for Take Command is a a caret [^]. See Escape Character for a description of special escape sequences. You cannot use any of the redirection characters (|, >, or < ) or the whitespace characters (space, tab, comma, or equal sign) as the escape character. The escape character is saved by SETLOCAL and restored by ENDLOCAL. Also see SETDOS /E, the %= internal variable, and Special Character Compatibility for information on using compatible escape characters for two or more products. ═══ 7.2.2.18. EvalMax ═══ EvalMax = nnnn (8): Controls the maximum number of digits after the decimal point in values returned by @EVAL. You can override this setting with the construct @EVAL[expression=n,n]. The allowable range is 0 to 8. Also see SETDOS /F. ═══ 7.2.2.19. EvalMin ═══ EvalMin = nnnn (0): Controls the minimum number of digits after the decimal point in values returned by @EVALF_EVAL. The allowable range is 0 to 8. This directive will be ignored if EvalMin is larger than EvalMax. You can override this setting with the construct @EVAL[expression=n,n]. Also see SETDOS /F. ═══ 7.2.2.20. ExecWait ═══ ExecWait = Yes | NO: Controls whether Take Command waits for an external program to complete before redisplaying the prompt. See Waiting for Applications to Finish in Starting Character Mode Applications for details on the effects of this directive. This setting applies only to applications started from the Take Command prompt. Take Command will always wait for applications run from batch files. ExecWait also has no effect on "TTY" applications run within the Take Command window, or on applications started with the START command, which has its own separate /WAIT switch. ═══ 7.2.2.21. FileCompletion ═══ FileCompletion = cmd1: ext1 ext2 ...; cmd2: ext3 ext4 ... Sets the files made available during filename completion for selected commands. The format is the same as that used for the FILECOMPLETION environment variable. See Customizing Filename Completion for a detailed explanation of selective filename completion. ═══ 7.2.2.22. FuzzyCD (Extended Directory Search) ═══ FuzzyCD = 0 | 1 | 2 | 3. Enables or disables extended directory searches, and controls their behavior. A setting of 0 (the default) disables extended searches. For complete details on the meaning of the other settings see Extended Directory Searches. ═══ 7.2.2.23. HistCopy ═══ HistCopy = Yes | NO: Controls what happens when you re-execute a line from the command history. If this option is set to Yes, the line is appended to the end of the history list. By default, or if this option is set to No, the command is not copied. The original copy of the command is always retained at its original position in the list, regardless of the setting of HistCopy. Set this option to No if you want to use HistMove = Yes; otherwise, the HistCopy setting will override HistMove. ═══ 7.2.2.24. HistLogName ═══ HistLogName = File: Sets the history log file name and/or path. If only a path is given, the default log file name (OS2HLOG) will be used. Using HistLogName does not turn history logging on; you must use a LOG /H ON command to do so. ═══ 7.2.2.25. HistMin ═══ HistMin = nnnn (0): Sets the minimum command-line size to save in the command history list. Any command line whose length is less than this value will not be saved. Legal values range from 0, which saves everything, to 1024, which disables all command history saves. ═══ 7.2.2.26. HistMove ═══ HistMove = Yes | NO: If set to Yes, a recalled line is moved to the end of the command history. The difference between this directive and HistCopy, above, is that HistCopy = Yes copies each recalled line to the end of the history but leaves the original in place. HistMove = Yes places the line at the end of history and removes the original line. This directive has no effect if HistCopy = Yes. ═══ 7.2.2.27. HistWrap ═══ HistWrap = YES | No: Controls whether the command history "wraps" when you reach the top or bottom of the list. The default setting enables wrapping, so the list appears "circular". If HistWrap is set to No, history recall will stop at the beginning and end of the list rather than wrapping. ═══ 7.2.2.28. ListRowStart ═══ ListRowStart = 1 | 0: Specifies whether LIST and FFIND consider the first line in the file to be line "1" or line "0". The default is "1". ═══ 7.2.2.29. LogName ═══ LogName = File: Sets the log file name and/or path. If only a path is given, the default log file name (OS2LOG) will be used. Using LogName does not turn logging on; you must use a LOG ON command to do so. ═══ 7.2.2.30. NoClobber ═══ NoClobber = Yes | NO: If set to Yes, will prevent standard output redirection from overwriting an existing file, and will require that the output file already exist for append redirection. Also see SETDOS /N. ═══ 7.2.2.31. ParameterChar ═══ ParameterChar = c: Sets the character used after a percent sign to specify all or all remaining command-line arguments in a batch file or alias (e.g., %$ or %n$; see Batch Files and ALIAS). The default in Take Command is the dollar sign [$]. The parameter character is saved by SETLOCAL and restored by ENDLOCAL. Also see SETDOS /P. See Special Character Compatibility for information on using compatible parameter characters for two or more products. ═══ 7.2.2.32. PathExt ═══ PathExt = Yes | NO: Determines whether Take Command will use the PATHEXT environment variable. If set to No (the default), the PATHEXT variable is ignored. If set to Yes, the PATHEXT variable will be used to determine extensions to look for when searching the PATH for an executable file. For details, see the PATHEXT variable and the PATH command. CAUTION: If you set PathExt = Yes in TCMDOS2.INI and then fail to set the PATHEXT variable, path searches will fail as there will be no extensions for which to search! PATHEXT is supported for compatibility reasons but should not generally be used as a substitute for the more flexible executable extensions feature. ═══ 7.2.2.33. PopupWinLeft, PopupWinTop, PopupWinWidth, PopupWinHeight ═══ PopupWinLeft, PopupWinTop, PopupWinWidth, PopupWinHeight = nnnn: These values set the initial position and size of the command-line, directory history, and filename completion windows, and most other popup windows (see CDDWinLeft etc. for the extended directory search window). The values are in characters, and include the border. The defaults are 40, 1, 36, and 12, respectively (i.e., a window beginning in column 40, row 1, 36 columns wide and 12 rows high). The position is relative to the top left corner of the Take Command window. The width and height values include the space required for the window border. The window cannot be smaller than than 10 columns wide by 5 rows high (including the border). The values you enter will be adjusted if necessary to keep a minimum-size window visible on the screen. ═══ 7.2.2.34. ScreenColumns ═══ ScreenColumns = nnnn (80): Sets the number of virtual screen columns used by the video display. If the virtual screen width is greater than the physical window width, Take Command will display a horizontal scrollbar at the bottom of the window. See Resizing the Take Command Window for more information on the virtual screen size. ═══ 7.2.2.35. ScreenRows ═══ ScreenRows = nnnn (25): Sets the initial height of the Take Command window. See Resizing the Take Command Window for more information on the virtual screen size. ═══ 7.2.2.36. ScrollLines ═══ ScrollLines = nnnn (2): Sets the number of lines displayed before the screen is physically scrolled. Take Command will scroll up when output reaches the bottom of the window. Higher values will speed up the display of scrolled output but also make it jerky; lower values will make scrolling smoother but will slow it down. ═══ 7.2.2.37. StatusBarOn ═══ StatusBarOn = YES | No: Yes enables the status bar when Take Command starts. No disables it. The status bar can always be enabled or disabled while Take Command is running by using the Setup menu. The StatusBarOn setting is automatically updated to reflect the current state of the status bar each time Take Command exits; this preserves the status bar state between sessions. ═══ 7.2.2.38. SwapFilePath ═══ SwapFilePath = Path: Specifies the path of the OS/2 swap file so the MEMORY command and the status bar can find it and display its size. ═══ 7.2.2.39. SwapScrollKeys ═══ SwapScrollKeys = Yes | NO: Yes switches to 4OS2- style keystrokes for manipulating the scrollback buffer. If SwapScrollKeys is set to Yes, the Up and Down arrow keys will scroll through the command history list and the PgUp key will pop up the history window. The Ctrl-Up, Ctrl-Down, Ctrl-PgUp, and Ctrl-PgDn keys will scroll the text in the screen buffer. If SwapScrollKeys is set to No, these keys will assume their default meanings. The Up and Down arrow keys and the PgUp and PgDn keys will scroll the text in the screen buffer. The Ctrl-Up and Ctrl-Down keys will scroll through the command history list and the Ctrl-PgUp key will pop up the history window. For additional details see Scrolling and History Keystrokes. Do not set SwapScrollKeys to Yes if you use key mapping directives to reassign the scrolling or history keys individually. SwapScrollKeys takes effect before other key mappings, and using both methods at the same time will be confusing at best. Setting SwapScrollKeys to Yes has essentially the same effect as including the following key mapping directives in TCMDOS2.INI individually: PrevHistory = Up NextHistory = Down HistWinOpen = PgUp HistWinOpen = PgDn ScrollUp = Ctrl-Up ScrollDown = Ctrl-Down ScrollPgUp = Ctrl-PgUp ScrollPgDn = Ctrl-PgDn ═══ 7.2.2.40. TabStops ═══ TabStops = nnnn (8): Sets the tab stops for Take Command's output (including the output from the LIST and TYPE commands). The allowable range is 1 to 32. ═══ 7.2.2.41. ThousandsChar ═══ ThousandsChar = . | , | AUTO: Sets the character used as the thousands separator for numeric output. The only valid settings are period [.], comma [,], and Auto (the default). A setting of Auto tells the command processor to use the thousands separator associated with your current country code. If you change the thousands character you must also adjust the decimal character (with DecimalChar) so that the two characters are different. Also see SETDOS /G. ═══ 7.2.2.42. ToolBarOn ═══ ToolBarOn = YES | No: Yes enables the tool bar when Take Command starts. No disables it. The tool bar can be enabled or disabled while Take Command is running by using the Setup menu. The ToolBarOn setting is automatically updated to reflect the current state of the tool bar each time Take Command exits; this preserves the tool bar state between sessions. ═══ 7.2.2.43. UnixPaths ═══ UnixPaths = Yes | NO: Enables the forward slash as a path separator in the command name (the first item on the command line). This allows you to enter a command like: [c:\] /bin/programs/foo.exe without having the forward slashes interpreted as switch characters. Note that setting UnixPaths to Yes does not change the command processor or operating system switch character, it's still '/'. It simply allows you to put forward slashes in the command name without problems. When UnixPaths is set to Yes command switches beginning with a forward slash must be preceded by a space to avoid confusion (this is a good general practice regardless of the setting of UnixPaths). For example: [c:\] \bin\foo.exe /c OK [c:\] /bin/foo.exe /c OK [c:\] \bin\foo.exe/c Error [c:\] /bin/foo.exe/c Error ═══ 7.2.2.44. UpperCase ═══ UpperCase = Yes | NO: Yes specifies that filenames should be displayed in the traditional upper-case by internal commands like COPY and DIR. No allows the normal Take Command lower-case style. This directive does not affect the display of filenames on drives which support long filenames. Also see SETDOS /U. ═══ 7.2.3. Color Directives ═══ These directives control the colors that Take Command use for its displays. For complete details on color names and numbers, see Colors and Color Names. The color directives are: ColorDir Directory colors InputColors Input colors ListColors Colors used in the LIST display SelectColors Colors used in the SELECT display StdColors Standard display colors ═══ 7.2.3.1. ColorDIR (directive) ═══ ColorDir = ext1 ext2 ...:colora;ext3 ext4... :colorb; ...: Sets the directory colors used by DIR. The format is the same as that used for the COLORDIR environment variable. See the Color-Coded Directories section of the DIR command for a detailed explanation. ═══ 7.2.3.2. InputColors ═══ InputColors = Color: Sets the colors used for command-line input. This setting is useful for making your input stand out from the normal output. ═══ 7.2.3.3. ListColors ═══ ListColors = Color: Sets the colors used by the LIST command. If this directive is not used, LIST will use the current default colors set by the CLS or COLOR command or by the StdColors directive. ═══ 7.2.3.4. SelectColors ═══ SelectColors = Color: Sets the colors used by the SELECT command. If this directive is not used, SELECT will use the current default colors set by the CLS or COLOR command or by the StdColors directive. ═══ 7.2.3.5. StdColors ═══ StdColors = Color: Sets the standard colors to be used when CLS is used without a color specification, and for LIST and SELECT if ListColors and SelectColors are not used. Using this directive is similar to placing a COLOR command in the TCSTART file. ═══ 7.2.4. Key Mapping Directives ═══ These directives allow you to change the keys used for command-line editing and other internal functions. They cannot be entered via the configuration notebook; you must enter them manually (see TCMDOS2.INIfor details). They are divided into five types, depending on the context in which the keys are used. For a discussion and list of directives for each type see: General Input Keys Command-Line Editing Keys Popup Window Keys LIST Keys Scrollback Buffer Keys Using a key mapping directive allows you to assign a different or additional key to perform the function described. For example, to use function key F3 to invoke the HELP facility (normally invoked with F1): Help = F3 Any directive can be used multiple times to assign multiple keys to the same function. For example: ListFind = F ;F does a find in LIST ListFind = F4 ;F4 also does a find in LIST Use some care when you reassign keystrokes. If you assign a default key to a different function, it will no longer be available for its original use. For example, if you assign F1 to the AddFile directive (a part of filename completion), the F1 key will no longer invoke the help system, so you will probably want to assign a different key to Help. See Keys and Key Names before using the key mapping directives. Key assignments are processed before looking for keystroke aliases. For example, if you assign Shift-F1 to HELP and also assign Shift- F1 to a key alias, the key alias will be ignored. Assigning a new keystroke for a function does not deassign the default keystroke for the same function. If you want to deassign one of the default keys, use the NormalKey, NormalEditKey, NormalPopupKey, or NormalListKey directive. ═══ 7.2.4.1. General Input Keys ═══ These directives apply to all input. They are in effect whenever Take Command requests input from the keyboard, including during command-line editing and the DESCRIBE, ESET, INPUT, LIST, and SELECT commands. The general input keys are: Backspace Deletes the character to the left of the cursor BeginLine Moves the cursor to the start of the line Del Deletes the character at the cursor DelToBeginning Deletes from the cursor to the start of the line DelToEnd Deletes from the cursor to the end of the line DelWordLeft Deletes the word to the left of the cursor DelWordRight Deletes the word to the right of the cursor Down Moves the cursor or scrolls the display down EndLine Moves the cursor to the end of the line EraseLine Deletes the entire line ExecLine Executes or accepts a line Ins Toggles insert / overstrike mode Left Moves the cursor or scrolls the display left NormalKey Deassigns a key Right Moves the cursor or scrolls the display right Up Moves the cursor or scrolls the display up WordLeft Moves the cursor left one word WordRight Moves the cursor right one word ═══ 7.2.4.1.1. Backspace ═══ Backspace = Key (Bksp): Deletes the character to the left of the cursor. ═══ 7.2.4.1.2. BeginLine ═══ BeginLine = Key (Home): Moves the cursor to the beginning of the line. ═══ 7.2.4.1.3. Del (directive) ═══ Del = Key (Del): Deletes the character at the cursor. ═══ 7.2.4.1.4. DelToBeginning ═══ DelToBeginning = Key (Ctrl-Home): Deletes from the cursor to the start of the line. ═══ 7.2.4.1.5. DelToEnd ═══ DelToEnd = Key (Ctrl-End): Deletes from the cursor to the end of the line. ═══ 7.2.4.1.6. DelWordLeft ═══ DelWordLeft = Key (Ctrl-L): Deletes the word to the left of the cursor. ═══ 7.2.4.1.7. DelWordRight ═══ DelWordRight = Key (Ctrl-R, Ctrl-Bksp): Deletes the word to the right of the cursor. See ClearKeyMap if you need to remove the default mapping of Ctrl-Bksp to this function. ═══ 7.2.4.1.8. Down ═══ Down = Key (Down): Scrolls the display down one line in LIST; moves the cursor down one line in SELECT and in the command-line history, directory history, or %@SELECT window. ═══ 7.2.4.1.9. EndLine ═══ EndLine = Key (End): Moves the cursor to the end of the line. ═══ 7.2.4.1.10. EraseLine ═══ EraseLine = Key (Esc): Deletes the entire line. ═══ 7.2.4.1.11. ExecLine ═══ ExecLine = Key (Enter): Executes or accepts a line. ═══ 7.2.4.1.12. Ins ═══ Ins = Key (Ins): Toggles insert / overstrike mode during line editing. ═══ 7.2.4.1.13. Left ═══ Left = Key (Left): Moves the cursor left one character on the input line; scrolls the display left 8 columns in LIST; scrolls the display left 4 columns in the command- line, directory history, or %@SELECT window. ═══ 7.2.4.1.14. NormalKey ═══ NormalKey = Key: Deassigns a general input key in order to disable the usual meaning of the key within Take Command and/or make it available for keystroke aliases. This will make the keystroke operate as a "normal" key with no special function. For example: NormalKey = Ctrl-End will disable Ctrl-End, which is the standard "delete to end of line" key. Ctrl-End could then be assigned to a keystroke alias. Another key could be assigned the "delete to end of line" function with the DelToEnd directive. ═══ 7.2.4.1.15. Right ═══ Right = Key (Right): Moves the cursor right one character on the input line; scrolls the display right 8 columns in LIST; scrolls the display right 4 columns in the command- line history, directory history, or %@SELECT window. ═══ 7.2.4.1.16. Up ═══ Up = Key (Up): Scrolls the display up one line in LIST; moves the cursor up one line in SELECT and in the command-line history, directory history, or %@SELECT window. ═══ 7.2.4.1.17. WordLeft ═══ WordLeft = Key (Ctrl-Left): Moves the cursor left one word; scrolls the display left 40 columns in LIST. ═══ 7.2.4.1.18. WordRight ═══ WordRight = Key (Ctrl-Right): Moves the cursor right one word; scrolls the display right 40 columns in LIST. ═══ 7.2.4.2. Command-Line Editing Keys ═══ These directives apply only to command-line editing. They are only effective at the Take Command prompt. The command-line editing keys are: AddFile Keeps filename completion entry and adds another AliasExpand Expands aliases on the command line CommandEscape Allows direct entry of a keystroke DelHistory Deletes a history list entry EndHistory Displays the last entry in the history list Help Invokes this help system LineToEnd Copies command to end of history list NextFile Gets the next matching filename NextHistory Recalls the next command from the history NormalEditKey Deassigns a command-line editing key PopFile Opens the filename completion window PrevFile Gets the previous matching filename PrevHistory Recalls the previous command from the history SaveHistory Saves the command line without executing it ═══ 7.2.4.2.1. AddFile ═══ AddFile = Key (Ctrl-Shift-Tab): Keeps the current filename completion entry and inserts the next matching name. ═══ 7.2.4.2.2. AliasExpand ═══ AddFile = Key (Ctrl-F): Expands all aliases in the current command line without executing them. ═══ 7.2.4.2.3. CommandEscape ═══ CommandEscape = Key (Alt-255): Allows direct entry of a keystroke that would normally be handled by the command line editor (e.g., Tab or Ctrl-D). ═══ 7.2.4.2.4. DelHistory ═══ DelHistory = Key (Ctrl-D): Deletes the displayed history list entry and displays the previous entry. ═══ 7.2.4.2.5. EndHistory ═══ EndHistory = Key (Ctrl-E): Displays the last entry in the history list. ═══ 7.2.4.2.6. Help ═══ Help = Key (F1): Invokes the HELP facility. ═══ 7.2.4.2.7. LineToEnd ═══ LineToEnd = Key (Ctrl-Enter): Copies the current command line to the end of the history list, then executes it. ═══ 7.2.4.2.8. NextFile ═══ NextFile = Key (F9, Tab): Gets the next matching filename during filename completion. See ClearKeyMap if you need to remove the default mapping of Tab to this function. ═══ 7.2.4.2.9. NextHistory ═══ NextHistory = Key (Ctrl-Down): Recalls the next command from the command history. Also see Scrolling and History Keystrokes and the SwapScrollKeys directive. ═══ 7.2.4.2.10. NormalEditKey ═══ NormalEditKey = Key: Deassigns a command-line editing key in order to disable the usual meaning of the key while editing a command line, and/or make it available for keystroke aliases. For additional details see NormalKey. ═══ 7.2.4.2.11. PopFile ═══ PopFile = Key (F7, Ctrl-Tab): Opens the filename completion window. You may not be able to use Ctrl-Tab, because not all systems recognize it as a keystroke. See ClearKeyMap if you need to remove the default mapping of Ctrl-Tab to this function. ═══ 7.2.4.2.12. PrevFile ═══ PrevFile = Key (F8, Shift-Tab): Gets the previous matching filename during filename completion. See ClearKeyMap if you need to remove the default mapping of Shift-Tab to this function. ═══ 7.2.4.2.13. PrevHistory ═══ PrevHistory = Key (Ctrl-Up): Recalls the previous command from the command history. Also see Scrolling and History Keystrokes and the SwapScrollKeys directive. ═══ 7.2.4.2.14. SaveHistory ═══ SaveHistory = Key (Ctrl-K): Saves the command line in the command history list without executing it. ═══ 7.2.4.3. Scrollback Buffer Keys ═══ The following keys are also part of the command line editing group. They are used to manipulate the scrollback buffer rather than to edit commands. For additional information see Scrolling and History Keystrokes and the SwapScrollKeys directive. The scrollback buffer keys are: ScrollUp Scroll the buffer up one line ScrollDown Scroll the buffer down one line ScrollPgUp Scroll the buffer up one page ScrollPgDn Scroll the buffer down one page ═══ 7.2.4.3.1. ScrollUp ═══ ScrollUp = Key (Up): Scrolls the Take Command scrollback buffer up one line. ═══ 7.2.4.3.2. ScrollDown ═══ ScrollDown = Key (Down): Scrolls the Take Command scrollback buffer down one line. ═══ 7.2.4.3.3. ScrollPageUp ═══ ScrollPgUp = Key (PgUp): Scrolls the Take Command scrollback buffer up one page. ═══ 7.2.4.3.4. ScrollPageDown ═══ ScrollPgDn = Key (PgDn): Scrolls the Take Command scrollback buffer down one page. ═══ 7.2.4.4. Popup Window Keys ═══ The following directives apply to popup windows, including the command history window, the directory history window, the file completion window, the extended directory search window, and the @SELECT window. The Popup window keys are: DirWinOpen Opens the directory history window HistWinOpen Opens the command history window NormalPopupKey Deassigns a popup window key PopupWinBegin Moves to the first line of the popup window PopupWinDel Deletes a line from within a popup window PopupWinEdit Moves a line from a popup window to the prompt PopupWinEnd Moves to the last line of a popup window PopupWinExec Executes the selected line in a popup window ═══ 7.2.4.4.1.  DirWinOpen ═══ DirWinOpen = Key (F6): Opens the directory history window while at the command line. Also see Scrolling and History Keystrokes. ═══ 7.2.4.4.2. HistWinOpen ═══ HistWinOpen = Key (Ctrl-PgUp): Brings up the history window while at the command line. Also see Scrolling and History Keystrokes and the SwapScrollKeys directive. ═══ 7.2.4.4.3. NormalPopupKey ═══ NormalPopupKey = Key: Deassigns a popup window key in order to disable the usual meaning of the key within the popup window. For additional details see NormalKey. ═══ 7.2.4.4.4. PopupWinBegin ═══ PopupWinBegin = Key (Ctrl-PgUp): Moves to the first item in the list when in a popup window. ═══ 7.2.4.4.5. PopupWinDel ═══ PopupWinDel = Key (Ctrl-D): Deletes a line from within the command history or directory history window. ═══ 7.2.4.4.6. PopupWinEdit ═══ PopupWinEdit = Key (Ctrl-Enter): Moves a line from the command history or directory history window to the prompt for editing. ═══ 7.2.4.4.7. PopupWinEnd ═══ PopupWinEnd = Key (Ctrl-PgDn): Moves to the last item in the list when in a popup window. ═══ 7.2.4.4.8. PopupWinExec ═══ PopupWinExec = Key (Enter): Selects the current item and closes the window. ═══ 7.2.4.5. LIST Keys ═══ These directives are effective only inside the LIST command. The LIST keys are: ListExit Exits the current file ListFind Prompts and searches for a string ListFindReverse Prompts and searches backwards ListHex Toggles hexadecimal display mode ListHighBit Toggles LIST's "strip high bit" option ListInfo Displays information about the current file ListNext Finds the next matching string ListPrevious Finds the previous matching string ListPrint Prints the file on LPT1 ListWrap Toggles LIST's wrap option NormalListKey Deassigns a LIST key ═══ 7.2.4.5.1. ListExit ═══ ListExit = Key (Esc): Exits the LIST command. ═══ 7.2.4.5.2. ListFind ═══ ListFind = Key (F): Prompts and searches for a string. ═══ 7.2.4.5.3. ListFindReverse ═══ ListFindReverse = Key (Ctrl-F): Prompts and searches backward for a string. ═══ 7.2.4.5.4. ListHex ═══ ListHex = Key (X): Toggles hexadecimal display mode. ═══ 7.2.4.5.5. ListHighBit ═══ ListHighBit = Key (H): Toggles LIST's "strip high bit" option, which can aid in displaying files from certain word processors. ═══ 7.2.4.5.6. ListInfo ═══ ListInfo = Key (I): Displays information about the current file. ═══ 7.2.4.5.7. ListNext ═══ ListNext = Key (N): Finds the next matching string. ═══ 7.2.4.5.8. ListPrevious ═══ ListPrevious = Key (Ctrl-N): Finds the previous matching string. ═══ 7.2.4.5.9. ListPrint ═══ ListPrint = Key (P): Prints the file. ═══ 7.2.4.5.10. ListWrap ═══ ListWrap = Key (W): Toggles LIST's wrap option on and off. The wrap option wraps text at the right margin. ═══ 7.2.4.5.11. NormalListKey ═══ NormalListKey = Key: Deassigns a LIST key in order to disable the usual meaning of the key within LIST. For additional details see NormalKey. ═══ 7.2.5. Advanced Directives ═══ These directives are generally used for unusual circumstances, or for diagnosing problems. Most often they are not needed in normal use. They cannot be entered via the configuration notebook; you must enter them manually (see TCMDOS2.INI for details). ClearKeyMap Clear default key mappings Debug Set debugging options Include Include text from a file in the current .INI file ═══ 7.2.5.1. ClearKeyMap ═══ ClearKeyMap: Clears all current key mappings. ClearKeyMap is a special directive which has no value or "=" after it. Use ClearKeyMap to make one of the keys in the default map (Tab, Shift-Tab, Ctrl-Tab, or Ctrl-Bksp) available for a keystroke alias. ClearKeyMap should appear before any other key mapping directives. If you want to clear some but not all of the default mappings, use ClearKeyMap, then recreate the mappings you want to retain (e.g., with "NextFile=Tab", etc.). ═══ 7.2.5.2. Debug ═══ Debug = nnnn (0): Controls certain debugging options which can assist you in tracking down unusual problems. Use the following values for Debug; to select more than one option, add the values together: 1 During the startup process, display the complete command tail passed to Take Command, then wait for a keystroke. 2 Include the product name with each error message displayed by Take Command. This may be useful if you are unsure of the origin of a particular error message. Also see the batch file debugger, a separate and unrelated facility for stepping through batch files. ═══ 7.2.5.3. Include ═══ Include = File: Include the text from the named file at this point in the processing of the current .INI file. Use this option to share a file of directives between several JP Software products. The text in the named file is processed just as if it were part of the original .INI file. When the include file is finished, processing resumes at the point where it left off in the original file. The included file may contain any valid directive for the current section, but may not contain a section name. Includes may be nested up to three levels deep (counting the original file as level 1). You must maintain include files manually Ч the configuration dialogs modify the original .INI file only, and do not update included files. ═══ 8. Setup and Troubleshooting ═══ To install Take Command, see the Introduction and Installation Guide. This section will help you if you have difficulties with Take Command once you have finished the initial installation. The topics included in this section are: Starting Take Command includes information about creating new desktop objects for Take Command, options available during startup and on the command line, and where Take Command files should be placed on your hard disk. The Take Command Help System describes this online help and explains how to configure it. Error Messages contains a list of the error messages that Take Command may display, what each means, and how to correct each possible error. Troubleshooting, Service, and Support explains how to isolate problems you may encounter in using Take Command and how to obtain technical support from JP Software. ═══ 8.1. Starting Take Command ═══ This section covers starting Take Command, including: Creating Desktop Objects for Take Command Startup and Command Line Options ═══ 8.1.1. Creating Desktop Objects for Take Command ═══ This section assumes you are running OS/2 Warp 4, with the default desktop shell and a standard OS/2 desktop. If you are using an earlier version of OS/2 or a different shell, or have altered your OS/2 desktop configuration substantially, you will need to take those changes into account as you read the instructions below. The Take Command for OS/2 installation program normally creates a desktop folder which contains objects to start Take Command for OS/2 and its online help. If you want to create additional objects in other folders, or directly on the desktop, click mouse button 2 on the installed Take Command for OS/2 object, select Copy on the popup menu, and copy the object to another location as desired. You can then alter the properties of the new object if you wish. If you need to create a new object, switch to the folder where you want the object to appear and either copy an existing object (use the Copy or Create Another selection on the object's popup menu) or drag a Program Template in from the Templates folder. The new object's Properties notebook should open automatically. Use the Program page of the notebook to set the file name to d:\path\TCMDOS2.EXE (use the appropriate drive and path for your system). Then modify the parameters and startup directory as required. No additional settings are required; the only required item is the drive and path for TCMDOS2.EXE. However, you can put command-line switches, a command, or the name of a batch file in the Parameters field for any object. This allows you to run specific commands or set configuration options when you start Take Command for OS/2 from that object. For details on the command line options available, see Startup and Command Line Options. For more information on creating and configuring desktop objects see your OS/2 documentation. ═══ 8.1.2. Startup and Command Line Options ═══ When you configure a Take Command object, place the full path and name for the TCMDOS2.EXE file in the Path and File Name field on the Program page of the object's Settings notebook, and put any startup options that you want passed to Take Command (e.g., the name of a startup batch file) in the Parameters field. (To bring up the Settings notebook click on the object with mouse button 2, then click on the Settings item on the popup menu.) For example: Path and File Name: C:\TCMDOS2\TCMDOS2.EXE Parameters: C:\GO.BAT Working directory: C:\ When Take Command starts it automatically runs the optional TCSTART batch file. You can use this file to load aliases and environment variables and otherwise initialize Take Command. You can also place the name of a batch file, internal or external command, or alias at the end of the Parameters field for any object (as shown in the example above). The batch file, command, or alias will be executed after TCSTART but before the first prompt is displayed. Each OS/2 program -- including Take Command -- has a command line which can be used to pass information to the program when it starts. When Take Command is started from an object on the OS/2 desktop, the command line is entered in the Parameters field on the Program page of the Settings notebook for the Take Command object. The Take Command startup command line does not need to contain any information. When invoked with an empty command line, Take Command will configure itself from the TCMDOS2.INI file, run TCSTART, and then display a prompt and wait for you to type a command. However, you may add information to the startup command line that will affect the way Take Command operates. Take Command recognizes several optional fields on the command line. If you use more than one of these fields, you should use them in the order that they are described below. If you do not do so, you may find that they do not operate properly. The following options can be included are: @d:\path\inifile: This option sets the path and name of the TCMDOS2.INI file. You do not need this option if you aren't using a TCMD.INI file, or if the file is named TCMDOS2.INI and is stored in the same subdirectory as TCMDOS2.EXE. //iniline: This option tells Take Command to treat the text appearing between the // and the next space or tab as a TCMDOS2.INI directive. The directive should be in the same format as a line in the [TakeCommand] section of TCMDOS2.INI, but it may not contain spaces, tabs, or comments. This option overrides any corresponding directive in your TCMDOS2.INI file. This option may be repeated. It is a convenient way to place a few simple directives on the startup line without having to modify or create a new .INI file. /L, /LA, /LD, and /LH: These options force Take Command to use a local alias, directory history, and / or command history list. This allows you to use global aliases as the default, but start a specific Take Command session with local aliases or history. See ALIAS for details on local and global aliases, Directory History Window for details on local and global directory history, and Command History for details on local and global command history. /LA forces local aliases, /LD forces local directory history, /LH forces local command history, and /L forces all three. [/C] command: This option tells Take Command to run a command when it starts. The command will be run after TCSTART has been executed and before any command prompt is displayed. It can be any valid internal or external command, batch file, or alias; you may include multiple commands by using the command separator. All other startup options must be placed before the command, because Take Command will treat characters after the command as part of the command and not as additional startup options. When the command is preceded by a /C, Take Command will execute the command and then exit and return to the parent program or the OS/2 desktop without displaying a prompt. For example, to execute any TCSTART file you have created, execute C:\STARTUP.BAT, and then display the prompt when the object starts: Path and File Name: C:\TCMDOS2\TCMDOS2.EXE Parameters: C:\STARTUP.BAT Working directory: C:\ To execute an internal or external command, an alias, or a batch file and then exit (return to the desktop) when it is done, place /Ccommand (rather than just command) as the last item in the Parameters field. For example: Path and File Name: C:\TCMDOS2\TCMDOS2.EXE Parameters: /C C:\STARTUP.BAT Working directory: C:\ ═══ 8.2. The Take Command Help System ═══ This online help system for Take Command covers all Take Command features and internal commands. It includes reference information to assist you in using Take Command and developing batch files, and includes most -- but not all -- of the details which are included in the printed Take Command manuals. If you type part or all of a command on the line and then press F1, the help system will provide "context-sensitive" help by using the first word on the line as a help topic. If it's a valid topic, you will see help for that topic automatically; if not, you will see the list of all help topics and you can pick the one you want. You can use this feature to obtain help on any topic -- not just on commands. For example, if you enter the command HELP _DISK you will see help for the _DISK internal variable. If you type the name of any internal command at the prompt, followed by a slash and a question mark [/?] like this: copy /? then you will see help for the command in a "quick-reference" style. The /? option may not work correctly if you have used an alias to redefine how an internal command operates. To view the /? help for such a command you must add an asterisk to the beginning of the command to disable alias processing. For example, if you have defined this alias: alias copy *copy /r then the command COPY /? will be translated to COPY /R /?, which will not work properly (because the /? does not appear immediately after the command name). However, if you use *COPY /?, the alias will be ignored and the /? will work as you intended. The Take Command help system uses OS/2's VIEW.EXE to display help text. Once you've started the help system with HELP or F1, you can use VIEW's standard keystrokes to navigate. For more information, click on the Help menu at the top of the VIEW window. Configuring the Help System For the help system to work properly you must place the files TCMDOS2.INF (this help text) and TCMDOS2H.MSG (the "quick-help" text) in the proper directories. See your Introduction and Installation Guide for additional details. OS/2 includes many other help files. For example, there is a complete reference to all internal and external commands in the reference book named CMDREF.INF. You can specify a different set of help files or "books" to be opened when HELP or F1 is invoked with the HelpBook directive in TCMDOS2.INI, or the corresponding entry in the configuration notebook. For example, to set up Take Command for OS/2 so that both the CMDREF book and Take Command for OS/2 book are displayed when F1 is pressed, include the following directive in TCMDOS2.INI, or make the corresponding change in the configuration notebook: HelpBook=TCMDOS2+CMDREF When more than one book is listed in the HelpBook setting, the OS/2 help program will see the combined group as a single book. The displayed Table of Contents will include the tables of contents from all the listed books, joined together as one group of topics with no divisions to show where one book ends and the next begins. If any of the listed books are not available the help program will not start. The Take Command installation program sets up a separate object for Take Command help so that you can load the help file directly. To create a similar object manually, use entries like this on the Program page of the object's Settings notebook: Path and File Name: VIEW.EXE Parameters: TCMDOS2 Working Directory: d:\path where "d:\path" is the directory where you installed Take Command for OS/2. ═══ 8.3. Error Messages ═══ This section lists error messages generated by Take Command, and includes a recommended course of action for most errors. If you are unable to resolve the problem, look through your Introduction and Installation Guide for any additional troubleshooting recommendations, then contact JP Software for technical support. Error messages relating to files are generally reports of errors returned by OS/2. You may find some of these messages (for example, "Access denied") vague enough that they are not always helpful. Take Command includes the file name in file error messages, but is often unable to determine a more accurate explanation of these errors. The message shown is the best information available based on the error codes returned by OS/2. The following list includes all error messages, in alphabetical order: Access denied: You tried to write to or erase a read-only file, rename a file or directory to an existing name, create a directory that already exists, remove a read-only directory or a directory with files or subdirectories still in it, or access a file in use by another program. Alias loop: An alias refers back to itself either directly or indirectly (i.e., a = b = a), or aliases are nested more than 16 deep. Correct your alias list. Already excluded files: You used more than one exclude range in a command. Combine the exclusions into a single range. Bad disk unit: Generally caused by a disk drive hardware failure. Batch file missing: Take Command can't find the batch (.BTM or .CMD) file it was running. It was either deleted, renamed, moved, or the disk was changed. Correct the problem and rerun the file. Can't COPY or MOVE file to itself: You cannot COPY or MOVE a file to itself. Take Command attempts to perform full path and filename expansion before copying to help ensure that files aren't inadvertently destroyed. Can't create: Take Command can't create the specified file. The disk may be full or write protected, or the file already exists and is read-only, or the root directory is full. Can't delete: Take Command can't delete the specified file or directory. The disk is probably write protected. Can't get directory: Take Command can't read the directory. The disk drive is probably not ready. Can't install hook: Take Command for OS/2 cannot install the operating system hooks required to support the KEYSTACK command. The operating system may have been damaged or improperly installed, or there may be too few resources to support KEYSTACK. Can't make directory entry: Take Command can't create the filename in the directory. This is usually caused by a full root directory. Create a subdirectory and move some of the files to it. Can't open: Take Command can't open the specified file. Either the file doesn't exist or the disk directory or File Allocation Table is damaged. Can't remove current directory: You attempted to remove the current directory, which OS/2 does not allow. Change to the parent directory and try again. CD-ROM door open or CD-ROM not ready: The CD-ROM drive door is open, the power is off, or the drive is disconnected. Correct the problem and try again. CD-ROM not High Sierra or ISO-9660: The CD-ROM is not recognized as a data CD (it may be a music CD). Put the correct CD in the drive and try again. Clipboard is empty or not text format: You tried to retrieve some text from the OS/2 clipboard, but there is no text available. Correct the contents of the clipboard and try again. Clipboard is in use by another program: Take Command could not access the OS/2 clipboard because another program was using it. Wait until the clipboard is available, or complete any pending action in the other program, then try again. Command line too long: A single command exceeded 1023 characters, or the entire command line exceeded 2047 characters, during alias and variable expansion. Reduce the complexity of the command or use a batch file. Also check for an alias which refers back to itself either directly or indirectly. Command only valid in batch file: You have tried to use a batch file command, like DO or GOSUB, from the command line or in an alias. A few commands can only be used in batch files (see the individual commands for details). Contents lost before copy: COPY was appending files, and found one of the source files is the same as the destination. That source file is skipped, and appending continues with the next file. Data error: OS/2 can't read or write properly to the device. On a floppy drive, this error is usually caused by a defective floppy disk, dirty disk drive heads, or a misalignment between the heads on your drive and the drive on which the disk was created. On a hard drive, this error may indicate a drive that is too hot or too cold, or a hardware problem. Retry the operation; if it fails again, correct the hardware or diskette problem. Directory stack empty: POPD or DIRS can't find any entries in the directory stack. Disk is write protected: The disk cannot be written to. Check the disk and remove the write-protect tab or close the write-protect window if necessary. Drive not ready -- close door: The removable disk drive door is open. Close the door and try again. Duplicate redirection: You tried to redirect standard input, standard output, or stand error more than once in the same command. Environment already saved: You have already saved the environment with a previous SETLOCAL command. You cannot nest SETLOCAL / ENDLOCAL pairs. Error in command-line directive: You used the //iniline option to place an .INI directive on the startup command line, but the directive is in error. Usually a more specific error message follows, and can be looked up in this list. Error on line [nnnn] of [filename]: There is an error in your TCMDOS2.INI file. The following message explains the error in more detail. Correct the line in error and restart Take Command for your change to take effect. Error reading: OS/2 experienced an I/O error when reading from a device. This is usually caused by a bad disk, a device not ready, or a hardware error. Error writing: OS/2 experienced an I/O error when writing to a device. This is usually caused by a full disk, a bad disk, a device not ready, or a hardware error. Exceeded batch nesting limit: You have attempted to nest batch files more than 10 levels deep. File Allocation Table bad: OS/2 can't access the FAT on the specified disk. This can be caused by a bad disk, a hardware error, or an unusual software interaction. File exists: The requested output file already exists, and Take Command won't overwrite it. File is empty: You attempted to LIST a file with no data (a zero-byte file). File not found: Take Command couldn't find the specified file. Check the spelling and path name. General failure: This is usually a hardware problem, particularly a disk drive failure or a device not properly connected to a serial or parallel port. Try to correct the problem, or reboot and try again. Also see Data error above. Include file not found: You used the Include directive in the TCMDOS2.INI file, but the file you specified was not found or could not be opened. Include files nested too deep: You used the Include directive in the TCMDOS2.INI file, and attempted to nest include files more than three levels deep. Infinite COPY or MOVE loop: You tried to COPY or MOVE a directory to one of its own subdirectories and used the /S switch, so the command would run forever. Correct the command and try again. Insufficient disk space: COPY or MOVE ran out of room on the destination drive. Remove some files and retry the operation. Invalid character value: You gave an invalid value for a character directive in the TCMDOS2.INI file. Invalid choice value: You gave an invalid value for a "choice" directive (one that accepts a choice from a list, like "Yes" or "No") in the TCMDOS2.INI file. Invalid color: You gave an invalid value for a color directive in the TCMDOS2.INI file. Invalid count: The character repeat count for KEYSTACK is incorrect. Invalid date: An invalid date was entered. Check the syntax and reenter. Invalid directive name: Take Command can't recognize the name of a directive in your TCMDOS2.INI file. Invalid drive: A bad or non-existent disk drive was specified. Invalid key name: You tried to make an invalid key substitution in the TCMDOS2.INI file, or you used an invalid key name in a keystroke alias or command. Correct the error and retry the operation. Invalid numeric value: You gave an invalid value for a numeric directive in the TCMDOS2.INI file. Invalid parameter: Take Command didn't recognize a parameter. Check the syntax and spelling of the command you entered. Invalid path: The specified path does not exist. Check the disk specification and/or spelling. Invalid path or file name: You used an invalid path or filename in a directive in the TCMDOS2.INI file. Invalid time: An invalid time was entered. Check the syntax and reenter. Keystroke substitution table full: Take Command ran out of room to store keystroke substitutions entered in the TCMDOS2.INI file. Reduce the number of key substitutions or contact JP Software or your dealer for assistance. Label not found: A GOTO or GOSUB referred to a non-existent label. Check your batch file. Missing ENDTEXT: A TEXT command is missing a matching ENDTEXT. Check the batch file. Missing GOSUB: Take Command cannot perform the RETURN command in a batch file. You tried to do a RETURN without a GOSUB, or your batch file has been corrupted. Missing SETLOCAL: An ENDLOCAL was used without a matching SETLOCAL. No aliases defined: You tried to display aliases but no aliases have been defined. No closing quote: Take Command couldn't find a second matching back quote [`] or double-quote ["] on the command line. No expression: The expression passed to the @EVAL variable function is empty. Correct the expression and retry the operation. No shared memory found: The SHRALIAS command could not find any global alias list, history list, or directory history list to retain, because you executed the command from a session with local lists. Start Take Command with at least one global list, then invoke SHRALIAS. Not an alias: The specified alias is not in the alias list. Not in environment: The specified variable is not in the environment. Not ready: The specified device can't be accessed. Not same device: This error usually appears in RENAME. You cannot rename a file to a different disk drive. Out of memory: Take Command or OS/2 had insufficient memory to execute the last command. Try to free some memory by closing other sessions. If the error persists, contact JP Software for assistance. Out of paper: OS/2 detected an out-of-paper condition on one of the printers. Check your printer and add paper if necessary. Overflow: An arithmetic overflow occurred in the @EVAL variable function. Check the values being passed to @EVAL. @EVAL can handle 16 digits to the left of the decimal point and 8 to the right. Read error: OS/2 encountered a disk read error; usually caused by a bad or unformatted disk. Also see Data error above. Sector not found: Disk error, usually caused by a bad or unformatted disk. Also see Data error above. Seek error: OS/2 can't seek to the proper location on the disk. This is generally caused by a bad disk or drive. Also see Data error above. Sharing error or Sharing violation: You tried to access a file in use by another program. Wait for the file to become available, or change your method of operation so that another program does not have the file open while you are trying to use it. SHRALIAS already loaded: You used the SHRALIAS command to load SHRALIAS.EXE, but it was already loaded. This message is informational and generally does not indicate an error condition. SHRALIAS not loaded: You used the SHRALIAS /U command to unload SHRALIAS.EXE, but it was never loaded. This message is informational and may not indicate an error condition. Startup failed, contact JP Software: Take Command could not initialize and start operation. Contact JP Software or your dealer for assistance. String area overflow: Take Command ran out of room to store the text from string directives in the TCMDOS2.INI file. Reduce the complexity of the TCMDOS2.INI file or contact JP Software for assistance. Syntax error: A command or variable function was entered in an improper format. Check the syntax and correct the error. Too many open files: OS/2 has run out of file handles. Unbalanced parentheses: The number of left and right parentheses did not match in an expression passed to the %@EVAL variable function. Correct the expression and retry the operation. UNKNOWN_CMD loop: The UNKNOWN_CMD alias, explained under the ALIAS command, called itself more than ten times. The alias probably contains an unknown command itself, and is stuck in an infinite loop. Correct the alias. Unknown command: A command was entered that Take Command didn't recognize and couldn't find in the current search path. Check the spelling or PATH specification. You can handle unknown commands with the UNKNOWN_CMD alias (see ALIAS). Variable loop: A nested environment variable refers to itself, or variables are nested more than 16 deep. Correct the error and retry the command. Window title not found: The ACTIVATE command could not find a window with the specified title. Correct the command or open the appropriate window and try again. Write error: OS/2 encountered a disk write error; usually caused by a bad or unformatted disk. Also see Data error above. ═══ 8.4. Troubleshooting, Service, and Support ═══ Before You Contact Us Before contacting us for support, please check this help file, the Reference Manual and other documentation for answers to your question. If you can't find what you need, try the Index. If you're having trouble getting Take Command to run properly, see the Introduction and Installation manual and look through the README.TXT file for any last-minute information for your product. (If you need help with sales, ordering, shipments, brand codes, or other similar non-technical issues please contact our Sales and Customer Service department. See Contacting JP Software for our addresses.) If you do need to contact us for support, it helps if you can give us some basic information. The first four items listed below are essential for us to be able to understand and assist you with your problem: What environment are you working in? This includes the operating system version are you using, the version of the JP Software product involved, and related information such as network connections and the name and version number of any other software which appears to be involved in the problem. Use the VER /R command to determine the Take Command version and operating system version. What exactly did you do? A concise description of what steps you must take to make the problem appear is much more useful than a long analysis of what might be happening. What did you expect to happen? Tell us the result you expected from the command or operation in question, so that we understand what you are trying to do. What actually happened? At what point did the failure occur? If you saw an error message or other important or unusual information on the screen, what exactly did it say? Briefly, what techniques did you use to try to resolve the problem? What results did you get? If the problem seems related to startup and configuration issues, what are the contents of any startup files you use (such as CONFIG.SYS, TCSTART, TCEXIT, and the TCMDOS2.INI file), any batch files they call, and any alias or environment variable files they load? Can you repeat the problem or does it occur randomly? If it's random, does it seem related to the programs you're using when the problem occurs? Online Support Support for Take Command for OS/2 is offered via our online support forum, where our support personnel can read and respond to your messages, and other users can respond as well. The forum is accessible via several methods; for complete details and access links see the support area of our web site at http://www.jpsoft.com/. A number of other support resources are available from our web site, including error message listings, documentation files, product histories, technical tips and discussions, other technical information, and links to other companies' sites. We update this information regularly, and we encourage you to check the Technical Support area of the web site to see if the information there will address any questions you have. If you are unable to gain access to the forum, or you need to include confidential information in your support request, contact us via email at support@jpsoft.com and we will assist you in resolving the problem with forum access, or assist you with your request privately if appropriate. Please do not use this address for standard support questions which can be posted on the forum. Technical support messages should be sent as standard ASCII text. Please do not transmit attached files, binary files, screen images, or any file over 10K bytes in size to any of our electronic technical support addresses unless asked to do so by our support staff. ═══ 8.4.1. Contacting JP Software ═══ You can contact JP Software at the following addresses and numbers. Our normal business hours are 8:30 AM to 5:00 PM weekdays, eastern US time (except holidays). Address: JP Software Inc. P.O. Box 1470 East Arlington, MA 02474 USA Main number: (781) 646-3975 Fax: (781) 646-0904 Order Line: (800) 368-8777 (US / Canada, orders only) Email: Sales / Customer Service: sales@jpsoft.com Technical Support: Visit our support forum, accessible via the support area of our web site at http://www.jpsoft.com/ World Wide Web: http://www.jpsoft.com/ Downloads via FTP: ftp://ftp.jpsoft.com/ ═══ 9. What's New ═══ This section provides a comprehensive list of what's changed since our previous major release, version 1.02. Maintenance changes made between versions 2.00 and 2.03 are indicated by 2.01, 2.02, or 2.03 in the left margin. This topic does not explain how to use each new feature. Instead, where appropriate we have provided links below to the detailed help topics containing additional usage information or other documentation. Some of the descriptions here may be more detailed than you need; if you aren't using a feature, feel free to skip to the next item. If you are new to Take Command for OS/2 with version 2.03, you can skip this topic entirely. This topic is divided into the following subtopics: General Features and Enhancements Line Editing and History Command Changes Variables and Variable Functions Startup and Configuration Technical and Compatibility Enhancements Bugs Fixed The major new features in this release include: п Extended Directory Searches: allow you to change to a directory anywhere on your system by entering only part of its name. They must be explicitly enabled before you can use them. See Directory Navigation for complete details. п New File Exclusion Ranges: provide a convenient way to exclude files from any internal command -- faster and more flexible than using EXCEPT. п The new Batch File Debugger can execute each line step by step, process or trace into additional batch files, and display variables, aliases, and expanded commands at each step. п New commands include: OPTION: Offers complete configuration adjustment, either through interactive dialogs or on the command line. SWITCH: Provides for "case" statements in batch files. TOUCH: Adjusts file dates and times. TREE: Displays the directory tree, with or without file names, in a variety of formats. ═══ 9.1. General Features and Enhancements ═══ What's New - General Features and Enhancements п Added a complete batch file debugger. The debugger displays the batch file in a window and allows you to execute each line step by step, process or trace into additional batch files and subroutines, and display variables and aliases at each step. See Batch File Debugging for complete details. п Popup windows (for filename completion, command history recall, etc.) now allow you to search for a line within the window contents by typing the first few characters of the line. The search string is displayed in the lower right corner of the window. п You can now redirect to and from the clipboard by using the pseudo-device name CLIP:. For example, to redirect DIR to the clipboard: dir *.doc > clip: п The online help has been reorganized to make it easier to navigate through the main topics, and includes additional reference information, reference tables, and a glossary. п The default maximum file description length is now 511 bytes in all products. п Two new characters can now follow the escape character: An escape followed by a 'q' will substitute a double quote; an escape followed by a 'k' will substitute a back quote. п The decimal and thousands characters used in @EVAL and in displayed version numbers and other similar locations are now controllable with the DecimalChar and ThousandsChar directives in the .INI file, the corresponding options in the configuration or OPTION dialogs, and the SETDOS /G command. These characters are saved by SETLOCAL and restored by ENDLOCAL. This is intended as an aid to those writing batch files which perform arithmetic operations and which may be used in countries with differing separator characters. п The directory stack size used by PUSHD and POPD has been increased from 255 to 511 bytes to leave adequate room for long directory names. п .BTM files can now be longer than 64K bytes, though compressed .BTMs still have to be less than 64K. ═══ 9.2. Command Line Editing ═══ What's New - Command Line Editing п Extended directory searches can be used directly from the command line for quick directory navigation; see Automatic Directory Changes or Directory Navigation for details. п Made several ehancements to filename completion, including: * The Ctrl-A key, which toggles between long and short filenames for filename completion, can now be hit at any point during command line entry -- not just during filename completion. For example, if you hit Ctrl-A at the beginning of the command line, all filenames subsequently returned for that line will be short names (until you hit Ctrl-A again). * Filename completion can now be customized for individual commands via the new FileCompletion .INI directive (or environment variable). For example, you can configure Take Command to complete only the names of .TXT files when the command line starts with the name of your text editor, or to display only directory names when you are entering a CD command. * The F7 filename completion popup window now sorts the filename list alphabetically. п You can now expand aliases immediately while still on the command line with the Ctrl-F key. п Command line history recall will now stop at the beginning and end of the history list rather than wrapping around, if you set HistWrap to No in the .INI file or through the configuration dialogs. п Take Command now supports ANSI screen commands. п In the Find Files dialog, double-clicking on the filename, then clicking on LIST in the Info dialog will now start LIST (in a separate copy of Take Command) with the pointer at the first matching string in the file. п A double (left) click in the Take Command window now selects the word under the mouse pointer. ═══ 9.3. Command Changes ═══ What's New - Command Changes п ATTRIB: Added the /E switch to disable display of non-fatal errors. Also, ATTRIB now allows underscores in the attribute string, so that you can get a result from the %@ATTRIB variable function and feed it directly to the ATTRIB command. п CD and CDD: Now support extended directory searches, which allow you to change to a directory anywhere on your system by entering only part of its name. The CDD /S switch builds the extended directory search database. Extended directory searches mmust be explicitly enabled before you can use them. See Directory Navigation for complete details. п CDD: Added the /A switch to display the current directory for all existing and ready drives from C: to Z:. п CHCP: Changed to only affect the current process and its children, as in CMD.EXE. п COPY: Added several switches: /E Disable display of non-fatal errors. /K Preserve read-only attributes during a COPY. /X Clear the archive bit from the source file after a successful copy. /Z Overwrite read-only target files. п COPY: When copying from a FAT drive to an HPFS drive, COPY will now use the .LONGNAME extended attribute of the source file (if available) to determine the long name. When copying from HPFS to FAT, COPY sets the .LONGNAME attribute if possible, to preserve the long name. п DEL: Added two switches: /E Disable display of non-fatal errors. /W Clear the file to 0's before deleting it. п DIR: Added or modified several of the DIR switches: /2 Now forces the use of truncated names on HPFS drives. /4 Now forces the use of truncated names on HPFS drives, and displays files between 1 and 9.9 Mb in tenths (i.e., "2.4M"). /G (New) Displays the allocated size instead of the file size. /W Now forces the use of truncated names on HPFS drives. п DIRHISTORY: This new command has the same syntax as HISTORY, but it modifies the directory history. п DO: Added two new DO loop types: * "DO x IN filename" retrieves each matching filename from a wildcard spec and inserts the value into the variable. * "DO x IN @filename" retrieves each line in the file and inserts it into the variable. п ECHOERR and ECHOSERR: These new commands are like ECHO and ECHOS, but output goes to the standard error device instead of standard output. п ENDLOCAL: To aid in making batch files portable, SETLOCAL and ENDLOCAL now save and restore the command separator, escape character, parameter character, and decimal and thousands separators. п FFIND: Added two new switches: /I Do a literal match even if the text search string contains wildcard characters. /R Start searching for text from the end backwards. Also, the /X switch will now display the offset in both hex and decimal. п FOR: Added several new switches for compatibility with Windows NT 4.0's CMD.EXE; see the command reference information for complete details. п GOTO: Added support for Windows NT 4.0's "GOTO :EOF" -- If there is no ":EOF" label, GOTO ends the current batch file (equivalent to a QUIT). п IF / IFF: These commands now support nested conditional tests, with parentheses, e.g.: if (%a == 1 .or. %b == 2) .and. %c == 3 echo something See the command reference information for complete syntax rules. п Added a new "IF DEFINED varname" test, which succeeds if the specified variable exists in the environment. This is included for compatibility with Windows NT 4.0's CMD.EXE, and is the same as a test like: if "%varname" ne "" ... п Changed the comparison tests to accept a leading decimal separator as a numeric character, provided the remainder of the string is numeric and does not contain additional decimal characters. п KEYSTACK: Now supports sending keystrokes to windowed VIO sessions (not just PM apps) from Take Command for OS/2. п LIST: Added a range of enhancements, including: * Ctrl-PgUp and Ctrl-PgDn will go to the previous and next file in the current group, respectively. * Ctrl-F searches backwards for a text string; Ctrl-N repeats the last search, searching backwards. * Matching strings on the first page are now highlighted after a search. * When piping output to LIST in most cases you no longer need the /S switch; for example, to view DIR's output in LIST you can now use: dir | list Also, added three new switches: /I Ignore case in a /T search. /R The search initiated by /T goes backwards from the end of the file. /T Search for text when LIST starts. п MD: Added the /N switch to create a directory without updating the extended directory search database (useful for temporary directories). п MOVE: Added the /E switch to disable display of non-fatal errors. п MOVE: When moving files from a FAT drive to an HPFS drive, MOVE will now use the .LONGNAME extended attribute of the source file (if available) to determine the long name. When moving files from HPFS to FAT, MOVE sets the .LONGNAME attribute if possible, to preserve the long name. п OPTION: This new command can be used for two purposes. When invoked without parameters, it loads configuration dialogs which adjust most commonly-used settings in the .INI file. The dialogs provide a convenient method of adjusting configuration without manually editing the .INI file. OPTION can also be used to change specific settings on an individual basis with the OPTION Name=value ... syntax; see the command for complete details. п PROMPT: Added the $+ metacharacter, which displays one + for each PUSHD level. п REN / RENAME: Added the /E switch to disable display of non-fatal errors. п RETURN: Now accepts an optional argument for the errorlevel to return. The errorlevel can be tested with %? or IF ERRORLEVEL. п SCREEN, SCRPUT, and VSCRPUT: If you specify 999 for the row, the text will be centered vertically; if you specify 999 for the column, the text will be centered horizontally. п SELECT: You can now type characters from the start of a filename and the selection bar will jump to the first matching name. Due to this change, the key to popup LIST on the currently selected file has been changed from L to ^L. Also, added the /T:acw switch to select the date and time to use for display and sorting on HPFS drives. п SETLOCAL: To aid in making batch files portable, SETLOCAL now saves the command separator, escape character, parameter character, and decimal and thousands separators; ENDLOCAL restores them. п SHIFT: The new "/n" argument will start the shift at the specified argument -- i.e., "shift /2" moves %3 to %2, %4 to %3, etc. п START: Added /LD for a local directory history list. п START: Added support for the (undocumented) Warp 4 CMD.EXE "DosSetting.xxx=yyy" environment variables to specify settings for DOS sessions. п SWITCH: This new command provides a C-like switch construct for batch files. SWITCH scans each CASE statement looking for a matching value; if it finds one it executes the block of code inside that CASE statement, and then jumps to the end of the switch block (ENDSWITCH). If no CASE statement matches, SWITCH will execute the code in the (optional) DEFAULT block. п TOUCH: This new command changes the date and/or time for a file or files. You can set a specified date and time or use the current system clock, and you can optionally change the last access / creation date and time fields on HPFS drives. п TREE: This new command displays a graphical directory tree using either line-drawing or ASCII characters. It can also optionally display file names, dates, times, and sizes. п UNALIAS: Added the /R switch to read a file of aliases to remove. п UNSET: Added the /R switch to read a file of variables to remove. 2.01 п FFIND: Added support for piping into FFIND. You can either specify CON for the filename, or if no filename is specified FFIND will detect whether STDIN is a pipe and use that. 2.01 п TOUCH: /T[acw] and /D[acw] now default to the current date and time. Previously when the "a", "c", or " w" was specified the date or time had to be specified also. 2.02 п CD and CDD: Added the /N switch to disable extended directory searches and the change directory popup window (intended primarily for use in batch files). ═══ 9.4. Variables and Functions ═══ What's New - Variables and Functions Added or updated the following internal variables (all variables listed are new unless otherwise noted): п _APMAC: Advanced Power Management AC line status. п _APMBATT: Advanced Power Management battery status. п _APMLIFE: Advanced Power Management remaining battery life. п _CPU: Now returns "686" for Pentium Pro. п _DOWI: Returns the current day of week as an integer (Sun = 1, Mon = 2, etc.). п _SELECTED: Returns the selected (highlighted) text. п _XPIXELS: Returns the physical screen horizontal size in pixels. п _YPIXELS: Returns the physical screen vertical size in pixels. 2.01 п _CMDPROC: Returns the name of the current command processor. Added or updated the following variable functions (all functions listed are new unless otherwise noted): п @CLIP[n]: Returns line n from the clipboard (base 0). п @CONVERT[input,output,value]: Converts a number from one base to another. п @DAY[date]: Returns the day for the specified date. п @DOW[date]: Returns the day of week for the specified date, as a string (Sun, Mon, etc.) п @DOWI[date]: Returns the day of week for the specified date, as an integer (Sun = 1, Mon = 2, etc.). п @DOY[date]: Returns the day of year for the specified date (136). п @EAREAD[filename,EAname]: Returns the specified text extended attribute for the file. п @EAWRITE[filename,EAname,value]: Writes the specified text extended attribute for the file. п @EVAL[expression]: Now supports user-definable decimal and thousands characters; see DecimalChar and ThousandsChar, or SETDOS /G for details. п @EXEC[command]: This function has been modified; if you preface the command with an '@', @EXEC will return an empty string rather than the result code of the command. п @EXECSTR[command]: Returns the first line written to STDOUT by the specified command. (This is intended to provide functionality similar to UNIX back-quoting.) п @EXPAND[filename[,attributes]]: Expands a wildcard filename and returns all of the matching filenames / directories on a single line. п @FILEDATE[filename[,acw]] / @FILETIME[filename[,acw]]: Added the optional second argument determines which date / time field to return on HPFS drives. п @FILESIZE[filename[,bkm[,a]]: Added the optional third argument a(llocated); if specified, the function returns the size actually used on disk, not the amount of data in the file. п @INSERT[n,string1,string2]: Inserts string1 into string2 starting at offset n. п @LEFT[n,string]: Returns the leftmost n characters of string. п @MONTH[date]: Return the month for the specified date. п @NUMERIC[string]: Now considers a leading decimal separator as a numeric character, provided the remainder of the string is numeric and does not contain additional decimal characters. п @REPLACE[string1,string2,text]: Replaces all occurrences of string1 in text with string2. п @RIGHT[n,string]: Returns the rightmost n characters of string. п @SEARCH[filename[,path]]: Now accepts an optional second argument for the path to search. п @SELECT[filename,top,left,bottom,right,title[,1]]: Has a new optional argument following the title. If it's set to 1, @SELECT will sort the list alphabetically. п @STRIP[chars,string]: Return string with the characters in chars removed. п @WILD[string1,string2]: Does a wildcard comparison on the two strings and returns 1 if they match; 0 if they don't. п @YEAR[date]: Return the year for the specified date. ═══ 9.5. Startup and Configuration ═══ What's New - Startup and Configuration Added or modified the following .INI directives (all are new unless otherwise noted): п CDDWinLeft, CDDWinTop, CDDWinWidth, CDDWinHeight. These directives set the position, and size of the popup window used for extended directory searches. п DescriptionName: This directive has a new capability: If set to "EA", Take Commandfor OS/2 will use extended attributes (specifically, the ".SUBJECT" EA) for file descriptions, rather than DESCRIPT.ION or another file. Depending on operating system configuration and cache behavior, this setting can cause a significant reduction in performance, but may be useful when working with other programs that manipulate Extended Attributes. п DuplicateBugs = Yes | NO: Tells the parser to duplicate certain CMD.EXE errors which may be important in solving rare compatibility problems. The only bug currently replicated by this command is the IF command. п FileCompletion = cmd1:ext1 ext2;cmd2 ...: Sets up command-specific filename completion. п FuzzyCD = 0 | 1 | 2 | 3: Enables or disables extended directory searches, and controls their behavior. п HistMove = Yes | NO: If set to Yes, a recalled line from the command history is moved to the end of the history list, and removed from its original location. п Include = filename: Includes the contents of the named file as if they had appeared at the location of the Include= directive in the current .INI file. п TreePath = Path: Specifies the location of JPSTREE.IDX (the extended directory search database; defaults to C:\). 2.02 п ListRowStart = 1 | 0: Specifies whether LIST and FFIND consider the first line in a file to be line "1" or line "0". The new default is "1". 2.02 п PathExt = NO | Yes: Determines whether Take Command uses standard extensions when searching the path, or uses the alternate extensions specified in the PATHEXT environment variable. 2.02 п UnixPaths= Yes | NO: Enables or disables the forward slash as a path separator in the command name (the first item on the command line). ═══ 9.6. Technical and Compatibility Enhancements ═══ What's New - Technical and Compatibility Enhancements п Replaced the old 4OS2DLL.DLL / TCOS2DLL.DLL with a single file for both 4OS2 and TCOS2, named JPOS2DLL.DLL. Also, JPOS2DLL is now loaded dynamically, so you can start the product without it if necessary (e.g. from a floppy boot). п Added support for inheritance (and shell levels) when invoking one copy of Take Command for OS/2 from another. п Worked around an OS/2 problem that prevented %_CPU from detecting anything higher than a 486. п Improved support for drive and file sizes over 4GB. п Added support for piping from VIO and DOS programs to secondary Take Command shells. п TYPE NUL now "works" (i.e. it generates no output), for compatibility with batch files which use TYPE NUL > file to generate a 0-byte file. п Added debugging options which allow you to view the command "tail" passed to Take Command for OS/2, and to "tag" error messages with the product name. See the Debug directive in TCMDOS2.INI for additional details. 2.01 п DESCRIBE: Worked around a Novell Netware bug which caused trouble with descriptions with trailing drive specs (i.e., "file from drive D:"). 2.02 п @UNIQUE: Worked around an OS/2 bug that caused trouble if @UNIQUE was called repeatedly on a fast machine. ═══ 9.7. Bugs Fixed ═══ What's New - Bugs Fixed п Piping the output of a batch file which also contains a pipe will no longer cause problems. п ACTIVATE: The CLOSE option now works properly. п DESCRIBE: Fixed a problem with quoted long filenames with paths. п INPUT: Fixed a problem with /P not displaying *'s. п RENAME: Now works properly when renaming quoted long filenames with embedded wildcards. п Fixed a problem with invalid drive change requests -- commands like "1:" would crash TCOS2. п Quoted long filenames can now be used in the .INI file. п Fixed a problem which locked the STARTUP.CMD file when loading SHRALIAS from STARTUP.CMD. п The file find dialog now adds quotes to long filenames when doing a file-only search. This should allow you to double-click the name successfully. п @FILESEEKL[] now always returns to the start of the file before seeking. 2.01 п Enabled the NormalPopupKey directive in the .INI file. Previously this directive was documented but was only available under its old name (NormalHWinKey). 2.01 п Modified popup windows to avoid the situation where the bottom half of the window is empty when the initially selected line is at the end of the list. 2.01 п DIR: Fixed several problems, including: * /4/Z did not display file sizes ending in ".9M" (1.9M, 2.9M, etc.) correctly. * /J did not display the descriptions. * /OGU was ignoring the 'U'; it will now display the files unsorted after the directory names. * "*.*" was incorrectly being appended to file specifications that ended in a question mark. 2.01 п DO: Fixed a problem with "LEAVE" not closing the file handle on a "do var in @filename", and a similar problem with exiting the batch file with QUIT or CANCEL from inside a DO loop which had a file open. 2.01 п DEL: Fixed a problem with /W and 0-byte files. 2.01 п DRAWVLINE: Fixed a problem with connecting to a horizontal line on the right side. 2.01 п ECHOS: Fixed a problem with aborting an ECHOS with a Ctrl-C while in a DO or FOR loop. 2.01 п FOR: Fixed a problem with combining /A:xx and /R, and another problem with combining /H and /R. 2.01 п SWITCH: Fixed occasional problems with nested SWITCHes. 2.01 п @EVAL: Fixed a bug with maximum-length argument strings. 2.01 п @FILEWRITEB[n,length,string]: No longer truncates on a write if the file was opened in binary mode. 2.01 п @WORDS[["xxx"],string]: Fixed a problem if the line began with a -. 2.02 п Extended wildcards are now supported inside file exclusion ranges. (In previous versions the documentation indicated that this support was available, but it was not.) 2.02 п Fixed a problem which prevented filename completion from returning hidden and system files when these files were enabled in the FILECOMPLETION variable. Note that the default filename completion search does not display hidden and system files, but now if you use FILECOMPLETION to enable those files for a specific command, they will be shown as you cycle through files with . 2.02 п Improved handling of commands using both * (disable alias) and @ (don't add to command history) at the start. 2.02 п @FILES: Fixed a problem which caused this function to leave a file handle open, which could cause subsequent "access denied" errors. 2.02 п @REPLACE: Fixed a problem with replacing commas. 2.02 п @SELECT: Fixed a problem with files over 64K. 2.02 п CDD: Fixed a problem if TREE was disabled (CDD /S uses TREE to build the directory index). 2.02 п FFIND: Fixed a problem with /C and bracketed wildcards. 2.02 п LIST: Fixed a problem with highlighting the offsets as well as the actual found text when in hex mode. 2.02 п SWITCH: Fixed minor problems with nested SWITCH statements. 2.02 п TEE: Fixed a problem with TEE'ing to CLIP:. 2.02 п TOUCH: Fixed a problem with failing to display a usage message when there were no parameters after a /C, and another problem with properly detecting invalid times. 2.02 п UNALIAS: Fixed a problem with /R. 2.02b п Fixed a problem with piping to external applications. 2.02b п Fixed a problem which occasionally caused spurious "internal error" crashes. 2.02b п @EXEC: Fixed a problem which prevented the command from being executed at all if it was preceded with an @. 2.02b п @MAKEAGE: Fixed a problem which caused 2-digit dates to be interpreted based on 1980 rather than 2000 (e.g. 01-01-02 was taken to mean 1-Jan-1982 rather than the correct value, 1-Jan-2000). 2.03 п Fixed a problem which caused a crash with extremely large extended directory search databases. 2.03 п Fixed a problem which caused a crash when multiple Take Command windows were running 'TTY' applications simultaneously. 2.03 п CHCP: Fixed a problem which caused a crash when changing the code page under Warp FixPak 13 and above. 2.03 п FFIND: Fixed a problem with wildcards. ═══ 10. Reference Information ═══ This section contains information that you'll need throughout Take Command. It is divided into six sections: Product Compatibility discusses compatiblity between our products: 4DOS, 4OS2, 4NT, Take Command for OS/2, Take Command/16 for Windows 3.x and Windows for Workgroups, and Take Command/32 for Windows 95 and Windows NT. If you use two or more of our products, you'll want to read this section. File Systems and File Name Conventions explains the file systems that are supported by OS/2 and Take Command for OS/2, the naming conventions used by each, and related issues. Miscellaneous Reference Information discusses a number of conventions and other topics that are necessary to get the most out of Take Command. Reference Tables includes tables of ASCII codes and of the codes produced when you press various keys and key combinations on the keyboard. Also contains a list of ANSI commands. The Glossary is a list of terms and definitions. If you come across terms in the online help that you don't understand, they are probably defined here. Copyright and Version contains the copyright information and version number for this online help file. ═══ 10.1. Product Compatibility ═══ This topic covers compatiblity between our products: 4DOS, 4OS2, 4NT, Take Command for OS/2, Take Command/16 for Windows 3.x and Windows for Workgroups, and Take Command/32 for Windows 95 and Windows NT. The topic is divided into 3 separate issues: Special Character Compatibility Scrolling and History Keystrokes Using 4OS2 and 4DOS Batch Files and Aliases ═══ 10.1.1. Special Character Compatibility ═══ Take Command is highly compatible with 4DOS, 4OS2, and 4NT. However, there are some minor differences between our products. These differences are caused by the different requirements of each operating system and by our design goal of maintaining compatibility between each product and the system's default command processor. We discuss the differences between our products in the online help as part of the description of each feature and command. Most of the differences are minor: different command line lengths, a few different options in some commands, and some commands that only make sense in one or two products. If you use two or more of our products, or if you want to share aliases and batch files with users of different products, you need to be aware of the differences in three important characters: the Command Separator, the Escape Character, and the Parameter Character. The default values of each of these characters in each product is shown in the following table: Product Separator Escape Parameter Take Command/16, ^  & 4DOS Take Command/32, & ^ $ Take Command for OS/2, 4NT, 4OS2 (In this section, an up-arrow [] is used for the ASCII Ctrl-X character, numeric value 24. The appearance of control characters depends on the font you use. In many fonts Ctrl-X is displayed as a "block" or other non-descript character, but the Terminal font used by default in Take Command typically displays Ctrl-X as an up-arrow.) In your batch files and aliases, and even at the command line, you can smooth over these differences in three ways:  Select a consistent set of characters on the Options 1 page of the configuration dialogs, TCMDOS2.INI file directives, or with the SETDOS command. For example, to set the Take Command/16 characters to match the defaults in Take Command/32, 4OS2, and 4NT, use these lines in TCMD.INI: CommandSep = & EscapeChar = ^ ParameterChar = $  Use internal variables that contain the current special character, rather than using the character itself. For example, this command: if "%1" == "" (echo Argument missing! ^ quit) will only work if the command separator is a caret. However, this version works regardless of the current command separator: if "%1" == "" (echo Argument missing! %+ quit)  In a batch file, use the SETLOCAL command to save the command separator, escape character, and parameter character when the batch file starts. Then use SETDOS as described below to select the characters you want to use within the batch file. Use an ENDLOCAL command at the end of the batch file to restore the previous settings. You can also use the SETDOS command to change special characters on the command line. However, when setting new special character values on the command line you must take into account the possibility that one of your new values will have a current meaning that causes problems with the setting. For example, this command: [c:\] setdos /e^ would not set the escape character to a caret [^] in Take Command/16 if the standard Take Command/16 special characters were currently in effect. The ^ would be seen as a command separator, and would terminate the SETDOS command before the escape character was set. To work around this, use the escape character variable %= before each setting to ensure that the following character is not treated with any special meaning. For example, the following sequence of commands in a batch file will always set the special characters correctly to their standard Take Command/32 and Take Command for OS/2 values, no matter what their current setting, and will restore them when the batch file is done: setlocal setdos /c%=& /e%=^ /p%=$ ..... endlocal A similar sequence can be used to select the standard Take Command/16 characters, regardless of the current settings: setlocal setdos /c%=^ /e%=н /p%=& ..... endlocal ═══ 10.1.2. Scrolling and History Keystrokes ═══ In order to support the scrollback buffer, some Take Command keystrokes are different from what you may be used to in 4DOS, 4OS2, and 4NT. The differences are: 4DOS, 4OS2, 4NT Take Command Command Line: Previous command Up [] Ctrl-Up Next command Down [] Ctrl-Down Open history window PgUp Ctrl-PgUp Directory history Ctrl-PgUp F6 Screen Scrollback: Up one line N/A Up [] Down one line N/A Down [] Up one page N/A PgUp Down one page N/A PgDn If you prefer to reverse this arrangement and use the arrow and PgUp keys to access the command history without having to press Ctrl (as in 4OS2 and 4DOS), see the SwapScrollKeys .INI file directive, or the Command Line 1 page of the configuration notebook. SwapScrollKeys switches the keystroke mapping so that the , , and PgUp keys manipulate the command history, and Ctrl-, Ctrl-, Ctrl-PgUp, and Ctrl-PgDn are used to control the scrollback buffer. (SwapScrollKeys does not affect the use of F6 for the directory history). You can also change the way any individual key operates with the corresponding key mapping directive in the TCMDOS2.INI file. The directives associated with the history and scrolling keys are: NextHistory ScrollUp PrevHistory ScrollDown HistWinOpen ScrollPageUp DirWinOpen ScrollPageDown ═══ 10.1.3. Using 4OS2 and 4DOS Batch Files and Aliases ═══ Take Command for OS/2, 4OS2, and 4DOS aliases are separate and independent; Take Command does not automatically "inherit" aliases from a previously loaded copy of 4OS2 or 4DOS, and it cannot pass aliases on to a copy of 4OS2 or 4DOS started from the Take Command prompt. However, you can load aliases from your Take Command startup batch file. These can be the same aliases you use in 4OS2 or 4DOS, or a set that is just for Take Command. While many of your 4OS2 aliases will work well under Take Command, you'll probably want to create a separate set of Take Command aliases. This will allow you to account for the differences in running OS/2 and DOS applications, and to create new aliases that take advantage of Take Command features that are unavailable in 4OS2 and 4DOS. If you want to write aliases or batch files that are used in Take Command, 4OS2, and 4DOS, but that behave differently in each environment, use the _DOS variable to make the distinction. For example, this batch file fragment uses the INPUT command to accept a string if it is run under 4DOS, but uses the OS/2-style QUERYBOX if it is run under Take Command: iff "%_dos" == "OS2PM" then querybox "Enter your name: " %%name else input "Enter your name: " %%name endiff Aliases and batch files which simply manipulate files or use other internal commands should work with little or no change under Take Command. However, as a general rule, you should test any batch file developed for 4OS2, 4DOS, or CMD.EXE before assuming it will do exactly what you want under Take Command. Pay particular attention to batch files which run complex sequences of external programs. If you use aliases or batch files to perform a sequence which mixes internal commands and DOS applications, the sequence may not work the way you expect under Take Command. For example, suppose you have an alias that changes the screen color, starts a DOS application, and then resets the color again. If the DOS application is started in a separate window the color changes will not affect it -- a contingency you probably didn't have to consider when you wrote the batch file. Similarly, if you run a sequence of several DOS applications which depend on each others' results (for example, through the use of error levels), they may not run the same way under Take Command that they do under 4DOS, 4OS2, or CMD.EXE. For example, if one DOS application runs in its own window and another runs using Take Command's named pipes, error levels will not be passed between the applications and your batch file or alias won't run the way you expect. You may also find that you want to take advantage of some of the new features of Take Command to improve your batch files. For example, the START command offers additional flexibility in starting applications. MSGBOX and QUERYBOX can be used to create OS/2- style input prompts, and KEYSTACK and ACTIVATE will help control your OS/2 applications. Once you get used to these enhancements and minor differences you'll find that you can use Take Command to manage your system using the same techniques and features you are already familiar with from your experience with 4OS2, 4DOS, or CMD.EXE. ═══ 10.2. File Systems and File Name Conventions ═══ You may have dozens, hundreds, or thousands of files stored on your computer's disks. Your operating system is responsible for managing all of these files. In order to do so, it uses a unique name to locate each file in much the same way that the post office assigns a unique address to every residence. The unique name of any file is composed of a drive letter, a directory path, and a filename. Each of these parts of the file's name is case insensitive; you can mix upper and lower case letters in any way you wish. OS/2 supports two different files systems: the traditional FAT file system, used by all versions of DOS prior to Windows 95, and OS/2's High Performance File System (HPFS), as well as installable file systems such as those used by CD-ROMs and some networks. Take Command includes support for all file systems that are accessible to OS/2. This section presents an overview of OS/2-compatible file systems, including naming conventions used by each. The following sub-topics are included in this section: Drives and Volumes File Systems Network File Systems including information about using UNC (Universal Naming Convention) names over a network. Directories and Subdirectories File Names File Attributes and Time Stamps OS/2 Extended Attributes ═══ 10.2.1. Drives and Volumes ═══ A drive letter designates which drive contains the file. In a file's full name, the drive letter is followed by a colon. Drive letters A: and B: are normally reserved for the floppy disk drives. Normally, drive C: is the first (or only) hard disk drive. Most current operating systems can divide a large hard disk into multiple logical drives or volumes that are usually called C:, D:, E:, etc. Network systems (LANs) give additional drive letters to sections of the network file server drives. Most recent systems also include a CD-ROM drive. The CD-ROM is also assigned a drive letter (or several letters, for CD-ROM changers), typically using letters beyond that used by the last hard disk in the system, but before any network drives. Some systems may have "RAM disks" (sometimes called "virtual disks"), which are areas of memory set aside by software (a "RAM disk driver") for use as fast but temporary storage. Like CD-ROM drives, RAM disks are usually assigned drive letters beyond the last hard disk in the system, but before network drives. For example, on a system with a large hard disk you might have A: and B: as floppy drives, C:, D:, and E: as parts of the hard disk, F: as a CD-ROM drive, G: as a RAM disk, and H: and I: as network drives. ═══ 10.2.2. File Systems ═══ Each disk volume is organized according to a file system. The file system determines how files are named and how they are organized on the disk. As hard disk technology and operating systems have evolved, new file systems have been invented to support longer file names, larger drives, and higher disk performance. Several different and incompatible schemes have evolved. Which file systems you can use depend on which operating system you are using and how the operating system and your hard disk are configured. Take Command for OS/2, and OS/2 itself, supports two standard file systems: FAT (and VFAT) and HPFS. See File Names for details on the rules for naming files under each file system. The FAT File System is the traditional file system used by all versions of DOS and by Windows 3.x. Its name comes from the File Allocation Table DOS uses to keep track of the space allocated to each file. The VFAT File System is an extension of the FAT file system available in Windows 95 and Windows NT. This system maintains additional information about files on FAT drives, including long filenames (LFNs). Other operating systems such as OS/2 and earlier versions of DOS can access files on VFAT drives, but will not be able to access long filenames or other information which is added by the VFAT file system. The FAT32 File System is an additional extension to the VFAT file system. It is only available in Windows 95 OEM Service Release 2 ("OEMSR2") and later versions. It is similar to the VFAT file system, but supports larger disk drives. It is incompatible with OS/2 and earlier versions of DOS, and can only be used under Windows 95 OEMSR2. The High Performance File System or HPFS is a file system provided with all versions of OS/2. It supports long file names, and offers higher performance and better support for large drives than the FAT or VFAT system. It also supports extended attributes to retain additional information about your files. DOS and Windows sessions running under OS/2 can access files on HPFS drives if the files have short, FAT-compatible names. Other operating systems (DOS, Windows 95, and Windows NT 4.0 and above) can not access files on HPFS drives. Additional file systems may be installed under some operating systems to support CD-ROM or network drives. In particular, OS/2 supports installable file systems, which are installed with the IFS= directive in the OS/2 CONFIG.SYS file. This facility is used to add support for HPFS, CD-ROM, and network drives to the base OS/2 operating system. The file system type (FAT / VFAT or HPFS) is determined when a hard disk volume is formatted and applies to the entire volume. For example, you might have a 2 GB hard disk divided into four 500 MB volumes, with the first three volumes (C:, D:, and E:) formatted for the FAT or VFAT file system, and the fourth formatted for HPFS. Take Command for OS/2 supports any standard file system installed under OS/2. If your operating system can access files on a particular drive, then your version of Take Command will be able to access those files as well. ═══ 10.2.3. Network File Systems ═══ A network file system allows you to access files stored on another computer on a network, rather than on your own system. Take Command for OS/2 supports all network file systems which are compatible with OS/2. File and directory names for network file systems depend on both the server software running on the system that has the files on it, and the client software running on your computer to connect it to the network. However, they usually follow the rules described here. Most network software "maps" unused drive letters on your system to specific locations on the network, and you can then treat the drive as if it were physically part of your local computer. Some networks also support the Universal Naming Convention, which provides a common method for accessing files on a network drive without using a "mapped" drive letter. Names specified this way are called UNC names. They typically appear as \\server\volume\path\filename, where server is the name of the network server where the files reside, volume is the name of a disk volume on that server, and the path\filename portion is a directory name and file name which follow the conventions described under Directories and Subdirectories. Take Command supports UNC filenames, and also allows you to use UNC directory names when changing directories (see Directory Navigation for more details). When you use a network file system, remember that the naming conventions for files on the network may not match those on your local system. For example, your local system may support long filenames while the network server or client software does not, or vice versa. Take Command will usually handle whatever naming conventions are supported by your network software, as long as the network software accurately reports the types of names it can handle. In some cases, Take Command (particularly Take Command/16) may not be able to report correct statistics on network drives (such as the number of bytes free on a drive). This is usually because the network file system does not provide complete or accurate information. ═══ 10.2.4.  Directories and Subdirectories ═══ A file system is a method of organizing all of the files on an entire disk or hard disk volume. Directories or folders are used to divide the files on a disk into logical groups that are easy to work with. Their purpose is similar to the use of file drawers to contain groups of hanging folders, hanging folders to contain smaller manila folders, and so on. (The terms directory and folder are nearly synoymous -- we use directory throughout this manual.) Every drive has a root or base directory, and many have one or more subdirectories. Subdirectories can also have subdirectories, extending in a branching tree structure from the root directory. The collection of all directories on a drive is often called the directory tree, and a portion of the tree is sometimes called a subtree. The terms directory and subdirectory are typically used interchangeably to mean a single subdirectory within this tree structure. Subdirectory names follow the same naming rules as files in each file system. However, under DOS it is best to use a name of 8 characters or less, without an extension, when naming subdirectories, because some application programs do not properly handle subdirectory names that have an extension. The drive and subdirectory portion of a file's name are collectively called the file's path. For example, the file name C:\DIR1\DIR2\MYFILE.DAT says to look for the file MYFILE.DAT in the subdirectory DIR2 which is part of the subdirectory DIR1 which is on drive C. The path for MYFILE.DAT is C:\DIR1\DIR2. The backslashes between subdirectory names are required. The total length of a file's path may not exceed 64 characters on FAT volumes under OS/2 (this limit excludes the file name and extension, but includes the drive letter and colon). On HPFS volumes, the path and file name must each be 255 characters or less in length, and in addition the total length of the path and file name together cannot exceed 260 characters. The operating system and Take Command remember both a current or default drive for your system as a whole, and a current or default directory for every drive in your system. Whenever a program tries to create or access a file without specifying the file's path, the operating system uses the current drive (if no other drive is specified) and the current directory (if no other directory path is specified). The root directory is named using the drive letter and a single backslash. For example, D:\ refers to the root directory of drive D:. Using a drive letter with no directory name at all refers to the current directory on the specified drive. For example, E:TCMD.DOC refers to the file TCMD.DOC in the current directory on drive E:, whereas E:\TCMD.DOC refers to the file TCMD.DOC in the root directory on drive E:. There are also two special subdirectory names that are useful in many situations: a single period by itself [.] means "the current default directory." Two periods together [..] means "the directory which contains the current default directory" (often referred to as the parent directory). These special names can be used wherever a full directory name can be used. Take Command allows you to use additional periods to specify directories further "up" the tree (see Extended Parent Directory Names). ═══ 10.2.5. File Names ═══ Each file has a filename. Under the FAT file system, the filename consists of a base name of 1 to 8 characters plus an optional extension composed of a period plus 1 to 3 more characters. Traditional FAT filenames with an 8- character name and a 3-character extension are sometimes referred to as short filenames (SFNs) to distinguish them from long filenames (LFNs). You can use alphabetic and numeric characters plus the punctuation marks ! # $ % & ' ( ) - @ ^ _ ` { } and ~ in both the base name and the extension of a FAT filename. Because the exclamation point [!], percent sign [%], caret [^], at sign [@], parentheses [()], ampersand [&], and back-quote [`] also have other meanings to Take Command, it is best to avoid using them in filenames. The HPFS file systems allows file names with a maximum of 255 characters, including spaces and other characters that are not allowed in a FAT system file name, but excluding some punctuation characters which are allowed in FAT file names. See your OS/2 documentation for details on the characters allowed. If you use file names which contain semicolons [;], see page Error! Bookmark not defined. for details on avoiding problems with interpretation of those file names under Take Command. HPFS file names are stored and displayed exactly as you entered them, and are not automatically shifted to upper or lower case. For example, you could create a file called MYFILE, myfile, or MyFile, and each name would be stored in the directory just as you entered it. However, case is ignored when looking for filenames, so you cannot have two files whose names differ only in case (i.e., the three names given above would all refer to the same file). This behavior is sometimes described as "case-retentive but not case-sensitive" because the case information is retained, but does not affect access to the files. Files stored on HPFS volumes often have "FAT-compatible" names: names which contain only those characters legal on a FAT volume, and which meet the 8-character name / 3-character extension limits. Programs which cannot handle long names (for example, DOS programs running under OS/2) generally can access files by using FAT-compatible names. If an HPFS file name includes spaces or other characters that would not be allowed in a FAT name, you must place double quotes around the name. For example, suppose you have a file named LET3 on a FAT volume, and you want to copy it to the LETTERS directory on drive F:, an HPFS partition, and give it the name Letter To Sara. To do so, use either of these commands: [c:\wp] copy let3 f:\LETTERS\"Letter To Sara" [c:\wp] copy let3 "f:\LETTERS\Letter To Sara" HPFS does not explicitly define an "extension" for file names which are not FAT-compatible. However, by convention, all characters after the last period in the file name are treated as the extension. For example, the file name "Letter to Sara" has no extension, whereas the name "Letter.to.Sara" has the extension Sara. You may occasionally encounter filenames which are not displayed the way you expect if you have used characters from outside the U.S. English character set in the name. These are generally due to problems in the way your operating system translates characters between the OEM and ANSI character sets. Correcting the problem may require experimentation with fonts, character sets, and code pages, and occasionally some such problems may not be readily correctable within Take Command. ═══ 10.2.6. File Attributes and Time Stamps ═══ Each file also has attributes and one or more time stamps. Attributes define characteristics of the file which may be useful to the operating system, to you, or to an application program. Time stamps can record when the file was created, last modified, or last accessed. Most Take Command file processing commands allow you to select files for processing based on their attributes and/or time stamp(s). Each file on your system has four standard attributes. Every time a program modifies a file, the operating system sets the Archive attribute, which signals that the file has been modified since it was last backed up. This attribute can be used by Take Command to determine which files to COPY or MOVE, and by backup programs to determine which files to back up. When the Read-only attribute is set, the file can't be changed or erased accidentally; this can be used to help protect important files from damage. The Hidden and System attributes prevent the file from appearing in normal directory listings. (Two additional attributes, Directory and Volume label, are also available. These attributes are controlled by the operating system, and are not modified directly by Take Command.) Attributes can be set and viewed with the ATTRIB command. The DIR command also has options to select filenames to view based on their attributes, to view the attributes themselves, and to view information about normally "invisible" hidden and system files. When a file is created, and every time it is modified, the operating system records the system time and date in a time stamp in the file's directory entry. Several Take Command variable functions and commands, and many backup and utility programs, use this time stamp to determine the relative ages of files. Files on HPFS volumes have three sets of time and date stamps. The operating system records when each file was created, when it was last written or modified, and when it was last accessed. The "last write" time stamp matches the single time stamp used on traditional FAT volumes. Several Take Command variable functions and commands let you specify which set of time and date stamps you want to view or work with on HPFS volumes. These commands and functions use the letter "c" to refer to the creation time stamp, "w" for the last write time stamp, and "a" for the last access time stamp. ═══ 10.2.7. OS/2 Extended Attributes ═══ The FAT and VFAT file systems allow the limited set of attributes for files described in the previous section. OS/2 supports additional information about files called Extended Attributes or EAs. The Extended Attributes for a file provide additional information which is not part of the file's actual contents. This information might include the icon to be displayed for the file on the OS/2 desktop, or the type of data contained in the file. OS/2 supports Extended Attributes on both FAT and HPFS (High Performance File System) partitions. EAs for the files on a FAT partition are stored in the file "EA DATA. SF" in the partition's root directory. Like CMD.EXE, Take Command for OS/2 preserves a file's EAs when copying or moving the file, and OS/2 makes the appropriate adjustments to EAs when a file is deleted or renamed. When copying or moving a file from a FAT to an HPFS volume, Take Command uses uses the file's .LONGNAME EA, if available, for the HPFS filename. Conversely, when copying or moving a file from an HPFS volume to a FAT volume, Take Command will set the .LONGNAME EA to the original HPFS name. See the COPY and MOVE commands for additional details. If you boot DOS or any version of Windows, then delete or otherwise manipulate files that have Extended Attributes, you can face unexpected problems when you next boot under OS/2, because the EAs and directories will no longer be synchronized. If you must manipulate files with Extended Attributes during a DOS boot, or when you boot a "specific version of DOS" (not a standard DOS seesion) from OS/2, make sure you run OS/2's CHKDSK program to clean up any "orphaned" EAs. For more information on Extended Attributes, see your OS/2 documentation. ═══ 10.3. Miscellaneous Reference Information ═══ This section contains miscellaneous information that is useful throughout Take Command: at the command line, in internal commands, in aliases, and in batch files. Included here is information about Colors and Color Names Keys and Key Names Popup Windows Internal and External Commands Executable Files and File Searches ═══ 10.3.1. Colors and Color Names ═══ You can use color names in several of the directives in the TCMDOS2.INI file and in many commands. The general form of a color name is: [BRIght] fg ON [BRIght] bg where fg is the foreground or text color, and bg is the background color. The available colors are: Black Blue Green Red Magenta Cyan Yellow White Color names and the word BRIght may be shortened to the first 3 letters. You can also specify colors by number instead of by name. The numbers are most useful in potentially long .INI file directives like ColorDIR. Take Command recognizes these color numbers: 0 - Black 8 - Gray (bright black) 1 - Blue 9 - Bright blue 2 - Green 10 - Bright green 3 - Cyan 11 - Bright cyan 4 - Red 12 - Bright red 5 - Magenta 13 - Bright magenta 6 - Yellow 14 - Bright yellow 7 - White 15 - Bright white Use one number to substitute for the [BRIght] fg portion of the color name, and a second to substitute for the [BRIght] bg portion. For example, instead of bright cyan on blue you could use 11 on 1 to save space in a ColorDir specification. The blinking text and border colors that are available with 4DOS can not be used with Take Command. This restriction is due to limitations inherent in OS/2 and in graphical displays. ═══ 10.3.2. Keys and Key Names ═══ Key names are used to define keystroke aliases, in several TCMDOS2.INI directives, and with the KEYSTACK command. The format of a key name is the same in all 3 uses: [Prefix-]Keyname The key prefix can be left out, or it can be one of the following : Alt followed by A - Z, 0 - 9, F1 - F12, or Bksp Ctrl followed by A - Z, F1 - F12, Tab, Bksp, Enter, Left, Right, Home, End, PgUp, PgDn, Ins, or Del Shift followed by F1 - F12 or Tab. The possible key names are: A - Z Enter PgDn 0 - 9 Up Home F1 - F Down End Esc Left Ins Bksp Right Del Tab PgUp All key names must be spelled as shown. Alphabetic keys can be specified in upper-case or lower-case. You cannot specify a punctuation key. The prefix and key name must be separated by a dash [-]. For example: Ctrl-F10 This is okay Ctrl F10 The space will cause an error If you prefer, you can use a numeric value instead of a key name. Use the ASCII code for an ASCII, extended ASCII, or control character. Use the scan code preceded by an at sign [@] for extended key codes like F1 or the cursor keys. For example, use 13 for Enter, or @59 for F1. In general, you will find it easier to use the names described above rather than key numbers. Some keys are intercepted by OS/2 and are not passed on to Take Command. For example, Ctrl-S pauses screen output temporarily, and Alt-Tab switches to another window. Keys which are intercepted by OS/2 (including menu accelerators, i.e. Alt plus another key) generally cannot be assigned to aliases or with key mapping directives, because Take Command never receives these keystrokes and therefore cannot act on them. ═══ 10.3.3. Popup Windows ═══ Several features of Take Command display popup windows. A popup window may be used to display filenames, recently-executed commands, recently-used directories, the results of an extended directory search, or a list created by the SELECT command or the @SELECT internal function. Popup windows always display a list of choices and a cursor bar. You can move the cursor bar inside the window until you find the choice that you wish to make, then press the Enter key to select that item. Navigation inside any popup window follows the conventions described below. Additional information on each specific type of popup window is provided when that window is introduced in the online help. You can control the color, position and size of most popup windows from the Command Line 2 page of the configuration dialogs, or with the PopupWinLeft, PopupWinTop, PopupWinWidth, and PopupWinHeight directives in the .INI file A few popup windows (e.g., the extended directory search window) have their own specific .INI directives, and corresponding separate choices in the configuration dialogs. You can also change the keys used in most popup windows with key mapping directives in TCMDOS2.INI. Once a window is open, you can use these navigation keys to find the selection you wish to make: Up Arrow Move the selection bar up one line. Down Arrow Move the selection bar one line. Left Arrow Scroll the display left 1 column, if it is a scrolling display (i.e. if it has a horizontal scrollbar). Right Arrow Scroll the display right 1 column, if it is a scrolling display (i.e. if it has a horizontal scrollbar). PgUp Scroll the display up one page. PgDn Scroll the display down one page. Ctrl-PgUp Go to the beginning of the list. or Home Ctrl-PgDn Go to the end of the list. or End Esc Close the window without making a selection. Enter Select the current item and close the window. In addition to scrolling through a popup window, you can search the list using character matching. If you press a character, the cursor bar will move to the next entry that begins with that character. If you type multiple characters, the cursor will move to the entry that begins with the character string entered to that point (you can enter a search string up to 32 characters long). If no entry matches the character or string that you have typed, Take Command beeps and does not move the cursor bar. To reset the search string, press Backspace. You can change the keys used in popup windows with key mapping directives in the TCMDOS2.INI file. ═══ 10.3.4. Internal and External Commands ═══ Whenever you type something at the Take Command prompt and press the Enter key, you have given a command, and Take Command must figure out how to execute it. If you understand the general process that Take Command uses, you will be able to make the best use of it and its commands. Take Command begins by dividing the line you typed into a command name and a command tail. The command name is the first word in the command; the tail is everything that follows the command name. For example, in this command line: dir *.txt /2/p/v the command name is "dir", and the command tail is " *.txt /2/p/v." If the command name is not an alias, Take Command tries to find the name in its list of internal commands. An internal command is one that Take Command can perform itself, without running another program. DIR and COPY are examples of internal commands. If the command name is not found in Take Command's list of internal commands, it assumes that it must find and execute an external command. This means that it must load and run a separate program, either an executable program or a batch file. OS/2 and DOS are shipped with a number of external utility programs (such as FORMAT and DISKCOPY), and any program or application you install on your system becomes a new external command. The advantage of internal commands is that they run almost instantly. When you type an internal command, Take Command interprets the command line and carries out the necessary activities without having to look for, load, and run another program. The advantage of external commands is that they can be large, varied, and complex without taking space inside Take Command. External commands can also be renamed or replaced easily. If you want to rename the external DOS command XCOPY to MYCOPY, for example, all you need to do is find the file called XCOPY.EXE in your DOS directory and change its name to MYCOPY.EXE. If you want to replace XCOPY with a more efficient program of the same name, you can do so. Take Command adds this flexibility to internal commands. You can rename or replace any internal command by using an alias, and you can enable or disable internal commands whenever you wish (see SETDOS /I). ═══ 10.3.5. Executable Files and File Searches ═══ When Take Command knows that it is supposed to run an external command, it tries to find an executable file whose name matches the command name. (Executable files are typically those with a .COM or .EXE extension, or with a .PIF extension under Windows.) It runs the executable file if it finds one. If Take Command cannot find an executable program to run, it next looks for a batch file (a file with one or more commands in it) whose name matches the command name. Take Command looks first for a .BTM file, then for a .CMD file, and then for a .BAT file, and finally for a .REX file. See .BAT, .CMD, and .BTM Files for more information on these different types of batch files. If the command processor finds such a file, it then reads each line in the file as a new command. If the search for a batch file fails, Take Command checks to see if the command name matches the name of a file with an extension that is associated with a specific application (for example, if you have associated .DOC with your editor or word processor, and type the name of a .DOC file). If a match is found, Take Command runs the program you specified when the association was defined. (Executable extensions are a Take Command feature used to associate file extensions with the specific program that processes a particular type of file). Take Command first searches for an executable program, a batch file, and a file with an executable extension in the current directory. If that search fails, it repeats its search in every directory in your search path. The search path is a list of directories that Take Command (and some applications) search for executable files. For example, if you wanted Take Command to search the root directory of the C: drive, the \WINUTIL subdirectory on the C: drive, and the \UTIL directory on the D: drive for executable files, your search path would look like this: PATH=C:\;C:\WINUTIL;D:\UTIL Notice that the directory names in the search path are separated by semicolons. You can create or view the search path with the PATH command. You can use the ESET command to edit the path. Many programs also use the search path to find their own files. The search path is stored in the environment with the name PATH. Remember, Take Command always looks for an executable file or a file with an executable extension first in the current subdirectory and then in each directory in the search path. (You can change the search order so the current directory is not searched first; see the PATH command for details.) If you include an extension as part of the command name, Take Command only searches for a file with that extension. Similarly, if you include a path as part of the command name, Take Command will look only in the directory you specified, and ignore the usual search of the current directory and the PATH. The following table sums up the possible search options (the term "standard search" refers to the search of the current directory and each directory in the search path): Command Take Command Search Sequence WP Standard search for any executable file whose base name is WP. WP.EXE Standard search for WP.EXE; will not find files with other extensions. C:\WP7\WP Looks in the C:\WP7 directory for any executable file whose base name is WP. Does not check the standard search directories. C:\WP7\WP.EXE Looks only for the file C:\WP7\WP.EXE. LAB.DOC Standard search for LAB.DOC, if .DOC is defined as a Take Command executable extension. Runs the associated application if the file is found. C:\LI\LAB.DOC Looks only for the file C:\LI\LAB.DOC, and only if .DOC is defined as a Take Command executable extension. Runs the associated application if the file is found. If Take Command cannot find an executable file, batch program, or a file with an executable extension in the current directory or any directory in the search path, it looks for an alias called UNKNOWN_CMD (see ALIAS for details). If you have defined an alias with that name, it is executed (this allows you to control error handling for unknown commands). Otherwise, Take Command displays an "Unknown command" error message and waits for your next instruction. ═══ 10.4. Reference Tables ═══ The reference tables in this section are based on U.S. English conventions. Your system may differ if it is configured for a different country or language. See your operating system documentation for more information about country and language support. To represent the text you type, computers must translate each letter to and from a number. The code used by all PC-compatible computers for this translation is called ASCII. Function keys, cursor keys, and Alt keys generate scan codes indicating which key was pressed, but not ASCII codes. The tables in this section cover both kinds of codes. For more information, see: ASCII Table Key Codes and Scan Codes Table Key Codes and Scan Codes Explanation ANSI Reference ═══ 10.4.1. ASCII Table ═══ Control Characters Dec Hex Chr Nam Ctl │ Dec Hex Chr Nam Ctl --- --- --- --- --- │ --- --- --- --- --- 000 00 NUL ^@ │ 016 10  DLE ^P 001 01  SOH ^A │ 017 11  DC1 ^Q 002 02  STX ^B │ 018 12  DC2 ^R 003 03  ETX ^C │ 019 13  DC3 ^S 004 04  EOT ^D │ 020 14  DC4 ^T 005 05  ENQ ^E │ 021 15  NAK ^U 006 06  ACK ^F │ 022 16  SYN ^V 007 07 BEL ^G │ 023 17  ETB ^W 008 08  BS ^H │ 024 18  CAN ^X 009 09 HT ^I │ 025 19  EM ^Y 010 0A LF ^J │ 026 1A  SUB ^Z 011 0B VT ^K │ 027 1B  ESC ^[ 012 0C FF ^L │ 028 1C  FS ^\ 013 0D CR ^M │ 029 1D  GS ^] 014 0E  SO ^N │ 030 1E  RS ^^ 015 0F  SI ^O │ 031 1F  US ^_ Punctuation, Digits, Upper Case Dec Hex Chr │ Dec Hex Chr │ Dec Hex Chr │ Dec Hex Chr --- --- --- │ --- --- --- │ --- --- --- │ --- --- --- 032 20 │ 048 30 0 │ 064 40 @ │ 080 50 P 033 21 ! │ 049 31 1 │ 065 41 A │ 081 51 Q 034 22 " │ 050 32 2 │ 066 42 B │ 082 52 R 035 23 # │ 051 33 3 │ 067 43 C │ 083 53 S 036 24 $ │ 052 34 4 │ 068 44 D │ 084 54 T 037 25 % │ 053 35 5 │ 069 45 E │ 085 55 U 038 26 & │ 054 36 6 │ 070 46 F │ 086 56 V 039 27 ' │ 055 37 7 │ 071 47 G │ 087 57 W 040 28 ( │ 056 38 8 │ 072 48 H │ 088 58 X 041 29 ) │ 057 39 9 │ 073 49 I │ 089 59 Y 042 2A * │ 058 3A : │ 074 4A J │ 090 5A Z 043 2B + │ 059 3B ; │ 075 4B K │ 091 5B [ 044 2C , │ 060 3C < │ 076 4C L │ 092 5C \ 045 2D - │ 061 3D = │ 077 4D M │ 093 5D ] 046 2E . │ 062 3E > │ 078 4E N │ 094 5E ^ 047 2F / │ 063 3F ? │ 079 4F O │ 095 5F _ Lower Case, Miscellaneous Dec Hex Chr │ Dec Hex Chr --- --- --- │ --- --- --- 096 60 ` │ 112 70 p 097 61 a │ 113 71 q 098 62 b │ 114 72 r 099 63 c │ 115 73 s 100 64 d │ 116 74 t 101 65 e │ 117 75 u 102 66 f │ 118 76 v 103 67 g │ 119 77 w 104 68 h │ 120 78 x 105 69 i │ 121 79 y 106 6A j │ 122 7A z 107 6B k │ 123 7B { 108 6C l │ 124 7C | 109 6D m │ 125 7D } 110 6E n │ 126 7E ~ 111 6F o │ 127 7F  International; Graphics Characters 1 Dec Hex Chr │ Dec Hex Chr │ Dec Hex Chr │ Dec Hex Chr --- --- --- │ --- --- --- │ --- --- --- │ --- --- --- 128 80 А │ 144 90 Р │ 160 A0 │ 176 B0 129 81 Б │ 145 91 С │ 161 A1 б │ 177 B1 ▒ 130 82 В │ 146 92 Т │ 162 A2 в │ 178 B2 ▓ 131 83 Г │ 147 93 У │ 163 A3 г │ 179 B3 │ 132 84 Д │ 148 94 Ф │ 164 A4 д │ 180 B4 ┤ 133 85 Е │ 149 95 Х │ 165 A5 е │ 181 B5 ╡ 134 86 Ж │ 150 96 Ц │ 166 A6 ж │ 182 B6 135 87 З │ 151 97 Ч │ 167 A7 з │ 183 B7 136 88 И │ 152 98 Ш │ 168 A8 и │ 184 B8 ╕ 137 89 Й │ 153 99 Щ │ 169 A9 й │ 185 B9 ╣ 138 8A К │ 154 9A Ъ │ 170 AA к │ 186 BA ║ 139 8B Л │ 155 9B Ы │ 171 AB л │ 187 BB ╗ 140 8C М │ 156 9C Ь │ 172 AC м │ 188 BC ╝ 141 8D Н │ 157 9D Э │ 173 AD н │ 189 BD ╜ 142 8E О │ 158 9E Ю │ 174 AE о │ 190 BE ╛ 143 8F П │ 159 9F Я │ 175 AF п │ 191 BF ┐ Graphics Characters 2; Symbols Dec Hex Chr │ Dec Hex Chr │ Dec Hex Chr │ Dec Hex Chr --- --- --- │ --- --- --- │ --- --- --- │ --- --- --- 192 C0 └ │ 208 D0 ╨ │ 224 E0 р │ 240 F0 Ё 193 C1 ┴ │ 209 D1 ╤ │ 225 E1 с │ 241 F1 ё 194 C2 ┬ │ 210 D2 ╥ │ 226 E2 т │ 242 F2 Є 195 C3 ├ │ 211 D3 ╙ │ 227 E3 у │ 243 F3 є 196 C4 ─ │ 212 D4 ╘ │ 228 E4 ф │ 244 F4 Ї 197 C5 ┼ │ 213 D5 ╒ │ 229 E5 х │ 245 F5 ї 198 C6 ╞ │ 214 D6 ╓ │ 230 E6 ц │ 246 F6 Ў 199 C7 ╟ │ 215 D7 ╫ │ 231 E7 ч │ 247 F7 ў 200 C8 ╚ │ 216 D8 ╪ │ 232 E8 ш │ 248 F8 ° 201 C9 ╔ │ 217 D9 ┘ │ 233 E9 щ │ 249 F9 ∙ 202 CA ╩ │ 218 DA ┌ │ 234 EA ъ │ 250 FA · 203 CB ╦ │ 219 DB █ │ 235 EB ы │ 251 FB √ 204 CC ╠ │ 220 DC ▄ │ 236 EC ь │ 252 FC № 205 CD ═ │ 221 DD ▌ │ 237 ED э │ 253 FD ¤ 206 CE ╬ │ 222 DE ▐ │ 238 EE ю │ 254 FE ■ 207 CF ╧ │ 223 DF ▀ │ 239 EF я │ 255 FF ═══ 10.4.2. Key Codes and Scan Codes Table ═══ (For more details on key codes and scan codes, see the Key Codes and Scan Codes Explanation.) Key names prefaced by np are on the numeric keypad. Those prefaced by cp are on the cursor keypad between the main typing keys and the number keypad. The numeric keypad values are valid if Num Lock is turned off. If you need to specify a number key from the numeric keypad, use the scan code shown for the keypad and the ASCII code shown for the corresponding typewriter key. For example, the keypad "7" has a scan code of 71 (the np Home scan code) and an ASCII code of 54 (the ASCII code for "7"). The chart is blank for key combinations that do not have scan codes or ASCII codes, like Ctrl-1 or Alt-PgUp. Top Two Keyboard Rows Shift Shift Ctrl Ctrl Alt Scan ASCII Scan ASCII Scan ASCII Scan Key Code Code Code Code Code Code Code Esc 1 27 1 27 1 27 1 1 ! 2 49 2 33 120 2 @ 3 50 3 64 3 0 121 3 # 4 51 4 35 122 4 $ 5 52 5 36 123 5 % 6 53 6 37 124 6 ^ 7 54 7 94 7 30 125 7 & 8 55 8 38 126 8 * 9 56 9 42 127 9 ( 10 57 10 40 128 0 ) 11 48 11 41 129 - _ 12 45 12 95 12 31 130 = + 13 61 13 43 131 Backspace 14 8 14 8 14 127 14 Tab 15 9 15 0 148 0 165 Q 16 113 16 81 16 17 16 W 17 119 17 87 17 23 17 E 18 101 18 69 18 5 18 R 19 114 19 82 19 18 19 T 20 116 20 84 20 20 20 Y 21 121 21 89 21 25 21 U 22 117 22 85 22 21 22 I 23 105 23 73 23 9 23 O 24 111 24 79 24 15 24 P 25 112 25 80 25 16 25 [ { 26 91 26 123 26 27 26 ] } 27 93 27 125 27 29 27 Enter 28 13 28 13 28 10 28 Bottom Two Keyboard Rows Shift Shift Ctrl Ctrl Alt Scan ASCII Scan ASCII Scan ASCII Scan Key Code Code Code Code Code Code Code A 30 97 30 65 30 1 30 S 31 115 31 83 31 19 31 D 32 100 32 68 32 4 32 F 33 102 33 70 33 6 33 G 34 103 34 71 34 7 34 H 35 104 35 72 35 8 35 J 36 106 36 74 36 10 36 K 37 107 37 75 37 11 37 L 38 108 38 76 38 12 38 ; : 39 59 39 58 39 ' " 40 39 40 34 40 ` ~ 41 96 41 126 41 \ | 43 92 43 124 43 28 43 Z 44 122 44 90 44 26 44 X 45 120 45 88 45 24 45 C 46 99 46 67 46 3 46 V 47 118 47 86 47 22 47 B 48 98 48 66 48 2 48 N 49 110 49 78 49 14 49 M 50 109 50 77 50 13 50 , < 51 44 51 60 51 . > 52 46 52 62 52 / ? 53 47 53 63 53 Space 57 32 57 32 57 32 57 Key Pads and Function Keys Shift Shift Ctrl Ctrl Alt Scan ASCII Scan ASCII Scan ASCII Scan Key Code Code Code Code Code Code Code F1 59 0 84 0 94 0 104 F2 60 0 85 0 95 0 105 F3 61 0 86 0 96 0 106 F4 62 0 87 0 97 0 107 F5 63 0 88 0 98 0 108 F6 64 0 89 0 99 0 109 F7 65 0 90 0 100 0 110 F8 66 0 91 0 101 0 111 F9 67 0 92 0 102 0 112 F10 68 0 93 0 103 0 113 F11 133 0 135 0 137 0 139 F12 134 0 136 0 138 0 140 np * 55 42 55 42 150 0 55 np Home 71 0 71 55 119 0 cp Home 71 224 71 224 119 224 151 np Up 72 0 72 56 141 0 cp Up 72 224 72 224 141 224 152 np PgUp 73 0 73 57 132 0 cp PgUp 73 224 73 224 132 224 153 np Minus 74 45 74 45 142 0 74 np Left 75 0 75 52 115 0 cp Left 75 224 75 224 115 224 155 np 5 76 0 76 53 143 0 np Right 77 0 77 54 116 0 cp Right 77 224 77 224 116 224 157 np Plus 78 43 78 43 144 0 78 np End 79 0 79 49 117 0 cp End 79 224 79 224 117 224 159 np Down 80 0 80 50 145 0 cp Down 80 224 80 224 145 224 160 np PgDn 81 0 81 51 118 0 cp PgDn 81 224 81 224 118 224 161 np Ins 82 0 82 48 146 0 cp Ins 82 224 82 224 146 224 162 np Del 83 0 83 46 147 0 cp Del 83 224 83 224 147 224 163 np / 224 47 224 47 149 0 164 np Enter 224 13 224 13 224 10 166 ═══ 10.4.3. Key Codes and Scan Codes Explanation ═══ Key Codes and Scan Codes Explanation (This section explains how key codes and scan codes work. For a reference chart, see the Key Codes and Scan Codes Table.) When you press a single key or a key combination, OS/2 translates your keystroke into two numbers: a scan code, representing the actual key that was pressed, and an ASCII code, representing the ASCII value for that key. OS/2 returns these numbers the next time a program requests keyboard input. This section explains how key codes work; for information on using them with Take Command see the TCMDOS2.INI file key mapping directives, keystroke aliases, and INKEY. Most Take Command commands that use the numeric key codes listed here also use key names, which are usually more convenient to use than the numeric codes. See Keys and Key Names for more information on key names. As PCs have evolved, the structure of keyboard codes has evolved somewhat haphazardly with them, resulting in a bewildering array of possible key codes. We'll give you a basic explanation of how key codes work. For a more in-depth discussion, refer to a BIOS or PC hardware reference manual. The nuances of how your keyboard behaves depends on the keyboard manufacturer, the computer manufacturer who provides the built-in BIOS, and your operating system. As a result, we can't guarantee the accuracy of the information in the tables for every system, but the discussion and reference table should be accurate for most systems. Our discussion is based on the 101-key "enhanced" keyboard commonly used on 286, 386, 486, and Pentium computers, but virtually all of it is applicable to the 84-key keyboards on older systems. The primary difference is that older keyboards lack a separate cursor pad and only have 10 function keys. All keys have a scan code, but not all have an ASCII code. For example, function keys and cursor keys are not part of the ASCII character set and have no ASCII value, but they do have a scan code. Some keys have more than one ASCII code. The A, for example, has ASCII code 97 (lower case "a") if you press it by itself. If you press it along with Shift, the ASCII code changes to 65 (upper case "A"). If you press Ctrl and A the ASCII code changes to 1. In all these cases, the scan code (30) is unchanged because you are pressing the same physical key. Things are different if you press Alt-A. Alt keystrokes have no ASCII code, so OS/2 returns an ASCII code of 0, along with the A key's scan code of 30. This allows a program to detect all the possible variations of A, based on the combination of ASCII code and scan code. Some keys generate more than one scan code depending on whether Shift, Ctrl, or Alt is pressed. This allows a program to differentiate between two different keystrokes on the same key, neither of which has a corresponding ASCII value. For example, F1 has no ASCII value so it returns an ASCII code of 0, and the F1 scan code of 59. Shift-F1 also returns an ASCII code 0; if it also returned a scan code of 59, a program couldn't distinguish it from F1. The operating system translates scan codes for keys like Shift-F1 (and Ctrl-F1 and Alt-F1) so that each variation returns a different scan code along with an ASCII code of 0. On the 101-key keyboard there's one more variation: non-ASCII keys on the cursor keypad (such as up-arrow) return the same scan code as the corresponding key on the numeric keypad, for compatibility reasons. If they also returned an ASCII code of 0, a program couldn't tell which key was pressed. Therefore, these keys return an ASCII code of 224 rather than 0. This means that older programs, which only look for an ASCII 0 to indicate a non-ASCII keystroke like up-arrow, may not detect these cursor pad keys properly. The number of different codes returned by any given key varies from one (for the spacebar) to four, depending on the key, the design of your keyboard, and the operating system. Some keys, like Alt, Ctrl, and Shift by themselves or in combination with each other, plus Print Screen, SysReq, Scroll Lock, Pause, Break, Num Lock, and Caps Lock keys, do not have any code representations at all. The same is true of keystrokes with more than one modifying key, like Ctrl-Shift- A. The operating system may perform special actions automatically when you press these keys (for example, it switches into Caps Lock mode when you press Caps Lock), but it does not report the keystrokes to whatever program is running. Programs which detect such keystrokes access the keyboard hardware directly, a subject which is beyond the scope of this manual. ═══ 10.4.4. ANSI Reference ═══ Take Command for OS/2's ANSI support allows you to manipulate the cursor, screen color, and other display attributes through sequences of special characters embedded in the text you display on the screen. These sequences are called "ANSI commands". This section is a quick-reference to the ANSI commands supported by Take Command for OS/2. These sequences are typically displayed by internal commands, or by character-mode applications started under Take Command's TTY application support (see Starting Character- Mode Applications). ANSI support within Take Command for OS/2 can be enabled or disabled with the ANSI directive in TCMDOS2.INI, the corresponding option on the Display page of the configuration notebook, or the SETDOS /A command. You can test whether ANSI support is enabled with the _ANSI internal variable. An ANSI command string consists of three parts: ESC[ The ASCII character ESC, followed by a left bracket. These two characters must be present in all ANSI strings. parameters Optional parameters for the command. If there are multiple parameters they are separated by semicolons. cmd A single-letter command. The case of the letter IS meaningful. For example, to position the cursor to row 7, column 12 the ANSI command is: ESC[7;12H To transmit ANSI commands to the screen with Take Command for OS/2, you can use the ECHO command. The ESC character can be generated by inserting it into the string directly (if you are putting the string in a batch file and your editor will insert such a character), or by using Take command's internal "escape" character (caret, [^]) followed by a lower-case "e". For example, the sequence shown above could be transmitted from a batch file with either of these commands (the first uses an ESC character directly; the second uses ^e): echo [7;12H echo ^e[7;12H You can also include ANSI commands in your prompt, using $e to transmit the ESC character. Commands ESC[rowsA Cursor up ESC[rowsB Cursor down ESC[colsC Cursor right ESC[colsD Cursor left ESC[row;colH Set cursor position (top left is row 1, column 1) ESC[2J Clear screen ESC[K Clear from cursor to end of line ESC[row;colf Set cursor position, same as "H" command ESC[attr;attr;...m Set display attributes; see table of attribute values below ESC[s Save cursor position (may not be nested) ESC[u Restore cursor position after a save Display Attributes 1 High intensity (bright) foreground color 2 Normal intensity 30-37 Set the foreground color: 30=Black 31=Red 32=Green 33=Yellow 34=Blue 35=Magenta 36=Cyan 37=White 40-47 Set the background color, same values as above but substitute 40 for 30 etc. Settings are cumulative, so (for example) to set bright red foreground you must first set red, then set high intensity: echo ^e[31;1m Examples Set the display to bright cyan on blue, and clear the screen: echo ^e[44;36;1m^e[2J Set up a prompt which saves the cursor position, displays the date and time on the top line in bright white on magenta, and then restores the cursor position and sets the color to bright cyan on blue, and displays the standard prompt: prompt $e[s$e[1;1f$e[45;37;1m$e[K$d $t$e[u$e[44;36;1m$p$g ═══ 10.5. Glossary ═══ The glossary contains over 200 terms, and is divided into sections by the first letter of each term. Select the section you want to review: A B C D E F G H I K L M N O P R S T U V W X ═══ 10.5.1. Glossary - A ═══ B C D E F G H I K L M N O P R S T U V W X Alias Parameter: A numbered variable (e.g. %2) included in an alias definition, allowing a different value to be used in the alias each time it is executed. Alias: A shorthand name for a command or series of commands. AND: A logical combination of two true or false conditions. If both conditions are true, the result is true; if either condition is false, the result is false. ANSI: Usually a reference to ANSI control sequences, standardized sequences of text characters which control colors on the screen, manipulate the cursor, and redefine keys. OS2 includes support for ANSI screen and cursor control sequences. The abbreviation ANSI is for American National Standards Institute, an organization whch sets standards for computer-related systems, including "ANSI" screen control sequences. Append: Concatenation of one file or string onto the end of another (this use is not related to the DOS and OS/2 external command named APPEND). Application: A program run from the command prompt or a batch file. Used broadly to mean any program other than the command processor; and more narrowly to mean a program with a specific purpose such as a spreadsheet or word processing program, as opposed to a utility. Archive: A file attribute indicating that the file has been modified since the last backup (most backup programs clear this attribute). Also sometimes refers to a single file (such as a .ZIP file) which contains a number of other files in compressed form. Argument: See Parameter. ASCII File: A file containing ASCII text, as opposed to a binary file which may contain numbers, or other information that cannot be sensibly interpreted as text. ASCII: The American Standard Code for Information Interchange, which defines numeric values for 128 different characters comprising the English alphabet, numbers, punctuation, and some control characters. Attribute: A characteristic of a file which can be set or cleared. The standard attributes are Read-Only, Hidden, System, and Archive; other attributes include Directory and Volume Label. Automatic Batch Files: See TCSTART and TCEXIT. Automatic Directory Change: A Take Command feature which allows you to change directories by typing the directory name and a backslash [\] at the prompt. ═══ 10.5.2. Glossary - B ═══ A C D E F G H I K L M N O P R S T U V W X Base Name: The file name without a drive, path, or extension. For example, in the file name C:\DIR1\LETTER.DAT the base name is LETTER. BAT File: See Batch File. Batch File: A text file containing a sequence of commands for the command processor to execute. Batch files are used to save command sequences so that they can be re-executed at any time, transferred to another system, etc. The extension of a batch file may be .BAT, .CMD, or .BTM, depending on the operating system and command processor you are using. Batch File Parameter: A numbered variable (e.g. %2) used within a batch file, allowing a different value to be used at that spot in the file each time it is executed. Binary File: A file containing information which does not represent or cannot sensibly be interpreted as text. See also ASCII File. BIOS or Basic Input Output System: The software (or "firmware") stored on chips inside PC systems. The BIOS provides basic low-level control of devices required to operate the system, such as the keyboard, floppy disk, and screen; it also handles system self-tests at startup, and intiates loading of the operating system. Block Device: A physical device for input or output which can transmit or receive large blocks of data while the computer is engaged in other activities. Examples include disk, tape, and CD-ROM drives. See also Character Device. Boot Directory: The current directory at the time the system is booted, usually the root directory of the boot drive. Boot Drive: The disk drive that the system is booted from, usually A: (the floppy disk) or C: (the hard disk). Boot: The process of starting the computer and loading the operating system into memory. See also Reboot, Cold Reboot, and Warm Reboot. Break: A signal sent to a program to tell it to halt what it is doing. The Ctrl-C key or Ctrl-Break key is used to send this signal. Some external commands abort when they receive a break signal; others return to a previous screen or menu, or abort the current operation. BTM File: A special type of Take Command batch file which is loaded into memory to speed up execution. Buffer: An area of memory set aside for storage. For example, disk buffers are used to save information as it is transferred between your program and the disk, and the keyboard buffer holds keystrokes until a program can use them. ═══ 10.5.3. Glossary - C ═══ A B D E F G H I K L M N O P R S T U V W X CDFS or CD-ROM File System: The file system which supports CD-ROM drives. This is typically implemented as a distinct file system in 32-bit operating systems like OS/2 and Windows NT. On other platforms it is implemented as a component of or addition to the underlying general file system for disk drives. Character Device: A physical device for input or output which must communicate with your computer one character at a time. Examples include the console, communications ports, and printers. See also Block Device. Character Mode: A display mode in which output is displayed in a fixed font, typically with 80 columns in a line and 25 lines on the screen (some systems allow you to increase the number of rows and columns to other fixed sizes), and which cannot display graphics or pictures. See also Graphics Mode. CMD File: See Batch File. CMDLINE: An environment variable used to extend the command line passed to another program beyond its normal length limits. Cold Reboot: The process of restarting the computer in a way that physically resets most hardware devices, typically by pressing a reset button, or by turning the power off and back on. See also Warm Reboot. Command Completion: A Take Command feature which allows you to recall a previous command by typing the first few letters of the command, then an up-arrow or down-arrow. Command Echoing: A feature which displays commands as they are executed. Echoing can be turned on and off. Command Grouping: A Take Command feature which allows you to group several commands with parentheses, and have them treated as a single command for most purposes. Command History Window: A pop-up window used by Take Command to display the command history, allowing you to choose a previous command to modify and/or execute. Command History: A Take Command feature which retains commands you have executed, so that they can be modified and re-executed later. Command Processor: A program which interprets commands and executes other programs. Sometimes also called a Command Interpreter. Command Recall: See Command History. Command Separator: A character used to separate multiple commands on the same command line. Command Tail: The portion of a command consisting of all the arguments, i.e., everything but the command name itself. Compound Command: See Multiple Commands. Compression: An operating system feature which compresses data as it is stored in a disk file, and decompresses it as it is read back, resulting in more efficient use of disk space (at a slight cost in processor time to perform the compression and decompression). More generally, an approach to data storage which reduces repeated or redundant information to a smaller number of bytes in the compressed version than in the original, in order to minimize the space required to store the information. COMSPEC: An environment variable which defines where to find the character-mode command processor to start a secondary shell. Conditional Commands: A Take Command feature allowing commands to be executed or skipped depending on the results of a previous command. See also Exit Code. Console: The PC keyboard and display. Console Mode: See Character Mode. Control Character: A character which is part of the ASCII code, but does not have a normal text representation, and which can usually be generated by pressing the Ctrl key along with another key. Coprocessor: See Numeric Coprocessor. Country Settings: The internal settings which tell the operating system how to interpret keyboard characters which vary from country to country, which character set to use, and how to retrieve and display date, time, and other information in the format appropriate to a particular country. See also Code Page. CPU: The Central Processing Unit which performs all logic and most calculations in a computer. In PC-compatible systems, the CPU is on a single microprocessor chip. CR or Carriage Return: The ASCII character "carriage return" (decimal value 13), generated by pressing the Enter key on the keyboard, and stored in most ASCII files at the end of each line. Critical Error: An error, usually related to a physical or hardware problem with input, output, or network access, which prevents a program from continuing. Current Directory: The directory in which all file operations will take place unless otherwise specified. The current directory is typically displayed as part of the command prompt. Also called the Current Working Directory. Current Drive: The disk drive on which all file operations will take place unless otherwise specified. The current drive is typically displayed as part of the command prompt. Cursor: A movable marker on the screen to show where text will be entered when you type at the keyboard, or which object on the screen will be affected when a mouse button is clicked. In character mode only the text cursor is available; graphical systems typically show both a mouse cursor and, when text can be entered, a separate text cursor. ═══ 10.5.4. Glossary - D ═══ A B C E F G H I K L M N O P R S T U V W X Date Range: A Take Command feature which allows you to select files based on the date and time they were last modified. Date Stamp: Information stored in a file's directory entry to show the dates on which the file was created, last modified, and last accessed. Creation and last access dates are not available in the FAT file system. See also Time Stamp. Default Directory: See Current Directory Default Drive: See Current Drive. Delete Tracking: An operating system or utility software feature which is designed to allow you to "undelete" or recover files which have recently been deleted. Delete tracking typically works by temporarily retaining the deleted files and/or information about the deleted files in a special area of the disk. Description: A string of characters assigned to describe a file with the Take Command DESCRIBE command. Destination: In file processing commands (e.g. COPY or MOVE), the name or directory files should have after any copying or modification has taken place, generally the last specification on the command line. See also Source. Detached Process: A program which is "detached" from the normal means of user input and output, and cannot use the keyboard, mouse, or video display. Device Driver: A program which allows the operating system to communicate with a device, and which is loaded into memory when the system boots. Device drivers are also used to manage memory or for other similar internal functions. Device: A physical device for input or output such as the console, a communications port, or a printer. Sometimes "device" is used to refer to character devices, and excludes block devices. Directive: An individual item in the TCMDOS2.INI file, used to control the configuration of Take Command. Directory: A portion of any disk, identified by a name and a relationship to other directories in a "tree" structure, with the tree starting at the root directory. A directory separates files on the disk into logical groups, but does not represent a physical division of the data on the disk. Directory History: A Take Command feature which allows you to recall recently-used directory names in a popup window, and choose one to switch to. Directory History Window: See Directory History. Directory Stack: A Take Command feature, implemented through the PUSHD and POPD commands, which allows you to save the current directory and return to it later. See also Stack. Directory Tree: The branching structure of directories on a hard disk, starting at the root directory. The root of the tree is usually considered as the "top" of the structure, so the actual structure can be visualized as an upside-down tree with the root at the top and branches going "down". A portion or branch of the directory tree is sometimes called a " subtree". DOS Memory: See Base Memory. DOS Session: See Session. DPMI or DOS Protected Mode Interface: A specification which allows DOS programs to access memory beyond 1 MB in order to manage larger programs or larger amounts of information than will fit in base memory. DPMI support for DOS programs is provided by some DOS memory managers, and by OS/2, Windows 3.1 and above, Windows 95, and Windows NT. Drive Letter: A letter used to designate a specific local disk volume, or part or all of a network server drive. In most cases drive letters range from A - Z, but some network operating systems allow the use of certain punctuation characters as drive letters in order to support more than 26 volumes. ═══ 10.5.5. Glossary - E ═══ A B C D F G H I K L M N O P R S T U V W X Echo: See Command Echoing. Environment: An area of memory which contains multiple entries in the form "NAME=value". See also Master Environment and Passed Environment. Environment Variable: The name of a single entry in the environment. Error Level: A numeric value between 0 and 255 returned from an external command to indicate its result (e.g., success, failure, response to a question). See also Exit Code. Escape Character: In some contexts, the Take Command escape character, which is used to suppress the normal meaning of or give special meaning to the following character. In other cases, the specific ASCII character ESC. The meaning must be determined from the context. Escape Sequence: A sequence of text characters which has a special meaning and is not treated as normal text. For example, the character sequence ]K (where is the ASCII "escape" character, decimal value 27) will cause an ANSI driver to clear the screen from the cursor to the end of the current line, rather than simply displaying the string "ESC]K" on the screen. Similarly, in Take Command, the escape sequence ^f on the command line is translated to a form feed, and is not treated as the literal characters "^f". Executable Extensions: A Take Command feature which allows you to specify the application to be executed when a file with a particular extension is named at the command prompt. Executable File: A file, usually with the extension .COM or .EXE, which can be loaded into memory and run as a program. Exit Code: The result code returned by an external command or an internal command. Take Command internal commands return an exit code of 0 if successful, or non-zero if unsuccessful. See also Errorlevel. Expansion: The process Take Command goes through when it scans a command line and substitutes the appropriate actual values for aliases, alias parameters, batch file parameters, and environment variables. See also Parsing. Extended ASCII Character: A character which is not part of the standard set of 128 ASCII characters, but is used on the PC as part of an extended set of 256 characters. These characters include international language symbols, and box and line drawing characters. Extended Attributes: An OS/2 High Performance File System (HPFS) feature which allows storage of additional information about a file, separate from the file itself. Extended attributes are typically used to store icons for executable files, property or settings information, and other information added by the user. Extended Directory Search: A Take Command feature which maintains a directory search " database" or list, typically including all directories in your system, and allows you to change quickly to any directory in the list. Extended Key Code: The code for a key on the PC keyboard which has no representation in the standard ASCII character set, such as a function key, cursor key, or Alt plus another key. The extended key code for a key is often the same as the scan code for that key. Extended Memory: Any memory on a computer system with a 286, 386, 486, or Pentium processor which is above the first 1 MB (one megabyte, or 1024*1024 bytes) of memory. See also XMS. Extended Parent Directory Names: A Take Command feature which allows you to use additional periods in a directory name to represent directories which are successively higher in the directory tree. Extended Wildcard: A Take Command feature which extends the traditional wildcard syntax and allows you to use multiple wildcard characters, and character ranges (e.g. [a-f] for the letters A through F). See also Wildcard. Extension: The final portion of a file name, preceded by a period. For example, in the file name C:\DIR1\LETTER.DAT the extension is .DAT. In a long filename which contains multiple periods, the extension is usually considered to be the portion of the name after the final period. External Command: A program which resides in an executable file, as opposed to an internal command which is part of the command processor. EXTPROC: A command processor feature which allows you to designate a specific external program to run a particular batch file. ═══ 10.5.6. Glossary - F ═══ A B C D E G H I K L M N O P R S T U V W X FAT File System: The traditional file system used by DOS to store files on diskettes and hard disks; also supported by OS/2 and Windows NT. Uses a File Allocation Table to keep track of allocated and unallocated space on the disk. FAT-Compatible File Name: See SFN. FF or Form Feed: The ASCII character "form feed" (decimal value 12), which typically causes a printer to skip to a new page. The FF character is not normally entered from the keyboard, but in many cases it can be generated, if necessary, by holding the Alt key, pressing 0-1-2, and releasing the Alt key. File Attribute: See Attribute. File Description: See Description. File Exclusion Range: A Take Command feature which allows you to exclude files from processing by internal commands based on their names. Filename Completion: A Take Command feature which allows you to type part of a filename on the command line, and have the command processor fill in the rest for you. Free Memory: Usually, the amount of total memory which is unoccupied and available for applications. ═══ 10.5.7. Glossary - G ═══ A B C D E F H I K L M N O P R S T U V W X Global Aliases: A Take Command option which allows you to store aliases in a global area accessible to all copies of Take Command, so that any change made by one copy is immediately available to all other copies. See also Local Aliases. Global Directory History: An option which allows you to store the directory history in a global area accessible to all copies of Take Command, so that any change made by one copy is immediately available to all other copies. See also Local Directory History. Global History: A Take Command option which allows you to store the command history in a global area accessible to all copies of Take Command, so that any change made by one copy is immediately available to all other copies. See also Local History. Graphics Mode: A display mode in which output is displayed in any one of a range of fonts, typically in resizable windows with a variable number of text rows and columns, and which supports the display of graphics and pictures along with text. See also Character Mode. ═══ 10.5.8. Glossary - H ═══ A B C D E F H I K L M N O P R S T U V W X Hidden: A file attribute indicating that the file should not be displayed with a normal DIR command, and should not be made available to programs unless they specifically request access to hidden files. History Window: See Command History Window and Directory History. History: See Command History. HMA or High Memory Area: The area of PC memory located in the first 64K bytes above the 1 megabyte that DOS can address directly. The HMA can be made addressable from DOS programs using special hardware facilities, or an XMS driver. HPFS or High Performance File System: A file system distributed with OS/2 and Windows NT 3.51 and below which allows longer file names, supports larger drives, and provides better performance than the traditional FAT file system. ═══ 10.5.9. Glossary - I ═══ A B C D E F G H K L M N O P R S T U V W X IFS or Installable File System: A file system which can be loaded when required to support devices such as CD-ROM or network drives, or non-default disk formats like HPFS (in OS/2) or NTFS (in Windows NT). Installable file systems are primarily supported 32-bit operating systems like OS/2 and Windows NT. Depending on operating system design they may be loaded at boot time, or loaded and unloaded dynamically while the system is running. Include List: A concise method of specifying several files or groups of files in the same directory, for use with all Take Command commands which take file names as arguments. Inheritance: A feature which allows one copy of Take Command to "inherit" the .INI file data, aliases, command history, and directory history from a previous copy. More generally, a system which allows one program to pass information or settings on to another, often to a second copy of the same program. .INI File: The Take Command initialization file containing directives which set the initial configuration of the command processor. Insert Mode: When editing text, a mode in which newly typed characters are inserted into the line at the cursor position, rather than overwriting existing characters on the line. See also Overstrike Mode. Internal Command: A command which is part of the command processor, as opposed to an external command. Internal Variables: Environment variables created by Take Command to provide information about your system. Internal variables are evaluated each time they are used, and are not actually stored in the environment. ═══ 10.5.10. Glossary - K ═══ A B C D E F G H I L M N O P R S T U V W X Key Code: The code passed to a program when a key is pressed on the keyboard. Depending on the key that is pressed, and the software handling the keyboard, the code can be an ASCII code, a scan code, or an extended key code. Key Mapping: A Take Command feature which allows you to assign new keystrokes for command line functions such as manipulating the command history or completing file names. Keyboard Buffer: A buffer which holds keystrokes you have typed that have not yet been used by the currently executing program. Keystroke Alias: An alias assigned to a key, so that it can be invoked or recalled with a single keystroke. ═══ 10.5.11. Glossary - L ═══ A B C D E F G H I K M N O P R S T U V W X Label: A marker in a batch file, with the format :name, allowing GOTO and GOSUB commands to "jump" to that point in the file. See also Volume Label. LF or Line Feed: The ASCII character "line feed" (decimal value 10), stored in most ASCII files at the end of each line, after the CR character. The LF character is not normally entered from the keyboard, but in many cases it can be generated, if necessary, by pressing Ctrl-Enter. Local Aliases: A Take Command option which allows you to store aliases in a local area only accessible to the current copy of Take Command, so that a change made in the current copy of Take Command does not affect other copies, and vice versa. See also Global Aliases. Local Directory History: A Take Command option which allows you to store the directory history in a local area only accessible to the current copy of Take Command, so that a change made in the current copy of Take Command does not affect other copies, and vice versa. See also Global Directory History. Local History: A Take Command option which allows you to store the command history in a local area only accessible to the current copy of Take Command, so that a change made in the current copy of Take Command does not affect other copies, and vice versa. See also Global History. Logging: A Take Command feature, implemented via the LOG command, which allows you to save a record of the commands you execute. ═══ 10.5.12. Glossary - M ═══ A B C D E F G H I K L N O P R S T U V W X Master Environment: The master copy of the environment maintained by the command processor. Modulo: The remainder after an integer division. For example 11 modulo 3 is 2, because when 11 is divided by 3 the remainder is 2. Multiple Commands: A Take Command feature which allows multiple commands to be placed on a line, separated by an ampersand [&], or another, user-defined character. Multitasking: A capability of some software (and the related hardware) which allows two or more programs to run apparently simultaneously on the same computer. Multitasking software for PC compatible systems includes operating environments like Windows 3, and complete operating systems like OS/2, Windows 95, and Windows NT. ═══ 10.5.13. Glossary - N ═══ A B C D E F G H I K L M O P R S T U V W X Network: A system which allows several computers to be connected together to share files, printers, modems, or other resources, and to pass electronic mail or other information between the systems on the network. Network File System: Software which runs over a network to allow access to files on the server. A network file system may support the same options as the file system used on local drives, or it may be more or less restrictive than the local file system about file names, disk volume capacity, and other similar features. NTFS or New Technology File System: A file system distributed with Windows NT which allows longer file names, supports larger drives, and provides better performance than the traditional FAT file system. Numeric Coprocessor: A chip which works in conjunction with an Intel 8086, 80286, 80386, 80486, or Pentium CPU to perform decimal arithmetic ("floating point") calculations. Some 80486s and the Pentium CPU have the numeric coprocessor built in to the CPU chip; in all other cases it is on a physically separate chip, and is optional (when the coprocessor is not avilable, the CPU performs decimal arithmetic through other, much slower methods). ═══ 10.5.14. Glossary - O ═══ A B C D E F G H I K L M N P R S T U V W X Operating System: A collection of software which loads when the computer is started, provides services to other software, and ensures that programs don't interfere with each other while they are running. Option: See Switch. OR: A logical combination of two true or false conditions. If both conditions are false the result is false; if either condition is true the result is true. Overstrike Mode: When editing text, a mode in which newly typed characters overwrite existing characters on the line, rather than being inserted into the line at the cursor position. See also Insert Mode. ═══ 10.5.15. Glossary - P ═══ A B C D E F G H I K L M N O R S T U V W X Parameter: A piece of additional information placed after a command or function name. For example, in the command DIR XYZ, XYZ is a parameter. Also used to refer to an alias parameter or batch file parameter. Parent Directory: The directory in which a particular subdirectory resides, often seen as the directory "above" a subdirectory. Parsing: The process Take Command performs to analyze the command line, perform alias and environment variable expansion, and find the appropriate internal command or external command to execute. More generally, the process of breaking down a string or message into its individual components in order to process them properly. Passed Environment: A copy of the master environment created before running an application, so that any changes made by the application will not affect the master environment. Path: A specification of all the directories a file resides in. For example, the path for C:\WPFILES\MYDIR\MEMO.TXT is C:\WPFILES\MYDIR\. Also used to refer to the environment variable PATH, which contains a series of path specifications used when searching for external commands and batch files. Pipe: A method for collecting the standard output of one program and passing it on as the standard input of the next program to be executed, signified by a vertical bar "|" on the command line. See also Redirection. Previous Working Directory: The working directory used most recently, just prior to the current working directory. For example, if C:\DATA is the current working directory and you switch to D:\UTIL, C:\DATA then becomes the previous working directory. Primary Shell: The copy of the character-mode command processor which is loaded by the operating system when the system boots or a session opens. ═══ 10.5.16. Glossary - R ═══ A B C D E F G H I K L M N O P S T U V W X RAM or Random Access Memory: The physical memory used to store data while a computer is operating. The information in most types of RAM is lost when power is turned off. RAM Disk: A pseudo "disk drive", created by software, which appears like a normal physical disk drive to programs. Sometimes also called a Virtual Disk. Range: See Date Range, Size Range, Time Range, and File Exclusion Range. Read-Only: A file attribute indicating that the file can be read, but not written or deleted by the operating system or the command processor unless special commands are used. Reboot: The process of restarting the computer with software, with the keyboard (e.g. by pressing Ctrl-Alt-Del), by pressing a reset button, or by turning the power off and back on. See also Cold Reboot and Warm Reboot. Redirection: A method for collecting output from a program in a file, and/or of providing the input for a program from a file. See also Pipe. REXX: A file and text processing language developed by IBM, and available on many PC and other platforms. ROM or Read Only Memory: A physical memory device used to store information which cannot be readily modified, such as the BIOS built into each PC system. The information in ROM is typically retained when power is turned off. Root Directory: The first directory on any disk, from which all other directories are "descended." The root directory is referenced with a single backslash [\]. ═══ 10.5.17. Glossary - S ═══ A B C D E F G H I K L M N O P R T U V W X Scan Code: The physical code for a key on the PC keyboard. For the original U.S. English keyboard layout the scan code represents the physical position of the key, starting with 1 for the key in the upper left corner (Esc), and increasing from left to right and top to bottom. This order will vary for more recent keyboards or those designed for other countries or languages. Search Path: See PATH. Secondary Shell: A copy of the command processor which is started by another program, rather than by the operating system. Session: A general term for the individual windows or tasks started by a multitasking system. For example, under OS/2 you might run a DOS application in one session, and Take Command in another. Shell: See Command Processor. Also used to refer to a program which gives access to operating system functions and commands through a menu- or mouse-driven system, or which replaces the primary user interface of the operating system. Size Range: A Take Command feature which allows you to select files based on their size. Source: In file processing commands (e.g. COPY or MOVE), the original files before any copying or modification has taken place, i.e., those specified earlier on the command line. See also Destination. Stack: An area of memory used by any program to store temporary data while the program is running; more generally, any such storage area where the last item stored is normally the first one removed. Standard Error, Standard Input, and Standard Output: The file(s) or character device(s) where a program respectively displays error messages, obtains its normal input, and displays its normal output. Standard error, standard input, and standard output normally refer to the console, unless redirection is used. Subdirectory: Any directory other than the root directory. Subtree: See Directory Tree. Swap File: A disk file created by an operating system or a program to store unused information on disk, and thereby free up memory for other purposes. Switch: A parameter for an internal command or application which specifies a particular behavior or setting. For example, the command "DIR /P" might be referred to as "having the /P switch set". System: A file attribute indicating that the file belongs to the operating system or command processor, and should not be accessed by other programs. ═══ 10.5.18. Glossary - T ═══ A B C D E F G H I K L M N O P R S U V W X Target: See Destination. TCEXIT: A batch file which is executed whenever Take Command exits. TCSTART: A batch file which is executed whenever Take Command starts. Time Range: A Take Command feature which allows you to select files based on the time they were last modified. Time Stamp: Information stored in a file's directory entry to show the times at which the file was created, last modified, and last accessed. Creation time is not available in the FAT file system; last access time is only available in the HPFS and NTFS file systems. See also Date Stamp. Tree: See Directory Tree. ═══ 10.5.19. Glossary - U ═══ A B C D E F G H I K L M N O P R S T V W X UMB or Upper Memory Block: An XMS Upper Memory Block, whose address is above the end of base memory (normally, above 640K), but within the 1 megabyte of memory that DOS can address directly. UNC or Universal Naming Convention: A common method for accessing files on a network drive without using a "mapped" drive letter. Names specified this way are called UNC names, and typically appear as \\server\volume\path\filename, where server is the name of the network server where the files reside, volume is the name of a disk volume on that server, and the path\filename portion is a directory name and file name. ═══ 10.5.20. Glossary - V ═══ A B C D E F G H I K L M N O P R S T U W X Variable Expansion: The process of scanning a command line and replacing each environment variable name, alias parameter, or batch file parameter with its value. Variable Functions: Functions provided by Take Command to manipulate strings, dates, and filenames; perform arithmetic; read and write files; and perform other similar functions. Variable functions are similar to static environment variables or internal variables, but have parameters and can perform actions rather than just returning static information. Variable: See Alias Parameter, Batch File Parameter, and Environment Variable. Virtual Disk: See RAM Disk. Volume Label: A special, hidden file placed on any disk, whose name constitutes a "label" for the entire disk. Volume: See Disk Drive. ═══ 10.5.21. Glossary - W ═══ A B C D E F G H I K L M N O P R S T U V X Warm Reboot: The process of restarting the computer with software, or with the keyboard (e.g. by pressing Ctrl-Alt-Del), typically without physically resetting any hardware devices. See also Cold Reboot. White Space Character: A character used to separate arguments on the command line. The white space characters recognized by Take Command are the space, tab, and comma. Wildcard: A character ("*" or "?") used in a filename to specify the possibility that any single character ("?") or sequence of characters ("*") can occur at that point in the actual name. See also Extended Wildcard. Windows NT File System: See NTFS. ═══ 10.5.22. Glossary - X ═══ A B C D E F G H I K L M N O P R S T U V W XOR (exclusive OR): A logical combination of two true or false conditions. If both conditions are false or both conditions are true the result is false; if either condition is true and the other is false the result is true.