═══ 1. About 4OS2 Help ═══ 4OS2 On-line Documentation (Version 1.11, 3/93) Text by Rex Conn and Tom Rawson, originally converted to OS/2 format by Matthew J. Palcic. Copyright 1992, 1993, Rex Conn and JP Software Inc., All Rights Reserved. 4OS2 is a trademark and 4DOS is a registered trademark of JP Software Inc. OS/2 is a registered trademark of IBM Corporation. Other product and company names are trademarks of their respective owners. This online help system for 4OS2 covers all 4OS2 features and internal commands. It includes reference information to assist you in using 4OS2 and developing batch files; however it does not include all of the details which are included in the printed 4OS2 and 4DOS manuals. The help system is fully indexed and cross-indexed. It is also context-sensitive; if you press F1 with a command already on the 4OS2 command line, the help system will display help for that command. If the line is blank when you press F1, the help topic index is displayed. You can obtain "quick help" for any 4OS2 command directly on your 4OS2 screen or window (without starting VIEW or switching back to the desktop) by entering the command at the prompt followed by a /?. The quick help displays the syntax, purpose, and switches for the command. 3/93-1.11A ═══ 2. Using 4OS2 ═══ This section includes information on: Differences between 4DOS and 4OS2 16 and 32 bit versions of 4OS2 Command line editing keys Internal variables Variable functions Redirection Command grouping Wildcards Shared alias and history lists 4OS2.INI See the individual topics for details. ═══ 2.1. 4OS2 and 4DOS ═══ Most 4DOS commands and features work the same way in 4OS2. However if you're an experienced 4DOS user or want to use the same batch files and aliases in both 4OS2 and 4DOS, there are some differences between 4DOS and 4OS2 you should be aware of. Those differences are listed here. (Several items below list elements of 4DOS which are not available under 4OS2. In all cases these items have been removed from 4OS2 because they are specific to DOS or for other similar reasons are not relevant or cannot be implemented under OS/2.) * The default command separator is ^ in 4DOS; in 4OS2 it is & (for compatibility with CMD.EXE). You can change it in 4OS2.INI or with the SETDOS /C command. * The default escape separator is  (Control-X) in 4DOS; in 4OS2 it is ^ (for compatibility with CMD.EXE). You can change it in 4OS2.INI or with the SETDOS /E command. * The alias and variable parameter syntax is %n& in 4DOS; in 4OS2 it is %n$ (because & is normally used in 4OS2 as the command separator). You can change it with the ParameterChar directive in 4OS2.INI or with the SETDOS /P command. * The following 4DOS commands do not exist in 4OS2: BREAK KEYSTACK SWAPPING CTTY LOADHIGH / LH TRUENAME * The following 4DOS internal variables and variable functions do not exist in 4OS2: %_ALIAS %@EMS[] %@REMOVABLE[] %_DV %@EXTENDED[] %@TRUENAME[] %_ENV %@LPT[] %@XMS[] %_WIN * New internal variables and variable functions available only in 4OS2 include: %_PID %_SID %@EXETYPE[] %_PPID %_PTYPE %@FSTYPE[] Also the %_VIDEO internal variable returns some additional values in 4OS2. See 4OS2 Internal Variables and 4OS2 Variable Functions for more information. * The following 4DOS.INI directives cannot be used in 4OS2.INI: Alias Environment ReserveTPA ANSI FineSwap StackSize AutoExecPath FullINT2E Swapping ChangeTitle HelpOptions SwapReopen CopyEA HelpPath UMBEnvironment DiskReset LineInput UMBLoad DRSets MessageServer UniqueSwapName DVCleanup NetwareNames EnvFree Reduce (The alias list size and environment size are set automatically by 4OS2; other directives refer to features which are not relevant under OS/2.) * New directives available in 4OS2.INI which are not available in 4DOS.INI include: LocalAliases LocalHistory WindowState See 4OS2.INI for more information. ═══ 2.2. 16 and 32 Bit Versions of 4OS2 ═══ 4OS2 comes in two versions: 32-bit (4OS2/32) and 16-bit (4OS2/16). 4OS2/16 runs under OS/2 1.2, 1.3, 2.0, and above. 4OS2/32 runs only under OS/2 2.0 and above. If you use OS/2 version 2, you will find that 4OS2/32 offers a few improvements and runs a bit faster than 4OS2/16. Caution: 4OS2/32 requires OS/2 2.0 with at least the XR06055 CSD (the "Service Pack") installed. 4OS2/32 will not work properly with earlier versions of OS/2 (it will behave erratically, and some commands will not work at all). 4OS2/32 will work properly on later versions of OS/2, including the "2.01" and "2.1" beta versions and subsequent releases. If you are unsure of what version of OS/2 you are running, and you have JP Software's 4DOS, start a 4DOS session and enter the command VER /R. Check the displayed OS/2 Revision level. This value must be 427 or greater for 4OS2/32 to work properly under OS/2 2.0. In this file, features which are available only in 4OS2/32 are marked with the legend "4OS2/32 only". If you don't see this legend, you can assume that the feature you are reading about is available in both versions. For details on differences between 4OS2/32 and the 4OS2/16 see the following topics in this file: Shared alias and history lists DEL command (/F switch) MEMORY command START command (/DOS switch) ═══ 2.3. Editing the Command Line ═══ The 4OS2 command line offers full editing, and can also display the command history in a window (see below). The command line accepts up to 1023 characters. The following keys have special meaning when entered at the command line (the caret ^ means press the Ctrl key together with the specified key):  Move the cursor left one character.  Move the cursor right one character.  Recall the previous command from the history list, or match a partial command entry with a history list entry.  Recall the next command from the history list, or match a partial command entry with a history list entry. ^ Move the cursor left one word. ^ Move the cursor right one word. Home Move the cursor to the beginning of the line. ^Home Delete from the beginning of the line to the character preceding the cursor. End Move the cursor to the end of the line. ^End Delete from the cursor to the end of the line. Ins Toggle between insert and overstrike mode. Del Delete the character at the cursor. Backspace Delete the character to the left of the cursor. Enter Execute the command. Esc Erase the entire line. ^L Delete the word to the left of the cursor. ^R or ^Backspace Delete the word to the right of the cursor. ^C Abort the command. ^D Delete the history list entry, and erase the line. ^E Go to the last entry in the history list. ^K Save the command to the history list without executing it, and erase the line. F1 Call the on-line help. F3 Fill in the rest of the line (beyond any characters that have already been typed) from the last line in the history. Tab (or F9), Shift-Tab (or F8), F10 A Tab will scan the filename (which may include the wildcard characters at or immediately to the left of the cursor position, and replaces it with the first matching filename. Pressing Tab again replaces it with the next matching filename; pressing F10 appends the next matching filename at the current cursor position. Pressing Shift-Tab will retrieve the previous matching filename. If you don't enter a filename, Tab defaults to *.*. If you don't enter an extension, Tab appends a .*. PgUp Popup a history window, showing those commands that match characters already entered on the command line. ^PgUp Popup a directory window, showing those directories recently changed to with the CD, CDD, and PUSHD commands. Alt-255 (Hold down the Alt key and enter 255 on the numeric keypad.) Accept the next character "as-is" from the keyboard and enter it on the command line. This allows you to enter characters normally interpreted as editing keys (for example, Esc). To enter the Alt-255 character itself into the line, you must type it twice. ^ (caret) "Escape" the next character (the default escape character for 4OS2 and CMD.EXE is the caret ^; it can be changed in 4OS2 with the SETDOS command or in the 4OS2.INI file). The escape character forces the parser to ignore any special meaning of the next character (for example, redirection characters). Note that 4OS2 will not recognize the escape character inside double quotes (for compatibility with CMD.EXE). Escaping the following characters will insert the specified control code: b bell (ASCII 7) e escape (ASCII 27) f form feed (ASCII 12) n line feed (ASCII 10) r carriage return (ASCII 13) t tab (ASCII 9) The following keys have special meaning when entered from inside the popup history and directory windows. The history list in a window is not circular as it is at the command line; scrolling and paging stop at the beginning or end of the history list.  Move the highlight up one line.  Move the highlight down one line. PgUp Move up one page. PgDn Move down one page. Home Move to the first line in the list. End Move to the last line in the list. Enter Execute the highlighted command (history window) or change to the highlighted directory (directory window). ^Enter Close the window and move the highlighted command to the prompt for editing (history window only). Esc Close the window and return to the previous command line at the prompt. ^C Close the window, abort any partially entered command line, and redisplay the prompt. Most of the command line and popup window keys, as well as the popup window location and size, can be redefined in the 4OS2.INI initialization file. ═══ 2.4. 4OS2 Internal Variables ═══ Environment variables are referenced in a command by starting the variable name with a percent sign (%). (If you want to enter a percent sign without referring to a variable, use two percent signs (%%).) An environment variable name is terminated by either another percent sign, or by an invalid character (see below). To pass a variable name (instead of the value) to a command (for example, in INKEY or INPUT), you must precede it with two percent signs. Environment variable names may be composed of any alphanumeric character, plus the underscore (_), and $ characters. In addition to the standard variable name characters, you can force 4OS2 to accept any sequence of characters as a valid variable name by enclosing them in square brackets. For example, %[AB##1] refers to an environment variable named AB##1. Batch file variables are only active inside a batch file. They are referenced as %0 to %127, and expand to the matching argument on the command line that started the batch file. The parameter %n$ is a special case, and expands to all arguments in the command line tail, starting at argument number n. If n is not specified, it defaults to 1 (so %$ will expand to all arguments in the command line tail). There are some variable names that have special meanings in 4OS2. Only CDPATH, CMDLINE, and PATH are actually stored in the environment; the remainder are internal to 4OS2, and cannot be viewed or modified with SET or ESET. (The internal variable names are checked after variable expansion, so they can be overridden by creating an environment variable of the same name.) The 4OS2 internal variables are: %# returns the number of command line arguments in a batch file. %? returns the exit code of the previous external command. %_? returns the exit code of the previous internal command. (Save this value immediately; it is overwritten by the next internal command.) %+ returns the current command separator. See the CommandSep directive in 4OS2.INI or the SETDOS /C command for more details. %= returns the current 4OS2 escape character. See the EscapeChar directive in 4OS2.INI or the SETDOS /E command for more details. %CDPATH tells 4OS2 where to search for directories names specified by a CD or CDD command. 4OS2 will append the specified directory name to each directory in CDPATH and attempt to change to that directory. If you have already have a CDPATH environment variable, you can use %_CDPATH instead for the directory search. %CMDLINE is the fully expanded 1023-character command line for the external command. You can access it from an external program by searching the environment. %COLORDIR is the "directory colorization" variable. See DIR for details on the COLORDIR format. %PATH tells 4OS2 where to search for executable files: .COM, .EXE, .BTM, and .CMD (and .BAT in OS/2 2.0), in that order, not found in the current directory. Some applications also use the PATH variable to find their files. %_4VER returns the 4OS2 version number (for example, 1.1). %_ANSI is 1 if ANSI is active (4OS2 always enables ANSI). %_BATCH is the current batch nesting level (0 if not in a batch file). %_BG is a string containing the screen background color at the current cursor position. %_BOOT returns the boot disk (for example, C). %_CODEPAGE is the current code page number. %_COLUMN is the current cursor column. %_COLUMNS is the current number of screen columns. %_CPU is the cpu type (286, 386, or 486). %_CWD is the current directory in the format d:\pathname. %_CWDS has the same value as CWD, except it ensures the pathname ends in a backslash (\). %_CWP is the current directory in the format \pathname. %_CWPS has the same value as CWP, except it ensures the pathname ends in a backslash (\). %_DATE contains the current system date, in the format mm-dd-yy (U.S.), dd-mm-yy (Europe), or yy-mm-dd (Japan). %_DISK is the current disk (for example, C). %_DOS is the operating system type (DOS or OS2). This is useful if you have .BTM files running in both modes. %_DOSVER is the current OS/2 version (for example, 2.0). %_DOW is the current day (Mon, Tue, Wed, etc.). %_FG is a string containing the screen foreground color at the current cursor position. %_LASTDISK returns the last disk on the system (A: - Z:). %_MONITOR is the monitor type (MONO or COLOR). %_MOUSE returns 1 if a mouse is installed. %_NDP is the coprocessor type (0 - no coprocessor; 287 - 80287; 387 - 80387 or 80486). %_PID is the process ID for 4OS2. %_PPID is the parent process ID (for the process that started 4OS2). %_PTYPE is the process type (FS - full screen; AVIO - Windowed; PM - Presentation manager; DT - detached). %_ROW is the current cursor row. %_ROWS is the current number of screen rows. %_SHELL is the current shell nesting level for that session. The first copy of 4OS2 started in a session is shell 0. %_SID is the session ID. %_TIME contains the current system time in the format hh:mm:ss. The separator character may vary depending upon your country information. %_TRANSIENT returns a 1 if the current shell is transient (started with a /C). %_VIDEO is the video card type (MONO, CGA, EGA, VGA, XGA, 8514, or IA/A). ═══ 2.5. 4OS2 Variable Functions ═══ Variable Functions are pseudo-variables that take one or more arguments (which can themselves be environment variables or variable functions), and return a value. The variable function name must be preceded by an %@ (%@eval, %@len, etc.). All variable functions must have square brackets enclosing their argument(s). Some functions return the number of bytes, kilobytes, or megabytes based on a b|k|m argument: b bytes k bytes / 1000 K kilobytes (bytes / 1024) m bytes / 1,000,000 M megabytes (bytes / 1,048,576) With such functions, you can append a c after the b|k|m character to return the value with the proper thousands delimiter every three characters. For example, if MYFILE.DAT is 62,374 bytes long, then: %@filesize[myfile.dat,b] returns 62374 %@filesize[myfile.dat,bc] returns 62,374 Note that values with commas in them can not be used when performing numeric comparisons with the IF command. The 4OS2 variable functions are: %@ALIAS[name] returns the alias argument for the specified name. %@ASCII[c] returns the ASCII value of the specified character. %@ATTRIB[filename,attrib] returns a 1 if the specified file has the matching attribute(s). The attributes (other than N) can be combined; ATTRIB will only return a 1 if _all_ the attributes match. The attributes are: N Normal (no attribute bits set) R Read-only H Hidden S System D Directory A Archive %@CHAR[n] returns the character for the specified ASCII value. %@DATE[mm/dd/yy] returns the number of days since 1/1/80 for the specified date. DATE will use the date format mandated by your country code (dd/mm/yy in Europe; yy/mm/dd in Japan). %@DESCRIPT[filename] returns the file's description. %@DEVICE[name] returns a 1 if the specified name is a character device. %@DISKFREE[d:,b|k|m[c]] returns the free disk space for the specified drive, in bytes, kilobytes, or megabytes. %@DISKTOTAL[d:,b|k|m[c]] returns the total disk space for the specified drive, in bytes, kilobytes, or megabytes. %@DISKUSED[d:,b|k|m[c]] returns the disk space used on the specified drive, in bytes, kilobytes, or megabytes. %@DOSMEM[b|k|m[c]] returns the size of the largest free OS/2 memory block in bytes, kilobytes, or megabytes. Due to OS/2's virtual memory system, this value is only a general reflection of available memory and not a precise statement of the RAM available for applications. %@EVAL[expression] evaluates an arithmetic expression. It supports addition (+), subtraction (-), multiplication (*), division (/), and modulo (%%). The expression can contain environment variables, including other variable functions. EVAL supports commas and decimal places; the maximum size is 16.8 (16 integer and 8 decimal places). EVAL strips leading and trailing zeros from the result. %@EXEC[command] executes the command and returns its exit code. The command can be an alias, an internal 4OS2 command, or an external program or batch file. This is a back door entry to 4OS2 command processing -- use with caution! %@EXETYPE[filename] returns the file's program type: UNKNOWN Unknown type FS Full-screen OS/2 AVIO Windowable OS/2 PM Presentation manager OS/2 DOS MS-DOS (OS/2 2.0 only) WIN Windows 3 (OS/2 2.0 only) %@EXT[filename] returns the file extension (without a leading period). %@FILEDATE[filename] returns the last modification date for the file, in the default country format (mm-dd-yy for US). %@FILESIZE[filename,b|k|m[c]] returns the size of the file in bytes, kilobytes, or megabytes, or -1 if the file doesn't exist. %@FILETIME[filename] returns the last modification time for the file, in hh:mm format. %@FULL[filename] returns the fully qualified path name. %@FSTYPE[d:] returns the drive's file system type (for example, FAT or HPFS). %@INDEX[string1,string2] returns the position of string2 within string1, or -1 if string2 is not found. The first position in string1 is 0. %@INT[n] returns the integer part of "n". See %@EVAL. %@LABEL[d:] returns the volume label of the specified disk. %@LEN[string] returns the length of the string. %@LINE[filename,n] returns line "n" from the specified file. If you specify "CON" for the filename, it will read from standard input. %@LINES[filename] returns the number of lines in the specified file, base 0. If there are no lines, it returns -1. %@LOWER[string] returns the string converted to lower case. %@MAKEDATE[n] returns the date given the number of days since 1/1/80. %@MAKETIME[n] returns the time given the number of seconds since midnight. %@NAME[filename] returns the filename only (no path or extension). %@PATH[filename] returns the path only (including the trailing backslash). %@READSCR[row,column,length] returns the text on the screen at the specified row and column, for the specified length. %@READY[d:] returns a 1 if the specified drive is ready. %@REMOTE[d:] returns a 1 if the specified drive is remote (LAN). %@REMOVABLE[d:] returns a 1 if the specified drive has removable media (floppy, CD_ROM, etc.). %@SEARCH[filename] searches for an executable file using the PATH environment variable, appending the extension if one wasn't specified. %@SELECT[filename,top,left,bottom,right,title] displays the file as a popup selection list. If you press Enter, it returns the string highlighted by the selection bar; if you press Esc it returns an empty string. If you specify "CON" for the filename, it will read from standard input. %@SUBSTR[string,start,length] returns a substring, starting at the position "start" and continuing for "length" characters. If the length is negative, the start is relative to the right side. If the length isn't specified, SUBSTR will return the remainder of the string. For example, %@SUBSTR[%_time,0,2] gets the current time and extracts the hour. If the string includes commas it must be quoted with double quotes or single back-quotes (" or `). %@TIME[hh:mm:ss] returns the number of seconds since midnight for the specified time. The time must be in 24-hour format. %@UNIQUE[d:\path] returns a unique filename in the specified drive and path. %@UPPER[string] returns the string converted to upper case. %@WORD[n,string] returns the "nth" word in the string (base 0). If "n" is negative, WORD starts from the end and counts backwards. ═══ 2.6. Redirection and Piping ═══ Redirection OS/2 assumes input comes from the keyboard and output goes to the display. The keyboard is referred to as standard input, and the display is referred to as standard output. You can change the default standard input and standard output by using the < and > symbols on the command line. 4OS2 also allows you to redirect the standard error by appending an & character. To get standard input from a file instead of the keyboard: < filename To redirect standard output to a file: > filename To redirect standard output and standard error to a file: >& filename To redirect standard error only to a file: >&> filename To append standard output or standard error to a file, use >> in place of the first >. If NOCLOBBER is set, the file must exist before it can be appended to (unless overridden by a !). Otherwise, 4OS2 will create the file. 4OS2 also supports the OS/2 CMD.EXE syntax: n>file and n>&m where n and m are digits from 0 to 9. You may not put any spaces between the n and the >, or between the & and the m in the second form. The digits represent file handles: 0, 1, and 2 are predefined by OS/2 as standard input, standard output, and standard error respectively; 3 through 9 can be defined by applications. The n>file syntax redirects output from handle n to a file. The n>&m syntax redirects handle n to the same location as the previously assigned handle m. In many cases you can perform the same operations by using 4OS2's enhanced redirection features. See the 4OS2 manual for more information on these options. Piping Piping makes the standard output of one command the standard input for a second command. To send the standard output of "cmd1" to the standard input of "cmd2": cmd1 | cmd2 To send the standard output and standard error of "cmd1" to the standard input of "cmd2": cmd1 |& cmd2 Unlike 4DOS, which creates a temporary file for pipes, 4OS2 connects a pipe directly to a secondary process; both processes execute simultaneously. ═══ 2.7. Command Grouping ═══ Command grouping allows you to logically group a set of commands together by enclosing them with parentheses. For example, this grouping: (global /iq echo %_cwd) > dirlist allows you to redirect all output from GLOBAL to the specified file. The following command will take the output of DIR and TYPE, sort the whole mess, and save it in the file AZ: (dir *.com & type autoexec.bat) | sort > AZ To group commands, the first character of the command must begin with a ( Note that if you have a closing parenthesis ) in a filename, you'll need to escape it with the 4OS2 escape character (^) to keep 4OS2 from assuming it's the end of the command group. You can also use command grouping to split commands over several lines. For example: for %x in (*.c) do ( echo %x dir *.c ) If you enter a command group on the command line without a closing parenthesis, 4OS2 will prompt you with More? for the remainder of the line. ═══ 2.8. Wildcards ═══ Wildcards let you specify a file or group of files by typing a partial filename. Most internal commands accept filenames with wildcards anywhere a full filename can be used. 4OS2 recognizes 3 wildcard types: asterisk *, question mark ?, and square brackets [ ]. You can combine various wildcard types in a single filename. Note that the 4OS2 wildcard extensions may not be interpreted properly by external programs, so when passing file names to external programs you should use the traditional wildcard syntax. A * in a filename means "any zero or more characters in this position." You can use both leading and trailing asterisks. For example, to get a directory of all files beginning with "ab": dir ab*.* To get a directory of all files with an "ab" anywhere in the filename: dir *ab*.* A ? matches any single filename character. A ? doesn't require that a character exist if it's at the end of the filename or extension. A set of characters in brackets [ ] acts like a ? (match any single character), but allows you to specify or exclude specific characters. If you specify one or more characters in the brackets (e.g. [abc]), the specification will only match files whose names have one of the listed characters in the corresponding position. For example, to get a directory of all files whose names have either a "p" or "q" as the first letter: dir [pq]*.* Two characters with a dash (-) between them represent a range of characters, and will match any character within the range (including the beginning and end characters). For example, to get a directory of all files with names beginning with a number from 1 to 6, or the letters "a" or "b", and ending with a "9": dir [1-6ab]*9.* If you enter a ! as the first character following the left bracket, the test is reversed (only match names that do not have the listed characters in the corresponding position). For example, to get a directory of all files with names of two characters or more that begin with an "a" and do not have a digit as the second character: dir a[!0-9]*.* The special wildcard construct [?] will match any character (like ?) but will require that the character exist, even at the end of a filename or extension. For example, if you have the files XYZ.DAT and XY.DAT in the current directory, then: dir xy?.dat will display both file names dir xy[?].dat will display only XYZ.DAT ═══ 2.9. Shared Alias and History Lists ═══ By default, 4OS2 will use the same history list and alias list in all sessions and in both primary and secondary 4OS2 shells. It keeps these lists in shared memory segments. This means that the aliases that you define in one session will be available immediately in copies of 4OS2 that are running in other sessions. In addition, the history list is updated in all 4OS2 sessions whenever you type a command at any 4OS2 prompt. If you want to start a 4OS2 shell or session with unique alias and history lists, use the LocalAlias and / or LocalHistory Initialization Directives in 4DOS.INI. Using the 4OS2.INI directive is the best choice if you want to have separate alias and history lists for all 4OS2 sessions. You can also place these directives on the command line if you want to create a separate list just for one particular session or shell. The memory segments that contain the shared history and alias lists are retained as long as there is at least one copy of 4OS2 running that supports shared lists. When all such copies of 4OS2 end, the shared history and alias lists are discarded. A utility program called SHRALIAS.EXE is included on the 4OS2 distribution diskette. It will keep these lists open until your computer is rebooted. To use this program, include the following line in your STARTUP.CMD, 4START, or 4OS2 session startup batch file: [d:\path\]shralias Once SHRALIAS is started, it will remain active until your computer is turned off or rebooted, even if the session from which it was started is terminated. To deactivate SHRALIAS, enter this command at any 4OS2 prompt: [d:\path\]shralias /u If you are using 4OS2/16 (see 16 and 32 bit versions of 4OS2), the SHRALIAS program is in the file SHRALS16.EXE on the distribution disk. If you are using 4OS2/32, SHRRALIAS is in the file SHRALS32.EXE. These files are renamed automatically to SHRALIAS.EXE during installation from diskettes. If you have a downloaded copy of 4OS2 the proper copy is in the ZIP file you downloaded, and is already named SHRALIAS.EXE (see the README.DOC file which came with your downloaded copy for details). You must use the correct version of SHRALIAS for the version of 4OS2 you are running. The 16-bit SHRALIAS program will not keep shared alias and history lists open for 4OS2/32, and SHRALS32 will not do so for 4OS2/16. ═══ 2.10. 4OS2 Initialization File (4OS2.INI) ═══ The 4OS2.INI file is an ASCII file containing directives to control the configuration of 4OS2 in primary and secondary shells. Blank lines are ignored 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 by entering at least one space or tab after the value, a semicolon, and your comment. The file has two sections, identified by a name in square brackets on a line by itself. The section names are: [Primary] Directives in this section will be used when 4OS2 is running as the primary shell (i.e., when a session is started). [Secondary] Directives in this section are used in secondary shells only (i.e., a second invocation of 4OS2 within the same session), and override any corresponding primary shell settings. Lines before a section name are used in both primary and secondary shells. When 4OS2 is loaded, whether as the primary or secondary shell, it first checks for an "@d:\path\inifile" option on the command line (you can set this option in the Parameters field of the Settings notebook for any icon that starts a 4OS2 session). If this option is found 4OS2 looks for the specified file, and skips the search for the default 4OS2.INI file. If no INI file name is specified on the command line, 4OS2 looks for 4OS2.INI in the same directory as 4OS2 itself, then in the root directory of the system boot drive. Directives in 4OS2.INI are divided into four types: Initialization directives Configuration directives Color directives Key mapping directives See the individual topics for details. ═══ 2.10.1. Initialization Directives ═══ These directives control how 4OS2 starts and where it looks for its files. 4StartPath= Path: Sets the drive and directory where 4OS2 will look for the 4START and 4EXIT batch files. History= nnnn (1024): Sets the history list size (in bytes). The range is 512 to 8192 bytes. LocalAliases= Yes | NO: "Yes" tells 4OS2 to create a local alias list for this session. "No" causes 4OS2 to use the global alias list shared by all sessions. LocalHistory= Yes | NO: "Yes" tells 4OS2 to create a local history list for this session. "No" causes 4OS2 to use the global history list shared by all sessions. LogName= File (none): Sets the log file name and/or path. If only a path is given, 4OS2 will use the default log file name (4OS2LOG). Using LogName does not turn logging on, you must still use LOG ON to do so. NextINIFile= File (none): Full path and name must be specified. All subsequent shells will read the specified INI file, and ignore any [Secondary] section in the original 4OS2.INI. Allows workstation users to shift 4OS2.INI to a network drive for secondary shells. PauseOnError= YES | No: "Yes" tells 4OS2 to pause with the message "Error in 4OS2.INI, press any key to continue processing" after displaying any error message related to a specific line in the 4OS2.INI file. "No" continues processing with no pause after an error message is displayed. WindowState= STANDARD | Maximize | Minimize: Switches the 4OS2 window to a maximized or minimized state at startup. Ignored in full-screen sessions. "Standard" means leave the window wherever OS/2 puts it. ═══ 2.10.2. Configuration Directives ═══ These directives control the way that 4OS2 operates. Some can be changed with the SETDOS command while 4OS2 is running. AmPm= Yes | NO | Auto: Sets the time display mode. Yes displays times in 12-hour format (e.g. in DIR and SELECT). The default of No gives 24-hour time displays. Auto sets the time display mode according to the current country code. BatchEcho= YES | No: Sets the default batch ECHO mode. Also see SETDOS /V. BeepFreq= nnnn (440): Sets the default BEEP command frequency in Hz. To disable all 4OS2 error beeps set this or BeepLength to 0; BeepLength= nnnn (2): Sets the default BEEP length in system clock ticks (approximately 1/18 of a second per tick). CursorIns= nnnn (100): Sets the percentage of the character cell filled by the 4OS2 cursor in insert mode. Also see SETDOS /S. CursorOver= nnnn (10): Sets the percentage of the character cell filled by the 4OS2 cursor in overtype mode. Also see SETDOS /S. CommandSep= c (&): This is the character used to separate multiple commands on the same line. Also see SETDOS /C. DescriptionMax= nnnn (40): Sets the maximum file description length accepted by DESCRIBE; the range is 20 - 120 characters. EditMode= Insert | OVERSTRIKE: Lets you start the command line editor in either insert or overstrike mode. Also see SETDOS /M. EscapeChar= c (^): Sets the character used to suppress the normal meaning of the following character. Also see SETDOS /E. HelpBook= String (4OS2+CMDREF): Tells the internal 4OS2 help command (F1 or HELP) which .INF files to use. Filenames are separated by a +. Files should be in one of the directories specified by the BOOKSHELF environment variable. HistMin= nnnn (0): Sets the minimum command length to save in the history list. 0 saves all commands, 300 disables all history saves. HistWinColor= Color: Sets the default colors for the command line history window. HistWinHeight= nn (10): Sets the height of the command line history window in lines, including the border. HistWinLeft= nn (50): Sets the horizontal position of the left side of the command line history window. The left edge of the screen is 0. HistWinTop= nn (0): Sets the vertical position of the top of the command line history window. The top of the screen is 0. HistWinWidth= nn (30): Sets the width of the command line history window in characters, including the border. NoClobber= Yes | NO: If set to Yes, prevents standard output redirection from overwriting an existing file, and requires the output file already exist for append redirection. Also see SETDOS /N. ParameterChar= c ($): Sets the character used to specify all or all remaining command line arguments (e.g. %$ or %2$). The default is $ in 4OS2 and & in 4DOS. Also see SETDOS /P. ScreenRows= nnnn: Sets the number of screen rows used by the video display. Normally, 4OS2 detects the screen size automatically, but if you have a non-standard display you may need to set it explicitly. Also see SETDOS /R. UpperCase= Yes | NO: "Yes" specifies filenames should be displayed in the traditional upper-case by internal commands like COPY and DIR. "No" allows the normal 4OS2 lower-case style. Also see SETDOS /U. ═══ 2.10.3. Color Directives ═══ These directives control the colors that 4OS2 uses for its displays. The color format is: [BRIght] [BLInk] fg ON bg [BORder bc] Where fg is the foreground color, bg is the background color, and bc is the border color. The color names are: Black Blue Green Red Magenta Cyan Yellow White The color names and the keywords BRIGHT, BLINK, and BORDER can be shortened to three letters. ColorDir= ext1 ext2 ...:colora;ext3 ext4 ... :colorb ... (none): Sets the directory colors. The format is the same as that used for the COLORDIR environment variable (see 4OS2 Internal Variables). ListColors= Color: Sets the colors used by the LIST and SELECT commands. StdColors= Color: Sets the standard colors to be used when CLS is used without a color specification, and for LIST and SELECT if ListColors is not used. ═══ 2.10.4. Key Mapping Directives ═══ The directives in this group allow you to change the keys used for 4OS2 command line editing and other internal functions. They take effect only inside 4OS2 itself and do not affect other programs (including the help system). 4OS2 processes all command line editing key assignments 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. (Use the "Normal" directives -- NormalKey, NormalEditKey, etc. -- to disable the preassigned function for a key so it can be used for a keystroke alias.) There are three pre-mapped keys: Tab and Shift-Tab (mapped to NextFile and PrevFile respectively) and Ctrl-Bksp (mapped to DelWordRight). If you need to clear out these assignments so you can assign Tab, Shift-Tab, or Ctrl-Bksp to a keystroke alias, use the ClearKeyMap directive described at the end of this section. The format for a key name is: [Prefix-]Keyname. The prefix and key name must be separated by a dash. The prefix can be left out, or it can be any of the following: Alt followed by A - Z, 0 - 9, F1 - F12, or Bksp Ctrl followed by A - Z, F1 - F12, 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 Esc Up PgUp 0 - 9 Bksp Down PgDn F1 - F12 Tab Left Home Ins Enter Right End Del General Input Keys These directives are effective whenever 4OS2 requests input from the keyboard, including command line editing and the DESCRIBE, ESET, INPUT, LIST, and SELECT commands. (Scrolling through the command history list is controlled by NextHist and PrevHist (see below), not by the Up and Down directives below.) Backspace= Key (Bksp): Deletes the character to the left of the cursor. BeginLine= Key (Home): Moves the cursor to the beginning of the line. Del = Key (Del): Deletes the character at the cursor. DelToBeginning= Key (Ctrl-Home): Deletes from the cursor to the start of the line. DelToEnd= Key (Ctrl-End): Deletes from the cursor to the end of the line. DelWordLeft= Key (Ctrl-L): Deletes the word to the left of the cursor. DelWordRight= Key (Ctrl-R, Ctrl-Bksp): Deletes the word to the right of the cursor. See ClearKeyMap at the end of this section if you need to remove the mapping of Ctrl-Bksp to DelWordRight. Down= Key (Down): Scrolls the display down one line in LIST; moves the cursor down one line in SELECT and in the command history window. EndLine= Key (End): Moves the cursor to the end of the line. EraseLine= Key (Esc): Deletes the entire line. ExecLine= Key (Enter): Executes or accepts a line. Ins = Key (Ins): Toggles insert / overstrike mode during line editing. Left= Key (Left): Moves the cursor left one character; moves the display left 8 columns in LIST. NormalKey= Key (none): Deassigns a general input key in order to disable the usual meaning of the key within 4OS2 and / or make it available for keystroke aliases. This will cause 4OS2 to treat the keystroke as a "normal" key with no special function. Right= Key (Right): Moves the cursor right one character; scrolls the display right 8 columns in LIST. Up = Key (Up): Scrolls the display up one line in LIST; moves the cursor up one line in SELECT and in the command history window. WordLeft= Key (Ctrl-Left): Moves the cursor left one word; scrolls the display left 40 columns in LIST. WordRight= Key (Ctrl-Right): Moves the cursor right one word; scrolls the display right 40 columns in LIST. Command Line Editing Keys The following directives apply only to command line editing (see Command Line Editing). They are only effective at the 4OS2 prompt. AddFile= Key (F10): Keeps the current filename completion entry and inserts the next matching name. CommandEscape= Key (Alt-255): Allows direct entry of a keystroke that would normally be interpreted as an editor command. DelHistory= Key (Ctrl-D): Deletes the displayed history list entry and displays the previous entry. EndHistory= Key (Ctrl-E): Displays the last history list entry. Help= Key (F1): Invokes the 4OS2 HELP facility. NextFile= Key (F9, Tab): Gets the next matching filename. See ClearKeyMap at the end of this section if you need to remove the mapping of Tab to NextFile. NextHistory= Key (Down): Recalls the next command from the command history. NormalEditKey= Key (none): 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. This will cause 4OS2 to treat the keystroke as a "normal" key with no special function. PrevFile= Key (F8, Shift-Tab): Gets the previous matching filename. See ClearKeyMap at the end of this section if you need to remove the mapping of Shift-Tab to PrevFile. PrevHistory= Key (Up): Recalls the previous command from the command history. SaveHistory= Key (Ctrl-K): Saves the command line in the history list without executing it. History Window Keys HistWinBegin= Key (Ctrl-PgUp): Moves to the first line of the history when in the history window. HistWinEdit= Key (Ctrl-Enter): Moves a line from the history window to the prompt for editing. HistWinEnd= Key (Ctrl-PgDn): Moves to the last line of the history when in the history window. HistWinExec= Key (Enter): Executes the selected line in the history window. HistWinOpen= Key (PgUp): Brings up the history window while at the command line. NormalHWinKey= Key (none): Deassigns a history window key in order to disable the usual meaning of the key within the history window. This will cause 4OS2 to treat the keystroke as a "normal" key with no special function. LIST Keys These directives control the keystrokes used within the LIST command. ListFind= Key (F): Prompts and searches for a string. ListHighBit= Key (H): Toggles LIST's "strip high bit" option, which can aid in displaying files from certain word processors. ListNext= Key (N): Finds the next matching string. ListPrint= Key (P): Prints the file on LPT1. ListWrap= Key (W): Toggles LIST's wrap option on and off. The wrap option wraps text at the right margin. NormalListKey= Key (none): Deassigns a LIST key in order to disable the usual meaning of the key within LIST. This will cause 4OS2 to treat the keystroke as a "normal" key with no special function. ClearKeyMap Directive This directive allows you to start with an empty key map. ClearKeyMap: Clears all current key mappings. ClearKeyMap is a special directive which has no value or "=" after it. Use ClearKeyMap if you want to make one of the keys in 4OS2's default map (Tab, Shift-Tab, or Ctrl-Bksp) available for a keystroke alias; or in the [Secondary] section to clear key mappings inherited from the primary shell. ClearKeyMap should appear before any other key mapping directives. If you only need to clear some of the default mappings, use ClearKeyMap, then recreate the mappings you want to retain (e.g. with "Tab=NextFile", etc.). ═══ 2.10.5. Example ═══ The following example gives you an idea of the types of things that can be done with the 4OS2.INI file. The comments on each directive explain what it does. History = 1024 ; set history size BatchEcho = No ; default is ECHO OFF EditMode = Insert ; editor in insert mode CursorO = 100 ; overstrike cursor 100% CursorI = 10 ; insert cursor 10% ListFind = S ; use "S" to search in LIST ListNext = A ; use "A" to search again in LIST ═══ 3. 4OS2 Commands ═══ The 4OS2 commands are described in detail in this section. The commands are arranged alphabetically, and each includes examples to help you learn to use the commands. ═══ 3.1. 4OS2 - 4OS2 command processor ═══ SYNTAX (External OS/2) [[d:]path]4OS2 [/C /K /L /Q /S][@inifile][command ...] PURPOSE Start a new copy of the 4OS2 command processor. COMMENTS 4OS2 replaces CMD.EXE, the default command processor provided with OS/2. The 4OS2 options are: /C Execute the command following the /C, and automatically return to the previous command processor. /K Execute the command following the /K, but do not return to the previous command processor. 4OS2 defaults to /K if /C is not specified. /LA Use local alias list. 4OS2 normally shares its alias list across all sessions; specifying /LA shares it only among processes in the same session. /LH Use local history list. 4OS2 normally shares its history list across all sessions; specifying /LH shares it only among processes in the same session. /Q Don't echo redirected standard input. /S Don't install a ^C signal handler. @inifile The 4OS2.INI file specification. command The command to execute. EXAMPLE Start 4OS2 with local alias and history lists, using the 4OS2.INI file in D:\4OS2: 4OS2 @D:\4OS2\4OS2.INI /LA /LH ═══ 3.2. ? - Display internal commands ═══ SYNTAX (Internal 4OS2) ? PURPOSE Display the internal commands. Commands disabled with SETDOS /I will not be displayed. ═══ 3.3. ALIAS - Display / set aliases ═══ SYNTAX (Internal 4OS2) ALIAS [/P] [/R [d:][path]filename...] [name[=][value]] PURPOSE Load or display the alias list, or define name as a substitute for value. COMMENTS Aliases are useful as a means of executing a complex series of commands with a few keystrokes. Aliases can also be used as very fast in-memory batch files, and will run much faster than disk-based batch files. 4OS2 supports two types of aliases; command aliases (where the alias is substituted for the first argument on the command line), and "keystroke aliases", where the command line editor will immediately substitute the alias when the key is pressed. Keystroke alias names are composed of an @ followed by the key name. You can add a carriage return to a key alias by ending the alias with a ^^r (^ is the 4OS2 escape character) if defined at the command line or in a batch file, or ^r if defined in an ALIAS /R file. The valid key names are the same as those listed in the section on Key Names in Extended Key Codes. If you only specify "name", ALIAS displays the current alias value for "name". Otherwise, ALIAS assigns the command(s) in "value" to "name". "Name" can now be used as if it were a built-in or external command. If you don't specify any arguments, ALIAS displays the current alias list. "Name" is limited to no more than 80 characters, and "value" to no more than 255 characters. The ALIAS options are: /P Pause after displaying each page and wait for a key to be pressed. /R Load an alias list from a file. This is much faster than loading aliases from a batch file. The file is in the same format as the ALIAS display, so ALIAS /R can accept as input a file generated by redirecting ALIAS output. You can add comments to an alias file by starting the comment line with a colon (:). For example, the following commands will save the aliases to a file, and then reload them from that file: alias > alist alias /r alist (You can load aliases from multiple files by listing all the filenames after the /R.) When defining aliases at the command line, back quotes must be used around the alias arguments that contain multiple commands or variable references (%2, %2$, etc.) to prevent premature expansion. Back quotes should NOT be used when defining aliases in a file to be read with ALIAS /R. Aliases may be nested; i.e., an alias can refer to another alias, but they cannot refer back to themselves (a=b=a). You can stop alias expansion by prefacing the alias with an asterisk (*). This also allows an alias to refer to a command of the same name (see below for an example). Alias names can be truncated by including an asterisk (*) in the name. To edit an alias, use ESET; to remove an alias, use UNALIAS. For more information on aliases (including the use of variables), see the Aliases section in the printed manual, and the sample file ALIASES distributed with 4OS2. See also ESET and UNALIAS. EXAMPLES Define D as an alias for DIR /AP: alias d dir /ap Rename the LIST command to DISPLAY, and alias LIST to an external program: alias display *list alias list c:\util\list.com The following examples show the use of alias arguments: alias zap `erase %$ & chkdsk & dir /w` alias reverse `echo %5 %4 %3 %2 %1` The following keystroke alias will insert a "dir /2 /v /p " on the command line when the Alt-F1 key is pressed: alias @Alt-F1 `dir /2 /v /p ` The same alias set up to execute immediately when Alt-F1 is pressed. alias @Alt-F1 `dir /2 /v /p^r` ═══ 3.4. ATTRIB - Display / set file attributes ═══ SYNTAX (Internal 4OS2) ATTRIB [/D /P /Q /S -|+[AHRS]] [d:][path]filename... PURPOSE Change the file or subdirectory attributes. COMMENTS The ATTRIB options are: /D Also modify subdirectory attributes /P Pause after displaying each page /Q Quiet mode - don't display filenames /S Modify files in the current directory and its subdirectories +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 file attribute -S Clear the system file attribute If you don't specify the /D option, ATTRIB only modifies file attributes. If you don't specify any attributes to change, ATTRIB displays the current file attributes. You can also display the file attributes using the /T option in DIR. ATTRIB will preserve the previous file attributes and change only the specified attributes. New attribute values are allowed between filenames; otherwise ATTRIB uses the same attributes specified for the previous file(s). You cannot modify the directory or volume label attributes. EXAMPLES Set the read-only and hidden attributes for the file MEMO: attrib +rh memo Set the archive attribute (file has been modified) for MEMO and change TEXT.COM to system and not modified: attrib +a memo +s -a test.com ═══ 3.5. BEEP - Beep the speaker ═══ SYNTAX (Internal 4OS2) BEEP [frequency [duration] ...] PURPOSE Beep the speaker. COMMENTS BEEP is normally used in batch files to signal that an operation has been completed, or that the computer needs attention (for example, to change disks). Because BEEP allows you to specify the frequency and duration, you can use it to play simple music. You can specify multiple frequency and duration pairs on the command line. The frequency is specified in Hertz, and the duration in 1/18th second intervals. No sound will be generated for frequencies less than 37 Hz, allowing you to insert short delays. The default value for frequency is 440 Hz; the default value for duration is 2. 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 ║ ╚════════╧═══════╧═══════╧═══════╧════════╧═══════╝ EXAMPLE The following batch file fragment runs the program DEMO, plays a few notes, and waits for you to press a key: demo beep 440 4 587 2 1040 6 pause Finished with the demo - press a key to continue ═══ 3.6. CALL - Call a batch file ═══ SYNTAX (Internal 4OS2) CALL [d:][path]filename PURPOSE Call a secondary batch file. COMMENTS CALL allows batch files to call other batch files (batch file nesting) without invoking a secondary copy of the command processor. The calling batch file is suspended while the called batch file runs. When the called batch file finishes, the calling batch file resumes execution at the next command. If you execute a batch file from another batch file without using CALL, the first batch file is terminated before the second one starts. The current ECHO state will be inherited by a called batch file. See also CANCEL and QUIT. EXAMPLE The following batch file fragment compares an input line to "wp" and calls a secondary batch file if it matches: input Enter your choice: %%option if "%option" == "wp" call wp ═══ 3.7. CANCEL - Quit all batch files ═══ SYNTAX (Internal 4OS2) CANCEL [value] PURPOSE Terminate batch processing. COMMENTS The CANCEL command will end all batch file processing, regardless of the batch nesting level. (Use QUIT to end a nested batch file and return to the previous batch file.) If you enter a value, CANCEL will set the ERRORLEVEL to that value. The value also affects the internal variable %_?, and the conditional command separators && and ||. You can CANCEL at any point in a batch file. See also CALL and QUIT. EXAMPLE 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 ═══ 3.8. CD or CHDIR - Change directory ═══ SYNTAX (Internal 4OS2) CD [[d:][pathname] CHDIR [[d:][pathname] PURPOSE Display or change the current directory. COMMENTS Entering CD with no argument or only a drive name will display the current directory. Entering CD and a pathname will change the current directory. If CD can't change to the specified directory, it will look for the CDPATH (or _CDPATH) environment variable. CD will append the specified directory name to each directory in CDPATH and attempt to change to that directory, until the first match or the end of the CDPATH argument. The previous directory is saved on each CD, and you can switch back to it with "CD -". You can switch between two directories by repeatedly entering "CD -". Note that the saved directory is the same for both CD and CDD. You can change directories by pressing ^PgUp at the prompt, which will display a popup window of the most recent directory changes; you can select a directory and switch to it by pressing Enter. 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 directory levels. 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. Use CDD to change both the drive and directory. See also %CDPATH, CDD, and PUSHD. EXAMPLES Change to the subdirectory C:\FINANCE\MYFILES: cd \finance\myfiles Change the default directory on drive A: cd a:\utility Set the CDPATH environment variable and then CD to a directory called DOCS (CD will first attempt to change to DOCS in the current directory, then C:\DOCS, then C:\OS\DOCS, etc.): set cdpath=c:\;c:\os;c:\util;c:\wp cd docs ═══ 3.9. CDD - Change disk and directory ═══ SYNTAX (Internal 4OS2) CDD [d:]pathname PURPOSE Change the current disk drive and directory. COMMENTS CDD is similar to CD, except it can also change the default disk drive. To start at the root directory, start the pathname with a backslash (\). To start at the parent directory, start the pathname with two periods (..). All other pathnames start at the current directory. If CDD can't change to the specified directory, it will look for the CDPATH (or _CDPATH) environment variable. CDD will append the specified directory name to each directory in CDPATH and attempt to change to that directory, until the first match or the end of the CDPATH argument. The previous directory is saved on each CDD, and you can switch back to it with "CDD -". You can switch between two directories by repeatedly entering "CDD -". Note that the saved directory is the same for both CDD and CD. You can change directories by pressing ^PgUp at the prompt, which will display a popup window of the most recent directory changes; you can select a directory and switch to it by pressing Enter. 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 directory levels. See also %CDPATH, CD and PUSHD. EXAMPLES Change to the subdirectory C:\WP: cdd c:\wp Set the CDPATH environment variable and then CDD to a directory called DOCS (CDD will first attempt to change to DOCS in the current directory, then C:\DOCS, then C:\OS\DOCS, etc.): set cdpath=c:\;c:\os;c:\util;c:\wp cdd docs ═══ 3.10. CHCP - Change code page ═══ SYNTAX (Internal 4OS2) CHCP [n] PURPOSE Display or change the current system code page. COMMENTS Code page switching allows you to select different character sets for language support. Before using CHCP, you must have DEVINFO= and CODEPAGE= statements in CONFIG.SYS for the specified code page. CHCP accepts one of the two prepared system code pages. An error message is displayed if a code page is selected that has not been prepared. Entering CHCP with no argument displays the active code page. The code pages supported by OS/2 are: 437 United States 850 Multilingual (Latin I) 852 Slavic (Latin II) 860 Portuguese 863 Canadian-French 865 Nordic See your OS/2 manual for more information on CHCP and code page switching. EXAMPLES Display the current code page: chcp Set the code page to multilingual: chcp 850 ═══ 3.11. CLS - Clear screen ═══ SYNTAX (Internal 4OS2) CLS [[bright] [blink] fg ON bg [BORDER fg]] PURPOSE Clear the video display, optionally to the specified colors. COMMENTS CLS clears the display and moves the cursor to the upper left corner. fg is the foreground color, bg the background color. Only the first three characters of the color name and attributes ("bright" and "blink") are required. You can set the default colors in the 4OS2.INI file. The available colors are: Black Blue Green Red Magenta Cyan Yellow White CLS is normally used in batch files to clear the screen before displaying text. See also COLOR and 4OS2.INI Color Directives. EXAMPLES Clear the display: cls Clear the display to a blue background, and set white characters as the new default: cls white on blue ═══ 3.12. COLOR - Set screen colors ═══ SYNTAX (Internal 4OS2) COLOR [[bright] [blink] fg ON bg [BORDER fg]] PURPOSE Set the screen display colors. COMMENTS fg is the foreground color, bg the background color. Only the first three characters of the color name and attributes ("bright" and "blink") are required. The available colors are: Black Blue Green Red Magenta Cyan Yellow White See also CLS. EXAMPLE Set the default screen colors to bright white text on a blue background: color bright white on blue ═══ 3.13. COPY - Copy files ═══ SYNTAX (Internal 4OS2) COPY [d:][path]filename[+]...[/A /B] [[d:][path]filename] [/A /B /C /F /M /N /P /Q /R /S /U /V] PURPOSE Copy or append one or more files. COMMENTS 4OS2 allows you to copy several unrelated files to a target directory with a single COPY command. If there are two or more arguments on the command line, COPY assumes the last argument is the target. If there is only one argument, the target is assumed to be the current directory. The plus (+) tells COPY to append two or more files to a single target file. If you don't specify a target, COPY will append each subsequent file to the first file. If you specify more than one source file, and the target is NOT a directory, COPY will automatically append the files to the target. The /A(SCII) or /B(inary) options apply to the preceding filename and to all subsequent filenames on the command line until the filename preceding another /A or /B, if any. All other options apply to all filenames on the command line. The COPY options are: /A If used with a source filename, COPY will copy the file up to, but not including, the first ^Z character in the file. If you use /A with a target filename, COPY will add a ^Z to the end of the file. COPY defaults to /A when appending files. /B If used with a source filename, COPY will copy the entire file. Using /B with a target filename prevents COPY from appending a ^Z to the target file. COPY defaults to /B for normal file copies. /C Copy only those files where the target exists and is older than the source (see /U). /F Fail the copy if the source file has extended attributes and the target file system doesn't support extended attributes. /H Copy hidden and system files too. /M Copy only those files with the archive bit set (see also ATTRIB). The archive bit will NOT be cleared after copying. /N Do everything except actually perform the copy (for testing what the result of the COPY would be). /P Confirm each file copy (Y or N). An N response will skip that particular file. /Q Don't display filenames as they are copied. /R Prompt before overwriting an existing file. /S Copy subdirectories - the target must be a directory (COPY will create it if it doesn't exist). COPY will copy each subdirectory to a matching subdirectory of the target. /U Copy only those source files that are newer than a matching target file, or where a matching target file doesn't exist (see /C). /V Verify each disk write. This is the same as executing the VERIFY ON command, but is only active during the COPY. See also MOVE. EXAMPLES Copy the files MEMO1 and PROJECT8.WKS to the root directory on drive A: copy memo1 project8.wks a:\ Append the files MEMO1, MEMO2, and MEMO3 and store the result in BIGMEMO: copy memo1+memo2+memo3 bigmemo Copy only those files in the root directory on drive A that are newer than the matching files in the current directory, or that don't exist in the current directory: copy /u a:\*.* c:\*.* Copy files from the root directory on drive A to the current directory, but prompt before overwriting existing files: copy /r a:\*.* Copy a downloadable font file to the printer in binary mode: copy myfont.dat lpt1: /b ═══ 3.14. DATE - Set or display date ═══ SYNTAX (Internal 4OS2) DATE [mm-dd-yy] PURPOSE Display and (optionally) change the system date. COMMENTS If you don't enter any parameters, DATE will display the current system date and time, and prompt for the new date. Press ENTER if you don't wish to change the date, otherwise enter the new date. The format for the date entry depends on the country code defined in CONFIG.SYS or by the CHCP command. The default format is U.S. (mm-dd-yy). The European format is dd-mm-yy; the Japanese is yy-mm-dd. The parameters for the DATE command are: mm Month (1 - 12) dd Day (1 - 31) yy Year (80 - 199 or 1980 - 2099) You can use hyphens, slashes, or periods to separate the month, day, and year entries. See also TIME. EXAMPLES Enter the date from the command line: date 12/25/89 To be prompted for the date: date ═══ 3.15. DEL or ERASE - Delete files ═══ SYNTAX (Internal 4OS2) DEL [/F /N /P /Q /S /X /Y /Z] [d:][path]filename... ERASE [/F /N /P /Q /S /X /Y /Z] [d:][path]filename... PURPOSE Erase the specified file(s) from the disk. COMMENTS The DEL options are: /F [4OS2/32 only] Delete the specified file(s) without making copies in the DELDIR directory. Caution: Using DEL /F will make the deleted files unrecoverable! /N Do everything except actually delete the file(s) (for testing what the result of a DEL would be). /P Confirm file deletion for each file. /Q Don't display filenames as they are deleted. /S Delete matching files in the subdirectories. /X Remove empty subdirectories after deleting (use with /S). /Y The reverse of /P - it assumes a Y response to everything, including deleting an entire subdirectory. Use with caution! /Z Delete all files, including read-only, hidden and system files. If you enter a subdirectory name, or a filename composed only of wildcards, DEL asks for confirmation (Y or N), unless you specified the /Y(es) option. If you respond with a Y, DEL will delete all the files in that subdirectory (except for hidden, system, and read-only files). If you do not use the /Q(uiet) option, DEL displays a count of files deleted, and the total space freed by the deletions. To improve performance, DEL calculates the space freed by comparing space available on the drive before and after the deletions, rather than checking the size of each file. Therefore, if other programs are allocating or deallocating disk space while a DEL command is in process, the figure for space freed may reflect the results of those other operations as well as those of the DEL command itself. If DEL finds that free space on your drive has decreased or remained the same after the deletions, the space freed is not displayed. This may happen if other programs are modifying the disk while DEL is running, or if you have enabled DELDIR to save deleted files for recovery (see your OS/2 documentation for information on DELDIR). EXAMPLES Erase all the files in the current directory with a .BAK or .PRN extension: del *.bak *.prn Delete the entire subdirectory tree starting with C:\UTIL, including hidden and read-only files, without further prompting (use with caution!): del /sxyz c:\util ═══ 3.16. DELAY - Pause for specified time ═══ SYNTAX (Internal 4OS2) DELAY [seconds] PURPOSE Pause for a specified period of time. COMMENTS DELAY is useful in batch file loops while waiting for a condition to occur. The default value is one second. If you need a shorter delay, use BEEP with a frequency < 37 Hz. You can cancel a DELAY loop by pressing ^C. See also BEEP. EXAMPLE Wait for 10 seconds: delay 10 ═══ 3.17. DESCRIBE - Describe files ═══ SYNTAX (Internal 4OS2) DESCRIBE [d:][path]filename... ["description"] PURPOSE Create, modify, or delete file and subdirectory descriptions. COMMENTS DESCRIBE adds descriptions to filenames and subdirectories. The descriptions will be displayed when using DIR with the default single column option, or when using SELECT. If you're using 4OS2 on an HPFS volume, descriptions will only be displayed if you use the DIR or SELECT /Z (FAT format) option. The default maximum description length is 40 characters; if you have a screen capable of displaying more than 80 columns, you can increase the maximum description length with the 4OS2.INI DescriptionMax option. File descriptions allow you to identify your files in much more meaningful ways than an eight character filename. You can enter a description on the command line by entering the filename followed by the description enclosed in quotes. Using wildcards and/or multiple filenames with a description on the command line will give all matching files the same description. Descriptions are stored in each directory in a hidden file called DESCRIPT.ION. Use the ATTRIB command to "unhide" this file if you need to copy or delete it. The description file is modified appropriately whenever you perform an internal command (such as COPY, DEL, MOVE, or RENAME), but not if you use an external command (such as REPLACE or XCOPY). See also DIR and SELECT. EXAMPLES Create a description for the file MEMO.TXT interactively: describe memo.txt Create the same description in a single command: describe memo.txt "Memo to Bob about party" ═══ 3.18. DETACH - Start detached process ═══ SYNTAX (Internal 4OS2) DETACH [d:][command ...] PURPOSE Start OS/2 commands in detached mode. COMMENTS A command started with DETACH cannot use the keyboard, mouse, or video display. You can redirect standard I/O to other devices if necessary. 4OS2 always detaches another copy of 4OS2.EXE to execute the command. This allows you to deatch any type of command including an alias, internal command, external command, or batch file. The entire command line after DETACH is passed to the detached process. If you place multiple commands on the line after DETACH, all those commands will be run by the detached copy of 4OS2. The current copy of 4OS2 will continue with the first command on the next line. EXAMPLES Detach a CHKDSK command and redirect its output to the file CHECK.DAT: detach chkdsk >& check.dat Detach CHKDSK commands for drives C and D, redirecting the output of each to the file CHECK.DAT in the root directory of the corresponding drive: detach chkdsk c: >& c:\check.dat & chkdsk d: >& d:\check.dat ═══ 3.19. DIR - Display directory ═══ SYNTAX (Internal 4OS2) DIR [/1 /2 /4 /A[:-rhsda] /B /C /D /F /J /K /L /M /N /O:-deginrsu /P /S /T[:acw] /U /V /W /Z] [[d:][path]filename...] PURPOSE Display information about files and subdirectories. COMMENTS DIR displays information about the files and subdirectories in the specified directory. Depending upon the options specified, DIR can show the filename, file attributes, size, date and time of the most recent change to the file, and the file description. For files on HPFS drives, the /T:acw switch can be used to specify whether to display the date and time of last access, file creation, or last write. The DIR options are: /1 Single column display - display the filename, size, date, time, and description. This is the default. /2 Two column display - display the filename, size, date, and time. /4 Four column display - display the filename and size, in K(ilobytes) or M(egabytes). /A Display only those files that have the specified attribute set. A /A with no attributes will display all files, including hidden and system files. Preceding the attribute character with a '-' will display those files that do not have that attribute set. Attributes can also be combined. The attributes are: R Read only H Hidden S System D Directory A Archive /B Suppress header line and summaries, and display file or subdirectory names only, in a single column (useful when redirecting output to a file or another program). /C Display FAT filenames in upper case (like CMD.EXE). See also SETDOS /U. /D Disable directory colorization. /F Display fully expanded filenames (including drive & path) in one column. /J Justify filenames (same format as CMD.EXE). /K Suppress the header display. /L Display FAT filenames in lower case. This option will not convert extended ASCII characters to lower case. /M Suppress the footer display. /N Display a FAT volume in HPFS format. /O Sort order; any combination of the following options: - Reverse the sort order for the next option a Sort by ASCII value rather than numeric value d Sort by date and time (oldest first; also see /T:acw below) e Sort by extension g Group subdirectories together i Sort by the file description n Sort by the filename (this is the default) r Reverse the sort order for all options s Sort by size u Unsorted /P Pause after each screen page and wait for a key to be pressed (useful for displaying long directory listings). /S Display contents of the current directory and all of its subdirectories. DIR will only display headers and summaries for those directories with matching filenames. /T Display the filenames and attributes only (see ATTRIB), in the format RHSA, where: R Read only H Hidden S System A Archive When displaying attributes, DIR cannot display file descriptions. /T:acw Select the date and time used for file date / time displays and date / time sorts on HPFS drives. This option is ignored for FAT drives. Use any one of the following options: a Use date and time of last access c Use date and time of creation w Use date and time of last write If /T is used without a date / time type (:acw) after it, 4OS2 will display the file attributes (see /T above). /U Display summary only (number of files & bytes used; both actual file size and the disk space used). /V Display filenames sorted vertically rather than horizontally (with the /2, /4, or /W option). /W Wide display - display the filenames only, horizontally across the screen (5 columns on an 80-character display). /Z Display an HPFS volume in FAT format. Filenames longer than 12 characters will be truncated. DIR allows wildcard characters in the filename. If you don't specify a filename, DIR defaults to *.* (display all files and subdirectories in the current directory). If you append filenames with a ; (an "include list"), DIR will display the matching filenames in a single directory listing. Only the first file in an include list can have a path. You can display the subdirectories and files in color by setting the COLORDIR variable. The format for COLORDIR is: ext [...]:[bright][blink] fg [ON bg]; ... where "ext" is the file extension, or one of the following file attributes: DIRS - directory RDONLY - read-only file HIDDEN - hidden file SYSTEM - system file ARCHIVE - file modified since last backup For example, to display the .COM and .EXE files in red, the .C and .ASM files in bright cyan, and the read-only files in blinking green: set colordir=com exe:red; c asm:bright cyan; rdonly:blink green If you don't select a background color, DIR will use the current screen background color. If a country code was defined in the CONFIG.SYS file or by the CHCP command, DIR will display the date in the format for that country. The default date format is U.S. (mm-dd-yy). Options on the command line apply only to the filenames that follow the option, except that options at the end of the line apply to the preceding filename only. This allows you to specify several options for a group of files, and retains compatibility with CMD.EXE when a single filename is specified. See also DESCRIBE and SELECT. EXAMPLES Display the .WKS files, and then the .WK1 files in the current directory: dir *.wks *.wk1 Display the .WKS and .WK1 files together (an "include list"): dir *.wks;*.wk1 Display the files on drive C, including hidden and system files, pausing after each page: dir /a/sp c:\*.* ═══ 3.20. DIRS - Display directory stack ═══ SYNTAX (Internal 4OS2) DIRS PURPOSE Display the current directory stack. COMMENTS DIRS displays the directory stack used by PUSHD and POPD, oldest entries first. The stack holds 255 characters (about 10 to 20 entries). See also PUSHD and POPD. EXAMPLE Change directories and then display the directory stack: pushd c:\database pushd d:\wordp\memos dirs ═══ 3.21. DPATH - Display / set data search path ═══ SYNTAX (Internal 4OS2) DPATH [[d:]path][[;[d:]path]...]] DPATH ; PURPOSE Tells applications where to search for their files. COMMENTS If you enter DPATH with no parameters, 4OS2 displays the current search path. If you enter DPATH and a semicolon (;), 4OS2 clears the search path. You can edit an existing DPATH with the ESET command. EXAMPLES The following DPATH command directs applications to search for their data files in the following order: the current directory, the root directory on drive C, the OS2 subdirectory on drive C, and the UTIL subdirectory on drive C: dpath c:\;c:\os2;c:\util Display the current DPATH: dpath ═══ 3.22. DRAWBOX - Draw a box ═══ SYNTAX (Internal 4OS2) DRAWBOX ulrow ulcol lrrow lrcol style [bright][blink] fg ON bg [FILL bgfill] [SHADOW] PURPOSE Draw a box on the screen. COMMENTS DRAWBOX is useful for creating attractive screen displays in batch files. DRAWBOX 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). The row and column numbering is zero-based, so on a standard 25 line by 80 column display, valid rows are 0 - 24 and valid columns are 0 - 79. The DRAWBOX parameters are: 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 line drawing characters (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) SHADOW Include a transparent drop shadow Only the first three characters of the color name and attributes ("bright" and "blink") are required. The available colors are: Black Blue Green Red Magenta Cyan Yellow White See also DRAWHLINE and DRAWVLINE. EXAMPLE Draw a single line box around the entire screen with bright white lines on a blue background: drawbox 0 0 24 79 1 bright white on blue fill blue ═══ 3.23. DRAWHLINE - Draw horizontal line ═══ SYNTAX (Internal 4OS2) DRAWHLINE row column length style [bright] [blink] fg ON bg PURPOSE Draw a horizontal line on the screen. COMMENTS DRAWHLINE is useful for creating attractive screen displays in batch files. DRAWHLINE 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). The row and column numbering is zero-based, so on a standard 25 line by 80 column display, valid rows are 0 - 24 and valid columns are 0 - 79. The DRAWHLINE parameters are: row Start row column Start column length Length of line style Line drawing style: 1 Single line 2 Double line fg Foreground character color bg Background character color Only the first three characters of the color name and attributes ("bright" and "blink") are required. The available colors are: Black Blue Green Red Magenta Cyan Yellow White See also DRAWBOX, DRAWVLINE and SCRPUT. EXAMPLE Draw a double line along the top row of the display with green characters on a blue background: drawhline 0 0 79 2 green on blue ═══ 3.24. DRAWVLINE - Draw vertical line ═══ SYNTAX (Internal 4OS2) DRAWVLINE row column length style [bright] [blink] fg ON bg PURPOSE Draw a vertical line on the screen. COMMENTS DRAWVLINE is useful for creating attractive screen displays in batch files. DRAWVLINE 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). The row and column numbering is zero-based, so on a standard 25 line by 80 column display, valid rows are 0 - 24 and valid columns are 0 - 79. The DRAWVLINE parameters are: row Start row column Start column length Length of line style Line drawing style: 1 Single line 2 Double line fg Foreground character color bg Background character color Only the first three characters of the color name and attributes ("bright" and "blink") are required. The available colors are: Black Blue Green Red Magenta Cyan Yellow White See also DRAWBOX, DRAWHLINE, and VSCRPUT. EXAMPLE Draw a double line along the left margin of the display with bright red characters on a black background: drawvline 0 0 24 2 bright red on black ═══ 3.25. ECHO - Display a message ═══ SYNTAX (Internal 4OS2) ECHO [on | off | message] PURPOSE Display the echo status, enable or disable batch file or command line echoing, or display a message. COMMENTS ECHO defaults to ON in batch files. To prevent a line from being echoed, preface it with the @ symbol. You can default to ECHO OFF by setting the SETDOS /V option to 0. (Setting SETDOS /V to 2 will echo all lines, regardless of the echo state or @ symbols.) The current ECHO state is inherited by called batch files. ECHO defaults to OFF during keyboard input. If you set ECHO ON from the command line, the fully parsed and expanded commands (including aliases and variables) will be displayed before they are executed. The keyboard 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. If no arguments are entered, ECHO displays the current echo state. ECHO commands in a batch file will send messages to the screen while the batch file executes, even if ECHO is set OFF. You cannot use the command separator character or the redirection symbols (|><) in an ECHO message, unless you enclose them in quotes or precede them with the escape character. If you want to echo a blank line, enter: echo. See also ECHOS, SETDOS, SCREEN, SCRPUT, TEXT and VSCRPUT. EXAMPLES Enable command line echoing: echo on Display a message in a batch file: echo Processing your print files... Turn off batch file echoing, without displaying the ECHO command itself: @echo off ═══ 3.26. ECHOS - Display a message with no CR/LF ═══ SYNTAX (Internal 4OS2) ECHOS message PURPOSE Display a message, without printing a trailing CR/LF. COMMENTS ECHOS is useful for outputting text when you don't want ECHO to add a carriage return / linefeed pair (for example, when redirecting control sequences to a printer). You cannot use the command separator character or the redirection symbols (|><) in an ECHOS message, unless you enclose them in quotes or precede them with the escape character. See also ECHO. EXAMPLE Send a control sequence (an Esc+H) to the printer. echos ^eH > lpt1: ═══ 3.27. ENDLOCAL - Restore saved environment ═══ SYNTAX (Internal 4OS2) ENDLOCAL PURPOSE Restore the saved disk drive, directory, aliases, and environment. COMMENTS ENDLOCAL restores the disk drive, directory, aliases, and environment variables saved by the previous SETLOCAL command. SETLOCAL and ENDLOCAL can only be used in batch files, not in aliases. See also SETLOCAL. EXAMPLE This batch file fragment saves the aliases, environment, drive, and current working directory, changes the drive and directory, modifies some environment variables, runs the program TEST1, and then restores the original values: setlocal cdd d:\test set path=c:\;c:\dos;c:\util set lib=d:\lib test1 endlocal ═══ 3.28. ESET - Edit variable or alias ═══ SYNTAX (Internal 4OS2) ESET [/A] varname... PURPOSE Edit environment variables and/or aliases. COMMENTS ESET allows you to edit your environment variables and aliases using the line editing commands. The cursor will be positioned at the first character of the variable or alias. The ESET options are: /A Assume the argument is an alias. This allows you to edit an alias with the same name as an environment variable. ESET will search for environment variables first, and then aliases. Environment variable and alias names are limited to 80 characters, and their arguments to 255 characters. See also Editing the Command Line, ALIAS, UNALIAS, SET, and UNSET. EXAMPLES Edit the executable file search path: eset path Create and then edit an alias: alias d dir /djp eset d ═══ 3.29. EXCEPT - Exclude files from command ═══ SYNTAX (Internal 4OS2) EXCEPT ([d:][path]filename...) command PURPOSE Perform a command, except on the file(s) specified. COMMENTS EXCEPT provides a means of executing a command on a group of files and/or subdirectories, except those enclosed within the parentheses. The command can be an internal command or alias, an external command, or a batch file. You may use wildcard characters in a filename. When using filename completion (TAB or F9) to get 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. EXCEPT prevents operations on the specified file(s) by setting the hidden attribute, performing the command, and then clearing the hidden attribute. If EXCEPT is aborted in an unusual way, you may need to use the ATTRIB command to "unhide" (-H) the file(s). EXCEPT will not work with programs or commands that ignore the hidden attribute. See also ATTRIB. EXAMPLE Erase all but the files beginning with MEMO and those ending in .WKS: except (memo*.* *.wks) del *.* ═══ 3.30. EXIT - Exit secondary processor ═══ SYNTAX (Internal 4OS2) EXIT [value] PURPOSE Exit the current command processor. COMMENTS Some application programs will start a secondary copy of the command processor to allow you execute commands. To return to the application again, type EXIT. If you EXIT from a primary command processor, you will be returned to PM. If you specify a value, EXIT will return that value to the parent process. EXAMPLE Return to the parent process: exit ═══ 3.31. FOR - Repeat a command ═══ SYNTAX (Internal 4OS2) FOR [/A[:-RHSDA]] %%var IN (set) [DO] command PURPOSE Repeat a command for several variables. COMMENTS FOR sets var sequentially to each member of (set), and then evaluates and executes command for every argument in (set). If an argument in (set) contains wildcard characters, var will be set sequentially to each matching filename on the disk. If a filename in (set) begins with an @, var will be set sequentially to each line in the file. You can nest multiple FOR statements. The only option for FOR is: /A Retrieve only those files with the specified attribute. A /A with no attributes will retrieve all files, including hidden and system files, and subdirectories. Preceding the attribute character with a '-' will retrieve those files that DON'T have that attribute set. Attributes can also be combined. The attributes are: R Read only H Hidden S System D Directory A Archive The command can be an internal command or alias, an external command, or a batch file. In CMD.EXE you must use a single % for the variable name from the command line, and %% when in a batch file. 4OS2 will accept either % or %% in either case. CMD.EXE requires the variable name to be a single character; 4OS2 supports variable names up to 80 characters. CMD.EXE requires the word DO on the command line; it is optional in 4OS2. EXAMPLES The following example compiles the C programs in the current directory that have a "2" or a "3" somewhere in their name: for %a in (*2*.c *3*.c) do cl %a ; The following example uses variable functions to delete the .BAK files for which a corresponding .TXT file exists in the current directory: for %a in (*.txt) if exist %@name[%a].bak del %@name[%a].bak ═══ 3.32. FREE - Display disk utilization ═══ SYNTAX (Internal 4OS2) FREE [d:] ... PURPOSE Display the total disk space, total bytes used, and total bytes free on the specified (or default) drive(s). COMMENTS FREE provides the same disk information as the external command CHKDSK, but without the wait. EXAMPLE Display the status of drives A, B, and C: free a: b: c: ═══ 3.33. GLOBAL - Execute command in all subdirectories ═══ SYNTAX (Internal 4OS2) GLOBAL [/H /I /P /Q] command PURPOSE Execute a command in the current directory and its subdirectories. COMMENTS GLOBAL performs the specified command first in the current directory, and then in every subdirectory under the current directory. The command can be an internal command or alias, an external command, or a batch file. The GLOBAL options are: /H Process hidden subdirectories. /I Ignore exit codes. If this option is not specified, GLOBAL will terminate if the command returns a non-zero exit code. /P Prompt for a Y/N whether to execute the command in each directory. /Q Do not display the directory names as each directory is accessed. EXAMPLE Copy the files in every directory on drive A to the directory C:\TEMP: cd a:\ & global copy a:*.* c:\temp ═══ 3.34. GOSUB - Call batch subroutine ═══ SYNTAX (Internal 4OS2) GOSUB label PURPOSE Call a subroutine in a batch file. COMMENTS GOSUB calls the specified label as a subroutine. The subroutine must end with a RETURN statement. After the RETURN, the batch file continues with the command following the GOSUB command. GOSUB searches for the label starting at the first line of the batch file. If the label doesn't exist, the batch file is terminated with the error message "Label not found." The label must begin with a colon (:), and appear by itself on the line. GOSUB ignores case differences when matching labels. See also GOTO and RETURN. EXAMPLE The following batch file fragment calls a subroutine that displays the directory and returns: echo Calling a subroutine gosub subr1 echo Returned from the subroutine quit :subr1 dir /hw return ═══ 3.35. GOTO - Jump to batch label ═══ SYNTAX (Internal 4OS2) GOTO [/I] label PURPOSE Continue batch file processing at the line following the label. COMMENTS GOTO changes the current position in the batch file to the line immediately following the label. The search for the label starts at the first line of the batch file. If the label doesn't exist, the batch file is terminated with the error message "Label not found." The label must begin with a colon (:), and appear by itself on the line. GOTO ignores case differences when matching labels. A GOTO will cancel all IFF nesting, unless you specify the /I option. See also GOSUB. EXAMPLE The following batch file fragment checks for the existence of the file CONFIG.SYS. If CONFIG.SYS exists, GOTO jumps to C_EXISTS and copies all the files from the current directory to the root directory on A. If CONFIG.SYS doesn't exist, the batch file prints an error message and exits. if exist config.sys goto C_EXISTS echo CONFIG.SYS doesn't exist - exiting quit :c_exists copy *.* a:\ ═══ 3.36. HELP - Display 4OS2 online help ═══ SYNTAX (Internal 4OS2) HELP [command] PURPOSE Display the 4OS2 help file. COMMENTS HELP uses the PM VIEW.EXE program to display help for 4OS2 (4OS2.INF) and OS/2 in general (CMDREF.INF). You can change the default .INF files with the HelpBook directive in 4OS2.INI. EXAMPLES Display the HELP table of contents: help Display help for the DIR command: help dir ═══ 3.37. HISTORY - Display / set command history ═══ SYNTAX (Internal 4OS2) HISTORY [/A command] [/F /P] [/R [d:][path]filename] PURPOSE Display, read, or clear the history list. COMMENTS If no parameters are entered, HISTORY displays the current history list. The HISTORY options are: /A Add the specified command to the history list. /F Clear the command history list. /P Prompt for a key after displaying each page. /R Read the command history from the specified file. You can save the history list by redirecting the output of HISTORY to 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 8192 characters. The default size is 1024 characters. You can disable saving commands to the history list, or specify a minimum command line length to save, with the HistMin directive in 4OS2.INI. EXAMPLES Display the history list: history Clear the history entries: history /f Save the history list to the file HISTFILE, and then read it in again: history > histfile history /r histfile ═══ 3.38. IF - Conditional command execution ═══ SYNTAX (Internal 4OS2) IF [NOT] condition [.AND. | .OR. | .XOR. [NOT] ...] command PURPOSE Allow conditional execution of commands. COMMENTS IF first tests the given condition. If the condition is true, IF executes the specified command, otherwise the command will be ignored. If you use the NOT option, the command is executed only when the condition is false. IF statements can be nested. The command can be an internal command or alias, an external command, or a batch file. For the string tests, case differences are ignored. When comparing strings, you should enclose them in double quotes (see examples). The use of double quotes reduces problems when the strings being compared contain characters that may have another meaning to the parser. If the strings begin with a digit, IF will do a numeric comparison. Otherwise, IF does an ASCII comparison. The .AND., .OR., and .XOR. tests allow you to combine tests in an IF statement. The expressions are scanned from left to right. The condition can be any of the following: string1 == string2 or string1 EQ string2 If string1 is equal to string2, the condition is true. string1 != string2 or string1 NE string2 If string1 is not equal to string2, the condition is true. string1 LT string2 If string1 is < string2, the condition is true. string1 LE string2 If string1 is <= string2, the condition is true. string1 GE string2 If string1 is >= string2, the condition is true. string1 GT string2 If string1 is > string2, the condition is true. In the tests below, the term "condition" refers to one of the relational operators described for the string tests above (==, EQ, NE, LT, etc.). ERRORLEVEL [condition] number Test the exit code of the preceding external program. If no relational operator (EQ, GT, etc.) is specified, the default is GE. NOTE: Not all programs return an explicit exit code. In those cases, the behavior of ERRORLEVEL is undefined. EXIST [d:][path]filename If the file exists, the condition is true. You can use wildcard characters in the filename, in which case the condition is true if any file matching the wildcards exists. ISALIAS aliasname If the specified name is an alias, the condition is true. ISDIR [d:]path If the subdirectory exists, the condition is true. ISINTERNAL command If the specified command is an internal command, the condition is true. ISLABEL labelname If the specified label exists in the current batch file, the condition is true. See also IFF. EXAMPLES Test for the presence of A:\JAN.DOC and copy it to the root directory on drive C if it exists: if exist a:\jan.doc copy a:\jan.doc c:\ This batch file fragment tests for a string value: if "%cmd" == "wp" goto wordproc if "%cmd" NE "graphics" goto badentry Test for more than 500K of free disk space on drive A: if %@diskfree[a:] gt 500 echo More than 500K free Run the program MONOPROG if the monitor type is monochrome: if %_monitor == mono monoprog ═══ 3.39. IFF - Conditional command execution ═══ SYNTAX (Internal 4OS2) IFF [NOT] condition [.AND. | .OR. | .XOR. [NOT] ...] THEN & ... & ELSE[[IFF] ... THEN] & ... & ENDIFF PURPOSE Allow IF/THEN/ELSE conditional execution of commands. COMMENTS IFF first tests the given condition. If the condition is true, IFF executes the specified command(s) until the next ELSE, ELSEIFF, or ENDIFF; otherwise the command(s) will be ignored and parsing will continue at the next ELSE, ELSEIFF, or ENDIFF. If you use the NOT option, commands are executed only when the condition is false. IFF statements can be nested up to 15 levels deep. The .AND., .OR., and .XOR. tests allow you to combine tests in an IFF statement. The expressions are scanned from left to right; each new .AND., .OR., or .XOR. tests the combination of all preceding tests. The command can be an internal command or alias, an external command, or a batch file. If you do a GOTO inside an IFF, GOTO assumes you are jumping outside the IFF statement. You cannot GOTO another part of the same IFF, or inside another IFF statement. See the IF command for a list of the tests available. EXAMPLES The following batch file fragment tests the monitor type (monochrome or color), and sets the appropriate colors and prompt: iff %_monitor == color then color bright white on blue & cls prompt=$e[s$e[1;1f$e[41;1;37m$e[K Path: $p$e[u$e[44;37m$n$g else prompt=$e[s$e[1;1f$e[0;7m$e[K Path: $p$e[u$e[0m$n$g endiff The following alias checks to see if the argument is a subdirectory. If so, the alias deletes the subdirectory's files and removes it (enter this on one line): alias zap `iff isdir %1 then & del /s/x/z %1 & else & echo Not a directory! & endiff` ═══ 3.40. INKEY - Enter environment variable ═══ SYNTAX (Internal 4OS2) INKEY [/K"..." /Wn] [text] %%varname PURPOSE Get a single keystroke environment variable from standard input. COMMENTS You can optionally display prompt text before the variable name. The INKEY options are: /K The allowable keystrokes, enclosed in double quotes. If you want to read a control or function key, you must enclose it in square brackets (for example, /K"ab[F1][F10]"). The valid key names are the same as those listed in the section on Key Mapping Directives in KEYCODES. /W Timeout period, where "n" is the number of seconds to wait for a response. If no keystroke is entered by the end of the timeout period, INKEY returns with the variable unchanged. You can specify /W0 to check if a keystroke is waiting, and return immediately. ASCII values from 1 to 255 are stored as a character. Extended characters (for example, function keys & cursor keys) are stored as a string in decimal format, with a leading @ (for example, the F1 key is stored as @59). The ENTER character is a special case; it is stored as its scan code (@28). See KEYCODES for the common extended keystrokes. INKEY and INPUT are normally used as batch file commands, allowing you great flexibility in entering or changing batch variables. If you press ^C or ^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 prompted whether to cancel the batch job. See also INPUT. EXAMPLES Prompt for a number and store it in the variable NUM: inkey /K"123456789" Enter a number from 1 to 9: %%num The following batch file fragment waits up to 10 seconds for a character, then tests to see if a "Y" was entered: set net=N inkey /w10 Do you want to load the network (Y/N)? %%net if "%net"=="Y" goto load_net ═══ 3.41. INPUT - Enter environment variable ═══ SYNTAX (Internal 4OS2) INPUT [/Wn] [text] %%varname PURPOSE Enter an environment variable from the standard input. COMMENTS You can optionally display prompt text before the variable name. The only INPUT option is: /W Specify a timeout period, where "n" is the number of seconds to wait for a response. If no keystroke is entered by the end of the timeout period, INPUT returns with the variable unchanged. If you enter a key before the timeout period, INPUT will wait indefinitely for the remainder of the line. You can specify /W0 to check if a key is already in the buffer, and return immediately. All characters entered up to, but not including, the carriage return are stored in the variable. INPUT and INKEY are normally used as batch file commands, allowing you great flexibility in entering or changing batch variables. See also INKEY. EXAMPLE The following batch file fragment prompts for a string and stores it in the variable FNAME: input Enter the file name: %%fname ═══ 3.42. KEYS - Display command history ═══ SYNTAX (Internal 4OS2) KEYS [ON | OFF | LIST] PURPOSE Display the history list, or enable / disable the command line editing keys. COMMENTS 4OS2 includes this command for compatibility with CMD.EXE; for 4OS2 you should normally use the HISTORY command instead. KEYS OFF will disable the command history and force 4OS2 to read input a line at a time (normally input is processed one character at a time). Applications which intercept line input intended for the command processor may not work properly unless you use KEYS OFF to switch to line input mode before starting the application (such applications are very rare). KEYS ON will reenable the command history and return input to the usual character by character method. ═══ 3.43. LIST - Display files ═══ SYNTAX (Internal 4OS2) LIST [/H /S /W] [d:][path]filename... PURPOSE Display a file with forward and backward paging and scrolling. COMMENTS LIST provides a much faster and more flexible way to view a file than TYPE, without the overhead of using a text editor. The LIST options are: /H 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. /S Read from the standard input rather than a file. This allows you to redirect command output and view it with LIST. /W Wrap the text at the right margin. This option is useful when displaying non-text files. LIST uses the cursor pad to scroll through the file. The LIST commands are (the caret ^ means press the Ctrl key together with the specified key): HOME Display the first page of the file END Display the last page of the file PgUp Scroll back one page PgDn Scroll forwards one page Esc Exit the current file ^C Quit LIST  Scroll up one line  Scroll down one line  Scroll left 8 columns  Scroll right 8 columns ^ Scroll left 40 columns ^ Scroll right 40 columns F1 Call the on-line help F Prompt and search for a string (case is ignored) H Toggle the "strip high bit" (/H) option N Find next matching string (case is ignored). LIST saves the search string, so you can LIST multiple files and search for the same string by pressing N in each file. P Print the file on LPT1 W Toggle the "line wrap" (/W) option LIST is normally only useful for displaying ASCII text files; executable files (.COM and .EXE) and many data files will be unreadable due to the presence of non-alphanumeric characters. See also TYPE. EXAMPLES Display the file MEMO.DOC: list memo.doc Display the output from a DIR command: dir | list /s ═══ 3.44. LOADBTM - Change batch file mode ═══ SYNTAX (Internal 4OS2) LOADBTM [on | off] PURPOSE Switch a batch file to or from .BTM mode. COMMENTS LOADBTM switches a batch file (.CMD or .BTM) to and from .BTM mode. If no argument is given, it displays the current LOADBTM status. .BTM mode runs from two to five times faster than normal batch mode, but should not be used for self-modifying batch files. LOADBTM can only be used within a .CMD or .BTM file. See the 4OS2 / 4DOS manual for more information on .BTM files. EXAMPLE The following .CMD batch file fragment tests if 4OS2 is the current command processor; if so, it switches to BTM mode: Rem The initial default state is LOADBTM OFF if "%@eval[2+2]" == "4" loadbtm on ═══ 3.45. LOG - Log commands to file ═══ SYNTAX (Internal 4OS2) LOG [/W [d:]pathname] [ON | OFF | "text"] PURPOSE Save a log of commands to a disk file. COMMENTS The default 4OS2 LOG filename is 4OS2LOG in the root directory of the boot drive. The LOG status and log filename will be passed to secondary shells. Entering LOG with no parameters displays the log status (ON or OFF). Entering LOG with text writes the text to the log file, even if LOG is set OFF. This allows you to enter headers in the log file. You can specify a different filename with the /W(rite) option. /W automatically enables command logging. The commands are stored in the log file as they are executed, after performing any alias or variable expansion. The LOG file format looks like: [mm/dd/yy hh:mm:ss] command. EXAMPLES Display the LOG status: log Enable command logging: log on Enable command logging to the file C:\LOG\LOGFILE and insert a header: log /w c:\log\logfile log "Started work on the database system" ═══ 3.46. MD or MKDIR - Create subdirectory ═══ SYNTAX (Internal 4OS2) MD [d:]pathname... MKDIR [d:]pathname... PURPOSE Create subdirectories. COMMENTS To start at the root directory, start the pathname with a backslash (\). To start at the parent directory, start the pathname with two periods (..). All other pathnames start at the current directory. See also RD. EXAMPLE Create a subdirectory called MYDIR in the root directory: md \mydir ═══ 3.47. MEMORY - Display system memory ═══ SYNTAX (Internal 4OS2) MEMORY PURPOSE Display the system RAM status. COMMENTS MEMORY displays the size of the largest free block of RAM, the size of the OS/2 swap file, the total and free environment space, the total and free alias list space, and the total command history space. Swap file size is displayed only if the swap file is located in the \OS2\SYSTEM directory on the boot drive (this is the default location). OS/2 provides virtual memory and swaps applications to disk as needed. This makes the size of the largest available free block of RAM as reported by MEMORY only a general reflection of available memory resources, and not a precise statement of the amount of RAM available for applications. In 4OS2/32 only, MEMORY also displays the size of physical and resident RAM. EXAMPLE Display your RAM totals: memory ═══ 3.48. MOVE - Move files ═══ SYNTAX (Internal 4OS2) MOVE [d:][path]filename... [d:][path][filename] [/C /D /H /N /P /Q /R /S /U] PURPOSE Move files to other directories and drives. COMMENTS The MOVE command moves the specified file(s) to the last filename specified, which is designated as the target. If the target already exists, it is deleted when the file is moved. You cannot move a file to itself. If there is more than one source file specification, the target must be a directory, and the files are moved to the directory with their original filenames. If the target is not a directory, MOVE will display an error message and exit. Use caution when using MOVE commands with commands like SELECT. If multiple files are selected and the target is not a subdirectory, each file will be moved in turn to the target, overwriting the previous file. The net result is that all files but the last will be deleted. If SELECT is invoked using square brackets instead of parentheses, the MOVE will be done in a single command and MOVE will detect the error. The MOVE options are: /C Move only files that exist in the target directory, and where the source file is newer than the target. /D The target must be a directory. If it doesn't exist, you will be prompted whether to create it. /H Move all files, including hidden & system. /N Do everything except actually move the file(s) (for testing what the result of a MOVE would be). /P Prompt for a Y or N response to confirm each move. /Q Don't display filenames as they are moved. /R Prompt for a Y or N response before overwriting an existing file. /S Move an entire subdirectory tree to another location. The target directories will be created if they don't exist (except for the first target, which must already exist). MOVE will remove empty subdirectories after the move. /U Move only those files that either don't exist in the target directory, or where the source file is newer than the target. MOVE first attempts to rename the file(s). If that fails (the target is on a different drive, or the target already exists), MOVE will copy the file(s) and then delete the originals. If MOVE cannot delete the original (for example, a read-only file), it will display an error message, but the target file is still created. See also COPY and REN. EXAMPLES Move some files to a different directory: move *.wks *.txt c:\finance\myfiles Move all the files in the current directory to A:\, prompting before overwriting any existing files: move /r *.* a:\ ═══ 3.49. PATH - Set executable file search path ═══ SYNTAX (Internal 4OS2) PATH [[d:]path][[;[d:]path]...]] PATH ; PURPOSE Tells 4OS2 where to search for executable and batch files not in the current directory. COMMENTS When searching for an external command (.COM, .EXE, .BTM, and .CMD, in that order), 4OS2 searches the current directory first, then the directories you specify in the PATH, in the order you list them. The directory names are separated by semicolons (;). In OS/2 2.0, 4OS2 will also search for MS-DOS .BAT files (following .CMD in the search order), for compatibility with CMD.EXE. If you enter PATH with no parameters, PATH displays the current search path. If you enter PATH and a semicolon (;), PATH clears the search path and will search only the current directory (this is the default at system startup). If you specify an invalid directory, 4OS2 will skip that directory and continue searching with the next directory in the path. If you have a directory '.' in the PATH, 4OS2 will not search the current directory first, but will wait to do so until it reaches that point in the PATH. Some applications also use the PATH variable to search for their files. You can edit an existing path with the ESET command. EXAMPLES The following PATH command sets the search path to the following order: the current directory, the root directory on drive C, the OS2 subdirectory on drive C, and the UTIL subdirectory on drive C: path c:\;c:\os2;c:\util Display the current search path: path ═══ 3.50. PAUSE - Wait for keystroke ═══ SYNTAX (Internal 4OS2) PAUSE [message] PURPOSE Suspend alias or batch file execution. COMMENTS A PAUSE command will suspend execution, giving you the opportunity to perform activities such as changing disks, turning on the printer, etc. PAUSE waits for any key (except ^C or ^BREAK) to be pressed and then continues executing. If a prompt message is specified, PAUSE will display the message and wait for a keystroke. Otherwise, PAUSE will prompt: Press a key when ready... If you press a ^C or ^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 prompted whether to cancel the batch file. EXAMPLE The following batch file fragment prompts the user before erasing files: pause ^C aborts, any other key erases the .LST files: erase *.lst ═══ 3.51. POPD - Restore saved directory ═══ SYNTAX (Internal 4OS2) POPD [*] PURPOSE Change to the disk drive and directory at the top of the directory stack. COMMENTS POPD restores the disk and directory saved using PUSHD (most recent first). The * option clears the directory stack, without changing the current drive and directory. Use the DIRS command to display the directory stack. See also DIRS and PUSHD. EXAMPLES Save and change your disk drive with PUSHD, and then restore it: pushd d:\database\test popd Clear the directory stack: popd * ═══ 3.52. PROMPT - Change command prompt ═══ SYNTAX (Internal 4OS2) PROMPT [text] PURPOSE Change the command line prompt. COMMENTS If you enter PROMPT with no parameters, PROMPT sets the prompt on drives A and B to $n$g (display current disk only), and on all other drives to $p$g (display current disk and directory). The prompt text can contain special strings of the form $?, where ? is one of the following: b The | character c The open parenthesis ( D Current date, in the format: Fri Dec 25, 1992 d Current date, in the format: Fri 12-25-92 e The ASCII ESC character (decimal 27) f The close parenthesis ) g The > character h BACKSPACE over the previous character i The default OS/2 line 0 prompt l The < character n Default drive letter P Current disk and directory (upper case) p Current disk and directory (lower case) q The = character r The numeric exit code returned by the last external command s The space character t Current time, in the format hh:mm:ss v OS/2 version number, in the format: 2.0 Xd: Current disk and directory (upper case) where d: is the drive specification xd: Current disk and directory (lower case) where d: is the drive specification z Display the current shell nesting level (you must be running 4OS2 as the primary shell in swapping mode). The primary command processor is 0. $ The $ character _ CR/LF (go to beginning of new line) You can embed any environment variable, internal variable, or variable function in your PROMPT string to view system status or resources. When defining the PROMPT to include variables of this type, use two % signs before the variable name, or enclose the prompt string in back-quotes [`] (if you don't, the prompt display will show the value the variable had when the prompt was defined, not the value at the moment the prompt is displayed). For example, to show free RAM to the left of the standard $p$g prompt: prompt [%%@dosmem[K]K] $p$g or prompt `[%@dosmem[K]K] $p$g` See 4OS2 Internal Variables and 4OS2 Variable Functions for lists of the available variables and functions. See also ANSI. EXAMPLE Set the prompt to the current date and time: prompt $d $t $g ═══ 3.53. PUSHD - Save & change directory ═══ SYNTAX (Internal 4OS2) PUSHD [[d:]pathname] PURPOSE Save the current disk and directory. COMMENTS PUSHD saves the current directory on the directory stack, and if a pathname is specified on the command line, changes the disk drive and directory. The directory stack can hold up to 255 characters (about 10 to 20 entries). If you exceed the directory stack size, the oldest directory is removed before adding the current directory. The saved directory is restored on a "last in, first out" basis by the POPD command. The directory stack can be displayed with the DIRS command. See also DIRS and POPD. EXAMPLE Save the current directory and change to C:\WORDP\MEMOS: pushd c:\wordp\memos ═══ 3.54. QUIT - Quit batch file ═══ SYNTAX (Internal 4OS2) QUIT [value] PURPOSE Terminate the current batch file. COMMENTS You can QUIT at any point in a batch file, not just the end. If you QUIT a batch file called from another batch file, you will be returned to the previous file at the command following the original call. To end all batch file processing, use CANCEL. If you specify a value, QUIT will set the ERRORLEVEL to that value. The value also affects the internal variable %_?, and the conditional command separators && and ||. You can also use QUIT in an alias. If you QUIT an alias while inside a batch file, QUIT will end both the alias and the batch file. See also CANCEL. EXAMPLE Check to see if the user entered "quit" and exit if true: input Enter your choice: %%option if "%option" == "quit" quit ═══ 3.55. RD or RMDIR - Remove subdirectory ═══ SYNTAX (Internal 4OS2) RD [d:]path... RMDIR [d:]path... PURPOSE Remove one or more directories. COMMENTS Before removing a subdirectory, you must delete all the files and subdirectories (and their files) in that directory (including any hidden or read-only files). You can use wildcard characters in the directory names. You cannot remove the root directory (\), the current directory (.), or the parent directory (..). See also MD. EXAMPLE Remove the subdirectory MEMOS from the directory WP on the current drive: rmdir \wp\memos ═══ 3.56. REBOOT - Reboot system ═══ SYNTAX (Internal 4OS2) REBOOT [/V] PURPOSE Reboot the system. COMMENTS The only option for REBOOT is: /V Prompt for confirmation (Y or N) before rebooting. REBOOT shuts down the file systems before rebooting the system, to allow the disk caches to finish writing any cached data. EXAMPLE The following command prompts you to verify the reboot: reboot /v ═══ 3.57. REM - Batch file comment ═══ SYNTAX (Internal 4OS2) REM [comment] PURPOSE Put a comment in a batch file. COMMENTS If ECHO is ON, or the SETDOS /V option is set, REM will echo the comment. Otherwise, REM will ignore it. If you don't want to echo the line, preface REM with the @ character. (Setting SETDOS /V to 2 will echo all lines, regardless of the echo state or @ symbols.) The current ECHO state is inherited by called batch files. Enter your comment following the REM, separated by a space or tab. Comments can be up to 295 characters. Everything following a REM will be ignored, including quote characters, the redirection symbols (|><) and the command separator character. An alternate way to put a comment in a batch file is to begin the line with a colon (:). The line will be interpreted as a label and ignored. (Make sure you don't have any actual labels beginning with the same word!) Batch file comments are useful for documenting the purpose for a batch file and the procedures used. EXAMPLE Enter comments in a batch file: rem This batch file provides a menu-based system rem for accessing the rem word processing utilities. rem Clear the screen and get a selection cls ═══ 3.58. REN or RENAME - Rename files ═══ SYNTAX (Internal 4OS2) REN [/N /P /Q] [d:][path]filename... [d:][path]filename RENAME [/N /P /Q] [d:][path]filename... [d:][path]filename PURPOSE Rename files or subdirectories. COMMENTS The last filename is the new name; preceding names are the files or directories to be renamed. You can use wildcard characters in the filenames. The new filename must not already exist. You cannot rename a subdirectory to a new path! The REN options are: /N Do everything except actually rename the file(s) (for testing what the result of a REN would be). /P Confirm each rename (Y or N). /Q Don't display filenames as they are renamed. REN in CMD.EXE only allows a path to be specified with the first file name; the path for the target is always the same as the source. 4OS2 allows you to optionally select the target path, renaming the source file to a new directory on the same disk drive. If you don't specify a path for the target, REN will assume a "CMD.EXE compatible RENAME" and will rename the source file to the new name without moving it to another directory. If you want to rename to a different drive, use MOVE. See also MOVE. EXAMPLES Rename the file MEMO.TXT to OFFICE.TXT: ren memo.txt office.txt Rename the directory \WORDPROC to \WP: ren \wordproc \wp ═══ 3.59. RETURN - Return from batch subroutine ═══ SYNTAX (Internal 4OS2) RETURN PURPOSE Return from a GOSUB (subroutine) call in a batch file. COMMENTS The RETURN command returns from a GOSUB call to the command following the original GOSUB. See also GOSUB. EXAMPLE The following batch file fragment calls a subroutine that displays the current directory: echo Calling a subroutine gosub subr1 echo Returned from the subroutine quit :subr1 dir /hw return ═══ 3.60. SCREEN - Position cursor ═══ SYNTAX (Internal 4OS2) SCREEN row column [message] PURPOSE Position the cursor on the screen, and optionally display a message. COMMENTS The row and column numbering is zero-based, so on a standard 25 line by 80 column display, valid rows are 0 - 24 and valid columns are 0 - 79. SCREEN does not change the default screen colors. To display text in specific colors, use SCRPUT. SCREEN checks for a valid row and column, and displays an error message if either value is out of range. See also ECHO, SCRPUT, TEXT, and VSCRPUT. EXAMPLE 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 7 20 2 - Spreadsheet screen 8 20 3 - Telecommunications screen 9 20 4 - Quit ═══ 3.61. SCRPUT - Display text in color ═══ SYNTAX (Internal 4OS2) SCRPUT row column [bright] [blink] fg ON bg text PURPOSE Display text in color. COMMENTS The row and column numbering is zero-based, so on a standard 25 line by 80 column display, valid rows are 0 - 24 and valid columns are 0 - 79. SCRPUT is similar to SCREEN, but allows you to specify the display colors, and writes directly to the screen. The parameters are: row Start row column Start column fg Foreground character color bg Background character color text The text to display Only the first three characters of the color name and attributes ("bright" and "blink") are required. The available colors are: Black Blue Green Red Magenta Cyan Yellow White See also ECHO, SCREEN, TEXT, and VSCRPUT. EXAMPLE The following batch file fragment displays a menu in color: @echo off & cls white on blue scrput 3 10 bri white on blue Select a number from 1 to 4: scrput 6 20 bri red on blue 1 - Word Processing scrput 7 20 bri yellow on blue 2 - Spreadsheet scrput 8 20 bri green on blue 3 - Telecommunications scrput 9 20 bri magenta on blue 4 - Quit ═══ 3.62. SELECT - Select files for command ═══ SYNTAX (Internal 4OS2) SELECT [/A[:-rhsda] /C /D /O:-deginrsu /Z] command ([path]filename) PURPOSE Execute a command on the specified files. COMMENTS SELECT allows you to select command line file arguments by marking the files using a full-screen "point-and-shoot" display. SELECT substitutes the selected files for the argument enclosed in parentheses, and executes the command for each marked file. If you specify multiple arguments in the parentheses, SELECT will display the matching files for the first argument, prompt you to mark the files, execute the command for each marked file, and then continue the same procedure with the next argument. The SELECT options are: /A Display only those files that have the specified attribute set. Preceding the attribute character with a '-' will display those files that DON'T have that attribute set. Attributes can also be combined. The attributes are: R Read only H Hidden S System D Directory A Archive /C Display filenames in upper case. /D Disable directory colorization. /O Sort sequence, where ? can be any combination of the following: - Reverse the sort order for the next option a Sort by ASCII value rather than numeric value d Sort by date and time (oldest first) e Sort by extension g Group subdirectories together i Sort by the file description n Sort by the filename (this is the default) r Reverse the sort order for all options s Sort by size u Unsorted /Z Display HPFS volumes in FAT format, including file descriptions and truncating filenames to 11 characters. If you append filenames with a ; (an "include list"), SELECT will display the matching filenames in a single listing. Only the first filename in an include list can have a path. You can display the file and subdirectory names in color by setting the COLORDIR variable. The format for COLORDIR is: ext [...]:[bright][blink] fg [ON bg]; ... where "ext" is the file extension, or one of the following file attributes: DIRS - directory RDONLY - read-only file HIDDEN - hidden file SYSTEM - system file ARCHIVE - file modified since last backup For example, to display the .COM and .EXE files in red, the .C and .ASM files in bright cyan, and the read-only files in blinking green: set colordir=com exe:red; c asm:bright cyan; rdonly:blink green If you don't select a background color, SELECT will use the current screen background color. If you enclose the arguments in square brackets [ ] rather than parentheses, SELECT will insert all of the arguments into the command line and only execute the command once. You must be careful not to exceed the maximum line length (1023 characters). SELECT uses the cursor up, cursor down, PgUp, and PgDn keys to scroll through the files matching the argument(s). Use the + key to select a file, and the - key to unselect a file. The * key will reverse all of the current marks (excluding subdirectories), and the / key will unmark everything. After marking the files, press ENTER to execute the command. You can select a single file by moving the scroll bar to the filename and pressing ENTER. To cancel the SELECT command, type an Escape, ^C, or ^BREAK. EXAMPLES Select from the files in the current directory with the extension .COM, and then from the files with the extension .EXE to copy to the root directory on drive A: select copy (*.com *.exe) a:\ Select and run an executable program (.COM or .EXE) from files in the C:\UTIL directory (an "include list"): select (c:\util\*.com;*.exe) ═══ 3.63. SET - Display / set environment variables ═══ SYNTAX (Internal 4OS2) SET [/P] [/R [d:][path]filename...] [variable=[value]] PURPOSE Display, create, modify, or delete environment variables. COMMENTS Entering SET with no variable or value displays the entire environment. If you don't enter a value, SET will display the value of that variable. Otherwise, the variable and value are placed in the environment. If the variable already exists, its old contents are replaced by the new value. Variable names are limited to a maximum of 80 characters, and the value to a maximum of 255 characters. The variable names are shifted to upper case before being stored in the environment; the value is stored exactly as entered. The SET options are: /P Pause after displaying a page of environment entries. Press ^C to quit, or any other key to display the next page. /R Read environment variables from a file. This is much faster than loading variables in a batch file. The file is in the same format as the SET display, 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 (:). You can remove multiple environment variables with the UNSET command, and edit environment variables with the ESET command. See also ESET and UNSET. EXAMPLES Display the current environment: set Add a variable to the environment: set mine=c:\finance\myfiles Remove a variable from the environment: set mine= ═══ 3.64. SETDOS - Display / set configuration options ═══ SYNTAX (Internal 4OS2) SETDOS [/C? /E? /I+|-command /M? /P? /N? /R? /S?:? /U? /V?] PURPOSE Display or set 4OS2 configuration options. COMMENTS Most of these options can also be set in 4OS2.INI. The name of the corresponding 4OS2.INI directive for each option, if any, is listed in square brackets [ ] at the end of the description for the option. Use SETDOS rather than 4OS2.INI when you need to make temporary changes. The SETDOS options are: /C The COMPOUND option sets the character used for separating multiple commands on the same line. The default character is the ampersand (&). You cannot use any of the redirection characters (|><), or the whitespace characters (blank, tab, comma, semicolon, or equal) as the command separator. [CommandSep] /E The ESCAPE 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 line. The default escape character is the caret (^). You cannot use any of the redirection characters (|><) or the whitespace characters (blank, tab, comma, semicolon, or equal) as the escape character. [EscapeChar] /I The INTERNAL option allows you to disable or enable internal 4OS2 commands. To disable a command, precede the command name with a minus (-). To reenable a command, precede it with a plus (+). /M The MODE option controls the line editing mode. The default is overstrike mode (/M0). If MODE is set to 1, the default is insert mode. [EditMode] /N The NOCLOBBER option controls output redirection. If NOCLOBBER is set to 1, existing files may not be destroyed by output redirection, and when appending with >>, the output file must exist. NOCLOBBER can be overridden with the ! character. The default value is 0. [NoClobber] /P The PARAMETER option sets the character used to specify argument lists in alias and variable expansion. The default character is $ (in 4DOS it is &). [ParameterChar] /R The ROWS option determines the number of screen rows used by the video display. Normally 4OS2 detects the screen size, but if you have a non-standard display you may need to set it explicitly. The ROWS option does not affect screen scrolling (that is controlled by your video BIOS and OS/2); it is used only for LIST, SELECT, the paged output options (i.e., TYPE /P), and error checking in the screen output commands. [ScreenRows] /S The SHAPE option sets the default cursor shape. The format is /So:i, where "o" is the cursor size for overstrike mode, and "i" the cursor size for insert mode. The size is entered as a percentage of the total character cell size. The default values are 10:100 (a thin underscore cursor for overstrike mode, and a block cursor for insert mode). Because of the way video BIOSes remap the cursor, you may not get a smooth progression in the cursor size from 0 - 100%. To disable the cursor, use /S0:0. [CursorOver, CursorIns] /U The UPPER option controls the way filenames are displayed for the internal commands (COPY, DIR, etc.). If UPPER is 1, filenames will be displayed in upper case. The default is /U0 (filenames will be displayed in lower case). [UpperCase] /V The VERBOSE option controls command echoing in batch files. If VERBOSE is set to 0, batch files will NOT be echoed unless ECHO is set ON. The default is 1 (batch file commands WILL be echoed). If VERBOSE is set to 2, all batch file lines will be echoed, including those prefaced by a '@', and when ECHO is OFF. [BatchEcho] EXAMPLES Change the COMPOUND character to a ~ (tilde): setdos /c~ Change MODE to insert, VERBOSE to off, and set NOCLOBBER on: setdos /m1 /v0 /n1 Disable the internal LIST command: setdos /i-list Change the the PARAMETER character to an &, the COMPOUND character to a ^, and the ESCAPE character to a  (ctrl-X), so that 4OS2 syntax matches that used in 4DOS. Note the ^ escape characters used before the new parameter and compound characters. These prevent the new characters from being given their old meanings within the SETDOS command; for example, without them the & would be taken as the end of the SETDOS command. setdos /p^& /c^^ /e ═══ 3.65. SETLOCAL - Save environment ═══ SYNTAX (Internal 4OS2) SETLOCAL PURPOSE Save a copy of the current disk drive, directory, aliases, and environment variables. COMMENTS SETLOCAL is used in batch files to save the disk drive, directory, aliases, and environment variables to a reserved block of memory. You can then change their values, and later restore the original values with ENDLOCAL. You cannot use SETLOCAL in an alias. SETLOCAL and ENDLOCAL are not nestable within the same 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. An ENDLOCAL will be automatically performed at the end of a batch file. Note that if you invoke a batch from another without using CALL, the first batch file is implicitly terminated, and an automatic ENDLOCAL performed. The second batch file will inherit the drive, directory, aliases, and environment variables as they were prior to the SETLOCAL. See also ENDLOCAL. EXAMPLE This batch file fragment saves the disk drive, directory, aliases, and environment variables, changes the disk and directory, modifies some variables, runs a program, and then restores the original values: setlocal cdd d:\test & set path=c:\;c:\os;c:\util & set lib=d:\lib rem run some program here endlocal ═══ 3.66. SHIFT - Shift batch arguments ═══ SYNTAX (Internal 4OS2) SHIFT [n] PURPOSE Allow the use of more than 10 variables in a batch file. COMMENT SHIFT is provided for compatibility with CMD.EXE, which only supports 10 parameters (%0 through %9); 4OS2 supports 128 (%0 to %127), so you may not need to use SHIFT for batch files running exclusively under 4OS2. SHIFT moves each batch file parameter n positions (i.e., if n is 1, then %1 becomes %0, %2 becomes %1, etc.). The default value for n is 1. You can also reverse a SHIFT by giving a negative value for n (i.e., if n is -1, the former value for %0 is restored, %1 becomes %1, %1 becomes %2, etc.). SHIFT also affects the %$ (command line tail) and %# (number of command arguments) batch variables. EXAMPLES Create a batch file called TEST.BTM: 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.BTM with the arguments "zero one two three four five six" produces the following results: zero one two three one two three four three four five six two three four five ═══ 3.67. START - Start new session ═══ SYNTAX (Internal 4OS2) START ["title"] [/B[G] /C /DOS[=filename] /F[G] /FS /I /ICON=name /INV /K /L /MAX /MIN /N /PGM /PM /POS=x,y,x1,y1 /WAIT /WIN] [command ...] PURPOSE Start a program in a new OS/2 session. COMMENTS Entering START with no program name starts another 4OS2 session. START determines the application type automatically and starts it in the appropriate mode (full-screen, windowed, or PM). If the program is a DOS app or Windows 3.x app, 4OS2 will either return an error message (in OS/2 1.3), or start the program in a VDM (in OS/2 2.0). You cannot start a batch file (.CMD or .BTM) with /PM; use /FS or /WIN. The START options are: "title" Specify the title to appear on the title bar and in the PM task list. The title must be enclosed in double quotes and cannot exceed 60 characters. If you don't specify a title, the program name is used. /B[G] Start as a background session. /C Start the application in a 4OS2 session, and end the session when the application finishes. /DOS (OS/2 2.0 only) Start a foreground DOS session. /DOS=filename[4OS2/32 only] Start a foreground DOS session with DOS settings from the specified file. Each line in the file should have a name, an equal sign (=), and a value. The names are those shown in OS/2's standard DOS Settings dialog box, for example: DOS_BREAK=ON DOS_LASTDRIVE=N DOS_RMSIZE=640 Note that the valid settings can depend on what device drivers you have loaded on your system, and DOS settings that are valid on one system may not be valid on another. Some experimentation may be required, as DOS settings often are not documented by IBM or device driver manufacturers. START will use the default DOS parameters for any options that aren't specified in the settings file. You can add comments to the file by beginning the line with a colon (:). /F[G] Start the session in the foreground. The default is to start in the background, unless you specify /DOS, /FS, /WIN, or /PM. /FS Start a foreground full-screen session. /I Inherit the environment specified by the SET statements in CONFIG.SYS, rather than the current 4OS2 environment. /ICON Use the specified icon file. /INV Start the session as invisible (no icon; only accessible through the Task Manager or Window List). /K Start the application in a 4OS2 session, and keep the session when the application finishes. This is the default for all non-PM applications. /L Start 4OS2 with local alias and history lists. /MAX Start the session maximized. /MIN Start the session minimized. /N Start the program directly without using 4OS2.EXE. The command cannot be a batch file or internal command. This is the default value for PM applications. /PGM The next argument is the program name, not a session name. /PM Start a foreground PM application. /POS Specify the start position (x,y), and the window size (x1,y1) in pels (the lower left corner is 0,0). /WAIT Start the session as a child session, and wait for it to end before continuing. /WIN Start a foreground windowed session. If you specify a session type incompatible with the program (for example, a /PM with a .CMD file), START will start the session in the default mode for that program. See also DETACH EXAMPLES Start a full-screen 4OS2 session: start /fs Start 4DOS in a windowed DOS session (OS/2 2.0 only): start /dos /win 4DOS.COM (The "4DOS.COM" in this example is optional. 4OS2 will start 4DOS automatically if no program name is given in a START /DOS command and 4DOS is your default DOS command processor.) Start CHKDSK in a minimized background window session, without using 4OS2, and with the title "Analyzing the disk": start "Analyzing the disk" /bg /min /win /n chkdsk ═══ 3.68. TEE - Tee pipe fitting ═══ SYNTAX (Internal 4OS2) TEE [/A] [d:][path]filename... PURPOSE Copy standard input to standard output, and save a copy in the specified file(s). COMMENTS The only option for TEE is: /A Append output to the file(s) rather than overwriting it. If you are typing at the keyboard, enter a ^Z to terminate the input. TEE is often used to save the intermediate output of a pipe. See also Y. EXAMPLE Search the file DOC for any lines containing the string "486", make a copy of the matching lines in 4.DAT, and write them to the output file 486.DAT: find "486" doc | tee 4.dat | sort > 486.dat ═══ 3.69. TEXT - Display text block ═══ SYNTAX (Internal 4OS2) TEXT . . . ENDTEXT PURPOSE Display a block of text in a batch file. COMMENTS The TEXT command is useful for displaying menus or multiple-line messages. TEXT will display subsequent lines in the text until terminated by ENDTEXT. Both TEXT and ENDTEXT must be entered as the only command on that line. You can change screen colors by inserting ANSI escape sequences into the text block. If the output of TEXT is redirected, all lines in the text block will be written to the specified output file, and not to the screen. See also ECHO, SCREEN, SCRPUT, and VSCRPUT. EXAMPLE 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 - DOS Utilities Enter your selection: endtext ═══ 3.70. TIME - Set/Display time ═══ SYNTAX (Internal 4OS2) TIME [hh:mm:ss] PURPOSE Display or set the current system time. COMMENTS 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. The parameters for the TIME command are: hh Hour (0 - 23) mm Minute (0 - 59) ss Second (0 - 59) TIME defaults to 24-hour format; you can optionally enter the time in 12-hour format by appending an "am" or "pm". Whenever you create or modify a file, the system time is recorded in the directory entry. See also DATE, and TIMER. EXAMPLES Enter the time (9:30 am): time 9:30 To be prompted for the time: time ═══ 3.71. TIMER - System stopwatch ═══ SYNTAX (Internal 4OS2) TIMER [/1 /2 /3 /S] [ON] PURPOSE System stopwatch. COMMENTS The TIMER command turns an internal stopwatch on and off. The first time you run TIMER, the stopwatch starts. When you run TIMER again, the stopwatch stops and the elapsed time is displayed. There are three timers available (1, 2, and 3), so you can time multiple overlapping events. The default timer is #1. The options for TIMER are: ON Force the timer to restart /1 Use timer #1 /2 Use timer #2 /3 Use timer #3 /S Display split time without stopping the timer TIMER is particularly useful for timing events in batch files. The smallest interval TIMER can measure 0.03 seconds; the largest interval is 23:59:59.99. See also TIME. EXAMPLES Start or stop the timer: timer Display a split time: timer /s ═══ 3.72. TYPE - Display files ═══ SYNTAX (Internal 4OS2) TYPE [/L /P] [d:][pathname]filename... PURPOSE Display the contents of the specified file(s). COMMENTS The TYPE command displays a file. Press ^S to suspend the display, and any character key to continue the display. The TYPE options are: /L Print line numbers preceding each line of text. /P Pause after each page. Press ^C to quit, or any other key to display the next page. TYPE is normally only useful for displaying ASCII text files; executable files (.COM and .EXE) and many data files will be unreadable due to the presence of non-alphanumeric characters. You will probably find LIST to be more useful for displaying files. See also LIST. EXAMPLE Display the files MEMO1 and MEMO2, pausing at the end of each page: type /p memo1 memo2 ═══ 3.73. UNALIAS - Remove aliases ═══ SYNTAX (Internal 4OS2) UNALIAS [/Q] alias... UNALIAS * PURPOSE Remove aliases from the alias list. COMMENTS UNALIAS also accepts the wildcard character * to delete all aliases. The only option for UNALIAS is: /Q Don't display an error message if the alias doesn't exist. See also ALIAS and ESET. EXAMPLES Remove the alias DDIR: unalias ddir Remove the aliases DDIR and ZAP: unalias ddir zap Remove all the aliases: unalias * ═══ 3.74. UNSET - Remove environment variables ═══ SYNTAX (Internal 4OS2) UNSET [/Q] name... UNSET * PURPOSE Remove variables from the environment. COMMENTS UNSET also accepts the wildcard character * to delete all environment variables. Use caution with UNSET *; many programs are dependent on environment variables. (4OS2 relies on PATH and COMSPEC.) The only option for UNSET is: /Q Don't display an error message if the environment variable doesn't exist. UNSET is often used in conjunction with SETLOCAL / ENDLOCAL in order to clear the environment of variables that may cause problems for some applications. See also ESET and SET. EXAMPLES Remove the variable CMDLINE: unset cmdline Remove the variables CMDLINE and PATH: unset cmdline path Remove all the environment variables: unset * ═══ 3.75. VER - Display 4OS2 and OS/2 versions ═══ SYNTAX (Internal 4OS2) VER [/R] PURPOSE Display the current 4OS2 and OS/2 versions. COMMENTS The 4OS2 and OS/2 versions consist of a one digit major version number, a period, and a one or two digit minor version number. The only option for VER is: /R Display the OS/2 and 4OS2 revision levels. EXAMPLE Get the current version of 4OS2 and OS/2: ver ═══ 3.76. VERIFY - Set disk write verification ═══ SYNTAX (Internal 4OS2) VERIFY [on | off] PURPOSE Display, enable, or disable disk write verification. COMMENTS When VERIFY is ON, the system will verify that no error occurred during each disk write operation. It does NOT compare the data actually written to the disk. VERIFY will remain ON until you set it OFF. Entering VERIFY with no parameters will display the current VERIFY state. Verification will slow your disk write operations slightly. At system startup, VERIFY is OFF. EXAMPLES Check the current verify status: verify Enable disk write verification: verify on ═══ 3.77. VOL - Display volume labels ═══ SYNTAX (Internal 4OS2) VOL [d:] ... PURPOSE Display the disk volume label(s). COMMENTS If you don't enter a drive name, VOL displays the disk label and the volume serial number for the current drive. If the disk doesn't have a volume name, VOL will report it as "unlabeled." Volume labels can be created, changed or deleted with the LABEL command. EXAMPLE Display the disk labels for drives A and B: vol a: b: ═══ 3.78. VSCRPUT - Write vertical text ═══ SYNTAX (Internal 4OS2) VSCRPUT row column [bright] [blink] fg ON bg text PURPOSE Display text in color in a vertical column. COMMENTS The row and column numbering is zero-based, so on a standard 25 row by 80 column display, valid rows are 0 - 24 and valid columns are 0 - 79. VSCRPUT works like SCRPUT, but writes the text vertically. The parameters are: row Start row column Start column fg Foreground character color bg Background character color text The text to display Only the first three characters of the color name and attributes ("bright" and "blink") are required. The available colors are: Black Blue Green Red Magenta Cyan Yellow White See also ECHO, SCREEN, SCRPUT, and TEXT. EXAMPLE The following batch file fragment displays an X and Y axis and labels them: drawhline 20 10 40 1 bright white on blue drawvline 2 10 18 1 bright white on blue scrput 21 20 bright red on blue X axis vcrput 8 9 bright red on blue Y axis ═══ 3.79. WINDOW - Set the window title and state ═══ SYNTAX (Internal 4OS2) WINDOW ["title"] MINimize | MAXimize | REStore PURPOSE Change the title and / or state of the current 4OS2 window. COMMENTS WINDOW works only in windowed OS/2 sessions. The minimize, maximize, and restore parameters may be abbreviated by their first three letters. The window options (other than "title") are equivalent to the similarly named options on the system menu (the menu which appears when you click on the box in the top left corner of a window). The parameters are: "title" Change the window title. Setting the title at the command prompt changes it permanently (or until WINDOW "title" is used to change it again); setting it in a batch file changes it only for the duration of the batch file. MINimize Minimize the 4OS2 window. MAXimize Maximize the 4OS2 window. REStore Restore the 4OS2 window to its "normal" size (the size before it was minimized or maximized). EXAMPLE This batch file fragment minimizes the current window, performs some operations, then restores the window to its original size (not maximized or minimized): window minimize dir memory window restore ═══ 3.80. Y - Y pipe fitting ═══ SYNTAX (Internal 4OS2) Y [d:][path]filename... PURPOSE Copy standard input to standard output, and then copy the specified file(s) to standard output. COMMENTS Standard input from the console is terminated by a ^Z. See also TEE. EXAMPLE Get text from standard input, append the files MEMO1 and MEMO2 to it, and send the output to MEMOS: y memo1 memo2 > memos ═══ 4. 4OS2 Reference tables ═══ This section includes an ASCII character table, an ANSI command reference, and a list of the keycodes used by INKEY. ═══ 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 ═══ 4.2. ANSI reference ═══ This section is a quick-reference to commonly-used ANSI commands. This information is generally applicable to OS/2 and the DOS ANSI drivers. 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 4OS2, you should 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 the internal "escape" character (the 4OS2 default escape character is the caret ^) followed by a lower-case "e". You can also include ANSI commands in your prompt, using $e to transmit the ESC character. You can NOT use PROMPT to transmit ANSI commands to the screen from a batch file. 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[=modeh Set display mode; see table of mode values below ESC[=model Set display mode; see table of mode values below ESC[attr;attr;...m Set display attributes; see table of attribute values below ESC[key;string;...p Substitute "string" for the specified key; see key substitutions section below ESC[s Save cursor position (may not be nested) ESC[u Restore cursor position after a save Display Attributes 0 All attributes off (normal white on black) 1 High intensity (bold) 2 Normal intensity 4 Underline (usually effective only on monochrome displays) 5 Blinking 7 Reverse Video 8 Invisible 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 a bright red foreground, first set all attributes off, then set red, then bold: echo ^e[0;31;1m Display Modes 0 Text 40x25 monochrome 1 Text 40x25 color 2 Text 80x25 monochrome 3 Text 80x25 color 4 Graphics 320x200 4-color 5 Graphics 320x200 4-color 6 Graphics 640x200 2-color 7 (cursor wrap kludge) Mode 7 is an unfortunate kludge; Setting mode 7 with an "h" command tells ANSI to wrap text to the next line when it passes the end of a line; setting mode 7 with an "l" (lower-case L) command tells ANSI not to wrap text. For all other modes the "h" and "l" commands are equivalent. Key Substitutions The key substitutions ("p") command causes ANSI to substitute the text in "string" when the specified key is pressed. The key code can be a single character in quotes, a numeric ASCII value, or an extended code for a non ASCII key (e.g. function or cursor keys) in the form 0;n, where n is the scan code for the key. The string to be substituted can be a single character or character string in quotes, a numeric ASCII value, or an extended key code. For a list of numeric ASCII values, see ASCII. To clear a key substitution, "substitute" the original key for itself (see examples). Examples Clear the display attributes, then set the display to bright cyan on blue, and clear the screen: echo ^e[0;44;36;1m^e[2J Substitute "dir" for F4: echo ^e[0;62;"dir";13p Undo the above substitution: echo ^e[0;62;0;62p Set up a prompt that saves the cursor position, displays the 4OS2 shell level, 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[0;45;37;1m$e[K($z) $d $t$e[u$e[0;44;36;1m$p$g ═══ 4.3. Extended Key Codes ═══ Key Names The format for a key name in a 4OS2 command or directive is: [Prefix-]Keyname. The prefix and key name must be separated by a dash. The prefix can be left out, or it can be any of the following: Alt followed by A - Z, 0 - 9, F1 - F12, or Bksp Ctrl followed by A - Z, F1 - F12, 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 Esc Up PgUp 0 - 9 Bksp Down PgDn F1 - F12 Tab Left Home Ins Enter Right End Del The following table lists the common extended key codes used by INKEY: F1 @59 Alt-F1 @104 Ctrl-F1 @94 Shift-F1 @84 F2 @60 Alt-F2 @105 Ctrl-F2 @95 Shift-F2 @85 F3 @61 Alt-F3 @106 Ctrl-F3 @96 Shift-F3 @86 F4 @62 Alt-F4 @107 Ctrl-F4 @97 Shift-F4 @87 F5 @63 Alt-F5 @108 Ctrl-F5 @98 Shift-F5 @88 F6 @64 Alt-F6 @109 Ctrl-F6 @99 Shift-F6 @89 F7 @65 Alt-F7 @110 Ctrl-F7 @100 Shift-F7 @90 F8 @66 Alt-F8 @111 Ctrl-F8 @101 Shift-F8 @91 F9 @67 Alt-F9 @112 Ctrl-F9 @102 Shift-F9 @92 F10 @68 Alt-F10 @113 Ctrl-F10 @103 Shift-F10 @93 Home @71 Up @72 PgUp @73 Left @75 Right @77 End @79 Down @80 PgDn @81 Ins @82 Del @83 Ctrl-Home @119 Ctrl-PgUp @132 Ctrl-Left @115 Ctrl-Right @116 Ctrl-End @117 Ctrl-PgDn @118 Ctrl-A 1 Ctrl-N 14 Ctrl-B 2 Ctrl-O 15 Ctrl-C 3 Ctrl-P 16 Ctrl-D 4 Ctrl-Q 17 Ctrl-E 5 Ctrl-R 18 Ctrl-F 6 Ctrl-S 19 Ctrl-G 7 Ctrl-T 20 Ctrl-H 8 Ctrl-U 21 Ctrl-I 9 Ctrl-V 22 Ctrl-J 10 Ctrl-W 23 Ctrl-K 11 Ctrl-X 24 Ctrl-L 12 Ctrl-Y 25 Ctrl-M 13 Ctrl-Z 26 Alt-A @30 Alt-N @49 Alt-1 @120 Alt-B @48 Alt-O @24 Alt-2 @121 Alt-C @46 Alt-P @25 Alt-3 @122 Alt-D @32 Alt-Q @16 Alt-4 @123 Alt-E @18 Alt-R @19 Alt-5 @124 Alt-F @33 Alt-S @31 Alt-6 @125 Alt-G @34 Alt-T @20 Alt-7 @126 Alt-H @35 Alt-U @22 Alt-8 @127 Alt-I @23 Alt-V @47 Alt-9 @128 Alt-J @36 Alt-W @17 Alt-0 @129 Alt-K @37 Alt-X @45 Alt-L @38 Alt-Y @21 Alt-M @50 Alt-Z @44