;--------------------------------------------------------------------------- ; Copyright 1988 - 2004, JP Software Inc., All Rights Reserved. ; Published by JP Software Inc., P.O. Box 328, Chestertown, MD 21620, USA. ; ; This is a variant help text for Luchezar Georgiev's updated release ; of 4DOS. ; ; Changes since 2006-04-04: ; ; 2006-12-15 CED Changes for build 136: Startup option /Y reenabled ; (yeah!); changes to RMDIR, SET, SHIFT, @FILESIZE. ; Stripped out the wishlist and change log pages. ; ; 2006-12-22 LIG Changes for build 140: Removed warning about @READY. ; Added _CPU information about the Pentium 4 and newer. ; ; 2006-12-24 LIG Changes for build 141: Added gigabyte suffix to file ; size ranges and units pages, and for DIR /4. ; ; 2006-12-26 LIG Added help for @SERIAL and compatibility information ; about CADStar PCB. ; ; 2006-12-30 LIG Changes for build 144: Added /V option to TYPE. ; Added SMARTDRV cache flushing and /P option to REBOOT. ; ; 2007-1-6 LIG Changes for build 145: Added EJECTMEDIA and CLOSETRAY. ; Added "DVD" to most places where a CD-ROM is mentioned. ; Added a @READY warning about some CD-ROM drivers. ; ; 2007-1-7 LIG Changes for build 146: Added @CWD and @CWDS functions. ; ; 2007-1-8 LIG Changes for build 147: Added @EVAL hex output option. ; Corrected the limits of @CONVERT value. ; ; 2007-1-31 LIG Changes for build 151 (7.51): ; Changed some error strings to reflect changes in 4DOS. ; Updated version number which now equals 7.(build-100). ; ; 2007-2-4 LIG Changes for build 152 (7.52): Added /L option to LIST. ; ; 2007-2-15 LIG Changes for build 153 (7.53): ; Maximal description length before wrapping decremented. ; Updated File Not Found & No More Files error messages. ; Second error list column condensed to hide less of it. ; ; 2007-4-20 LIG Changes for build 154 (7.54): ; Added _ALT, _CAPSLOCK, _CTRL, _LSHIFT, _NUMLOCK, ; _RSHIFT, _SCROLLLOCK and _SHIFT variables. ; ; 2007-6-25 LIG Changes for build 156 (7.56): ; Added _DATETIME and _MONTHF variables. ; Added @AGEDATE and @MONTHF functions. ; ; 2007-7-27 LIG Changes for build 157 (7.57): Added @FIELDS function. ; ; 2007-10-27 LIG Changes for build 159 (7.59): Added @MD5 function. ; ; 2008-5-24 LIG Changes for build 164 (7.64): Added EQC operator. ; ; 2008-6-11 LIG Changes for build 165 (7.65): ; Added _LALT, _LCTRL, _RALT, _RCTRL variables. ; Changed and amended text for the _DOS variable. ; Added newer Windows versions to the Windows NT topic ; and changed the URL for 4NT (now named TCC). ; ; 2008-6-29 LIG Changes for build 167 (7.67): ; Added _EXECSTR variable. ; Deleted the note about REBOOT not working in Windows 9x ; and added a similar note about the /P option. ; ; 2008-7-1 LIG Changes for build 168 (7.68): ; Added a warning for REBOOT under Windows (important!). ; Deleted text saying REBOOT /P does not work in W9x/ME. ; Added text about showing the "brand string" for _CPU. ; ; 2008-7-4 LIG Changes for build 169 (7.69): ; Added _STDIN, _STDOUT and _STDERR variables. ; Added @SHA1 function. ; ; 2008-7-9 LIG Changes for build 170 (7.70): ; Added /N option and case-sensitive search to LIST. ; ; 2008-7-10 LIG Changes for build 171 (7.71): ; Added _EDITMODE and _EXPANSION variables. ; Added user-defined function expansion (9) to SETDOS /X. ; ; 2008-7-15 LIG Changes for build 172 (7.72): ; Added @LTRIM, @RTRIM and @TRUNCATE functions. ; Added text for @RANDOM to describe the new algorithm. ; Removed text on SETDOS /W failing in MS-/PC DOS/W9x/ME. ; and added a link to SETDOS in the UnixPaths topic. ; ; 2008-7-17 LIG Added a recommendation to set Logo=0 in MSDOS.SYS. ; ; 2008-8-4 LIG Changes for build 173 (7.73): ; Added @SMBSTR. ; Removed text in MEMORY and @EXTENDED topics saying that ; XMS excludes extended memory because it's no longer so. ; ; 2008-8-12 LIG Changes for build 174 (7.74): ; Added @FILEREADB. ; Added text for the mode of @FILEWRITEB when length = -1 ; ; 2008-8-24 LIG Changes for build 175 (7.75): ; Added SET /E option. ; Added @AVERAGE and _SYSREQ. ; Added text that labels are not limited to 8 characters. ; ; 2008-8-29 LIG Changes for build 176 (7.76): ; Added MOD operator for @EVAL. ; Added @ISODOWI, @ISOWEEK, _ISODOWI, _ISOWEEK. ; ; 2008-8-31 LIG Changes for build 177 (7.77): ; Added _ISOWDATE. ; Added ISO week date input to Date Formats, DATE, TOUCH ; and ranges. ; Added format 5 (ISO week date) to @AGEDATE, @FILEDATE ; and @MAKEDATE. ; ; 2008-9-8 LIG Changes for build 178 (7.78): ; Removed text for 55 ms DELAY resolution limit, updated ; maximum allowed delay and added default value. ; Added details for TIMER smallest and largest interval, ; documented its already existing OFF option and added /Q ; Added _TSC and _CPUSPEED. ; ; 2008-9-11 LIG Changes for build 179 (7.79): ; Added _BATCHTYPE, _BDEBUGGER, _CMDSPEC, _V86 variables. ; Added @QUOTE and @UNQUOTE functions. ; Marked all 4DOS-unique variables and functions by '!'. ; ; 2008-9-14 LIG Changes for build 180 (7.80): ; Added _ININAME and _TICK variables. ; Added @COUNT, @ISALNUM, @ISALPHA, @ISASCII, @ISCNTRL, ; @ISDIGIT, @ISPRINT, @ISPUNCT, @ISSPACE and @ISXDIGIT. ; ; 2008-9-17 LIG Changes for build 181 (7.81): ; Added _CDROMS, _DRIVES, _ISOWYEAR and _READY variables. ; Added @DATECONV, @HISTORY, @ISOWYEAR, @SUBST and ; @UNQUOTES functions. ; ; 2008-9-19 LIG Changes for build 182 (7.82): ; Added text that SETDOS /C|E|P accept decimal ASCII code ; Added $A and $K special characters to the PROMPT page. ; Added _HDRIVES variable. ; Added @CEILING, @DRIVETYPE and @FLOOR functions. ; ; 2008-9-22 LIG Changes for build 183 (7.83): ; Added @COMPARE, @LCS and @REVERSE functions. ; ; 2008-9-24 LIG Changes for build 184 (7.84): ; Added format 6 (ISO ordinal date) ; to @AGEDATE, @DATECONV, @FILEDATE and @MAKEDATE. ; Added _ISORDATE and _WINTICKS variables. ; Added @DIRSTACK and @SIMILAR functions. ; Reflected the actual order of lines shown by DIRS. ; ; 2008-9-26 LIG Changes for build 185 (7.85): ; Added ISO ordinal date input ; to Date Formats, DATE, TOUCH and ranges. ; Added _STARTPATH variable. ; Noted that _WINTITLE now works also under W9x/ME. ; Updated the "Keywords" page. ; ; 2008-10-6 LIG Changes for build 186 (7.86): ; Added _DST,_MJD,_STZN,_STZO,_TZN,_TZO,_UNIXTIME, ; _UTCDATE,_UTCDATETIME,_UTCHOUR,_UTCISODATE,_UTCMINUTE, ; _UTCSECOND,_UTCTIME. ; Updated the "Keywords" page. ; ; 2008-10-10 LIG Changes for build 187 (7.87): ; Edited the TZ text to stress the universality and ; importance of this environment variable. ; Removed text on old CPU limitations for TIMER,_WINTICKS ; Added text that TITLEPROMPT works under OS/2 too. ; Added TITLE and moved most TITLEPROMPT text there. ; Updated the "Keywords" page. ; ; 2008-10-12 LIG Changes for build 188 (7.88): ; Added hex input format for SETDOS /C|E|P, @CHAR and ; @FILEWRITEB (others accept it too but it's unusual). ; Added =X hex output format with a leading 0x for @EVAL. ; Added TRANSIENT. ; Updated the "Keywords" page. ; ; 2008-10-20 LIG Changes for build 190 (7.90): ; Added IDLE. ; Updated the errors page. ; Updated the "Keywords" page. ; ; 2008-10-27 LIG Changes for build 191 (7.91): ; Added COUNTRY. ; Updated the "Keywords" page. ; ; 2008-10-31 LIG Changes for build 192 (7.92): ; Updated the KSTACK page for the /U(ninstall) option. ; Updated ALIAS, FUNCTION and SET pages for wildcards. ; Added @FSTYPE, _KEYSTACKED and _VCPI. ; Added VCPI in the glossary. ; Updated the "Keywords" page. ; ; 2008-11-7 LIG Changes for build 193 (7.93): ; Added /E option to BATCOMP. ; Added _FONTPAGE. ; Updated the "Keywords" page. ; ; 2008-11-18 LIG Changes for build 194 (7.94): ; Added notes for a possible crash of _CPUSPEED and _TSC. ; Added a V86 mode description in the glossary. ; Added @DDCSTR, _MACHINE, _NETWORK, _NLSFUNC and _SHARE. ; Updated the "Keywords" page. ; ; 2008-11-24 LIG Changes for build 195 (7.95): ; @DDCSTR: Added a warning about switching to a VESA mode ; Added @CLUSTSIZE and @HDDSIZE functions. ; Added APPEND,_ASSIGN,_DISPLAY,_DRIVER,_EGA,_GRAFTABL, ; _GRAPHICS,_MSCDEX,_PRINT,_SMARTDRV,_TASKMAX and ; _TASKSWITCHER variables. ; Updated the "Keywords" page. ; ; 2008-12-1 LIG Changes for build 196 (7.96): ; Added /M and /S options to REBOOT. ; Added @CODEPAGE and _POWER. ; Added a VESA description in the glossary. ; Updated the "Keywords" page. ; ; 2008-12-12 LIG Changes for build 197 (7.97): ; Replaced the JP Software support forum with the ; comp.os.msdos.4dos newsgroup in the "Unsupported" topic. ; Removed the obsolete 4NT and Take Command descriptions. ; Rewrote the Copyright and Contacting JP Software topics. ; Added NO_SEP environment variable. ; Added _VDS variable. ; Added VDS definition in the glossary. ; Updated the "Keywords" page. ; ; 2008-12-19 LIG Changes for build 198 (7.98): ; Added "svga" to the list of returned values for _VIDEO. ; Added @COM function and _SBDSP variable. ; Updated the "Keywords" page. ; ; 2008-12-29 LIG Changes for build 199 (7.99): ; Updated the _CPU, _NPU, _CPUSPEED and Copyright pages ; (renamed the later to Legal). ; ; 2009-2-27 LIG Changes for build 200 (8.00): ; Added SETERROR. ; Added /N option to ATTRIB. ; Added @ISLOWER and @ISUPPER functions. ; Updated the "Keywords" page. ; ; 2015-9-30 JOS Updated the 4DOS help text to reflect 4DOS' use in vDos. ; 2016-10-8 WEN Updated the 4DOS help text to reflect 4DOS' use in ; vDosPlus instead of original vDos. ;--------------------------------------------------------------------------- !WIDTH 80 !FIRST 1 !KEYS 13 !EXTERNAL HELP.COM DOSHELP !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 1 Table of Contents !NOINDEX Welcome to the 124DOS help system in 060vDosPlus. Select a topic area: !NOWRAP Using 4DOS 031Using the Command Line 592Commands by Category 071File Selection 047Directory Navigation 3514DOS.INI 046Other Features Aliases and Batch Files 101Aliases 102Batch Files The Environment 131Using the Environment 161Internal Variables 241Variable Functions Setup and Troubleshooting 352Starting 4DOS 719Error Messages 751Compatibility 720Troubleshooting Reference Information 941File Systems and File Name Conventions 891Miscellaneous Reference Information 911ASCII and Key Codes 920An Embarrassment of Riches 971Glossary 011Legal !WRAP ;;version [2017-03-15 WEN -- 8.00] ;--------------------------------------------------------------------------- ; Topic equates for index --------------------------------------------- !TOPIC 1001 =31 Cmd Line !INDEX 1 !TOPIC 1002 =71 File Sel !INDEX 2 !TOPIC 1003 =47 Dir Nav !INDEX 3 !TOPIC 1004 =46 Other Feat !INDEX 4 !TOPIC 1005 =592 Commands !INDEX 5 !TOPIC 1006 =101 Aliases !INDEX 6 !TOPIC 1007 =102 Batch File !INDEX 7 !TOPIC 1008 =131 Environ !INDEX 8 !TOPIC 1009 =161 Variables !INDEX 9 !TOPIC 1010 =241 Functions !INDEX 10 !TOPIC 1011 =351 4DOS.INI !INDEX 11 !TOPIC 1012 =352 Startup !INDEX 12 !TOPIC 1014 =719 Errors !INDEX 14 !TOPIC 1015 =751 Compat !INDEX 15 !TOPIC 1017 =720 Support !INDEX 17 !TOPIC 1018 =12 Help Sys !INDEX 18 !TOPIC 1019 =16 DOS Help !INDEX 19 !TOPIC 1020 =941 File Sys !INDEX 20 !TOPIC 1021 =891 Reference !INDEX 21 !TOPIC 1022 =911 Codes !INDEX 22 !TOPIC 1024 =971 Glossary !INDEX 24 !TOPIC 1025 =11 Legal !INDEX 25 ;--------------------------------------------------------------------------- !TOPIC 11 Legal !NOINDEX 旼컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴커 � Help Text Copyright 1988-2004, JP Software Inc., Worton, MD, USA � � Changes Charles Dye 2004-2006 풧P Software is not responsible for any � � & Luchezar Georgiev 2006-2009. � inaccuracies introduced in this text. � 읕컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컨컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴켸 The help system is based on an extensively modified version of the TPHELP unit from TurboPower Software's Turbo Professional 5.2 Turbo Pascal toolkit. Portions Copyright 1985-1986 Sunny Hill Software. !LINE Portions Copyright 1987-1992 TurboPower Software  Aristocrat Leisure Ltd. Portions Copyright 1987-1992 Borland Software Corporation. Software Copyright 1988-2004 Rex Conn and JP Software Inc. !LINE Portions Copyright 1983-2002 Watcom International Corporation  Sybase Inc. !LINE Portions Copyright 1985-1992 Microsoft Corporation. !LINE Portions Copyright 1991-1992 RSA Data Security Inc. !LINE Portions Copyright 1995-2004 The Internet Society. !LINE Portions Copyright 1996-2000 Vladimir Zakharychev. !LINE Portions Copyright 1991-1995 Mix Software Inc. Updates 2006-2009 Luchezar Georgiev and Jaelani Utomo 4DOS and 0204NT are trademarks of 732JP Software Inc. for its family of character- mode command processors. 4DOS and 20Take Command are registered trademarks of JP Software Inc. JP Software, jpsoft.com, and all JP Software's designs and logos are also trademarks of JP Software Inc. All other trademarked product and company names are the property of their respective trademark holders. ;--------------------------------------------------------------------------- !TOPIC 12 The 4DOS Help System !NOINDEX For information on using the help system see: 013Help Keys 014Help Reference 015Using the Mouse 0004DOS Help Index 016External (DOS) Help ;--------------------------------------------------------------------------- !TOPIC 13 Help Keys !NOINDEX 旼컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴쩡컴컴컴컴컴컴컴컴컴컴컴컴컴컴커 � Scroll down  � Next link Tab,  � � Scroll up  � Prev link Shift-Tab,  � � Next page PgDn, Space � Select link Enter � � Prev page PgUp � � 쳐컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴탠컴컴컴컴컴컴컴컴컴컴컴컴컴컴캑 � Back up / exit Esc, Ctrl-B � Next topic F8, Ctrl  � � Quick exit Alt-F4, Ctrl-C � Prev topic F7, Ctrl  � � Exit, no clear Alt-X � � 쳐컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴탠컴컴컴컴컴컴컴컴컴컴컴컴컴컴캑 � Search topic F5, Ctrl-F � Go to index F1 � � Search all F6, Ctrl-G � Go to ToC F2 � � Search again Shift-F5/F6, Ctrl-N � External help F4 � 쳐컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴탠컴컴컴컴컴컴컴컴컴컴컴컴컴컴캑 � Print topic F9, Ctrl-P � (Go to keys) F3 � 읕컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴좔컴컴컴컴컴컴컴컴컴컴컴컴컴컴켸 Press Esc to return; press Enter or 014click here for more information. ;--------------------------------------------------------------------------- !TOPIC 14 Help Reference !NOINDEX The 4DOS help system includes complete help for all 4DOS internal commands and most 4DOS features, and can allow you to load the DOS help system for help on DOS external commands. The information is fully cross-referenced, so you can move easily among related commands. This section explains in detail how to use and configure the 4DOS help system. The help system is easy to navigate and uses standard keystrokes or mouse clicks to move between the table of contents, help text, and cross-referenced topics. In most cases you'll be able to find what you want by experimenting, without studying the details below. However if you want to know what shortcuts are built into the system, reconfigure it to your liking, or see the full range of options available, then read on. For information on using the mouse see 015Using the Mouse. For information on customization options for use with the 380HelpOptions directive in 4DOS.INI, see the end of this section. The help system supports most screen heights, and will adjust the height of the help index and text display to match the height of your screen. The width of the help text display is fixed at 80 characters. To modify the help colors see the section on HELPCFG below. Starting the Help System To start the help system and go to the table of contents, press F1 or type HELP at the 4DOS prompt. If you type part or all of a command on the line before you press F1, the help system will provide "context-sensitive" help by using the first word on the line as a help topic. If it's a valid topic, you will see help for that topic automatically; if not, you will see the help table of contents and you can pick the topic you want. You can also invoke help for the word immediately above (or immediately to the left of) the cursor by pressing Ctrl-F1. (This can be useful when you need the syntax for a variable function.) You can get help on a specific command by entering the command HELP (for example, HELP COPY) at the 4DOS prompt. You can use this feature to obtain help on any topic -- not just on commands. For example, if you enter the command HELP _DOSVER you will see help for the _DOSVER internal variable. Quick Help If you type the name of any internal command at the prompt, followed by a slash and a question mark [e.g. COPY /?] then you will see help for the command in a "quick-reference" style. Output from a /? display may be redirected with > or >>. The /? option may not work correctly if you have used an alias to redefine how an internal command operates. To view the /? help for such a command you must add an asterisk to the beginning of the command to disable alias processing. For example, if you have defined this alias: alias copy *copy /r then the command COPY /? will be translated to COPY /R /?, which will not work properly. However, if you use *COPY /?, the alias will be ignored and the /? will work as you intended. Using the Keyboard The following keys can be used within the HELP system (see 013Help Keys for a quick-reference chart): !NOWRAP F1 Display the help index. PgDn Display the next page of text for the current topic. or Space PgUp Display previous page of text for the current topic.  Select the next cross-reference, or scroll one line toward the bottom of the topic (see below).  Select the previous cross-reference, or scroll one line toward the top of the topic (see below). Tab Select the next cross-reference. or  Shift-Tab Select the previous cross-reference. or  Enter Switch to the selected cross-reference topic. F8 Display help for the next topic in the index. or Ctrl  F7 Display help for the previous topic in the index. or Ctrl  F5 Find a string in the current help topic (a topic search). or Ctrl-F F6 Find a string in any help topic (a global search). or Ctrl-G Shift-F5 Find the next occurrence of the search string. or Ctrl-N F9 Print the current topic. or Ctrl-P Esc Go back to the last topic you viewed (the help system or Ctrl-B saves the last 15 topics). If there is no previous topic, exit from the help system. Alt-F4 Exit the help system immediately, without returning to or Ctrl-C the index or Table of Contents. Alt-X Exit the help system without restoring the screen (leaves the topic you were viewing visible after you exit). !WRAP F9 or Ctrl-P will print the topic on LPT1 at 58 lines per page. You can select another output device or file if you wish (you will be prompted for the output device each time you print a topic). If there are any cross-references highlighted in the text you can use the Tab and arrow keys (Tab, Shift-Tab, , or ) to select a topic, and  to switch to the selected topic. You can also move between cross-reference topics by typing text which matches a topic name. You can use F5 or Ctrl-F to search the current topic for a string, and F6 or Ctrl-G to search all topics, starting with the current topic (a "global" search). Shift-F5 or Ctrl-N continues either type of search. The search is not case sensitive. If the string is found, the line containing it is highlighted with marks ( ) at either end. If the string is not found, the help program beeps. The Esc Key Pressing Esc or Ctrl-B will "backtrack" through the most recent 15 help topics you have viewed. As you back up through the list each topic will be displayed at the same screen position it was at when you last saw it. When you "back up" from the Table of Contents, or the first topic you viewed, the help system exits. The default behavior of the Esc key allows you to navigate through a hierarchy of topics and quickly back up to previous screens. If you prefer, you can change the default so that Esc does not back up through previous topics, and always returns immediately to the first topic shown (the table of contents or index), or exits completely if HELP was started with an explicit topic. To do so, add the /E switch to the 380HelpOptions directive in 4DOS.INI (see below for additional details on help system options). If you use /E, you can still back up to previous topics with Ctrl-B. Using /E also affects the right mouse button, which always has the same effect as the Esc key. The  and  Arrow Keys The  and  keys normally move the cross-reference highlight in the appropriate direction. Once the highlight is at the first or last cross-reference on the screen, the screen begins to scroll. This allows you to scroll through long cross-reference lists easily. If you want to change the behavior of the arrow keys so that they always scroll the text immediately, without moving the cross-reference highlight, add the /L switch to the 380HelpOptions directive in 4DOS.INI (see below for additional details on help system options). If you use /L, you can still move the cross-reference highlight with , , Tab, or Shift-Tab. Using the Index While in the index, pressing an alphabetic key will move the highlighted box to the first topic starting with that letter. If you continue to press alphabetic keys the string being entered will be displayed at the lower left of the screen and the highlight bar will be placed on the first topic that matches the entered string, moving, if necessary, to a new topic as the string is being entered. If a character is entered that results in no matching topic, the entered string will be reset and the highlight bar will be placed on the first topic that begins with that letter. Pressing  selects the highlighted help topic and displays the appropriate text. Changing the Help Colors The HELPCFG.EXE program included with 4DOS allows you to customize the HELP colors. To use it, just change to your 4DOS directory, enter the command HELPCFG, and follow the instructions it displays. To force HELPCFG to adjust the monochrome HELP colors, even if you are using a color system, use the command HELPCFG /M to start the program. Help System Options You can set several options for the help system, see 380HelpOptions for the options. For example, if you want HELP to use a monochrome display and disable the mouse by default, you could include the following line in your 4DOS.INI file: HelpOptions = /M /X You can include the same options on the HELP command line if you wish. Options used on the HELP command line will override any that are set in the 4DOS.INI file. For example, to obtain help on the COPY command, and disable the mouse, you could use this command: c:\> help /x copy You can also use the 384InstallPath directive in your 3514DOS.INI file to inform 4DOS of the location of the HELP files (4HELP.EXE and 4DOS.HLP). If you don't use the InstallPath directive, the HELP program must be in the current directory or in one of the directories specified in your 138PATH setting. If you use the InstallPath directive, the HELP command will generally respond more quickly because 4DOS won't have to search the directories in your PATH setting to find the help files. ;--------------------------------------------------------------------------- !TOPIC 15 Using the Mouse !NOINDEX This topic covers mouse usage in the HELP system. For general information on the help system, including keyboard usage, see 014Help Reference. The mouse is fully supported in this help system. It can be used to scroll the display, select a cross-reference topic, and perform other actions. When the table of contents or index is displayed, you can highlight a topic by positioning the mouse cursor on the topic and pressing the left button. Pressing the left button a second time on that topic will display the help text. Once in the help screen, most standard keyboard actions can be selected with the mouse by placing the mouse cursor on the appropriate section of the "button bar" at the bottom of the screen and pressing the left button. Pressing the left mouse button while highlighting the diamond in the upper left corner will exit to the menu or the 4DOS prompt. Pressing the right mouse button will back up through the topics you have viewed, then exit to the menu or the 4DOS prompt (like the Esc key). If you use the /E switch to change Esc so it returns to the table of contents or exits immediately, the behavior of the right mouse button will change as well. See 014Help Reference for details on /E. Pressing the left and right buttons together will display the help index. When the topic you are viewing is longer than one screen, you can move through the text by placing the mouse cursor on the "scroll bar" at the right side of the screen and pressing the left button. A "slider" is displayed in the scroll bar to show the relative position of the current page of text within the topic. Different parts of the scroll bar can be used to move the text by lines or pages, or to "drag" it vertically within the window. The action taken depends on where the mouse cursor is when you press the left button: Mouse cursor position Action of left button --------------------- --------------------- On the  at the bottom Scroll down one line On the  at the top Scroll up one line Below the slider Move down one page Above the slider Move up one page On the slider Drag the slider and the text in either direction If you hold the button down while scrolling by line, the scrolling will be repeated until the beginning or end of the topic is reached. If you hold the button down while paging from the scroll bar, the paging will be repeated until the slider reaches or moves past the mouse cursor. To make the scroll bar easier to "hit" with the mouse, the help system responds to mouse clicks in the column immediately to the left of the scroll bar as if they had taken place in the scroll bar itself. ;--------------------------------------------------------------------------- !TOPIC 16 External Help !NOINDEX 65535Select this link to invoke the external DOS help program. You must specify its location in the 145DOSHELP environment variable before 4DOS help can find it. You can not put parameters after the file name; the DOSHELP variable must be set to the path and file name only. ;--------------------------------------------------------------------------- !TOPIC 17 OPTION Dialog Keys !NOINDEX General 旼컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴쩡컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� � Next control Tab � Menu bar F10 � � Previous control Shift-Tab � Field help F1 � � Select control Space � Close menu Esc � � Navigate menus &     � Exit OPTION Ctrl-C, � � list-boxes � Alt-F4 � 읕컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴좔컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� Data entry fields 旼컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴쩡컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� � Move through text   � Beginning of field Home, Ctrl  � � Delete character Backspace � Clear field Ctrl-Home � � Insert/Overstrike Insert � Clear field to end Ctrl-End � 읕컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴좔컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� Press Esc to return; press Enter or 018click here for more information. ;--------------------------------------------------------------------------- !TOPIC 18 OPTION Reference !NOINDEX This section describes how to use the OPTION dialogs to change 4DOS configuration settings. The dialogs are run by using the 648OPTION command. Each setting in the dialogs corresponds to a directive in the 4DOS.INI file. If you save the changes made in the dialogs, 4DOS.INI will be updated automatically (additional details are below). See 017OPTION Dialog Keys for a summary of the keys that can be used in OPTION. Menu bar You can access the menu bar at the top of the screen in one of three ways: Selecting a menu item with the left mouse button, hitting F10, or holding down the Alt key while typing one of the highlighted letters (i.e. Alt-X for Exit, Alt-C for Configure, or Alt-H for help). Once the menu is active, you can move the selection bar between the items with the arrow keys. As you move the selection bar from item to item in a menu, the status bar at the bottom of the screen will show a description of the currently highlighted item. Hitting Esc while in a menu will return you to the dialog area. Pressing Enter selects the menu item. The main menu items are Exit, Configure, and Help. The Exit sub-menu displays three options for leaving the program: Save, Use, and Cancel. For an explanation each option, see the Exiting OPTION topic below. The Configure menu lists the major categories of options. Selecting a category will change the dialog area of the screen to allow you to modify that group of options. The Help menu allows you to access this help topic and the help file Table of Contents, as well as additional information on the 4DOS.INI directive corresponding to the current option, the 4DOS.INI file in general, and the keys that can be used to navigate the OPTION dialogs. Dialogs The dialog area displays "controls" (numeric values, check boxes, etc.) which allow you to modify specific 4DOS configuration settings. In addition to displaying a short description of the current option, the status bar at the bottom of the screen contains the corresponding 4DOS.INI directive name enclosed in brackets. You can use the Tab key to move forward (down or right) and Shift-Tab to move backward through the controls. In addition, each control has a highlighted letter which represents its hot key. By holding down Alt and striking the hot key, the appropriate control will be selected. The integer and text controls are simple data entry fields. You can use the keyboard to edit the information contained in the data area; see 017OPTION Dialog Keys for the keys that can be used. Check box controls are represented by brackets "[ ]", which either have an X or a blank space between them. When a check box contains an X, the 4DOS.INI directive will be given the value of "Yes"; if it is blank, the directive will be assigned "No." You can toggle the value of a check box by selecting it with the spacebar. Radio buttons are represented by parentheses "( )" and are found in groups of two or more controls. Only one radio button in a group may be active, signifying the current value of the option, and this is indicated by the character "". To change the selection, use Tab or Shift-Tab to move to the value you want selected, and press the spacebar. "Combo boxes" look like a text field followed by a down arrow symbol []. However, a combo box is not editable because the directive it represents can only be assigned one of a specific set of values. When a combo box is active, pressing the spacebar or the down arrow [] will display this set in a list and allow you to choose a value. Once the list is displayed, you can move a selection bar within it by using the up and down arrows [], PageUp, PageDown, End, Home, or by typing the first character of an item in the list. You can then select that value with the spacebar. The list will disappear when you Tab to a different control or hit the left arrow key. Using the Mouse The mouse is supported when OPTION is run in 80 column mode. It can be used to select controls, menu items, and buttons, and to perform other actions. (On screens wider than 80 columns you can use the keyboard to control OPTION.) To select a control or menu item, position the mouse cursor on it and press the left mouse button. The color of the text for that item will change to show that it is active. When selecting a text or numeric field, clicking on the text preceeding the entry field will position the cursor at the left edge of the field. You can put the cursor elsewhere by clicking on a location inside the data entry field. A numeric field may also have "spin buttons"; arrow controls which can be clicked on to increment [] or decrement [] the value in the field. The value used to raise or lower the number in the field is different for each numeric field. Selecting a check box with the mouse will toggle the setting. Selecting a radio button option will turn on that option and turn off the others. Selecting a combo box control will drop the list to allow you to choose a setting. You can also display the list by clicking on the [] character to the right of the list box. You can move through the selections in a combo box list with the "scroll bar" at the right side of the list. You can use the arrows at the top and bottom of the scroll bar to move a line at a time; click above or below the "slider" to move a page at a time; or drag the slider for continuous scrolling. To select an item in the list, click on it with the left mouse button. You can close an open list by clicking on the [] character or by selecting another control or menu item. Exiting OPTION When you are finished modifying the 4DOS options you can exit the program by selecting Exit on the main menu, or by typing Ctrl-C or Alt-F4. When you use the Exit selection on the menu bar you can select Save to save your changes in 4DOS.INI for use in the current session and all future sessions, Use to use your changes in the current session only, or Cancel to discard the changes. Save saves all changes since the last Save, or since the last time you started 4DOS. If you run OPTION and exit with Use, any changes will not be saved in the .INI file at that time. However, if you run OPTION again and exit with Save, any earlier changes will automatically be saved in 4DOS.INI along with any new changes. Using Ctrl-C or Alt-F4 to exit OPTION displays a popup box containing a button for each of the options found on the exit menu. There is an additional button, labeled Resume, which will return you to the OPTION dialogs without affecting 4DOS.INI or the current session. You can choose a button with the arrow keys or Tab and select it with the spacebar or Enter, or click on it with the left mouse button. In most cases, changes you make in the Startup section of the OPTION dialogs or notebook will only take effect when you restart the vDosPlus session. Other changes take effect as soon as you exit the dialogs or notebook with Save or Use. However, not all option changes will appear immediately, even if they have taken effect. For example, some color changes will only appear after a 604CLS command. ;--------------------------------------------------------------------------- !TOPIC 20 4NT and Take Command !NOINDEX 4NT is the old name (before version 9) of the Take Command Console (TCC), a powerful alternative to the 25Windows NT line command processor (CMD.EXE) that enhances most of its standard commands and adds a wide variety of new ones. Take Command offers a new approach to working in Windows that brings users the "best of both worlds." It is a powerful command line utility, fully integrated into the Windows graphical environment. Visit http://jpsoft.com for up-to-date features, system requirements and pricing and ordering information. ;--------------------------------------------------------------------------- !TOPIC 25 The Windows NT Line !NOINDEX Microsoft's Windows NT line includes Windows NT, 2000, XP, Server 2003, Vista, Server 2008 and 7. Unlike Windows ME, 98, 95 and earlier Windows versions, these operating systems do not contain or require an underlying MS-DOS layer; they instead include a DOS emulation system which is loaded as needed. 4DOS is a DOS-based program; it was not designed for Windows NT. It can be run under the NT line, but with some limitations. Files and directories with extremely long DOS-compatible filenames, or without DOS-compatible filenames, will be inaccessible. Long filename support is disabled by default, and must be explicitly enabled through an .INI directive. Very large or deeply-nested directories may cause out-of-memory errors. 4DOS does not support internet files, Windows file associations, graphical controls, or true pipes. 4DOS is also unable to access the clipboard under Windows NT. 0204NT and Take Command are the preferred command shells for Windows NT. They were designed for these systems, and do not suffer from the DOS-imposed limitations of 4DOS. ;--------------------------------------------------------------------------- ;OPTION equates (for help from OPTION) !TOPIC 27 =17 OPTKEYS !NOINDEX !TOPIC 28 =18 OPTHELP !NOINDEX ;--------------------------------------------------------------------------- !TOPIC 31 Using the Command Line !NOINDEX 4DOS displays a c:\> prompt when it is waiting for you to enter a command. (The actual text depends on the current drive and directory as well as your PROMPT settings.) This is called the command line and the prompt is asking you to enter a command, an alias or batch file name, or the instructions necessary to begin an application program. This section explains the features that will help you while you are typing in commands, and how keystrokes are interpreted when you enter them at the command line. The keystrokes discussed here are the ones normally used by 4DOS. If you prefer using different keystrokes to perform these functions, you can assign new ones with 481Key Mapping Directives in 4DOS.INI. The standard command line features documented in this section are: 032Command-Line Editing 033Command History and Recall 034Command History Window 058Command Names and Parameters 035Filename Completion 039Automatic Directory Changes 040Directory History Window 041Multiple Commands 042Expanding and Disabling Aliases 043Command Line Help 117Command Parsing 118Argument Quoting 044Command Line Length Limits Additional command-line features are documented under 071File Selection and 047Directory Navigation. ;--------------------------------------------------------------------------- !TOPIC 32 Command-Line Editing !NOINDEX The command line works like a single-line word processor, allowing you to edit any part of the command at any time before you press Enter to execute it, or Esc to erase it. The command line you enter can be up to 511 characters long. You can use the following editing keys when you are typing a command (the words Ctrl and Shift mean to press the Ctrl or Shift key together with the other key named): !NOWRAP Cursor Movement Left arrow Move the cursor left one character. Right arrow Move the cursor right one character. Ctrl-Left Move the cursor left one word. Ctrl-Right Move the cursor right one word. Home Move the cursor to the beginning of the line. End Move the cursor to the end of the line. Insert and Delete Ins Toggle between insert and overstrike mode. Del Delete the character at the cursor. Backspace Delete the character to the left of the cursor. Ctrl-L Delete the word or partial word to the left of the cursor. Ctrl-R Delete the word or partial word to the right (or Ctrl-Bksp) of the cursor. Ctrl-Home Delete from the beginning of the line to the cursor. Ctrl-End Delete from the cursor to the end of the line. Esc Delete the entire line. Ctrl-V Insert the first line in the clipboard. Marking Text Shift-Left Mark the character to the left. Shift-Right Mark the character to the right. Shift-Home Mark from the beginning of the line to the cursor. Shift-End Mark from the cursor to the end of the line. Ctrl-Shift-Left Mark the word to the left. Ctrl-Shift-Right Mark the word to the right. Ctrl-Y Copy the marked text to the clipboard (Windows only). Execution Ctrl-C Cancel the command line. (or Ctrl-Break) Enter Execute the command line. Ctrl-F5 Toggle batch debug mode. !WRAP Most of the command-line editing capabilities are also available when a 4DOS command prompts you for a line of input. For example, you can use the command-line editing keys when 611DESCRIBE prompts for a file description, when 636INPUT prompts for input from an alias or batch file, or when 640LIST prompts you for a search string. If you want your input at the command line to be in a different color from 4DOS's prompts or output, you can use the Display page of the 648OPTION dialogs, or the 465InputColors directive in 4DOS.INI. 4DOS will prompt for additional command-line text when you include the escape character as the very last character of a typed command line. The default escape character is Ctrl-X (see 086Escape Character.) For example, c:\> echo The quick brown fox jumped over the lazy More? sleeping dog. > alphabet Sometimes you may want to enter one of the command line editing keystrokes on the command line, instead of performing the key's usual action. For example, suppose you have a program that requires a Ctrl-R character on its command line. Normally you couldn't type this keystroke at the prompt, because it would be interpreted as a "Delete word right" command. To get around this problem, use the special keystroke Alt-255. You enter Alt-255 by holding down the Alt key while you type 255 on the numeric keypad, then releasing the Alt key (you must use the number keys on the numeric pad; the row of keys at the top of your keyboard won't work). This forces 4DOS to interpret the next keystroke literally and places it on the command line, ignoring any special meaning it would normally have as a command-line editing or history keystroke. You can use Alt-255 to suppress the normal meaning of command-line editing keystrokes even if they have been reassigned with key mapping directives in the .INI file (see 351.INI File), and Alt-255 itself can be reassigned with the 513CommandEscape directive. ;--------------------------------------------------------------------------- !TOPIC 33 Command History and Recall !NOINDEX Command History Keys !NOWRAP Up Arrow Recall the previous (or most recent) command, or the most recent command that matches a partial command line. Down Arrow Recall the next (or oldest) command, or the oldest command that matches a partial command line. F3 Fill in the rest of the command line from the previous command, beginning at the current cursor position. Ctrl-D Delete the currently displayed history list entry, erase the command line, and display the previous (matching) history list entry. Ctrl-E Display the last entry in the history list. Ctrl-K Save the current command line in the history list without executing it, and then clear the command line. Ctrl-Enter Copy the current command line to the end of the history list even it has not been altered, then execute it. @ As the first character in a line: Do not save the current line in the history list when it is executed, or store it in the 132CMDLINE environment variable. This allows you to squeeze out the last few bytes of environment space before loading TSRs by prefacing each TSR command with an "@". !WRAP Use the Up Arrow key repeatedly to scan back through the history list. When the desired command appears, press Enter to execute it again. After you have found a command, you can edit it before pressing Enter. See 034Command History Window for information on viewing previous commands in a popup window. The history list is normally "circular." If you move to the last command in the list and then press the down arrow one more time, you'll see the first command in the list. Similarly, if you move to the first command in the list and then press the up arrow one more time, you'll see the last command in the list. You can disable this feature and make command history recall stop at the beginning or end of the list by turning off the History Wrap selection on the Command Line page of the 648OPTION dialogs, or setting 435HistWrap to No in the .INI file. You can search the command history list to find a previous command quickly using command completion. Just enter the first few characters of the command you want to find and press Up Arrow. If you press the Up Arrow key a second time, you will see the previous command that matches. The system will beep if there are no matching commands. The search process stops as soon as you type one of the editing keys, whether or not the line is changed. At that point, the line you're viewing becomes the new line to match if you press Up Arrow again. You can specify the size of the command history list on the Command Line page of the 648OPTION dialogs, or with the 382History directive in 4DOS.INI. When the list is full, the oldest commands are discarded to make room for new ones. You can also use the 433HistMin directive in 4DOS.INI to enable or disable history saves and to specify the shortest command line that will be saved. You can prevent any command line from being saved in the history by beginning it with an at sign [@]. When you execute a command from the history, that command remains in the history list in its original position. The command is not copied to the end of the list (unless you modify it). If you want each command to be copied or moved to the end of the list when it is re-executed, set 431HistCopy or 434HistMove to Yes in 4DOS.INI. If you select either of these options, the list entry identified as "current" (the entry from which commands are retrieved when you press Up Arrow) is also adjusted to refer to the end of the history list after each recalled command is executed. Local and Global Command History The command history can be stored in either a "local" or "global" list. With a local command history list, any changes made to the history will only affect the current copy of 4DOS. They will not be visible in other shells, or other sessions. A local command history list is the default. With a global command history list, all copies of 4DOS will share the same command history, and any changes made to the history in one copy will affect all other copies. You can control the type of command history on the Startup page of the 648OPTION dialogs, with the 388LocalHistory directive in 4DOS.INI and with the /L and /LH 352startup options. There is no fixed rule for deciding whether to use a local or global command history list. Depending on your work style, you may find it most convenient to use one type, or a mixture of types in different sessions or shells. We recommend that you start with the default approach for your 4DOS, then modify it if you find a situation where the default is not convenient. 4DOS can share a global command history list among a parent 4DOS shell and any child shells you start from that parent shell. For example, if you start an application, and then "shell to DOS" from the application, the original copy of 4DOS and the child shell can share the global command history. ;--------------------------------------------------------------------------- !TOPIC 34 Command History Window !NOINDEX Command History Window Keys !NOWRAP PgUp or PgDn (from the command line) Open the command history window. Up Arrow Scroll the display up one line. Down Arrow Scroll the display down one line. Left Arrow Scroll the display left 4 columns. Right Arrow Scroll the display right 4 columns. PgUp (inside the window) Scroll the display up one page. PgDn (inside the window) Scroll the display down one page. Ctrl-PgUp Go to the beginning of the history list. (or Home) Ctrl-PgDn Go to the end of the history list. (or End) Ctrl-D Delete the selected line from the history list. Enter Execute the selected line. Ctrl-Enter Move the selected line to the command line for editing. !WRAP You can view the command history in a scrollable window, and select the command to modify or re-execute from those displayed in the window. To activate the command history window press PgUp or PgDn at the command line. A window will appear in the upper right corner of the screen, with the command you most recently executed marked with a highlight. (If you just finished re-executing a command from the history, then the next command in sequence will be highlighted.) Once you have selected a command in the history window, press Enter to execute it immediately, or Ctrl-Enter to move the line to the prompt for editing (you cannot edit the line directly in the history window). You can bring up a "filtered" history window by typing some characters on the command line, then pressing PgUp or PgDn. Only those commands matching the typed characters will be displayed in the window. 4DOS also supports the mouse in popup windows. See 894Popup Windows for information on customizing window position, size, and color. ;--------------------------------------------------------------------------- !TOPIC 35 Filename/Variable Completion !NOINDEX Filename Completion Keys !NOWRAP F8 Get the previous matching filename. (or Shift-Tab) F9 or Tab Get the next matching filename. F10 Keep the current matching filename and display the next matching name immediately after the current one. F12 Repeat the filename just returned from an F9 match. Ctrl-A Toggle between long filename and short filename in vDosPlus. !WRAP Filename completion can help you by filling in a complete file name on the command line when you only remember or want to type part of the name. For example, if you want to copy a file whose name begins with AU, but you can't remember the rest of the name, type copy au, then press the Tab key or F9 key. 4DOS will search the current directory for filenames that begin AU and insert the first one onto the command line in place of the AU that you typed. If this is the file that you want, simply complete the command. If 4DOS didn't find the file that you were looking for, press Tab or F9 again to substitute the next filename that begins with AU. When there are no more filenames that match your pattern, the system will beep each time you press Tab or F9. If you go past the filename that you want, press Shift-Tab or F8 to back up and return to the previous matching filename. After you back up to the first filename, the system will beep each time you press Shift-Tab or F8. If you want to enter more than one matching filename on the same command line, press F10 when each desired name appears. This will keep that name and place the next matching filename after it on the command line. You can then use Tab (or F9), Shift-Tab (or F8), and F10 to move through the remaining matching files. The pattern you use for matching may contain any valid filename characters, as well as 073wildcard characters and extended wildcards. For example, you can copy the first matching .TXT file by typing c:\> copy *.txt and then pressing Tab. If you don't specify part of a filename before pressing Tab, 4DOS will match all files. For example, if you enter the above command as "COPY", without the "*.TXT", and then press Tab, the first filename in the current directory is displayed. Each time you press Tab or F9 after that, another name from the current directory is displayed, until all filenames have been displayed. If you type a filename without an extension, 4DOS will add *.* to the name (* on LFN drives). It will also place a "*" after a partial extension. If you are typing a group of file names in an 080include list, the part of the include list at the cursor will be used as the pattern to match. When filename completion is used at the start of the command line, it will only match directories, executable files, and files with executable extensions, since these are the only file names that it makes sense to use at the start of a command. If a directory is found, a "\" will be appended to it to enable an 039automatic directory change. If the name to be completed begins with a %, the completion routines will scan the environment for matching variable names. Converting Between Long and Short Filenames On LFN drives, 4DOS will search for and display long filenames during filename completion. If you want to search for traditional 8.3 short filenames, press Ctrl-A before you start using filename completion. This allows you to use filename completion on LFN drives with applications that do not support long filenames. The switch to the short filename format remains in effect for the remainder of the current command line. When 4DOS begins a new command line it will return to long filename format unless you press Ctrl-A again. You can also press Ctrl-A just after a filename is displayed, and the name will be converted to short filename format. However, this feature only affects the most recently entered file or directory name (the part between the cursor and the last backslash [\] on the command line), and any subsequent entries. It will not automatically convert all the parts of a previously entered path. Ctrl-A "toggles" the filename completion mode, so you can switch back and forth between long and short filename displays by pressing Ctrl-A each time you want to change modes. Several topics are related to filename completion: 036Appending Backslashes to Directory Names 037Customizing Filename Completion 038Filename Completion Window ;--------------------------------------------------------------------------- !TOPIC 36 Appending Backslashes to Directory Names !NOINDEX If you set the 413AppendToDir .INI directive, or the "Add \ .." option on the Command Line page of the 648OPTION dialogs, 4DOS will add a trailing backslash [\] to all directory names. This feature can be especially handy if you use filename completion to specify files that are not in the current directory -- a succession of Tab (or F9) and F10 keystrokes can build a complete path to the file you want to work with. The following example shows the use of this technique to edit the file C:\DATA\FINANCE\MAPS.DAT. The lines which include show where F9 (or Tab) is pressed; the other lines show how the command line appears after the previous F9 or Tab (the example is displayed on several lines here, but all appears at a single command prompt when you actually perform the steps): 1 c:\> edit \da 2 c:\> edit \data\ 3 c:\> edit \data\f 4 c:\> edit \data\frank.doc 5 c:\> edit \data\finance\ 6 c:\> edit \data\finance\map 7 c:\> edit \data\finance\maps.dat Note that F9 was pressed twice in succession on lines 3 and 4, because the file name displayed on line 3 was not what was needed -- we were looking for the FINANCE directory, which came up the second time F9 was pressed. In this example, filename completion saves about half the keystrokes that would be required to type the name in full. If you are using long file or directory names, the savings can be much greater. ;--------------------------------------------------------------------------- !TOPIC 37 Customizing Filename Completion !NOINDEX You can customize filename completion for any internal or external command or alias. This allows the DOS to display filenames intelligently based on the command you are entering. For example, you might want to see only .TXT files when you use filename completion in the EDIT command. To customize filename completion you can use the Command Line page of the 648OPTION command, or set the 429FileCompletion directive manually in your .INI file. You can also use the 137FILECOMPLETION environment variable. If you use both, the environment variable will override the settings in your .INI file. You may find it useful to use the environment variable for experimenting, then create permanent settings with the OPTION command or the FileCompletion directive. The format for both the environment variable and the .INI file is: cmd1:ext1 ext2 ...; cmd2: ... where "cmd" is a command name and "ext" is a file extension (which may include wildcards) or one of the following file types: DIRS Directories RDONLY Read-only files HIDDEN Hidden files SYSTEM System files ARCHIVE Files modified since the last backup FILES Files only (no directories) The command name is the internal command, alias command, or executable file name (without a path). For example, to have file completion return only directories for the CD command and only .C and .ASM files for B (the Boxer editor), you would use this setting for filename completion in the OPTION dialogs: FileCompletion=cd:dirs; b:c asm To set the same values using the environment variable, you would use this line: c:\> set filecompletion=cd:dirs; b:c asm With this setting in effect, if you type "CD " and then pressed Tab, 4DOS will return only directories, not files. If you type "B " and press Tab, you will see only names of .C and .ASM files. You can specify extensions NOT to match by prefacing the extension with a !. 4DOS does not check your command line for aliases before matching the commands for customized file completion. Instead, they ignore any path or file extension information in the first word of the command, and then search the 137FILECOMPLETION environment variable and the 429FileCompletion .INI directive to find a match that will limit the files selected for filename completion. ;--------------------------------------------------------------------------- !TOPIC 38 Filename Completion Window !NOINDEX You can also view filenames in a filename completion window and select the file you want to work with. To activate the window, press F7 or Ctrl-Tab at the command line. You will see a window in the upper-right corner of the screen, with a sorted list of files that match any partial filename you have entered on the command line. If you haven't yet entered a file name, the window will contain the name of all files in the current directory. You can search for a name by typing the first few characters. (Ctrl-Tab will work only if your keyboard and BIOS or keyboard driver support it. If it does not work on your system, use F7 instead.) The keys you can use in the filename completion window are: F7 or Ctrl-Tab (from the command line) Open the filename completion window. Up Arrow Scroll the display up one line. Down Arrow Scroll the display down one line. Left Arrow Scroll the display left 4 columns. Right Arrow Scroll the display right 4 columns. PgUp Scroll the display up one page. PgDn Scroll the display down one page. Ctrl-PgUp Go to the beginning of the filename list. (or Home) Ctrl-PgDn Go to the end of the filename list. (or End) Enter Insert the selected filename into the command line. See 894Popup Windows for information on customizing window position, size, and color. ;--------------------------------------------------------------------------- !TOPIC 39 Automatic Directory Changes !NOINDEX [Automatic directory changes are part of a set of comprehensive directory navigation features built into 4DOS. For a summary of these features, and more information on the 048Extended Directory Searches and 049CDPATH features mentioned below, see 047Directory Navigation.] The automatic directory change feature lets you change directories quickly from the command prompt, without entering an explicit 601CD or 602CDD command. To do so, simply type the name of the directory you want to change to at the prompt, with a backslash [\] at the end. For example: c:\> 4dos\ c:\4dos> This can make directory changes very simple when it is combined with 048Extended Directory Searches or 049CDPATH. If you have enabled either of those features, 4DOS will use them in searching for any directory you change to with an automatic directory change. For example, suppose Extended Directory Searches are enabled, and the directory WIN exists on drive E:. You can change to this directory with a single word on the command line: c:\4dos> win\ e:\win> Depending on the way Extended Directory Searches are configured, and the number of subdirectories on your disk whose names contain the string WIN, when you execute such a command you may see an immediate change as shown above, or a popup window which contains a list of subdirectories named WIN to choose from. The text before the backslash can include a drive letter, a full path, or a partial path. Commands like "....\" can be used to move up the directory tree quickly (see 072Extended Parent Directory Names). Automatic directory changes save the current directory, so it can be recalled with a "CDD -" or "CD -" command. For example, any of the following are valid automatic directory change entries: c:\> d:\data\finance\ c:\> archives\ c:\> ...\util\win95\ The first and last examples change to the named directory. The second changes to the ARCHIVES subdirectory of the current directory, and the third changes to the UTIL\WIN95 subdirectory of the directory which is two levels "up" from the current directory in the tree. ;--------------------------------------------------------------------------- !TOPIC 40 Directory History Window !NOINDEX [The directory history window is part of a set of comprehensive directory navigation features built into 4DOS. For a summary of these features, and more information on enhanced directory navigation features, see 047Directory Navigation.] Directory History Window Keys Ctrl-PgUp (from the command line) Open the directory history (or Ctrl-PgDn) window. Up Arrow Scroll the display up one line. Down Arrow Scroll the display down one line. Left Arrow Scroll the display left 4 columns. Right Arrow Scroll the display right 4 columns. PgUp Scroll the display up one page. PgDn Scroll the display down one page. Ctrl-PgUp Go to the beginning of the directory (or Home) list. Ctrl-PgDn Go to the end of the directory list. (or End) Ctrl-D Delete the selected line from the directory list. Enter Change to the selected drive and directory. Ctrl-Enter Move the selected line to the command line for editing. See 894Popup Windows for information on customizing window position, size, and color. The current directory is recorded automatically in the directory history list just before each change to a new directory and drive. You can view the directory history from a directory history window and change to any drive and directory on the list. To activate the directory history window, press Ctrl-PgUp or Ctrl-PgDn at the command line. You can then select a new directory with the Enter key. If the directory history list becomes full, old entries are deleted to make room for new ones. You can set the size of the list with the 376DirHistory directive in the .INI file. In order to conserve space, each directory name is recorded just once in the directory history, even if you move into and out of that directory several times. The directory history can be stored in either a "local" or "global" list. When you switch directories the original directory is saved in the directory history list, regardless of whether you change directories at the command line, from within a batch file, or from within an alias. However, directory changes made by external directory navigation utilities or other external programs are not recorded by 4DOS. Local and Global Directory History The directory history can be stored in either a "local" or "global" list. With a local directory history list, any changes made to the list will only affect the current copy of 4DOS. They will not be visible in other shells, or other sessions. A local directory history list is the default under 4DOS. With a global list, all copies of 4DOS will share the same directory history, and any changes made to the list in one copy will affect all other copies. You can control the type of directory history list on the Startup page of the 648OPTION dialogs, with the 386LocalDirHistory directive in 4DOS.INI, with the /L and /LD 352startup options. You can control where a global directory history list is stored with the 394UMBDirHistory directive in 4DOS.INI, or the corresponding setting available from the OPTION command. There is no fixed rule for deciding whether to use a local or global directory history list. Depending on your work style, you may find it most convenient to use one type, or a mixture of types in different sessions or shells. We recommend that you start with the default setting for 4DOS, then modify it if you find a situation where the default is not convenient. 4DOS can share a global directory history list among a parent 4DOS shell and any child shells you start from that parent shell. For example, if you start an application, and then "shell to DOS" from the application, the original copy of 4DOS and the child shell can share the global directory history. Whenever you start a secondary shell which uses a local directory history list, it inherits a copy of the directory history from the previous shell. However, any changes to the list made in the secondary shell will affect only that shell. If you want changes made in a secondary shell to affect the previous shell, use a global directory history list in both shells. ;--------------------------------------------------------------------------- !TOPIC 41 Multiple Commands !NOINDEX You can type several commands on the same command line, separated by a caret [^]. For example, if you know you want to copy all of your .TXT files to drive A: and then run CHKDSK to be sure that drive A's file structure is in good shape, you could enter the following command: c:\> copy *.txt a: ^ chkdsk a: You may put as many commands on the command line as you wish, as long as the total length of the command line does not exceed 511 characters. You can use multiple commands in 101aliases and 102batch files as well as at the command line. If you don't like using the default command separator, you can pick another character using the 664SETDOS /C command or the 418CommandSep directive in 4DOS.INI. If you plan to share aliases or batch files between 4DOS and 0204NT or Take Command, see 054Special Character Compatibility for details about choosing compatible command separators for two or more products. ;--------------------------------------------------------------------------- !TOPIC 42 Expanding and Disabling Aliases !NOINDEX A few command line options are specifically related to 101aliases, and are documented briefly here for completeness. You can expand an alias on the command line and view or edit the results by pressing Ctrl-F before the command is executed. Doing so is especially useful when you are developing and debugging a complex alias or if you want to make sure that an alias that you may have forgotten won't change the intent of your command. At times, you may want to temporarily disable an alias that you have defined. To do so, precede the command with an asterisk [*]. For example, if you have an alias for DIR which changes the display format, you can use the following command to bypass the alias and display the directory in the standard format: c:\> *dir ;--------------------------------------------------------------------------- !TOPIC 43 Command Line Help !NOINDEX You can start the online help system at the command line by entering HELP or HELP plus a topic, or by pressing F1 or Ctrl-F1 at any time. If you have already typed part or all of a command on the line, the help system will provide "context-sensitive" help by using the first word on the line as a help topic. If it's a valid topic, you will see help for that topic automatically; if not, you will see a table of contents and you can then pick the topic you want. For example, if you press F1 after entering each of the command lines shown below you will get the display indicated: c:\> Topic list / table of contents c:\> copy *.* a: Help on COPY c:\> c:\util\map Topic list / table of contents Ctrl-F1 works just like F1 except that it provides help for the word at the cursor instead of the first word on the command line. Where F1 is good for checking the syntax of commands, Ctrl-F1 is useful for reviewing internal variables and variable functions. For quick help you can type the name of any internal command at the prompt, followed by a slash and a question mark [/?] like this: copy /? This will show you help for the command in a "quick-reference" style (the output can be 051redirected.) The /? option may not work correctly if you have redefined how the command operates with an alias. In this case you may need to add an asterisk to the beginning of the command to 042disable alias processing: alias copy copy /r *copy /? /? will only access the help system when you use it with an internal command. If you use it with an external command name, the external command will be executed and will interpret the /? parameter according to its own rules. Some external commands, including some external utility programs, do display help when run with a /? parameter, but this a characteristic of these commands and does not depend on 4DOS. Many other external commands do not have this feature. ;--------------------------------------------------------------------------- !TOPIC 44 Command Line Length Limits !NOINDEX A command line can be up to 511 characters long, including aliases, environment variables, and multiple commands. If your use of aliases or environment variables causes the command line to exceed 511 characters, you will see a "Command line too long" error and the remainder of the line will not be executed. ;--------------------------------------------------------------------------- !TOPIC 45 Page and File Prompts !NOINDEX Several 4DOS commands can generate prompts, which wait for you to press a key to view a new page or to perform a file activity. When 4DOS is displaying information in page mode, for example with a DIR /P or SET /P command, it displays the message Press ESC to quit or another key to continue... At this prompt, you can press Esc, Ctrl-C, or Ctrl-Break if you want to quit the command. You can press almost any other key to continue with the command and see the next page of information. During file processing, if you have activated prompting with a command like DEL /P, you will see this prompt before processing every file: Y/N/A/R ? You can answer this prompt by pressing Y for Yes, N for No, or A or R to process all remaining files without further prompting. (A and R are equivalent.) You can also press Ctrl-C, Ctrl-Break, or Esc at this prompt to cancel the remainder of the command. ;--------------------------------------------------------------------------- !TOPIC 46 Other Features !NOINDEX For information on other features of 4DOS see: 045Page and File Prompts 050Redirection and Piping 053Keystack 083Critical Errors 084Conditional Commands 085Command Grouping 086Escape Character ;--------------------------------------------------------------------------- !TOPIC 47 Directory Navigation !NOINDEX The operating system remembers a current or default directory for every drive in your system. The current directory on the current drive is sometimes called the current working directory. With traditional command processors, you change the current drive by typing the new drive letter plus a colon at the prompt, and you change the current working directory with the CD command. 4DOS supports those standard features, and offers a number of enhancements to make directory navigation much simpler and faster. This section begins with a summary of all 4DOS directory navigation features. It also provides detailed documentation on the enhanced directory search features: 048Extended Directory Searches and the 049CDPATH. The 4DOS directory navigation features are in three groups: features which help 4DOS find the directory you want, methods for initiating a directory change with a minimal amount of typing, and methods for returning easily to directories you've recently used. Each group is summarized below. Finding Directories Traditional command processors require you to explicitly type the name of the directory you want to change to. 4DOS supports this method, and also offers two significant enhancements: !INDENT 7 5 5 5 * 048Extended Directory Searches allow 4DOS to search a "database" of all the directories on your system to find the one you want. * The 049CDPATH allows you to enter a specific list of directories to be searched, rather than searching a database. Use CDPATH instead of Extended Directory Searches if you find the extended searches too broad, or your hard drive has too many directories for an efficient search. !INDENT 0 Initiating a Directory Change 4DOS supports the traditional methods of changing directories, and also offers several more flexible approaches: !INDENT 7 5 5 5 * 039Automatic Directory Changes allow you to type a directory name at the prompt and switch to it automatically, without typing an explicit CD or similar command. * The 601CD command can change directories on a single drive, and can return to the most recently used directory. * The 602CDD command changes drive and directory at the same time, and can return to the most recently used drive and directory. * The 653PUSHD command changes the drive and directory like CDD, and records the previous directory in a directory "stack." You can view the stack with 614DIRS and return to the directory on the top of the stack with 651POPD. !INDENT 0 CDD, PUSHD, and automatic directory changes can also change to a network drive and directory mapped to a drive letter. Returning to a Previous Directory Traditional command processors do not remember previously-used directories, and can only "return" to a directory by changing back to it with a standard drive change or CD command. 4DOS supports three additional methods for returning to a previous directory: !INDENT 7 5 5 5 * The 601CD - and 602CDD - commands can be used to return to the previous working directory (the one you used immediately before the current directory). Use these commands if you are working in two directories and alternating between them. * The 040Directory History Window allows you to select one of several recently-used directories from a popup list and return to it immediately. The window displays the contents of the directory history list. * The 651POPD command will return to the last directory saved by 653PUSHD. The directory stack holds 511 characters, enough for 20 to 40 typical drive and directory entries. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 48 Extended Directory Searches !NOINDEX When you change directories with an 039automatic directory change, 601CD, 602CDD, or 653PUSHD command, 4DOS must find the directory you want to change to. To do so, 4DOS first uses the traditional method to find a new directory: it checks to see whether you have specified either the name of an existing subdirectory below the current directory, or the name of an existing directory with a full path or a drive letter. If you have, 4DOS changes to that directory, and does no further searching. This traditional search method requires that you navigate manually through the directory tree, and type the entire name of each directory you want to change to. Extended Directory Searches speed up the navigation process dramatically by allowing 4DOS to find the directory you want, even if you only enter a small part of its name. When the traditional search method fails, 4DOS tries to find the directory you requested via the 049CDPATH, then via an Extended Directory Search. This section covers only Extended Directory Searches, which are more flexible and more commonly used than CDPATH. Extended Directory Searches use a database of directory names to facilitate changing to the correct directory. The database is used only if Extended Directory Searches are enabled, and if the explicit directory search and CDPATH search fail to find the directory you requested. An extended directory search automatically finds the correct path to the requested directory and changes to it if that directory exists in your directory database. If more than one directory in the database matches the name you have typed, a popup window appears and you can choose the directory you want. You can control the color, position and size of the popup directory search window from the Windows page of the 648OPTION dialogs, or with directives in the .INI file, including 417CDDWinLeft, CDDWinTop, CDDWinWidth, and CDDWinHeight, and 462CDDWinColors. You can also change the keys used in the popup window with 481Key Mapping Directives in the .INI file. To use extended directory searches, you must explicitly enable them and also create the directory database. The Extended Search Database To create or update the database of directory names, use the 602CDD /S command. When you create the database with CDD /S, you can specify which drives should be included. If you enable Extended Directory Searches and do not create the database, it will be created automatically the first time it is required, and will include all local hard drives. The database is stored in the file JPSTREE.IDX, which is placed in the root directory of drive C: by default. The same tree file is used by all JP Software command processors. You can specify a different location for this file on the Windows page of the 648OPTION dialogs, or with the 392TreePath .INI directive. If you are using 2 or more of our products on your computer and want to have different drives stored in the database for each, use the dialogs or the TreePath directive to place their database directories in different locations. If you use an internal 4DOS command to create or delete a directory, the directory database is automatically updated to reflect the change to your directory structure. The updates occur if 4DOS can find the JPSTREE.IDX file in the root directory of drive C: or in the location specified by the TreePath .INI directive. The internal commands which can modify the directory structure and cause automatic updates of the file are 644MD, 655RD, 606COPY /S, 609DEL /X, 609ERASE /X, 646MOVE /S, and 658REN. The MD /N command can be used to create a directory without updating the directory database. This is useful when creating a temporary directory which you do not want to appear in the database. In 4DOS, directories can only be added automatically to JPSTREE.IDX if the new entry needs to be placed less than 64K bytes from the end of the file. If a directory cannot be added automatically, an error message appears. Automatic deletions will work from any location in the file. Enabling Extended Searches To enable extended directory searches and control their operation, you must set the 430FuzzyCD directive in the .INI file. You can set FuzzyCD with the Search Level option on the Windows page of the 648OPTION dialogs, or by editing the .INI file manually. !INDENT 5 5 5 5 If FuzzyCD = 0, extended searches are disabled, the JPSTREE database is ignored, and CD, CDD, PUSHD, and automatic directory changes search for directories using only explicit names and CDPATH. This is the default. If FuzzyCD = 1 and an extended search is required, 4DOS will search the JPSTREE database for directory names which exactly match the name you specified. If FuzzyCD = 2 and an extended search is required, 4DOS will search the database for exact matches first, just as when FuzzyCD = 1. If the requested directory is not found, it will search the database a second time looking for directory names that begin with the name you specified. If FuzzyCD = 3 and an extended search is required, 4DOS will search the database for exact matches first, just as when FuzzyCD = 1. If the requested directory is not found, it will search the database a second time looking for directory names that contain the name you specified anywhere within them. !INDENT 0 For example, suppose that you have a directory called C:\DATA\MYDIR, CDPATH is not set, and C:\DATA is not the current directory on drive C:. The following chart shows what CDD command you might use to change to this directory. FuzzyCD Setting CDD Command 0 cdd c:\data\mydir 1 cdd mydir 2 cdd myd 3 cdd yd An extended directory search is not used if you specify a full directory path (one beginning with a backslash [\], or a drive letter and a backslash). If you use a name which begins with a drive letter (e.g. C:MYDIR), the extended search will examine only directories on that drive. Forcing an Extended Search with Wildcards Normally you type a specific directory name for 4DOS to locate, and the search proceeds as described in the preceding sections. However, you can also force 4DOS to perform an extended directory search by using 073wildcard characters in the directory name. If you use a wildcard, an extended search will occur whether or not extended searches have been enabled. When 4DOS is changing directories and it finds wildcards in the directory name, it skips the explicit search and 049CDPATH steps and goes directly to the extended search. If a single match is found, the change is made immediately. If more than one match is found, a popup window is displayed with all matching directories. Wildcards can only be used in the final directory name in the path (after the last backslash in the path name). For example you can find COMM\*A*.* (all directories whose parent directory is COMM and which have an A somewhere in their names), but you cannot find CO?M\*A*.* because it uses a wildcard before the last backslash. If you use wildcards in the directory name as described here, and the extended directory search database does not exist, it will be built automatically the first time a wildcard is used. You can update the database at any time with 602CDD /S. Internally, extended directory searches use wildcards to scan the directory database. If FuzzyCD is set to 2, an extended search looks for the name you typed followed by an asterisk (i.e. DIRNAME*). If FuzzyCD is set to 3, it looks for the name preceded and followed by an asterisk (i.e. *DIRNAME*). These internal wildcards will be used in addition to any wildcards you use in the name. For example if you search for ABC?DEF (ABC followed by any character followed by DEF) and FuzzyCD is set to 3, 4DOS will actually search the directory database for *ABC?DEF*. Disabling Extended Searches in Batch Files When writing batch files you may want to use the 601CD or 602CDD command to switch directories without triggering an extended search. For example, you may need the search to fail (rather than search the extended search database) if a directory does not exist, or you may want to ensure that the extended search popup window does not appear in a batch file designed to run in unattended mode. To disable extended searches, use the /N option of CD or CDD. When this option is used and a directory does not exist below the current directory or on the CDPATH, the command will fail with an error message, and will not search the extended search database. For example this command might trigger an extended search: cdd testdir but this one will not: cdd /n testdir Note that this option is not available for 653PUSHD. To perform the same function when using PUSHD, save the current directory with PUSHD (without parameters) and then use CDD /N to change directories, for example: pushd cdd /n testdir ;--------------------------------------------------------------------------- !TOPIC 60 vDosPlus !NOINDEX vDosPlus - 4DOS, what's what? vDosPlus: A Windows program emulating a PC, its hardware, BIOS and DOS in a window, based on vDos and DOSBox. 4DOS: A DOS program running in vDosPlus. 4DOS is an enhanced DOS command.com, executing DOS commands and batch files. DOS programs were once developed to run on PC's that booted into DOS. DOS wasn't multitasking itself, DOS programs always start as 16-bit, and the 16-bit processor mode isn't supported by Windows 64-bit. DOS programs running under Windows are unaware that the PC's hardware cannot be directly addressed anymore. The (windowed) DOS screen doesn't match the real display. The Windows printing system is incompatible with that of DOS, etc., etc. To work around these problems, vDosPlus runs DOS programs in an emulated DOS PC in the Windows environment. In vDosPlus, these internal DOS-style commands have been added or modified: !NOWRAP 062ABOUT Displays a popup with information about vDosPlus. 603CHCP Enhanced to display language specific characters. 065CMD Links to the Windows CMD command line processor. 066LABEL Assigns a volume label to a disk drive. 063MEM Reports memory available to DOS programs. 663SET Enhanced to include Windows variables. 067SETCFG Views or changes the vDosPlus configuration settings. 068SETCOLOR Views or changes the vDosPlus text mode color settings. 069SETPORT Views or changes the vDosPlus COMx/LPTx port settings. 064UNUSE Unassigns specified vDosPlus drive letters. 061USE Assigns vDosPlus drive letters to Windows drives/shares. 681VER Displays the vDosPlus and emulated DOS version. !WRAP Visit the vDosPlus home page for latest downloads and further information: http://www.vdosplus.org/ ;--------------------------------------------------------------------------- !TOPIC 61 USE !TTY Purpose: Assigns a vDosPlus drive letter to a Windows path. Format: USE [drive letter:] [Windows path\] Windows path: Windows drive letter:, or Windows folder, or network share. Usage This is one of the most important commands in vDosPlus. The DOS drive letters in vDosPlus are not just those of Windows. At startup, before any USE commands, only the C: drive is defined in vDosPlus; this drive in vDosPlus is the Start-in folder of the shortcut that launches vDosPlus. It is possible to let vDosPlus automatically assign DOS drive letters to match those of Windows at startup by setting the USEDRVS=ON directive in its config file. USE without any parameters reports the assigned vDosPlus drive letters. You could be accustomed to assign a Windows drive letter to some network share, accommodating Windows 32-bit NTVDM. That's not needed, preferred is to USE that share directly (eg: USE F: \\servername\share name\). Drives letters assigned by USE can be unassigned by UNUSE in vDosPlus. ;--------------------------------------------------------------------------- !TOPIC 62 ABOUT !TTY Purpose: Displays a popup with information about vDosPlus. Format: ABOUT !TTY Usage About displays information about vDosPlus, including the version and build dates as well as a few other information such as the credits. ;--------------------------------------------------------------------------- !TOPIC 63 MEM !TTY Purpose: Briefly reports memory available to DOS programs. Format: MEM !TTY Usage Mem provides a brief report of memory available to DOS programs. A more detailed (and typically slightly different) report is provided by the 645MEMORY command. ;--------------------------------------------------------------------------- !TOPIC 64 UNUSE !TTY Purpose: Unassigns a vDosPlus drive letter that was previously assigned. Format: UNUSE drive letter: Usage This command unassigns a vDosPlus drive letter previously assigned by USE. If you unassign the C: drive, then it will be restored to the Start-in folder of the shortcut that launches vDosPlus. Drives that have been unassigned by this command can be assigned again by USE. ;--------------------------------------------------------------------------- !TOPIC 65 CMD !TTY Purpose: Links to the Windows CMD command line processor. Format: CMD [WAIT][HIDE] windows command line Usage This command is linked to the Windows CMD command line processor. You can start an internal command or external program with this. The optional WAIT and HIDE have to be in capitals. Eventual paths in command line are those of Windows. If you program yourself, you can execute cmd.exe w/o the need of setting vDosPlus drives to Windows paths. Some examples cmd /c start /max notepad cmd WAITHIDE /c mytest.bat ;--------------------------------------------------------------------------- !TOPIC 66 LABEL !TTY Purpose: Assigns a volume label to a disk drive. Format: LABEL [drive letter:] newlabel Usage You can change the volume label of a disk drive with this command. You can use the VOL command to display the volume labels of disk drives. If you want to delete the current label of a disk drive without assigning a new one, then you simply need to specify "" as the new volume label. ;--------------------------------------------------------------------------- !TOPIC 67 SETCFG !TTY Purpose: Views or changes the vDosPlus configuration settings. Format: SETCFG [option[=value]] Usage You can change the vDosPlus configuration options (config.txt directives) on the fly from the DOS command line with this command. Note however that not all configuration options can be changed with this command. Currently the only configuration options NOT supported by the SETCFG command are: COLORS CONFWARN LOW XMEM Use the SETPORT command to view or change the COM and LPT port settings, and the color settings can be viewed or changed with the SETCOLOR command. If you do not specify any parameters for this command, then it will list the current settings in the alphabetic order; if only an option is given (and without the equal sign), the current value for this option will be shown. Some examples SETCFG MOUSE=ON SETCFG WHEELMOD=3,2 SETCFG TITLE=New title for vDosPlus If you do not specify a value for an option, then the default value for this option is used. For example: SETCFG WP= ;--------------------------------------------------------------------------- !TOPIC 68 SETCOLOR !TTY Purpose: Views or changes the vDosPlus text mode color settings. Format: SETCOLOR [color# [value]] Usage You can change the vDosPlus text mode color settings with this command. The COLORS directive in the config file can be used to set up the color scheme by supplying all 16 color values at the same time when vDosPlus starts, but this command allows you to change the color value one by one and on the fly. Both RGB: (r,g,b) and hexadecimal as in HTML: #RRGGBB formats are accepted. If you do not specify any parameters (or only specify a color#) for this command, then it will list the current color setting(s). Note: You can use the 605COLOR command to actually change the default display colors in the text mode. Some examples SETCOLOR 0 (20,30,40) SETCOLOR 7 #606060 If you specify "-" as the color value, then it will return the specified color to the default color value. For example: SETCOLOR 7 - You can also use the syntax "SETCOLOR MONO [+|-]" to view or change the MONO color mode. For example, to enable the MONO mode: SETCOLOR MONO + ;--------------------------------------------------------------------------- !TOPIC 69 SETPORT !TTY Purpose: Views or changes the vDosPlus COMx and LPTx port settings. Format: SETPORT [port[=value]] Usage You can view or changes the current settings of COMx and LPTx ports (x=1..9) with this command. The format of this command is similar to the SETCFG command. If an equal sign is given after a COM or LPT port but no value is provided, then the default value will be used for this port. If only a port is given for this command then the current setting of this port is shown. If you do not specify any parameters for this command, then the current settings of all COM and LPT ports are displayed. Some examples SETPORT LPT4=CLIP SETPORT COM5=DUMMY SETPORT COM6 ;--------------------------------------------------------------------------- !TOPIC 144 = 49 _CDPATH !NOINDEX !TOPIC 49 CDPATH !NOINDEX When you change directories with an 039automatic directory change, 601CD, 602CDD, or 653PUSHD command, 4DOS must find the directory you want to change to. To do so, it first uses the traditional method to find a new directory. When the traditional search method fails, 4DOS tries to find the directory you requested via the CDPATH, then via an 048Extended Directory Search. This section covers only the CDPATH. Enabling both CDPATH and Extended Directory Searches can yield confusing results, so we recommend that you do not use both features at the same time. If you prefer to explicitly list where 4DOS should look for directories, use CDPATH. If you prefer to have 4DOS look at all of the directory names on your disk, use Extended Directory Searches. CDPATH is an environment variable, and is similar to the 138PATH variable used to search for executable files: it contains an explicit list of directories to search when attempting to find a new directory. 4DOS appends the specified directory name to each directory in CDPATH and attempts to change to that drive and directory. It stops when it finds a match or when it reaches the end of the CDPATH list. CDPATH is ignored if a complete directory name (one beginning with a backslash [\]) is specified, or if a drive letter is included in the name. It is only used when a name is given with no drive letter or leading backslash. CDPATH provides a quick way to find commonly used subdirectories in an explicit list of locations. You can create CDPATH with the 663SET command. The format of CDPATH is similar to that of 138PATH: a list of directories separated by semicolons [;]. For example, if you want the directory change commands to search the C:\DATA directory, the D:\SOFTWARE directory, and the root directory of drive E:\ for the subdirectories that you name, you should create CDPATH with this command: c:\> set cdpath=c:\data;d:\software;e:\ Suppose you are currently in the directory C:\WP\LETTERS\JANUARY, and you'd like to change to D:\SOFTWARE\UTIL. You could change directories explicitly with the command: c:\wp\letters\january> cdd d:\software\util However, because the D:\SOFTWARE directory is listed in your CDPATH variable as shown in the previous example (we'll assume it is the first directory in the list with a UTIL subdirectory), you can simply enter the command: c:\wp\letters\january> cdd util or, using an automatic directory change: c:\wp\letters\january> util\ to change to D:\SOFTWARE\UTIL. As it handles this request, 4DOS looks first in the current directory, and attempts to find the C:\WP\LETTERS\JANUARY\UTIL subdirectory. Then it looks at CDPATH, and appends the name you entered, UTIL, to each entry in the CDPATH variable in other words, it tries to change to C:\DATA\UTIL, then to D:\SOFTWARE\UTIL. Because this change succeeds, the search stops and the directory change is complete. An alternative for the CDPATH environment variable is _CDPATH (see 862Compatibility with Microsoft Bookshelf). ;--------------------------------------------------------------------------- !TOPIC 50 Redirection and Piping !NOINDEX This section covers redirection and piping. You can use these features to change how 4DOS and some application programs handle input and output. Internal commands and many external programs get their input from the computer's standard input device and send their output to the standard output device. Some programs also send special messages to the standard error device. Normally, the keyboard is used for standard input and the video screen for both standard output and standard error. Redirection and piping allow you to change these assignments temporarily. 051Redirection changes the standard input, standard output, or standard error device for a program or command from the default device (the keyboard or screen), to another device or to a file. 052Piping changes the standard output and/or standard error device so that the output of one command becomes the standard input for another program or command. ;--------------------------------------------------------------------------- !TOPIC 51 Redirection !NOINDEX Redirection can be used to reassign standard input, standard output, and standard error devices from their default settings (the keyboard and screen) to another device like the printer or serial port, to a file, or to the clipboard. You must use some discretion when you use redirection with a device; there is no way to get input from the printer, for example. Redirection always applies to a specific command, and lasts only for the duration of that command. When the command is finished, the assignments for standard input, standard output, and standard error revert to whatever they were before the command. In the descriptions below, filename means either the name of a file or of an appropriate device (for example PRN, LPT1, LPT2, LPT3 for printers; AUX and COM1 to COM4 for serial ports; CON for the keyboard and screen; CLIP: for the clipboard; NUL for the "null" device, etc.). Here are the redirection options supported by 4DOS: < filename To get input from a file or device instead of from the keyboard > filename To redirect standard output to a file or device >& filename To redirect standard output and standard error to a file or device >&> filename To redirect standard error only to a file or device If you want to append output to the end of an existing file, rather than creating a new file, replace the first ">" in the output redirection symbol with ">>" (i.e., use >>, >>&, and >>&>). This 055table of all legal output redirection operators in 4DOS may be helpful. To use redirection, place the redirection symbol and filename at the end of the command line, after the command name and any parameters. For example, to redirect the output of the DIR command to a file called DIRLIST, you could use a command line like this: c:\> dir /b *.dat > dirlist You can use both input and output redirection for the same command, if both are appropriate. For example, this command sends input to SORT from the file DIRLIST, and sends output from SORT to the file DIRLIST.SRT: c:\> sort < dirlist > dirlist.srt You can redirect text to or from the Windows clipboard by using the pseudo-device name CLIP: (the colon is required). If you redirect the output of a single internal command like DIR, the redirection ends automatically when that command is done. If you start a batch file with redirection, all of the batch file's output is redirected, and redirection ends when the batch file is done. Similarly, if you use redirection at the end of a 085command group, all of the output from the command group is redirected, and redirection ends when the command group is done. When output is directed to a file with >, >&, or >&>, if the file already exists, it will be overwritten. You can protect existing files by using the 664SETDOS /N1 command, the "Protect redirected output files" setting available on the Options 1 page of the 648OPTION dialogs, or the 438NoClobber directive in 4DOS.INI. When output is appended to a file with >>, >>&, or >>&>, the file will be created if it doesn't already exist. However, if NoClobber is set as described above, append redirection will not create a new file; instead, if the output file does not exist, a "File not found" or similar error will be displayed. You can temporarily override the current setting of NoClobber by using an exclamation mark [!] after the redirection symbol. For example, to redirect the output of DIR to the file DIROUT, and allow overwriting of any existing file despite the NoClobber setting: c:\> dir >! dirout Redirection is fully nestable. For example, you can invoke a batch file and redirect all of its output to a file or device. Output redirection on a command within the batch file will take effect for that command only; when the command is completed, output will revert to the redirected output file or device in use for the batch file as a whole. You can use redirection if you need to create a zero-byte file. To do so, enter >filename as a command, with no actual command before the > character. Redirections are performed before the command is executed. If a redirection fails for any reason -- an illegal filename or a nonexistant file, a device which is not available or not ready, NoClobber protection, etc. -- then the command will not be executed at all, and the 164_? internal variable will be set to a nonzero value. For another method of changing the standard input and output devices, see 607CTTY. ;--------------------------------------------------------------------------- !TOPIC 52 Piping !NOINDEX You can use the | character to create a "pipe" which sends the standard output of one command to the standard input of another command: command1 | command2 Sends the standard output of command1 to the standard input of command2 command1 |& command2 Sends the standard output and standard error of command1 to the standard input of command2 For example, to take the output of the 663SET command (which displays a list of your environment variables and their values) and pipe it to the SORT utility to generate a sorted list, you would use the command: c:\> set | sort To do the same thing and then pipe the sorted list to the internal 640LIST command for full-screen viewing: c:\> set | sort | list The 670TEE and 686Y commands are "pipe fittings" which add more flexibility to pipes. Like redirection, pipes are fully nestable. For example, you can invoke a batch file and send all of its output to another command with a pipe. A pipe on a command within the batch file will take effect for that command only; when the command is completed, output will revert to the pipe in use for the batch file as a whole. 4DOS creates one or two temporary files to hold the output of pipes. The files are given unique names, and deleted when the pipe is completed. By default, these files are stored in the root directory of C: drive, but you can override this with either the 141TEMP4DOS or 140TEMP environment variable. ;--------------------------------------------------------------------------- ;This is the keystack explanation; see also KEYSTACK !TOPIC 53 Keystack !NOINDEX The Keystack overcomes two weaknesses of input redirection: some programs ignore standard input and read the keyboard directly, and input redirection doesn't end until the program or command terminates. You can't, for example, use redirection to send the opening commands to a program and then type the rest of the commands yourself. But the Keystack lets you do exactly that. The Keystack sends keystrokes to an application program. Once the Keystack is empty, the program will receive the rest of its input from the keyboard. The Keystack is useful when you want a program to take certain actions automatically when it starts. It is most often used in batch files and aliases. The Keystack is invoked with the 638KEYSTACK command. KEYSTACK depends on a small resident program called 703KSTACK.COM, which may be installed from your 109AUTOEXEC.BAT file. If you don't have KSTACK.COM installed, the KEYSTACK command will display an error message. To place the letters, digits, and punctuation marks you would normally type for your program into the keystack, enclose them in double quotes: c:\> keystack "myfile" Many other keys can be entered into the Keystack using their names. This example puts the F1 key followed by the Enter key in the keystack: c:\> keystack F1 Enter See 893Keys and Key Names for details on how key names are entered. See the 638KEYSTACK command for information on using numeric key values along with or instead of key names, and other details about using the Keystack. The following command creates an 595alias that will run a FoxPro report called TIMEREP (it should be entered on one line): c:\> alias timerep `keystack "use times index times" Enter "report form timerep to print" Enter "quit" Enter ^ foxpro` This command creates an alias called timerep which puts the following characters on the keystack: the characters "use times index times" the Enter key's code the characters "report form timerep to print" the Enter key's code the characters "quit" and one more Enter key The alias then runs the program FOXPRO which receives those characters just as if you had typed them. When you use the Keystack, remember that you must put the keystrokes into the Keystack before you run the program that will receive them. The Keystack will hold the keystrokes until the program asks for them. ;--------------------------------------------------------------------------- !TOPIC 54 Special Character Compatibility !NOINDEX If you use two or more of our products, or if you want to share aliases and batch files with users of different products, you need to be aware of the differences in three important characters: the Command Separator (see 041Multiple Commands), the Escape Character (see 086Escape Character), and the Parameter Character (see 105Batch File Parameters). The default values of each of these characters in each product is shown in the following chart: Product Separator Escape Parameter 4DOS ^  & 4OS2, 4NT, Take Command & ^ $ (The up-arrow [] represents the ASCII Ctrl-X character, numeric value 24.) In your batch files and aliases, and even at the command line, you can smooth over these differences in three ways: !INDENT 7 5 5 5 * Select a consistent set of characters from the Options 1 page of the 648OPTION dialogs, or with .INI file 410Configuration Directives. For example, to set the 4DOS characters to match 0204NT, use these lines in 4DOS.INI: !INDENT 7 5 7 5 418CommandSep = & 426EscapeChar = ^ 439ParameterChar = $ !INDENT 7 5 5 5 * Use internal variables that contain the current special character, rather than using the character itself (see 166+ and 165=). For example, this command: !INDENT 7 5 7 5 if "%1" == "" (echo Argument missing! ^ quit) will only work if the command separator is a caret. However, this version works regardless of the current command separator: if "%1" == "" (echo Argument missing! %+ quit) !INDENT 7 5 5 5 * In a batch file, use the 665SETLOCAL command to save the command separator, escape character, and parameter character when the batch file starts. Then use 664SETDOS as described below to select the characters you want to use within the batch file. Use an 621ENDLOCAL command at the end of the batch file to restore the previous settings. !INDENT 0 You can also use the SETDOS command to change special characters on the command line. However, when setting new special character values on the command line you must take into account the possibility that one of your new values will have a current meaning that causes problems with the setting. For example, this command: c:\> setdos /e^ would not set the escape character to a caret [^] in 4DOS if the standard 4DOS special characters were currently in effect. The ^ would be seen as a command separator, and would terminate the SETDOS command before the escape character was set. To work around this, use the escape character variable %= before each setting to ensure that the following character is not treated with any special meaning. For example, the following sequence of commands in a batch file will always set the special characters correctly to their standard 4NT values, no matter what their current setting, and will restore them when the batch file is done: setlocal setdos /c%=& /e%=^ /p%=$ ..... endlocal A similar sequence can be used to select the standard 4DOS characters, regardless of the current settings: setlocal setdos /c%=^ /e%= /p%=& ..... endlocal ;--------------------------------------------------------------------------- !TOPIC 55 Output Redirection Operators !NOINDEX !NOWRAP 旼컴컴컴컫컴컴컴컴컴컴컴컴컴컫컴컴컴컴컴컴컴컴컴쩡컴컴컴컴컴컴컴컴커 � Symbol � Redirects � NoClobber=No � NoClobber=Yes � 쳐컴컴컴컵컴컴컴컴컴컴컴컴컴컵컴컴컴컴컴컴컴컴컴탠컴컴컴컴컴컴컴컴캑 � > � stdout � Create/Overwrite � Create, or error � � >> � stdout � Create/Append � Append, or error � � >! � stdout � Create/Overwrite � Create/Overwrite � � >>! � stdout � Create/Append � Create/Append � � >&> � stderr � Create/Overwrite � Create, or error � � >>&> � stderr � Create/Append � Append, or error � � >&>! � stderr � Create/Overwrite � Create/Overwrite � � >>&>! � stderr � Create/Append � Create/Append � � >& � stdout and stderr � Create/Overwrite � Create, or error � � >>& � stdout and stderr � Create/Append � Append, or error � � >&! � stdout and stderr � Create/Overwrite � Create/Overwrite � � >>&! � stdout and stderr � Create/Append � Create/Append � 읕컴컴컴컨컴컴컴컴컴컴컴컴컴컨컴컴컴컴컴컴컴컴컴좔컴컴컴컴컴컴컴컴켸 !WRAP This table summarizes all the legal output redirection operators in 4DOS. The first column lists operators; the second tells which output stream (standard output, standard error, or both) each one redirects. The third column indicates how the output file is opened when the NoClobber feature is disabled, 4DOS's default condition. The fourth is for when NoClobber is enabled. NoClobber support is set by the 438NoClobber .INI directive at startup, and can be dynamically changed using 664SETDOS /N. For most devices (as opposed to files), there is no real difference between appending and overwriting: DIR > LPT1 and DIR >> LPT1 are equivalent. However, you can overwrite or append to the clipboard contents when redirecting to the CLIP: pseudo-device: DIR > CLIP: replaces any text on the clipboard, but DIR >> CLIP: adds to it. stdout is the command's standard output; stderr is its standard error. Create/Overwrite: The output file will be created if it does not already exist, overwritten if it does. Create/Append: The output file will be created if it does not already exist; otherwise the command's output will be added to the end of to the existing file. Create, or error: A new output file will be created. If the specified file already exists, 4DOS will display a "File exists" error. Append, or error: The command's output will be added to the end of to an existing file. If the file does not exist, 4DOS will display a "File not found" error. ;--------------------------------------------------------------------------- !TOPIC 56 Command Switches for File Selection !NOINDEX The 4DOS file processing commands (606COPY, 609DEL, 646MOVE, 658REN, 677TYPE, etc.) support several standard switches for selecting files to process. Be sure to see the individual commands for details on which switches are supported for each command and how they work, and for additional switches specific to each command. The common file selection switches include: /A:[[+|-]rhsad]: Select files based on their attributes. Preceding an attribute letter with a hyphen [-] will select files that do not have that attribute set. You can OR attributes by preceding each attribute letter with a plus sign [+]. For example: dir /a:rh lists all files with both the read-only and hidden attributes set dir /a:-a lists files which do not have the archive attribute dir /a:d lists subdirectories only, not files dir /a:-d lists files only, not subdirectories dir /a:+s+h lists all files with either the system or the hidden attribute (or both) set See 946File Attributes and Time Stamps for more information on attributes. /I"text": Select files based on their description. 073Wildcards are supported. The search text must be enclosed in quotation marks, and must follow the /I immediately, with no intervening spaces. del /i"*agua*" *.txt deletes all .TXT files with the string "agua" somewhere in the file description del /i"[]" *.txt deletes all .TXT files which do not have a description See 611DESCRIBE for details on file descriptions. /N: Don't actually process any files. This allows you to test what the results of a command would be, without actually performing the operation. /P: Prompt for confirmation of each file individually. See also 045Page and File Prompts. /S: Process files in the current (or specified) directory and all of its subdirectories. In most cases, /S will not search into subdirectories with the hidden or system attributes set unless you also specify /A:. Do not use /S in combination with 057@file lists! ;--------------------------------------------------------------------------- !TOPIC 57 @File Lists !NOINDEX Certain 4DOS file processing commands allow you to specify the files you want to process in a file list instead of on the command line. We call these "@file lists" because the "@" sign is used in the command, preceding the list filename. An @file list is simply a standard ASCII file containing the names of the files to process, one per line. This allows you to create a list of files for processing using output from 612DIR /B, DIR /F, or 625FFIND, a text editor, or any other method that produces a file in the proper format. Paths may be included in the file; see below for details. @File lists are supported by the 596ATTRIB, 606COPY, 609DEL, 611DESCRIBE, 623EXCEPT, 697HEAD, 640LIST, 646MOVE, 655RD / RMDIR, 658REN, 698TAIL, 674TOUCH, and 677TYPE commands. Note: Elements of an @file list are always processed exactly "as is". No further checking is done. This means that if a command allows options to restrict operations based on age (/U, /C), ranges (/[d..., /[t...), descriptions (/I), attributes (/A:), or location (/S), those options will not apply to the @file contents. To use an @file list, precede its name with an "@" sign in the command. For example, to copy all of the files listed in MYLIST.TXT to D:\SAVE\: c:\> copy @mylist.txt d:\save\ If you use a drive and/or path specification the "@" sign can appear before the path or before the file name. For example, these are equivalent: c:\> copy @e:\lists\mylist.txt d:\save\ c:\> copy e:\lists\@mylist.txt d:\save\ To use appropriately formatted data on the Windows clipboard as an @file list use @CLIP: as the file name, for example: c:\> copy @clip: d:\save\ @File Lists, Paths, and Subdirectories The entries in @file lists may contain no path, a relative path, or an absolute path, for example: file1 mydir\file1 d:\data\mydir\file1 If a filename has no path the command processor will look for the file in the directory that is current when the operation takes place. Similarly, if a relative path is used it will be interpreted as relative to the directory that is current when the operation takes place. @file lists should not be used with the subdirectory switches in file processing commands (COPY /S, DEL /S, etc.). To process files listed in a single @file list across multiple subdirectories use 626FOR's ability to read the list and handle each file name individually, for example: for %file in (@flist) copy /s %file d:\target\ @File Lists and "@" Signs in File Names Note that the "@" sign is a rarely used, but legal filename character in some environments. If a file whose name begins with @ exists and you attempt to use an @file list with the same name, the file whose name begins with @ will take precedence. For example, if C:\ contains both a file named @MYLIST.TXT and another named MYLIST.TXT, this command: c:\> copy @mylist.txt d:\save\ will copy the single file @MYLIST.TXT to D:\SAVE\, and will not process the list of files in MYLIST.TXT. To avoid this confusion, use a different name for one of the files. ;--------------------------------------------------------------------------- !TOPIC 58 Command Names and Parameters !NOINDEX When you enter a command you type its name at the prompt, followed by a space and any parameters for the command. For example, all of these could be valid commands: c:\> dir c:\> copy file1 file2 d:\ c:\> f:\util\mapmem /v c:\> "c:\program files\jp software\take command\tcmd.exe" /l The last three commands above include both a command name, and one or more parameters. There are no spaces within the command name (except in quoted file names), but there is a space between the command name and any parameters, and there are spaces between the parameters. Some commands may work when parameters are entered directly after the command (without an intervening space, e.g. DIR/P), or when several parameters are entered without spaces between them (e.g. DIR /2/P). A very few older programs may even require this approach. However leaving out spaces in this way is usually technically incorrect, and is not recommended as a general practice, as it may not work for all commands. If the command name includes a path, the elements must be separated with backslashes (e.g. F:\UTIL\MAPMEM). If you are accustomed to Unix syntax where forward slashes are used in command paths, and want 4DOS to recognize this approach, you can set 476UnixPaths to Yes in 4DOS.INI. For more information on command entry see 041Multiple Commands and 044Command Line Length Limits. For details on how 4DOS handles the various elements it finds on the command line see 117Command Parsing. ;--------------------------------------------------------------------------- !TOPIC 71 File Selection !NOINDEX Most internal commands (like COPY, DIR, etc.) work on a file or a group of files. Besides typing the exact name of the file you want to work with, you can use several shorthand forms for naming or selecting files and the applications associated with them. Most of the features explained in this section apply to 4DOS commands only, and can not be used to pass file names to external programs unless those programs were specifically written to support these features. The file selection features are: 072Extended Parent Directory Names 073Wildcards 074Date, Time, and Size Ranges 078File Exclusion Ranges 079Multiple Filenames 080Include Lists 081LFN File Searches 082Executable Extensions 057@File Lists 056Command Switches for File Selection ;--------------------------------------------------------------------------- !TOPIC 72 Extended Parent Directory Names !NOINDEX 4DOS allows you to extend the traditional DOS ".." syntax for naming the parent directory, by adding additional [.] characters. Each additional [.] represents an additional directory level above the current directory. For example, .\FILE.DAT refers to a file in the current directory, ..\FILE.DAT refers to a file one level up (in the parent directory), and ...\FILE.DAT refers to a file two levels up (in the parent of the parent directory). If you are in the C:\DATA\FINANCE\JANUARY directory and want to copy the file LETTERS.DAT from the directory C:\DATA to drive A: C:\DATA\FINANCE\JANUARY> copy ...\LETTERS.DAT A: ;--------------------------------------------------------------------------- !TOPIC 73 Wildcards !NOINDEX Wildcards let you specify a file or group of files by typing a partial filename. The appropriate directory is scanned to find all of the files that match the partial name you have specified. Wildcards are usually used to specify which files should be processed by a command. If you need to specify which files should not be processed see 078File Exclusion Ranges (for internal commands), or 623EXCEPT (for external commands). Most internal commands accept filenames with wildcards anywhere that a full filename can be used. There are two wildcard characters, the asterisk [*] and the question mark [?], plus a special method of specifying a range of permissible characters. An asterisk [*] in a filename means "any zero or more characters in this position." For example: c:\> dir *.* Displays a list of all files in the current directory c:\> dir *.txt Displays a list of all .TXT files in the current directory If you know that the file you are looking for has a base name that begins with ST and an extension that begins with .D, you can find it this way. Filenames such as STATE.DAT, STEVEN.DOC, and ST.D will all be displayed: c:\> dir st*.d* With 4DOS, you can also use the asterisk to match filenames with specific letters somewhere inside the name. The following example will display any file with a .TXT extension that has the letters AM together anywhere inside its base name. It will, for example, display AMPLE.TXT, STAMP.TXT, CLAM.TXT, and AM.TXT: c:\> dir *am*.txt A question mark [?] matches any single filename character. You can put the question mark anywhere in a filename and use as many question marks as you need. The following example will display files with names like LETTER.DOC and LATTER.DAT, and LITTER.DU: c:\> dir l?tter.d?? The use of an asterisk wildcard before other characters, and of the character ranges discussed below, are enhancements to the standard wildcard syntax, and may not work properly with software other than 4DOS and Take Command. "Extra" question marks in your wildcard specification are ignored if the file name is shorter than the wildcard specification. For example, if you have files called LETTER.DOC, LETTER1.DOC, and LETTERA.DOC, this command will display all three names: c:\> dir letter?.doc The file LETTER.DOC is included in the display because the "extra" question mark at the end of "LETTER?" is ignored when matching the shorter name LETTER. In some cases, the question mark wildcard may be too general. You can also specify what characters you want to accept (or exclude) in a particular position in the filename by using square brackets. Inside the brackets, you can put the individual acceptable characters or ranges of characters. For example, if you wanted to match LETTER0.DOC through LETTER9.DOC, you could use this command: c:\> dir letter[0-9].doc You could find all files that have a vowel as the second letter in their name this way. This example also demonstrates how to mix the wildcard characters: c:\> dir ?[aeiouy]*.* You can exclude a group of characters or a range of characters by using an exclamation mark [!] as the first character inside the brackets. This example displays all filenames that are at least 2 characters long except those which have a vowel as the second letter in their names: c:\> dir ?[!aeiouy]*.* The next example, which selects files such as AIP, BIP, and TIP but not NIP, demonstrates how you can use multiple ranges inside the brackets. It will accept a file that begins with an A, B, C, D, T, U, or V: c:\> dir [a-dt-v]ip You may use a question mark character inside the brackets, but its meaning is slightly different than a normal (unbracketed) question mark wildcard. A normal question mark wildcard matches any character, but will be ignored when matching a name shorter than the wildcard specification, as described above. A question mark inside brackets will match any character, but will not be discarded when matching shorter filenames. For example: c:\> dir letter[?].doc will display LETTER1.DOC and LETTERA.DOC, but not LETTER.DOC. A pair of brackets with no characters between them [], or an exclamation point and question mark together [!?], will match only if there is no character in that position. For example, c:\> dir letter[].doc will not display LETTER1.DOC or LETTERA.DOC, but will display LETTER.DOC. This is most useful for commands like c:\> dir /I"[]" *.btm which will display a list of all .BTM files which don't have a description because the empty brackets match only an empty description string (DIR /I selects files to display based on their descriptions). You can repeat any of the wildcard characters in any combination you desire within a single file name. For example, the following command lists all files which have an A, B, or C as the third character, followed by zero or more additional characters, followed by a D, E, or F, followed optionally by some additional characters, and with an extension beginning with P or Q. You probably won't need to do anything this complex, but we've included it to show you the flexibility of extended wildcards: c:\> dir ??[abc]*[def]*.[pq]* You can also use the square bracket wildcard syntax to work around a conflict between long filenames containing semicolons [;], and the use of a semicolon to indicate an 080Include List. For example, if you have a file named C:\DATA\LETTER1;V2 and you enter this command: c:\> del \data\letter1;v2 you will not get the results you expect. Instead of deleting the named file, 4DOS will attempt to delete LETTER1 and then V2, because the semicolon indicates an include list. However, if you use square brackets around the semicolon it will be interpreted as a filename character, and not as an include list separator. For example, this command would delete the file named above: c:\> del \data\letter1[;]v2 Also, extra caution should be taken using wildcards on long file names because operations using wildcards will be performed on both long and short filenames. See 081LFN File Searches for more information. ;--------------------------------------------------------------------------- !TOPIC 74 Ranges -- Date, Time, and Size Ranges !NOINDEX Most internal commands which accept wildcards also allow date, time, and size ranges to further define the files that you wish to work with. 4DOS will examine each file's size and timestamp (a record of when the file was created, last modified, or last accessed) to determine if the file meets the range criteria you have specified. (4DOS also supports 078File Exclusion Ranges to exclude files from a command. These are similar to date, time, and size ranges, but have a slightly different purpose and therefore are documented separately.) A range begins with the switch character (usually a slash [/]), followed by a left square bracket ("[") and a character that specifies the range type: "s" for a size range, "d" for a date range, or "t" for a time range. The "s", "d", or "t" is followed by a start value, and an optional comma and end value. The range ends with a right square bracket ("]"). For example, to select files between 100 and 200 bytes long you could use the range /[s100,200]. See the individual range types for details on specifying ranges: 075Size Ranges 076Date Ranges 077Time Ranges Using Ranges All ranges are inclusive. For example, a size range which selects files from 10,000 to 20,000 bytes long will match files that are exactly 10,000 bytes and 20,000 bytes long, as well as all sizes in between; a date range that selects files last modified between 6-27-2000 and 6-30-2000 will include files modified on each of those dates, and on the two days in between. If you reverse range start and end values 4DOS will recognize the reversal, and will use the second (lower) value as the start point of the range and the first (higher) value as its end point. For example, selecting files between 100 and 200 bytes long could also be entered as /[s200,100]. If you combine two types of ranges, a file must satisfy both ranges to be included. For example, /[d2-8-00,2-9-00] /[s1024,2048] means files last modified between February 8 and February 9, 2000, which are also between 1,024 and 2,048 bytes long. When you use a date, time, size, or file exclusion range in a command, it should immediately follow the command name, so that any additional switches for the command are after any range(s) used. If the range is placed later in the command it may be ignored, or cause an error. Unlike some command switches which apply to only part of the command line, the range usually applies to all file names specified for the command. For example: c:\> dir /[d6-1-00,+0] *.c Get a directory of all the *.C files dated June 1, 2000. c:\> del /[s0,0] *.* /s Delete all the 0-byte files on the hard disk. c:\> copy /[d-1] /[s1] *.* a: Copy all the non-zero byte files that were changed yesterday or today. c:\> copy /[s10k,20k] *.* a: Copy all the files with sizes from 10,000 to 20,000 bytes to drive A:. Drives which support long filenames (e.g. under Windows 95/98/ME, or under plain DOS with a suitable LFN driver loaded) maintain 3 sets of dates and times for each file: creation, last access, and last write (for last access only the date is recorded; the last access time is always returned as 00:00). By default, date and time ranges work with the last write time stamp. You can use the "last access" (a) or "created" (c) time stamp in a date or time range with the syntax: /[da...] or /[dc...] or /[ta...] or /[tc...] For example, to select files that were last accessed yesterday or today: /[da-1] Date, time, and size ranges can be used with the 596ATTRIB, 606COPY, 609DEL, 611DESCRIBE, 612DIR, 615DO, 623EXCEPT, 625FFIND, 626FOR, 697HEAD, 640LIST, 646MOVE, 655RD / RMDIR, 658REN, 662SELECT, 698TAIL, 674TOUCH, 675TREE, and 677TYPE commands. They cannot be used with filename completion or in filename arguments for variable functions. ;--------------------------------------------------------------------------- !TOPIC 75 Size Ranges !NOINDEX Size ranges simply select files whose size is between the limits given. For example, /[s10000,20000] selects files between 10,000 and 20,000 bytes long. Either or both values in a size range can end with "k" to indicate thousands of bytes, "K" to indicate kilobytes (1,024 bytes), "m" to indicate millions of bytes, "M" to indicate megabytes (1,048,576 bytes), "g" to indicate billions of bytes or "G" to indicate gigabytes (1,073,741,824 bytes). For example, the range above could be rewritten as /[s10k,20k]. The second argument of a size range is optional. If you use a single argument, like /[s10k], you will select files of that size or larger. You can also precede the second argument with a plus sign [+]; when you do, it is added to the first value to determine the largest file size to include in the search. For example, /[s10k,+1k] select files from 10,000 through 11,000 bytes in size. Some further examples of size ranges: Specification Selects Files /[s0,0] of length zero (empty) /[s1M] 1 megabyte or more in length /[s10k,+200] between 10,000 and 10,200 bytes ;--------------------------------------------------------------------------- !TOPIC 76 Date Ranges !NOINDEX Date ranges select files that were created or last modified at any time between the two dates. For example, /[d12-1-99,12-5-99] selects files that were last modified between December 1, 1999, and December 5, 1999. You can use hyphens, slashes, or periods to separate the month, day, and year. 4DOS generally accepts dates between January 1, 1980 and December 31, 2099. The year can be entered as a 2-digit or 4-digit value. Two-digit years between 80 and 99 are interpreted as 1980 - 1999; values between 00 and 79 are interpreted as 2000 - 2079. References to years beyond 2079 must be entered with 4 digits. For example, /[d12-31-99,1-1-00] is equivalent to /[d12-31-1999,1-1-2000], and selects files modified on December 31, 1999 or January 1, 2000. If an argument begins with a four digit year greater than 1900, it's assumed to be a date in the ISO 8601 international format (yyyy-mm-dd). If the date contains the letter "W", it is assumed to be in the ISO 8601 week date format yyyy-Www-d, where yyyy = year, ww = week, d = week day. If the date is entered as two numbers in the format yyyy-ddd, it is assumed to be in the ISO 8601 ordinal date format, where yyyy = year, ddd = day of the year. The time for the starting date defaults to 00:00:00 and the time for the ending date defaults to 23:59:59. You can alter these defaults, if you wish, by including a start and stop time inside the date range. The time is separated from the date with an at sign [@]. For example, the range /[d7-1-00@8:00a,7-3-00@6:00p] selects files that were modified at any time between 8:00 am on July 1, 2000 and 6:00 pm on July 3, 2000. If you prefer, you can specify the times in 24-hour format (e.g., @18:00 for the end time in the previous example). If you omit the second argument in a date range, 4DOS substitutes the current date and time. For example, /[d10-1-99] selects files dated between October 1, 1999 and today. You can use an offset value for either the beginning or ending date, or both. An offset begins with a plus sign [+] or a minus sign [-] followed by an integer. If you use an offset for the second value, it is calculated relative to the first. If you use an offset for the first (or only) value, the current date is used as the basis for calculation. For example: Specification Selects Files /[d10-27-99,+3] modified between 10-27-99 and 10-30-99 /[d10-27-99,-3] modified between 10-24-99 and 10-27-99 /[d-0] modified today (from today minus zero days, to today) /[d-1] modified yesterday or today (from today minus one day, to today) /[d-1,+0] modified yesterday (from today minus one day, to zero days after that) As a shorthand way of specifying files modified today, you can also use /[d]; this has the same effect as the /[d-0] example shown above. To select files last modified n days ago or earlier, use /[dn,1/1/80]. For example, to get a directory of all files last modified 3 days or more before today (i.e., those files not modified within the last 3 days), you could use this command: c:\> dir /[d-3,1/1/80] This reversed date range (with the later date given first) will be handled correctly by 4DOS. It takes advantage of the facts that an offset in the start date is relative to today, and that the base or "zero" point for PC file dates is January 1, 1980. Note: If you do not specify a time in a reversed date range, the default times will be applied before the first and second dates are swapped to become the ending and starting dates respectively. If you want to include the entire first and last days of a reversed date range, simply add a specific @00:00:00 to your intended start date and a @23:59:59 to your intended end date. You cannot use offsets in the time portion of a date range (the part after an @ sign), but you can combine a time with a date offset. For example, /[d12-8-99@12:00,+2@12:00] selects files that were last modified between noon on December 8 and noon on December 10, 1999. Similarly, /[d-2@15:00,+1] selects files last modified between 3:00 pm the day before yesterday and the end of the day one day after that, i.e., yesterday. The second time defaults to the end of the day because no time is given. Drives which support long filenames (e.g. under Windows 95/98/ME, or under plain DOS with a suitable LFN driver loaded) maintain 3 sets of dates and times for each file: creation, last access, and last write (for last access only the date is recorded; the last access time is always returned as 00:00). By default, date ranges work with the last write time stamp. You can use the "last access" (a) or "created" (c) date/time stamp in a date range with the syntax: /[da...] or /[dc...] For example, to select files that were last accessed yesterday or today: /[da-1] ;--------------------------------------------------------------------------- !TOPIC 77 Time Ranges !NOINDEX A time range specifies a file modification time without reference to the date. For example, to select files modified between noon and 2:00 pm on any date, use /[t12:00p,2:00p]. The times in a time range can either be in 12-hour format, with a trailing "a" for AM or "p" for PM, or in 24-hour format. If you omit the second argument in a time range, you will select files that were modified between the first time and the current time, on any date. You can also use offsets, beginning with a plus sign [+] or a minus sign [-] for either or both of the arguments in a time range. The offset values are interpreted as minutes. Some examples: Specification Selects Files /[t12:00p,+120] modified between noon and 2:00 PM on any date /[t-120,+120] modified between two hours ago and the current time on any date /[t0:00,11:59] modified in the morning on any date Drives which support long filenames (e.g. under Windows 95/98/ME, or under plain DOS with a suitable LFN driver loaded) maintain 3 sets of dates and times for each file: creation, last access, and last write (for last access only the date is recorded; the last access time is always returned as 00:00). By default, time ranges work with the last write time stamp. You can use the "last access" (a) or "created" (c) time stamp in a time range with the syntax: /[ta...] or /[tc...] ;--------------------------------------------------------------------------- !TOPIC 78 File Exclusion Ranges !NOINDEX Most internal commands which accept wildcards also accept file exclusion ranges to further define the files that you wish to work with. 4DOS examines each file name and excludes files that match the names you have specified in a file exclusion range. A file exclusion range begins with the switch character (usually a slash), followed by a left square bracket and an exclamation mark ("[!") The range ends with a right square bracket ("]"). Inside the brackets, you can list one or more filenames to be excluded from the command. The filenames can include wildcards and extended wildcards, but cannot include path names or drive letters. The following example will display all files in the current directory except backup files (files with the extension .BAK or .BKP): c:\> dir /[!*.bak *.bkp] *.* You can combine file exclusion ranges with 074date, time, and size ranges. This example displays all files that are 10K bytes or larger in size and that were created in the last 7 days, except .C and .H files: c:\> dir /[s10k] /[d-7] /[!*.c *.h] *.* File exclusion ranges will only work for 4DOS internal commands. The 623EXCEPT command can be used to exclude files from processing by many external commands. When you use a file exclusion range in a command it should immediately follow the command name. See Using Ranges under 074Date, Time, and Size Ranges for additional details. See also 080Include Lists. ;--------------------------------------------------------------------------- !TOPIC 79 Multiple Filenames !NOINDEX Most file processing commands can work with multiple files at one time. To use multiple file names, you simply list the files one after another on the command line, separated by spaces. You can use wildcards in any or all of the filenames. For example, to copy all .TXT and .DOC files from the current directory to drive A, you could use this command: c:\> copy *.txt *.doc a: If the files you want to work with are not in the default directory, you must include the full path with each filename: c:\> copy a:\details\file1.txt a:\details\file1.doc c: Multiple filenames are handy when you want to work with a group of files which cannot be defined with a single filename and wildcards. They let you be very specific about which files you want to work with in a command. (For another method which allows you to specify multiple filenames with a single path before them, see 080Include Lists.) Caution: When you use multiple filenames with a command that expects both a source and a destination, like 606COPY or 646MOVE, be sure that you always include a specific destination on the command line. If you don't, the command will assume that the last filename is the destination and may overwrite important files. Like extended wildcards and include lists, the multiple filenames will work with internal commands but not with external programs, unless those programs have been written to handle multiple file names on the command line. If you have a list of files to process that's too long to put on the command line or too time-consuming to type, see 626FOR or 662SELECT for another way of passing multiple file names to a command. ;--------------------------------------------------------------------------- !TOPIC 80 Include Lists !NOINDEX Any internal command that accepts 079multiple filenames will also accept one or more include lists. An include list is simply a group of filenames, with or without wildcards, separated by semicolons [;]. All files in the include list must be in the same directory. You may not add a space on either side of the semicolon. For example, you can shorten this command which uses multiple file names: c:\> copy a:\details\file1.txt a:\details\file1.doc c: to this using an include list: c:\> copy a:\details\file1.txt;file1.doc c: Include lists are similar to multiple filenames, but have three important differences. First, you don't have to repeat the path to your files if you use an include list, because all of the included files must be in the same directory. Second, if you use include lists, you aren't as likely to accidentally overwrite files if you forget a destination path for commands like COPY, because the last name in the list will be part of the include list, and won't be seen as the destination file name. Include lists can only be used as the source parameter (the location files are coming from) for COPY and other similar commands. They cannot be used to specify a destination for files. Third, multiple filenames and include lists are processed differently by the 612DIR and 662SELECT commands. If you use multiple filenames, all of the files matching the first filename are processed, then all of the files matching the second name, and so on. When you use an include list, all files that match any entry in the include list are processed together, and will appear together in the directory display or SELECT list. You can see this difference clearly if you experiment with both techniques and the DIR command. For example: c:\> dir *.txt *.doc Lists the .TXT files then the .DOC files, in two separate lists. c:\> dir *.txt;*.doc Lists the .TXT and .DOC files in a single list. Like extended wildcards and multiple filenames, the include list feature will work with internal commands, but not with most external programs (unless they have been programmed to support them). The maximum length of an include list is 260 characters. See also 078File Exclusion Ranges. ;--------------------------------------------------------------------------- !TOPIC 81 LFN File Searches !NOINDEX In an LFN environment like vDosPlus, files on volumes which support long filenames (VFAT, FAT32, etc. volumes) can have both a long file name (LFN) and a short FAT-compatible file name. 4DOS normally examines both forms of each file name when searching for files. It does so in order to remain compatible with the default command processor, COMMAND.COM. The long filename is checked first, and if it does not match then the short name is checked. Matching files which have only a short filename will be found during the first search, because in that case Windows treats the short name as if it were a long name. For example, suppose you have two files in a directory with these names: Long Name Short Name --------------- ------------ Letter Home.DOC LETTER~1.DOC Letter02.DOC LETTER02.DOC A search for LETTER??.DOC will find both files. The second file (LETTER02.DOC) will be found during the search of long filenames. The firstfile ("Letter Home.DOC") will be found during the search of short filenames. You can change this default behavior with the 447Win95SFNSearch directive in 4DOS.INI. Set Win95SFNSearch to No to disable the secondary short filename search. This will prevent the potential problem described above, but will make 4DOS's behavior inconsistent with that of COMMAND.COM. Caution: Take extra care when you use wildcards to perform operations on LFN volumes because you may select more files than you intended. For example, Windows often creates short filenames that end "~1.", "~2.", etc. If you use a command like: del *1.* you will delete all such files, including most files with long filenames, which is probably not the result you intended! ;--------------------------------------------------------------------------- !TOPIC 82 Executable Extensions !NOINDEX Normally, when you type a filename (as opposed to an alias or internal command name) as the first word on the command line, 4DOS looks for a file with that name to execute. The file's extension may be .EXE or .COM to indicate that it contains a program; or .BTM or .BAT to indicate a batch file. The exact list of default extensions for executable files varies slightly depending on which operating system you use, because each has its own rules for batch file extensions. (See 649PATH and 143PATHEXT for additional ways to control the search for executable files.) You can add to the default list of extensions, and have 4DOS take the action you want with files that are not executable programs or batch files. The action taken is always based on the file's extension. For example, you could start your text editor whenever you type the name of a .DOC file, or start your database manager whenever you type the name of a .DAT file. You use environment variables to define the internal command, external program, batch file, or alias to run for each defined file extension. To create an executable extension for use only in 4DOS, use the SET command to create a new environment variable. An environment variable is recognized as an executable extension if its name begins with a period. The syntax for creating an executable extension is: set .ext=command [options] where .EXT is the executable file extension; command is the name of the internal command, external program, alias, or batch file to run; and [options] are any command-line startup options you want to specify for the program, batch file, or alias. You can specify multiple extensions for a single command by separating them with semicolons, for example: set .txt;.doc;.lst=command [options] For example, if you want to run a word processor called EDITOR whenever you type the name of a file that has an extension of .EDT, you could use this command: c:\> set .edt=c:\edit\editor.exe If the command is a batch file or external program, 4DOS will search the 138PATH for it if necessary. However, you can make sure that the correct program or batch file is used, and speed up the executable extension, by specifying the full name including drive, path, filename, and extension. This example defines B.EXE (the Boxer text editor) as the processor for .MAK files: c:\> set .mak=c:\boxer\b.exe -s With this definition, if you have a file named INIT.MAK in the current directory and enter the command: c:\source> init 4DOS will execute the command: c:\boxer\b.exe -s c:\source\init.mak Notice that the full pathname of INIT.MAK is automatically included. If you enter parameters on the command line, they are appended to the end of the command. For example, if you changed the above entry to: c:\source> init -w 4DOS would execute the command: c:\boxer\b.exe -s c:\source\init.mak -w In order for executable extensions to work, the command, program, batch file, or alias must be able to interpret the command line properly. For example, if a program you want to run doesn't accept a file name on its command line as shown in these examples, then executable extensions won't work with that program. However, you can always point it to a 4DOS batch file which will do the necessary parameter conversions for you and then call the desired destination program. Executable extensions may include 073wildcards, so you could, for example, run your text editor for any file with an extension beginning with T by defining an executable extension called .T*. Extended wildcards (e.g., DO[CT] for .DOC and .DOT files) may also be used. To remove an executable extension, use the 680UNSET command to remove the corresponding variable. ;--------------------------------------------------------------------------- !TOPIC 83 Critical Errors !NOINDEX DOS watches for physical errors during input and output operations. Physical errors are those due to hardware problems. These errors are called critical errors because DOS, 4DOS, or your application program cannot proceed until the error is resolved. When a critical error occurs, you will see a message asking you to choose one of four error handling options. The message comes from 4DOS or your application, and will vary slightly depending on your operating system and whether you are in full-screen or windowed mode. However, the options and their neanings are similar in all cases: Retry Retry the operation. Choose this option if you have corrected the problem. Ignore Ignore the error and continue. Use caution when choosing this option. Ignoring critical errors, especially on the hard disk, can cause errors in your applications or damage data on the disk. Fail Tell the program that the operation failed. This option returns an error code to 4DOS or to the application program that was running when the error occurred. 4DOS generally stops the current command when an operation fails. This option is not available for all errors; if you don't see it, use Abort instead. You can force a Fail response to all critical errors with the 562CritFail directive in 4DOS.INI. Abort Abort the program. Choose this option to stop the program that was running when the error occurred. Choosing Abort will abort the command, but not 4DOS itself. ;--------------------------------------------------------------------------- !TOPIC 84 Conditional Commands !NOINDEX When an internal command or external program finishes, it returns a result called the exit code. Conditional commands allow you to perform tasks based upon the previous command's exit code. Many programs return a 0 if they are successful and a non-zero value if they encounter an error. If you separate two commands by && (AND), the second command will be executed only if the first returns an exit code of 0. For example, the following command will only erase files if the BACKUP operation succeeds: c:\> backup c:\ a: && del c:\*.bak;*.lst If you separate two commands by || (OR), the second command will be executed only if the first returns a non-zero exit code. For example, if the following BACKUP operation fails, then ECHO will display a message: c:\> backup c:\ a: || echo Error in the backup! All internal commands return an exit code, but not all external programs do. Conditional commands will behave unpredictably if you use them with external programs which do not return an explicit exit code. To determine whether a particular external program returns a meaningful exit code use an ECHO %? command immediately after the program is finished. If the program's documentation does not discuss exit codes you may need to experiment with a variety of conditions to see how the exit code changes. ;--------------------------------------------------------------------------- !TOPIC 85 Command Grouping !NOINDEX Command grouping allows you to group a set of commands together logically by enclosing them in parentheses. The parentheses are similar in function to the BEGIN and END block statements in some programming languages. There are two primary uses for command grouping. One is to execute multiple commands in a place where normally only a single command is allowed. For example, suppose you want to execute two different 658REN commands in all subdirectories of your hard disk. You could do it like this: c:\> global ren *.wx1 *.wxo c:\> global ren *.tx1 *.txo But with command grouping you can do the same thing in one command: c:\> global (ren *.wx1 *.wxo ^ ren *.tx1 *.txo) The two REN commands enclosed in the parentheses appear to 628GLOBAL as if they were a single command, so both commands are executed for every directory, but the directories are only scanned once, not twice. This kind of command grouping is most useful with the 623EXCEPT, 626FOR, 628GLOBAL, and 633IF commands. When you use this approach in a batch file you must either place all of the commands in the group on one line, or place the opening parenthesis at the end of a line and place the commands on subsequent lines. For example, the first two of these sequences will work properly, but the third will not: for %f in (1 2 3) (echo hello %f ^ echo goodbye %f) for %f in (1 2 3) ( echo hello %f echo goodbye %f ) for %f in (1 2 3) (echo hello %f echo goodbye %f) The second common use of command grouping is to 050redirect input or output for several commands without repeatedly using the redirection symbols. For example, consider the following batch file fragment which places some header lines (including today's date) and directory displays in an output file using redirection. The first ECHO command creates the file using >, and the other commands append to the file using >>: echo Data files %_date > filelist dir *.dat >> filelist echo. >> filelist echo Text files %_date >> filelist dir *.txt >> filelist Using command grouping, these commands can be written much more simply. Enter this example on one line: (echo Data files %_date ^ dir *.dat ^ echo. ^ echo Text files %_date ^ dir *.txt) > filelist The redirection applies to all the commands within the parentheses. Because the redirection is performed only once, the commands will run slightly faster than if each command was entered separately. The same approach can be used for input 051redirection and for 052piping. You can also use command grouping in a batch file or at the prompt to split commands over several lines. This last example is like the redirection example above, but is entered at the prompt. Note the "More?" prompt after each incomplete line. None of the commands are executed until the command group is completed with the closing parenthesis. This example does not have to be entered on one line: c:\> (echo Data files %_date More? dir *.dat More? echo. More? echo Text files %_date More? dir *.txt) > filelist c:\> A group of commands in parentheses is like a long command line. The total length of the group may not exceed 511 characters in 4DOS, whether the commands are entered from the prompt, an alias, or a batch file. The limit includes the space required to expand aliases and environment variables used within the group. In addition, each line you type at the normal prompt or the More? prompt, and each individual command within the line, must meet the length limit of 511 characters. ;--------------------------------------------------------------------------- !TOPIC 86 Escape Character !NOINDEX 4DOS recognizes a user-definable escape character. This character gives the following character a special meaning; it is not the same as the ASCII ESC that is often used in 915ANSI and printer control sequences. The default escape character is Ctrl-X (ASCII 24), which will be displayed here as an up arrow []. If you don't like using the default escape character, you can pick another character using the 664SETDOS /E command, the Options 1 page of the 648OPTION dialogs, or the 426EscapeChar directive in 4DOS.INI. If you plan to share aliases or batch files between 4DOS and 0204NT or 021Take Command, see 054Special Character Compatibility for details about choosing compatible escape characters for two or more products. Ten special characters are recognized when they are preceded by the escape character. The combination of the escape character and one of these characters is translated to a single character, as shown below. These are useful for redirecting codes to the printer; e is also useful to generate 915ANSI escape sequences in your 652PROMPT, 619ECHO, or other output commands. The special characters which can follow the escape character are: b backspace c comma e the ASCII ESC character (ASCII 27) f form feed k back quote n line feed q double quote r carriage return s space t tab character If you follow the escape character with any other character, the escape character is removed and the second character is copied directly to the command line. This allows you to suppress the normal meaning of special characters (such as ? * / \ | " ` > < and &). For example, to display a message containing a < symbol, which normally indicates redirection: c:\> echo 2 is < 4 To send a form feed followed by the sequence ESC Y to the printer, you can use this command: c:\> echos feY > prn The escape character has an additional use when it is the last character on any line of a .BAT or .BTM batch file. 4DOS recognizes this use of the escape character to signal line continuation: 4DOS removes the escape character and appends the next line to the current line before executing it. ;--------------------------------------------------------------------------- !TOPIC 101 Aliases !NOINDEX Much of the power of 4DOS comes together in aliases, which give you the ability to create your own commands. An alias is a name that you select for a command or group of commands. Simple aliases substitute a new name for an existing command. More complex aliases can redefine the default settings of internal or external commands, operate as very fast in-memory batch files, and perform commands based on the results of other commands. This topic will show you some examples of the power of aliases. See the 595ALIAS command for complete details about writing your own aliases. The simplest type of alias gives a new name to an existing command. For example, you could create a command called ROOT which uses 601CD to switch to the root directory this way: c:\> alias root = cd \ After the alias has been defined this way, every time you type the command ROOT, you will actually execute the command CD \. Aliases can also create customized versions of commands. For example, the 612DIR command can sort a directory in various ways. You can create an alias called DE that means "sort the directory by filename extension, and pause after each page while displaying it" like this: c:\> alias de = dir /oe /p Aliases can be used to execute sequences of commands as well. The following command creates an alias called W which saves the current drive and directory, changes to the WP directory on drive C, runs the program E:\WP60\WP.EXE, and, when the program terminates, returns to the original drive and directory: c:\> alias w = `pushd c:\wp ^ e:\wp60\wp.exe ^ popd` This alias is enclosed in back-quotes because it contains multiple commands. You must use the back-quotes whenever an alias contains multiple commands, environment variables, parameters (see below), redirection, or piping. See the 595ALIAS command for full details. Aliases can be nested, that is, one alias can invoke another. For example, the alias above could also be written as: c:\> alias wp = e:\wp60\wp.exe c:\> alias w = `pushd c:\wp ^ wp ^ popd` If you enter W as a command, 4DOS will execute the 653PUSHD command, detect that the next command (WP) is another alias, and execute the program E:\WP60\WP.EXE, and - when the program exits - return to the first alias, execute the 651POPD command, and return to the prompt. You can use aliases to change the default options for both internal commands and external commands. Suppose that you always want the 609DEL command to prompt before it erases a file: c:\> alias del = *del /p An asterisk [*] is used in front of the second "del" to show that it is the name of an internal command, not an alias. See the 595ALIAS command for more information about this use of the asterisk. You may have a program on your system that has the same name as an internal command. Normally, if you type the command name, you will start the internal command rather than the program you desire, unless you explicitly add its full path on the command line. For example, if you have a program named LIST.COM in the C:\UTIL directory, you could run it with the command C:\UTIL\LIST.COM. However, if you simply type LIST, the internal 640LIST command will be invoked instead. Aliases give you two ways to get around this problem. First, you could define an alias that runs the program in question, but with a different name: c:\> alias l = c:\util\list.com Another approach is to rename the internal command and use the original name for the external program. The following example renames the LIST command as DISPLAY and then uses a second alias to run LIST.COM whenever you type LIST: c:\> alias display = *list c:\> alias list = c:\util\list.com You can also assign an alias to a key, so that every time you press the key, the command will be invoked. You do so by naming the alias with an at sign [@] followed by a key name. After you enter this next example, you will see a 2-column directory with paging whenever you press Shift-F5, then Enter: c:\> alias @Shift-F5 = *dir /2/p This alias will put the 612DIR command on the command line when you press Shift-F5, then wait for you to enter file names or additional switches. You must press Enter when you are ready to execute the command. To execute the command immediately, without displaying it on the command line or waiting for you to press Enter, use two at signs at the start of the alias name: c:\> alias @@Shift-F5 = *dir /2/p The next example clears the screen whenever you press Alt-F1: c:\> alias @@Alt-F1 = cls Aliases have many other capabilities as well. This example creates a simple command-line calculator using the 263@EVAL function. Once you have entered the example, you can type CALC 4*19, for example, and you will see the answer: c:\> alias calc = `echo The answer is: %@eval[%&]` Our last example in this section creates an alias called IN. It will temporarily change directories, run an internal or external command, and then return to the current directory when the command is finished: c:\> alias in = `pushd %1 ^ %2& ^ popd` Now if you type c:\> in c:\letters wp letter.txt you will change to the C:\LETTERS subdirectory, execute the command WP LETTER.TXT and then return to the current directory. The above example uses two parameters: %1 means the first argument on the command line, and %2& means the second and all subsequent arguments. Parameters are explained in detail under the 595ALIAS command. See the 595ALIAS and 678UNALIAS commands for more information and examples, and also 111Using Aliases in Batch Files. ;--------------------------------------------------------------------------- !TOPIC 102 Batch Files !NOINDEX A batch file is a file that contains a list of commands to execute. 4DOS reads and interprets each line as if it had been typed at the keyboard. Like 595aliases, batch files are handy for automating computing tasks. Unlike aliases, batch files can be as long as you wish. Batch files take up separate disk space for each file, and can't usually execute quite as quickly as aliases, since they must be read from the disk. The topics included in this section are: 103.BAT and .BTM Files 104Echoing in Batch Files 105Parameters 106Using Environment Variables 107Batch File Commands 108Interrupting a Batch File 109Automatic Batch Files (4START and 4EXIT) 110Detecting 4DOS and other JP Software shells 111Using Aliases in Batch Files 112Debugging Batch Files 113String Processing 114Line Continuation 115Batch File Compression 054Special Character Compatibility 117Command Parsing 118Argument Quoting 116REXX Support ;--------------------------------------------------------------------------- !TOPIC 103 .BAT and .BTM Files !NOINDEX A batch file can run in two different modes. In the first, traditional mode, each line of the batch file is read and executed individually. In the second mode, the entire batch file is read into memory at once. The second mode can be 5 to 10 times faster, especially if most of the commands in the batch file are internal commands. However, only the first mode can be used for self-modifying batch files (which are rare), or for batch files which install memory-resident utilities. The batch file's extension determines its mode. Files with a .BAT extension are run in the slower, traditional mode. Files with a .BTM extension are run in the faster, more efficient mode. You can change the execution mode inside a batch file with the 641LOADBTM command. Under 4DOS, .BTM files must be less than 64K (65536) bytes long. ;--------------------------------------------------------------------------- !TOPIC 104 Echoing in Batch Files !NOINDEX By default, each line in a batch file is displayed or "echoed" as it is executed. You can change this behavior, if you want, in several different ways: !INDENT 5 5 5 5 Any batch file line that begins with an [@] symbol will not be displayed. The display can be turned off and on within a batch file with the 619ECHO OFF and ECHO ON commands. The default setting can be changed with the 664SETDOS /V command, on the Options 1 page of the 648OPTION dialogs, or the 414BatchEcho directive in 4DOS.INI. !INDENT 0 For example, the following line turns off echoing inside a batch file. The [@] symbol keeps the batch file from displaying the ECHO OFF command: @echo off 4DOS also has a command line echo that is unrelated to the batch file echo setting. See 619ECHO for details about both settings. ;--------------------------------------------------------------------------- !TOPIC 105 Batch File Parameters !NOINDEX Like aliases and application programs, batch files can examine the command line that is used to invoke them. The command tail (everything on the command line after the batch file name) is separated into individual parameters (also called arguments or batch variables) by scanning for the spaces, tabs, and commas that separate the parameters. A batch file can work with the individual parameters or with the command tail as a whole. Batch file parameters are numbered from %1 to %255. %1 refers to the first parameter on the command line, %2 to the second, and so on. You can use quotation marks to pass spaces, tabs, commas, and other special characters in a batch file parameter; see 118Argument Quoting for details. Parameters that are referred to in a batch file, but which are missing on the command line, appear as empty strings inside the batch file. For example, if you start a batch file and put two parameters on the command line, any reference in the batch file to %3, or any higher-numbered parameter, will be interpreted as an empty string. A batch file can also work with three special parameters: %0 contains the name of the batch file as it was entered on the command line, %# contains the number of command line arguments, and %n& contains the complete command-line tail starting with argument number n (for example, %3& means the third parameter and all those after it). %& contains the entire command tail. The values of these special parameters will change if you use the 666SHIFT command. If you wish to use a symbol other than the ampersand [&] to refer to multiple arguments, you can use the 439ParameterChar directive in 4DOS.INI or the 664SETDOS /P command to define a different parameter character. For example, if your batch file interprets the first argument as a subdirectory name then the following line would move to the specified directory: cd %1 A friendlier batch file would check to make sure the directory exists and take some special action if it doesn't: iff isdir %1 then ^ cd %1 else ^ echo Subdirectory %1 does not exist! ^ quit endiff (see the 633IF and 634IFF commands). For compatibility with CMD.EXE, you may also use %* to refer to the entire command tail; %* is mostly equivalent to %&. You cannot, however, specify a number between the percent sign and the asterisk. %4* represents the fourth word in the command tail (%4) followed by a literal asterisk (*), but %4& represents the fourth and all following arguments. Unlike %&, the %* parameter is not affected by the 666SHIFT command. Batch files can also use 131environment variables, 161internal variables, and 241variable functions. ;--------------------------------------------------------------------------- !TOPIC 106 Using Environment Variables !NOINDEX Batch files can also use 131environment variables, 161internal variables, and 241variable functions. You can use these variables and functions to determine system status (e.g., the type of CPU in the system), resource levels (e.g., the amount of free disk space), file information (e.g., the date and time a file was last modified), and other information (e.g., the current date and time). You can also perform arithmetic operations (including date and time arithmetic), manipulate strings and substrings, extract parts of a filename, and read and write files. To create temporary variables for use inside a batch file, just use the 663SET command to store the information you want in an environment variable. Pick a variable name that isn't likely to be in use by some other program (for example, 138PATH would be a bad choice), and use the 680UNSET command to remove these variables from the environment at the end of your batch file. You can use 665SETLOCAL and 621ENDLOCAL to create a "local" environment so that the original environment will be restored when your batch file is finished. Environment variables used in a batch file may contain either numbers or text. It is up to you to keep track of what's in each variable and use it appropriately; if you don't (for example, if you use %263@EVAL to add a number to a text string), you'll get an error message. ;--------------------------------------------------------------------------- !TOPIC 107 Batch File Commands !NOINDEX Several commands are particularly suited to batch file processing. Here is a list of some of the commands you might find most useful: !INDENT 5 5 5 5 597BEEP produces a sound of any pitch and duration through the computer's speaker. 599CALL executes one batch file from within another. 600CANCEL terminates all batch file processing. 604CLS and 605COLOR set the screen display colors. 615DO starts a loop. The loop can be based on a counter, or on a conditional test like those used in IF and IFF. 616DRAWBOX draws a box on the screen. 617DRAWHLINE and 618DRAWVLINE draw horizontal and vertical lines on the screen. 619ECHO and 620ECHOS print text on the screen (the text can also be redirected to a file or device). 689ECHOERR and 690ECHOSERR print text to the standard error device. 629GOSUB executes a subroutine inside a batch file. The 659RETURN command terminates the subroutine. 630GOTO branches to a different location in the batch file. 626FOR executes commands for each file that matches a set of wildcards, or each entry in a list. 633IF and 634IFF execute commands based on a test of string or numeric values, program exit codes, or other conditions. 635INKEY and 636INPUT collect keyboard input from the user and store it in environment variables. 638KEYSTACK sends keystrokes to applications. 641LOADBTM changes the batch file operating mode. 647ON initializes error handling for Ctrl-C / Ctrl-Break, or for program and command errors. 650PAUSE displays a message and waits for the user to press a key. 654QUIT ends the current batch file and optionally returns an exit code. 657REM places a remark in a batch file. 660SCREEN positions the cursor on the screen and optionally prints a message at the new location. 661SCRPUT displays a message in color. 665SETLOCAL saves the current disk drive, default directory, environment, alias list, and special character settings. 621ENDLOCAL restores the settings that were saved. 666SHIFT changes the numbering of the batch file parameters. 669SWITCH selects a group of statements to execute based on the value of a variable. 671TEXT displays a block of text. 671ENDTEXT ends the block. 673TIMER starts or reads a stopwatch. 684VSCRPUT displays a vertical message in color. !INDENT 0 These commands, along with the internal variables and variable functions, make the enhanced batch file language extremely powerful. Your copy of 4DOS includes a sample batch file, in the file EXAMPLES.BTM, that demonstrates some of the things you can do with batch files. ;--------------------------------------------------------------------------- !TOPIC 108 Interrupting a Batch File !NOINDEX You can usually interrupt a batch file by pressing Ctrl-C or Ctrl-Break. Whether and when these keystrokes are recognized will depend on whether 4DOS or an application program is running, how the application (if any) was written, whether 598BREAK is ON or OFF, and whether the 647ON BREAK command is in use. If 4DOS detects a Ctrl-C or Ctrl-Break (and ON BREAK is not in use), it will display a prompt, for example: Cancel batch job C:\CHARGE.BTM ? (Y/N/A) : Enter N to continue, Y to terminate the current batch file and continue with any batch file which called it, or A to end all batch file processing regardless of the batch file nesting level. Answering Y is similar to the 654QUIT command; answering A is similar to the 600CANCEL command. ;--------------------------------------------------------------------------- !TOPIC 109 Automatic Batch Files !NOINDEX 4DOS supports "automatic" batch files, files that run without your intervention, as long as 4DOS can find them. Each time 4DOS starts as either a primary or a secondary shell, it looks for an automatic batch file called 4START.BTM or 4START.BAT. If the 4START batch file is not in the same directory as 4DOS itself (as specified in the 134COMSPEC variable, you should use the Startup page of the 648OPTION dialogs or the 3724StartPath directive in 4DOS.INI to specify its location. 4START is optional, so 4DOS will not display an error message if it cannot find the file. 4START is a convenient place to change the color or content of the prompt for each shell, 643LOG the start of a shell, or put other special startup or configuration commands. With the exception of some 4DOS initialization switches, the entire startup command line passed to 4DOS is available to 4START via 105batch file parameters (%1, %2, etc.). This can be useful if you want to see the command line passed to a secondary shell by an application. For example, to pause if any parameters are passed to a secondary shell you could include this command in 4START (enter this on one line): if "%1" != "" .and. "%_shell" gt 0 pause Starting shell %_shell with parameters [%&] Normally, AUTOEXEC.BAT (.TXT) must be in the Start in folder of vDosPlus. You can store it in a different location (and even give it a different name) by using the 4DOS.INI directive 375AutoExecPath. You can also pass parameters to AUTOEXEC.BAT using the 374AutoExecParms directive in 4DOS.INI. Whenever a 4DOS shell ends, it runs an automatic batch file called 4EXIT.BTM or 4EXIT.BAT. This file, if you use it, should be in the same directory as your 4START batch file. Like 4START, 4EXIT is optional. It is not necessary in most circumstances, but it is a convenient place to put commands to save information such as a history list before a shell ends, or 643LOG the end of the shell. 4START and 4EXIT should not load any memory resident programs (TSRs). Otherwise, these files can include any commands that could be part of any batch file or any commands which you could type from the command line. Pipes, Transient Sessions, and 4START When you set up the 4START file, remember that it is executed every time 4DOS starts, including when running a transient copy of 4DOS started with the /C 352startup option. This could result in your 4DOS sessions executing in the directory set by 4START, not the directory in which 4DOS was originally started. Similarly, any changes to environment variables or other settings in 4START will affect all copies of 4DOS, including those used for pipes and transient sessions. You can work around these potential problems with the 633IF or 634IFF command and the internal variable 220_TRANSIENT. For example, to skip all 4START processing when running in a transient session, you could use a command like this at the beginning of 4START: if %_transient != 0 quit ;--------------------------------------------------------------------------- !TOPIC 110 Detecting 4DOS !NOINDEX A batch file can test whether it is running in a JP Software shell by attempting a numeric comparison: if 01 == 1.0 echo Running in 4DOS, 4NT or Take Command! This syntax is legal in COMMAND.COM and all compatible shells, including 4DOS, 0204NT, Take Command, and CMD.EXE. In JP Software shells, this is a numeric comparison and true; in COMMAND.COM and CMD.EXE, it is a string comparison and false. ;--------------------------------------------------------------------------- !TOPIC 111 Using Aliases in Batch Files !NOINDEX One way to simplify batch file programming is to use 101aliases to hide unnecessary detail inside a batch file (see the 595ALIAS command for more details on how to define aliases). For example, suppose you want a batch file to check for certain errors, and display a message and exit if one is encountered. This example shows one way to do so: setlocal unalias * alias error `echo. ^ echo ERROR: %& ^ goto dispmenu` alias fatalerror `echo. ^ echo FATAL ERROR: %& ^ quit` alias in `pushd %1 ^ %2& ^ popd` if not exist setup.btm fatalerror Missing setup file! call setup.btm cls :dispmenu text 1. Word Processing 2. Spreadsheet 3. Communications 4. Exit endtext echo. inkey Enter your choice: %%userchoice switch %userchoice case 1 input Enter the file name: %%fname if not exist fname error File does not exist in d:\letters c:\wp60\wp.exe case 2 in d:\finance c:\quattro\q.exe case 3 in d:\comm c:\comsw\pcplus.exe case 4 goto done default error Invalid choice, try again endswitch goto dispmenu :done endlocal The first alias, ERROR, simply displays an error message and jumps to the label DISPMENU to redisplay the menu. The "%&" in the second 619ECHO command displays all the text passed to ERROR as the content of the message. The similar FATALERROR alias displays the message, then exits the batch file. The last alias, IN, expects 2 or more command-line arguments. It uses the first as a new working directory and changes to that directory with a 653PUSHD command. The rest of the command line is interpreted as another command plus possible command line parameters, which the alias executes. This alias is used here to switch to a directory, run an application, and switch back. It could also be used from the command line. The following lines print a menu on the screen and then get a keystroke from the user and store the keystroke in an environment variable called 'userchoice'. Then the 669SWITCH command is used to test the user's keystroke and decide what action to take. There's another side to aliases in batch files. If you're going to distribute your batch files to others, you need to remember that they may have aliases defined for the commands you're going to use. For example if the user has aliased 601CD to 602CDD and you aren't expecting this, your file may not work as you intended. There are two ways to address this problem. First, you can use 665SETLOCAL, 621ENDLOCAL, and 678UNALIAS to clear out aliases before your batch file starts and restore them at the end, as we did in the previous example. Remember that SETLOCAL and ENDLOCAL will save and restore not only the aliases but also the environment, the current drive and directory, and various special characters. If this method isn't appropriate or necessary for the batch file you're working on, you can also use an asterisk [*] before the name of any command. The asterisk means the command that follows it should not be interpreted as an alias. For example the following command redirects a list of file names to the file FILELIST: dir /b > filelist However, if the user has redefined 612DIR with an alias this command may not do what you want. To get around this just use: *dir /b > filelist The same can be done for any command in your batch file. If you use the asterisk, it will disable alias processing, and the rest of the command will be processed normally as an internal command, external command, or batch file. Using an asterisk before a command will work whether or not there is actually an alias defined with the same name as the command. If there is no alias with that name, the asterisk will be ignored and the command will be processed as if the asterisk wasn't there. ;--------------------------------------------------------------------------- !TOPIC 112 Debugging Batch Files !NOINDEX 4DOS includes a built-in batch file debugger, invoked with the 664SETDOS /Y1 command. The debugger allows you to "single-step" through a batch file line by line, with the file displayed in a popup window as it executes. You can execute or skip the current line, continue execution with the debugger turned off, view the fully-expanded version of the command line, or exit the batch file. The batch debugger can also pop up a separate window to view current environment variables or aliases so you can check their values during execution, and can pop up the 640LIST command to display the contents of any file. To start the debugger, insert a 664SETDOS /Y1 command at the beginning of the portion of the batch file you want to debug, and a SETDOS /Y0 command at the end. You can also invoke SETDOS /Y1 from the prompt, but because the debugger is automatically turned off whenever 4DOS returns to the prompt, you must enter the SETDOS command and the batch file name on the same line, for example: c:\> setdos /y1 ^ mybatch.btm If you use the debugger regularly you may want to define a simple alias to invoke it, for example: c:\> alias trace `setdos /y1 ^ %&` This alias simply enables the debugger, then runs whatever command is passed to it. You can use the alias to debug a batch file with a command like this: c:\> trace mybatch.btm You can also start or stop the debugger by pressing Ctrl-F5 while a batch file is waiting for input, such as in an 636INPUT or 635INKEY statement. You must complete the input (press Enter during INPUT, or any other key during INKEY) before the keystroke will be recognized and the debugger will start. When the debugger is running you can control its behavior with keystrokes. Debugging continues after each keystroke unless otherwise noted: !INDENT 30 5 5 5 T(race), Enter, or F8 Execute the current command. If it calls a subroutine with 629GOSUB, or another batch file with 599CALL, single-step into the called subroutine or batch file. S(tep) or F10 Execute the current command, but execute any subroutine or 599CALLed batch file without single-stepping. J(ump) Skip the current command and proceed to the next command. X (Expand) Display the next command to be executed, after expansion of aliases and environment variables. L(ist) Prompt for a file name and then view the file with the 640LIST command. V(ariables) Open a popup window to display the current environment, in alphabetical order. A(liases) Open a popup window to display the current aliases, in alphabetical order. O(ff) or Esc Turn off the debugger and continue with the remainder of the batch file. Q(uit) Quit the debugger and the current batch file, without executing the remainder of the file. !INDENT 0 The debugger highlights each line of the batch file as it is executed. It executes the commands on the line one at a time, so when a line contains more than one command, the highlight will not move as each command is executed. To see the individual commands, use the X key to expand each command before it is executed. If you use a "prefix" command like 623EXCEPT, 626FOR, 628GLOBAL, or 662SELECT, the prefix command is considered one command, and each command it invokes is another. For example, this command line executes four commands -- the 626FOR and three 619ECHO commands: for %x in (a b c) do echo %x You cannot use the batch debugger with 116REXX files; it can only be used with normal 4DOS batch files. The debugger gives you a detailed, step-by-step view of batch file execution, and will help solve particularly difficult batch file problems. However, in some cases you will find it easier to diagnose these problems with techniques that allow you to review what is happening at specific points in the batch file without stepping through each line individually. There are several tricks you can use for this purpose. Probably the simplest is to turn 619ECHO on at the beginning of the file while you're testing it, or use 664SETDOS /V2 to force ECHO on even if an ECHO OFF command is used in the batch file. This will give you a picture of what is happening as the file is executed, without stopping at each line. It will make your output look messy of course, so just turn it off once things are working. You can also turn ECHO on at the beginning of a group of commands you want to "watch", and off at the end, just by adding ECHO commands at the appropriate spots in your file. If an error occurs in a batch file, the error message will display the name of the file, the number of the line that contained the error, and the error itself. For example: e:\test.bat [3] Invalid parameter "/d" tells you that the file E:\TEST.BAT contains an error on line 3. The first line of the batch file is numbered 1. Another trick, especially useful in a fast-moving batch file or one where the screen is cleared before you can read messages, is to insert 650PAUSE commands wherever you need them in order to be able to watch what's happening. You can also use an 647ON ERRORMSG command to pause if an error occurs, then continue with the rest of the file (the first command below), or to quit if an error occurs (the second command): on errormsg pause on errormsg quit If you can't figure out how your aliases and variables are expanded, try turning 643LOG on at the start of the batch file. LOG keeps track of all commands after alias and variable expansion are completed, and gives you a record in a file that you can examine after the batch file is done. You must use a standard LOG command; LOG /H (the history log) does not work in batch files. You may also want to consider using 050redirection to capture your batch file output. Simply type the batch file name followed by the redirection symbols, for example: c:\> mybatch >& testout This records all batch file output, including error messages, in the file TESTOUT, so you can go back and examine it. If you have 619ECHO ON in the batch file you'll get the batch commands intermingled with the output, which can provide a very useful trace of what's happening. Of course, output from full-screen commands and programs that don't write to the standard output devices can't be recorded, but you can still gain a lot of useful information if your batch file produces any output. If you're using 050redirection to see the output, remember that any prompts for input will probably go to the output file and not to the screen, so you need to know in advance the sequence of keystrokes required to get through the entire batch file, and enter them by hand or with 638KEYSTACK. ;--------------------------------------------------------------------------- !TOPIC 113 Batch File String Processing !NOINDEX As you gain experience with batch files, you're likely to find that you need to manipulate text strings. You may need to prompt a user for a name or password, process a list of files, or find a name in a phone list. All of these are examples of string processing -- the manipulation of lines of readable text. 4DOS includes several features that make string processing easier. For example, you can use the 635INKEY and 636INPUT commands for user input; the 619ECHO, 660SCREEN, 661SCRPUT, and 684VSCRPUT commands for output; and the 626FOR command or the 274@FILEREAD function to scan through the lines of a file. In addition, 241variable functions offer a wide range of string handling capabilities. For example, suppose you need a batch file that will prompt a user for a name, break the name into a first name and a last name, and then run a hypothetical LOGIN program. LOGIN expects the syntax /F:first /L:last with both the first and last names in upper case and neither name longer than 8 characters. Here is one way to write such a program: @echo off setlocal unalias * input Enter your name (no initials): %%name set first=%@word[0,%name] set flen=%@len[%first] set last=%@word[1,%name] set llen=%@len[%last] iff %flen gt 8 .or. %llen gt 8 then echo First or last name too long quit endiff login /F:%@upper[%first] /L:%@upper[%last] endlocal The 665SETLOCAL command at the beginning of this batch file saves the environment and aliases. Then the 678UNALIAS * command removes any existing aliases so they won't interfere with the behavior of the commands in the remainder of the batch file. The first block of lines ends with an 636INPUT command which asks the user to enter a name. The user's input is stored in the environment variable NAME. The second block of lines extracts the user's first and last names from the NAME variable and calculates the length of each. It stores the first and last name, along with the length of each, in additional environment variables. Note that the 329@WORD function numbers the first word as 0, not as 1. The 634IFF command in the third block of lines tests the length of both the first and last names. If either is longer than 8 characters, the batch file displays an error message and ends. Finally, in the last block, the batch file executes the LOGIN program with the appropriate parameters, then uses the 621ENDLOCAL command to restore the original environment and alias list. At the same time, ENDLOCAL discards the temporary variables that the batch file used (NAME, FIRST, FLEN, etc.). When you're processing strings, you also need to avoid some common traps. The biggest one is handling special characters. Suppose you have a batch file with these two commands, which simply accept a string and display it: input Enter a string: %%str echo %str Those lines look safe, but what happens if the user enters the string "some > none" (without the quotes). After the string is placed in the variable STR, the second line becomes: echo some > none The ">" is a 050redirection symbol, so the line echoes the string "some" and redirects it to a file called NONE - probably not what you expected. You could try using quotation marks to avoid this kind of problem (see 118Argument Quoting), but that won't quite work. If you use back-quotes (ECHO `%STR`), the command will echo the four-character string %STR. Environment variable names are not expanded (replaced by their contents) when they are inside back-quotes. If you use double quotes (ECHO "%STR"), the string entered by the user will be displayed properly, and so will the quotation marks. With double quotes, the output would look like this: "some > none" As you can imagine, this kind of problem becomes much more difficult if you try to process text from a file. Special characters in the text can cause all kinds of confusion in your batch files. Text containing back-quotes, double quotes, or 050redirection symbols can be virtually impossible to handle correctly. One way to overcome these potential problems is to use the 664SETDOS /X command to temporarily disable redirection symbols and other special characters. The two-line batch file above would be a lot more likely to produce the expected results if it were rewritten this way: setdos /x-15678 input Enter a string: %%str echo %str setdos /x0 The first line turns off 101alias processing and disables several special symbols, including the command separator (see 041Multiple Commands) and all 050redirection symbols. Once the string has been processed, the last line re-enables the features that were turned off in the first line. If you need advanced string processing capabilities beyond those provided by 4DOS, you may want to consider using the 116REXX language. Our products support external REXX programs for this purpose. ;--------------------------------------------------------------------------- !TOPIC 114 Batch File Line Continuation !NOINDEX 4DOS will combine multiple lines in the batch file into a single line for processing when you include the 086escape character as the very last character of each line to be combined (except the last). The default escape character is Ctrl-X (ASCII 24, which appears on screen as an up-arrow [].) For example: echo The quick brown fox jumped over the lazy sleeping dog. > alphabet You cannot use this technique to extend a batch file line beyond the normal line length limit of 511 characters. ;--------------------------------------------------------------------------- !TOPIC 115 Batch File Compression !NOINDEX You can compress your batch files with a program called BATCOMP.EXE, which is distributed with 4DOS. This program condenses batch files by about a third and makes them unreadable with the 640LIST command and similar utilities. Compressed batch files run at approximately the same speed as regular .BTM files. You may want to consider compressing batch files if you need to distribute them to others and keep your original code secret or prevent your users from altering them. The syntax for the batch compression program is BATCOMP [/Ekkkk /K /O /Q] InputFile [OutputFile] For example, to compress MYBATCH.BAT and save the result as MYBATCH.BTM: c:\> batcomp mybatch.bat mybatch.btm You must specify the full name of the input file, including its extension, on the BATCOMP command line. If you do not specify the output file, BATCOMP will use the same base name as the input file and add a .BTM extension. If you do specify a output file name, you must give an extension or the output file will not have one. See 704BATCOMP for more information on options and usage. Under 4DOS, compressed .BTMs must be less than 64K bytes long. You can usually work around this limitation by breaking a very long batch file into two or more smaller files that CALL or chain to each other, and then compiling the shorter files separately. JP Software does not provide a decompression utility to decompress batch files. If you use BATCOMP.EXE, make sure that you also keep a copy of the original batch file for future inspection or modification. You can adopt one of two strategies for keeping track of your original source files and compressed batch files. First, you may want to create the source files with a traditional .BAT extension and reserve the .BTM extension for compressed batch files. The advantage of this approach is that you can modify and test the uncompressed versions at any time, although they will run in the slower, traditional mode unless they begin with a 641LOADBTM command. If you prefer, you can use a .BTM extension for both the source and compressed files. In this case you will have to use a different directory or a different base name for each file. For example, you might use SOURCE\MYBATCH.BTM for the source file and COMP\MYBATCH.BTM for the compressed version, or use MYBATCHS.BTM for the source file and MYBATCH.BTM for the compressed file (however, the latter approach may make it more difficult to keep track of the correspondence between the source file and the compressed file). ;--------------------------------------------------------------------------- !TOPIC 116 REXX Support !NOINDEX REXX is a file and text processing language developed by IBM, and available on many PC and other platforms. You can invoke REXX programs from 4DOS using executable extensions. REXX is an ideal extension to the 4DOS batch language, especially if you need advanced string processing capabilities. The REXX language is not built into 4DOS, and requires a separate REXX processor. REXX programs are stored in either .BAT or .REX files. .REX files are used for Quercus's Personal REXX; .BAT files are used for REXX programs under IBM PC DOS 7.0 and above, and can also be used with Personal REXX as described below. To enable support for .REX files, you must define an 082executable extension that tells 4DOS to load Personal REXX when you invoke a .REX file. For example: set .rex=c:\prexx\rexx.exe INDENT 0 Once you have enabled REXX execution of .BAT files by setting REXXPath or using PC DOS 7.0 or later, 4DOS checks the first 2 characters of the first line of each .BAT file. If the first 2 characters are [/*], the beginning of a REXX comment, 4DOS calls your REXX interpreter to execute the .BAT file. All of the REXX processors described above (Enterprise REXX, Personal REXX and PC DOS's built in REXX) extend the interface between REXX and 4DOS by allowing you to invoke 4DOS commands from within a REXX program. For details on communication between REXX and 4DOS, or for more information on any aspect of REXX, see your REXX documentation. ;--------------------------------------------------------------------------- !TOPIC 117 Command Parsing !NOINDEX !TTY Whenever you type something at the command line and press the Enter key, or include a command in a batch file, you have given a command to 4DOS, which must figure out how to execute your command. If you understand the general process that is used, you will be able to make the best use of the commands. Understanding these steps can be especially helpful when working with complex aliases or batch file commands. To decide what activity to perform, 4DOS goes through several steps. Before it starts, it writes the entire command line (which may contain multiple commands) to the history log file if history logging has been enabled with the LOG /H command (see 643LOG), and the command did not come from a batch file. Then, if the line contains multiple commands, the first command is isolated for processing. 4DOS begins by dividing the command into a command name and a command tail. The command name is the first word in the command; the tail is everything that follows the command name. For example, in the command line dir *.txt /2/p/v the command name is "dir", and the command tail is " *.txt /2/p/v". Next 4DOS tries to match the command name against its list of aliases. If it finds a match between the command name and one of the aliases you've defined, it replaces the command name with the contents of the alias. This substitution is done internally and is not normally visible to you; however, you can view a command line with aliases expanded by pressing Ctrl-F after entering the command at the prompt. If the alias included parameters (%1, %2, etc.), the parameter values are filled in from the text on the command line, and any parameters used in this process are removed from the command line. The process of replacing a command name that refers to an alias with the contents of the alias, and filling in the alias parameters, is called alias expansion. This expansion of an alias creates a new command name: the first word of the alias. This new command name is again tested against the list of aliases, and if a match is found the contents of the new alias is expanded just like the first alias. This process, called nested alias expansion, continues until the command name no longer refers to an alias. Once it has finished with the aliases, 4DOS next tries to match the command name with its list of internal commands. If it is unsuccessful, 4DOS knows that it will have to search for a batch file or external program to execute your command. The next step is to locate any batch file or alias parameters, environment variables, internal variables, or variable functions in the command, and replace each one with its value. This process is called variable expansion. The variable expansion process is modified for certain internal commands, like EXCEPT, IF, and GLOBAL. These commands are always followed by another command, so variable expansion takes place separately for the original command and the command that follows it. Once all of the aliases and environment variables have been expanded, 4DOS will echo the complete command to the screen (if command-line echo has been enabled) and write it to the log file (if command logging has been turned on). Before it can actually execute your command, 4DOS must scan the command tail to see if it includes 051redirection or 052piping. If so, the proper internal switches are set to send output to an alternate device or to a file, instead of to the screen. Finally, it is time to execute the command. If the command name matches an internal command, 4DOS will perform the activities you have requested. Otherwise, 4DOS searches for an executable (.COM or .EXE) file, a batch file, or a file with an executable extension that matches the command name (see the detailed description of this search on page 895Executable Files and File Searches). Once the internal command or external program has terminated, 4DOS saves the result or exit code that the command generated, cleans up any redirection that you specified, and then returns to the original command line to retrieve the next command. When all of the commands in a command line are finished, the next line is read from the current batch file, or if no batch file is active, the prompt is displayed. You can disable and re-enable several parts of command parsing (for example alias expansion, variable expansion, and redirection) with the SETDOS /X command (see 664SETDOS). ;--------------------------------------------------------------------------- !TOPIC 118 Argument Quoting !NOINDEX As it parses the command line, 4DOS looks for command separators [^], conditional commands (|| or &&), white space (spaces, tabs, and commas), percent signs [%] which indicate variables to be expanded, and redirection and piping characters (>, <, or |). Normally, these special characters cannot be passed to a command as part of an argument. However, you can include any of the special characters in an argument by enclosing the entire argument in back-quotes [`] or double quotes ["]. Although both back-quotes and double quotes will let you build arguments that include special characters, they do not work the same way. No alias or variable expansion is performed on an argument enclosed in back-quotes. Redirection symbols inside the back-quotes are ignored. The back-quotes are removed from the command line before the command is executed. No alias expansion is performed on expressions enclosed in double quotes. Redirection symbols inside double quotes are ignored. However, variable expansion is performed on expressions inside double quotes. The double quotes themselves will be passed to the command as part of the argument. For example, suppose you have a batch file CHKNAME.BTM which expects a name as its first parameter (%1). Normally the name is a single word. If you need to pass a two-word name with a space in it to this batch file you could use the command: c:\> chkname `MY NAME` Inside the batch file, %1 will have the value MY NAME, including the space. The back-quotes caused 4DOS to pass the string to the batch file as a single argument, rather than as the two separate parameters MY and NAME. The quotes keep characters together and reduce the number of arguments in the line. When an alias is defined in a batch file or from the command line, its argument can be enclosed in back-quotes to prevent the expansion of replaceable parameters, variables, and multiple commands until the alias is invoked. See 595ALIAS for details. You can disable and re-enable back-quotes and double quotes with the 664SETDOS /X command. ;--------------------------------------------------------------------------- !TOPIC 131 Using the Environment !NOINDEX The environment is a collection of information about your computer that every program receives. Each entry in the environment consists of a variable name, followed by an equal sign and a string of text. You can automatically substitute the text for the variable name in any command. To create the substitution, include a percent sign [%] and a variable name on the command line or in an alias or batch file. The following standard environment variables have special meanings in 4DOS: 049CDPATH / _CDPATH Directory change path 132CMDLINE Current command line 133COLORDIR Directory colors 134COMSPEC Name of the command processor 135COPYCMD Default COPY/MOVE options (Compatibility only) 136DIRCMD Default DIR options (Compatibility only) 145DOSHELP Path to external DOS help system 137FILECOMPLETION Filename completion customization 147LOGINNAME User login name 823NO_SEP Removes the thousands separators from numbers 138PATH Executable file search path 143PATHEXT Extensions to search for in the PATH 139PROMPT Command prompt 140TEMP Directory for temporary files 141TEMP4DOS Directory for temporary files 142TMP Directory for temporary files ; TMPDIR ; TEMPDIR ; OPTKEYS ; OPTHELP 4DOS also supports two special types of variables, which are documented separately: !INDENT 5 5 5 5 161Internal Variables are similar to environment variables, but are stored internally within 4DOS, and are not visible in the environment. They provide information about your system for use in batch files and aliases. 241Variable Functions are referenced like environment variables, but perform additional functions like file handling, string manipulation and arithmetic calculations. !INDENT 0 The 663SET command is used to create environment variables. For example, you can create a variable named BACKUP like this: c:\> set BACKUP=*.bak;*.bk!;*.bk If you then type c:\> del %BACKUP it is equivalent to the command DEL *.bak;*.bk!;*.bk The size of the environment can be specified on the Startup page of the 648OPTION dialogs, with the 377Environment and 378EnvFree directives in 4DOS.INI, or by the /E: 352startup switch. Environment variable names may contain any alphabetic or numeric characters, the underscore character [_], and the dollar sign [$]. You can force acceptance of other characters by including the full variable name in square brackets, like this: %[AB##2]. You can also "nest" environment variables using square brackets. For example %[%var1] means "the contents of the variable whose name is stored in VAR1." A variable referenced with this technique cannot contain more than 511 characters of information. Nested variable expansion can be disabled with the 664SETDOS /X command. Environment variables may contain alias names. 4DOS will substitute the variable value for the name, then check for any alias name which may have been included within the variable's value. For example, the following commands would generate a 2-column directory of the .TXT files: c:\> alias d2 dir /2 c:\> set cmd=d2 c:\> %cmd *.txt The trailing percent sign that was traditionally required for environment variable names is not usually required in 4DOS, which accept any character that cannot be part of a variable name (including a space) as the terminator. However, the trailing percent can be used to maintain compatibility. The trailing percent sign is needed if you want to join two variable values. The following examples show the possible interactions between variables and literal strings. First, create two environment variables called ONE and TWO this way: c:\> set ONE=abcd c:\> set TWO=efgh Now the following combinations produce the output text shown: %ONE%TWO abcdTWO ("%ONE%" + "TWO") %ONE%TWO% abcdTWO ("%ONE%" + "TWO%") %ONE%%TWO abcdefgh ("%ONE%" + "%TWO") %ONE%%TWO% abcdefgh ("%ONE%" + "%TWO%") %ONE%[TWO] abcd[TWO] ("%ONE%" + "[TWO]") %ONE%[TWO]% abcd[TWO] ("%ONE%" + "[TWO]%") %[ONE]%TWO abcdefgh ("%[ONE]" + "%TWO") %[ONE]%TWO% abcdefgh ("%[ONE]" + "%TWO%") If you want to pass a percent sign to a command, or a string which includes a percent sign, you must use two percent signs in a row. Otherwise, the single percent sign will be seen as the beginning of a variable name and will not be passed on to the command. For example, to display the string "We're with you 100%" you would use the command: echo We're with you 100%% You can also use back-quotes around the text, rather than a double percent sign. See 118Argument Quoting for details. Each copy of 4DOS maintains its own copy of the environment. The copy of the environment maintained by the primary shell is called the master environment. When using a secondary shell, 4DOS will allow you to access the master environment in the primary shell with the commands 663SET /M, 680UNSET /M, and 622ESET /M, and with the 304%@MASTER variable function. ;--------------------------------------------------------------------------- !TOPIC 132 CMDLINE !NOINDEX !TTY CMDLINE is the fully expanded text of the currently executing command line. CMDLINE is set just before invoking any .COM, .EXE, .BTM or .BAT file. If a command line is prefaced with an "@" to prevent echoing, it will not be put in CMDLINE, and any previous CMDLINE variable will be removed from the environment. This allows you to squeeze out the last few bytes of environment space before loading TSRs by prefacing each TSR command with an "@". ;--------------------------------------------------------------------------- !TOPIC 133 COLORDIR !NOINDEX COLORDIR controls directory display colors used by 612DIR and 662SELECT. See the discussion of color-coded directories under DIR for a complete description. ;--------------------------------------------------------------------------- !TOPIC 134 COMSPEC !NOINDEX !TTY COMSPEC contains the full path to the command processor. Normally it's c:\command.com, vDosPlus takes care that 4DOS is executed instead. !TTY You can set the COMSPEC variable with a 663SET command in the vDosPlus AUTOEXEC.TXT. This method is not recommended, because it allows applications to shell to DOS, but does not provide information that the primary 4DOS shell needs to find its files during the startup process. ;--------------------------------------------------------------------------- !TOPIC 135 COPYCMD !NOINDEX !TTY COPYCMD is used by MS-DOS 6.20 and PC DOS 6.3 COMMAND.COM and above to hold default options for the 606COPY, 646MOVE, and XCOPY commands. 4DOS does not support this variable, but you can achieve the same effect with an 101alias. For example, if you want the COPY and MOVE commands to default to prompting you before overwriting an existing file (see also the 4DOS.INI 450CopyPrompt directive), you could use these aliases: c:\> alias copy = `*copy /r` c:\> alias move = `*move /r` If you wish to use COPYCMD for compatibility with systems that do not use 4DOS, you can define the aliases this way: c:\> alias copy = `*copy %copycmd` c:\> alias move = `*move %copycmd` However, please note that there are a number of subtle differences in regard to the available options and their usage between the DOS COPY and MOVE commands and 4DOS' own implementation thereof, so that the above recommendation may not always be applicable. ;--------------------------------------------------------------------------- !TOPIC 136 DIRCMD !NOINDEX !TTY DIRCMD is used by MS-DOS / PC DOS 5.0 COMMAND.COM and above, and some versions of CMD.EXE to hold default options for the 612DIR command. 4DOS does not support this variable, but you can achieve the same effect with an 101alias. For example, if you want the DIR command to default to wide column display with a vertical sort and a pause at the end of each page, you could use this alias: c:\> alias dir = `*dir /w/p/v` If you wish to continue to use DIRCMD for compatibility with systems that do not use 4DOS, you can define the alias this way: c:\> alias dir = `*dir %dircmd` ;--------------------------------------------------------------------------- !TOPIC 137 FILECOMPLETION !NOINDEX !TTY FILECOMPLETION sets the files made available during filename completion for selected commands. See 037Customizing Filename Completion for a complete description of the format of this variable. ;--------------------------------------------------------------------------- !TOPIC 823 NO_SEP !NOINDEX !TTY NO_SEP removes the thousands separators from numbers shown or returned by the 4DOS commands and functions. The exact value to which NO_SEP is set does not matter (e.g. "SET NO_SEP=1"). Type "SET NO_SEP=" or "UNSET NO_SEP" to turn thousands separators back on. ;--------------------------------------------------------------------------- !TOPIC 138 PATH !NOINDEX PATH is a list of directories that 4DOS will search for executable files that aren't in the current directory. PATH may also be used by some application programs to find their own files. See the 649PATH command for a full description of this variable. ;--------------------------------------------------------------------------- !TOPIC 143 PATHEXT !NOINDEX PATHEXT can be used to select the extensions to look for when searching the 138PATH for an executable file. It consists of a list of extensions, separated by semicolons. For example, to replicate the default extension list used by 4DOS: set pathext=.com;.exe;.btm;.bat PATHEXT is ignored unless the 477PathExt setting is set to Yes in 4DOS.INI. Once PATHEXT is enabled the standard path search for .COM, .EXE, .BTM, and .BAT, files is replaced by a search for files with the extensions listed in PATHEXT, in the order listed there. Enabling PATHEXT affects only the standard path search, it does not affect the subsequent searches for files with 082executable extensions. PATHEXT is supported for compatibility reasons but should not generally be used as a substitute for executable extensions, which are much more flexible. For more details on path searches, see the 649PATH command. CAUTION: If you set PathExt = Yes in 4DOS.INI and then fail to set the PATHEXT variable, path searches will fail as there will be no extensions for which to search! ;--------------------------------------------------------------------------- !TOPIC 139 PROMPT !NOINDEX PROMPT defines the command-line prompt. It can be set or changed with the 652PROMPT command. ;--------------------------------------------------------------------------- !TOPIC 140 TEMP !NOINDEX !TTY TEMP specifies the directory where 4DOS should store temporary 050pipe and clipboard files if the 141TEMP4DOS variable doesn't exist. Some other programs also use TEMP to define where they should place their temporary files. See also 141TEMP4DOS and 142TMP. ;--------------------------------------------------------------------------- !TOPIC 141 TEMP4DOS !NOINDEX !TTY TEMP4DOS specifies where 4DOS should store temporary 050pipe and clipboard files. Also see 140TEMP and 142TMP. ;--------------------------------------------------------------------------- !TOPIC 142 TMP !NOINDEX !TTY TMP specifies the directory where 4DOS should store temporary 050pipe and clipboard files if the 140TEMP and 141TEMP4DOS variables don't exist. ;--------------------------------------------------------------------------- !TOPIC 145 DOSHELP !NOINDEX !TTY DOSHELP specifies the full path to an external DOS help system, if the executable file is not called HELP.COM or is not accessible via the 138PATH on your system. See 16External Help for more details. ;--------------------------------------------------------------------------- !TOPIC 147 LOGINNAME !NOINDEX !TTY LOGINNAME specifies the name, the 4DOS 652PROMPT $U will display as the current user. ;--------------------------------------------------------------------------- !TOPIC 161 Internal Variables !NOINDEX Internal Variables are special environment variables built into 4DOS to provide information about your system. They are not actually stored in the environment and therefore are invisible to applications scanning the environment, but they can be used in internal commands, aliases, and batch files just like any other environment variable. The values of these variables are stored internally in 4DOS, and cannot be changed with the 663SET, 680UNSET, or 622ESET command. However, you can override any of the internal variables by defining a new variable with the same name. The list below gives a one-line description of each variable, and a cross-reference which selects a full screen help topic on that variable. Most of the variables are simple enough that the one-line description is sufficient. However, for those variables marked with an asterisk [*], the cross-reference topic contains some additional information you may wish to review. You can also obtain help on any variable with a HELP _variablename command at the prompt. See the discussion after the variable list for some additional information, and examples of how these variables can be used. For a more comprehensive set of examples see the EXAMPLES.BTM file which came with 4DOS. Note: The variables marked with an exclamation mark [!] are 4DOS-specific; they are either not present in 0204NT, or their equivalents there have different names. Take this into account when writing portable batch files. The variables are grouped by category: Hardware status _ALT Alt key depressed (0 or 1) _CAPSLOCK CapsLock on (0 or 1) _CPU "NexGen Nx586" in vDosPlus _CPUSPEED Will stall vDosPlus!!! _CTRL Ctrl key depressed (0 or 1) _KBHIT Keystroke waiting in buffer (0 or 1) _LALT Left Alt key depressed (0 or 1) _LCTRL Left Ctrl key depressed (0 or 1) _LSHIFT Left Shift key depressed (0 or 1) _MONITOR "color" in vDosPlus _NDP "None" in vDosPlus _NUMLOCK NumLock on (0 or 1) _RALT Right Alt key depressed (0 or 1) _RCTRL Right Ctrl key depressed (0 or 1) _RSHIFT Right Shift key depressed (0 or 1) _SBDSP "0" in vDosPlus _SCROLLLOCK ScrollLock on (0 or 1) _SHIFT Shift key depressed (0 or 1) _SYSREQ SysReq key depressed (0 or 1) _TSC "?" in vDosPlus _V86 "0" in vDosPlus _VIDEO "vga" in vDosPlus Operating system and software status _ANSI "1" in vDosPlus _APPEND "0" in vDosPlus _ASSIGN "0" in vDosPlus _BOOT "C" in vDosPlus _CODEPAGE Current code page number _COUNTRY Current country code _DISPLAY "0" in vDosPlus _DOS "MS-DOS" in vDosPlus _DOSVER Reported DOS version, default "7.10" in vDosPlus _DPMI DPMI version, usually "0" in vDosPlus _DRIVER "0" in vDosPlus _DV DESQview loaded (0 or 1) _EGA "0" in vDosPlus _FONTPAGE "0" in vDosPlus _GRAFTABL "0" in vDosPlus _GRAPHICS "0" in vDosPlus _MACHINE Machine name _MOUSE Mouse enabled (0 or 1) _MSCDEX "0" in vDosPlus _NETWORK "8" in vDosPlus _NLSFUNC "0" in vDosPlus _POWER "0" in vDosPlus _PRINT "0" in vDosPlus _SHARE "1" in vDosPlus _SMARTDRV "0" in vDosPlus _TASKMAX "0" in vDosPlus _TASKSWITCHER "0" in vDosPlus _VCPI "0" in vDosPlus _VDS "0" in vDosPlus _WIN "0" in vDosPlus 4DOS status _4VER "8.00" in vDosPlus 168_ALIAS ! Free alias space in bytes 173_BATCH Batch nesting level 174_BATCHLINE Current line number in current batch file 175_BATCHNAME Name of current batch file 500_BATCHTYPE Type of current batch file 501_BDEBUGGER Batch debugger active (0 or 1) _BUILD "200" in vDosPlus 228_CMDLINE Contents of the command line _CMDPROC "4DOS" in vDosPlus 502_CMDSPEC Full pathname of command processor 192_DNAME Name of file used to store file descriptions 229_ECHO Echo state (0 or 1) 404_EDITMODE Current line editing mode (0 or 1) 200_ENV ! Free environment space in bytes 405_EXPANSION Current expansion mode (SETDOS /X) 202_HLOGFILE Current history log file name 506_ININAME Full pathname of the current INI file 779_KEYSTACKED ! Number of keystrokes in the KSTACK.COM buffer 205_KSTACK ! KSTACK.COM load status (0 or 1) 207_LOGFILE Current log file name 216_SHELL Shell level (0, 1, 2, ...) 737_STARTPATH Startup directory of current shell 366_STDERR Standard error not redirected flag (0 or 1) 367_STDIN Standard input not redirected flag (0 or 1) 368_STDOUT Standard output not redirected flag (0 or 1) 217_SWAPPING !* Swapping state (XMS, EMS, Disk, None, or off) 220_TRANSIENT * Transient shell flag (0 or 1) _VERMAJOR "8" in vDosPlus _VERMINOR "0" in vDosPlus _VERSION "8.00" in vDosPlus Screen, color, and cursor 176_BG Background color at cursor position 178_CI Current cursor shape in insert mode 179_CO Current cursor shape in overstrike mode 181_COLUMN Current cursor column 182_COLUMNS Screen width 201_FG Foreground color at cursor position 213_ROW Current cursor row 214_ROWS Screen height Drives and directories 185_CWD Current drive and directory (d:\path) 186_CWDS Current drive and directory with \ (d:\path\) 187_CWP Current directory (\path) 188_CWPS Current directory with \ (\path\) 191_DISK Current drive (C, D, etc.) 590_DRIVES List of all available drives 830_LASTDIR Previous directory (from directory history) 206_LASTDISK Last possible drive (E, F, etc.) 716_READY List of ready (accessible) drives Dates and times 189_DATE * Current date (mm-dd-yy) 370_DATETIME * Current date and time (yyyyMMddhhmmss) 190_DAY Day of the month (1 - 31) 195_DOW Day of the week (Mon, Tue, Wed, etc.) 226_DOWF Day of the week (Monday, Tuesday, etc.) 196_DOWI Numeric day of the week (Sun = 1, etc.) 197_DOY Day of the year (1 - 366) 738_DST Daylight saving time (0 or 1) 203_HOUR Hour (0 - 23) 230_ISODATE Current date (yyyy-mm-dd) 454_ISODOWI ! Numeric day of the week (Mon = 1, etc.) 736_ISORDATE ! Current ISO 8601 ordinal date (yyyy-ddd) 460_ISOWDATE ! Current ISO 8601 week date (yyyy-Www-d) 455_ISOWEEK ! Week of the year pursuant to ISO 8601 591_ISOWYEAR ! Current ISO 8601 week date year 208_MINUTE Minute (0 - 59) 739_MJD ! Modified Julian Day 210_MONTH Month of the year (1 - 12) 240_MONTHF Month of the year (January, February, etc.) 215_SECOND Second (0 - 59) 740_STZN Name of time zone for standard time 741_STZO Offset in minutes from UTC for standard time 588_TICK ! BIOS clock tick since midnight 219_TIME * Current time (hh:mm:ss) 742_TZN Name of current time zone 743_TZO Offset in minutes from UTC for current time zone 744_UNIXTIME ! Current Unix time 745_UTCDATE Current UTC date 746_UTCDATETIME Current UTC date and time 747_UTCHOUR Current UTC hour 748_UTCISODATE Current UTC date in ISO format 749_UTCMINUTE Current UTC minute 750_UTCSECOND Current UTC second 760_UTCTIME Current UTC time _WINTICKS Milliseconds since midnight _YEAR Current system year (1980 to 2099). Error codes 162? * Exit code, last external program 163?? !* Reason for external program termination 164_? * Exit code, last internal command 365_EXECSTR * Last @EXECSTR return code 218_SYSERR * Last DOS error Compatibility 166+ * Substitutes command separator 165= * Substitutes escape character Additional Notes These internal variables are often used in batch files and aliases to examine system resources and adjust to the current computer settings. You can examine the contents of any internal variable (except %= and %+) from the command line with a command like this: c:\> echo %variablename Some variables return values based on information provided by your operating system. These variables will only return correct information if the operating system provides it. On disk volumes which do not support long filenames, variables which return a path or file name will return their result in upper or lower case depending on the value of the 664SETDOS /U switch or the 446UpperCase directive in the .INI file. On volumes which do support long filenames, these variables will return names as they are stored on the disk and no case shifting will be performed. Returned filename values which include long filenames are not quoted automatically; you must add quotes yourself if they are required for your use of the variable value (see 118Argument Quoting). Examples You can use these variables in a wide variety of ways depending on your needs. Here are just a few examples. For a more comprehensive set of examples see the EXAMPLES.BTM file which came with 4DOS. Some of these examples rely on the 633IF and 634IFF commands to test the value of a variable and perform different actions based on that value. In a batch file, set the color based on the video card type: iff "%_video"=="mono" then color bright white on black else color bright white on blue endiff Call another batch file if 4DOS is running under DESQview: if "%_dv" == "1" call dvstart Store the current date and time in a file, then save the output of a 612DIR command in the same file: echo Directory as of %_date %_time > dirsave dir >> dirsave Set up a prompt for the primary shell which displays the time and current directory, and a different one for secondary shells which includes the shell level rather than the time (see 652PROMPT for details about setting the prompt). Also set different background colors for the two shells, without changing the foreground color. You might use a sequence like this in your 4START file (see 109Automatic Batch Files): iff %_shell==0 then prompt $t $p$g color %_fg on blue else prompt [$z] $p$g color %_fg on cyan endiff ;--------------------------------------------------------------------------- !TOPIC 162 ? !NOINDEX !TTY ? contains the exit code of the last external command. Many programs return a "0" to indicate success and a non-zero value to signal an error. However, not all programs return an exit code. If no explicit exit code is returned, the value of %? is undefined. ;--------------------------------------------------------------------------- !TOPIC 163 ?? !NOINDEX !TTY ?? returns a code which explains how the last program terminated: 0 -- program terminated normally. 1 -- program terminated by Ctrl-C or Ctrl-Break. 2 -- program terminated due to a critical error. 3 -- program terminated and stayed resident in memory (TSR). ;--------------------------------------------------------------------------- !TOPIC 164 _? !NOINDEX !TTY _? contains the exit code of the last internal command. It is set to "0" if the command was successful, "1" if a usage error occurred, "2" if another command processor error or an operating system error occurred, or "3" if the command was interrupted by Ctrl-C or Ctrl-Break. You must use or save this value immediately, because it is set by every internal command. ;--------------------------------------------------------------------------- !TOPIC 165 = !NOINDEX !TTY = returns the current 086escape character. Use this variable, instead of the actual escape character, if you want your batch files and aliases to work regardless of how the escape character is defined. For example, if the escape character is a Ctrl-X [], both of the commands below will send a form feed to the printer. However, if the escape character has been changed, the first command will send the string "^f" to the printer, while the second command will continue to work as intended. echos f > prn echos %=f > prn See 054Special Character Compatibility for further information. ;--------------------------------------------------------------------------- !TOPIC 166 + !NOINDEX !TTY + returns the current 041command separator. Use this variable, instead of the actual command separator, if you want your batch files and aliases to work regardless of how the command separator is defined. For example, if the command separator is a caret [^], both of the commands below will display "Hello" on one line and "World" on the next. However, if the command separator has been changed the first command will display "Hello ^ echo World", while the second command will continue to work as intended. echo Hello ^ echo World echo Hello %+ echo World See 054Special Character Compatibility for further information. ;--------------------------------------------------------------------------- !TOPIC 168 _ALIAS !NOINDEX !TTY _ALIAS contains the free space in the alias list, in bytes. ;--------------------------------------------------------------------------- !TOPIC 173 _BATCH !NOINDEX !TTY _BATCH is the current batch nesting level. It is "0" if no batch file is currently being processed. ;--------------------------------------------------------------------------- !TOPIC 174 _BATCHLINE !NOINDEX !TTY _BATCHLINE is the current line number in the current batch file. It is "-1" if no batch file is currently being processed. ;--------------------------------------------------------------------------- !TOPIC 175 _BATCHNAME !NOINDEX !TTY _BATCHNAME is the full path and file name of the current batch file. It is an empty string if no batch file is currently being processed. ;--------------------------------------------------------------------------- !TOPIC 500 _BATCHTYPE !NOINDEX !TTY _BATCHTYPE is the file type of the current batch file, as follows: !NOWRAP Value Meaning -1 not in a batch file 0 normal 1 compressed 2 encrypted !WRAP ;--------------------------------------------------------------------------- !TOPIC 501 _BDEBUGGER !NOINDEX !TTY _BDEBUGGER is "1" if the batch debugger is actively debugging a file, or "0" if it is not. ;--------------------------------------------------------------------------- !TOPIC 176 _BG !NOINDEX !TTY _BG is a string containing the first three characters of the screen background color at the current cursor location (for example, "Bla"). ;--------------------------------------------------------------------------- !TOPIC 178 _CI !NOINDEX !TTY _CI returns the current shape of the cursor in insert mode, as a percentage (see 664SETDOS /S and the 419CursorIns directive). ;--------------------------------------------------------------------------- !TOPIC 228 _CMDLINE !NOINDEX !TTY _CMDLINE is the current command line. (This is most useful inside key aliases.) If specified on the command line, returns the contents of the command line with the %_CMDLINE name removed. ;--------------------------------------------------------------------------- !TOPIC 502 _CMDSPEC !NOINDEX !TTY _CMDSPEC is the full pathname of the command processor. ;--------------------------------------------------------------------------- !TOPIC 179 _CO !NOINDEX !TTY _CO returns the current shape of the cursor in overstrike mode, as a percentage (see 664SETDOS /S and the 420CursorOver directive). ;--------------------------------------------------------------------------- !TOPIC 181 _COLUMN !NOINDEX !TTY _COLUMN is the current cursor column (for example, "0" for the left side of the screen). ;--------------------------------------------------------------------------- !TOPIC 182 _COLUMNS !NOINDEX !TTY _COLUMNS is the current number of screen columns (for example, "80"). ;--------------------------------------------------------------------------- !TOPIC 185 _CWD !NOINDEX !TTY _CWD is the current working directory in the format d:\pathname. ;--------------------------------------------------------------------------- !TOPIC 186 _CWDS !NOINDEX !TTY _CWDS has the same value as CWD, except it ends the pathname with a backslash [\]. ;--------------------------------------------------------------------------- !TOPIC 187 _CWP !NOINDEX !TTY _CWP is the current working directory in the format \pathname. ;--------------------------------------------------------------------------- !TOPIC 188 _CWPS !NOINDEX !TTY _CWPS has the same value as CWP, except it ends the pathname with a backslash [\]. ;--------------------------------------------------------------------------- !TOPIC 189 _DATE !NOINDEX !TTY _DATE contains the current system date, in the format mm-dd-yy (U.S.), dd-mm-yy (Europe), or yy-mm-dd (Japan). The separator character may vary depending upon your country information. ;--------------------------------------------------------------------------- !TOPIC 370 _DATETIME !NOINDEX !TTY _DATETIME contains the current system date and time as 14-characters in the format yyyyMMddhhmmss. The date part is the same as 230_ISODATE without separators. ;--------------------------------------------------------------------------- !TOPIC 190 _DAY !NOINDEX !TTY _DAY is the current day of the month (1 to 31). ;--------------------------------------------------------------------------- !TOPIC 191 _DISK !NOINDEX !TTY _DISK is the current disk drive, without a colon (for example, "C"). ;--------------------------------------------------------------------------- !TOPIC 192 _DNAME !NOINDEX !TTY _DNAME returns the name of the file used to store file descriptions. It can be changed with the 423DescriptionName directive in 4DOS.INI or the 664SETDOS /D command. ;--------------------------------------------------------------------------- !TOPIC 195 _DOW !NOINDEX !TTY _DOW is the first three characters of the current day of the week ("Mon", "Tue", "Wed", etc.). ;--------------------------------------------------------------------------- !TOPIC 226 _DOWF !NOINDEX !TTY _DOWF is the full day of the week for the current date ("Monday", "Tuesday", etc.). ;--------------------------------------------------------------------------- !TOPIC 196 _DOWI !NOINDEX !TTY _DOWI is the current day of the week as an integer (1 = Sunday, 2 = Monday, etc.). ;--------------------------------------------------------------------------- !TOPIC 197 _DOY !NOINDEX !TTY _DOY is the day of the year (1 to 366). ;--------------------------------------------------------------------------- !TOPIC 590 _DRIVES !NOINDEX !TTY _DRIVES returns a space-delimited list of the existing drives on the system (for example, "A: C: D: E:"). ;--------------------------------------------------------------------------- !TOPIC 738 _DST !NOINDEX !TTY _DST is "1" if daylight saving time (a.k.a. "summer time") is in effect, or "0" otherwise. See 759TZ for more information. ;--------------------------------------------------------------------------- !TOPIC 229 _ECHO !NOINDEX !TTY _ECHO is the current echo state. There are two echo states, one for the command line and one for batch files. ;--------------------------------------------------------------------------- !TOPIC 404 _EDITMODE !NOINDEX !TTY _EDITMODE is "0" if the line editor is in overstrike mode, or "1" if it is in insert mode. ;--------------------------------------------------------------------------- !TOPIC 200 _ENV !NOINDEX !TTY _ENV is the free space in the environment, in bytes. ;--------------------------------------------------------------------------- !TOPIC 365 _EXECSTR !NOINDEX !TTY _EXECSTR is the integer return code of the last 265@EXECSTR function. ;--------------------------------------------------------------------------- !TOPIC 405 _EXPANSION !NOINDEX !TTY _EXPANSION is the current expansion mode (i.e. 664SETDOS /X). It is "0" if everything is enabled, or a string of up to 9 digits for the disabled modes, e.g. "46" if nested variable expansion and redirection are disabled. ;--------------------------------------------------------------------------- !TOPIC 201 _FG !NOINDEX !TTY _FG is a string containing the first three letters of the screen foreground color at the current cursor position (for example, "Whi"). ;--------------------------------------------------------------------------- !TOPIC 202 _HLOGFILE !NOINDEX !TTY _HLOGFILE returns the name of the current history log file (or an empty string if 643LOG /H is OFF). ;--------------------------------------------------------------------------- !TOPIC 203 _HOUR !NOINDEX !TTY _HOUR is the current hour (0 - 23). ;--------------------------------------------------------------------------- !TOPIC 506 _ININAME !NOINDEX !TTY _ININAME returns the full pathname of the INI file used by the current shell. ;--------------------------------------------------------------------------- !TOPIC 230 _ISODATE !NOINDEX !TTY _ISODATE returns the current date in ISO 8601 international format (yyyy-mm-dd). ;--------------------------------------------------------------------------- !TOPIC 454 _ISODOWI !NOINDEX !TTY _ISODOWI is the current day of the week as an integer (1 = Monday, 2 = Tuesday, ... , 6 = Saturday, 7 = Sunday), pursuant to ISO 8601. ;--------------------------------------------------------------------------- !TOPIC 736 _ISORDATE !NOINDEX !TTY _ISORDATE returns the current ordinal date in ISO 8601 international format (yyyy-ddd where ddd is the day of the year, 1 to 366). ;--------------------------------------------------------------------------- !TOPIC 460 _ISOWDATE !NOINDEX !TTY _ISOWDATE returns the current week date in ISO 8601 international format (yyyy-Www-d where ww is the week and d is the week day). It is possible that the year is one less or more than the current year because some partial weeks at the beginning or the end of the year may belong to the last or next year, according to ISO 8601. ;--------------------------------------------------------------------------- !TOPIC 455 _ISOWEEK !NOINDEX !TTY _ISOWEEK is the week of the year (1 to 53), pursuant to ISO 8601. Week 1 is the one that includes the first Thursday of the year, or equivalently, the week which includes 4th of January. It is possible that a January week is 52 or 53, or a December week is 1. This means that, according to ISO 8601, it belongs to the last or the next calendar year, respectively. ;--------------------------------------------------------------------------- !TOPIC 591 _ISOWYEAR !NOINDEX !TTY _ISOWYEAR is the ISO 8601 week date year. It may not be the calendar year but the last or next year. This means that, according to ISO 8601, the week belongs to the last or the next calendar year, respectively. ;--------------------------------------------------------------------------- !TOPIC 779 _KEYSTACKED !NOINDEX !TTY _KEYSTACKED returns the number of the keystrokes left in the KSTACK.COM buffer. If KSTACK.COM is not loaded, it returns "0". ;--------------------------------------------------------------------------- !TOPIC 205 _KSTACK !NOINDEX !TTY _KSTACK returns "1" if KSTACK.COM is loaded or "0" otherwise. ;--------------------------------------------------------------------------- !TOPIC 830 _LASTDIR !NOINDEX !TTY _LASTDIR is the previous directory (from the directory history). ;--------------------------------------------------------------------------- !TOPIC 206 _LASTDISK !NOINDEX !TTY _LASTDISK is the last valid drive letter, without a colon. ;--------------------------------------------------------------------------- !TOPIC 207 _LOGFILE !NOINDEX !TTY _LOGFILE returns the name of the current log file (or an empty string if 643LOG is OFF). ;--------------------------------------------------------------------------- !TOPIC 208 _MINUTE !NOINDEX !TTY _MINUTE is the current minute (0 - 59). ;--------------------------------------------------------------------------- !TOPIC 739 _MJD !NOINDEX !TTY _MJD is the Modified Julian Day or the fractional number of days elapsed since 17 November 1858, 00:00 UTC. See 759TZ for more information. ;--------------------------------------------------------------------------- !TOPIC 210 _MONTH !NOINDEX !TTY _MONTH is the current month of the year (1 to 12). ;--------------------------------------------------------------------------- !TOPIC 240 _MONTHF !NOINDEX !TTY _MONTHF is the full name of the current month ("January", "February", etc.). ;--------------------------------------------------------------------------- !TOPIC 716 _READY !NOINDEX !TTY _READY returns a space-delimited list of the the currently ready (accessible) drives on the system (for example, "C: D: E:"). ;--------------------------------------------------------------------------- !TOPIC 213 _ROW !NOINDEX _ROW is the current cursor row (for example, "0" for the top of the screen). ;--------------------------------------------------------------------------- !TOPIC 214 _ROWS !NOINDEX !TTY _ROWS is the current number of screen rows (for example, "25"). ;--------------------------------------------------------------------------- !TOPIC 215 _SECOND !NOINDEX !TTY _SECOND is the current second (0 - 59). ;--------------------------------------------------------------------------- !TOPIC 216 _SHELL !NOINDEX !TTY _SHELL is the current shell nesting level. The primary shell is level "0", and each subsequent secondary shell increments the level by 1. ;--------------------------------------------------------------------------- !TOPIC 737 _STARTPATH !NOINDEX !TTY _STARTPATH is the startup directory for the current shell (not necessarily the same as the location of the executable!). ;--------------------------------------------------------------------------- !TOPIC 366 _STDERR !NOINDEX !TTY _STDERR is "1" if the standard error points to the console, and "0" if it has been redirected. ;--------------------------------------------------------------------------- !TOPIC 367 _STDIN !NOINDEX !TTY _STDIN is "1" if the standard input points to the console, and "0" if it has been redirected. ;--------------------------------------------------------------------------- !TOPIC 368 _STDOUT !NOINDEX !TTY _STDOUT is "1" if the standard output points to the console, and "0" if it has been redirected. ;--------------------------------------------------------------------------- !TOPIC 740 _STZN !NOINDEX !TTY _STZN is the name of standard time in the current time zone. See 759TZ for more information. ;--------------------------------------------------------------------------- !TOPIC 741 _STZO !NOINDEX !TTY _STZO is the offset in minutes of UTC from standard time in the current time zone. See 759TZ for more information. ;--------------------------------------------------------------------------- !TOPIC 217 _SWAPPING !NOINDEX !TTY _SWAPPING returns the current swapping state. The return value is "OFF" if swapping has been disabled with the 668SWAPPING command, "EMS" if expanded memory is being used, "XMS" if extended memory is being used, or "Disk" if 4DOS is using disk swapping. The return value is "None" if swapping has been disabled with the 4DOS.INI 391Swapping directive or if 4DOS failed to initiate memory or disk swapping during initialization. Note: If 4DOS reports swapping to XMS, 4DOS will actually be swapped out of DOS completely by vDosPlus. ;--------------------------------------------------------------------------- !TOPIC 218 _SYSERR !NOINDEX !TTY _SYSERR is the error code of the last operating system error. Some of the error codes are listed below. You will need a technical or programmer's manual to understand these error values in detail, and to check the meaning of codes not listed. The specific codes used and the meaning of each may vary between operating systems or operating system versions; the list below is based on DOS 6.xx and 7.xx. !NOWRAP Code Meaning Code Meaning ---- ---------------------------------- ---- ------------------------------ 1 Bad function 40 Device not ready 2 File not found 41 File allocation table bad 3 Invalid path 4 Too many open files 50 Invalid net request 5 Access denied 51 Remote computer not listening 6 Invalid handle 52 Duplicate name on net 7 Memory destroyed 53 Net name not found 8 Out of memory 54 Net busy 9 Bad memory block 55 Net device no longer exists 10 Bad environment 56 NetBIOS command limit exceeded 11 Bad format 57 Net adapter hardware error 12 Invalid access code 58 Bad response from net 13 Invalid data 59 Unexpected net error 14 Internal DOS error / Fixup overflow 60 Incompatible remote adapter 15 Invalid drive 61 Print queue full 16 Can't remove current directory 62 No room for print file 17 Not same device 63 Print file was cancelled 18 No more files 64 Net name was deleted 65 Access denied 19 Write protect error 66 Net device type incorrect 20 Invalid unit 67 Network name not found 21 Not ready 68 Net name limit exceeded 22 Invalid device request 69 NetBIOS session limit exceeded 23 Data error 70 Sharing temporarily paused 24 Invalid device request parameters 71 Net request not accepted 25 Seek error 72 Print or disk redirection paused 26 Invalid media type 73 Invalid network version 27 Sector not found 74 Adapter close / Account expired 28 Printer out of paper error 75 Password expired 29 Write fault error 76 Login currently not allowed 30 Read fault error 77 Disk limit exceeded on node 31 General failure 78 Not logged in to a net node 32 Sharing violation 33 Lock violation 80 File exists 34 Invalid disk change 81 Duplicated FCB 35 FCB unavailable 82 Can't make directory entry 36 Sharing buffer overflow 83 Fail on INT 24 37 Code page mismatch 38 Out of input before end 39 Out of disk space Some of the less common error codes are listed below. Most of them belong to redirector software (such as MSCDEX, NWCDEX, DRFAT32, etc.), and networking software such as Novell NetWare, or LANtastic, but there are also some codes related to JOIN/SUBST or DOS 7.xx volume locking problems. Code Meaning ---- ----------------------------------------------------------------------- 84 Too many redirections 85 Duplicate redirection 86 Invalid password 87 Invalid parameter 88 Net device fault 89 Net function not supported / No process slots 90 Required component not installed 91 Timer server table overflow 92 Duplicate in timer service table 93 No items to work on 95 Interrupted / Invalid system call 100 Open net semaphore limit exceeded / CD-ROM unknown error 101 Exclusive net semaphore is already owned / CD-ROM not ready 102 Semaphore was set when close attempted / CD-ROM EMS memory bad 103 Too many exclusive semaphore requests / CD not High Sierra or ISO-9660 104 Operation invalid from interrupt handler / CD-ROM door open 105 Semaphore owner died 106 Semaphore limit exceeded 107 Insert drive B: disk into A: / Disk changed 108 Drive locked by another process 109 Broken pipe 110 Pipe open/create failed 111 Pipe buffer overflowed 112 Disk full 113 No more search handles 114 Invalid target handle for dup2 115 Bad user virtual address / Protection violation 116 VIOKBD request / Error on console I/O 117 Unknown category code for IOCTL 118 Invalid value for verify flag 119 Level four driver not found by DOS IOCTL 120 Invalid function number 121 Semaphore timeout 122 Buffer too small to hold return data 123 Invalid character or bad file-system name 124 Unimplemented information level 125 No volume label found 126 Module handle not found 127 Procedure address not found 128 CWait found no children 129 CWait children still running 130 Invalid operation for direct disk-access handle 131 Attempted seek to negative offset 132 Attempted to seek on device or pipe 133 Drive already has JOINed drives 134 Drive is already JOINed 135 Drive is already SUBSTed 136 Can not delete drive which is not JOINed 137 Can not delete drive which is not SUBSTed 138 Can not JOIN to a JOINed drive 139 Can not SUBST to a SUBSTed drive 140 Can not JOIN to a SUBSTed drive 141 Can not SUBST to a JOINed drive 142 Drive is busy 143 Can not JOIN/SUBST to same drive 144 Directory must not be root directory 145 Can only JOIN to empty directory 146 Path is already in use for SUBST 147 Path is already in use for JOIN 148 Path is in use by another process 149 Directory previously SUBSTituted 150 System trace error 151 Invalid event count for DosMuxSemWait 152 Too many waiting on mutex 153 Invalid list format 154 Volume label too large 155 Unable to create another TCB 156 Signal refused 157 Segment discarded 158 Segment not locked 159 Invalid thread-ID address 160 Bad arguments / Bad environment pointer 161 Invalid pathname passed to EXEC 162 Signal already pending 163 Uncertain media / ERROR_124 mapping 164 Maximum number of threads reached / No more process slots 165 ERROR_124 mapping 176 Volume is not locked 177 Volume is locked in drive 178 Volume is not removable 180 Lock count has been exceeded / Invalid segment number 181 A valid eject request failed / Invalid call gate 182 Invalid ordinal 183 Shared segment already exists 184 No child process to wait for 185 NoWait specified and child still running 186 Invalid flag number 187 Semaphore does not exist 188 Invalid starting code segment 189 Invalid stack segment 190 Invalid module type (DLL can not be used as application) 191 Invalid EXE signature 192 EXE marked invalid 193 Bad EXE format (e.g. DOS-mode program) 194 Iterated data exceeds 64K 195 Invalid minimum allocation size 196 Dynamic link from invalid Ring 197 IOPL not enabled 198 Invalid segment descriptor privilege level 199 Automatic data segment exceeds 64K 200 Ring2 segment must be moveable 201 Relocation chain exceeds segment limit 202 Infinite loop in relocation chain 203 Environment variable not found 204 Not current country 205 No signal sent 206 File name not 8.3 207 Ring2 stack in use 208 Meta expansion is too long 209 Invalid signal number 210 Inactive thread 211 File system information not available 212 Locked error 213 Attempted to execute non-family API call in DOS mode 214 Too many modules 215 Nesting not allowed 230 Non-existent pipe, or bad operation 231 Pipe is busy 232 No data available for nonblocking read 233 Pipe disconnected by server 234 More data available 255 Invalid drive !WRAP ;--------------------------------------------------------------------------- !TOPIC 588 _TICK !NOINDEX !TTY _TICK contains the current BIOS clock tick since midnight. There are approximately 18.2 ticks per second. The possible values are from 0 to 1,573,039. ;--------------------------------------------------------------------------- !TOPIC 219 _TIME !NOINDEX !TTY _TIME contains the current system time in the format hh:mm:ss. The separator character may vary depending upon your country information. ;--------------------------------------------------------------------------- !TOPIC 220 _TRANSIENT !NOINDEX !TTY _TRANSIENT is "1" if the current shell is transient (started with a /C, see 352Startup), or "0" otherwise. See also 109Automatic Batch Files for further uses of the _TRANSIENT internal variable. ;--------------------------------------------------------------------------- !TOPIC 742 _TZN !NOINDEX !TTY _TZN is the name of the current time zone. See 759TZ for more information. ;--------------------------------------------------------------------------- !TOPIC 743 _TZO !NOINDEX !TTY _TZO is the offset in minutes of UTC from the current time zone. See 759TZ for more information. ;--------------------------------------------------------------------------- !TOPIC 744 _UNIXTIME !NOINDEX !TTY _UNIXTIME is the number of seconds elapsed since 1 January 1970, 00:00 UTC (the Epoch) as defined by ISO/IEC 9945 (a.k.a. POSIX or IEEE Std 1003.1). See 759TZ for more information. ;--------------------------------------------------------------------------- !TOPIC 745 _UTCDATE !NOINDEX !TTY _UTCDATE is the current UTC date in format mm-dd-yy (U.S.), dd-mm-yy (Europe), or yy-mm-dd (Japan). The separator character may vary depending upon your country information. See 759TZ for more information. ;--------------------------------------------------------------------------- !TOPIC 746 _UTCDATETIME !NOINDEX !TTY _UTCDATETIME is the current UTC date and time as 14-characters in the format yyyyMMddhhmmss. The date part is the same as 748_UTCISODATE without separators. See 759TZ for more information. ;--------------------------------------------------------------------------- !TOPIC 747 _UTCHOUR !NOINDEX !TTY _UTCHOUR is the current UTC hour. See 759TZ for more information. ;--------------------------------------------------------------------------- !TOPIC 748 _UTCISODATE !NOINDEX !TTY _UTCISODATE is the current UTC date in ISO 8601 international format (yyyy-mm-dd). See 759TZ for more information. ;--------------------------------------------------------------------------- !TOPIC 749 _UTCMINUTE !NOINDEX !TTY _UTCMINUTE is the current UTC minute. See 759TZ for more information. ;--------------------------------------------------------------------------- !TOPIC 750 _UTCSECOND !NOINDEX !TTY _UTCSECOND is the current UTC second. See 759TZ for more information. ;--------------------------------------------------------------------------- !TOPIC 760 _UTCTIME !NOINDEX !TTY _UTCTIME is the current UTC time in the format hh:mm:ss. The separator character may vary depending upon your country information. See 759TZ for more information. ;--------------------------------------------------------------------------- !TOPIC 350 Examples of Variable Functions !NOINDEX You can use variable functions in a wide variety of ways depending on your needs. We've included a few examples below to give you an idea of what's possible. For a more comprehensive set of examples see the EXAMPLES.BTM file which came with 4DOS. For information on how to set up user-defined variable functions, see the 696FUNCTION and 699UNFUNCTION commands. To set the prompt to show the amount of free memory (see 652PROMPT for details on including variable functions in your prompt): c:\> prompt (%%@dosmem[K]K) $p$g Set up a simple command-line calculator. The calculator is used with a command like CALC 3 * (4 + 5): c:\> alias calc `echo The answer is: %@eval[%&]` The following batch file uses variable functions to implement "once a day" execution of a group of commands. It works by constructing a 6-digit number "yymmdd" from today's date, and comparing that to a number of the same type stored in the file C:\ONCEADAY.DAT. If today's date is numerically larger than the saved date, and the time is after 6:00 AM, then the "once a day" commands are run, and today's date is saved in the file as the new date for comparison. Otherwise, no action is taken. You can make this file simpler using the %250@DATE and %322@TIME functions instead of using %291@INSTR to extract substrings of the %189_DATE and %219_TIME variables; we used the approach shown to demonstrate the use of %@INSTR. rem Temporary variables used to shorten example lines: rem DD is _date, DY is yymmdd date, TM is _time set dd=%_date set dy=%@instr[6,2,%dd]%@instr[0,2,%dd]%@instr[3,2,%dd] set lastdate=0 iff exist c:\onceaday.dat then set lastdate=%@line[onceaday.dat,0] endiff iff %dy gt %lastdate then set tm=%_time iff "%@instr[0,2,%tm]%@instr[3,2,%tm]" gt "0600" then rem Commands to be executed once a day go here echo %dy > c:\onceaday.dat endiff endiff ;--------------------------------------------------------------------------- !TOPIC 241 Variable Functions !NOINDEX Variable functions are like 161internal variables, but they take one or more arguments (which can be environment variables or even other variable functions) and they return a value. There are two general types of variable functions, pre-defined variable functions and user-defined ones. The list below gives a one-line description of each pre-defined function, and a cross-reference which selects a full screen help topic on that function. A few of the variables are simple enough that the one-line description is sufficient, but in most cases you should check for any additional information in the cross-reference topic if you are not already familiar with a function. You can also obtain help on any function with a HELP @functionname command at the prompt. See the discussion after the function list for some additional information, and examples of how these functions can be used. For a more comprehensive set of examples see the EXAMPLES.BTM file which came with 4DOS. For information on how to set up user-defined variable functions, refer to the description of the 696FUNCTION and 699UNFUNCTION commands. Note: The functions marked with an exclamation mark [!] are 4DOS-specific; they are not present in 0204NT. Take this into account when writing portable batch files. The pre-defined variable functions are grouped by category: System status 258@DOSMEM[b|k|m] ! Free DOS memory 262@EMS[b|k|m] ! Free EMS memory 268@EXTENDED[b|k|m] ! Free extended memory 304@MASTER[varname] Value from master environment 310@READSCR[row,col,len] Character from the screen 331@XMS[b|k|m] ! Free XMS memory Drives and devices @CDROM[d:] "0" in vDosPlus 809@CLUSTSIZE[d:] ! Cluster size @CODEPAGE[name] "0" in vDosPlus 826@COM[n] ! Serial port ready status (0 or 1) 359@CWD[d:] Current directory of specified drive 360@CWDS[d:] Current directory with trailing \ 254@DEVICE[name] Character device detection 255@DISKFREE[d:,b|k|m|g] Free disk space 256@DISKTOTAL[d:,b|k|m|g] Total disk space 257@DISKUSED[d:,b|k|m|g] Used disk space 727@DRIVETYPE[d:] Type of drive (hard/remote drive, etc.) @HDDSIZE[d:,b|k|m|g] "0" in vDosPlus 293@LABEL[d:] Volume label @LPT[n] "1" in vDosPlus 311@READY[d:] Drive ready status (0 or 1) 312@REMOTE[d:] Remote drive detection (0 or 1) 313@REMOVABLE[d:] Removable drive detection (0 or 1) 358@SERIAL[d:] Volume serial number Files 244@ATTRIB[filename,[nrhsad]] File attribute test (0 or 1) 728@COMPARE[filename1,filename2] Compare two files 346@CRC32[filename] CRC32 of a file 253@DESCRIPT[filename] File description 269@FILEAGE[filename[,acw]] File age (date and time) 270@FILECLOSE[n] Close a file 271@FILEDATE[filename[,[acw][,n]]] File date 273@FILEOPEN[filename,mode] Open a file 274@FILEREAD[n[,length]] Read line or bytes from a file 478@FILEREADB[n,length] Read bytes from a file 275@FILES[filename[,-nrhsad]] Count files matching a wildcard 276@FILESEEK[n,offset,start] Move file pointer to an offset 277@FILESEEKL[n,line] Move file pointer to a line number 278@FILESIZE[filename,b|k|m|g] Size of files matching a wildcard 279@FILETIME[filename[,[acw][,s]]] File time 280@FILEWRITE[n,text] Write next line to a file 281@FILEWRITEB[n,length,string] Write bytes to a file 282@FINDCLOSE[filename] Close search handle 283@FINDFIRST[filename[,-nrhsad]] Find first matching file 284@FINDNEXT[filename[,-nrhsad]] Find next matching file 297@LINE[filename,n] Read the specified line from a file 298@LINES[filename] Count lines in a file 402@MD5[filename] MD5 hash of a file 317@SEARCH[filename] Path search 403@SHA1[filename] SHA1 hash of a file 325@TRUENAME[filename] True name of a file 408@TRUNCATE[n] Truncate file at current position 326@UNIQUE[d:\path] Create file with unique name File names 334@ALTNAME[filename] FAT filename 266@EXPAND[filename,[nrhsad]] Wildcard expansion 267@EXT[filename] File extension 272@FILENAME[filename] File name and extension 286@FULL[filename] Full file name with path 296@LFN[filename] Long path and filename 306@NAME[filename] File name without path or extension 308@PATH[filename] File path without name 503@QUOTE[filename] Double quote a filename 319@SFN[filename] Short path and filename 504@UNQUOTE[filename] Remove double quotes from a filename 723@UNQUOTES[string] Remove leading & trailing double quotes Strings and characters 243@ASCII[c] Numeric ASCII value(s) for string 345@CAPS["sep",c] Capitalize first letter of words 246@CHAR[n] Character(s) for numeric ASCII 507@COUNT[c,string] Occurrences of a character in a string 347@FIELD[["sep",]n,string] Returns a field from a string 449@FIELDS[["sep",]string] Counts number of fields in a string 285@FORMAT[[-][x][.y],string] Formats (justifies) a string 289@INDEX[string1,string2[,n]] Position of one string in another 290@INSERT[n,string1,string2] Insert one string into another 291@INSTR[start,length,string] Extract a substring 508@ISALNUM[string] Test for alphanumeric characters 509@ISALPHA[string] Test for alphabetic characters 510@ISASCII[string] Test for ASCII characters 528@ISCNTRL[string] Test for control characters 529@ISDIGIT[string] Test for decimal digits 828@ISLOWER[string] Test for lower-case letters 530@ISPRINT[string] Test for printable characters 558@ISPUNCT[string] Test for punctuation characters 559@ISSPACE[string] Test for white space characters 829@ISUPPER[string] Test for upper-case letters 560@ISXDIGIT[string] Test for hexadecimal digits 730@LCS[str1,str2] Longest Common Subsequence in strings 294@LEFT[n,string] Leftmost characters of a string 295@LEN[string] Length of a string 299@LOWER[string] Convert string to lower case 406@LTRIM[chars,string] Trims specified leading characters 314@REPEAT[c,n] Repeat a character 315@REPLACE[str1,str2,str3] Replace within a string 729@REVERSE[string] Reverse a string 316@RIGHT[n,string] Rightmost characters of a string 407@RTRIM[chars,string] Trims specified trailing characters 733@SIMILAR[str1,str2] Similarity (0 - 100%) between 2 strings 320@STRIP[chars,string] Strip characters from a string 722@SUBST[n,str1,str2] Substitute a string in another string 321@SUBSTR[string,start,length] Extract a substring 324@TRIM[string] Remove blanks from a string 327@UPPER[string] Convert string to upper case 328@WILD[str1,str2] Wildcard comparison 329@WORD[["sep",]n,string] Extract a word from a string 330@WORDS[["sep",]string] Counts number of words in a string Numbers and arithmetic 333@ABS[n] Absolute value of a number 452@AVERAGE[a,b,...] Average of a list of integers 725@CEILING[n] Smallest integer not less than n 248@COMMA[n] Inserts commas in a number 249@CONVERT[in,out,value] Base conversion 252@DEC[expression] Decrements an expression 336@DECIMAL[n] Decimal portion of a number 337@DIGITS[string] Test if a string is only digits 263@EVAL[expression] Arithmetic calculations 726@FLOOR[n] Largest integer not larger than n 288@INC[expression] Increments an expression 292@INT[n] Integer part of a number 342@MAX[a,b,...] Largest integer in list 343@MIN[a,b,...] Smallest integer in list 307@NUMERIC[string] Test if a string is numeric 309@RANDOM[min,max] Generate a random integer Dates and times 401@AGEDATE[n[,format]] Converts an age into date and time 250@DATE[date] Convert date to number of days 717@DATECONV[date[,format]] Convert date from one format to another 251@DAY[date] Day of the month 259@DOW[date] Day of the week 338@DOWF[date] Day of the week (full name) 260@DOWI[date] Numeric day of the week (Sun = 1, etc.) 261@DOY[date] Numeric day of the year 458@ISODOWI[date] ! Numeric day of the week (Mon = 1, etc.) 459@ISOWEEK[date] ! Week of the year pursuant to ISO 8601 721@ISOWYEAR[date] ! ISO 8601 week date year 301@MAKEAGE[date[,time]] Convert date/time to file date/time 302@MAKEDATE[n[,format]] Convert number of days to date 303@MAKETIME[n] Convert number of seconds to time 305@MONTH[date] Month of the year 369@MONTHF[date] ! Month of the year (full name) 322@TIME[time] Convert time to number of seconds 332@YEAR[date] Year number Utility 242@ALIAS[name] Value of an alias 247@CLIP[n] Line from the clipboard 335@CLIPW[n] Write line to clipboard 734@DIRSTACK[n] Display directory stack entry 339@ERRTEXT[n] DOS error text for specified code 264@EXEC[command] Execute a command 265@EXECSTR[command] Execute, return string 348@FUNCTION[name] Value of a user-defined function 718@HISTORY[x[,y]] A line or word from the command history 287@IF[condition,true,false] Evaluates a test condition 340@INIREAD[file,sect,key] Read from .INI file 341@INIWRITE[file,sect,key,val] Write to .INI file 318@SELECT[file,t,l,b,r,title] Menu selection 323@TIMER[n] Elapsed time of specified timer Additional Notes Like all environment variables, these variable functions must be preceded by a percent sign in normal use (%@EVAL, %@LEN, etc.). All variable functions must have square brackets enclosing their argument(s). The argument(s) to a variable function cannot exceed 255 characters in length for all arguments taken as a group. Specific Functions and Arguments Some variable functions, like 255@DISKFREE, are shown with "b|k|m|g" as one of their arguments. Those functions return a number of bytes, kilobytes, megabytes or gigabytes based on the "b|k|m|g" argument: b return the number of bytes K return the number of kilobytes (bytes / 1,024) k return the number of thousands of bytes (bytes / 1,000) M return the number of megabytes (bytes / 1,048,576) m return the number of millions of bytes (bytes / 1,000,000) G return the number of gigabytes (bytes / 1,073,741,824) g return the number of billions of bytes (bytes / 1,000,000,000) You can include commas (or the "thousands separator" character for your system) in the results from a "b|k|m|g" function by appending a "c" to the argument. For example, to add commas to a "b" or number of bytes result, enter "bc" as the argument. To set the thousands separator, see the 445ThousandsChar directive. Several functions return filenames or parts of filenames. It is possible, and on LFN drives very likely, that the strings returned by these functions may contain whitespace or other special characters. To avoid problems which could be caused by these characters, quote the returned name before you pass it to other commands, for example (either of these methods would work): set fname="%@findfirst[pro*.*]" echo First PRO file contains: type %fname ..... set fname=%@findfirst[pro*.*] echo First PRO file contains: type "%fname" ..... If you don't use the quotes in the 663SET or 677TYPE command in this example, TYPE will not interpret any whitespace or special characters in the name properly. In variable functions which take a drive letter as an argument, like 255@DISKFREE or 311@READY, the drive letter must be followed by a colon. The function will not work properly if you use the drive letter without the colon. The 274@FILEREAD, 478@FILEREADB, 280@FILEWRITE, 281@FILEWRITEB, 276@FILESEEK, 277@FILESEEKL, 408@TRUNCATE and 270@FILECLOSE functions allow you to access files based on their file handle. These functions should only be used with file handles returned by 273@FILEOPEN! If you use them with any other file handle you may damage other files opened by 4DOS (or, in a secondary shell, the program which started 4DOS), or hang your system. Many functions return values based on information provided by your operating system. Such functions will only return correct information if the operating system provides it. For example, 311@READY will not return accurate results if your operating system does not provide correct disk drive status information to 4DOS. See also some 350examples of functions used at the prompt, in aliases and batch files. ;--------------------------------------------------------------------------- !TOPIC 344 Date Formats !NOINDEX Variable function date arguments use the date format and separators mandated by your country code (for example dd.mm.yy in Germany, or yy-mm-dd in Japan). The year can be entered as a 4-digit or 2-digit value. Two-digit years between 80 and 99 are interpreted as 1980 - 1999; values between 00 and 79 are interpreted as 2000 - 2079. If the date begins with a four digit year greater than 1900, it is assumed to be in the ISO 8601 international format yyyy-mm-dd. If the date contains the letter "W", it is assumed to be in the ISO 8601 week date format yyyy-Www-d, where yyyy = year, ww = week, d = week day. If the date is entered as two numbers in the format yyyy-ddd, it is assumed to be in the ISO 8601 ordinal date format, where yyyy = year, ddd = day of the year. ;--------------------------------------------------------------------------- !TOPIC 242 @ALIAS !NOINDEX !TTY @ALIAS[name]: Returns the contents of the specified alias as a string, or a null string if the alias doesn't exist. When manipulating strings returned by @ALIAS you may need to disable certain special characters with the 664SETDOS /X command. Otherwise, command separators, redirection characters, and other similar "punctuation" in the alias may be interpreted as part of the current command, rather than part of a simple text string. ;--------------------------------------------------------------------------- !TOPIC 333 @ABS !NOINDEX !TTY @ABS[n]: Returns the absolute value of the number. ;--------------------------------------------------------------------------- !TOPIC 401 @AGEDATE !NOINDEX !TTY @AGEDATE[n[,format]]: Converts n (an age) into a date and time pair (formatted according to the current country settings). Time is separated from date by a comma, and is always in 24-hour format. n is the file date and time (age), as returned by 269@FILEAGE and 301@MAKEAGE. @AGEDATE takes an optional second argument for the date format: 0 - system default format 1 - U.S. format (mm-dd-yy) 2 - European format (dd-mm-yy) 3 - Japanese format (yy-mm-dd) 4 - ISO 8601 international format (yyyy-mm-dd) 5 - ISO 8601 international format (yyyy-Www-d) week date 6 - ISO 8601 international format (yyyy-ddd) ordinal date The separator used in the return string depends on the current country settings of the system, except for in the ISO 8601 international format, where it will always by a hyphen ('-') as per spec. ;--------------------------------------------------------------------------- !TOPIC 334 @ALTNAME !NOINDEX !TTY @ALTNAME[filename]: Returns the alternate (short, "8.3" FAT-format) name for the specified file. If the filename is already in 8.3 format, or if it does not exist, returns the filename as entered. @ALTNAME will also return the shortened pathname if you provide a path in place of the filename. The filename must be in quotes if it contains whitespace or special characters. ;--------------------------------------------------------------------------- !TOPIC 243 @ASCII !NOINDEX !TTY @ASCII[c]: Returns the numeric value of the specified ASCII character or string as a string. For example %@ASCII[A] returns 65. You can put an escape character [] before the actual character to process. This allows quotes and other special characters as the argument (e.g., %@ASCII[`]). If the argument is a string, @ASCII returns a space delimited string with the ASCII values of each character. ;--------------------------------------------------------------------------- !TOPIC 244 @ATTRIB !NOINDEX !TTY @ATTRIB[filename[,-nrhsad[,p]]]: Returns a "1" if the specified file has the matching attribute(s); otherwise returns a "0". The attributes are: N Normal (no attributes set) S System R Read-only A Archive H Hidden D subDirectory The attributes (other than N) can be combined (for example %@ATTRIB[MYFILE,HS]). You can prefix an attribute with - to mean "everything except files with this attribute." Without the optional p as a third argument, ATTRIB will only return a 1 if all of the attributes match. With the p, ATTRIB will return a 1 if there is a partial match. For example, if MYFILE.DAT has R, H, and A attributes set: %@attrib[myfile.dat,r] returns 0 because there is not an exact match %@attrib[myfile.dat,r,p] returns 1 because there is a partial match If you do not specify any attributes, @ATTRIB will return the attributes of the specified file in the format RHSAD, rather than a "0" or "1". Attributes which are not set will be replaced with an underscore. For example, if SECURE.DAT has the read-only, hidden, and archive attributes set, %@ATTRIB[SECURE.DAT] would return "RH_A_" (without the quotes). ;--------------------------------------------------------------------------- !TOPIC 452 @AVERAGE !NOINDEX !TTY @AVERAGE[a,b,c,...]: Returns the average of a list of integer numbers. ;--------------------------------------------------------------------------- !TOPIC 345 @CAPS !NOINDEX !TTY @CAPS["sep",string]: Capitalizes the first letter of each word in the string. Word delimiters are defined by the first argument, which must be enclosed in double quotes. ;--------------------------------------------------------------------------- !TOPIC 725 @CEILING !NOINDEX !TTY @CEILING[n]: Returns the value of the smallest integer that is not less than n. ;--------------------------------------------------------------------------- !TOPIC 246 @CHAR !NOINDEX !TTY @CHAR[n]: Returns the character(s) corresponding to an ASCII numeric value. For example %@CHAR[65] returns A. %@CHAR[65 66 67] returns ABC. The ASCII code of each byte may be entered in either decimal (1 to 3 decimal digits 0-9), or hexadecimal format ("0x" followed by 1 or 2 hex digits 0-F). ;--------------------------------------------------------------------------- !TOPIC 507 @COUNT !NOINDEX !TTY @COUNT[c,string]: Returns the number of times the character c appears in string. ;--------------------------------------------------------------------------- !TOPIC 247 @CLIP !NOINDEX !TTY @CLIP[n]: Returns line n from the clipboard. The first line is numbered 0. "**EOC**" is returned for all line numbers beyond the end of the clipboard. ;--------------------------------------------------------------------------- !TOPIC 335 @CLIPW !NOINDEX !TTY @CLIPW[string]: Writes a string to the clipboard. ;--------------------------------------------------------------------------- !TOPIC 809 @CLUSTSIZE !NOINDEX !TTY @CLUSTSIZE[d:]: Returns the size in bytes of a cluster of the specified drive. ;--------------------------------------------------------------------------- !TOPIC 826 @COM !NOINDEX !TTY @COM[n]: Returns a "1" if the specified serial port is ready; otherwise, returns "0". n=1 checks COM1, n=2 checks COM2, n=3 checks COM3, and n=4 checks COM4. The value returned from @COM reflects the status of the Data Set Ready (DSR) line, which depends also on the cable and the device connected to its other end. You may need to check both for troubleshooting eventual problems. ;--------------------------------------------------------------------------- !TOPIC 248 @COMMA !NOINDEX !TTY @COMMA[n]: Inserts commas, or the "thousands separator" character for your system, into a numeric string. To set the thousands separator see the 445ThousandsChar directive. See also the 285@FORMAT function, which can be useful for aligning or zero-padding numbers. NOTE: If the 823NO_SEP environment variable is set, @COMMA has no effect. ;--------------------------------------------------------------------------- !TOPIC 728 @COMPARE !NOINDEX !TTY @COMPARE[filename1,filename2]: Returns 1 if the two files are identical, or 0 if they differ. ;--------------------------------------------------------------------------- !TOPIC 249 @CONVERT !NOINDEX !TTY @CONVERT[input, output, value]: Converts a numeric string (value) from one number base (input) to another (output). Valid bases range from 2 to 36. The value must be a positive number between 0 and 2**32-1 (4,294,967,295). No error is returned if value is outside that range. For example, to convert "1010101" from binary to decimal, use this syntax: %@convert[2,10,1010101] ;--------------------------------------------------------------------------- !TOPIC 346 @CRC32 !NOINDEX !TTY @CRC32[filename]: Returns the CRC32 for the specified file, or "-1" if the file doesn't exist. ;--------------------------------------------------------------------------- !TOPIC 359 @CWD !NOINDEX !TTY @CWD[d:]: Returns the Current Working Directory of the specified drive, in the format "d:\pathname". ;--------------------------------------------------------------------------- !TOPIC 360 @CWDS !NOINDEX !TTY @CWDS[d:]: Returns the Current Working Directory of the specified drive, in the format "d:\pathname\". ;--------------------------------------------------------------------------- !TOPIC 250 @DATE !NOINDEX !TTY @DATE[date]: Returns the number of days since January 1, 1980 for the specified date. The date may be in either the local date format, or in ISO format with a four-digit year; see 344date formats for more information. ;--------------------------------------------------------------------------- !TOPIC 717 @DATECONV !NOINDEX !TTY @DATECONV[date[,format]]: Converts a date from one format to another. The input date may be in either the local date format, or in ISO format with a four-digit year; see 344date formats for more information. By default, the output date is formatted according to the current country settings, but @DATECONV takes an optional second argument for the output date format: 0 - system default format 1 - U.S. format (mm-dd-yy) 2 - European format (dd-mm-yy) 3 - Japanese format (yy-mm-dd) 4 - ISO 8601 international format (yyyy-mm-dd) 5 - ISO 8601 international format (yyyy-Www-d) week date 6 - ISO 8601 international format (yyyy-ddd) ordinal date The separator used in the return string depends on the current country settings of the system, except for in the ISO 8601 international format, where it will always by a hyphen ('-') as per spec. ;--------------------------------------------------------------------------- !TOPIC 251 @DAY !NOINDEX !TTY @DAY[date]: Returns the numeric day of the month for the specified date. The date may be in either the local date format, or in ISO format with a four-digit year; see 344date formats for more information. ;--------------------------------------------------------------------------- !TOPIC 252 @DEC !NOINDEX !TTY @DEC[expression]: Returns the same value as 263@EVAL[(expression) - 1]. That is, it subtracts one from the value of the expression. Note that the function returns a value that has been decremented; any variable used in the expression will not be changed. To decrement the value of a variable, use a command like this: set var=%@dec[%var] See also 288@INC. ;--------------------------------------------------------------------------- !TOPIC 336 @DECIMAL !NOINDEX !TTY @DECIMAL[n]: Returns the decimal portion of the number. ;--------------------------------------------------------------------------- !TOPIC 253 @DESCRIPT !NOINDEX !TTY @DESCRIPT[filename]: Returns the file description for the specified filename (see 611DESCRIBE). ;--------------------------------------------------------------------------- !TOPIC 254 @DEVICE !NOINDEX !TTY @DEVICE[name]: Returns "1" if the name is a character device (such as a printer or serial port), or "0" if not. ;--------------------------------------------------------------------------- !TOPIC 337 @DIGITS !NOINDEX !TTY @DIGITS[n]: Returns 1 if the string is digits only (no decimal point, sign character, or thousands separator). ;--------------------------------------------------------------------------- !TOPIC 734 @DIRSTACK !NOINDEX !TTY @DIRSTACK[n]: Returns the name of the nth entry in the directory stack. The oldest is number 0. If no n parameter is specified, returns the total number of entries in the stack. The directory stack is set by calls to 653PUSHD / 651POPD. ;--------------------------------------------------------------------------- !TOPIC 255 @DISKFREE !NOINDEX !TTY @DISKFREE[d:,b|k|m|g]: Returns the amount of free disk space on the specified drive. DOS networks with large server disk drives (over 2 GB) may report disk space values that are too small when @DISKFREE is used. If this occurs, it is because the network software does not report the proper values to 4DOS. ;--------------------------------------------------------------------------- !TOPIC 256 @DISKTOTAL !NOINDEX !TTY @DISKTOTAL[d:,b|k|m|g]: Returns the total disk space on the specified drive. DOS networks with large server disk drives (over 2 GB) may report disk space values that are too small when @DISKTOTAL is used. If this occurs, it is because the network software does not report the proper values to 4DOS. ;--------------------------------------------------------------------------- !TOPIC 257 @DISKUSED !NOINDEX !TTY @DISKUSED[d:,b|k|m|g]: Returns the amount of disk space in use by files and directories on the specified drive. DOS networks with large server disk drives (over 2 GB) may report disk space values that are too small when @DISKUSED is used. If this occurs, it is because the network software does not report the proper values to 4DOS. ;--------------------------------------------------------------------------- !TOPIC 258 @DOSMEM !NOINDEX !TTY @DOSMEM[b|k|m]: Returns the amount of free base memory. ;--------------------------------------------------------------------------- !TOPIC 259 @DOW !NOINDEX !TTY @DOW[date]: Returns the first three characters of the day of the week for the specified date ("Mon", "Tue", "Wed", etc.) The date may be in either the local date format, or in ISO format with a four-digit year; see 344date formats for more information. ;--------------------------------------------------------------------------- !TOPIC 338 @DOWF !NOINDEX !TTY @DOWF[date]: Returns the day of the week for the specified date ("Monday", "Tuesday", "Wednesday", etc.) The date may be in either the local date format, or in ISO format with a four-digit year; see 344date formats for more information. ;--------------------------------------------------------------------------- !TOPIC 260 @DOWI !NOINDEX !TTY @DOWI[date]: Returns the day of the week for the specified date as an integer (1 = Sunday, 2 = Monday, etc). The date may be in either the local date format, or in ISO format with a four-digit year; see 344date formats for more information. ;--------------------------------------------------------------------------- !TOPIC 261 @DOY !NOINDEX !TTY @DOY[date]: Returns the day of the year for the specified date (1-366). The date may be in either the local date format, or in ISO format with a four-digit year; see 344date formats for more information. ;--------------------------------------------------------------------------- !TOPIC 727 @DRIVETYPE !NOINDEX !TTY @DRIVETYPE[d:]: Returns the type for the specified drive: 0 - The drive type cannot be determined 1 - The drive does not exist 2 - Removable disk 3 - Fixed disk 4 - Remote (network) drive ;--------------------------------------------------------------------------- !TOPIC 262 @EMS !NOINDEX !TTY @EMS[b|k|m]: Returns the amount of free EMS memory. ;--------------------------------------------------------------------------- !TOPIC 339 @ERRTEXT !NOINDEX !TTY @ERRTEXT[n]: Returns the DOS error text for the specified code. ;--------------------------------------------------------------------------- !TOPIC 263 @EVAL !NOINDEX !TTY @EVAL[expression]: Evaluates an arithmetic expression. The expression can contain environment variables and other variable functions, and may use any of the operators listed below. @EVAL also supports parentheses, commas, and decimals. Parentheses can be nested. @EVAL will strip leading and trailing zeros from the result. The valid operators are: +/- (with one value) numeric sign (e.g. -1, +3) + (with two values) addition - (with two values) subtraction * multiplication / division \ integer division (the integer part of the quotient) MOD modulo (the remainder when the first value is divided by the second) %% same as MOD ** exponentiation (the exponent must be a non-negative decimal integer) AND bitwise and (returns a 1 for each bit where the corresponding bits in both values are 1) & same as AND OR bitwise or (returns a 1 for each bit where the corresponding bit in either value is 1) | same as OR XOR bitwise exclusive or (returns a 1 for each bit where the corresponding bit in one value is 1, and in the other value is 0) ^ same as XOR The order of precedence from highest to lowest is: Parentheses Unary + and - ** *, /, \, MOD +, - AND, OR, XOR For example, 3 + 4 * 2 will be interpreted as 3 + 8, not as 7 * 2. To change this order of evaluation, use parentheses to specify the order you want. To ensure that your @EVAL expressions are interpreted correctly, spaces should be placed on both sides of each operator, for example: %@eval[(20 %% 3) + 4] You can enter hexadecimal numbers up to 8 digits long by preceding the number with 0x. For example: c:\> echo %@eval[0x10 + 0x10] 32 c:\> echo %@convert[10, 16, %@eval[0x10 + 0x10]] 20 You can specify hexadecimal output with the special syntax @eval[...=H], in which case a leading 0x is not included in the output, or @eval[...=X], in which case a leading 0x is included in the output. For example: c:\> echo %@eval[3*6=H] 12 The default is decimal output. To convert between decimal and hexadecimal formats, see the 249@CONVERT function. The maximum precision is 20 digits to the left of the decimal point and 10 digits to the right of the decimal point. You can alter the default precision on the Options 2 page of the 648OPTION dialogs, or with the 427EvalMax and 428EvalMin directives in 4DOS.INI, and with the 664SETDOS /F command. You can alter the decimal character from the Options 1 page of the OPTION dialogs, with the 421DecimalChar directive, or the SETDOS /G command. You can alter the precision for a single evaluation with the construct @EVAL[expression=x.y]. The x value specifies the minimum decimal precision (i.e., the minimum number of decimal places displayed); the y value sets the maximum decimal precision. You can use =x,y instead of =x.y if the comma is your decimal separator. You can specify either or both values. If x is greater than y, it is ignored; if only x is specified, y is set to the same value (e.g. =2 is equivalent to =2.2). For example: @eval[3 / 6=2.4] returns 0.50 @eval[3 / 6=4.4] returns 0.5000 @eval[3 / 7] returns 0.4285714286 @eval[3 / 7=.4] returns 0.4286 @eval[3 / 7=2.2] returns 0.43 @eval[3 / 7=2] also returns 0.43 Also see 252@DEC and 288@INC. ;--------------------------------------------------------------------------- !TOPIC 264 @EXEC !NOINDEX !TTY @EXEC[[@]command]: Execute the command. The command can be an alias, internal command, external command, .BTM file, .BAT file, .CMD file. @EXEC is primarily intended for running a program from within the PROMPT. It is a "back-door" entry into command processing and should be used with extreme caution. Incorrect or recursive use of @EXEC may cause stack overflows or hang your system. While you may be able to use complex commands involving pipes, command groups, etc. as its argument, you should test carefully first as the results may not be what you expect. We recommend that you only use a single command as the argument to @EXEC. By default, @EXEC returns the result code from the command; if you preface the command name with an '@' then @EXEC will return an empty string. ;--------------------------------------------------------------------------- !TOPIC 265 @EXECSTR !NOINDEX !TTY @EXECSTR[command]: Runs the specified command and returns the first line written to stdout by that command. @EXECSTR is useful for retrieving a result from an external utility. For example, if you have a program called NETTIME.EXE which retrieves the time of day from your network server and writes it to standard output, you could save it in an environment variable using a command like this: c:\> set server_time=%@execstr[d:\path\nettime.exe] If the same utility returned a result properly formatted for the 672TIME command you could also use it to set the time on your system: c:\> time %@execstr[d:\path\nettime.exe] @EXECSTR is a "back-door" entry into command processing and should be used with extreme caution. Incorrect or recursive use of @EXECSTR may cause stack overflows or hang your system. While you may be able to use complex commands involving pipes, command groups, etc. as its argument, you should test carefully first as the results may not be what you expect. We recommend that you only use a single command as the argument to @EXECSTR. ;--------------------------------------------------------------------------- !TOPIC 266 @EXPAND !NOINDEX !TTY @EXPAND[filename[,-nrhsad]]: Returns, on a single line, the names of all files and directories that match the filename specification, which may contain wildcards and include lists. Returns an empty string if no files match. If the file list is longer than the allowed command line length, it will be truncated without an error message. The second argument, if included, defines the attributes of the files that will be included in the search. The attributes are: N Normal (no attributes set) S System R Read-only A Archive H Hidden D subDirectory The attributes (other than N) can be combined (for example %@EXPAND[MYFILE,HS]). You can prefix an attribute with - to mean "everything except files with this attribute." If the attribute argument is not used, all matching files and directories will be returned. ;--------------------------------------------------------------------------- !TOPIC 267 @EXT !NOINDEX !TTY @EXT[filename]: Returns the extension from a filename, without a leading period. On LFN drives, the extension can be up to 64 characters long. On traditional FAT drives, it can be up to 3 characters long. ;--------------------------------------------------------------------------- !TOPIC 268 @EXTENDED !NOINDEX !TTY @EXTENDED[b|k|m]: Returns the amount of extended memory. Most memory managers convert extended memory to XMS and / or EMS memory, and make it unavailable as extended memory. Even if so, this function will return the correct amount of extended memory for informational purposes. ;--------------------------------------------------------------------------- !TOPIC 347 @FIELD !NOINDEX !TTY @FIELD[["xxx",]n,string]: Returns the nth field in the string. Like 329@WORD, except it will not scan past multiple delimiters. The first field is numbered 0. If n is negative, fields are returned from the end of the string. The first argument is a list of field separators you want to use; if you don't specify it, only spaces, tabs, and commas are considered to be field separators. If you want to use a double quote as a separator, prefix it with an 086escape character. If the string argument is enclosed in quotation marks, you must enter a list of separators. ;--------------------------------------------------------------------------- !TOPIC 449 @FIELDS !NOINDEX !TTY @FIELDS[["xxx",]string]: Returns the number of fields in the string. Like 330@WORDS, except it will not scan past multiple delimiters (it counts each occurrence of a separator individually to allow processing empty fields in a string). The first argument is a list of field separators you want to use; if you don't specify it, only spaces, tabs, and commas are considered to be field separators. See also 330@WORDS. If you want to use a double quote as a separator, prefix it with an 086escape character. If the string argument is enclosed in quotation marks, you must enter a list of separators. ;--------------------------------------------------------------------------- !TOPIC 269 @FILEAGE !NOINDEX !TTY @FILEAGE[filename[,acw]]: Returns the date and time of the file as a single numeric value. The number can be used to compare the relative ages of two or more files, but can not be used for date and time calculations as it is not returned in identifiable units. The optional second argument selects which date field is returned for files on an LFN drive: a means the last access date, c means the creation date, and w means the last modification (write) date, which is the default. Also see 301@MAKEAGE. ;--------------------------------------------------------------------------- !TOPIC 270 @FILECLOSE !NOINDEX !TTY @FILECLOSE[n]: Closes the file whose handle is n. You cannot close handles 0, 1 or 2. Returns "0" if the file closed OK or "-1" if an error occurs. Be sure to read the cautionary note about file functions under 241Variable Functions. ;--------------------------------------------------------------------------- !TOPIC 271 @FILEDATE !NOINDEX !TTY @FILEDATE[filename[,[acw][,n]]]: Returns the date a file was last modified, in the default country format (mm-dd-yy for the US). The optional second argument selects which date field is returned for files on an LFN drive: a means the last access date, c means the creation date, and w means the last modification (write) date, which is the default. @FILEDATE also takes an optional third argument for the date format: 0 - System default format 1 - U.S. format (mm-dd-yy) 2 - European format (dd-mm-yy) 3 - Japanese format (yy-mm-dd) 4 - ISO 8601 international format (yyyy-mm-dd) 5 - ISO 8601 international format (yyyy-Www-d) week date 6 - ISO 8601 international format (yyyy-ddd) ordinal date The separator used in the returned string depends on the current country settings of the system, except for in the ISO 8601 international format, where it will always by a hyphen ('-') as per spec. ;--------------------------------------------------------------------------- !TOPIC 272 @FILENAME !NOINDEX !TTY @FILETIME[filename[,[acw][,s]]]: Returns the time a file was last modified, in hh:mm format. The optional second argument selects which time field is returned for files on an LFN drive: a means the last access time, c means the creation time, and w means the last modification (write) time, which is the default. Times are normally returned with hours and minutes only; to retrieve seconds as well, add an s as the third argument. The last access time is always returned as 00:00, and without a seconds field, on LFN drives. ;--------------------------------------------------------------------------- !TOPIC 273 @FILEOPEN !NOINDEX !TTY @FILEOPEN[filename, r | w | a, [b|t]]: Opens the file in the specified mode: r(ead), w(rite) or a(ppend), and returns the file handle as an integer. Returns "-1" if the file cannot be opened. The optional third parameter controls whether the file is opened in binary mode (b) or text mode (t). Text mode (the default) should be used to read text using 274@FILEREAD without a length parameter, and to write text using 280@FILEWRITE. Binary mode should be used to read binary data with 478@FILEREADB or @FILEREAD with a length parameter, and to write binary data with 281@FILEWRITEB. To open a file for both reading and writing, open it in append mode, then use 276@FILESEEK to seek to the start of the file (or any other desired location) before performing additional operations. Be sure to read the cautionary note about file functions under 241Variable Functions. ;--------------------------------------------------------------------------- !TOPIC 274 @FILEREAD !NOINDEX !TTY @FILEREAD[n[,length]]: Reads data from the file whose handle is n. Returns "**EOF**" if you attempt to read past the end of the file. If length is not specified @FILEREAD will read until the next CR or LF (end of line) character. If length is specified, @FILEREAD will read length bytes regardless of any end of line characters. If you plan to read text a line at a time, without using length, you should open the file in text mode. If you plan to read binary data using length, you should open the file in binary mode. See 273@FILEOPEN for details on opening the file in the proper mode. Be sure to read the cautionary note about file functions under 241Variable Functions. ;--------------------------------------------------------------------------- !TOPIC 478 @FILEREADB !NOINDEX !TTY @FILEREADB[n,length]: Reads length bytes from the file whose handle is n. Returns "**EOF**" if you attempt to read past the end of the file. The data will be returned as a string of space-separated numeric digits representing the ASCII value of each character. If you plan to read binary data with @FILEREADB you should open the file in binary mode (see 273@FILEOPEN). If you want to read text a line at a time you may want to use the 274@FILEREAD function instead, and open the file in text mode. Be sure to read the cautionary note about file functions under 241Variable Functions. ;--------------------------------------------------------------------------- !TOPIC 275 @FILES !NOINDEX !TTY @FILES[filename,[-nrhsad]]: Returns the number of files that match the filename, which may contain wildcards and include lists. Returns "0" if no files match. The filename must consist of a single file or directory name (with wildcards if desired); to check several directories or filenames use @FILES once for each, and add the results together with 263@EVAL. !TTY The second argument is a list of file attributes. If it is included, only those files matching all the specified attributes are counted. The attributes are: N Normal (no attributes set) S System R Read-only A Archive H Hidden D subDirectory The attributes (other than N) can be combined (for example %@FILES[MYFILE,HS]). You can prefix an attribute with - to mean "everything except files with this attribute." ;--------------------------------------------------------------------------- !TOPIC 276 @FILESEEK !NOINDEX !TTY @FILESEEK[n,offset,start]: Moves the file pointer offset bytes in the file whose handle is n. Returns the new position of the pointer, in bytes from the start of the file. Set start to 0 to seek relative to the beginning of the file, 1 to seek relative to the current file pointer, or 2 to seek relative to the end of the file. The offset value may be negative (seek backward), positive (seek forward), or zero (return current position, but do not change it). Be sure to read the cautionary note about file functions under 241Variable Functions. ;--------------------------------------------------------------------------- !TOPIC 277 @FILESEEKL !NOINDEX !TTY @FILESEEKL[n,line]: Moves the file pointer to the specified line in the file whose handle is n. The first line in the file is numbered 0. Returns the new position of the pointer, in bytes from the start of the file. @FILESEEKL must read each line of the file up to the target line in order to position the pointer, and will therefore cause significant delays if used in a long loop or on a large file. Be sure to read the cautionary note about file functions under 241Variable Functions. ;--------------------------------------------------------------------------- !TOPIC 278 @FILESIZE !NOINDEX !TTY @FILESIZE[filename,b|k|m|g[,a]]: Returns the size of a file, or "-1" if the file does not exist. If the filename includes wildcards or an include list, returns the combined size of all matching files. The optional third argument a (allocated), if used, instructs @FILESIZE to return the amount of space allocated for the file(s) on the disk, rather than the amount of data in the file. Network drives and compressed drives may not always report allocated sizes accurately, depending on the way the network or disk compression software is implemented. ;--------------------------------------------------------------------------- !TOPIC 279 @FILETIME !NOINDEX !TTY @FILETIME[filename[,[acw][,s]]]: Returns the time a file was last modified, in hh:mm format. The optional second argument selects which time field is returned for files on an LFN drive: a means the last access time, c means the creation time, and w means the last modification (write) time, which is the default. Times are normally returned with hours and minutes only; to retrieve seconds as well, add an s as the third argument. The last access time is always returned as 00:00, and without a seconds field, on LFN drives. ;--------------------------------------------------------------------------- !TOPIC 280 @FILEWRITE !NOINDEX !TTY @FILEWRITE[n,text]: Writes a line to the file whose handle is n. Returns the number of bytes written, or "-1" if an error occurred. n must be a handle returned by 273FILEOPEN; or 1 (for standard output) or 2 (for standard error). If you plan to write text a line at a time with @FILEWRITE, you should open the file in text mode (see 273@FILEOPEN). If you want to write binary data you should use 281@FILEWRITEB instead, and open the file in binary mode. Be sure to read the cautionary note about file functions under 241Variable Functions. ;--------------------------------------------------------------------------- !TOPIC 281 @FILEWRITEB !NOINDEX !TTY @FILEWRITEB[n,length,string]: Writes the specified number of bytes from the string to the file whose handle is n. Returns the number of bytes written, or "-1" if an error occurred. If the length argument is -1, @FILEWRITEB will read the string argument as a series of ASCII values to write to the file. For example: echo %@filewriteb[%file,-1,224 242 169] The ASCII code of each byte may be entered in either decimal (1 to 3 decimal digits 0-9), or hexadecimal format ("0x" followed by 1 or 2 hex digits 0-F). If you plan to write binary data with @FILEWRITEB you should open the file in binary mode (see 273@FILEOPEN). If you want to write text a line at a time you may want to use the 280@FILEWRITE function instead, and open the file in text mode. Be sure to read the cautionary note about file functions under 241Variable Functions. ;--------------------------------------------------------------------------- !TOPIC 282 @FINDCLOSE !NOINDEX !TTY @FINDCLOSE[filename]: Signals the end of a 283@FINDFIRST / 284@FINDNEXT sequence. When LFN support is available, you must use this function to release the directory search handle used for @FINDFIRST / @FINDNEXT. ;--------------------------------------------------------------------------- !TOPIC 283 @FINDFIRST !NOINDEX !TTY @FINDFIRST[filename [,-nrhsad]]: Returns the name of the first file that matches the filename, which may contain wildcards and "include lists." The second argument, if included, defines the attributes of the files that will be included in the search. Returns an empty string if no files match. The attributes are: N Normal (no attributes set) S System R Read-only A Archive H Hidden D subDirectory The attributes (other than N) can be combined (for example %@FINDFIRST[MYFILE,HS]). @FINDFIRST will only find a file if all of the attributes match. You can prefix an attribute with - to mean "everything except files with this attribute." @FINDFIRST always skips the "." and ".." entries when processing directory names. To search for additional files after the first which match a wildcard or include list see 284@FINDNEXT. ;--------------------------------------------------------------------------- !TOPIC 284 @FINDNEXT !NOINDEX !TTY @FINDNEXT[[filename [,-nrhsad]]]: Returns the name of the next file that matches the filename passed to 283@FINDFIRST. Returns an empty string when no more files match. @FINDNEXT should only be used after a successful call to @FINDFIRST. The first argument is included for compatibility with previous versions, but is ignored; it can be omitted if the second argument is not used (e.g. %@FINDNEXT[]). The second argument, if included, defines the attributes of the files that will be included in the search. N Normal (no attributes set) S System R Read-only A Archive H Hidden D subDirectory The attributes (other than N) can be combined (for example %@FINDNEXT[MYFILE,HS]). @FINDNEXT will only find a file if all of the attributes match. You can prefix an attribute with - to mean "everything except files with this attribute." @FINDNEXT always skips the "." and ".." entries when processing directory names. When running 4DOS in an LFN environment you must use @FINDCLOSE after 283@FINDFIRST or the last @FINDNEXT to avoid running out of directory search handles. See the notes under 241Variable Functions about quoting returned long filenames. ;--------------------------------------------------------------------------- !TOPIC 726 @FLOOR !NOINDEX !TTY @FLOOR[n]: Returns the value of the smallest integer that is not less than n. ;--------------------------------------------------------------------------- !TOPIC 285 @FORMAT !NOINDEX !TTY @FORMAT[[-][[0]x][.y],string]: Reformats a string, truncating it or padding it with spaces as necessary. If you use the minus [-], the string is left-justified; otherwise, it is right-justified. The x value is the minimum number of characters in the result. The y value is the maximum number of characters in the result. You can combine the options as necessary. For example: "%@format[12,JPSoftware]" returns " JPSoftware" "%@format[.3,JPSoftware]" returns "JPS" @FORMAT will add leading or trailing spaces if necessary to pad the result to the minimum width specified by x. If a leading zero is used before x, the padding will be with 0's instead, for example: "%@format[4,5]" returns " 5" "%@format[04,5]" returns "0005" "%@format[-04,5]" returns "5000" See also the 248@COMMA function, which can make numeric values easier to read by inserting thousands separators. ;--------------------------------------------------------------------------- !TOPIC 286 @FULL !NOINDEX !TTY @FULL[filename]: Returns the fully qualified path and filename of a file. ;--------------------------------------------------------------------------- !TOPIC 348 @FUNCTION !NOINDEX !TTY @FUNCTION[name]: Returns the contents of the specified user-defined function as a string, or a null string if the function doesn't exist. When manipulating strings returned by @FUNCTION you may need to disable certain special characters with the 664SETDOS /X command. Otherwise, command separators, redirection characters, and other similar "punctuation" in the function may be interpreted as part of the current command, rather than part of a simple text string. ;--------------------------------------------------------------------------- !TOPIC 718 @HISTORY !NOINDEX !TTY @HISTORY[x[,y]]: Returns a line or word from the command history. (This function will prove most useful in keystroke aliases). x is the line to retrieve (current line = 0), and y is the specific word (first word = 0) desired within that line. If y is omitted, @HISTORY returns the entire line. See 033Command History and Recall for more information about the command history. ;--------------------------------------------------------------------------- !TOPIC 287 @IF !NOINDEX !TTY @IF[condition,true-value,false-value]: Evaluates the condition and returns a string based on the result. The condition can include any of the tests allowed in the 633IF command. If the condition is true, @IF returns the first result string; if it is false, @IF returns the second string. For example, echo %@if[2 == 2,Correct!,Oops!] displays "Correct!" Be aware that both true-value and false-value will be evaluated even though only one is to be returned! Whether the condition is true or false, both arguments are expanded. For this reason, you should avoid using "action" functions like 335@CLIPW, 264@EXEC, 265@EXECSTR, 273@FILEOPEN, 270@FILECLOSE, 274@FILEREAD, 280@FILEWRITE, 283@FINDFIRST, 340@INIREAD, 341@INIWRITE, 326@UNIQUE, and so on in either the true-value or the false-value. ;--------------------------------------------------------------------------- !TOPIC 288 @INC !NOINDEX !TTY @INC[expression]: Returns the same value as 263@EVAL[(expression) + 1]. That is, it adds one to the value of the expression. Note that the function returns a value that has been incremented; any variable used in the expression will not be changed. To increment the value of a variable, use a command like this: set var=%@inc[%var] See also 252@DEC. ;--------------------------------------------------------------------------- !TOPIC 289 @INDEX !NOINDEX !TTY @INDEX[string1,string2[,n]]: Returns the position of string2 within string1, or "-1" if string2 is not found. The first position in string1 is numbered 0. The optional third parameter n specifies the offset of additional matches. For example, to return the offset of the second match: %@index[abcdeabcde,cd,2] An offset of 0 will return the total number of matches. A negative offset will search from right to left. ;--------------------------------------------------------------------------- !TOPIC 340 @INIREAD !NOINDEX !TTY @INIREAD[filename,section,key]: Returns an entry from the specified .INI file or an empty string if the entry does not exist. For example, %@iniread[c:\4DOS\4DOS.ini,PRIMARY,history] returns the size of the command history if it is specified in the [PRIMARY] section of 4DOS.INI. The filename must be in quotes if it contains whitespace or special characters. The section name and key name are each limited to 255 characters. ;--------------------------------------------------------------------------- !TOPIC 341 @INIWRITE !NOINDEX !TTY @INIWRITE[filename,section,key,value]: Creates or updates an entry in the specified .INI file. For example, %@iniwrite[c:\4dos\4dos.ini,4dos,history,2048] will set the size of the command history to 2,048 bytes the next time 4DOS is started. @INIWRITE returns "0" for success or "-1" for failure. The filename must be in quotes if it contains whitespace or special characters. The section name and key name are each limited to 255 characters ;--------------------------------------------------------------------------- !TOPIC 290 @INSERT !NOINDEX !TTY @INSERT[n,string1,string2]: Inserts string1 into string2 starting at position n. The first position in the string is postion 0. For example, %@insert[1,arm,wing] returns the string "warming". ;--------------------------------------------------------------------------- !TOPIC 291 @INSTR !NOINDEX !TTY @INSTR[start,length,string]: Returns a substring, starting at the position start and continuing for length characters. If the length is omitted, it will default to the remainder of the string. If the length is negative, the start is relative to the right side of the string. The first character in the string is numbered 0; if the length is negative, the last character is numbered 0. For example, %@INSTR[0,2,%_TIME] gets the current time and extracts the hour; %@INSTR[1,-2,%_TIME] extracts the seconds. 321@SUBSTR is an older version of the same function. ;--------------------------------------------------------------------------- !TOPIC 292 @INT !NOINDEX !TTY @INT[n]: Returns the integer part of the number n. ;--------------------------------------------------------------------------- !TOPIC 508 @ISALNUM !NOINDEX !TTY @ISALNUM[string]: Returns "1" if string is entirely composed of alphabetic (a-z, A-Z) and/or numeric (0-9) characters; "0" otherwise. ;--------------------------------------------------------------------------- !TOPIC 509 @ISALPHA !NOINDEX !TTY @ISALPHA[string]: Returns "1" if string is entirely composed of alphabetic (a-z, A-Z) characters; "0" otherwise. ;--------------------------------------------------------------------------- !TOPIC 510 @ISASCII !NOINDEX !TTY @ISASCII[string]: Returns "1" if string is entirely composed of 7-bit ASCII characters (0-7Fh); "0" otherwise. ;--------------------------------------------------------------------------- !TOPIC 528 @ISCNTRL !NOINDEX !TTY @ISCNTRL[string]: Returns "1" if string is entirely composed of ASCII control characters (0-1Fh or 7Fh); "0" otherwise. ;--------------------------------------------------------------------------- !TOPIC 529 @ISDIGIT !NOINDEX !TTY @ISDIGIT[string]: Returns "1" if string is entirely composed of decimal digits (0-9); "0" otherwise. ;--------------------------------------------------------------------------- !TOPIC 828 @ISLOWER !NOINDEX !TTY @ISLOWER[string]: Returns "1" if string is entirely composed of lower-case letters (a-z); "0" otherwise. ;--------------------------------------------------------------------------- !TOPIC 458 @ISODOWI !NOINDEX !TTY @ISODOWI[date]: Returns the day of the week for the specified date as an integer (1 = Monday, 2 = Tuesday, ... , 6 = Saturday, 7 = Sunday), pursuant to ISO 8601. The date may be in either the local date format, or in ISO format with a four-digit year; see 344date formats for more information. ;--------------------------------------------------------------------------- !TOPIC 459 @ISOWEEK !NOINDEX !TTY @ISOWEEK[date] is the week of the year (1 to 53), pursuant to ISO 8601. Week 1 is the one that includes the first Thursday of the year, or equivalently, the week which includes 4th of January. It is possible that a January week is 52 or 53, or a December week is 1. This means that, according to ISO 8601, it belongs to the previous or the following calendar year, respectively. The date may be in either the local date format, or in ISO format with a four-digit year; see 344date formats for more information. ;--------------------------------------------------------------------------- !TOPIC 721 @ISOWYEAR !NOINDEX !TTY @ISOWYEAR[date] is the year of the ISO 8601 week date. It may not be the calendar year of the entered date but the previous or the following one. This means that, according to ISO 8601, the week of the entered date belongs to the previous or the following calendar year, respectively. The date may be in either the local date format, or in ISO format with a four-digit year; see 344date formats for more information. ;--------------------------------------------------------------------------- !TOPIC 530 @ISPRINT !NOINDEX !TTY @ISPRINT[string]: Returns "1" if string is entirely composed of printable characters; "0" otherwise. ;--------------------------------------------------------------------------- !TOPIC 558 @ISPUNCT !NOINDEX !TTY @ISPUNCT[string]: Returns "1" if string is entirely composed of punctuation characters, i.e. printable characters which are not alphanumeric or space; "0" otherwise. ;--------------------------------------------------------------------------- !TOPIC 559 @ISSPACE !NOINDEX !TTY @ISSPACE[string]: Returns "1" if string is entirely composed of white space characters (9-0Dh or 20h); "0" otherwise. ;--------------------------------------------------------------------------- !TOPIC 829 @ISUPPER !NOINDEX !TTY @ISUPPER[string]: Returns "1" if string is entirely composed of upper-case letters (A-Z); "0" otherwise. ;--------------------------------------------------------------------------- !TOPIC 560 @ISXDIGIT !NOINDEX !TTY @ISXDIGIT[string]: Returns "1" if string is entirely composed of hexadecimal digits (0-9, A-F, a-f); "0" otherwise. ;--------------------------------------------------------------------------- !TOPIC 293 @LABEL !NOINDEX !TTY @LABEL[d:]: Returns the volume label of the specified disk drive. ;--------------------------------------------------------------------------- !TOPIC 730 @LCS !NOINDEX !TTY @LCS[string1,string2]: Returns the Longest Common Subsequence in string1 and string2. For example, for the strings "XMJYAUZ" and "MZJAWXU", it is "MJAU". ;--------------------------------------------------------------------------- !TOPIC 294 @LEFT !NOINDEX !TTY @LEFT[n,string]: Returns the leftmost n characters from the string. If n is greater than the length of the string, returns the entire string. For example, %@left[2,jpsoft] returns the string "jp". If n is negative, returns all but the rightmost n characters. ;--------------------------------------------------------------------------- !TOPIC 295 @LEN !NOINDEX !TTY @LEN[string]: Returns the length of a string. ;--------------------------------------------------------------------------- !TOPIC 296 @LFN !NOINDEX !TTY @LFN[filename]: Returns the long filename for a short ("8.3") filename. The filename may contain any valid filename element including drive letter, path, filename and extension; the entire name including all intermediate paths will be returned in long name format. Be sure to read the notes under 241Variable Functions about quoting returned long filenames. ;--------------------------------------------------------------------------- !TOPIC 297 @LINE !NOINDEX !TTY @LINE[filename,n]: Returns line n from the specified file. The first line in the file is numbered 0. "**EOF**" is returned for all line numbers beyond the end of the file. @LINE works with files having lines of no more than 511 characters; longer lines will not be counted accurately. The @LINE function must read each line of the file to find the line you request, and will therefore cause significant delays if used in a long loop or on a large file. For a more effective method of processing each line of a file in sequence use the FOR command, or 273@FILEOPEN and a sequence of @FILEREADs. You can retrieve input from standard input if you specify CON as the filename. If you are 051redirecting input to @LINE using this feature, you must use 085command grouping or the redirection will not work properly (you can 052pipe to @LINE without a command group; this restriction applies only to input redirection). For example: (echo %@line[con,0]) < myfile.dat ;--------------------------------------------------------------------------- !TOPIC 298 @LINES !NOINDEX !TTY @LINES[filename]: Returns the line number of the last line in the file, or "-1" if the file is empty. The first line in the file is numbered 0, so (for example) @LINES will return 0 for a file containing one line. To get the actual number of lines, use %@INC[%@LINES[filename]]. @LINES works with files having lines of no more than 511 characters; longer lines will not be counted accurately. @LINES must read each line of the file in order to count it, and will therefore cause significant delays if used in a long loop or on a large file. ;--------------------------------------------------------------------------- !TOPIC 299 @LOWER !NOINDEX !TTY @LOWER[string]: Returns the string converted to lower case. ;--------------------------------------------------------------------------- !TOPIC 406 @LTRIM !NOINDEX !TTY @LTRIM[chars,string]: Returns string with all the leading characters in chars removed. For example, %@LTRIM[IJMPX,JP Software] returns " Software". The test is case sensitive. To include a comma in the chars string, enclose the entire first argument in double quotes. @LTRIM will remove the quotes before processing the string. ;--------------------------------------------------------------------------- !TOPIC 301 @MAKEAGE !NOINDEX !TTY @MAKEAGE[date[,time]]: Returns the date and time (if included) as a single value in the same format as 269@FILEAGE. Can be used to compare the time stamp of a file with a specific date and time, for example: if %@fileage[myfile] lt %@makeage[1/1/85] echo OLD! The value returned by @MAKEAGE can be used for comparisons, but can not be used for date and time calculations because it is not in identifiable units. The @MAKEAGE value changes every two seconds, so, for example, %@MAKEAGE[01-06-2003,12:00:00] and %@MAKEAGE[01-06-2003,12:00:01] will return the same result. The date may be in either the local date format, or in ISO format with a four-digit year; see 344date formats for more information. The time must be in 24-hour format; "am" and "pm" cannot be used. If the time is not specified, it defaults to midnight. ;--------------------------------------------------------------------------- !TOPIC 302 @MAKEDATE !NOINDEX !TTY @MAKEDATE[n[,format]]: Returns a date (formatted according to the current country settings). n is the integer number of days since 1980-01-01. This is the inverse of 250@DATE. @MAKEDATE takes an optional second argument for the date format: 0 - system default format 1 - U.S. format (mm-dd-yy) 2 - European format (dd-mm-yy) 3 - Japanese format (yy-mm-dd) 4 - ISO 8601 international format (yyyy-mm-dd) 5 - ISO 8601 international format (yyyy-Www-d) week date 6 - ISO 8601 international format (yyyy-ddd) ordinal date The separator used in the return string depends on the current country settings of the system, except for in the ISO 8601 international format, where it will always by a hyphen ('-') as per spec. ;--------------------------------------------------------------------------- !TOPIC 303 @MAKETIME !NOINDEX !TTY @MAKETIME[n]: Returns a time (formatted according to the current country settings). n is the number of seconds since midnight. This is the inverse of 322@TIME. ;--------------------------------------------------------------------------- !TOPIC 304 @MASTER !NOINDEX !TTY @MASTER[varname]: Returns the value of a variable from the master environment. ;--------------------------------------------------------------------------- !TOPIC 342 @MAX !NOINDEX !TTY @MAX[a,b,c,...]: Returns the largest integer in the list. ;--------------------------------------------------------------------------- !TOPIC 402 @MD5 !NOINDEX !TTY @MD5[filename]: Returns the 32 hexadecimal digit MD5 hash of the contents of the specified file, or "-1" if the file doesn't exist. The RSA Data Security Inc. MD5 message-digest algorithm described in RFC 1321 is used to compute the hash value. ;--------------------------------------------------------------------------- !TOPIC 343 @MIN !NOINDEX !TTY @MIN[a,b,c,...]: Returns the smallest integer in the list. ;--------------------------------------------------------------------------- !TOPIC 305 @MONTH !NOINDEX !TTY @MONTH[date]: Returns the month number for the specified date (1-12). The date may be in either the local date format, or in ISO format with a four-digit year; see 344date formats for more information. ;--------------------------------------------------------------------------- !TOPIC 369 @MONTHF !NOINDEX !TTY @MONTHF[date]: Returns the full month name for the specified date ("January, "February", etc.). The date may be in either the local date format, or in ISO format with a four-digit year; see 344date formats for more information. ;--------------------------------------------------------------------------- !TOPIC 306 @NAME !NOINDEX !TTY @NAME[filename]: Returns the base name of a file, without the path or extension. See the notes under 241Variable Functions about quoting returned long filenames. ;--------------------------------------------------------------------------- !TOPIC 307 @NUMERIC !NOINDEX !TTY @NUMERIC[string]: Returns "1" if string is composed entirely of digits (0 to 9), signs (+ or -), and the thousands and decimals separators. Otherwise, returns "0". If the string begins with a decimal separator it is not considered numeric unless the next character is a digit, and there are no more decimal separators within the string. For example, ".07" is numeric, but ".a" and ".07.50" are not. ;--------------------------------------------------------------------------- !TOPIC 308 @PATH !NOINDEX !TTY @PATH[filename]: Returns the path from a filename, including the drive letter and a trailing backslash but not including the base name or extension. See the notes under 241Variable Functions about quoting returned long filenames. ;--------------------------------------------------------------------------- !TOPIC 503 @QUOTE !NOINDEX !TTY @QUOTE[filename]: Returns a double quoted argument, if it contains any whitespace characters. ;--------------------------------------------------------------------------- !TOPIC 309 @RANDOM !NOINDEX !TTY @RANDOM[min, max]: Returns a "pseudo-random" value between min and max, inclusive. Min, max, and the returned value are all integers. The pseudo-random number generator is initialized from the system clock the first time it is used after 4DOS starts, so it will produce a different sequence of random numbers each time you use it. It can be called up to 115,792,089,237,316,195,423,570,985,008,687,907,853,269,984,665,640,564,039, 457,584,007,913,129,639,935 (2^256-1) times before repeating the sequence of pseudo-random numbers it produces. The Xorshift7 generator proposed in the paper "On the Xorshift Random Number Generators" by Francois Panneton and Pierre L'Ecuyer is used to generate the pseudo-random numbers. ;--------------------------------------------------------------------------- !TOPIC 310 @READSCR !NOINDEX !TTY @READSCR[row,col,length]: Returns the text displayed on the screen at the specified location. The upper left corner of the screen is location 0,0. The row and col can be specified as an offset from the current cursor location by preceding either value with a [+] or [-]. For example: %@readscr[-2,+2,10] returns 10 characters from the screen, starting 2 rows above and 2 columns to the right of the current cursor position. You can also specify the row and column as offsets from the current cursor position. Begin the value with a plus sign [+] to read the screen the specified number of rows below (or columns to the right of) the current position, or with a minus sign [-] to read the screen above (or to the left of) the current position. ;--------------------------------------------------------------------------- !TOPIC 311 @READY !NOINDEX !TTY @READY[d:]: Returns "1" if the specified drive is ready; otherwise returns "0". Warning: Some CD-ROM drivers may report an incorrect status to 4DOS. ;--------------------------------------------------------------------------- !TOPIC 312 @REMOTE !NOINDEX !TTY @REMOTE[d:]: Returns "1" if the specified drive is a remote (network) drive; otherwise returns "0". ;--------------------------------------------------------------------------- !TOPIC 313 @REMOVABLE !NOINDEX !TTY @REMOVABLE[d:]: Returns "1" if the specified drive is removable (i.e., a floppy disk or removable hard disk); otherwise returns "0". ;--------------------------------------------------------------------------- !TOPIC 314 @REPEAT !NOINDEX !TTY @REPEAT[c,n]: Returns the character c repeated n times. ;--------------------------------------------------------------------------- !TOPIC 315 @REPLACE !NOINDEX !TTY @REPLACE[string1,string2,text]: Replaces all occurrences of string1 in the text string with string2. For example, %@replace[w,ch,warming] returns the string "charming". The search is case-sensitive. ;--------------------------------------------------------------------------- !TOPIC 729 @REVERSE !NOINDEX !TTY @REVERSE[string]: Reverses the order of the characters in string. ;--------------------------------------------------------------------------- !TOPIC 316 @RIGHT !NOINDEX !TTY @RIGHT[n,string]: Returns the rightmost n characters from the string. If n is greater than the length of the string, returns the entire string. For example, %@right[4,jpsoft] returns the string "soft". If n is negative, returns all but the leftmost n characters. ;--------------------------------------------------------------------------- !TOPIC 407 @RTRIM !NOINDEX !TTY @RTRIM[chars,string]: Returns string with all the trailing characters in chars removed. For example, %@RTRIM[958NPTX,Windows XP] returns "Windows ". The test is case sensitive. To include a comma in the chars string, enclose the entire first argument in double quotes. @LTRIM will remove the quotes before processing the string. ;--------------------------------------------------------------------------- !TOPIC 317 @SEARCH !NOINDEX !TTY @SEARCH[filename[,path]]: Searches for the filename using the 138PATH environment variable or the specified path, appending an extension if one isn't specified. Returns the fully-expanded name of the file including drive, path, base name, and extension, or an empty string if a matching file is not found. If wildcards are used in the filename, @SEARCH will search for the first file that matches the wildcard specification, and return the drive and path for that file plus the wildcard filename (e.g., E:\UTIL\*.COM). ;--------------------------------------------------------------------------- !TOPIC 318 @SELECT !NOINDEX !TTY @SELECT[filename,top,left,bottom,right,title[,1]]: Pops up a selection window with the lines from the specified file, allowing you to display menus or other selection lists from within a batch file. You can move through the selection window with standard popup window navigation keystrokes, including character matching (see 894Popup Windows for details; to change the navigation keys see 481Key Mapping Directives). @SELECT returns the text of the line the scrollbar is on if you press Enter, or an empty string if you press Esc. The file size is limited only by available memory. To select from lines passed through input redirection or a pipe, use CON as the filename. To select from lines on the Windows clipboard, use CLIP: as the filename. If you use the optional 1 argument after the window title, the list will be sorted alphabetically. ;--------------------------------------------------------------------------- !TOPIC 358 @SERIAL !NOINDEX !TTY @SERIAL[d:]: Returns the serial number of the specified disk drive (in hex, i.e.: ABCD:1234). ;--------------------------------------------------------------------------- !TOPIC 319 @SFN !NOINDEX !TTY @SFN[filename]: Returns the fully expanded short ("8.3") filename for a long filename. The filename may contain any valid filename element including drive letter, path, filename and extension; the entire name including all intermediate paths will be returned in short name format. The filename should not be quoted. ;--------------------------------------------------------------------------- !TOPIC 403 @SHA1 !NOINDEX !TTY @SHA1[filename]: Returns the 40 hexadecimal digit SHA1 hash of the contents of the specified file, or "-1" if the file doesn't exist. The Secure Hash Algorithm 1 (SHA1) described in RFC 4634 is used to compute the hash value. ;--------------------------------------------------------------------------- !TOPIC 733 @SIMILAR !NOINDEX !TTY @SIMILAR[string1,string2]: Returns a percentage value (0 - 100) reflecting the similarity between string1 and string2. 0 means the two strings have nothing in common; 100 means the strings are identical. Using the longer string as the first parameter usually results in lower similarity values and using the shorter results in higher values. The algorithm is the same as in the PHP similar_text() function and was derived from the paper "Decision Graphs - An Extension of Decision Trees" by Jonathan Oliver. ;--------------------------------------------------------------------------- !TOPIC 320 @STRIP !NOINDEX !TTY @STRIP[chars,string]: Removes the characters in chars from the string and returns the result. For example, %@STRIP[AaEe,All Good Men] returns "ll Good Mn". The test is case sensitive. To include a comma in the chars string, enclose the entire first argument in double quotes. @STRIP will remove the quotes before processing the string. ;--------------------------------------------------------------------------- !TOPIC 321 @SUBSTR !NOINDEX !TTY @SUBSTR[string,start,length]: This is an older, deprecated version of 291@INSTR. The string parameter is at the start of the @SUBSTR argument list. If the string includes commas, it must be quoted with quote marks ["] or back-quotes [`], or else the commas must be escaped using the 086escape character. The quotes do count in calculating the position of the substring. @INSTR, which has the string argument last, does not have this limitation. ;--------------------------------------------------------------------------- !TOPIC 722 @SUBST !NOINDEX !TTY @SUBST[n,str1, str2]: Substitutes str1 starting at position n in str2. ;--------------------------------------------------------------------------- !TOPIC 322 @TIME !NOINDEX !TTY @TIME[time]: Returns the number of seconds since midnight for the specified time. The time must be in 24-hour format; "am" and "pm" cannot be used. ;--------------------------------------------------------------------------- !TOPIC 323 @TIMER !NOINDEX !TTY @TIMER[n]: Returns the current split time for a stopwatch started with the 673TIMER command. The value of n specifies the timer to read and can be 1, 2, or 3. ;--------------------------------------------------------------------------- !TOPIC 324 @TRIM !NOINDEX !TTY @TRIM[string]: Returns the string with the leading and trailing white space (space and tab characters) removed. ;--------------------------------------------------------------------------- !TOPIC 325 @TRUENAME !NOINDEX !TTY @TRUENAME[filename]: Returns the fully-expanded name for a file. ;--------------------------------------------------------------------------- !TOPIC 408 @TRUNCATE !NOINDEX !TTY @TRUNCATE[n]: Truncate the file opened for write access by 273@FILEOPEN at the current position of the file pointer, where n is the value returned by 273@FILEOPEN. Be sure to read the cautionary note about file functions under 241Variable Functions. ;--------------------------------------------------------------------------- !TOPIC 326 @UNIQUE !NOINDEX !TTY @UNIQUE[d:\path]: Creates a zero-length file with a unique name in the specified directory, and returns the full name and path. If no path is specified, the file will be created in the current directory. The file name will be FAT-compatible (8 character name and 3 character extension) regardless of whether the file is created on a FAT or LFN drive. This function allows you to create a temporary file without overwriting an existing file. ;--------------------------------------------------------------------------- !TOPIC 504 @UNQUOTE !NOINDEX !TTY @UNQUOTE[filename]: Returns the argument with all double quotes removed. ;--------------------------------------------------------------------------- !TOPIC 723 @UNQUOTES !NOINDEX !TTY @UNQUOTES[filename]: Returns the argument with leading and trailing double quotes removed. ;--------------------------------------------------------------------------- !TOPIC 327 @UPPER !NOINDEX !TTY @UPPER[string]: Returns the string converted to upper case. ;--------------------------------------------------------------------------- !TOPIC 328 @WILD !NOINDEX !TTY @WILD[string1,string2]: Performs a comparison of the two strings, and returns "1" if they match or "0" if they don't match. The second argument, string2, may contain wildcards or extended wildcards; the first argument, string1, may not. The test is not case sensitive. The following example tests whether the \UTIL directory (or any directory that begins with the characters UTIL) is included in the 138PATH: if %@wild[%path,*\UTIL*] == 1 command ;--------------------------------------------------------------------------- !TOPIC 329 @WORD !NOINDEX !TTY @WORD[["xxx",]n,string]: Returns the nth word in the string. The first word is numbered 0. If n is negative, words are returned from the end of the string. The first argument is a list of word separators you want to use; if you don't specify it, only spaces, tabs, and commas are considered to be word separators. See also 347@FIELD. If you want to use a double quote as a separator, prefix it with an 086escape character. If the string argument is enclosed in quotation marks, you must enter a list of separators. For example: %@WORD[2,NOW IS THE TIME] returns "THE" %@WORD[-0,NOW IS THE TIME] returns "TIME" %@WORD[-2,NOW IS THE TIME] returns "IS" %@WORD["=",1,2 + 2=4] returns "4" ;--------------------------------------------------------------------------- !TOPIC 330 @WORDS !NOINDEX !TTY @WORDS[["xxx",]string]: Returns the number of words in the string. The first argument is a list of word separators you want to use; if you don't specify it, only spaces, tabs, and commas are considered to be word separators. See also 449@FIELDS. If you want to use a double quote as a separator, prefix it with an 086escape character. If the string argument is enclosed in quotation marks, you must enter a list of separators. ;--------------------------------------------------------------------------- !TOPIC 331 @XMS !NOINDEX !TTY @XMS[b|k|m]: Returns the amount of free XMS memory. ;--------------------------------------------------------------------------- !TOPIC 332 @YEAR !NOINDEX !TTY @YEAR[date]: Returns the year for the specified date. The date may be in either the local date format, or in ISO format with a four-digit year; see 344date formats for more information. ;--------------------------------------------------------------------------- !TOPIC 351 4DOS.INI !NOINDEX Part of the power of 4DOS is its flexibility. You can alter its configuration to match your style of computing. Most of the configuration of 4DOS is controlled through a file of initialization information called 4DOS.INI, which is discussed in the following sections: !NOWRAP !INDENT 5 5 5 5 353Modifying the .INI File 354Using the .INI File 355.INI File Sections 356.INI File Directives 357.INI File Examples !INDENT 0 !WRAP We also discuss many ways of configuring 4DOS in other sections of the help, for example: !INDENT 7 5 5 5 * With 101aliases you can set default options for internal commands and create new commands. * With 082executable extensions you can associate data files with the applications you use to open them. * With the 137FILECOMPLETION environment variable and the 429FileCompletion .INI directive you can customize filename completion to match the command you are working with. * With the 133COLORDIR environment variable and the 463ColorDir .INI directive you can set the colors used by the 612DIR and 662SELECT commands. * With the 664SETDOS command, you can change some aspects of 4DOS's operation "on the fly." !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 352 Starting 4DOS !NOINDEX 4DOS is started as the primary shell by vDosPlus, it can also be started as a secondary shell by another program or by running a copy of 4DOS directly from the command line. Exit Codes If you start 4DOS from another program as a temporary process (e.g. to run a batch file or internal command), it will return a numeric code to the other program when it is finished. This code is usually used to indicate whether the operation performed was successful or not, with 0 often indicating success and a non-zero value indicating a failure or other numeric result. The exit code is normally the numeric exit code from the last external command. Internal commands do not set the exit code. If you enter an unknown command the exit code will be 2, which is the internal 4DOS unknown command error number. You can also use the 624EXIT n command to explicitly set the exit code. If you do, this will override the rules above, and set the return code to the value in your EXIT command. The normal rules described above may not return a code that indicates the success or failure of the specific operation that concerns you. Therefore, if you need to rely on the exit code from 4DOS, we recommend that you use a batch file or alias to create the exit code you want, and then set the code explicitly with EXIT n. ;--------------------------------------------------------------------------- !TOPIC 353 Modifying the .INI File !NOINDEX Note: in vDosPlus the 4DOS.INI has to be copied to the same folder as the autoexec.txt and config.txt files. You can create, add to, and modify the .INI file in two ways: with the OPTION command and by editing the file with any ASCII editor. OPTION displays a set of dialogs which allow you to modify the settings that are used most often. When you exit from the dialogs, you can select the Save button to save your changes in the .INI file for use in the current session and all future sessions, select the Use or OK button to use your changes in the current session only, or discard the changes you have made by selecting the Cancel button. See the 648OPTION command for additional details. Changes you make in the Startup section of the OPTION dialogs will only take effect the next time you start vDosPlus. OPTION handles most standard .INI file settings. A few more advanced settings, as well as all settings that affect the interpretation of keystrokes, cannot be modified with OPTION and must be inserted or modified manually. For more details see the 648OPTION command. You can also create, add to, and edit the .INI file "manually" with any ASCII text editor. 4DOS reads its .INI file when it starts, and configures itself accordingly. The .INI file is not re-read when you change it manually. For manual changes to take effect, you must restart vDosPlus. If you edit the .INI file manually, make sure you save the file in ASCII format. Each item that you can include in the .INI file has a default value. You only need to include entries in the file for settings that you want to change from their default values. Format Most lines in the .INI file consist of a one-word directive, an equal sign [=], and a value. For example, in the following line, the word "Environment" is the directive and "2048" is the value: Environment = 2048 Any spaces before or after the equal sign are ignored. If you have a long string to enter in the .INI file (for example, for the 463ColorDir directive), you must enter it all on one line. Strings cannot be "continued" to a second line. Each line may be up to 511 characters long. The format of the value part of a directive line depends on the individual directive. It may be a numeric value, a single character, a choice (like "Yes" or "No"), a color setting, a key name, a path, a filename, or a text string. The value begins with the first non-blank character after the equal sign and ends at the end of the line or the beginning of a comment. Blank lines are ignored in the .INI file and can be used to separate groups of directives. You can place comments in the file by beginning a line with a semicolon [;]. You can also place comments at the end of any line except one containing a text string value. To do so, enter at least one space or tab after the value, a semicolon, and your comment, like this: Environment = 2048 ; set standard environment size If you try to place a comment at the end of a string value, the comment will become part of the string and will probably cause an error. If you use the 648OPTION dialogs to modify the .INI file, comments on lines modified from within the dialogs will not be preserved when the new lines are saved. To be sure .INI file comments are preserved, put them on separate lines in the file. If you want to include the text of one .INI file within another (for example, if you have a set of common directives used by several JP Software products), see the 567Include directive. ;--------------------------------------------------------------------------- !TOPIC 354 Using the .INI File !NOINDEX When 4DOS is loaded as a secondary shell, it does not search for the .INI file. Instead, it retrieves the primary shell's .INI file data, processes the [Secondary] section of the original .INI file if necessary, and then processes any "@d:\path\inifile" option on the secondary shell command line. You can override this behavior with the 571NextINIFile directive. Secondary shells automatically inherit the configuration settings currently in effect in the previous shell. If values have been changed by 664SETDOS since the primary shell started, the current values will be passed to the secondary shell. If the previous shell's .INI file had a [Secondary] section, it will then be read and processed (see 355.INI File Sections). If not, the previous shell's settings will remain in effect. For example, you might set BatchEcho to Yes in the .INI file, to enable batch file echo. If you then use 664SETDOS /V0 to turn off batch file echoing in the primary shell, then any secondary shells will inherit the SETDOS setting, rather than the original value from the .INI file; i.e., batch files in the secondary shell will default to no echo. If you want to force secondary shells to start with a specific value for a particular directive, regardless of any changes made with SETDOS in a previous shell, repeat the directive in the [Secondary] section of the .INI file. When you start a secondary shell you can specify an alternate location and name for 4DOS.INI by passing the "@d:\path\inifile" option to 4DOS as a command-line parameter. In this case, the configuration settings in the alternate 4DOS.INI file will supersede any settings inherited from the previous shell. Any values which are not explicitly set in the alternate file will retain the value they had in the previous shell. The 664SETDOS command can override several of the .INI file directives. For example, the cursor shape used by 4DOS can be adjusted either with the 419CursorIns and 420CursorOver directives or the SETDOS /S command. The correspondence between SETDOS options and .INI directives is noted with each directive, and under each option of the SETDOS command. When 4DOS detects an error while processing the .INI file, it displays an error message and prompts you to press a key to continue processing the file. This allows you to note any errors before the startup process continues. The directive in error will retain its previous or default value. Only the most catastrophic errors (like a disk read failure) will terminate processing of the remainder of the .INI file. If you don't want a pause after each error, use a "PauseOnError = No" directive at the beginning of the .INI file. If you need to test different values for an .INI directive without repeatedly editing the .INI file, use the 648OPTION command or see the 383INIQuery directive. ;--------------------------------------------------------------------------- !TOPIC 355 .INI File Sections !NOINDEX The .INI file has three possible sections: the first or global section, named [4DOS]; the [Primary] section; and the [Secondary] section. Each section is identified by the section name in square brackets on a line by itself. Directives in the global section are effective in all shells. In most cases, this is the only section you will need. Any changes you make to the .INI file with the 648OPTION command are stored in the global section. The [Primary] and [Secondary] sections include directives that are used only in primary and secondary shells, respectively. You don't need to set up these sections unless you want different directives for primary and secondary shells. Directives in the [Primary] section are used for the first or primary shell. The values are passed automatically to all secondary shells, unless overridden by a directive with the same name in the [Secondary] section. Directives in the [Secondary] section are used in secondary shells only, and override any corresponding primary shell settings. For example, these lines in the .INI file: [Primary] ScreenRows = 25 [Secondary] ScreenRows = 50 mean to assume that you have 25 rows on the screen in the primary shell and 50 lines in all secondary shells. Sections that begin with any name other than [4DOS], [Primary], or [Secondary] are ignored. ;--------------------------------------------------------------------------- !TOPIC 356 .INI File Directives !NOINDEX For information on specific directives, see the separate topic for each type of directive. !NOWRAP !INDENT 5 5 5 5 371Initialization Directives 410Configuration Directives 448Color Directives 481Key Mapping Directives 550Advanced Directives !INDENT 0 !WRAP These topics list the directives, with a one-line description of each, and a cross-reference which selects a full screen help topic on that directive. A few of the directives are simple enough that the one-line description is sufficient, but in most cases you should check for any additional information in the cross-reference topic if you are not already familiar with the directive. You can also obtain help on most directives with a HELP directive command at the prompt. There are 8 types of directives in the .INI file. The different types of directives are shown in the descriptions as follows: !INDENT 7 5 5 5 * Name = nnnn (1234): This directive takes a numeric value which replaces the "nnnn." The default value is shown in parentheses. * Name = c (X): This directive accepts a single character as its value. The default character is shown in parentheses. You must type in the actual character; you cannot use a key name. * Name = CHOICE1 | Choice2 | ... : This directive takes a choice value. The possible choices are listed, separated by vertical bars. The default value is shown in all upper case letters in the directive description, but in your file any of the choices can be entered in upper case or lower case. For example, if the choices were shown as "YES | No" then "YES" is the default. * Name = Color: This directive takes a color specification. See 892Colors and Color Names for the format of color names. * Name = Key (Default): This directive takes a key specification. See 893Keys and Key Names for the format of key names. * Name = Path: This directive takes a path specification, but not a filename. The value should include both a drive and path (e.g., C:\4DOS) to avoid any possible ambiguities. A trailing backslash [\] at the end of the path name is acceptable but not required. Any default path is described in the text. * Name = File: This directive takes a filename. We recommend that you use a full filename including the drive letter and path to avoid any possible ambiguities. Any default filename is described in the text. * Name = String: This directive takes a string in the format shown. The text describes the default value and any additional requirements for formatting the string correctly. No comments are allowed. !INDENT 0 4DOS contains a fixed-length area for storing strings entered in the .INI file, including file names, paths, and other strings. This area is large and is unlikely to overflow; if it does, you will receive an error message. If this occurs, reduce the complexity of your .INI file. ;--------------------------------------------------------------------------- !TOPIC 357 .INI File Examples !NOINDEX The following examples will give you an idea of the types of things that can be done with the .INI file. The comments on each directive explain what it does. First, a very simple example that just sets up swapping and environment size, leaving everything else at its default value: [4DOS] InstallPath = c:\4dos ; Installation directory Swapping = ems, c:\ ; try EMS, then C: root Environment = 1024 ; set environment size Here's an example for a system which supports Upper Memory blocks (UMBs). Several settings take advantage of UMBs, and others modify the 4DOS configuration to match the user's preferences. Note that the comment for the 391Swapping directive is on separate lines before the directive itself, as no comments are allowed in string directives: [4DOS] InstallPath = c:\4dos ; Installation directory Environment = 3072 ; expand environment to 3KB Alias = 6144 ; expand aliases to 6KB LocalHistory = No ; use a global history ; for swapping try XMS, then RAM disk H:, ; then hard disk C: Swapping = xms, h:\, c:\ UMBLoad = Yes ; resident part of 4DOS in UMB UMBEnvironment = Yes ; master environment in UMB UMBHistory = Yes ; global history in UMB BatchEcho = No ; default is ECHO OFF EditMode = Insert ; editor in insert mode CursorOver = 100 ; overstrike cursor 100% CursorIns = 10 ; insert cursor 10% ;--------------------------------------------------------------------------- !TOPIC 371 Initialization Directives !NOINDEX  3724StartPath Path for 4START and 4EXIT 373Alias Size of alias list 374AutoExecParms Parameters for AUTOEXEC.BAT 375AutoExecPath Path and optional file name for AUTOEXEC.BAT 376DirHistory Size of directory history list 377Environment Size of environment 378EnvFree Required free space in environment 379Function Size of function list  380HelpOptions Options for help system 381HelpPath Path to 4HELP.EXE (obsolete) 400HistLogOn Default history logging state 382History Size of history list 383INIQuery Query for each line in 4DOS.INI  384InstallPath Location of 4DOS files 385LocalAliases Local vs. global aliases 386LocalDirHistory Local vs. global directory history 387LocalFunctions Local vs. global functions 388LocalHistory Local vs. global history 399LogOn Default command logging state 389PauseOnError Pause on errors in 4DOS.INI  390REXXPath Set path to PC DOS 7.0 / 2000 REXX interpreter 391Swapping Swapping type(s)  392TreePath Path for directory database 393UMBAlias Load global aliases in UMB 394UMBDirHistory Load global directory history in UMB 395UMBEnvironment Load master environment in UMB 396UMBFunction Load global functions in UMB 397UMBHistory Load history in UMB 398UMBLoad Load resident part of 4DOS in UMB Directives marked with a  may be dynamically changed at the command line using the 648OPTION //optname=value syntax. If a directive does not have this mark, it may not be meaningful to change it after 4DOS has started. Or there may be some simpler way to change it, e.g. options to the 643LOG or 668SWAPPING commands. When starting a secondary copy of 4DOS, remember that you can pass directives on its command line using the //iniline syntax; see 352Starting 4DOS for details. Nearly all the initialization directives can be easily adjusted using the interactive 648OPTION dialogs. The only exceptions are the obsolete 381HelpPath, and 383INIQuery and 389PauseOnError, used to debug .INI files. ;--------------------------------------------------------------------------- !TOPIC 400 HistLogOn !NOINDEX !TTY HistLogOn = Yes | NO: Default history logging state (see 643LOG /H.) ;--------------------------------------------------------------------------- !TOPIC 399 LogOn !NOINDEX !TTY LogOn = Yes | NO: Default command logging state (see 643LOG.) ;--------------------------------------------------------------------------- !TOPIC 372 4StartPath !NOINDEX !TTY 4StartPath = Path: Sets the drive and directory where the 4START and 4EXIT batch files (if any) are located. ;--------------------------------------------------------------------------- !TOPIC 373 Alias !NOINDEX !TTY Alias = nnnn (1024): Sets the amount of memory in bytes allocated for the alias list. The allowable range of values is 256 to 32767 bytes. If you use a global alias list (see 595ALIAS), the Alias value is ignored in all shells except the shell which first establishes the global list. ;--------------------------------------------------------------------------- !TOPIC 374 AutoExecParms !NOINDEX !TTY AutoExecParms = String: Sets the parameter or parameters to be passed to 109AUTOEXEC.BAT. The parameters will be available in your AUTOEXEC.BAT file as %1, %2, etc. ;--------------------------------------------------------------------------- !TOPIC 375 AutoExecPath !NOINDEX !TTY AutoExecPath = Path | File: Sets the path used to find AUTOEXEC.BAT if 4DOS is started as a primary shell with the /P option. If you include only a path, 4DOS will look for AUTOEXEC.BAT in the specified directory. If you include a complete file name, 4DOS will look for the specified file, and will not look for AUTOEXEC.BAT. The default is the file AUTOEXEC.BAT in the root directory of C:. !TTY ;--------------------------------------------------------------------------- !TOPIC 376 DirHistory !NOINDEX !TTY DirHistory = nnnn (256): Sets the amount of memory allocated to the directory history in bytes. The allowable range of values is 256 to 2048 bytes. If you use a global directory history list, the DirHistory value is ignored in all shells except the shell which first establishes the global list. ;--------------------------------------------------------------------------- !TOPIC 377 Environment !NOINDEX !TTY Environment = nnnn (512): Sets the amount of memory allocated to the environment in bytes. The allowable range of values is 160 to 32767 bytes. ;--------------------------------------------------------------------------- !TOPIC 378 EnvFree !NOINDEX !TTY EnvFree = nnnn (128): Sets the minimum amount of memory in bytes that will be available in the environment for secondary shells. 4DOS will enlarge the environment for each secondary shell, if necessary, so that there is at least this much free environment space when the shell starts. The allowable range of values is 128 to 32767 bytes. When launching a secondary shell, it may be useful to specify the directive using the //iniline syntax: c:\4dos\4dos.com //envfree=2048 /c%_batchname See 352Starting 4DOS for an explanation of //iniline. ;--------------------------------------------------------------------------- !TOPIC 379 Function !NOINDEX !TTY Function = nnnn (1024): Sets the amount of memory in bytes allocated for the function list. The allowable range of values is 256 to 32767 bytes. If you use a global function list, the Function value is ignored in all shells except the shell which first establishes the global list. ;--------------------------------------------------------------------------- !TOPIC 380 HelpOptions !NOINDEX !TTY HelpOptions = String: Sets default options for the 4DOS help system. The options are: !INDENT 5 5 0 5 /E: (Esc) Changes the Esc key and right mouse button so that they return you to the table of contents immediately, rather than backing up through recently viewed topics. /F: (Full screen index) Forces the index to occupy the entire screen. Primarily included for the convenience of blind users, to prevent speech software from reading the underlying screen when the index is up. /I: (Index) Starts the help system at the index page, rather than the Table of Contents. /L: (Lock scrolling) Changes the behavior of the up and down arrow keys so that they always scroll the text, and do not move the cross-reference highlight first. /M: (Monochrome) Forces HELP to use monochrome display mode. /Sn: (Speed) Sets the HELP mouse movement speed. /S0 sets the speed to one half the default mouse speed. /S2 sets it to twice the default, and /S4 sets it to four times the default. The higher values may be useful if you use a screen larger than the standard size of 80 x 25. /X: Disable the mouse while HELP is running. !INDENT 0 For more information and examples, see 014Help Reference. ;--------------------------------------------------------------------------- !TOPIC 381 HelpPath !NOINDEX !TTY HelpPath = Path: This directive is obsolete. It has been replaced by 384InstallPath. ;--------------------------------------------------------------------------- !TOPIC 382 History !NOINDEX !TTY History = nnnn (1024): Sets the amount of memory allocated to the command history list in bytes. The allowable range of values is 256 to 8192 bytes. If you use a global history list (see 033Command History and Recall), the History value is ignored in all shells except the shell which first establishes the global list. ;--------------------------------------------------------------------------- !TOPIC 383 INIQuery !NOINDEX !TTY INIQuery = Yes | NO: If set to Yes, a prompt will be displayed before execution of each subsequent line in the current .INI file. This allows you to modify certain directives when you start 4DOS in order to test different configurations. INIQuery can be reset to No at any point in the file. Normally INIQuery = Yes is only used during testing of other 4DOS.INI directives. !TTY The prompt generated by INIQuery = Yes is: [contents of the line] (Y/N/Q/R/E) ? At this prompt, you may enter: Y = Yes: Process this line and go on to the next. N = No: Skip this line and go on to the next. Q = Quit: Skip this line and all subsequent lines. R = Rest: Execute this and all subsequent lines. E = Edit: Prompt for a new value for this entry. If you choose E for Edit, you can enter a new value for the directive, but not a new directive name. For example, if you have found a compatibility problem you think may be related to 4DOS's swapping or upper memory block usage, you might change your 4DOS.INI file so a part of it read as follows: INIQuery = Yes Swapping = XMS, EMS, C:\ UMBLoad = Yes UMBEnvironment = Yes INIQuery = No You could then choose to process, ignore, or edit the Swapping, 398UMBLoad, or 395UMBEnvironment directive each time 4DOS started. This would allow you to test several possible combinations to see if you could resolve the compatibility problem. ;--------------------------------------------------------------------------- !TOPIC 384 InstallPath !NOINDEX !TTY InstallPath = Path: Sets the path used to find the help system, OPTION.EXE, and other 4DOS files. This directive is normally set by the installation program, and should not be changed unless you move the 4DOS files to a different directory. You can use the 648OPTION //optname=value syntax to change this setting (See also: 381HelpPath.) ;--------------------------------------------------------------------------- !TOPIC 385 LocalAliases !NOINDEX !TTY LocalAliases = YES | No: No forces all copies of 4DOS to share the same alias list. Yes keeps the lists for each shell separate. See 595ALIAS for more details on local and global alias lists. ;--------------------------------------------------------------------------- !TOPIC 386 LocalDirHistory !NOINDEX !TTY LocalDirHistory = YES | No: No forces all copies of 4DOS to share the same directory history. Yes keeps the directory histories for each shell separate. See 040Directory History Window for more details on local and global directory histories. ;--------------------------------------------------------------------------- !TOPIC 387 LocalFunctions !NOINDEX !TTY LocalFunctions = YES | No: No forces all copies of 4DOS to share the same user-defined functions list. Yes keeps the lists for each shell separate. ;--------------------------------------------------------------------------- !TOPIC 388 LocalHistory !NOINDEX !TTY LocalHistory = YES | No: No forces all copies of 4DOS to share the same history list. Yes keeps the lists for each shell separate. See 033Command History and Recall for more details on local and global history lists. ;--------------------------------------------------------------------------- !TOPIC 389 PauseOnError !NOINDEX !TTY PauseOnError = YES | No: Yes forces a pause with the message "Error in filename, press any key to continue processing" after displaying any error message related to a specific line in 4DOS.INI. No continues processing with no pause after an error message is displayed. ;--------------------------------------------------------------------------- !TOPIC 390 REXXPath !NOINDEX !TTY REXXPath = File: Specifies the program that 4DOS will use to execute .BAT files that begin with the characters [/*]. Specify a full path and filename if the program is not in your 138PATH. Under PC DOS 7.0 and above, REXXPath defaults to REXX.EXE, the REXX interpreter included with the operating system. If REXX.EXE is not in your PATH under PC DOS 7.0 or above, you must use this directive to specify the location of the REXX interpreter. See 116REXX Support for more details. ;--------------------------------------------------------------------------- !TOPIC 391 Swapping !NOINDEX !TTY Swapping = swap type [, swap type] ...: Sets the type of swapping 4DOS should use. 4DOS runs in two parts, a resident portion that is always in memory and a transient portion that is "swapped" to EMS memory, XMS memory, a RAM disk, or your hard disk while application programs are running. The swap area for the transient portion normally requires about 245K bytes of memory or disk space for the primary shell, and 60K bytes for each secondary shell (unless you set 575SwapReopen = Yes). !TTY The swap types can be any of the following: !INDENT 5 5 5 5 EMS: 4DOS will swap to EMS expanded memory if it is available. XMS: 4DOS will swap to XMS extended memory if it is available. Note: 4DOS will actually be swapped out of DOS completely by vDosPlus. d:\path: 4DOS will create a swap file in the drive and directory specified. The file will be called 4DOSSWAP.nnn where "nnn" is the shell number (unless you use the 576UniqueSwapName to generate a unique swap file name). This swap file is created as a hidden system file to avoid accidental deletion and will not be visible with a normal DIR command. None: No swapping. The transient portion of 4DOS will remain in memory at all times. This option will reduce memory available for application programs by about 245K compared to the other swap types, and should not be needed in vDosPlus. !INDENT 0 You can specify multiple swap types and 4DOS will try them in the order listed. Swap type "None" is always appended to your list of possible swap types as a "last resort," even if you don't include it explicitly. This allows 4DOS to start even if the other swap types you specify don't work. For example: Swapping = EMS, D:\, C:\SWAP tells 4DOS to try EMS memory first, then the D: disk, and finally the \SWAP directory on drive C. If all of these options fail (because there isn't enough free space available), the transient portion of 4DOS will remain in memory (swap type "None"). The default Swapping specification is: Swapping = EMS, XMS, x:\, None where "x" is C (for the primary shell) or the 134COMSPEC drive (for secondary shells). After 4DOS starts, you can use the 668SWAPPING command to view the type of swapping in use. ;--------------------------------------------------------------------------- !TOPIC 392 TreePath !NOINDEX !TTY TreePath = Path: Sets the location of JPSTREE.IDX, the file used for 048extended directory searches. By default, the file is placed in the root directory of drive C:\. ;--------------------------------------------------------------------------- !TOPIC 393 UMBAlias !NOINDEX !TTY UMBAlias = Yes | NO | 1 | 2 ... | 8: Yes attempts to load global alias list storage into a UMB (Upper Memory Block). If you use a specific region number (1 through 8), 4DOS will attempt to reserve room for the global alias list in that UMB region. !TTY If you use an invalid region number, or if region numbers have not been enabled on your system, 4DOS will load the global alias list into the first available region. If no upper memory is available, space for the global alias list will be reserved in low memory. UMBAlias applies to global aliases only, and is only used in the first shell which establishes the global alias area (see 595ALIAS for more information on local and global alias lists). If you specify 385LocalAliases = Yes, or if the previous shell already created a global alias area, any UMBAlias setting is ignored. ;--------------------------------------------------------------------------- !TOPIC 394 UMBDirHistory !NOINDEX !TTY UMBDirHistory = Yes | NO | 1 | 2 ... | 8: Yes attempts to load global directory history list storage into a UMB (Upper Memory Block). See 040Directory History Window for more details on local and global directory histories. If you use an invalid region number, or if region numbers have not been enabled on your system, 4DOS will load the global directory history list into the first available region. If no upper memory is available, space for the global directory history list will be reserved in low memory. UMBDirHistory applies to global directory history only, and is only used in the first shell which establishes the global directory history area (see 040Directory History Window for more information on local and global directory history lists). If you specify 386LocalDirHistory = Yes, or if the previous shell already created a global directory history area, any UMBDirHistory setting is ignored. ;--------------------------------------------------------------------------- !TOPIC 395 UMBEnvironment !NOINDEX !TTY UMBEnvironment = Yes | NO | 1 | 2 ... | 8: Yes attempts to load the master environment into a UMB (Upper Memory Block). This reduces 4DOS's base memory requirements but may cause problems with some programs that try to access the master environment directly. If you use an invalid region number, or if region numbers have not been enabled on your system, 4DOS will load the environment into the first available region. If no upper memory is available, space for the environment will be reserved in low memory. ;--------------------------------------------------------------------------- !TOPIC 396 UMBFunction !NOINDEX !TTY UMBFunction = Yes | NO | 1 | 2 ... | 8: Yes attempts to load global function list storage into a UMB (Upper Memory Block). If you use a specific region number (1 through 8), 4DOS will attempt to reserve room for the global function list in that UMB region. If you use an invalid region number, or if region numbers have not been enabled on your system, 4DOS will load the function list into the first available region. If no upper memory is available, space for the function list will be reserved in low memory. UMBFunction applies to global functions only, and is only used in the first shell which establishes the global function area. If you specify 385LocalFunctions = Yes, or if the previous shell already created a global function area, any UMBFunction setting is ignored. ;--------------------------------------------------------------------------- !TOPIC 397 UMBHistory !NOINDEX !TTY UMBHistory = Yes | NO | 1 | 2 ... | 8: Yes attempts to load global history list storage into a UMB (Upper Memory Block). If you use a specific region number (1 through 8), 4DOS will attempt to reserve room for the global history list in that UMB region. If you use an invalid region number, or if region numbers have not been enabled on your system, 4DOS will load the history list into the first available region. If no upper memory is available, space for the history list will be reserved in low memory. UMBHistory applies to global history only, and is only used in the first shell which establishes the global history area (see 033Command History and Recall for more information on local and global history lists). If you specify 388LocalHistory = Yes, or if the previous shell already created a global history area, any UMBHistory setting is ignored. ;--------------------------------------------------------------------------- !TOPIC 398 UMBLoad !NOINDEX !TTY UMBLoad = Yes | NO | 1 | 2 ... | 8: Yes attempts to load the resident portion of 4DOS into a UMB (Upper Memory Block). This reduces the size of the resident portion in base memory from about 3K bytes to 256 bytes. If you use an invalid region number, or if region numbers have not been enabled on your system, 4DOS will load it's resident portion into the first available region. If no upper memory is available, space for the resident portion will be reserved in low memory. ;--------------------------------------------------------------------------- !TOPIC 410 Configuration Directives !NOINDEX  411AmPm Time display format 412ANSI ANSI driver state  413AppendToDir "\" on directory names in filename completion 414BatchEcho Default batch file echo state  415BeepFreq Default beep frequency  416BeepLength Default beep length  417CDDWinHeight Position and size of the popup window used  417CDDWinLeft by extended directory searches  417CDDWinTop "  417CDDWinWidth " 418CommandSep Multiple command separator character  472CompleteHidden Filename completion of hidden/system files  450CopyPrompt Prompt before overwriting existing files 419CursorIns Cursor shape in insert mode 420CursorOver Cursor shape in overstrike mode 421DecimalChar Decimal separator  422DescriptionMax Maximum length of file descriptions 423DescriptionName Name of file to hold file descriptions 424Descriptions Enable / disable description processing 425EditMode Editing mode (insert / overstrike) 426EscapeChar 4DOS escape character 427EvalMax Max digits after decimal point in @EVAL 428EvalMin Min digits after decimal point in @EVAL 429FileCompletion Filename completion by extension  430FuzzyCD Selects Extended Directory Search mode  431HistCopy History copy mode  451HistDups History duplicate removal 432HistLogName History log file name  433HistMin Minimum command length to save  434HistMove History move mode  435HistWrap History wrap mode 436LineInput Enable / disable line input mode  475ListRowStart Starting row number for LIST and FFIND  473LogErrors Write errors to log file 437LogName Log file name 474Mouse Enable / disable mouse for popup boxes 438NoClobber Overwrite protection for output redirection 439ParameterChar Alias / function / batch file parameter character  477PathExt Enable or disable the PATHEXT variable  440PopupWinHeight Position and size of the popup windows used  440PopupWinLeft for the command history, directory history,  440PopupWinTop and filename completion  440PopupWinWidth "  441Printer LIST print device  442ScreenColumns Screen width  443ScreenRows Screen height  444TabStops Tab width in LIST 445ThousandsChar Thousands separator  476UnixPaths Enable or disable slash in command paths 446UpperCase Force file names to upper case  447Win95SFNSearch Control short filename search Directives marked with a  may be dynamically changed at the command line using the 648OPTION //optname=value syntax. If a directive does not have this mark there is probably some simpler way to change it, such as options to the 664SETDOS or 643LOG command, or the 137FILECOMPLETION environment variable. Most of the configuration directives can be easily adjusted using the interactive 648OPTION dialogs. The exceptions are 423DescriptionName, 436LineInput, 475ListRowStart, and 477PathExt. ;--------------------------------------------------------------------------- !TOPIC 411 AmPm !NOINDEX !TTY AmPm = Yes | NO | Auto: Yes displays times in 12-hour format with a trailing "a" for AM or "p" for PM. The default of No forces a display in 24-hour time format. Auto formats the time according to the country code set for your system. AmPm controls the time displays used by 612DIR and 662SELECT, in 643LOG files, and the output of the 673TIMER, 608DATE, and 672TIME commands. It has no effect on 219%_TIME, 303%@MAKETIME, the $t and $T options of 652PROMPT, or date and time 074ranges. ;--------------------------------------------------------------------------- !TOPIC 412 ANSI !NOINDEX !TTY ANSI = AUTO | Yes | No: Tells 4DOS whether an ANSI driver is installed and should be used for the 604CLS and 605COLOR commands. 4DOS normally determines this itself, but you may need to explicitly inform 4DOS. Also see 664SETDOS /A. ;--------------------------------------------------------------------------- !TOPIC 413 AppendToDir !NOINDEX !TTY AppendToDir = Yes | NO: If set to Yes, a trailing "\" will be appended to directory names when doing filename completion. The default is No. (Regardless of the setting of this directive, a trailing backslash is always appended to a directory name at the beginning of the command line to enable automatic directory changes.) ;--------------------------------------------------------------------------- !TOPIC 414 BatchEcho !NOINDEX !TTY BatchEcho = YES | No: Sets the default batch echo mode. Yes enables echoing of all batch file commands unless 619ECHO is explicitly set off in the batch file. No disables batch file echoing unless ECHO is explicitly set on. Also see 664SETDOS /V. ;--------------------------------------------------------------------------- !TOPIC 415 BeepFreq !NOINDEX !TTY BeepFreq = nnnn (440): Sets the default 597BEEP command frequency in Hz. This is also the frequency for "error" beeps (for example, if you press an illegal key). To disable all error beeps set this or 416BeepLength to 0. If you do, the BEEP command will not produce sound unless you explicitly specify a frequency and duration. ;--------------------------------------------------------------------------- !TOPIC 416 BeepLength !NOINDEX !TTY BeepLength = nnnn (2): Sets the default 597BEEP length in system clock ticks (approximately 1/18 of a second per tick). BeepLength is also the default length for "error" beeps (for example, if you press an illegal key). To disable all error beeps set this or 415BeepFreq to 0. If you do, the BEEP command will not produce sound unless you explicitly specify a frequency and duration. ;--------------------------------------------------------------------------- !TOPIC 417 CDDWin Directives !NOINDEX !TTY CDDWinLeft = nnnn, CDDWinTop = nnnn, CDDWinWidth = nnnn, CDDWinHeight = nnnn: These numeric values set the position and size of the popup window used by 048extended directory searches, in characters, including the border. The defaults are 3, 3, 72, and 16, respectively (i.e., a window beginning in column 3, row 3, 72 columns wide and 16 rows high). The position is relative to the top left corner of the screen. The width and height values include the space required for the window border. The window cannot be smaller than than 10 columns wide by 5 rows high (including the border). The values you enter will be adjusted if necessary to keep a minimum-size window visible on the screen. The window is normally displayed with a shadow, but if you specify a window starting at column 0 and extending to the right margin, the shadow is eliminated; this may be useful to prevent speech software from reading text in the shadow area while viewing the window. ;--------------------------------------------------------------------------- !TOPIC 418 CommandSep !NOINDEX !TTY CommandSep = c (^): This is the character used to separate 041multiple commands on the same line. The default is the caret [^]. You cannot use any of the redirection characters [<>|] or any of the whitespace characters (space, tab, comma, or equal sign). The command separator is saved by 665SETLOCAL and restored by 621ENDLOCAL. Also see 664SETDOS /C, the 166%+ internal variable, and 054Special Character Compatibility for information on using compatible command separators for two or more products. ;--------------------------------------------------------------------------- !TOPIC 472 CompleteHidden !NOINDEX !TTY CompleteHidden = Yes | NO: If set to YES, filename completion will return hidden and system files and directories, and CDD /S will include hidden directories when indexing. ;--------------------------------------------------------------------------- !TOPIC 450 CopyPrompt !NOINDEX !TTY CopyPrompt = Yes | NO: If set to Yes, a 606COPY or 646MOVE will prompt before overwriting an existing file if the command is being performed at the command prompt. This duplicates the behavior of later versions of COMMAND.COM and CMD.EXE. See also the environment variable 135COPYCMD. ;--------------------------------------------------------------------------- !TOPIC 419 CursorIns !NOINDEX !TTY CursorIns = nnnn (100): This is the shape of the cursor for insert mode during command-line editing and all commands which accept line input (DESCRIBE, ESET, etc.). The size is a percentage of the total character cell size, between 0% and 100%. Because of the way video BIOSes and drivers map the cursor shape, you may not get a smooth progression in cursor shapes as CursorIns and CursorOver change. If CursorIns or CursorOver is set to -1, 4DOS will not attempt to modify the cursor shape at all; you can use this feature to give another program full control of the cursor shape. Also see 420CursorOver and 664SETDOS /S. ;--------------------------------------------------------------------------- !TOPIC 420 CursorOver !NOINDEX !TTY CursorOver = nnnn (15): This is the shape of the cursor for overstrike mode during command-line editing and all commands which accept line input. The size is a percentage of the total character cell size, between 0% and 100%. Also see 419CursorIns and 664SETDOS /S. ;--------------------------------------------------------------------------- !TOPIC 421 DecimalChar !NOINDEX !TTY DecimalChar = . | , | AUTO: Sets the character used as the decimal separator for 263@EVAL, numeric 633IF and 634IFF tests, version numbers, and other similar uses. The only valid settings are period [.], comma [,], and Auto (the default). A setting of Auto tells 4DOS to use the decimal separator associated with your current country code. If you change the decimal character you must also adjust the thousands character (with 445ThousandsChar) so that the two characters are different. Also see 664SETDOS /G. ;--------------------------------------------------------------------------- !TOPIC 422 DescriptionMax !NOINDEX !TTY DescriptionMax = nnnn (40): Controls the description length limit for 611DESCRIBE. The allowable range is 20 to 511 characters. ;--------------------------------------------------------------------------- !TOPIC 423 DescriptionName !NOINDEX !TTY DescriptionName = File: Sets the file name in which to store file descriptions. The default file name is DESCRIPT.ION. Use this directive with caution because changing the name from the default will make it difficult to transfer file descriptions to another system. Also see 664SETDOS /D. ;--------------------------------------------------------------------------- !TOPIC 424 Descriptions !NOINDEX !TTY Descriptions = YES | No: Turns description handling on or off during the file processing commands COPY, DEL, MOVE, and REN. If set to No, 4DOS will not update the description file when files are moved, copied, deleted or renamed. Also see 664SETDOS /D. ;--------------------------------------------------------------------------- !TOPIC 425 EditMode !NOINDEX !TTY EditMode = Insert | OVERSTRIKE | InitOverstrike | InitInsert: This directive lets you start the command-line editor in either Insert or Overstrike mode. If you specify InitOverstrike or InitInsert, the command line editor will start in the specified state, but if you toggle insert mode while editing a line, the editor will continue to use the new mode on subsequent lines. Also see 664SETDOS /M. ;--------------------------------------------------------------------------- !TOPIC 426 EscapeChar !NOINDEX !TTY EscapeChar = c (Ctrl-X): Sets the character used to suppress the normal meaning of the following character. The default is Ctrl-X []. See 086Escape Character for a description of special escape sequences. You cannot use any of the redirection characters [<>|] or the whitespace characters (space, tab, comma, or equal sign) as the escape character. The escape character is saved by 665SETLOCAL and restored by 621ENDLOCAL. Also see 664SETDOS /E, the 165%= internal variable, and 054Special Character Compatibility for information on using compatible escape characters for two or more products. ;--------------------------------------------------------------------------- !TOPIC 427 EvalMax !NOINDEX !TTY EvalMax = nnnn (10): Controls the maximum number of digits after the decimal point in values returned by 263@EVAL. This setting can be overridden with the construct @EVAL[expression=n.n]. The allowable range is 0 to 10. Also see 664SETDOS /F. ;--------------------------------------------------------------------------- !TOPIC 428 EvalMin !NOINDEX !TTY EvalMin = nnnn (0): Controls the minimum number of digits after the decimal point in values returned by 263@EVAL. The allowable range is 0 to 10. This directive will be ignored if EvalMin is larger than 427EvalMax. This setting can be overridden with the construct @EVAL[expression=n.n]. Also see 664SETDOS /F. ;--------------------------------------------------------------------------- !TOPIC 429 FileCompletion !NOINDEX !TTY FileCompletion = cmd1: ext1 ext2 ...; cmd2: ext3 ext4 ... Sets the files made available during 035filename completion for selected commands. The format is the same as that used for the 137FILECOMPLETION environment variable. ;--------------------------------------------------------------------------- !TOPIC 430 FuzzyCD !NOINDEX !TTY FuzzyCD = 0 | 1 | 2 | 3: Enables or disables extended directory searches, and controls their behavior. A setting of 0 (the default) disables extended searches. For complete details on the meaning of the other settings see 048Extended Directory Searches. ;--------------------------------------------------------------------------- !TOPIC 431 HistCopy !NOINDEX !TTY HistCopy = Yes | NO: Controls what happens when you re-execute a line from the command history. If this option is set to Yes, the line is appended to the end of the history list. By default, or if this option is set to No, the command is not copied. The original copy of the command is retained at its original position in the list, regardless of the setting of HistCopy. Set this option to No if you want to use 434HistMove = Yes; otherwise, the HistCopy setting will override HistMove. ;--------------------------------------------------------------------------- !TOPIC 451 HistDups !NOINDEX !TTY HistDups = OFF | First | Last: Controls the history list duplicate removal. If this option is set to First, and a new entry matches an older one, the old entry is preserved and the new entry discarded. If set to Last, the new entry is saved and the old entry deleted. If set to Off, everything is saved to the history. ;--------------------------------------------------------------------------- !TOPIC 432 HistLogName !NOINDEX !TTY HistLogName = File: Sets the history log file name, and optionally its location. If no path is specified, the history log will be created in the root directory of C:. Using HistLogName does not turn history logging on; you must use a 643LOG /H ON command to do so. You can use the 648OPTION //optname=value syntax to change this setting ;--------------------------------------------------------------------------- !TOPIC 433 HistMin !NOINDEX !TTY HistMin = nnnn (0): Sets the minimum command-line size to save in the command history list. Any command line whose length is less than this value will not be saved. Legal values range from 0, which saves everything, to 256. You can prevent any command line from being saved in the history by beginning it with an at sign [@]. See also 033Command History and Recall, the 034Command History Window, and the 632HISTORY command. ;--------------------------------------------------------------------------- !TOPIC 434 HistMove !NOINDEX !TTY HistMove = Yes | NO: If set to Yes, a recalled line is moved to the end of the command history. The difference between this directive and 431HistCopy is that HistCopy = Yes copies each recalled line to the end of the history but leaves the original in place. HistMove = Yes places the line at the end of history and removes the original line. This directive has no effect if HistCopy = Yes. ;--------------------------------------------------------------------------- !TOPIC 435 HistWrap !NOINDEX !TTY HistWrap = YES | No: Controls whether the command history recall "wraps" when you reach the top or bottom of the list. The default setting enables wrapping, so the list appears "circular." If HistWrap is set to No, history recall will stop at the beginning and end of the list rather than wrapping. This setting affects history recall at the prompt only; the command history window never wraps. ;--------------------------------------------------------------------------- !TOPIC 436 LineInput !NOINDEX !TTY LineInput = Yes | NO: This directive controls how 4DOS gets its input from the command line. Yes forces 4DOS to perform line-by-line input, just as COMMAND.COM and CMD.EXE do, instead of character-by-character input. This will disable command-line editing, history recall, the directory history window, and filename completion. It is normally used only for rare memory-resident programs (TSRs) or applications which do not work properly unless 4DOS uses line input. If you have a particular program that requires line input, you can use 664SETDOS /L to temporarily change modes. See 751Compatibility for information on any programs which require this option. ;--------------------------------------------------------------------------- !TOPIC 475 ListRowStart !NOINDEX !TTY ListRowStart = 1 | 0: Specifies whether 640LIST and 625FFIND consider the first line in the file to be line "1" or line "0". The default is "1". ;--------------------------------------------------------------------------- !TOPIC 473 LogErrors !NOINDEX !TTY LogErrors = Yes | NO: If set to Yes, error messages will be written to the log file. ;--------------------------------------------------------------------------- !TOPIC 437 LogName !NOINDEX !TTY LogName = File: Sets the log file name, and optionally its location. If no path is specified, the log file will be created in the root directory of C:. Using LogName does not turn logging on; you must use a 643LOG ON command to do so. You can use the 648OPTION //optname=value syntax to change this setting ;--------------------------------------------------------------------------- !TOPIC 474 Mouse !NOINDEX !TTY Mouse = AUTO | yes | no: Specifies whether a mouse is available for popup boxes. If you don't have a mouse, or if the driver takes a long time for the query/reset call, you should explicitly set this value to No. ;--------------------------------------------------------------------------- !TOPIC 438 NoClobber !NOINDEX !TTY NoClobber = Yes | NO: If set to Yes, will prevent standard output 050redirection from overwriting an existing file, and will require that the output file already exist for append redirection. Also see 664SETDOS /N. ;--------------------------------------------------------------------------- !TOPIC 439 ParameterChar !NOINDEX !TTY ParameterChar = c (&): Sets the character used after a percent sign to specify all or all remaining command-line arguments in a batch file, alias, or user-defined function (e.g., %& or %n&; see 102Batch Files, 595ALIAS, and 696FUNCTION). The default is the ampersand [&]. The parameter character is saved by 665SETLOCAL and restored by 621ENDLOCAL. Also see 664SETDOS /P. See 054Special Character Compatibility for information on using compatible parameter characters for two or more products. ;--------------------------------------------------------------------------- !TOPIC 477 PathExt !NOINDEX !TTY PathExt = NO | Yes: Determines whether 4DOS will use the PATHEXT environment variable. If set to No (the default), the PATHEXT variable is ignored. If set to Yes, the PATHEXT variable will be used to determine extensions to look for when searching the 138PATH for an executable file. For details, see the 143PATHEXT variable and the 649PATH command. CAUTION: If you set PathExt = Yes in 4DOS.INI and then fail to set the PATHEXT variable, path searches will fail as there will be no extensions for which to search! PATHEXT is supported for compatibility reasons but should not generally be used as a substitute for the more flexible 082executable extensions feature. ;--------------------------------------------------------------------------- !TOPIC 440 PopupWin Directives !NOINDEX !TTY PopupWinLeft = nnnn, PopupWinTop = nnnn, PopupWinWidth = nnnn, PopupWinHeight = nnnn: These numeric values set the position and size of the command-line, directory history, and filename completion windows, and most other popup windows (see 417CDDWinLeft etc. for the extended directory search window). The values are in characters, and include the border. The defaults are 40, 1, 36, and 12 respectively (i.e., a window beginning in column 40, row 1, 36 columns wide and 12 rows high). The position is relative to the top left corner of the screen. The width and height values include the space required for the window border. The window cannot be smaller than than 10 columns wide by 5 rows high (including the border). The values you enter will be adjusted if necessary to keep a minimum-size window visible on the screen. The window is normally displayed with a shadow, but if you specify a window starting at column 0 and extending to the right margin, the shadow is eliminated; this may be useful to prevent speech software from reading text in the shadow area while viewing the window. ;--------------------------------------------------------------------------- !TOPIC 441 Printer !NOINDEX !TTY Printer = devicename: Sets the output device that the 640LIST command will print to. By default, LPT1 is used. The device can be PRN, LPT1 to 9, AUX, COM1 to 9, NUL (which will disable printed output). PRN usually defaults to LPT1 and AUX to COM1. ;--------------------------------------------------------------------------- !TOPIC 442 ScreenColumns !NOINDEX !TTY ScreenColumns = nnnn: Sets the number of columns used by the video display. Normally the screen size is determined automatically, but if you have a non-standard display you may need to set it explicitly. Systems which need to set 572OutputBIOS to Yes may also need to use this directive. ;--------------------------------------------------------------------------- !TOPIC 443 ScreenRows !NOINDEX !TTY ScreenRows = nnnn: Sets the number of screen rows used by the video display. Normally the screen size is determined automatically, but if you have a non-standard display you may need to set it explicitly. This value does not affect screen scrolling, which is controlled by your video BIOS. ScreenRows is used only by the 640LIST and 662SELECT commands, the paged output options of other commands (e.g., TYPE /P), and error checking in the screen output commands. Also see 664SETDOS /R. ;--------------------------------------------------------------------------- !TOPIC 444 TabStops !NOINDEX !TTY TabStops = nnnn (8): Sets the tab stops for files displayed with the 640LIST command. Setting TabStops=3, for example, will place a tab stop in every third column. The allowable range is 1 to 32. ;--------------------------------------------------------------------------- !TOPIC 445 ThousandsChar !NOINDEX !TTY ThousandsChar = . | , | AUTO: Sets the character used as the thousands separator for numeric output. The only valid settings are period [.], comma [,], and Auto (the default). A setting of Auto tells 4DOS to use the thousands separator associated with your current country code. If you change the thousands character you must also adjust the decimal character (with DecimalChar, see above) so that the two characters are different. Also see 664SETDOS /G. ;--------------------------------------------------------------------------- !TOPIC 476 UnixPaths !NOINDEX !TTY UnixPaths = Yes | NO: Enables the forward slash as a path separator in the command name (the first item on the command line). This allows you to enter a command like: c:\> /bin/programs/foo.exe without having the forward slashes interpreted as switch characters. Note that setting UnixPaths to Yes does not change the 4DOS or operating system switch character ('/' by default, unless changed by 664SETDOS /W). It simply allows you to put forward slashes in the command name without problems. When UnixPaths is set to Yes command switches beginning with a forward slash must be preceded by a space to avoid confusion (this is a good general practice regardless of the setting of UnixPaths). For example: c:\> \bin\foo.exe /c OK c:\> /bin/foo.exe /c OK c:\> \bin\foo.exe/c Error c:\> /bin/foo.exe/c Error ;--------------------------------------------------------------------------- !TOPIC 446 UpperCase !NOINDEX !TTY UpperCase = Yes | NO: Yes specifies that file and directory names should be displayed in the traditional upper-case by internal commands like COPY and DIR. No allows the normal 4DOS lower-case style. This directive does not affect the display of filenames on drives which support long filenames (see 945File Names for additional details). Also see 664SETDOS /U. ;--------------------------------------------------------------------------- !TOPIC 447 Win95SFNSearch !NOINDEX !TTY Win95SFNSearch = YES | No: Set to No to disable the automatic search for short filenames after long filenames in Windows 95/98/ME. See 081LFN File Searches. ;--------------------------------------------------------------------------- !TOPIC 448 Color Directives !NOINDEX 461BrightBG Bright background colors  462CDDWinColors Directory change window colors 463ColorDir Directory colors  465InputColors Input colors  466ListboxBarColors Light bar color in list boxes  467ListColors LIST display colors  468ListStatBarColors LIST status bar colors  464PopupWinColors Popup window colors  469SelectColors SELECT display colors  470SelectStatBarColors SELECT status bar colors  471StdColors Standard display colors Directives marked with a  may be dynamically changed at the command line using the 648OPTION //optname=value syntax. Bright backgrounds or blinking can be selected with 664SETDOS /B; the 133COLORDIR variable provides an easy way to redefine directory colorization on the fly. All of the color directives except for 466ListboxBarColors can be easily adjusted using the interactive 648OPTION dialogs. ;--------------------------------------------------------------------------- !TOPIC 461 BrightBG !NOINDEX !TTY BrightBG = Yes | No. If set to Yes, 4DOS will enable bright background colors. If set to No, bright backgrounds will be disabled, but blinking foreground characters will be enabled. If BrightBG is not used, 4DOS will not adjust the bright background / blinking foreground switch at all. Most color video boards default to a blinking foreground with bright background colors disabled. See also 664SETDOS /B. !TTY Using BrightBG requires careful attention to interactions of display type, mode, and color. For a detailed explanation, see 892Colors and Color Names. ;--------------------------------------------------------------------------- !TOPIC 462 CDDWinColors !NOINDEX !TTY CDDWinColors = Color: Sets the default colors for the popup window used by 048extended directory searches. If this directive is not used, the colors will be reversed from the current colors on the screen. ;--------------------------------------------------------------------------- !TOPIC 463 ColorDir !NOINDEX !TTY ColorDir = ext1 ext2 ...:colora;ext3 ext4 ... :colorb; ...: Sets the directory colors used by 612DIR and 662SELECT. The format is the same as that used for the 133COLORDIR environment variable. See the discussion of color-coded directories under DIR for more details. ;--------------------------------------------------------------------------- !TOPIC 465 InputColors !NOINDEX !TTY InputColors = Color: Sets the colors used for command-line input. This setting is useful for making your input stand out from the normal output. ;--------------------------------------------------------------------------- !TOPIC 466 ListboxBarColors !NOINDEX !TTY ListboxBarColors = Color: Sets the color for the highlight bar in the popup list boxes (i.e., 034command history window, 035filename completion window, 318@SELECT window, etc.). ;--------------------------------------------------------------------------- !TOPIC 467 ListColors !NOINDEX !TTY ListColors = Color: Sets the colors used by the 640LIST command. If this directive is not used, LIST will use the current default colors set by the 604CLS or 605COLOR command or by the 471StdColors directive. ;--------------------------------------------------------------------------- !TOPIC 468 ListStatBarColors !NOINDEX !TTY ListStatBarColors = Color: Sets the colors used on the 640LIST status bar. If this directive is not used, LIST will set the status bar to the reverse of the screen color (the screen color is controlled by 467ListColors). ;--------------------------------------------------------------------------- !TOPIC 464 PopupWinColors !NOINDEX !TTY PopupWinColors = Color: Sets the default colors for the command-line, directory history, and filename completion windows, and most other popup windows (see 462CDDWinColors for the extended directory search window). If this directive is not used the colors will be reversed from the current colors on the screen. ;--------------------------------------------------------------------------- !TOPIC 469 SelectColors !NOINDEX !TTY SelectColors = Color: Sets the color used by the 662SELECT command. If this directive is not used, SELECT will use the current default colors set by the 604CLS or 605COLOR command or by the 471StdColors directive. ;--------------------------------------------------------------------------- !TOPIC 470 SelectStatBarColors !NOINDEX !TTY SelectStatBarColors = Color: Sets the color used on the 662SELECT status bar. If this directive is not used, SELECT will set the status bar to the reverse of the screen color (the screen color is controlled by 469SelectColors). ;--------------------------------------------------------------------------- !TOPIC 471 StdColors !NOINDEX !TTY StdColors = Color: Sets the standard colors to be used when 604CLS is used without a color specification, and for 640LIST and 662SELECT if 467ListColors and 469SelectColors are not used. Using this directive is similar to placing a 605COLOR command in AUTOEXEC.BAT or 4START. StdColors takes effect the first time 604CLS, LIST, or SELECT is used after 4DOS starts, but will not affect the color of error or other messages displayed during the loading and initialization process. ;--------------------------------------------------------------------------- !TOPIC 481 Key Mapping Directives !NOINDEX These directives allow you to change the keys used for command-line editing and other internal functions. They are divided into four types: !INDENT 5 5 5 5 General Input Keys apply to all input. They are in effect whenever 4DOS requests input from the keyboard, including during 032command-line editing and the 611DESCRIBE, 622ESET, 636INPUT, 640LIST, and 662SELECT commands. Command-Line Editing Keys apply only to command-line editing, and are only effective at the 4DOS prompt. Popup Window Keys apply to popup windows, including the 034command history window, the 040directory history window, the 035filename completion window, the 048extended directory search window, and the 318@SELECT window. LIST Keys are effective only inside the 640LIST command. !INDENT 0 This topic lists all the key mapping directives, divided by type. It includes a one-line description of each directive, and a cross-reference which selects a full screen help topic on that directive. Most of the directives are simple enough that the one-line description is sufficient if you are generally familiar with how key mapping works. However, for those directives marked with an asterisk [*], the cross-reference topic contains some additional information you may wish to review. You can also obtain help on any directive with a HELP directive command at the prompt (this is why each directive has its own topic, in addition to its appearance in the list below). A detailed discussion of how key mapping works follows the directive list below. General Input Keys  512AliasExpand Expand aliases without executing them  482Backspace Deletes the character to the left of the cursor  483BeginLine Moves the cursor to the start of the line  484Del Deletes the character at the cursor  485DelToBeginning Deletes from the cursor to the start of the line  486DelToEnd Deletes from the cursor to the end of the line  487DelWordLeft Deletes the word to the left of the cursor  488DelWordRight Deletes the word to the right of the cursor  489Down * Moves the cursor or scrolls the display down  490EndLine Moves the cursor to the end of the line  491EraseLine Deletes the entire line  492ExecLine Executes or accepts a line  493Ins Toggles insert / overstrike mode  494Left * Moves the cursor or scrolls the display left  495NormalKey * Deassigns a key  496Right * Moves the cursor or scrolls the display right  497Up * Moves the cursor or scrolls the display up  498WordLeft Moves the cursor left one word  499WordRight Moves the cursor right one word Command-Line Editing Keys  511AddFile * Keeps filename completion entry and adds another  513CommandEscape * Allows direct entry of a keystroke  514DelHistory Deletes a history list entry  531DirWinOpen Opens the directory history window  515EndHistory Displays the last entry in the history list  516Help Invokes this help system  532HistWinOpen Opens the command history window  517LFNToggle Switches filename completion between LFN and SFN  518LineToEnd Copies the current line to the end of the history  519NextFile * Gets the next matching filename  520NextHistory Recalls the next command from the history  521NormalEditKey * Deassigns a command-line editing key  522PopFile * Opens the filename completion window  523PrevFile * Gets the previous matching filename  524PrevHistory Recalls the previous command from the history  527RepeatFile Repeats the just-matched filename  525SaveHistory Saves the command line without executing it Popup Window Keys  533NormalPopupKey * Deassigns a popup window key  534PopupWinBegin Moves to the first line of the popup window  535PopupWinDel Deletes a line from within the popup window  536PopupWinEdit Moves a line from the popup window to the prompt  537PopupWinEnd Moves to the last line of the popup window  538PopupWinExec Executes the selected line in the popup window LIST Keys  526ListContinue Continues LIST  539ListExit Exits the current file  540ListFind Prompts and searches for a string  541ListFindReverse Prompts and searches backward for a string  542ListHex Toggles hexadecimal display mode  543ListHighBit Toggles LIST's "strip high bit" option  544ListInfo Displays information about the current file  545ListNext Finds the next matching string  546ListPrevious Finds the previous matching string  547ListPrint Prints the file on LPT1  548ListWrap Toggles LIST's wrap option  549NormalListKey * Deassigns a LIST key See Also:  561ClearKeyMap Clear default key mappings Using Key Mapping Directives Using a key mapping directive allows you to assign a different or additional key to perform the function described. For example, to use function key F3 to invoke the HELP facility (normally invoked with F1): Help = F3 Any directive can be used multiple times to assign multiple keys to the same function. For example: ListFind = F ; F does a find in LIST ListFind = F5 ; F5 also does a find in LIST Use some care when you reassign keystrokes. If you assign a default key to a different function, it will no longer be available for its original use. For example, if you assign F1 to the AddFile directive (a part of filename completion), the F1 key will no longer invoke the help system, so you will probably want to assign a different key to Help. See 893Keys and Key Names before using the key mapping directives. Key assignments are processed before looking for keystroke aliases. For example, if you assign Shift-F1 to HELP and also assign Shift-F1 to a key alias, the key alias will be ignored. Assigning a new keystroke for a function does not deassign the default keystroke for the same function. If you want to deassign one of the default keys, use the 495NormalKey directive for general input keys, or the corresponding directive for keys in the other key groups (521NormalEditKey, 533NormalPopupKey, or 549NormalListKey).  All of the key-mapping directives may be dynamically reassigned at the command line using the 648OPTION //optname=value syntax. There is no provision for remapping keys in the interactive 648OPTION dialogs. ;--------------------------------------------------------------------------- ;Key mapping directives -- General Input ------------------------------- ;--------------------------------------------------------------------------- !TOPIC 482 Backspace !NOINDEX !TTY Backspace = Key (Bksp): Deletes the character to the left of the cursor. ;--------------------------------------------------------------------------- !TOPIC 483 BeginLine !NOINDEX !TTY BeginLine = Key (Home): Moves the cursor to the beginning of the line. ;--------------------------------------------------------------------------- !TOPIC 484 Del !NOINDEX Del = Key (Del): Deletes the character at the cursor. ;--------------------------------------------------------------------------- !TOPIC 485 DelToBeginning !NOINDEX !TTY DelToBeginning = Key (Ctrl-Home): Deletes from the cursor to the start of the line. ;--------------------------------------------------------------------------- !TOPIC 486 DelToEnd !NOINDEX !TTY DelToEnd = Key (Ctrl-End): Deletes from the cursor to the end of the line. ;--------------------------------------------------------------------------- !TOPIC 487 DelWordLeft !NOINDEX !TTY DelWordLeft = Key (Ctrl-L): Deletes the word to the left of the cursor. ;--------------------------------------------------------------------------- !TOPIC 488 DelWordRight !NOINDEX !TTY DelWordRight = Key (Ctrl-R, Ctrl-Bksp): Deletes the word to the right of the cursor. See 561ClearKeyMap if you need to remove the default mapping of Ctrl-Bksp to this function. ;--------------------------------------------------------------------------- !TOPIC 489 Down !NOINDEX !TTY Down = Key (Down): Scrolls the display down one line in LIST; moves the cursor down one line in 662SELECT and in the command-line history, directory history, or 318%@SELECT window. (Scrolling down through the command history at the prompt is controlled by 520NextHistory, not by this directive.) ;--------------------------------------------------------------------------- !TOPIC 490 EndLine !NOINDEX !TTY EndLine = Key (End): Moves the cursor to the end of the line. ;--------------------------------------------------------------------------- !TOPIC 491 EraseLine !NOINDEX !TTY EraseLine = Key (Esc): Deletes the entire line. ;--------------------------------------------------------------------------- !TOPIC 492 ExecLine !NOINDEX !TTY ExecLine = Key (Enter): Executes or accepts a line. ;--------------------------------------------------------------------------- !TOPIC 493 Ins !NOINDEX !TTY Ins = Key (Ins): Toggles insert / overstrike mode during line editing. ;--------------------------------------------------------------------------- !TOPIC 494 Left !NOINDEX !TTY Left = Key (Left): Moves the cursor left one character on the input line; scrolls the display left 8 columns in LIST; scrolls the display left 4 columns in the command-line, directory history, or 318%@SELECT window. ;--------------------------------------------------------------------------- !TOPIC 495 NormalKey !NOINDEX !TTY NormalKey = Key: Deassigns a general input key in order to disable the usual meaning of the key within 4DOS and/or make it available for keystroke aliases. This will make the keystroke operate as a "normal" key with no special function. For example: NormalKey = Ctrl-End will disable Ctrl-End, which is the standard "delete to end of line" key. Ctrl-End could then be assigned to a keystroke alias. Another key could be assigned the "delete to end of line" function with the 486DelToEnd directive. ;--------------------------------------------------------------------------- !TOPIC 496 Right !NOINDEX !TTY Right = Key (Right): Moves the cursor right one character on the input line; scrolls the display right 8 columns in 640LIST; scrolls the display right 4 columns in the command-line history, directory history, or 318%@SELECT window. ;--------------------------------------------------------------------------- !TOPIC 497 Up !NOINDEX !TTY Up = Key (Up): Scrolls the display up one line in 640LIST; moves the cursor up one line in 662SELECT and in the command-line history, directory history, or 318%@SELECT window. (Scrolling up through the command history at the prompt is controlled by 524PrevHistory, not by this directive.) ;--------------------------------------------------------------------------- !TOPIC 498 WordLeft !NOINDEX !TTY WordLeft = Key (Ctrl-Left): Moves the cursor left one word; scrolls the display left 40 columns in 640LIST. ;--------------------------------------------------------------------------- !TOPIC 499 WordRight !NOINDEX !TTY WordRight = Key (Ctrl-Right): Moves the cursor right one word; scrolls the display right 40 columns in 640LIST. ;--------------------------------------------------------------------------- ;Key mapping directives -- Command Line Editing -------------------------- ;--------------------------------------------------------------------------- !TOPIC 511 AddFile !NOINDEX !TTY AddFile = Key (F10): Keeps the current filename completion entry and inserts the next matching name. ;--------------------------------------------------------------------------- !TOPIC 512 AliasExpand !NOINDEX !TTY AliasExpand = Key (Ctrl-F): Expands all aliases in the current command line without executing them. ;--------------------------------------------------------------------------- !TOPIC 513 CommandEscape !NOINDEX !TTY CommandEscape = Key (Alt-255): Allows direct entry of a keystroke that would normally be handled by the command line editor (e.g. Tab or Ctrl-D). ;--------------------------------------------------------------------------- !TOPIC 514 DelHistory !NOINDEX !TTY DelHistory = Key (Ctrl-D): Deletes the displayed history list entry and displays the previous entry. ;--------------------------------------------------------------------------- !TOPIC 515 EndHistory !NOINDEX !TTY EndHistory = Key (Ctrl-E): Displays the last entry in the history list. ;--------------------------------------------------------------------------- !TOPIC 516 Help !NOINDEX !TTY Help = Key (F1): Invokes the HELP facility. ;--------------------------------------------------------------------------- !TOPIC 517 LFNToggle !NOINDEX !TTY LFNToggle = Key (Ctrl-A): Toggles filename completion between long filename and short filename modes on LFN drives. ;--------------------------------------------------------------------------- 0!TOPIC 518 LineToEnd !NOINDEX !TTY LineToEnd = Key (Ctrl-Enter): Copies the current command line to the end of the history list, then executes it. ;--------------------------------------------------------------------------- !TOPIC 519 NextFile !NOINDEX !TTY NextFile = Key (F9, Tab): Gets the next matching filename. See 561ClearKeyMap if you need to remove the default mapping of Tab to this function. ;--------------------------------------------------------------------------- !TOPIC 520 NextHistory !NOINDEX !TTY NextHistory = Key (Down): Recalls the next command from the command history. ;--------------------------------------------------------------------------- !TOPIC 521 NormalEditKey !NOINDEX !TTY NormalEditKey = Key: Deassigns a command-line editing key in order to disable the usual meaning of the key while editing a command line, and/or make it available for keystroke aliases. For additional details see 495NormalKey. ;--------------------------------------------------------------------------- !TOPIC 522 PopFile !NOINDEX !TTY PopFile = Key (F7, Ctrl-Tab): Opens the filename completion window. You may not be able to use Ctrl-Tab, because not all systems recognize it as a keystroke. See 561ClearKeyMap if you need to remove the default mapping of Ctrl-Tab to this function. ;--------------------------------------------------------------------------- !TOPIC 523 PrevFile !NOINDEX !TTY PrevFile = Key (F8, Shift-Tab): Gets the previous matching filename. See 561ClearKeyMap if you need to remove the default mapping of Shift-Tab to this function. ;--------------------------------------------------------------------------- !TOPIC 524 PrevHistory !NOINDEX !TTY PrevHistory = Key (Up): Recalls the previous command from the command history. ;--------------------------------------------------------------------------- !TOPIC 527 RepeatFile !NOINDEX !TTY RepeatFile = Key (F12): Repeats the previous matching filename during filename completion. ;--------------------------------------------------------------------------- !TOPIC 525 SaveHistory !NOINDEX !TTY SaveHistory = Key (Ctrl-K): Saves the command line in the command history list without executing it. ;--------------------------------------------------------------------------- ;Key mapping directives -- Popup -------------------------- ;--------------------------------------------------------------------------- !TOPIC 531 DirWinOpen !NOINDEX !TTY DirWinOpen = Key (Ctrl-PgUp): Opens the directory history window while at the command line. ;--------------------------------------------------------------------------- !TOPIC 532 HistWinOpen !NOINDEX !TTY HistWinOpen = Key (PgUp): Brings up the history window while at the command line. ;--------------------------------------------------------------------------- !TOPIC 533 NormalPopupKey !NOINDEX !TTY NormalPopupKey = Key: Deassigns a popup window key in order to disable the usual meaning of the key within the popup window. For additional details see 495NormalKey. ;--------------------------------------------------------------------------- !TOPIC 534 PopupWinBegin !NOINDEX !TTY PopupWinBegin = Key (Ctrl-PgUp): Moves to the first item in the list when in the popup window. ;--------------------------------------------------------------------------- !TOPIC 535 PopupWinDel !NOINDEX !TTY PopupWinDel = Key (Ctrl-D): Deletes a line from within the command history or directory history window. ;--------------------------------------------------------------------------- !TOPIC 536 PopupWinEdit !NOINDEX !TTY PopupWinEdit = Key (Ctrl-Enter): Moves a line from the command history or directory history window to the prompt for editing. ;--------------------------------------------------------------------------- !TOPIC 537 PopupWinEnd !NOINDEX !TTY PopupWinEnd = Key (Ctrl-PgDn): Moves to the last item in the list when in the popup window. ;--------------------------------------------------------------------------- !TOPIC 538 PopupWinExec !NOINDEX !TTY PopupWinExec = Key (Enter): Selects the current item and closes the window. ;--------------------------------------------------------------------------- ;Key mapping directives -- LIST ------------------------------------ ;--------------------------------------------------------------------------- !TOPIC 526 ListContinue !NOINDEX !TTY ListContinue = Key (C): Continues LIST. ;--------------------------------------------------------------------------- !TOPIC 539 ListExit !NOINDEX !TTY ListExit = Key (Esc): Exits from the LIST command. ;--------------------------------------------------------------------------- !TOPIC 540 ListFind !NOINDEX !TTY ListFind = Key (F): Prompts and searches for a string. ;--------------------------------------------------------------------------- !TOPIC 541 ListFindReverse !NOINDEX !TTY ListFindReverse = Key (Ctrl-F): Prompts and searches backward for a string. ;--------------------------------------------------------------------------- !TOPIC 542 ListHex !NOINDEX !TTY ListHex = Key (X): Toggles hexadecimal display mode. ;--------------------------------------------------------------------------- !TOPIC 543 ListHighBit !NOINDEX !TTY ListHighBit = Key (H): Toggles LIST's "strip high bit" option, which can aid in displaying files from certain word processors. ;--------------------------------------------------------------------------- !TOPIC 544 ListInfo !NOINDEX !TTY ListInfo = Key (I): Displays information about the current file. ;--------------------------------------------------------------------------- !TOPIC 545 ListNext !NOINDEX !TTY ListNext = Key (N): Finds the next matching string. ;--------------------------------------------------------------------------- !TOPIC 546 ListPrevious !NOINDEX !TTY ListPrevious = Key (Ctrl-N): Finds the previous matching string. ;--------------------------------------------------------------------------- !TOPIC 547 ListPrint !NOINDEX !TTY ListPrint = Key (P): Prints the file on LPT1. ;--------------------------------------------------------------------------- !TOPIC 548 ListWrap !NOINDEX !TTY ListWrap = Key (W): Toggles LIST's wrap option on and off. The wrap option wraps text at the right margin. ;--------------------------------------------------------------------------- !TOPIC 549 NormalListKey !NOINDEX !TTY NormalListKey = Key: Deassigns a LIST key in order to disable the usual meaning of the key within LIST. For additional details see 495NormalKey. ;--------------------------------------------------------------------------- !TOPIC 550 Advanced Directives !NOINDEX ChangeTitle Does not apply in vDosPlus  561ClearKeyMap Clear default key mappings CopyEA Does not apply in vDosPlus 562CritFail Automatic fail on critical errors  563Debug Set debugging options DiskReset Does not apply in vDosPlus DRSets Does not apply in vDosPlus 565DVCleanup Clean up on DESQview window close 554FineSwap Fine-grained disk swapping 566FullINT2E Full interrupt 2E support 567Include Include a file of .INI directives 568Inherit Inherit aliases, functions, and history 555MaxLoadAddress Shell load address control (NDIS etc.) 569MessageServer COMMAND.COM message server 570NetWareNames Novell NetWare support 571NextINIFile Set secondary shell .INI file name 572OutputBIOS Use BIOS instead of direct video output 556Reduce Control spawning of secondary shells 557ReserveTPA Control shell memory allocation 573SDFlush Control SMARTDRV write-behind buffers 574StackSize Internal stack size 575SwapReopen Reopen swap file if it is closed 576UniqueSwapName Use unique swap file name  577Win95LFN Disable long filename support Directives marked with a  may be dynamically changed at the command line using the 648OPTION //optname=value syntax. ;--------------------------------------------------------------------------- !TOPIC 554 FineSwap !NOINDEX !TTY FineSwap = Yes | NO: If you are using disk swapping and your system hangs when exiting an application, Yes enables "fine-grained" checksums during disk swapping. This should be used only to diagnose unusual swapping problems. ;--------------------------------------------------------------------------- !TOPIC 555 MaxLoadAddress !NOINDEX !TTY MaxLoadAddress = nnn: Specifies the maximum load address in order to work around problems with some rare drivers not properly allocating the memory they use. This should be used only to solve unusual problems. ;--------------------------------------------------------------------------- !TOPIC 556 Reduce !NOINDEX !TTY Reduce = YES | No: Set to No, if you have unexplained problems in starting secondary shells. ;--------------------------------------------------------------------------- !TOPIC 557 ReserveTPA !NOINDEX !TTY ReserveTPA = YES | No: Set to No for unusual memory allocation problems. ;--------------------------------------------------------------------------- !TOPIC 561 ClearKeyMap !NOINDEX !TTY ClearKeyMap: Clears all current 481key mappings. ClearKeyMap is a special directive which has no value or "=" after it. Use ClearKeyMap to make one of the keys in the default map (Tab, Shift-Tab, Ctrl-Tab, or Ctrl-Bksp) available for a keystroke alias, or in the [Secondary] section of 4DOS.INI to clear key mappings inherited from the primary shell. ClearKeyMap should appear before any key mapping directives. If you want to clear some but not all of the default mappings, use ClearKeyMap, then recreate the mappings you want to retain (e.g., with "NextFile=Tab", etc.). ;--------------------------------------------------------------------------- !TOPIC 562 CritFail !NOINDEX !TTY CritFail = Yes | NO: It intercepts all DOS critical errors and returns a Fail to each. We do not recommend this on most systems, because you will not have a chance to react to a critical error and correct the problem that caused it. It is intended for use on bulletin boards or other systems where unattended operation is required without user prompts. ;--------------------------------------------------------------------------- !TOPIC 563 Debug !NOINDEX !TTY Debug = nnnn (0): Controls certain debugging options which can assist you in tracking down unusual problems. Use the following values for Debug; to select more than one option, add the values together: !INDENT 8 5 5 5 1 During the startup process, display the complete command tail passed to 4DOS, then wait for a keystroke. 2 Include the product name with each error message displayed by 4DOS. This may be useful if you are unsure of the origin of a particular error message. !INDENT 0 Also see the 112batch file debugger, a separate and unrelated facility for stepping through batch files. ;--------------------------------------------------------------------------- !TOPIC 565 DVCleanup !NOINDEX !TTY DVCleanup = YES | No. Controls the cleanup of 4DOS resources (the shell number and any disk swap file) when you close a 4DOS window from the DESQview menu. See 751Compatibility for more details. ;--------------------------------------------------------------------------- !TOPIC 566 FullINT2E !NOINDEX !TTY FullINT2E = YES | No: This option does not apply for vDosPlus. ;--------------------------------------------------------------------------- !TOPIC 567 Include !NOINDEX !TTY Include = File: Include the text from the named file at this point in the processing of the current .INI file. Use this option to share a file of directives between several products. The text in the named file is processed just as if it were part of the original .INI file. When the include file is finished, processing resumes at the point where it left off in the original file. The included file may contain any valid directive for the current section, but may not contain a section name. Includes may be nested up to three levels deep (counting the original file as level 1). You must maintain include files manually -- the 648OPTION command modifies the original .INI file only, and does not update included files. ;--------------------------------------------------------------------------- !TOPIC 568 Inherit !NOINDEX !TTY Inherit = YES | No: 4DOS.INI data, aliases, functions, command history, and directory history are normally passed to secondary shells automatically. No disables this feature. ;--------------------------------------------------------------------------- !TOPIC 569 MessageServer !NOINDEX !TTY MessageServer = YES | No: For compatibility with COMMAND.COM, 4DOS includes a "message server" that retrieves error message text for DOS external commands like DISKCOPY and FORMAT. The message server increases the size of the resident portion of 4DOS by about 200 bytes. No disables the message server and saves this space, but will cause more cryptic error messages such as "Parse error 3" or "Extended error 7" from some DOS external commands. ;--------------------------------------------------------------------------- !TOPIC 570 NetWareNames !NOINDEX !TTY NetWareNames = Yes | NO. Set to Yes to include strings in the resident portion of 4DOS which Novell NetWare searches for when it loads. NetWareNames should be Yes for NetWare systems to avoid problems with destroyed environment variables during LOGIN. Setting NetWareNames to Yes increases 4DOS's low DOS memory usage by 112 bytes. ;--------------------------------------------------------------------------- !TOPIC 571 NextINIFile !NOINDEX !TTY NextINIFile = File. The full path and name of the file must be specified. All subsequent shells will read the specified .INI file, and ignore any [Secondary] section in the original .INI file. ;--------------------------------------------------------------------------- !TOPIC 572 OutputBIOS !NOINDEX !TTY OutputBIOS = Yes | NO: Determines whether 4DOS uses the BIOS for all screen displays. If set to No, 4DOS will use direct screen writes for color-coded directories and the 616DRAWBOX, 617DRAWHLINE, 618DRAWVLINE, 640LIST, 662SELECT, 661SCRPUT, and 684VSCRPUT commands. If set to Yes, 4DOS will perform these commands using BIOS calls. This directive is only needed for compatibility with unusual display adapters, such as those used on Japanese systems running DOS/V. Setting OutputBIOS to Yes may substantially reduce the speed of the affected commands. When OutputBIOS is set to Yes you may also need to set 442ScreenColumns appropriately. ;--------------------------------------------------------------------------- !TOPIC 573 SDFlush !NOINDEX !TTY SDFlush = Yes | NO: Determines whether 4DOS instructs Microsoft SMARTDRV (and other SMARTDRV-compatible disk caching programs) to flush any "write-behind" buffers to the disk before the 4DOS prompt is displayed. Setting SDFlush to Yes may decrease performance, but will ensure that SMARTDRV is instructed to write all modified data to disk before the prompt is displayed. SDFlush does not take into account any changes in the design or behavior of SMARTDRV after the release of 4DOS, or your SMARTDRV startup options. Therefore setting SDFlush to Yes does not guarantee that write-behind data will be written to disk before the prompt is displayed, only that SMARTDRV will be instructed to do so. ;--------------------------------------------------------------------------- !TOPIC 574 StackSize !NOINDEX !TTY StackSize = nnnn (8192): Set the 4DOS internal stack size. The allowable range of values is 8192 to 16384. If you use complex combinations of "prefix" commands like 615DO, 623EXCEPT, 626FOR, 628GLOBAL, 633IF, 634IFF, and 662SELECT on the same command line, and especially if you use these commands in multiple nested batch files or 629GOSUBs, you may encounter a "4DOS internal stack overflow" error. If you do, you should use this directive to increase the amount of stack space available. For virtually all users, the default stack size will be sufficient. If you increase the stack size, you will increase the size of 4DOS's transient portion in memory, and the size of the 4DOS swap area, by the amount of the stack size increase. Please note that you may receive "out of memory" errors which prevent 4DOS from loading if you use large StackSize values along with enlarged alias and/or history buffers. ;--------------------------------------------------------------------------- !TOPIC 575 SwapReopen !NOINDEX !TTY SwapReopen = Yes | NO: Set to Yes to enable reopening of the 4DOS swap file if it is closed by another program. This is required when using other applications which close 4DOS's swap file. In all other circumstances, it is only useful for diagnostic purposes. Setting SwapReopen to Yes also disables the reduced swapping size normally used in 4DOS secondary shells (see also 391Swapping). ;--------------------------------------------------------------------------- !TOPIC 576 UniqueSwapName !NOINDEX !TTY UniqueSwapName = Yes | No: Set to Yes to change the disk swap file name from 4DOSSWAP.nnn to a unique name generated by 4DOS, with an extension of "4SW" (e.g., A1CD6B11.4SW). This prevents conflicts between swap files in different shells; it is only necessary when you are using disk swapping with a primary shell. The default is No. ;--------------------------------------------------------------------------- !TOPIC 577 Win95LFN !NOINDEX !TTY Win95LFN= Yes | No: Under vDosPlus the default setting is Yes. Set Win95LFN to No to disable long filename support in the vDosPlus environment. This directive affects a wide range of internal filename and file handling features, but does not prevent 4DOS from detecting that it is running under Windows 95/98/ME. It generally should be used only for debugging or diagnostic purposes. In other environments the default is No. You can set Win95LFN to Yes to force 4DOS to try to use long filenames in non-standard environments (e.g., where a driver or memory-resident program provides long filename support that is not built into the operating system). Setting Win95LFN to Yes does not guarantee that non-standard LFN support will work with 4DOS, so you should do some testing before using this method extensively or for critical data or procedures. ;--------------------------------------------------------------------------- ; Directive equates ---------------------------------------------------------- !TOPIC 456 =417 CDDWinLeft !NOINDEX !TOPIC 457 =440 PopupWinLeft !NOINDEX !TOPIC 578 =373 _Alias_ !NOINDEX !TOPIC 579 =382 _History_ !NOINDEX !TOPIC 580 =391 _Swapping_ !NOINDEX !TOPIC 581 =412 _ANSI_ !NOINDEX !TOPIC 582 =428 _EvalMin_ !NOINDEX !TOPIC 583 =427 _EvalMax_ !NOINDEX !TOPIC 584 =429 _FileCompletion_ !NOINDEX !TOPIC 585 =376 _DirHistory_ !NOINDEX !TOPIC 586 =377 _Environment_ !NOINDEX !TOPIC 587 =379 _Function_ !NOINDEX !TOPIC 880 =417 CDDWinTop !NOINDEX !TOPIC 881 =417 CDDWinWidth !NOINDEX !TOPIC 882 =417 CDDWinHeight !NOINDEX !TOPIC 883 =440 PopupWinTop !NOINDEX !TOPIC 884 =440 PopupWinWidth !NOINDEX !TOPIC 885 =440 PopupWinHeight !NOINDEX ;--------------------------------------------------------------------------- !TOPIC 592 Commands by Category !NOINDEX The best way to learn the 4DOS commands is to use them and experiment with them. The lists below categorize the available commands by topic and will help you find the ones that you need. System configuration and status 598BREAK 603CHCP 604CLS 605COLOR 776COUNTRY 607CTTY 608DATE 613DIRHISTORY 627FREE 632HISTORY 637KEYBD 066LABEL 639LH / LOADHIGH 643LOG 645MEMORY 648OPTION 652PROMPT 656REBOOT 067SETCFG 068SETCOLOR 664SETDOS 069SETPORT 668SWAPPING 672TIME 681VER 682VERIFY 683VOL File and directory management 596ATTRIB 606COPY 609DEL / ERASE 611DESCRIBE 697HEAD 640LIST 646MOVE 658REN / RENAME 662SELECT 698TAIL 674TOUCH 676TRUENAME 677TYPE 064UNUSE 061USE 685WHICH Subdirectory management 601CD / CHDIR 602CDD 612DIR 614DIRS 644MD / MKDIR 651POPD 653PUSHD 655RD / RMDIR 675TREE Input and output 616DRAWBOX 617DRAWHLINE 618DRAWVLINE 619ECHO 689ECHOERR 620ECHOS 690ECHOSERR 635INKEY 636INPUT 638KEYSTACK 660SCREEN 661SCRPUT 671TEXT 684VSCRPUT Commands primarily for use in or with batch files and aliases (some work only in batch files; see the individual commands for details) 595ALIAS 597BEEP 599CALL 600CANCEL 065CMD 610DELAY CLOSETRAY 615DO EJECTMEDIA 621ENDLOCAL 626FOR 696FUNCTION 628GLOBAL 629GOSUB 630GOTO 633IF 634IFF 687LFNFOR 641LOADBTM 647ON 650PAUSE 654QUIT 657REM 659RETURN 827SETERROR 665SETLOCAL 666SHIFT 669SWITCH 671TEXT 774TRANSIENT 678UNALIAS 699UNFUNCTION Environment and path commands 622ESET 649PATH 663SET 680UNSET Other commands 594? 623EXCEPT 624EXIT 625FFIND 631HELP 640LIST 670TEE 673TIMER 686Y ;--------------------------------------------------------------------------- !TOPIC 594 ? !TTY Purpose: Display a list of internal commands or prompt for a command. Format: ? ["prompt" command] prompt: Prompt text about whether to execute the command. command: Command to be executed if user answers Y. !TTY Usage ? has two functions. ? by itself displays a list of internal commands. For help with any individual command, see the 631HELP command. If you have disabled a command with SETDOS /I, it will not appear in the list. The second function of ? is to prompt the user before executing a specific line in a batch file. If you add a prompt and a command, ? will display the prompt followed by "(Y/N)?" and wait for the user's response. If the user presses "Y" or "y", the line will be executed. If the user presses "N" or "n", the line will be ignored. For example, the following command might be used in a batch file: ? "Load the network" call netstart.btm When this command is executed, you will see the following prompt; if you answer "Y", the CALL command will be executed: Load the network (Y/N)? ;--------------------------------------------------------------------------- !TOPIC 595 ALIAS !TTY Purpose: Create new command names that execute one or more commands or redefine default options for existing commands; assign commands to keystrokes; load or display the list of defined alias names. Format: ALIAS [/P /R file...] [name[=][value]] file: One or more files to read for alias definitions. name: Name for an alias, or for the key to execute the alias. value: Text to be substituted for the alias name. /P(ause) /R(ead file) !TTY See also: 678UNALIAS. Usage The ALIAS command lets you create new command names or redefine internal commands. It also lets you assign one or more commands to a single keystroke. An alias is often used to execute a complex series of commands with a few keystrokes or to create "in memory batch files" that run much faster than disk-based batch files. For example, to create a single-letter command D to display a wide directory, instead of using the longer DIR /W, you could use the command: c:\> alias d = dir /w Now when you type a single d as a command, it will be translated into a DIR /W command. If you define aliases for commonly used application programs, you can often remove the directories they're stored in from the 138PATH. For example, if you use Quattro Pro and had the C:\QPRO directory in your path, you could define the following alias: c:\> alias qpro = c:\qpro\q.exe With this alias defined, you can probably remove C:\QPRO from your PATH. Quattro Pro will now load more quickly than it would if 4DOS had to search the PATH for it. In addition, the PATH can be shorter, which will speed up searches for other programs. If you apply this technique for each application program, you can often reduce your PATH to just two or three directories containing utility programs, and significantly reduce the time it takes to load most software on your system. Before removing a directory from the PATH, you will need to define aliases for all the executable programs you commonly use which are stored in that directory. Aliases are stored in memory, and are not saved automatically when you turn off your computer or end your current session. See below for information on saving and reloading your aliases. Multiple Commands and Special Characters in Aliases An alias can represent more than one command. For example: c:\> alias letters = `cd \letters ^ text` creates a new command called LETTERS. The command first uses CD to change to a subdirectory called \LETTERS and then runs a program called TEXT. The caret [^] is the 041command separator and indicates that the two commands are distinct and should be executed sequentially. When you type alias commands at the command line or in a batch file, you must use back-quotes [`] around the definition if it contains multiple commands, parameters (discussed below), environment variables, redirection, or piping. The back-quotes prevent premature expansion of these arguments. You may use back-quotes around other definitions, but they are not required. (You do not need back-quotes when your aliases are loaded from an ALIAS /R file; see below for details.) The examples above and below include back-quotes only when they are required. Nested Aliases Aliases may invoke internal commands, external commands, or other aliases. (However, an alias may not invoke itself, except in special cases where an IF or IFF command is used to prevent an infinite loop.) The two aliases below demonstrate alias nesting (one alias invoking another). The first line defines an alias which runs a program called WP.EXE that is in the E:\WP60\ subdirectory. The second alias changes directories with the PUSHD command, runs the WP alias, and then returns to the original directory with the POPD command: c:\> alias wp = e:\wp60\wp.exe c:\> alias w = `pushd c:\wp ^ wp ^ popd` The second alias above could have included the full path and name of the WP.EXE program instead of calling the WP alias. However, writing two aliases makes the second one easier to read and understand, and makes the first alias available for independent use. If you rename the WP.EXE program or move it to a new directory, only the first alias needs to be changed. Temporarily Disabling Aliases If you put an asterisk [*] immediately before a command in the value of an alias definition (the part after the equal sign), it tells 4DOS not to attempt to interpret that command as another (nested) alias. An asterisk used this way must be preceded by a space or the command separator and followed immediately by an internal or external command name. By using an asterisk, you can redefine the default options for any internal or external command. For example, suppose that you always want to use the DIR command with the /2 (two column) and /P (pause at the end of each page) options. The following line will do just that: c:\> alias dir = *dir /2/p If you didn't include the asterisk, the second DIR on the line would be the name of the alias itself, and 4DOS would repeatedly re-invoke the DIR alias, rather than running the DIR command. This would cause an "Alias loop" or "Command line too long" error. An asterisk also helps you keep the names of internal commands from conflicting with the names of external programs. For example, suppose you have a program called LIST.COM. Normally, the internal LIST command will run anytime you type LIST. But two simple aliases will give you access to both the LIST.COM program and the LIST command: c:\> alias list = c:\util\list.com c:\> alias display = *list The first line above defines LIST as an alias for the LIST.COM program. If you stopped there, the external program would run every time you typed LIST and you would not have easy access to the internal LIST command. The second line renames the internal LIST command as DISPLAY. The asterisk is needed in the second command to indicate that the following word means the internal command LIST, not the LIST alias which runs your external program. Another way to understand the asterisk is to remember that a command is always checked for an alias first, then for an internal or external command, or a batch file. The asterisk at the beginning of a command name simply skips over the usual check for aliases when processing that command, and allows 4DOS to go straight to checking for an internal command, external command, or batch file. You can also use an asterisk before a command that you enter at the command line or in a batch file. If you do, that command won't be interpreted as an alias. This can be useful when you want to be sure you are running the true, original command and not an alias with the same name, or temporarily defeat the purpose of an alias which changes the meaning or behavior of a command. You can also disable aliases temporarily with the 664SETDOS /X command. Partial Alias Names You can also use an asterisk in the name of an alias. When you do, the characters following the asterisk are optional when you invoke the alias command. (Use of an asterisk in the alias name is unrelated to the use of an asterisk in the alias value discussed above.) For example, with this alias: c:\> alias wher*eis = dir /sp the new command, WHEREIS, can be invoked as WHER, WHERE, WHEREI, or WHEREIS. Now if you type: c:\> where myfile.txt The WHEREIS alias will be expanded to the command: dir /sp myfile.txt Keystroke Aliases If you want to assign an alias to a keystroke, use the keyname on the left side of the equal sign, preceded by an at sign [@]. For example, to assign the command DIR /W to the F5 key, type c:\> alias @F5 = dir /w See 893Keys and Key Names for a complete listing of key names and a description of the key name format. When you define keystroke aliases, the assignments will only be in effect at the command line, not inside application programs. Be careful not to assign aliases to keys that are already used at the command line (like F1 for Help). The command-line meanings take precedence and the keystroke alias will never be invoked. If you want to use one of the command-line keys for an alias instead of its normal meaning, you must first disable its regular use with the 495NormalKey or 521NormalEditKey directives in 4DOS.INI. If you define a keystroke alias with a single at sign as shown above, then, when you press the F5 key, the value of the alias (DIR /W above) will be placed on the command line for you. You can type additional parameters if you wish and then press Enter to execute the command. With this particular alias, you can define the files that you want to display after pressing F5 and before pressing Enter to execute the command. If you want the keystroke alias to take action automatically without waiting for you to edit the command line or press Enter, you can begin the definition with two at signs [@@]. 4DOS will execute the alias "silently," without displaying its text on the command line. For example, this command will assign an alias to the F6 key that uses the CDD command to take you back to the previous default directory: c:\> alias @@f6 = cdd - When you define keystroke aliases, the assignments will only be in effect at the command line, not inside application programs. Be careful not to assign aliases to keys that are already used at the command line (like F1 for Help). The command-line meanings take precedence and the keystroke alias will never be invoked. If you want to use one of the command-line keys for an alias instead of its normal meaning, you must first disable its regular use with the 495NormalKey or 521NormalEditKey directives in your .INI file. You can also define a keystroke alias by using "@" or "@@" plus a scan code for one of the permissible keys (see 911ASCII and Key Codes for a list of scan codes). In most cases it will be easier to use key names. Scan codes should only be used with unusual keyboards where a key name is not available for the key you are using. Note that it is possible for more than one keystroke alias to refer to the same key. For example, @F2, @@F2, @60, and @@60 are all valid aliases for the F2 key. If you have multiple aliases for the same key, the first definition in the alias list will be used. Displaying Aliases If you want to see a list of all current ALIAS commands, type: c:\> alias You can also view the definition of a single alias. For example, if you want to see the definition of the alias LIST, you can type: c:\> alias list And you can view the definitions for all aliases matching a specific pattern by specifying a single parameter containing 073wildcards. For example: c:\> alias *win* will display all aliases containing the string win. Saving and Reloading Your Aliases You can save your aliases to a file called ALIAS.LST this way: c:\> alias > alias.lst You can then reload all the alias definitions in the file the next time you start a vDosPlus session: c:\> alias /r alias.lst This is much faster than defining each alias individually in a batch file. If you keep your alias definitions in a separate file which you load when your system starts, you can edit them with a text editor, reload the edited file with ALIAS /R, and know that the same alias list will be loaded the next time you start the vDosPlus session. When you define aliases in a file that will be read with the ALIAS /R command, you do not need back-quotes around the value, even if back-quotes would normally be required when defining the same alias at the command line or in a batch file. To remove an alias, use the 678UNALIAS command. Alias Parameters Aliases can use command-line arguments or parameters like those in batch files. The command-line arguments are numbered from %0 to %255. %0 contains the alias name. It is up to the alias to determine the meaning of the other parameters. You can use quotation marks to pass spaces, tabs, commas, and other special characters in an alias parameter; see 118Argument Quoting for details. Parameters that are referred to in an alias, but which are missing on the command line, appear as empty strings inside the alias. For example, if you put two parameters on the command line, any reference in the alias to %3 or any higher-numbered parameter will be interpreted as an empty string. The parameter %n& has a special meaning. 4DOS interprets it to mean "the entire command line, from argument n to the end." If n is not specified, it has a default value of 1, so %& means "the entire command line after the alias name." The special parameter %# contains the number of command-line arguments. If you wish to use a symbol other than the ampersand [&] to refer to multiple arguments, you can use the 439ParameterChar directive in 4DOS.INI or the 664SETDOS /P command to define a different parameter character. For example, the following alias will change directories, perform a command, and return to the original directory: c:\> alias in `pushd %1 ^ %2& ^ popd` When this alias is invoked as: c:\> in c:\comm mycomm /zmodem /56K the first parameter, %1, has the value c:\comm. %2 is mycomm, %3 is /zmodem, and %4 is /56K. The command line expands into these three separate commands: pushd c:\comm mycomm /zmodem /56K popd This next example uses the IFF command to redefine the defaults for SET. It should be entered on one line: c:\> alias set = `iff %# == 0 then ^ *set /p ^ else ^ *set %& ^ endiff` This modifies the SET command so that if SET is entered with no arguments, it is replaced by SET /P (pause after displaying each page), but if SET is followed by an argument, it behaves normally. Note the use of asterisks (*set) to prevent alias loops. If an alias uses parameters, command-line arguments will be deleted up to and including the highest referenced argument. For example, if an alias refers only to %1 and %4, then the first and fourth arguments will be used, the second and third arguments will be discarded, and any additional arguments beyond the fourth will be appended to the expanded command (after the value portion of the alias). If an alias uses no parameters, all of the command-line arguments will be appended to the expanded command. Aliases also have full access to all variables in the environment, internal variables, and variable functions. For example, you can create a simple command-line calculator this way: c:\> alias calc = `echo The answer is: %@eval[%&]` Now, if you enter: c:\> calc 5 * 6 the alias will display: The answer is: 30 Expanding Aliases at the Prompt You can expand an alias on the command line and view or edit the results by pressing Ctrl-F after typing the alias name, but before the command is executed. This replaces the alias with its contents, and substitutes values for each alias paramter, just as if you had pressed the Enter key. However, the command is not executed; it is simply redisplayed on the command line for additional editing. Ctrl-F is especially useful when you are developing and debugging a complex alias, or if you want to make sure that an alias that you may have forgotten won't change the effect of your command. Local and Global Aliases The aliases can be stored in either a "local" or "global" list. With a local alias list, any changes made to the aliases will only affect the current copy of 4DOS. They will not be visible in other shells or other sessions. A local alias list is the default. With a global alias list, all copies of 4DOS will share the same alias list, and any changes made to the aliases in one copy will affect all other copies. You can control the type of alias list on the Startup page of the 648OPTION dialogs, with the 385LocalAliases directive in 4DOS.INI, with the /L and /LA 352startup options. Whenever you start a secondary shell which uses a local alias list, it inherits a copy of the aliases from the previous shell. However, any changes to the aliases made in the secondary shell will affect only that shell. If you want changes made in a secondary shell to affect the previous shell, use a global alias list in both shells. If you select a global alias list, you can share the aliases among all copies of 4DOS. The UNKNOWN_CMD Alias If you create an alias with the name UNKNOWN_CMD, it will be executed any time 4DOS would normally issue an "Unknown command" error message. This allows you to define your own handler for unknown commands. When the UNKNOWN_CMD alias is executed, the command line which generated the error is passed to the alias for possible processing. For example, to display the command that caused the error: alias unknown_cmd `echo Error in command "%&"` If the UNKNOWN_CMD alias contains an unknown command, it will call itself repeatedly. If this occurs, 4DOS will loop up to 10 times, then display an "UNKNOWN CMD loop" error. Options !INDENT 5 5 0 5 /P: (Pause) This option is only effective when ALIAS is used to display existing definitions. It pauses the display after each page and waits for a keystroke before continuing (see 045Page and File Prompts). /R: (Read file) This option loads an alias list from a file. The format of the file is the same as that of the ALIAS display: !INDENT 5 5 5 5 name=value where name is the name of the alias and value is its value. You can use an equal sign [=] or space to separate the name and value. Back-quotes are not required around the value. You can add comments to the file by starting each comment line with a colon [:]. You can load multiple files with one ALIAS /R command by placing the names on the command line, separated by spaces: c:\> alias /r alias1.lst alias2.lst Each definition in an ALIAS /R file can be up to 511 characters long. The definitions can span multiple lines in the file if each line, except the last, is terminated with an 086escape character. If there is no filename argument and input is redirected, ALIAS /R will read from stdin. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 596 ATTRIB !TTY Purpose: Change or view file and subdirectory attributes. Format: ATTRIB [/A:[[+|-]rhsad] /D /E /I"text" /N /P /Q /S] [+|-[AHRS]] [@file] files ... files: A file, directory, or list of files or directories on which to operate. @file: A text file containing the names of the files on which to operate, one per line (see 057@file lists for details). /A: (Attribute select) /N(othing) /D(irectories) /P(ause) /E (no error messages) /Q(uiet) /I (match descriptions) /S(ubdirectories) Attribute flags: +A Set the archive attribute -A Clear the archive attribute +H Set the hidden attribute -H Clear the hidden attribute +R Set the read-only attribute -R Clear the read-only attribute +S Set the system attribute -S Clear the system attribute !TTY File Selection Supports extended 073wildcards, 074ranges, 079multiple file names, and 080include lists. Usage Every file and subdirectory has four attributes that can be turned on (set) or turned off (cleared): Archive, Hidden, Read-only, and System. The ATTRIB command lets you view, set, or clear attributes for any file, group of files, or subdirectory. You can view file attributes by entering ATTRIB without specifying new attributes (i.e., without the [+|-[AHRS]] part of the format) or with the DIR /T command.) The primary use of ATTRIB is to set attributes. For example, you can set the read-only and hidden attributes for the file MEMO: c:\> attrib +rh memo Attribute options apply to the file(s) that follow the options on the ATTRIB command line. The example below shows how to set different attributes on different files with a single command. It sets the archive attribute for all .TXT files, then sets the system attribute and clears the archive attribute for TEST.COM: c:\> attrib +a *.txt +s -a test.com You must quote any file names which contain whitespace or special characters. See 945File Names for additional details. To change directory attributes, use the /D switch. If you give ATTRIB a directory name instead of a file name, and omit /D, it will append "\*.*" to the end of the name and act on all files in that directory, rather than acting on the directory itself. Your operating system also supports "D" (subdirectory) and "V" (volume label) attributes. These attributes cannot be altered with ATTRIB; they are designed to be controlled only by the operating system itself. ATTRIB will ignore underlines in the new attribute (the [+|-[AHRS]] part of the command). For example, ATTRIB sees these two commands as identical: c:\> attrib +a filename c:\> attrib +__A_ filename This allows you to use a string of attributes from either the @ATTRIB variable function or from ATTRIB itself (both of which use underscores to represent attributes that are not set) and send that string back to ATTRIB to set attributes for other files. For example, to clear the attributes of FILE2 and then set its attributes to match those of FILE1 (enter this on one line): c:\> attrib -arhs file2 ^ attrib +%@attrib[file1] file2 If you include a +D / -D in the attribute list, it will set the /D flag automatically. Options !INDENT 5 5 0 5 /A:: (Attribute select) Select only those files that have the specified attribute(s) set. The colon [:] after /A is required. !INDENT 5 5 5 5 Preceding an attribute letter with a hyphen [-] will select files that do not have that attribute set. You can OR attributes by preceding each attribute letter with a plus sign [+]. The attributes are: R Read-only D subDirectory H Hidden A Archive S System If no attributes are listed at all (e.g., ATTRIB /A: ...), ATTRIB will select all files including hidden and system files. If attributes are combined, all the specified attributes must match for a file to be selected. For example, /A:RHS will select only those files with all three attributes set. The /A switch specifies which files to select, not which attributes to set. For example, to remove the archive attribute from all hidden files, you could use this command: c:\> attrib /a:h -a *.* !INDENT 5 5 0 5 /D: (Directories) If you use the /D option, ATTRIB will modify the attributes of subdirectories in addition to files (yes, you can have a hidden subdirectory): !INDENT 5 5 5 5 c:\> attrib /d +h c:\mydir In addition, the /D option will keep ATTRIB from appending "\*.*" to the end of a directory name and modifying the attributes of all the files in the subdirectory. If you use a directory name instead of a file name, and omit /D, ATTRIB will append "\*.*" to the end of the name and act on all files in that directory, rather than acting on the directory itself. !INDENT 5 5 0 5 /E: (No error messages) Suppress all non-fatal error messages, such as "File not found." Fatal error messages, such as "Drive not ready," will still be displayed. This option is most useful in batch files and aliases. /I"text": Select files by matching text in their descriptions. The text can include 073wildcards and extended wildcards. The search text must be enclosed in quotation marks, and must follow the /I immediately, with no intervening spaces. You can select all filenames that have a description with /I"[?]*", or all filenames that do not have a description with /I"[]". /N: (Nothing) Do everything except actually change attributes. This option is useful for testing what the result of a complex ATTRIB command will be. /P: (Pause) Wait for a key to be pressed after each screen page before continuing the display. Your options at the prompt are explained in detail under 045Page and File Prompts. /Q: (Quiet) This option turns off ATTRIB's normal screen output. It is most useful in batch files. /S: (Subdirectories) If you use the /S option, the ATTRIB command will be applied to all matching files in the current or named directory and all of its subdirectories. Do not use /S with @file lists; see 057@file lists for details. Unlike most 4DOS commands, ATTRIB /S will search into subdirectories with the hidden or system attributes set. !INDENT 0 For comparison with the external DOS ATTRIB command refer to the 65535external DOS help system. ;--------------------------------------------------------------------------- !TOPIC 597 BEEP !TTY Purpose: Beep the speaker or play simple music. Format: BEEP [frequency duration ...] frequency: The beep frequency in Hertz (cycles per second). duration: The beep length in 1/18th second intervals. !TTY See also: 415BeepFreq and 416BeepLength. Usage BEEP generates a sound through your computer's speaker. It is normally used in batch files to signal that an operation has been completed, or that the computer needs attention. Because BEEP allows you to specify the frequency and duration of the sound, you can also use it to play simple music or to create different kinds of signals for the user. You can include as many frequency and duration pairs as you wish. No sound will be generated for frequencies less than 20 Hz, allowing you to use BEEP as a way to create short delays. The default value for frequency is 440 Hz; the default value for duration is 2. This batch file fragment runs a program called DEMO, then plays a few notes and waits for you to press a key: demo ^ beep 440 4 600 2 1040 6 pause Finished with the demo - hit a key... The following table gives the frequency values for a five octave range (middle C is 262 Hz): C 131 262 523 1046 2093 C#/Db 139 277 554 1108 2217 D 147 294 587 1174 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 1864 3729 B 248 494 988 1976 3951 ;--------------------------------------------------------------------------- !TOPIC 598 BREAK !TTY Purpose: Display, enable, or disable Ctrl-C and Ctrl-Break checking. Format: BREAK [ON | OFF] !TTY Usage The Ctrl-C and Ctrl-Break keys are used by many programs (including 4DOS) as a signal to interrupt the current operation. BREAK controls how often DOS checks to see if you've entered one of these keystrokes. Normally, BREAK is turned off, and DOS only checks for Ctrl-C and Ctrl-Break keystrokes during DOS input or output operations involving the screen, keyboard, serial port, and printer. However, many programs don't use DOS for these operations, and it can be difficult to interrupt them. When BREAK is turned on, DOS checks for Ctrl-C and Ctrl-Break every time a program calls DOS. Since most programs use DOS to access files and perform other functions, turning BREAK on makes it much more likely that a Ctrl-C or Ctrl-Break will be noticed. If you turn BREAK on, programs will run slightly slower than normal (the difference is not usually noticeable). Turning BREAK on or off only affects when DOS detects Ctrl-C and Ctrl-Break and notifies the program you're running. Any program can choose to ignore these signals. Also, any program can change the BREAK setting on its own. Type BREAK plus ON or OFF to set the BREAK status, or BREAK by itself to display the current BREAK status. BREAK is off by default. For more information on this command, refer to the 65535external DOS help system. ;--------------------------------------------------------------------------- !TOPIC 599 CALL !TTY Purpose: Execute one batch file from within another. Format: CALL file file: The batch file to execute. !TTY See also: 600CANCEL and 654QUIT. Usage CALL allows batch files to call other batch files (batch file nesting). The calling batch file is suspended while the called (second) batch file runs. When the second batch file finishes, the original batch file resumes execution at the next command. If you execute a batch file from inside another batch file without using CALL, the first batch file is terminated before the second one starts. The following batch file fragment compares an input line to "wp" and calls another batch file if it matches: input Enter your choice: %%option if "%option" == "wp" call wp.bat 4DOS supports batch file nesting up to 16 levels deep. The current ECHO state is inherited by a called batch file. The called batch file should always either return (by executing its last line, or using the QUIT command), or terminate batch file processing with CANCEL. Do not restart or CALL the original batch file from within the called file as this may cause an infinite loop or a stack overflow. CALL returns an exit code which matches the batch file return code. You can test this exit code with the 164%_? or 162%? environment variable, and use it with 084conditional commands. ;--------------------------------------------------------------------------- !TOPIC 600 CANCEL !TTY Purpose: Terminate batch file processing. Format: CANCEL [value] value: The numeric exit code to return to 4DOS. !TTY See also: 599CALL, 624EXIT, and 654QUIT. Usage The CANCEL command ends all batch file processing, regardless of the batch file nesting level. Use QUIT to end a nested batch file and return to the previous batch file. You can CANCEL at any point in a batch file. If CANCEL is used from within an alias it will end execution of both the alias and any batch files which are running at the time. If you specify a value, CANCEL will set the ERRORLEVEL or exit code to that value (see the 633IF command, and the 162%? variable). ;--------------------------------------------------------------------------- !TOPIC 601 CD !TTY Purpose: Display or change the current directory. Format: CD [/N] [ path | - ] or CHDIR [/N] [ path | - ] path: The directory to change to, including an optional drive name. /N(o extended search) !TTY See also: 602CDD, 644MD, 653PUSHD, 655RD, 049CDPATH, and 047Directory Navigation. Usage CD and CHDIR are synonyms. You can use either one. CD lets you navigate through a drive's subdirectory structure by changing the current working directory. If you enter CD and a directory name, the named directory becomes the new current directory. For example, to change to the subdirectory C:\FINANCE\MYFILES: c:\> cd \finance\myfiles c:\finance\myfiles> Every disk drive on the system has its own current directory. Specifying both a drive and a directory in the CD command will change the current directory on the specified drive, but will not change the default drive. For example, to change the default directory on drive A: c:\> cd a:\utility c:\> Notice that this command does not change to drive A:. Use the CDD command to change the current drive and directory at the same time. You should quote the path name if it contains whitespace or special characters. See 945File Names for additional details. You can change to the parent directory with CD ..; you can also go up one additional directory level with each additional [.]. For example, CD .... will go up three levels in the directory tree (see 072Extended Parent Directory Names). You can move to a sibling directory -- one that branches from the same parent directory as the current subdirectory -- with a command like CD ..\newdir. If you enter CD with no argument or with only a disk drive name, it will display the current directory on the default or named drive. If CD cannot change to the directory you have specified it will attempt to search the 049CDPATH and the 048extended directory search database in order to find a matching directory and switch to it. You can use wildcards in the path to force an extended directory search. See 047Directory Navigation for complete details on these and other directory navigation features. To disable extended directory searches for the current command (e.g. in a batch file) see the /N option below. CD saves the current directory before changing to a new directory. You can switch back to the previous directory by entering CD - (there must be a space between the CD command and the hyphen). You can switch back and forth between two directories by repeatedly entering CD -. The saved directory is the same for both the CD and CDD commands. Drive changes and 039automatic directory changes also modify the saved directory, so you can use CD - to return to a directory that you exited with an automatic directory change. Directory changes made with CD are also recorded in the directory history list and can be displayed in the 040directory history window, which allows you to return quickly to a recently-used directory. You can use CD . to save the current drive and directory to the directory history without changing directories. This might be useful if you use an external program to navigate directories. You could create an 595alias using CD . to stash the current location before calling the external utility, so you can return later using CDD - or the directory history window. For example, to save the current drive and directory before running a program called ACD: alias acd=`cd . %+ c:\utility\acd.exe` CD never changes the default drive. If you change directories on one drive, switch to another drive, and then enter CD -, the directory will be restored on the first drive but the current drive will not be changed. You will probably find 602CDD - more useful than CD -. Floating drives Under DR DOS 3.31 - 6.0 (up to 1992 issues), 4DOS fully supports the DR DOS CD / CHDIR "floating drive" syntax to implicitly specify ASSIGN or SUBST drives on the fly as follows: cd d:=c: cd d:=c:\path or or chdir d:=c: chdir d:=c:\path Option !INDENT 5 5 0 5 /N: (No extended search) This option prevents CD from searching the 048extended directory search database or displaying the related popup window. If /N is used and the specified directory is not found via other methods (i.e. without an extended search), CD will display an error. This option is primarily intended for use in batch files where you do not want CD to use "fuzzy" directory searching or display an extended search popup window. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 602 CDD !TTY Purpose: Change the current disk drive and directory. Format: CDD [/A /D[drive...] /N /S[drive...] /U[drive...] [ path | - ] path: The name of the directory (or drive and directory) to change to. drive: A drive or list of drives to include in the extended directory search database. /A(ll drives) /S (build tree) /D(elete from JPSTREE.IDX) /U(pdate tree) /N(o extended search) !TTY See also: 601CD, 644MD, 653PUSHD, 655RD, 049CDPATH, and 047Directory Navigation. Usage CDD is similar to the CD command, except that it also changes the default disk drive if one is specified. CDD will change to the directory and drive you name. To change from the root directory on drive A to the subdirectory C:\WP: a:\> cdd c:\wp c:\wp> You can change to the parent directory with CDD ..; you can also go up one additional directory level with each additional [.]. For example, CDD .... will go up three levels in the directory tree (see 072Extended Parent Directory Names). You should quote the path name if it contains whitespace or special characters. See 945File Names for additional details. If CDD cannot change to the directory you have specified it will attempt to search the 049CDPATH and the 048extended directory search database in order to find a matching directory and switch to it. You can also use wildcards in the path to force an extended directory search. See 047Directory Navigation for complete details on these and other directory navigation features. To disable extended directory searches for the current command (e.g. in a batch file) see the /N option below. CDD saves the current drive and directory before changing to a new directory. You can switch back to the previous drive and directory by entering CDD - (there must be a space between the CDD command and the hyphen). You can switch back and forth between two drives and directories by repeatedly entering CDD -. The saved directory is the same for both the CD and CDD commands. Drive changes and 039automatic directory changes also modify the saved directory, so you can use CDD - to return to a directory that you exited with a drive change or an automatic directory change. Directory changes made with CDD are also recorded in the directory history list and can be displayed in the 040directory history window, which allows you to return quickly to a recently-used directory. CDD is also used to create and update the 048extended directory search database (JPSTREE.IDX); see the /D /S and /U options for details. Options !INDENT 5 5 0 5 /A: (All drives) When CDD is used with this option, it displays the current directory on all drives from C: to the last drive in the system. You cannot move to a new drive and directory and use /A in the same command. /D: (Delete tree) remove the specified drives or directory trees from JPSTREE.IDX. /N: (No extended search) This option prevents CDD from searching the 048extended directory search database or displaying the related popup window. If /N is used and the specified directory is not found via other methods (i.e. without an extended search), CDD will display an error. This option is primarily intended for use in batch files where you do not want CDD to use "fuzzy" directory searching or display an extended search popup window. /S: (Search tree) Builds or rebuilds the 048extended directory search database, JPSTREE.IDX, with the specified drives and/or directories. You cannot move to a new drive and directory and use /S in the same command. !INDENT 5 5 5 5 To include all local hard drives in the database use the command: cdd /s To limit or add to the list of drives included in the database, list the drives and network volume names (and optionally subdirectory paths) after the /S switch. For example, to include drives C, D, E, and the network volume \\server\dir1 in the database, use this command: cdd /s cde \\server\dir1 All non-hidden directories on the listed drives will be indexed; you cannot restrict the database to certain directories within a drive. Each time you use /S, everything in the previous directory database is replaced by the new database that is created. If you set the 472CompleteHidden directive, CDD will index hidden subdirectories as well. !INDENT 5 5 0 5 /U: (Update tree) Updates JPSTREE.IDX with the specified drives and/or directories. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 603 CHCP !TTY Purpose: Display or change the current DOS code page. Format: CHCP [nnn] nnn: Specifies a code page number. !TTY Usage Code page switching allows you to select different character sets for language support. If CHCP is entered without a number, the current code page is displayed. If you enter CHCP plus a code page number, the DOS code page is changed. For example, to set the code page to multilingual: chcp 850 Eventually the number of characters not defined in the active TTF font of vDosPlus will be shown. ;--------------------------------------------------------------------------- !TOPIC 604 CLS !TTY Purpose: Clear the video display and move the cursor to the upper left corner; optionally change the default display and border colors. Format: CLS [[BRIght] [BLInk] fg ON [BRIght] bg] [BORder bc] fg: The new foreground color. bg: The new background color. bc: The new border color. !TTY Usage CLS can be used to clear the screen without changing colors, or to clear the screen and change the screen colors simultaneously. These three examples show how to clear the screen to the default colors, to bright white letters on a blue background, and to bright yellow letters on a magenta background with a blue border: c:\> cls c:\> cls bright white on blue c:\> cls bri yel on mag bor blu CLS is often used in batch files to clear the screen before displaying text. See 892Colors and Color Names for details about colors and notes on the use of bright background colors. ;--------------------------------------------------------------------------- !TOPIC 605 COLOR !TTY Purpose: Change the default display colors. Format: COLOR [BRIght] [BLInk] fg ON [BRIght] bg [BORder bc] fg: The new foreground color. bg: The new background color. bc: The new border color. !TTY See also: 068SETCOLOR, 604CLS, and 892Colors and Color Names for details about using colors. Usage COLOR is normally used in batch files before displaying text. For example, to set screen colors to bright white on blue, you can use this command: c:\> color bright white on blue COLOR will not change anything on the screen. It will only set the default colors for subsequent screen displays. If you see odd characters like "[44;37m" when you try to set the screen colors, 4DOS probably thinks you have an ANSI driver loaded when you don't. Use 664SETDOS /A2, the Display page of the 648OPTION dialogs, or 412ANSI = No in 4DOS.INI, to tell 4DOS you have no ANSI driver. ;--------------------------------------------------------------------------- !TOPIC 606 COPY !TTY Purpose: Copy data between disks, directories, files, or physical hardware devices (such as your printer or serial port). Format: COPY [/A:[[+|-]rhsad] /C /E /G /H /I"text" /K /M /N /O /P /Q /R /S /T /U /V /X /Z] [@file] source[+] ... [/A /B] destination source: File or list of files or a device to copy from. destination: File, directory, or device to copy to. @file: Text file containing the names of the source files, one per line (see 057@file lists for details). /A(SCII) /O (copy if not exist) /A: (Attribute select) /P(rompt) /B(inary) /Q(uiet) /C(hanged) /R(eplace) /E (no error messages) /S(ubdirectories) /G (display percent) /T(otals) /H(idden) /U(pdate) /I (match description) /V(erify) /K(eep attributes) /X (clear archive) /M(odified) /Z (overwrite) /N(othing) !TTY See also: 596ATTRIB, 646MOVE, and 658REN. File Selection Supports extended 073wildcards, 074ranges, 079multiple file names, and 080include lists. 074Date, time, size, or 078exclude ranges anywhere on the line apply to all source files. Use extended wildcards with caution on LFN volumes; see 081LFN File Searches for details. Usage The COPY command accepts all traditional syntax and options and adds many new features. The simplest use of COPY is to make a copy of a file, like this example which makes a copy of a file called FILE1.ABC: c:\> copy file1.abc file2.def You can also copy a file to another drive and/or directory. The following command copies FILE1 to the \MYDIR directory on drive E: c:\> copy file1 e:\mydir Copying Files You must quote any file names which contain whitespace or special characters. See 945File Names for additional details. You can copy several files at once by using 073wildcards: c:\> copy *.txt e:\mydir You can also list several source files in one command. The following command copies 3 files from the current directory to the \MYDIR directory on drive E: c:\> copy file1 file2 file3 e:\mydir COPY also understands 080include lists, so you can specify several different kinds of files in the same command. This command copies the .TXT, .DOC, and .BAT files from the E:\MYDIR directory to the root directory of drive A: c:\> copy e:\mydir\*.txt;*.doc;*.bat a:\ If there is only one argument on the line, COPY assumes it is the source, and uses the current drive and directory as the destination. For example, the following command copies all the .DAT files on drive A to the current directory on drive C: c:\data> copy a:*.dat If there are two or more arguments on the line, separated by spaces, then COPY assumes that the last argument is the destination and copies all source files to this new location. If the destination is a drive, directory, or device name then the source files are copied individually to the new location. If the destination is a file name, the first source file is copied to the destination, and any additional source files are then appended to the new destination file. For example, the first of these commands copies the .DAT files from the current directory on drive A individually to C:\MYDIR (which must already exist as a directory); the second appends all the .DAT files together into one large file called C:\DATA (assuming C:\DATA is not a directory): c:>\ copy a:*.dat c:\mydir\ c:>\ copy a:*.dat c:\data When you copy to a directory, if you add a backslash [\] to the end of the name as shown in the first example above, COPY will display an error message if the name does not refer to an existing directory. You can use this feature to keep COPY from treating a mistyped destination directory name as a file name and attempting to append all your source files to a destination file, when you really meant to copy them individually to a destination directory. To copy a file to a device such as the printer, use the device name as the destination, for example: c:\> copy schedule.txt prn To copy text to or from the clipboard use CLIP: as the device name. Using CLIP: with non-text data will produce unpredictable results. See 051Redirection for additional information on CLIP:, including on when you can use the clipboard under 4DOS. Appending Files A plus [+] tells COPY to append two or more files to a single destination file. If you list several source files separated with [+] and don't specify a destination, COPY will use the name of the first source file as the destination, and append each subsequent file to the first file. For example, the following command will append the contents of C:\MEMO2 and C:\MEMO3 to C:\MEMO1 and leave the combined contents in the file named C:\MEMO1: c:\> copy memo1+memo2+memo3 To append the same three files but store the result in BIGMEMO: c:\> copy memo1+memo2+memo3 bigmemo If no destination is specified, the destination file will always be created in the current directory even if the first source file is in another directory or on another drive. For example, this command will append C:\MEM\MEMO2 and C:\MEM\MEMO3 to D:\DATA\MEMO1, and leave the result in C:\MEM\MEMO1: c:\mem> copy d:\data\memo1+memo2+memo3 You cannot append files to a device (such as a printer); if you try to do so, COPY will ignore the [+] signs and copy the files individually. If you attempt to append several source files to a destination directory or disk, COPY will append the files and place the copy in the new location with the same name as the first source file. Advanced Features If your destination has wildcards in it, COPY will attempt to match them with the source names. For example, this command copies the .DAT files from drive A to C:\MYDIR and gives the new copies the extension .DX: c:\> copy a:*.dat c:\mydir\*.dx This feature can give you unexpected results if you use it with multiple source file names. For example, suppose that drive A contains XYZ.DAT and XYZ.TXT. The command: c:\> copy a:\*.dat a:\*.txt c:\mydir\*.dx will copy A:XYZ.DAT to C:\MYDIR\XYZ.DX. Then it will copy A:XYZ.TXT to C:\MYDIR\XYZ.DX, overwriting the first file it copied. COPY also understands 080Include Lists, so you can specify several different kinds of files in the same command. This command copies the .TXT, .DOC, and .BAT files from the E:\MYDIR directory to the root directory of drive A: c:\> copy e:\mydir\*.txt;*.doc;*.bat a:\ You can use 074Date, Time, and Size Ranges to further define the files that you want to copy. This example copies every file in the E:\MYDIR directory, which was created or modified yesterday, and which is also 10,000 bytes or smaller in size, to the root directory of drive A: c:\> copy /[d-1] /[s0,10000] e:\mydir\*.* a:\ You can also use file 078exclusion ranges to restrict the list of files that would normally be selected with wildcards. This example copies every file in the E:\MYDIR directory except backup (.BAK or .BK!) files: c:\> copy /[!*.bak;*.bk!] e:\mydir\*.* a:\ COPY will normally process source files which do not have the hidden or system attribute, and will ignore the read-only and archive attributes. It will always set the archive attribute and clear the read-only attribute of destination files. In addition, if the destination is an existing file with the read-only attribute, COPY will generate an "Access Denied" error and refuse to overwrite the file. You can alter some of these behaviors with switches: !INDENT 10 5 5 5 /A: Forces COPY to process source files with the attributes you specify after the ":", or to process all source files regardless of attributes (if /A: is used by itself). /H Forces COPY to process hidden and system source files, as well as normal files. The hidden and system attributes from each source file will be preserved when creating the destination files. /K Retains the read-only attribute from each source file when creating the destination file. See /K below for a special note if you are running under Novell NetWare. /Z Forces COPY to overwrite an existing read-only destination file. !INDENT 0 Use caution with /A:, /H, or /K when both the source and destination directories contain file descriptions. If the source file specification matches the description file name (normally DESCRIPT.ION), and you use a switch which tells COPY to process hidden files, the DESCRIPT.ION file itself will be copied, overwriting any existing file descriptions in the destination directory. For example, if the \DATA directory contains file descriptions this command would overwrite any existing descriptions in the \SAVE directory: c:\data> copy /h d*.* \save\ If you remove the hidden attribute from the DESCRIPT.ION file the same caution applies even if you do not use /A:, /H, or /K, as DESCRIPT.ION is then treated like any other file. You can use an 078exclusion range to prevent the descriptions file from being copied: c:\data> copy /[!%192_dname] /h d*.* \save\ In an LFN environment, if you COPY files with long filenames to a volume which does not support them, 4DOS will store the destination files with their short, FAT-compatible names. You can view the short names before executing the COPY with the 612DIR /X command. See 945File Names for additional details. Options The /A(SCII) and /B(inary) options apply to the preceding filename and to all subsequent filenames on the command line until the file name preceding the next /A or /B, if any. The other options (/A:, /C, /E, /H, /K, /M, /N, /P, /Q, /R, /S, /T, /U, /V, /X, /Z) apply to all filenames on the command line, no matter where you put them. For example, either of the following commands could be used to copy a font file to the printer in binary mode: c:\> copy /b myfont.dat prn c:\> copy myfont.dat /b prn Some options do not make sense in certain contexts, in which case COPY will ignore them. For example, you cannot prompt before replacing an existing file when the destination is a device such as the printer -- there's no such thing as an "existing file" on the printer. If you use conflicting output options, like /Q and /P, COPY will generally take a "conservative" approach and give priority to the option which generates more prompts or more information. !INDENT 5 5 0 5 /A: (ASCII) If you use /A with a source filename, the file will be copied up to, but not including, the first Ctrl-Z (Control-Z or ASCII 26) character in the file. (Some old applications use the Ctrl-Z to mark the end of a file). If you use /A with a destination filename, a Ctrl-Z will be added to the end of the file. /A is the default when appending files, or when the destination is a device like NUL or PRN, rather than a disk file. Also see /B. /A:: (Attribute select) Select only those files that have the specified attribute(s) set. The colon [:] after /A is required. !INDENT 5 5 5 5 Preceding an attribute letter with a hyphen [-] will select files that do not have that attribute set. You can OR attributes by preceding each attribute letter with a plus sign [+]. The attributes are: R Read-only S System H Hidden A Archive If no attributes are listed at all (e.g., COPY /A: ...), COPY will select all files including hidden and system files (this is equivalent to COPY /H). If attributes are combined, all the specified attributes must match for a file to be selected. For example, /A:RHS will select only those files with all three attributes set. You must include the colon with this option to distinguish it from the /A(SCII) switch, above. See the cautionary note under Advanced Features above before using /A: when both source and destination directories contain file descriptions. !INDENT 5 5 0 5 /B: (Binary) If you use /B with a source filename, the entire file is copied; Ctrl-Z characters in the file do not affect the copy operation. Using /B with a destination filename prevents addition of a Ctrl-Z to the end of the destination file. /B is the default for normal file copies. Also see /A. /C: (Changed files) Copy files only if the destination file exists and is older than the source (see also /U). This option is useful for updating the files in one directory from those in another without copying any newly created files. (Before using /C in a network environment be sure to read the note under /U.) /E: (No Error messages) Suppress all non-fatal error messages, such as "File not found." Fatal error messages, such as "Drive not ready," will still be displayed. This option is most useful in batch files and aliases. /G: Displays the percent copied. This is useful when copying large files across a network to ensure the copy is proceeding. /H: (Hidden) Copy all matching files including those with the hidden and/or system attribute set. See the cautionary note under Advanced Features above before using /H when both source and destination directories contain file descriptions. /I"text": Select source files by matching text in their descriptions. The text can include 073wildcards and extended wildcards. The search text must be enclosed in quotation marks, and must follow the /I immediately, with no intervening spaces. You can select all filenames that have a description with /I"[?]*", or all filenames that do not have a description with /I"[]". /K: (Keep attributes) To maintain compatibility with COMMAND.COM and NetWare, COPY normally maintains the hidden and system attributes, sets the archive attribute, and removes the read-only attribute on the target file. /K tells COPY to also maintain the read-only attribute on the destination file. However, if the destination is on a Novell NetWare volume, this option will fail to maintain the read-only attribute. This is due to the way NetWare handles file attributes, and is not a problem in COPY. /M: (Modified) Copy only those files with the archive attribute set, i.e., those which have been modified since the last backup. The archive attribute of the source file will not be cleared after copying; to clear it use the /X switch or use 596ATTRIB. /N: (Nothing) Do everything except actually perform the copy. This option is useful for testing what the result of a complex COPY command will be. /N does not prevent creation of destination subdirectories when it is used with /S. /O: Only copy the source file if the target file doesn't exist. /P: (Prompt) Ask the user to confirm each source file. Your options at the prompt are explained in detail under 045Page and File Prompts. /Q: (Quiet) Don't display filenames or the total number of files copied. This option is most often used in batch files. See also /T. /R: (Replace) Prompt the user before overwriting an existing file. Your options at the prompt are explained in detail under 045Page and File Prompts. See also the 4DOS.INI 450CopyPrompt directive. /S: (Subdirectories) Copy the subdirectory tree starting with the files in the source directory plus each subdirectory below that. The destination must be a directory; if it doesn't exist, COPY will attempt to create it. COPY will also attempt to create needed subdirectories on the tree below the destination, including empty source directories. If COPY /S creates one or more destination directories, they will be added automatically to the 048Extended Directory Search database. !INDENT 5 5 5 5 If you attempt to use COPY /S to copy a subdirectory tree into part of itself, COPY will detect the resulting infinite loop, display an error message, and exit. Do not use /S with @file lists; see 057@file lists for details. Note that COPY /S will not search into subdirectories with the hidden or system attributes set unless you also specify /A: or /H. !INDENT 5 5 0 5 /T: (Totals) Turns off the display of filenames, like /Q, but does display the total number of files copied. /U: (Update) Copy each source file only if it is newer than a matching destination file or if a matching destination file does not exist (see also /C). This option is useful for keeping one directory matched with another with a minimum of copying. !INDENT 5 5 5 5 The time comparisons used with /U may not always work reliably across a network, due to differences in time zone and in the file time storage method between the local and remote systems. Be sure to do some non-destructive testing (e.g. with /N) before depending on this option to yield the results you want in a network environment. !INDENT 5 5 0 5 /V: (Verify) Verify each disk write. This is the same as executing the 682VERIFY ON command, but is only active during the COPY. /V does not read back the file and compare its contents with what was written; it only verifies that the data written to disk is physically readable. /X: (Clear Archive) Clear the archive attribute from the source file after a successful copy. This option is most useful if you are using COPY to maintain a set of backup files. /Z: (Overwrite) Overwrite read-only destination files. Without this option, COPY will fail with an "Access denied" error if the destination file has its read-only attribute set. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 776 COUNTRY !TTY Purpose: Display or change the current country. Format: COUNTRY [n] n: A country code. !TTY Usage COUNTRY can change "on the fly" the current country-specific DOS conventions for displaying dates and times inside vDosPlus. If you enter COUNTRY without a country code, the current country code is displayed. If you enter COUNTRY plus a country code, the country settings are changed. For example, to set the country settings to those for Germany: c:\> country 49 To set the country settings to those for Australia or International English: c:\> country 61 ;--------------------------------------------------------------------------- !TOPIC 607 CTTY !TTY Purpose: Change the default console device. Format: CTTY device device: The new console device. !TTY Usage Normally, 4DOS uses the keyboard as the standard input device and the display as the standard output device. Together, the keyboard and display are known as the console or CON. The CTTY command allows you to substitute another device that can perform standard character I/O for the console. For example to change the console to the first serial port: c:\> ctty com1 Change the console back to the standard keyboard and display (this command must be entered from the current console, e.g., a terminal attached to COM1, or from a batch file): c:\> ctty con CTTY works only for programs and commands that use standard DOS input and output functions. This includes all 4DOS internal commands except 616DRAWBOX, 617DRAWHLINE, 618DRAWVLINE, 640LIST, 660SCREEN, 661SCRPUT, 662SELECT, and 684VSCRPUT. In addition, if you use color-coded directories you should disable them with 612DIR /D when using CTTY. Otherwise, directories will not be displayed correctly. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 608 DATE !TTY Purpose: Display and optionally change the system date. Format: DATE [/T] [mm-dd-yy] /T: (Display only) mm: The month (1 - 12). dd: The day (1 - 31). yy: The year (00 - 99, or a 4-digit year). !TTY See also: 672TIME. Usage If you simply type DATE without parameters, you will see the current system date and time, and be prompted for a new date. Press ENTER if you don't wish to change the date. You can type a new date, but it will be ignored by vDosPlus unless you set the SYNCTIME=OFF directive in its config file. date Mon June 19, 2015 9:30:06 Enter new date (mm-dd-yy): You can also enter a new system date by typing the DATE command plus the new date on the command line: date 6-19-2015 Options !INDENT 5 5 0 5 /T: (Display only) Displays the current date but does not prompt for a new date. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 609 DEL !TTY Purpose: Erase one file, a group of files, or entire subdirectories. Format: DEL [/A:[[+|-]rhsad] /E /F /I"text" /N /P /Q /S /T /W /X /Y /Z] [@file] file... or ERASE [/A:[[+|-]rhsad] /E /F /I"text" /N /P /Q /S /T /W /X /Y /Z] [@file] file... file: The file, subdirectory, or list of files or subdirectories to erase. @file: A text file containing the names of the files or directories to delete, one per line (see 057@file lists for details). /A: (Attribute select) /S(ubdirectories) /E (no error messages) /T(otal) /F(orce delete) /W(ipe) /I (match descriptions) /X (remove empty subdirectories) /N(othing) /Y(es to all prompts) /P(rompt) /Z(ap hidden and read-only files) /Q(uiet) !TTY File Selection Supports extended 073wildcards, 074ranges (see below for conditions), 079multiple file names, and 080include lists. Use wildcards with caution on LFN volumes; see 081LFN File Searches for details. Usage DEL and ERASE are synonyms, you can use either one. Use the DEL and ERASE commands with caution; the files and subdirectories that you erase may be impossible to recover without specialized utilities and a lot of work. To erase a single file, simply enter the file name: c:\> del letters.txt You can also erase multiple files in a single command. For example, to erase all the files in the current directory with a .BAK or .PRN extension: c:\> del *.bak *.prn You must quote any file names which contain whitespace or special characters. See 945File Names for additional details. To exclude files from a DEL command, use a 078file exclusion range. For example, to delete all files in the current directory except those whose extension is .TXT, use a command like this: c:\> del /[!*.TXT] *.* When using exclusion ranges or other more complex options you may want to use the /N switch first, to preview the effects of the DEL without actually deleting any files. If you enter a subdirectory name, or a filename composed only of wildcards (* and / or ?), DEL asks for confirmation (Y or N) unless you specified the /Y option. If you respond with a Y, DEL will delete all the files in that subdirectory (hidden, system, and read-only files are only deleted if you use the /Z option). DEL displays the amount of disk space recovered, unless the /Q option is used (see below). It does so by comparing the amount of free disk space before and after the DEL command is executed. This amount may be incorrect if you are using a deletion tracking system which stores deleted files in a hidden directory, or if, under a multitasking system, another program performs a file operation while the DEL command is executing. Remember that DEL removes file descriptions along with files. Most deletion tracking systems will not be able to save or recover a file's description, even if they can save or recover the data in a file. Use caution when using wildcards with DEL under Windows 95/98/ME. For compatibility with COMMAND.COM, 4DOS's wildcard matching will match both short and long filenames. This can delete files you did not expect; see 081LFN File Searches for additional details. When a file is deleted, its disk space is returned to the operating system for use by other files. However, the contents of the file remain on the disk until they are overwritten by another file. If you wish to obliterate a file or wipe its contents clean, use DEL /W, which overwrites the file with zeros before deleting it. Use this option with caution once a file is obliterated, it is impossible to recover. DEL returns a non-zero exit code if no files are deleted, or if another error occurs. You can test this exit code with the 162%_? environment variable, and use it with 084conditional commands) (&& and ||). Options !INDENT 5 5 0 5 /A:: (Attribute select) Delete only those files that have the specified attribute(s) set. The colon [:] after /A is required. !INDENT 5 5 5 5 Preceding an attribute letter with a hyphen [-] will select files that do not have that attribute set. You can OR attributes by preceding each attribute letter with a plus sign [+]. The attributes are: R Read-only S System H Hidden A Archive If no attributes are listed at all (e.g., DEL /A: ...), DEL will delete all files including hidden and system files. If attributes are combined, all the specified attributes must match for a file to be selected for deletion. For example, /A:RHS will select only those files with all three attributes set. !INDENT 5 5 0 5 /E: (No error messages): Suppress all non-fatal error messages, such as "File not found." Fatal error messages, such as "Drive not ready," will still be displayed. This option is most useful in batch files and aliases. /F: (Force delete) This option has no effect in vDosPlus. /I"text": Select files by matching text in their descriptions. The text can include 073wildcards and extended wildcards. The search text must be enclosed in quotation marks, and must follow the /I immediately, with no intervening spaces. You can select all filenames that have a description with /I"[?]*", or all filenames that do not have a description with /I"[]". /N: (Nothing) Do everything except actually delete the file(s). This is useful for testing what the result of a DEL would be. /P: (Prompt) Prompt the user to confirm each erasure. Your options at the prompt are explained in detail under 045Page and File Prompts. /Q: (Quiet) Don't display filenames as they are deleted, or the number of files deleted or bytes freed. DEL will run fastest if you specify the /Q option and the filename doesn't use the extended 4DOS wildcards. /S: (Subdirectories) Delete the specified files in this directory and all of its subdirectories. This is can be used to delete all the files in a subdirectory tree or even a whole disk. It should be used with caution! Do not use /S with 057@file lists. Note that DEL /S will not search into subdirectories with the hidden or system attributes set unless you also specify /A: or /Z. /T: (Total) Don't display filenames as they are deleted, but display the total number of files deleted plus the amount of free disk space recovered. Unlike /Q, the /T option will not speed up deletions under DOS. /W: (Wipe) Clear the file to zeros before deleting it. Use this option to completely obliterate a file's contents from your disk. Once you have used this option it is impossible to recover the file even if you are using an undelete utility, because the contents of the file are destroyed before it is deleted. /W overwrites the file only once; it does not adhere to security standards which require multiple overwrites with varying data when destroying sensitive information. /X: (Remove subdirectories) Remove empty subdirectories after deleting (only useful when used with /S). If DEL deletes one or more directories, they will be removed automatically from the 048extended directory search. /Y: (Yes) The reverse of /P -- it assumes a Y response to everything, including deleting an entire subdirectory tree. 4DOS normally prompts before deleting files when the name consists only of wildcards or a subdirectory name (see above); /Y overrides this protection, and should be used with extreme caution! /Z: (Zap) Delete read-only, hidden, and system files as well as normal files. Files with the read-only, hidden, or system attribute set are normally protected from deletion; /Z overrides this protection, and should be used with caution. Because 623EXCEPT works by hiding files, /Z will override an EXCEPT command. However, files specified in a 078file exclusion range will not be deleted by DEL /Z. !INDENT 5 5 5 5 For example, to delete the entire subdirectory tree starting with C:\UTIL, including hidden and read-only files, without prompting (use this command with CAUTION!): c:\> del /sxyz c:\util\ !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 610 DELAY !TTY Purpose: Pause for a specified length of time. Format: DELAY [/B /M time] time: The number of seconds or milliseconds to delay. /B(reak enabled) /M(illiseconds) !TTY Usage DELAY is useful in batch file loops while waiting for something to occur. To wait for 10 seconds: delay 10 DELAY is most useful when you need to wait a specific amount of time for an external event, or check a system condition periodically. For example, this batch file checks the battery status (as reported by your Advanced Power Management drivers) every 15 seconds, and gives a warning when battery life falls below 30%: do forever iff %_apmlife lt 30 then beep 440 4 880 4 440 4 880 4 echo Low Battery!! endiff delay 15 enddo The time value can be as large as 1,073,741,823 seconds (over 34 years!). If you don't enter a time, the default is 1 second. 4DOS uses the minimum possible processor time during a DELAY, in order to allow other applications full use of system resources. You can cancel a delay by pressing Ctrl-C or Ctrl-Break. Options !INDENT 5 5 0 5 /B: (Break) Allows terminating a DELAY by pressing a key. ;!INDENT 5 5 5 5 /M: (Milliseconds) Count by milliseconds instead of seconds. Normally only used for delays of less than 1 second. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 611 DESCRIBE !TTY Purpose: Create, modify, or delete file and subdirectory descriptions. Format: DESCRIBE [/A:[[+|-]rhsad] /I"text"][@file] file [[/D]"desc"] file: The file, directory, or list of files and directories to operate on. @file: A text file containing the names of the files to describe, one per line (see 057@file lists for details). "desc": The description to attach to the file. /A: (Attribute select) /I (Match descriptions) /D(escription follows) !TTY File Selection Supports extended 073wildcards, 074ranges, 079multiple file names, and 080include lists. Usage DESCRIBE adds descriptions to files and subdirectories. The descriptions can be displayed by 612DIR in single-column mode, and by 662SELECT. Descriptions let you identify your files in much more meaningful ways than you can in an eight-character filename. You enter a description on the command line by typing the DESCRIBE command, the filename, and the description in quotation marks, like this: c:\> describe memo.txt "Memo to Bob about party" If you don't put a description on the command line, DESCRIBE will prompt you for it: c:\> describe memo.txt Describe "memo.txt" : Memo to Bob about party If you use wildcards or multiple filenames with the DESCRIBE command and don't include the description text, you will be prompted to enter a description for each file. If you do include the description on the command line, all matching files will be given the same description. You must quote the file name if it contains whitespace or special characters. See 945File Names for additional details. If you enter a quoted description on the command line, and the text matches the name of a file in the current directory, 4DOS will treat the string as a quoted file name, not as description text as you intended. To resolve this problem use the /D switch immediately prior to the quoted description (with no intervening spaces). For example, if the current directory contains the files DATA.TST and "Test File", the first of these commands will work as intended, but the second will not (in the second example the string "test file" will be treated as a second file name, when it is intended to be description text): c:\> describe data.tst /D"test file" c:\> describe data.tst "test file" On drives which support long file names you will not see file descriptions in a normal DIR display, because DIR must leave space for the long filenames. To view the descriptions, use DIR /Z to display the directory in FAT format. See 945File Names and the 612DIR command for more details. Each description can be up to 511 characters long. You can change this limit with the 422DescriptionMax directive in 4DOS.INI. In order to fit your descriptions on a single line in a standard DIR display, keep them to 39 characters or less (longer descriptions are wrapped in the DIR output). DESCRIBE can edit descriptions longer than DescriptionMax (up to 511 characters), but will not allow you to lengthen the existing text. The descriptions are stored in each directory in a hidden file called DESCRIPT.ION. Use the 596ATTRIB command to remove the hidden attribute from this file if you need to copy or delete it. DESCRIPT.ION is always created as a hidden file, but will not be re-hidden by 4DOS if you remove the hidden attribute. You can change the description file name with the 664SETDOS /D command, or the 423DescriptionName directive in 4DOS.INI, and retrieve it with the %192_DNAME internal variable. Use caution when changing the description file name, as changing the name from the default will make it difficult to transfer file descriptions to another system. The description file is modified appropriately whenever you perform an internal command which affects it (such as 606COPY, 646MOVE, 609DEL, or 658REN), but not if you use an external program (such as XCOPY or a visual shell). You can disable description processing on the Options 1 page of the 648OPTION dialogs, with the 424Descriptions directive in 4DOS.INI, or with 664SETDOS /D. When you COPY or MOVE files between two directories, both of which have descriptions, and you use switches which enable processing of hidden files (or you have removed the hidden attribute from DESCRIPT.ION), you must use caution to avoid overwriting existing file descriptions in the destination directory with the DESCRIPT.ION file from the source directory. See the notes under the Advanced Features sections of 606COPY and 646MOVE for additional details. Options !INDENT 5 5 0 5 /A:: (Attribute select) Select only those files that have the specified attribute(s) set. The colon [:] after /A is required. !INDENT 5 5 5 5 Preceding an attribute letter with a hyphen [-] will select files that do not have that attribute set. You can OR attributes by preceding each attribute letter with a plus sign [+]. The attributes are: R Read-only D subDirectory H Hidden A Archive S System If no attributes are listed at all (e.g., DESCRIBE /A: ...), DESCRIBE will select all files and subdirectories including hidden and system files. If attributes are combined, all the specified attributes must match for a file to be selected. For example, /A:RHS will select only those files with all three attributes set. !INDENT 5 5 0 5 /D: (Description follows) The quoted string immediately following this switch is a description, not a file name. Use /D to avoid any ambiguity in the meaning of quoted strings. See the Usage section above for details. /I"text": Select files by matching text in their descriptions. The text can include 073wildcards and extended wildcards. The search text must be enclosed in quotation marks, and must follow the /I immediately, with no intervening spaces. You can select all filenames that have a description with /I"[?]*", or all filenames that do not have a description with /I"[]". !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 612 DIR !TTY Purpose: Display information about files and subdirectories. !NOWRAP Format: DIR [/1 /2 /4 /A[[:][+|-]rhsad] /B /C[HP] /D /E /F /G /H /I"text" /J /K /L /M /N /O[[:][-]acdeginrsu] /P /R /S /T[:acw] /U[1|2] /V /W /X /Z] [file...] !WRAP file: The file, directory, or list of files or directories to display. /1 (one column) /L(ower case) /2 (two columns) /M (suppress footer) /4 (four columns) /N(ormal display) /A (Attribute select) /O(rder) /B(are) /P(ause) /C[HP] (Compression) /R (disable wRap) /D(isable color) /S(ubdirectories) /E (use upper case) /T (aTtribute) /F(ull path) /U (sUmmary information) /G (allocated size) /V(ertical sort) /H(ide dots) /W(ide) /I (match descriptions) /X (display short names) /J(ustify names) /Z (use FAT format) /K (suppress header) !TTY See also: 596ATTRIB, 611DESCRIBE, 662SELECT, and 664SETDOS. File Selection Supports extended 073wildcards, 074ranges, 079multiple file names, and 080include lists. Usage DIR can be used to display information about files from one or more of your disk directories, in a wide range of formats. Depending on the options chosen, you can display the file name, attributes, and size; the time and date of the last change to the file; the file description; and the file's compression ratio. You can also display information in 1, 2, 4, 5, or more columns, sort the files several different ways, use color to distinguish file types, and pause after each full screen. The various DIR displays are controlled through options or switches. The best way to learn how to use the many options available with the DIR command is to experiment. You will soon know which options you want to use regularly. You can select those options permanently by using the 595ALIAS command. You can override aliases by prefixing a switch with a - to disable it. For example, to display all the files in the current directory, in 2 columns, sorted vertically (down one column then down the next), and with a pause at the end of each page: dir /2/p/v To set up this format as the default, using an alias: alias dir=*dir /2/p/v You must quote any file names which contain whitespace or special characters. See 945File Names for additional details. The following sections group DIR's features together in several categories. Many of the sections move from a general discussion to more technical material. If you find some of the information in a category too detailed for your needs, feel free to skip to the beginning of the next section. The sections are: Selecting Files Default DIR Output Format Switching Formats Multiple Column Displays Color-Coded Directories Redirected Output Other Notes Options Selecting Files DIR can display information about a single file or about several, dozens, hundreds, or thousands of files at once. To display information about a single file, just add the name of the file to the DIR command line: dir january.wks The simplest way to view information about several files at once is to use 073wildcards. DIR can work with traditional wildcard characters (* and ?) and extended wildcards. For example to display all of the .WKS files in the current directory: dir *.wks To display all .TXT files whose names begin with A, B, or C: dir [abc]*.txt If you don't specify a filename, DIR defaults to *.* on traditional FAT drives, and * on LFN drives. This default displays all non-hidden files and subdirectories in the current directory. If you specify a filename for a non-LFN drive which includes some wildcards, and does not include an extension, DIR will append .* to it to match all extensions. If you link two or more filenames together with spaces, DIR will display all of the files that match the first name and then all of the files that match the second name. You may use a different drive and path for each filename. This example lists all of the .WKS and then all of the .WK1 files in the current directory: dir *.wks *.wk1 If you use an 080include list to link multiple filenames, DIR will display the matching filenames in a single listing. Only the first filename in an include list can have a path; the other files must be in the same path. This example displays the same files as the previous example, but the .WKS and .WK1 files are intermixed: dir *.wks;*.wk1 You can include files in the current or named directory plus all of its subdirectories by using the /S option. This example displays all of the .WKS and .WK1 files in the D:\DATA directory and each of its subdirectories: dir /s d:\data\*.wks;*.wk1 You can also select files by their attributes by using the /A option. For example, this command displays the names of all of the subdirectories of the current directory: dir /a:d Finally, with the /I option, DIR can select files to display based on their descriptions (see the 611DESCRIBE command for more information on file descriptions). DIR will display a file if its description matches the text after the /I switch. The search is not case sensitive. You can use wildcards and extended wildcards as part of the text. For example, to display any file described as a "Test File" you can use this command: dir /i"test file" If you want to display files that include the words "test file" anywhere in their descriptions, use extended wildcards like this: dir /i"*test file*" To display only those files which do not have descriptions, use: dir /I"[]" In addition, you can use 074ranges to select or exclude specific sets of files. For example, to display all files modified in the last week, all files except those with a .BAK extension, and all files over 500 KB in size: dir /[d-7] dir /[!*.bak] dir /[s500K] You can, of course, mix any of these file selection techniques in whatever ways suit your needs. Default DIR Output Format DIR's output varies based on the type of volume or drive on which the files are stored. If the volume supports long file names (VFAT volumes under Windows 95/98/ME), the default DIR format contains 4 columns: the date of the last file modification or write, the time of last write, the file size in bytes, and the file name. The name is displayed as it is stored on the disk, in upper, lower, or mixed case. DIR will wrap filenames from one line to the next if they are too long to fit the width of the display. The standard output format is: Volume in drive C is C - BOOTUP Serial number is ....:.... Directory of C:\4DOS\*.* 12-08-2002 12:17 . 12-08-2002 12:17 .. 1-04-2003 16:21 Test 1-10-2003 18:59 995 4dos7.pif 1-06-2003 7:50 273,406 4DOS.COM 1-09-2003 10:03 45 4DOS.INI (See Switching Formats below for information on changing the standard long filename format to allow room for file descriptions.) On FAT volumes which do not support long file names, the default DIR format contains 5 columns: the file name, the file size in bytes, the date of the last write, the time of the last write, and the files description. File names are listed in lower-case; directory names in upper case: Volume in drive C is C - BOOTUP Serial number is ....:.... Directory of C:\4DOS\*.* . 12-08-02 12:17 C:\4DOS .. 12-08-02 12:17 C:\ TEST 01-04-03 16:21 4dos7.pif 995 01-10-03 18:59 4DOS PIF file 4dos.com 273406 01-06-03 7:50 4DOS executable ... 4dos.ini 45 01-09-03 10:03 4DOS configuration ... DIR's output is normally sorted by name, with directories listed first. You can change the sort order with the /O option. For example, these two commands sort the output by date: the first command lists the oldest file first; the second command lists the oldest file last: dir /o:d dir /o:-d When displaying file descriptions, DIR wraps long lines to fit on the screen. DIR displays a maximum of 39 characters of text in each line of a description, unless your screen width allows a wider display. If you disable description wrapping with the /R option, the description is truncated at the right edge of the screen, and a right arrow [] is added at the end of the line to alert you to the existence of additional description text. DIR's default output is sorted. It displays directory names first, with "" inserted instead of a file size, and then filenames. DIR assumes that sequences of digits should be sorted numerically (for example, the file DRAW2 is listed before DRAW03 because 2 is numerically smaller than 03), rather than strictly alphabetically (where DRAW2 would come second because "2" is after "0" in alphanumeric order). You can change the sort order with the /O option. When DIR displays file names in a multi-column format, it sorts file names horizontally unless you use the /V option to display vertically sorted output. DIR's display can be modified in many ways to meet different needs. Most of the following sections describes the various ways you can change DIR's output format. Switching Formats On volumes which support long file names, you can force DIR to use a FAT-like format (file name first, followed by file information) with the /Z option. If necessary, DIR /Z truncates long file names on LFN drives, and adds a right arrow [] to show that the name contains additional characters. The standard LFN output format does not provide enough space to show descriptions along with file names. Therefore, if you wish to view file descriptions as part of the DIR listing on a volume which supports long file names, you must use the /Z option. 4DOS will display the alternate, short file names for files with long file names if you use the /X option. Used alone, /X causes DIR to display names in 2 columns after the size, time, and date: one column for alternate or short file names and the other for long file names. If a file does not have a short or alternate name which is different from the long filename, the first filename column is empty. If you use /X and /Z together under 4DOS, DIR will display the short or alternate file names in the FAT-style display format. If you use the /B option, DIR displays just file names and omits the file size, time stamp, and description for each file, for example: c:\> dir w* /b WINDOWS WINNT win311 WINALIAS WINENV.BTM ..... There are several ways to modify the display produced by /B. The /F option is similar to /B, but displays the full path and name of each file, instead of just its name. To view the same information for a directory and its subdirectories use /B /S or /F /S. You can use /B /X to display the short name of each file, with no additional information. To display the short version of both the path and file name for each file, use /F /X. For example: c:\> dir /x/f/s *.pif C:\MACH64\INSTALL.PIF C:\PROGRA~1\WINZIP\WZ.PIF C:\WINDOWS\DOSPRMPT.PIF C:\WINDOWS\STARTM~1\APPS&U~1\INFOSE~1.PIF C:\WINDOWS\STARTM~1\PROMPTS\4DOS.PIF C:\WINDOWS\STARTM~1\PROMPTS\TOCP.PIF C:\WINDOWS\STARTM~1\PROMPTS\SPECIAL\4DOS(R~1.PIF ..... Multiple Column Displays DIR has three options, /2, /4, and /W, that create multi-column displays. The /2 option creates a 2-column display. On drives which support long filenames, only the name of each file is displayed, with directory names placed in square brackets to distinguish them from file names. On drives which do not support long filenames, or when /Z or /X is used (see below), the display includes the name, file size, and time stamp for each file. The /4 option is similar to /2, but displays directory information in 4 columns. On drives which do not support long filenames, or when the /Z or /X is used (see below), the display shows the file name and the file size in kilobytes (KB), megabytes (MB) or gigabytes (GB), with "" in the size column for directories. The /W option displays directory information in 5 or more columns, depending on your screen width. Each entry in a DIR /W display contains either the name of a file or the name of a directory. Directory names are placed in square brackets to distinguish them from file names. If you use one of these options on a drive that supports long file names, and do not select an alternate display format with /Z or /X, the actual number of columns will be based on the longest name to be displayed and your screen width, and may be less than the number you requested (for example, you might see only three columns even though you used /4). If the longest name is too long to fit in on a single line the display will be reduced to one column, and each name will be wrapped, with "extra" blank lines added so that each name takes the same number of lines. On LFN drives you can use /Z with any of the multi-column options to create a traditional FAT-format display, with long names truncated to fit in the available space. If you use /X, the traditional FAT-format display is also used, but short names are displayed (rather than truncated long names). The following table summarizes the effects of different options on LFN drives: !NOWRAP 旼컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� � Display Columns � 旼컴컴컴컵컴컴컴컴컴컴컴컴컴컫컴컴컴컴컴컴컴컴컴컫컴컴컴컴컴컴컴컴컴캑 � Format � Normal � /2 or /4 � /W � 쳐컴컴컴컵컴컴컴컴컴컴컴컴컴컵컴컴컴컴컴컴컴컴컴컵컴컴컴컴컴컴컴컴컴캑 � Normal � 1 column, long � 2 - 4 columns, � No. of columns � � � names plus size, � long names only � based on longest � � � date, time � � name, long names � � � � � only � 쳐컴컴컴컵컴컴컴컴컴컴컴컴컴컵컴컴컴컴컴컴컴컴컴컵컴컴컴컴컴컴컴컴컴캑 � /Z � 1 column, � 2 - 4 columns, � 5+ columns, � � � truncated long � truncated long � truncated long � � � names plus size, � names plus other � names only � � � date, time � info � � 쳐컴컴컴컵컴컴컴컴컴컴컴컴컴컵컴컴컴컴컴컴컴컴컴컵컴컴컴컴컴컴컴컴컴캑 � /X � 1 column, both � 2 - 4 columns, � 5+ columns, � � � names plus size, � short names � short names � � � date, time � plus other info � only � 쳐컴컴컴컵컴컴컴컴컴컴컴컴컴컵컴컴컴컴컴컴컴컴컴컵컴컴컴컴컴컴컴컴컴캑 � /Z /X � 1 column, short � (Same as /X � (Same as /X � � � names plus size, � alone) � alone) � � � date, time � � � 읕컴컴컴컨컴컴컴컴컴컴컴컴컴컨컴컴컴컴컴컴컴컴컴컨컴컴컴컴컴컴컴컴컴켸 !WRAP Color-Coded Directories The DIR command can display each file name and the associated file information in a different color, depending on the file's extension. To choose the display colors, you must either use the 663SET command to create an environment variable called 133COLORDIR, or use the Commands page of the 648OPTION dialogs or a text editor to set the 463ColorDir directive in your .INI file. If you do not use the COLORDIR variable or the ColorDir directive, DIR will use the default screen colors for all files. If you use both the COLORDIR variable and the ColorDir directive, the environment variable will override the settings in your .INI file. You may find it useful to use the COLORDIR variable for experimenting, then to set permanent directory colors with the ColorDir directive. The format for both the COLORDIR environment variable and the ColorDir directive in the .INI file is: ext ... :ColorName; ... where "ext" is a file extension (which may include wildcards) or one of the following file types: DIRS Directories RDONLY Read-only files HIDDEN Hidden files SYSTEM System files ARCHIVE Files modified since the last backup and "ColorName" is any valid color name (see 892Colors and Color Names). Unlike most color specifications, the background portion of the color name may be omitted for directory colors. If you don't specify a background color, DIR will use the current screen background color. For example, to display the .COM and .EXE files in red on the current background, the .C and .ASM files in bright cyan on the current background, and the read-only files in blinking green on white (this should be entered on one line): c:\> set colordir=com exe:red; c asm:bright cyan; rdonly:blink green on white Extended 073wildcards can be used in directory color specifications. For example, to display .BAK, .BAX, and .BAC files in red: c:\> set colordir=BA[KXC]:red Redirected Output The output of the DIR command, like that of most other internal commands, can be redirected to a file, printer, serial port, or other device. However, you may need to take certain DIR command options into account when you redirect DIR's output. DIR wraps both long file names and file descriptions at the width of your display. Its redirected output will also wrap at the screen width. Use the /R option if you wish to disable wrapping of long descriptions. If you redirect a color-coded directory to a file, DIR will remove the color data as it sends the directory information to a file. It will usually do the same if you redirect output to a character device such as a printer or serial port. However, it is not always possible for DIR to tell whether or not a device is a character device. If you notice that non-colored lines are being sent to the output device and colored lines are appearing on your screen, you can use the /D option to temporarily disable color-coding when you redirect DIR's output. To redirect DIR output to the clipboard, use CLIP: as the output device name, for example: c:\> dir *.exe > clip: Other Notes If you have selected a specific country code for your system, DIR will display the date in the format for that country. The default date format is U.S. (mm-dd-yy). The separator character in the file time will also be affected by the country code. Thousands and decimal separators in numeric displays are affected by the country code, and by the 445ThousandsChar and 421DecimalChar settings selected on the Options 1 page of the 648OPTION dialogs, or in the .INI file. DIR can generally display any file date between January 1, 1980 and December 31, 2099 if the date is supplied properly by the operating system. DIR can handle directories of any size, limited only by available memory. Each short filename requires 64 bytes of memory, plus the size of the description (if any). For example, a system with just 128K of free memory can display up to about 2,000 files per directory. Additional space is required when using DIR /S, particularly with deeply-nested directories. Options Options on the command line apply only to the filenames which follow the option, and options at the end of the line apply to the preceding filename only. This allows you to specify different options for different groups of files, yet retains compatibility with the traditional DIR command when a single filename is specified. !INDENT 5 5 0 5 /1: (Single column) Display the filename, size, date, and time; also displays the description on drives which do not support long filenames. This is the default. If /T is used the attributes are displayed instead of the description; if /C or /O:c is used the compression ratio is displayed instead of the description. This option is most useful if you wish to override a default /2, /4, or /W setting stored in an alias. /2: (Two columns) Display just the filename, size, date, and time. See Multiple Column Displays above for more details. /4: (Four columns) Display just the filename and size, in K (kilobytes), M (megabytes) or G (gigabytes), with files between 1 and 9.9 megabytes and files over 1 gigabyte in size displayed in tenths (i.e. "2.4M"). See Multiple Column Displays above for more details. /A: (Attribute select) Display only those files that have the specified attribute(s) set. The colon [:] after /A is optional. !INDENT 5 5 5 5 Preceding an attribute letter with a hyphen [-] will select files that do not have that attribute set. You can OR attributes by preceding each attribute letter with a plus sign [+]. The attributes are: R Read-only D subDirectory H Hidden A Archive S System If no attributes are listed at all (e.g., DIR /A ...), DIR will display all files and subdirectories including hidden and system files. If attributes are combined, all the specified attributes must match for a file to be included in the listing. For example, /A:RHS will display only those files with all three attributes set. !INDENT 5 5 0 5 /B: (Bare) Suppress the header and summary lines, and display file or subdirectory names only, in a single column. This option is most useful when you want to redirect a list of names to a file or another program. If you use /B with /S, DIR will show the full path of each file (the same display as /F) instead of simply its name and extension. If you use /B with /X on an LFN drive, DIR will display the short name of each file instead of the long name. /C: (Compression) Display per-file and total compression ratio on compressed drives. The compression ratio is displayed instead of the file description or attributes. The ratio is left blank for directories and files with a length of 0 bytes, and for files on non-compressed drives. /C only works in single-column mode; it is ignored if /2, /4, or /W is used. !INDENT 5 5 0 5 /D: (Disable color coding) Temporarily disable directory color coding. May be required when color-coded directories are used and DIR output is redirected to a character device like the printer (e.g., PRN or LPT1 to 3) or serial port (e.g., AUX or COM1 to 4). /D is not required when DIR output is redirected to a file. /E: (Case) Display filenames in the traditional upper case; also see 664SETDOS /U and the 446UpperCase directive in 4DOS.INI. /F: (Full path) Display each filename with its drive letter and path in a single column, without other information. If you use /F with /X on a volume which supports long filenames, the "short" version of the entire path is displayed. /G: Display the allocated disk space instead of the actual size of each file. /H: (Hide dots) Suppress the display of the "." and ".." directories. /I"text": Select files by matching text in their descriptions. The text can include 073wildcards and extended wildcards. The search text must be enclosed in quotation marks, and must follow the /I immediately, with no intervening spaces. You can select all filenames that have a description with /I"[?]*", or all filenames that do not have a description with /I"[]". !INDENT 5 5 5 5 The /I option may be used to select files even if descriptions are not displayed (for example, if /2 is used). However, /I will be ignored if /C or /O:c is used. !INDENT 5 5 0 5 /J: (Justify names) Align filename extensions and display them in the traditional format. /K: (Suppress header) Suppress the disk and directory name display. /L: (Lower case) Display file and directory names in lower case; also see 664SETDOS /U and the 446UpperCase directive in 4DOS.INI. /M: (Suppress footer) Suppress the file and byte count totals display. /N: (Normal) Reset the DIR options to the default values. This is useful when you want to display some files in one format, and then change back to the defaults for another set of files. /O: (Order) Set the sorting order. You may use any combination of the following sorting options; if multiple options are used, the listing will be sorted with the first sort option as the primary key, the next as the secondary key, and so on: !INDENT 5 5 5 5 - Reverse the sort order for the next option. a Sort names and extensions in standard ASCII order, rather than sorting numerically when digits are included in the name or extension. c Sort by compression ratio (the least compressed file in the list will be displayed first). For single-column directory displays in the traditional short filename format, the compression ratios will be used as the basis of the sort and will also be displayed. For wider displays (/2, /4, and /W) and displays in LFN format, the compression ratios will be used to determine the order but will not be displayed. If /O:c is used with /CH or /CHP, the sort will be based on the host-drive compression ratios. For information on supported compression systems, see /C above. d Sort by date and time (oldest first); for drives which support long filenames, also see /T. e Sort by extension. g Group subdirectories first, then files. i Sort by the file description (ignored if /C or /O:c is also used). n Sort by filename (this is the default). r Reverse the sort order for all options. s Sort by size. u Unsorted. !INDENT 5 5 0 5 /P: (Pause) Wait for a key to be pressed after each screen page before continuing the display. Your options at the prompt are explained in detail under 045Page and File Prompts. /R: (Disable Wrap) Forces long descriptions to be displayed on a single line, rather than wrapped onto two or more lines. Use /R when output is redirected to a character device, such as a serial port or the printer; or when you want descriptions truncated, rather than wrapped, in the on-screen display. /S: (Subdirectories) Display file information from the current directory and all of its subdirectories. DIR will only display headers and summaries for those directories which contain files that match the filename(s), ranges, and attributes that you specify. Note that DIR /S will not search into subdirectories with the hidden or system attributes set unless you also specify /A:. /T: (Attribute display) Display the filenames and attributes. /T is ignored if /C or /O:c is also used. The attributes are displayed in the format RHDSA, with the following meanings: !INDENT 5 5 5 5 The attributes are: R Read-only D subDirectory H Hidden A Archive S System On drives which support long file names, if you wish to add another option after /T, you must start the next option with a forward slash. If you dont, 4DOS will interpret the /T as the /T:acw time display switch (see below) and the following character as a time selector. For example: c:\> dir /tz incorrect, will display error c:\> dir /t/z correct !INDENT 5 5 5 5 a Last access date (access time is not saved). c Creation date and time. w Last write date and time (default). !INDENT 5 5 0 5 /U: (Summary information) Only display the number of files, the total file size, and the total amount of disk space used. There are two additional /U options: !INDENT 5 5 5 5 /U1 Display summaries for each directory, but no total for each parent directory. /U2 Display grand total only. !INDENT 5 5 0 5 /V: (Vertical sort) Display the filenames sorted vertically rather than horizontally (use with the /2, /4, or /W options). /W: (Wide) Display filenames only, horizontally across the screen. On drives which do not support long filenames, or when used with /Z or /X under 4DOS, /W displays as many columns as it can fit into 4DOS window, using 16 characters in each column. Otherwise (i.e., when long filenames are displayed) the number of columns depends on the width of the longest name in the listing. See Multiple Column Display above for more details. /X: Selects short filenames in the /2, /4, /B, /W, and /Z displays, and short file and path names in the /F display. /Z: Display filenames on LFN drives in the traditional FAT format, with the short filename at the left and the description at the right. Long names will be truncated to 12 characters unless /X is also used; if the name is longer than 12 characters, it will be followed by a right arrow [] to show that one or more characters have been truncated. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 613 DIRHISTORY !TTY Purpose: Display, add to, clear, or read the directory history list. Format: DIRHISTORY [/A directory /F /P /R filename] directory: The name of a directory to be added to the directory history. filename: The name of a file containing entries to be added to the directory history. /A(dd) /P(ause) /F(ree) /R(ead) !TTY See also: 632HISTORY. Usage Every time you change to a new directory or drive, 4DOS record the current directory in an internal directory history list. See 040Directory History for information on directory history window, which allows you to use the list to return to a previous directory. Also see 047Directory Navigation. The DIRHISTORY command lets you view and manipulate the directory history list directly. If no parameters are entered, DIRHISTORY will display the current directory history list: c:\> dirhistory With the options explained below, you can clear the list, add new directories to the list without changing to them, save the list in a file, or read a new list from a file. The number of directories saved in the directory history list depends on the length of each directory name. The list size can be specified at startup from 256 to 2048 characters by using the 376DirHistory directive in 4DOS.INI. The default size is 256 characters. Your directory history list can be stored either locally (a separate history list for each copy of 4DOS) or globally (all copies of 4DOS share the same list). See 040Directory History for a discussion of local and global directory history lists. You can save the directory history list by redirecting the output of DIRHISTORY to a file. This example saves the history to a file called DIRHIST and reads it back again: c:\> dirhistory > dirhist ..... c:\> dirhistory /r dirhist Because the directory history stores each name only once, you don't have to delete its contents before reading back the file unless you want to delete the directories that were visited by the intervening commands. If you need to save your directory history at the end of each day's work, you might use commands like this in your AUTOEXEC.BAT or other startup file: if exist c:\dirhist dirhistory /r c:\dirhist alias shut*down `dirhistory > c:\dirhist` This restores the previous history list if it exists, then defines an alias which will allow you to save the history before shutting off the system. Options !INDENT 5 5 0 5 /A: (Add) Add a directory to the directory history list. /F: (Free) Erase all entries in the directory history list. /P: (Prompt) Wait for a key after displaying each page of the list. Your options at the prompt are explained in detail in 045Page and File Prompts. /R: (Read) Read the directory history from the specified file and append it to the list currently held in memory. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 614 DIRS !TTY Purpose: Display the current directory stack. Format: DIRS !TTY See also: 653PUSHD, 651POPD, and 047Directory Navigation. Usage The PUSHD command adds the current default drive and directory to the directory stack, a list that 4DOS maintains in memory. The POPD command removes the top entry of the directory stack and makes that drive and directory the new default. The DIRS command displays the contents of the directory stack, with the most recent entries last (i.e., the next POPD will retrieve the last entry that DIRS displays). The directory stack holds 511 characters, enough for 20 to 40 typical drive and directory entries. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 615 DO !TTY Purpose: Create loops in batch files. Format: DO [n | FOREVER] or DO varname = start TO end [BY n] or DO [WHILE | UNTIL] condition or DO varname IN [range /A:[[+|-]rhsad] /I"text" /L] [@]fileset commands [ITERATE] [LEAVE] commands ENDDO !TTY varname: The environment variable that will hold the loop counter, filename, or line from a file. n, start, end: Integers between 0 and 2,147,483,647 inclusive, or an internal variables or variable function that evaluates to such a value. condition: A test to determine if the loop should be executed. fileset: A list of wildcard patterns to match, or (if /L is specified) literal values to process. commands: One or more commands to execute each time through the loop. If you use multiple commands, they must be separated by command separators or be placed on separate lines. !TTY /A: (Attribute select) /I (match descriptions) /L(iteral arguments) !TTY File Selection Supports extended 073wildcards, 074ranges, and 080include lists for the fileset. Date, time, or size ranges must appear immediately following the IN keyword (not after the command itself, as with most 4DOS commands!) Usage DO can only be used in batch files. It cannot be used in aliases. DO can be used to create four different kinds of loops. The first, introduced by DO n, is a counted loop. The batch file lines between DO and ENDDO are repeated n times. For example: do 5 beep enddo You can also specify "forever" for n if you wish to create an endless loop (you can use LEAVE or 630GOTO to exit such a loop; see below for details). The second type of loop is similar to a "for loop" in programming languages like BASIC. DO creates an environment variable, varname, and sets it equal to the value start (if varname already exists in the environment, it will be overwritten). DO then begins the loop process by comparing the value of varname with the value of end. If varname is less than or equal to end, DO executes the batch file lines up to the ENDDO. Next, DO adds 1 to the value of varname, or adds the value n if BY n is specified, and repeats the compare and execute process until varname is greater than end. This example displays the even numbers from 2 through 20: do i = 2 to 20 by 2 echo %i enddo DO can also count down, rather than up. If n is negative, varname will decrease by n with each loop, and the loop will stop when varname is less than end. For example, to display the even numbers from 2 through 20 in reverse order, replace the first line of the example above with: do i = 20 to 2 by -2 The third type of loop is called a "WHILE loop" or "UNTIL loop." DO evaluates the condition, which can be any of the tests supported by the 633IF command, and executes the lines between DO and ENDDO according to the result. A WHILE loop ends when the condition becomes false; an UNTIL loop ends when the condition becomes true. WHILE tests the condition at the start of the loop. Therefore, if the condition is false when the loop starts, the statements within the loop will never be executed, and the batch file will continue with the statement after the ENDDO. UNTIL tests the condition at the end of the loop. Therefore, the statements within the loop will always be executed at least once. The fourth type of loop executes the lines between DO and ENDDO once for every filename in the fileset, or once for each argument (if you use the /L option). For example: do x in *.txt will execute the loop once for every .TXT file in the current directory; each time through the loop the variable x will be set to the name of the next file that matches the file specification. If, between DO and ENDDO, you create a new file that could be included in the list of files, it may or may not appear in an iteration of the DO loop. Whether the new file appears depends on its physical location in the directory structure, a condition over which 4DOS has no control. You can also execute the loop once for each line of text in a file by placing an [@] in front of the file name. If you have a file called DRIVES.TXT that contains a list of drives on your computer, one drive name per line, you can execute the loop once for each drive this way: do x in @drives.txt To execute the loop once for each line of text in the clipboard, use CLIP: as the file name (e.g. DO X IN @CLIP:). CLIP: will not return any data unless the clipboard contains text. See 051redirection for additional information on CLIP:, including details on when you can use the clipboard under 4DOS. Two special commands, ITERATE and LEAVE, can be used inside a DO / ENDDO loop. ITERATE ignores the remaining lines inside the loop and returns to the beginning of loop for another iteration (unless DO determines that the loop is finished). LEAVE exits from the current DO loop and continues with the line following ENDDO. Both ITERATE and LEAVE are most often used in an 633IF or 634IFF command: do while "%var" != "%var1" ... if "%var" == "%val2" leave enddo You can nest DO loops up to 15 levels deep. The DO and ENDDO commands must be on separate lines, and cannot be placed within a 085command group, or on the same line as other commands (this is the reason DO cannot be used in aliases). However, commands within the DO loop can use command groups or the 041command separator in the normal way. If you receive a stack overflow error when using DO in complex, nested command sequences, see the 574StackSize directive. You can exit from all DO / ENDDO loops by using GOTO to a line past the last ENDDO. However, be sure to read the cautionary notes about GOTO and DO under the 630GOTO command before using a GOTO in any other way inside any DO loop. You cannot use 659RETURN to return from a 629GOSUB while inside a DO loop. Options !INDENT 5 5 0 5 /A:: (Attribute select) Process only those files that have the specified attribute(s) set. The colon [:] after /A is required. !INDENT 5 5 5 5 Preceding an attribute letter with a hyphen [-] will select files that do not have that attribute set. You can OR attributes by preceding each attribute letter with a plus sign [+]. The attributes are: R Read-only D subDirectory H Hidden A Archive S System If no attributes are listed (e.g., DO I IN /A: *.*), DO will process all matching files and subdirectories, including any with the hidden or system attribute set. If attributes are combined, all the specified attributes must match for a file to be included. For example, /A:RHS will include only those files with all three attributes set. !INDENT 5 5 0 5 /I"text": Select filenames by matching text in their descriptions. The text can include 073wildcards and extended wildcards. The search text must be enclosed in quotation marks, and must follow the /I immediately, with no intervening spaces. You can select all filenames that have a description with /I"[?]*", or all filenames that do not have a description with /I"[]". /L: Specifies that the arguments in a DO x IN ... statement are literal text, not filenames. The arguments will be assigned (left to right) to the DO variable on each pass through the loop. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 616 DRAWBOX !TTY Purpose: Draw a box on the screen. Format: DRAWBOX ulrow ulcol lrrow lrcol style [BRIght] [BLInk] fg ON [BRIght] bg [FILl [BRIght] bgfill] [ZOOm] [SHAdow] ulrow: Row for upper left corner. ulcol: Column for upper left corner. lrrow: Row for lower right corner. lrcol: Column for lower right corner. style: Box drawing style: 0 No lines (box is drawn with blanks). 1 Single line. 2 Double line. 3 Single line top and bottom, double on sides. 4 Double line top and bottom, single on sides. fg: Foreground character color. bg: Background character color. bgfill: Background fill color (for the inside of the box). !TTY See also: 617DRAWHLINE and 618DRAWVLINE. Usage DRAWBOX is useful for creating attractive screen displays in batch files. For example, to draw a box around the edge of an 80x25 window with bright white lines on a blue background: drawbox 0 0 24 79 1 bri whi on blu fill blu See 892Colors and Color Names for details about colors and notes on the use of bright background colors. If you use ZOOM, the box appears to grow in steps to its final size. The speed of the zoom operation depends on the speed of your computer and video system. If you use SHADOW, a drop shadow is created by changing the characters in the row under the box and the 2 columns to the right of the box to normal intensity text with a black background (this will make characters displayed in black disappear entirely). The row and column values are zero-based, so on a standard 25 line by 80 column display, valid rows are 0 - 24 and valid columns are 0 - 79. If ulrow is set to 999, lrrow is assumed to be the desired height, and the box will be centered vertically. If ulcol is set to 999, lrcol is assumed to be the desired width, and the box will be centered horizontally. Unlike DRAWHLINE and DRAWVLINE, DRAWBOX does not automatically connect boxes to existing lines on the screen with the proper connector characters. If you want to draw lines inside a box and have the proper connectors drawn automatically, draw the box first, then use DRAWHLINE and DRAWVLINE to draw the lines. DRAWBOX uses the standard line and box drawing characters in the U.S. English extended ASCII character set. If your system is configured for a different country or language, or a font which does not include these characters, the box may not appear on your screen as you expect. DRAWBOX normally writes text directly to the screen. If you have an unusual display adapter which does not support direct video output, see the 572OutputBIOS directive. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 617 DRAWHLINE !TTY Purpose: Draw a horizontal line on the screen. Format: DRAWHLINE row column len style [BRIght] [BLInk] fg ON [BRIght] bg row: Starting row. column: Starting column. len: Length of line. style: Line drawing style: 1 Single line. 2 Double line. fg: Foreground character color. bg: Background character color. !TTY See also: 616DRAWBOX and 618DRAWVLINE. Usage DRAWHLINE is useful for creating attractive screen displays in batch files. It detects other lines and boxes on the display, and creates the appropriate connector characters when possible (not all types of lines can be connected with the available characters). For example, the following command draws a double line along the top row of the display with green characters on a blue background: drawhline 0 0 80 2 green on blue The row and column values are zero-based, so on a standard 25 line by 80 column display, valid rows are 0 - 24 and valid columns are 0 - 79. If row is set to 999, the line will be centered vertically. If column is set to 999, the line will be centered horizontally. See 892Colors and Color Names for details about colors and notes on the use of bright background colors. DRAWHLINE uses the standard line and box drawing characters in the U.S. English extended ASCII character set. If your system is configured for a different country or language, or a font which does not include these characters, the box may not appear on your screen as you expect. DRAWHLINE normally writes text directly to the screen. If you have an unusual display adapter which does not support direct video output, see the 572OutputBIOS directive. ;--------------------------------------------------------------------------- !TOPIC 618 DRAWVLINE !TTY Purpose: Draw a vertical line on the screen. Format: DRAWVLINE row col len style [BRIght] [BLInk] fg ON [BRIght] bg row: Starting row. col: Starting column. len: Length of line. style: Line drawing style: 1 Single line. 2 Double line. fg: Foreground character color. bg: Background character color. !TTY See also: 616DRAWBOX and 617DRAWHLINE. Usage DRAWVLINE is useful for creating attractive screen displays in batch files. It detects other lines and boxes on the display, and creates the appropriate connector characters when possible (not all types of lines can be connected with the available characters). For example, to draw a double width line along the left margin of the display with bright red characters on a black background: drawvline 0 0 25 2 bright red on black The row and column values are zero-based, so on a standard 25 line by 80 column display, valid rows are 0 - 24 and valid columns are 0 - 79. If row is set to 999, the line will be centered vertically. If column is set to 999, the line will be centered horizontally. See 892Colors and Color Names for details about colors and notes on the use of bright background colors. DRAWVLINE uses the standard line and box drawing characters in the U.S. English extended ASCII character set. If your system is configured for a different country or language, or a font which does not include these characters, the box may not appear on your screen as you expect. DRAWVLINE normally writes text directly to the screen. If you have an unusual display adapter which does not support direct video output, see the 572OutputBIOS directive. ;--------------------------------------------------------------------------- !TOPIC 619 ECHO !TTY Purpose: Enable or disable command echoing, or display the current status; display a message. Format: ECHO [ON | OFF | message] message: Text to display. !TTY See also: 620ECHOS, 689ECHOERR, 690ECHOSERR, 660SCREEN, 661SCRPUT, 664SETDOS and 671TEXT. Usage The ECHO command has two separate functions. The first is to change or display the current command-echo state. The second, more common use is to display a message on the screen. 4DOS has a separate echo capability for batch files and for the command line. The command-line ECHO state is independent of the batch file ECHO state; changing ECHO in a batch file has no effect on the display at the command prompt, and vice versa. To see the current echo state, use the ECHO command with no arguments. This displays either the batch file or command-line echo state, depending on where the ECHO command is performed. In a batch file, if you turn ECHO on, each line of the file is displayed before it is executed. If you turn ECHO off, each line is executed without being displayed. Regardless of the ECHO state, a batch file line that begins with the [@] character will not be displayed. To turn off batch file echoing without displaying the ECHO command, use this line: @echo off ECHO defaults to ON in batch files. The current ECHO state is inherited by called batch files. You can change the default setting to ECHO OFF with the 664SETDOS /V0 command, the Options 1 page of the 648OPTION dialogs, or the 414BatchEcho directive in 4DOS.INI. See 104Echoing in Batch Files for details. ECHO defaults to OFF at the command line. If you turn the command-line ECHO on, each command will be displayed before it is executed. This will let you see the command line after expansion of aliases and variables. The command-line ECHO is most useful when you are learning how to use advanced features. This example will turn command-line echoing on: c:\> echo on If the ECHO command is followed by anything other than ON or OFF, ECHO will treat it as a message to be displayed. This is most often used in 102batch files and 101aliases, but it can even be useful at the prompt to display the values of 161internal variables, 241functions, and so on. For example, a batch file might display a simple message to let the user know what's going on: echo Processing your print files... An alias might use ECHO to report the value of a variable or function: 595alias caps=`@echo Caplock is %_CAPSLOCK%%%` Note that this second use of the ECHO command is independent of the first. You can use ECHO to display a message regardless of the current command-echo state. The message is actually sent to standard output (stdout). Normally this is the screen, but it can be redirected with the usual 055operators. You could, for example, use ECHO to append a line to a text file: echo Starting backup at %230_isodate %219_time >>! c:\runlog.txt To include the 418command separator character [^] or the 050redirection and piping symbols [<>|] in an ECHO message, enclose them in quotes (see 118Argument Quoting) or precede them with the 086escape character. Trailing spaces in the message are normally ignored. To display trailing spaces, enclose them in back-quotes: echo Five spaces follow:` ` If you want to echo a blank line, or a line containing only the word ON or OFF, put a period immediately after the ECHO with no space between: echo. echo.on echo.off If you are writing a batch file and you want to display several lines or strings containing troublesome characters, or to display text without expanding variables and functions, consider using the 671TEXT command instead. ;--------------------------------------------------------------------------- !TOPIC 689 ECHOERR !TTY Purpose: Display a message to the standard error device. Format: ECHOERR message message: Text to display. !TTY See also: 619ECHO, 620ECHOS, 690ECHOSERR, 660SCREEN, 661SCRPUT and 671TEXT. Usage ECHOERR displays a message like ECHO, but sends its output to the standard error device stderr (usually the screen) instead of the standard output device. If the standard output of a batch file is redirected to a file or another device with > or >>, ECHOERR will still generate a screen message. You can redirect ECHOERR's output using redirection operators like >& and >&>, which affect stderr. See 050Redirection and Piping for more information about the standard output and standard error devices and redirection. To include the 418command separator character [^] or the 050redirection and piping symbols [<>|] in an ECHOERR message, enclose them in quotes (see 118Argument Quoting) or precede them with the 086escape character. Trailing spaces in the message are normally ignored. To display trailing spaces, enclose them in back-quotes: echoerr Five spaces follow:` ` ECHOERR can not be used to change or display the current command-echo state. Use 619ECHO to control echoing of commands in a batch file or at the prompt. ;--------------------------------------------------------------------------- !TOPIC 620 ECHOS !TTY Purpose: Display a message without a trailing carriage return and line feed. Format: ECHOS message message: Text to display. !TTY See also: 619ECHO, 689ECHOERR, 690ECHOSERR, 660SCREEN, 661SCRPUT, 671TEXT, and 684VSCRPUT. Usage ECHOS is useful for text output when you don't want to add a carriage return and line feed at the end of the line. For example, you can use ECHOS when you need to redirect control sequences to your printer; this example sends the sequence Esc P to the printer on LPT1: c:\> echos eP > lpt1: To include the 418command separator character [^] or the 050redirection and piping symbols [<>|] in an ECHOS message, enclose them in quotes (see 118Argument Quoting) or precede them with the 086escape character. If you want to embed a carriage return or other control character in the message, you can use the 246@CHAR function or an escape sequence. For instance, you might wish to print a carriage return at the start of your message to move the cursor to the start of the line, so you can overwrite text already on the screen. Use @CHAR[13] or %=r to print a carriage return: 615do i = 100 to 0 by -1 echos %=r%i` ` 610delay /m 1 enddo ECHOS does not translate or modify the message text. For example, carriage return characters are not translated to CR/LF pairs. ECHOS sends only the characters you specify. The only character you cannot put into an ECHOS message is the NUL character (ASCII 0). To include the 418command separator character [^] or the 050redirection and piping symbols [<>|] in an ECHOS message, enclose them in quotes (see 118Argument Quoting) or precede them with the 086escape character. Trailing spaces in the message are normally ignored. To display trailing spaces, enclose them in back-quotes, as in the example above. ECHOS can not be used to change or display the current command-echo state. Use 619ECHO to control echoing of commands in a batch file or at the prompt. ;--------------------------------------------------------------------------- !TOPIC 690 ECHOSERR !TTY Purpose: Display a message to the standard error device, without a trailing carriage return and line feed. Format: ECHOSERR message message: Text to display. !TTY See also: 619ECHO, 620ECHOS, 689ECHOERR, 660SCREEN, 661SCRPUT and 671TEXT. Usage ECHOSERR acts like ECHOS but sends its output to the standard error device stderr (usually the screen) instead of the standard output device. If the standard output of a batch file is redirected to a file or another device with > or >>, ECHOSERR will still generate a screen message. You can redirect ECHOSERR's output using redirection operators like >& and >&>, which affect stderr. See 050Redirection and Piping for more information about the standard output and standard error devices and redirection. If you want to embed a carriage return or other control character in the message, you can use the 246@CHAR function or an escape sequence. For instance, you might wish to print a carriage return at the start of your message to move the cursor to the start of the line, so you can overwrite text already on the screen. Use @CHAR[13] or %=r to print a carriage return: 615do i = 100 to 0 by -1 echoserr %=r%i` ` 610delay /m 1 enddo ECHOSERR does not translate or modify the message text. For example, carriage return characters are not translated to CR/LF pairs. ECHOSERR sends only the characters you specify. The only character you cannot put into an ECHOSERR message is the NUL character (ASCII 0). To include the 418command separator character [^] or the 050redirection and piping symbols [<>|] in an ECHOSERR message, enclose them in quotes (see 118Argument Quoting) or precede them with the 086escape character. Trailing spaces in the message are normally ignored. To display trailing spaces, enclose them in back-quotes, as in the example above. ECHOSERR can not be used to change or display the current command-echo state. Use 619ECHO to control echoing of commands in a batch file or at the prompt. ;--------------------------------------------------------------------------- !TOPIC 621 ENDLOCAL !TTY Purpose: Restore the saved disk drive, directory, environment, alias list, and special characters. Format: ENDLOCAL [exportvar] !TTY See also: 665SETLOCAL. Usage The SETLOCAL command in a batch file saves the current disk drive, default directory, all environment variables, the alias list, and the command separator, escape character, parameter character, decimal separator, and thousands separator. ENDLOCAL restores everything that was saved by the previous SETLOCAL command. For example, this batch file fragment saves everything, removes all aliases so that user aliases will not affect batch file commands, changes the disk and directory, changes the command separator, runs a program, and then restores the original values: setlocal unalias * cdd d:\test setdos /c~ program ~ echo Done! endlocal SETLOCAL and ENDLOCAL are nestable up to 8 levels deep within a batch file. You cannot use SETLOCAL and ENDLOCAL in an alias or at the command line. You can "export" environment variables from inside a SETLOCAL by specifying the variable names to be preserved following the ENDLOCAL. For example: setlocal set test=abcd endlocal test An ENDLOCAL is performed automatically at the end of a batch file if you forget to do so. If you invoke one batch file from another without using CALL, the first batch file is terminated, and an automatic ENDLOCAL is performed; the second batch file inherits the settings as they were prior to any SETLOCAL. ;--------------------------------------------------------------------------- !TOPIC 622 ESET !TTY Purpose: Edit environment variables and aliases. Format: ESET [/A /F /M] variable name... variable name: The name of an environment variable, alias, or function to edit. /A(lias) /M(aster environment) /F(unctions) !TTY See also: 595ALIAS, 678UNALIAS, 663SET, and 680UNSET. Usage ESET allows you to edit environment variables and aliases using line editing commands (see 032Command-Line Editing). For example, to edit the executable file search path use ESET PATH; to edit the alias D, use ESET D. ESET will search for environment variables first and then aliases. If you have an environment variable and an alias with the same name, ESET will edit the environment variable and ignore the alias unless you use the /A option. Environment variable and alias names are normally limited to 80 characters, and the name and value together normally cannot be longer than 511 characters. ESET can edit any variable provided the variable contains no more than 511 characters of text. If you have enabled global aliases (see 595ALIAS), any changes made to an alias with ESET will immediately affect all other copies of 4DOS which are using the same alias list. Options !INDENT 5 5 0 5 /A: (Alias) Edit the named alias even if an environment variable of the same name exists. If you have an alias and an environment variable with the same name, you must use this switch to be able to edit the alias. /F: (Functions) Edit the named user-defined function. /M: (Master environment) Edit an environment variable in the master environment rather than the local environment. This option is only useful from a secondary command shell (for example, when an application has "shelled to DOS"). /M only works for environment variables; it cannot be used to edit the primary shell's aliases. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 623 EXCEPT !TTY Purpose: Perform a command on all available files except those specified. Format: EXCEPT [/I"text"] (@file) (file) command file: The file or files to exclude from the command. @file: A text file containing the names of the files to exclude, one per line (see 057@file lists for details). command: The command to execute, including all appropriate arguments and switches. /I: (match description) !TTY See also: 596ATTRIB and 078File Exclusion Ranges. File Selection Supports extended 073wildcards, 074ranges, 079multiple file names, and 080include lists. Date, time, size, or file exclusion ranges must appear immediately after the EXCEPT keyword. Use wildcards with caution on LFN volumes; see 081LFN File Searches for details. Usage EXCEPT provides a means of executing a command on a group of files and/or subdirectories, and excluding a subgroup from the operation. EXCEPT is intended primarily as a helper for external utilities which do not offer exclusion ranges or any similar capability. The command may also be an internal command, alias or batch file. However, an 078exclusion range will generally be the preferable method for excluding files when using internal commands. You may use wildcards to specify the files to exclude from the command. The first example erases all the files in the current directory except those beginning with MEMO, and those whose extension is .WKS. The second example copies all the files and subdirectories on drive C to drive D except those in C:\MSC and C:\DOS, using the COPY command: c:\> except (memo*.* *.wks) erase *.* c:\> except (c:\msc c:\dos) copy c:\*.* d:\ /s Note that in the second example, EXCEPT is used to hide subdirectories, not files. Because COPY /S does not recurse into hidden directories by default, this prevents the contents of the specified subdirectories from being copied. Using EXCEPT to hide files from COPY /S would be less successful: c:\> except (*.tmp *.bak) copy c:\*.* d:\ /s Wrong! This command would temporarily hide all .TMP and .BAK files in the current directory before performing the COPY -- probably not what was intended! You must quote any file names inside the parentheses which contain whitespace or special characters (see 945File Names for details). For example, to copy all files except those in the "Program Files" directory to drive E:\: c:\> except ("Program Files") copy /s *.* e:\ EXCEPT will assume that the files to be excluded are in the current directory, unless another directory is specified explicitly. EXCEPT prevents operations on the specified file(s) by setting the hidden attribute, performing the command, and then clearing the hidden attribute. If the command is aborted in an unusual way, you may need to use the ATTRIB command to remove the hidden attribute from the file(s). Caution: EXCEPT will not work with programs or commands that ignore the hidden attribute or which work explicitly with hidden files, including 609DEL /Z, and the /H (process hidden files) switch available in some 4DOS file processing commands. 078File exclusion ranges provide a faster and more flexible method of excluding files from internal commands, and do not manipulate file attributes, as EXCEPT does. However, exclusion ranges can only be used with 4DOS internal commands; you must use EXCEPT for external commands. 074Date, time, and size ranges can be used immediately after the word EXCEPT to further qualify which files should be excluded from the command. If the command is an internal command that supports ranges, an independent range can also be used in the command itself. You can also use a file exclusion range within the EXCEPT command; however, this will select files to be excluded from EXCEPT, and therefore included in execution of the command. You can use 085command grouping to execute multiple commands with a single EXCEPT. For example, the following command copies all files in the current directory whose extensions begin with .DA, except the .DAT files, to the D:\SAVE directory, then changes the first two characters of the extension of the copied files to .SA: c:\data> except (*.dat) (copy *.da* d:\save ^ ren *.da* *.sa*) If you use 035filename completion to enter the filenames inside the parentheses, type a space after the open parenthesis before entering a partial filename or pressing Tab. Otherwise, the command-line editor will treat the open parenthesis as the first character of the filename to be completed. Options !INDENT 5 5 0 5 /I"text": Select files by matching text in their descriptions. The text can include 073wildcards and extended wildcards. The search text must be enclosed in quotation marks, and must follow the /I immediately, with no intervening spaces. You can select all filenames that have a description with /I"[?]*", or all filenames that do not have a description with /I"[]". !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 624 EXIT !TTY Purpose: Return from 4DOS. Format: EXIT [value] value: The numeric exit code to return. !TTY See also: 600CANCEL and 654QUIT. Usage EXIT terminates the current copy of 4DOS. Use it to return to an application when you have "shelled out" to work at the prompt, or to end a command-line session. To close the session, or to return to the application that started 4DOS, type: c:\> exit If you specify a value, EXIT will return that value to the program that started 4DOS. For example: c:\> exit 255 The value is a number you can use to inform the program of some result, such as the success or failure of a batch file and it can range from 0 - 255. This feature is most useful for systems which use batch files to automate their operation, such as bulletin boards, or custom application programs like databases that shell to 4DOS to perform certain tasks. You cannot EXIT from the primary 4DOS shell under DOS. If EXIT does not seem to have any effect, you are probably in the primary shell. Before exiting, 4DOS will execute the contents of any 1094EXIT batch file. ;--------------------------------------------------------------------------- !TOPIC 625 FFIND !TTY Purpose: Search for files by name or contents. Format: FFIND [/A[[:][+|-]rhsad] /B /C /D[list] /E /F /I /I"text" /K /L /M /N /O[[:][-]acdeginrsu] /P /R /S /[T|X]"xx" /U /V /Y] file... list: A list of disk drive letters (without colons). file: The file, directory, or list of files or directories to display. /A (Attribute select) /N(ot) /B(are) /O(rder) /C(ase sensitive) /P(ause) /D(rive) /R(everse) /E (upper case display) /S(ubdirectories) /F (stop after match) /T"xx" (text search string) /I(gnore wildcards) /U (summary only) /I"text" (match description) /V(erbose) /K (no headers) /X["xx"] (hex display/search string) /L(ine numbers) /Y (prompt to continue after match) /M (no footers) !TTY File Selection Supports extended 073wildcards, 074ranges, 079multiple file names, and 080include lists. Usage FFIND is a flexible search command that looks for files based on their names and their contents. Depending on the options you choose, FFIND can display filenames, matching text, or a combination of both in a variety of formats. If you want to search for files by name, FFIND works much like the DIR command. For example, to generate a list of all the .BTM files in the current directory, you could use the command c:\> ffind *.btm The output from this command is a list of full pathnames, followed by the number of files found. If you want to limit the output to a list of .BTM files which contain the string color, you could use this command instead: c:\> ffind /t"color" *.btm The output from this command is a list of files that contain the string "color" along with the first line in each file that contains that string. By default, FFIND uses a case-insensitve search, so the command above will include files that contain "COLOR", "Color", "color", or any other combination of upper-case and lower-case letters. If you would rather see the last line of each file that contains the search string, use the /R option, which forces FFIND to search from the end of each file to the beginning. This option will also speed up searches somewhat if you are looking for text that will normally be at the end of a file, such as a signature line: c:\> ffind /r /t"Sincerely," *.txt You can use extended wildcards in the search string to increase the flexibility of FFIND's search. For example, the following command will find .TXT files which contain either the string "June" or "July" (it will also find "Juny" and "Jule"). The /C option makes the search case-sensitive: c:\> ffind /c /t"Ju[nl][ey]" *.txt If you want to search for text that contains wildcard characters (*, ?, [, or ]), you can use the /I option to force FFIND to interpret these as normal characters instead of wildcards. The following command, for example, finds all .TXT files that contain a question mark: c:\> ffind /i /t"?" *.txt At times, you may need to search for data that cannot be represented by ASCII characters. You can use FFIND's /X option to represent the search string in hexadecimal format (this option also changes the output to show hexadecimal offsets rather than text lines). With /X the search must be represented by pairs of hexadecimal digits separated by spaces; a search of this type is always case-sensitive (in the example below, 41 63 65 is the hex code for "Ace"): c:\> ffind /x"41 63 65" *.txt You can use FFIND's other options to further specify the files for which you are searching and to modify the way in which the output is displayed. You must quote any file names which contain whitespace or special characters. See 945File Names for additional details. Options !INDENT 5 5 0 5 /A: (Attribute select) Find only those files that have the specified attribute(s) set. The colon [:] after /A is optional. !INDENT 5 5 5 5 Preceding an attribute letter with a hyphen [-] will select files that do not have that attribute set. You can OR attributes by preceding each attribute letter with a plus sign [+]. The attributes are: R Read-only D subDirectory H Hidden A Archive S System If no attributes are listed at all (e.g., FFIND /A ...), FFIND will display all files and subdirectories including hidden and system files. If attributes are combined, all the specified attributes must match for a file to be selected. For example, /A:RHS will select only those files with all three attributes set. !INDENT 5 5 0 5 /B: (Bare) Display file names only and omit the text that matches the search. This option is only useful in combination with /T or /X, which normally force FFIND to display file names and matching text. /C: (Case sensitive) Perform a case-sensitive search. This option is only valid with /T, which defaults to a case-insensitive search. It is not needed with a /X hexadecimal search, which is always case-sensitive. /D: (Drive) Search all files on one or more drives. If you use /D without a list of drives, FFIND will search the drives specified in the list of files. If no drive letters are listed, FFIND will search all of the current drive. You can include a list of drives or a range of drives to search as part of the /D option. For example, to search drives C:, D:, E:, and G:, you can use either of these commands: c:\> ffind /dcdeg ... c:\> ffind /dc-eg ... !INDENT 5 5 5 5 Drive letters listed after /D will be ignored when processing file names which also include a drive letter. For example, this command displays all the .BTM files on C: and E:, but only the .BAT files on D: c:\> ffind /s /dce *.btm d:\*.bat !INDENT 5 5 0 5 /E: (Upper case) Display filenames in the traditional upper case; also see 664SETDOS /U and the 446UpperCase directive in 4DOS.INI. /F: (First) Stops the search after the first match. /I: (Ignore wildcards) Only meaningful when used in conjunction with the /T"xx" option. Suppresses the recognition of wildcard characters in the search text. This option is useful if you need to search for characters that would normally be interpreted as wildcards: *, ?, [, and ]. /I"text": Select filenames by matching text in their descriptions. The text can include 073wildcards and extended wildcards. The search text must be enclosed in quotation marks, and must follow the /I immediately, with no intervening spaces. You can select all filenames that have a description with /I"[?]*", or all filenames that do not have a description with /I"[]". /K: (No headers) Suppress the display of the header or filename for each matching text line. /L: (Line numbers) Include the line number for each text line displayed. FFIND numbers lines beginning with 1, unless 475ListRowStart is set to 0 in 4DOS.INI. A new line is counted for every CR or LF character (FFIND determines automatically which character is used for line breaks in each file), or when line length reaches 511 characters, whichever comes first. /M: (No footers) Suppress the footer (the number of files and number of matches) at the end of FFIND's display. /N: (Not) Reverse the meaning of the search. /N will also set /B; i.e. searches are on a file-by-file basis. /O: (Order) Set the sort order for the files that FFIND displays. You may use any combination of the following sorting options; if multiple options are used, the listing will be sorted with the first sort option as the primary key, the next as the secondary key, and so on: !INDENT 5 5 5 5 - Reverse the sort order for the next option a Sort names and extensions in standard ASCII order, rather than sorting numerically when digits are included in the name or extension. c Sort by compression ratio (the least compressed file in the list will be displayed first). d Sort by date and time (oldest first); for LFN drives, also see /T. e Sort by extension. g Group subdirectories first, then files. i Sort by the file description (ignored if /C or /O:c is also used). n Sort by filename (this is the default). r Reverse the sort order for all options. s Sort by size. u Unsorted. !INDENT 5 5 0 5 /P: (Pause) Wait for a key to be pressed after each screen page before continuing the display. Your options at the prompt are explained in detail under 045Page and File Prompts. /R: (Reverse) Only meaningful when used in conjuction with the /T"xx" or /X options. Searches each file from the end backwards to the beginning. This option is useful if you want to display the last occurrence of the search string in each file instead of the first (the default). It can also speed up searches for information that is normally at the end of a file, such as a signature. /S: (Subdirectories) Display matches from the current directory and all of its subdirectories. Note that FFIND /S will not search into subdirectories with the hidden or system attributes set unless you also specify /A:. /T"xx": (Text search) Specify the text search string. /T must be followed by a text string in double quotes (e.g., /t"color"). FFIND will perform a case-insensitive search unless you also use the /C option. For a hexadecimal search and/or hexadecimal display of the location where the search string is found, see /X. You can specify a search string with either /T or /X, but not both. /U: (Summary) Only displays the summary line. /V: (Verbose) Show every matching line. FFIND's default behavior is to show only the first matching line then and then go on to the next file. This option is only valid with /T or /X. /X["xx xx ..."]: (Hexadecimal display / search) Specify hexadecimal display and an optional hexadecimal search string. !INDENT 5 5 5 5 If /X is followed by one or more pairs of hexadecimal digits in quotes (e.g., /x"44 63 65"), FFIND will search for that exact sequence of characters or data bytes without regard to the meaning of those bytes as text. If those bytes are found, the offset is displayed (in both decimal and hexadecimal). A search of this type will always be case-sensitive. If /X is not followed by a hexadecimal search string it must be used in conjunction with /T, and will change the output format to display offsets (in both decimal and hexadecimal) rather than actual text lines when the search string is found. For example, this command uses /T to display the first line in each .BTM file containing the word "hello": c:\> ffind /t"hello" *.btm --- c:\test.btm: echo hello If you use the same command with /X, the offset is displayed instead of the text: c:\> ffind /t"hello" /x *.btm --- c:\test.btm: Offset: 26 (1Ah) You can specify a search string with either /T or /X, but not both. !INDENT 5 5 0 5 /Y: (Prompt) Prompt to stop searching after each match. This option is most useful when you are using FFIND to search for one specific file, and don't want to display all files which include a particular search string. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 626 FOR !TTY Purpose: Repeat a command for several values of a variable. Format: FOR [/A:[[+|-]rhsad] /D /F ["options"] /H /I"text" /L /R [path]] %var IN ([@]set | start, step, end) [DO] command ... options: Parsing options for a "file parsing" FOR. path: The starting directory for a "recursive" FOR. %var: The variable to be used in the command ("FOR variable"). set: A set of values for the variable. start: The starting value for a "counted" FOR. step: The increment value for a "counted" FOR. end: The limit value for a "counted" FOR. command: A command or group of commands to be executed for each value of the variable. /A: (Attribute select) /I (match descriptions) /D(isable "/") /L (counted loop) /F(ile parsing) /R(ecursive) /H(ide dots) !TTY See also: 687LFNFOR. File Selection Supports extended 073wildcards, 074ranges, 079multiple file names, and 080include lists. Date, time, or size ranges must appear immediately after the FOR keyword. Use extended wildcards with caution on LFN volumes; see 081LFN File Searches for details. Usage FOR begins by creating a set. It then executes a command for every member of the set. The command can be an internal command, an alias, an external command, or a batch file. The members of the set can be a list of file names, text strings, a group of numeric values, or text read from a list of files. When the set is made up of text or several separate file names (not an include list), the elements must be separated by spaces, tabs, commas, or the switch character (normally a slash [/]). FOR includes a large number of options, some of which duplicate functions available in other 4DOS commands, and/or do not follow conventions you may find in our other commands. Most of these extra options are included for compatibility with CMD.EXE in the 25Windows NT line. However, we make them available in 4DOS, 0204NT, and Take Command so that aliases and batch files which use them can work under all three products. The first three sections below ("Working with Files", "Working with Text", and "Retrieving Text from Files") describe the traditional FOR command and the enhancements to it which are part of 4DOS. The sections on "Parsing Text from Files" and "Counted FOR Loops" describe features added for compatibility with CMD.EXE. The section entitled "Other Notes" contains information you may need if you use any aspect of the FOR command extensively. Working with Files Normally, the set is a list of files specified with wildcards. For example, if you use this line in a batch file: for %x in (*.txt) do list %x then LIST will be executed once for each file in the current directory with the extension .TXT. The FOR variable %x is set equal to each of the file names in turn, then the 640LIST command is executed for each file. (You could do the same thing more easily with a simple LIST *.TXT. We used FOR here so you could get a feel for how it operates, using a simple example. Many of the examples in this section are constructed in the same way.) The set can include multiple files or an include list, like this: for %x in (d:\*.txt;*.doc;*.asc) do type %x FOR supports 073wildcards and extended wildcards, as well as 072extended parent directory names (e.g., ...\*.txt to process all of the .TXT files that are contained in the directory 2 levels above the current directory). You must quote any file names within the set which contain whitespace or special characters. The same restriction applies to names returned in the FOR variable, if you pass them to 4DOS internal commands, or other commands which require quoting filenames with whitespace. FOR does not quote returned names automatically, even if you included quotes in the set. See 945File Names for additional details on file name quoting. If the set includes filenames, the file list can be further refined by using 074date, time, size and 078file exclusion ranges. The range or ranges must be placed immediately after the word FOR. Ranges will be ignored if no wildcards are used inside the parentheses. For example, this set is made up of all of the .TXT files that were created or updated on July 1, 2000: for /[d7-1-2000,+0] %x in (*.txt) do ... If the command is an internal command that supports ranges, an independent range can also be used in the command itself. You can also refine the list by limiting it with the /A: option to select only files that have specific attributes. By default, FOR works only with files in the current directory or a specified directory. With the /R option, FOR will also search for files in subdirectories. For example, to work with all of the .TXT files in the current directory and its subdirectories: for /r %x in (*.txt) do ... If you specify a directory name immediately after /R, FOR will start in that directory and then search each of its subdirectories. This example works with all of the .BAK files on drive D: for /r d:\ %x in (*.bak) do ... When you use wildcards to specify the set, FOR scans the directory and finds each file which matches the wildcard name(s) you specified. If, during the processing of the FOR command, you create a file that could be included in the set, it may or may not appear in a future iteration of the same FOR command. Whether the new file appears depends on its physical location in the directory structure. For example, if you use FOR to execute a command for all .TXT files, and the command also creates one or more new .TXT files, those new files may or may not be processed during the current FOR command, depending on where they are placed in the physical structure of the directory. This is an operating system constraint over which 4DOS has no control. Therefore, in order to achieve consistent results you should construct FOR commands which do not create files that could become part of the set for the current command. Working with Text The set can also be made up of text instead of file names. For example, to create three files named file1, file2, and file3, each containing a blank line: for %suffix in (1 2 3) do echo. > file%suffix You could also use the names of environment variables as the text. This example displays the name and content of several variables from the environment (see 131Using the Environment for details on the use of square brackets when expanding environment variables). Enter this on one line: for %var in (path prompt comspec) do echo %var=%[%var] Retrieving Text from Files FOR can extract text from files in two different ways. The first method extracts each line from each file in the set and places it in the variable. To use this method, place an [@] at the beginning of the set, in front of the file name or names. For example, if you have a file called DRIVES.TXT that contains a list of drives on your computer, one drive name per line (with a ":" after each drive letter), you can print the free space on each drive this way: for %d in (@drives.txt) do free %d > prn Because the [@] is also a valid filename character, FOR first checks to see if the file exists with the [@] in its name (i.e., a file named @DRIVES.TXT). If so, the filename is treated as a normal argument. If it doesn't exist, FOR uses the filename (without the [@]) as the file from which to retrieve text. If you use @CON as the filename, FOR will read from standard input (a redirected input file) or a pipe; see 050Redirection and Piping for more information). If you use @CLIP: as the filename, FOR will read any text available from the Windows clipboard (see 051Redirection for details on when you can use the clipboard under 4DOS). Parsing Text from Files The second method of working with text from files is to have FOR parse each line of each file for you. To begin a "file-parsing" FOR, you must use the /F option and then include one or more file names in the set. When you use this form of FOR, the variable must be a single letter, for example, %a. This method of parsing, included for compatibility with CMD.EXE, can be cumbersome and inflexible. For a more powerful method, use FOR with "@filename" as the set to retrieve each line from the file, as described in the previous section. Then use variable functions like 291@INSTR, 294@LEFT, 316@RIGHT, and 329@WORD to parse the line. By default, FOR will extract the first word or token from each line and return it in the variable. For example, to display the first word on each line in the file FLIST.TXT: for /f %a in (flist.txt) do echo %a You can control the way FOR /F parses each line by specifying one or more parsing options in a quoted string immediately after the /F. The available options are: !INDENT 5 5 5 5 skip=n: FOR /F will skip "n" lines at the beginning of each file before parsing the remainder of the file. tokens=n, m, ...: By default, FOR /F returns just the first word or "token" from each parsed line in the variable you named. You can have it return more than one token in the variable, or return tokens in several variables, with this option. This option is followed by a list of numbers separated by commas. The first number tells FOR /F which token to return in the first variable, the second number tells it which to return in the second variable, etc. The variables follow each other alphabetically starting with the variable you name on the FOR command line. This example returns the first word of each line in each text file in %d, the second in %e, and the third in %f: for /f "tokens=1,2,3" %d in (*.txt) do ... You can also indicate a range of tokens by separating the numbers with a hyphen [-]. This example returns the first word of each line in %p, the second through fifth words in %q, and the eighth word in %r: for /f "tokens=1,2-5,8" %p in (*.txt) do ... eol=c: If FOR /F finds the character "c" in the line, it will assume that the character and any text following it are part of a comment and ignore the rest of the line. delims=xxx...: By default, FOR /F sees spaces and tabs as word or token delimiters. This option replaces those delimiters with all of the characters following the equal sign to the end of the string. This option must therefore be the last one used in the quoted options string. !INDENT 0 You can also use FOR /F to parse a single string instead of each line of a file by using the string, in quotes, as the set. For example, this command will assign variable A to the string "this", B to "is", etc., then display "this" (enter the command on one line): for /f "tokens=1,2,3,4" %a in ("this is a test") do echo %a "Counted" FOR Loop The "counted FOR" loop is included only for compatibility with CMD.EXE. In most cases, you will find the 615DO command more useful for performing counted loops. In a counted FOR command, the set is made up of numeric values instead of text or file names. To begin a counted FOR command, you must use the /L option and then include three values, separated by commas, in the set. These are the start, step, and end values. During the first iteration of the FOR loop, the variable is set equal to the start value. Before each iteration, the variable is increased by the step value. The loop ends when the variable exceeds the end value. This example will print the numbers from 1 to 10: for /l %val in (1,1,10) do echo %val This example will print the odd numbers from 1 to 10 (1, 3, 5, 7, and 9): for /l %val in (1,2,10) do echo %val The step value can be negative. If it is, the loop will end when the variable is less than the end value. Other Notes You can use either % or %% in front of the variable name. Either form will work, whether the FOR command is typed from the command line or is part of an alias or batch file (some of the traditional command processors require a single % if FOR is used at the command line, but require %% if FOR is used in a batch file). The variable name can be up to 80 characters long. The word DO is optional. If you use a single-character FOR variable name, that name is given priority over any environment variable which starts with the same letter, in order to maintain compatibility with the traditional FOR command. For example, the following command tries to add a: and b: to the end of the PATH, but will not work as intended: c:\> for %p in (a: b:) do path %path;%p The "%p" in "%path" will be interpreted as the FOR variable %p followed by the text "ath", which is not what was intended. To get around this, use a different letter or a longer name for the FOR variable, or use square brackets around the variable name (see 131Using the Environment). FOR variables can be referenced like normal environment variables, but are not stored in the same way, and cannot be modified with the 663SET, 622ESET, or 680UNSET commands. The following example uses FOR with variable functions to delete the .BAK files for which a corresponding .TXT file exists in the current directory: c:\docs> for %file in (*.txt) do del %@name[%file].bak The above command would not work properly on an LFN drive, because the returned FILE variable might contain whitespace. To correct this problem, you would need two sets of quotes, one for DEL and one for %@NAME: c:\docs> for %file in (*.txt) do del "%@name["%file"].bak" You can use 085command grouping to execute multiple commands for each element in the set. For example, the following command copies each .WKQ file in the current directory to the D:\WKSAVE directory, then changes the extension of each file in the current directory to .SAV. This should be entered on one line: c:\text> for %file in (*.wkq) do (copy "%file" d:\wksave\ ^ ren "%file" *.sav) In a batch file you can use GOSUB to execute a subroutine for every element in the set. Within the subroutine, the FOR variable can be used just like any environment variable. This is a convenient way to execute a complex sequence of commands for every element in the set without CALLing another batch file. One unusual use of FOR is to execute a collection of batch files or other commands with the same parameter. For example, you might want to have three batch files all operate on the same data file. The FOR command could look like this: c:\> for %cmd in (filetest fileform fileprnt) do %cmd datafile This line will expand to three separate commands: filetest datafile fileform datafile fileprnt datafile The variable that FOR uses (the %CMD in the example above) is created in the environment and then erased when the FOR command is done. (For compatibility with COMMAND.COM, a single-character FOR variable is created in a special way that does not overwrite an existing environment variable with the same name.) When using a multi-character variable name you must be careful not to use the name of one of your environment variables as a FOR variable. For example, a command that begins c:\> for %path in ... will write over your current path setting, then erase the path variable completely when FOR is done. FOR statements can be nested; the permissible nesting level depends on the amount of free space in 4DOS's internal stack. If you receive a stack overflow error when using FOR in complex, nested command sequences, see the notes under the 574StackSize directive. Options !INDENT 5 5 0 5 /A:: (Attribute select) Process only those files that have the specified attribute(s) set. /A: will be used only when processing wildcard file names in the set. It will be ignored for filenames without wildcards or other items in the set. The colon [:] after /A is required. !INDENT 5 5 5 5 Preceding an attribute letter with a hyphen [-] will select files that do not have that attribute set. You can OR attributes by preceding each attribute letter with a plus sign [+]. The attributes are: R Read-only D subDirectory H Hidden A Archive S System If no attributes are listed (e.g., FOR /A: IN (*.*) DO ...), FOR will process all files and subdirectories including hidden and system files. If attributes are combined, all the specified attributes must match for a file to be included. For example, /A:RHS will include only those files with all three attributes set. For example, to process only those files with the archive attribute set: for /a:a %f in (*.*) echo %f needs a backup! !INDENT 5 5 0 5 /D: (Disable "/") Disables the special processing of the forward slash [/] character in the FOR set. For compatibility with certain versions of COMMAND.COM (those prior to Windows 95/98/ME), 4DOS normally treats a forward slash inside the set as an "escape" character, discard the slash, and return the character after the slash, followed by the remainder of the string. This behavior can be used in batch files to separate a string into individual characters (although 4DOS provides a much easier method with the 291@INSTR and 294@LEFT variable functions). !INDENT 5 5 5 5 The /D option must follow the FOR keyword and come before the variable name. These examples show the effects of /D: c:\> for %s in (/abcdef) do echo %s a bcdef c:\> for /d %s in (/abcdef) do echo %s /abcdef !INDENT 5 5 0 5 /F: (File parsing) Return one or more words or tokens from each line of each file in the set. The /F option can be followed by one or more options in a quoted string which control how the parsing is performed. See the details under "Parsing Text From Files", above. /H: (Hide dots) Suppress the assignment of the "." and ".." directories to FOR variable. /I"text": Select filenames by matching text in their descriptions. The text can include 073wildcards and extended wildcards. The search text must be enclosed in quotation marks, and must follow the /I immediately, with no intervening spaces. You can select all filenames that have a description with /I"[?]*", or all filenames that do not have a description with /I"[]". /L: (counted loop) Interpret the three values in the set as the start, step, and end values of a counted loop. See the details under "Counted FOR Loop", above. /R: (Recursive) Look in the current directory and all of its subdirectories for files in the set. If the /R is followed by a directory name, look for files in that directory and all of its subdirectories. Note that FOR /R will not search into subdirectories with the hidden or system attributes set. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 627 FREE !TTY Purpose: Display the total disk space, total bytes used, total bytes free, and the percent used on the specified (or default) drive(s). Format: FREE [drive: ...] drive: One or more drives to include in the report. !TTY See also: 645MEMORY. Usage FREE provides the same disk information as the external command CHKDSK, but without the wait, since it does not check the integrity of the file and directory structure of the disk. A colon [:] is required after each drive letter. This example displays the status of drives A and C: c:\> free a: c: If the volume serial number is available, it will appear after the drive label or name. ;--------------------------------------------------------------------------- !TOPIC 696 FUNCTION !TTY Purpose: Create a user-defined variable function. Format: FUNCTION [/P /R file...] [name[=][value]] file: One or more files to read for function definitions. name: The name of the function you want to display or set. value: Variable function to be substituted for the variable name. /P(ause) /R(ead file) !TTY See also: 699UNFUNCTION. Usage FUNCTION allows you to create or display user-defined variable functions that can be used everywhere 241variable functions are used. If you invoke FUNCTION with no parameters, it will display the current function list. If you include a name, with no equals sign or value, FUNCTION will display the current definition of that function. The name may include 073wildcards, in which case FUNCTION will display the current values, if any, of all functions matching that name. For example function *dx* will display all functions which contain dx in their name. If you include the equals sign and value, FUNCTION will create or update the function referred to by name. Parameters to the function are numbered from %0 to %255, and are replaced with the matching argument when the function is called. %1 is the first argument, %2 is the second, and so on. %0 is the function name. %n& contains all of the function's arguments starting with the nth; %& contains all arguments. If you wish to use a symbol other than the ampersand [&] to refer to multiple arguments, you can use the 439ParameterChar directive in 4DOS.INI or the 664SETDOS /P command to define a different parameter character. For example, the function: function leftmost=`%@left[1,%1]` will return the leftmost character in a string. Note that function definitions will nearly always contain references to variables, parameters, or other functions. To prevent these references from being expanded at the time the function is defined, use back-quotes around the function definition (as above.) See 118Argument Quoting for more information on using back-quotes to delay variable expansion. Local and Global Functions The functions can be stored in either a "local" or "global" list. With a local function list, any changes made to functions will only affect the current copy of 4DOS. They will not be visible in other shells or other sessions. A local function list is the default. With a global function list, all copies of 4DOS will share the same function list, and any changes made to functions in one copy will affect all other copies. You can control the type of function list on the Startup page of the 648OPTION dialogs, with the 387LocalFunctions directive in 4DOS.INI, or with the /L and /LF 352startup options. There is no fixed rule for determining whether to use a local or global function list. Depending on your work style, you may find it most convenient to use one type, or a mixture of types in different sessions or shells. We recommend that you start with the default approach, then modify it if you find a situation where the default is not convenient. Whenever you start a secondary shell which uses a local function list, it inherits a copy of the functions from the previous shell. However, any changes made to functions in the secondary shell will affect only that shell, and will be lost when the secondary shell exits. If you want changes made in a secondary shell to affect the previous shell, use a global function list in both shells. Options !INDENT 5 5 0 5 /P: (Pause) This option is only effective when FUNCTION is used to display existing definitions. It pauses the display after each page and waits for a keystroke before continuing (see 045Page and File Prompts). /R: (Read file) This option loads a function list from a file. The format of the file is the same as that of the FUNCTION display: !INDENT 5 5 5 5 name=value where name is the name of the function and value is its value. You can use an equal sign [=] or space to separate the name and value. Back-quotes are not required around the value. You can add comments to the file by starting each comment line with a colon [:]. You can load multiple files with one FUNCTION /R command by placing the names on the command line, separated by spaces: c:\> function /r func1.lst func2.lst Each definition in a FUNCTION /R file can be up to 511 characters long. The definitions can span multiple lines in the file if each line, except the last, is terminated with an 086escape character. If there is no filename argument and input is redirected, FUNCTION /R will read from stdin. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 628 GLOBAL !TTY Purpose: Execute a command in the current directory and its subdirectories. Format: GLOBAL [/H /I /P /Q] command command: The command to execute, including arguments and switches. /H(idden directories) /P(rompt) /I(gnore exit codes) /Q(uiet) !TTY Usage GLOBAL performs the command first in the current directory and then in every subdirectory under the current directory. The command can be an internal command, an alias, an external command, or a batch file. This example copies the files in every directory on drive A to the directory C:\TEMP: a:\> global copy *.* c:\temp If files with the same name are found in more than one directory on A:, assuming COPY is the default internal command, the one found last will be left in C:\TEMP. Which one of the identically named files is found last is unpredictable! If you use the /P option, GLOBAL will prompt for each subdirectory before performing the command. You can use this option if you want to perform the command in most, but not all subdirectories of the current directory. You can use 085command grouping to execute multiple commands in each subdirectory. For example, the following command copies each .TXT file in the current directory and all of its subdirectories to drive A. It then changes the extension of each of the copied files to .SAV: c:\> global (copy *.txt a: ^ ren *.txt *.sav) If you receive a stack overflow error when using GLOBAL in complex, nested command sequences, see the notes under the 574StackSize directive. Options !INDENT 5 5 0 5 /H: (Hidden directories) Forces GLOBAL to look for hidden and system subdirectories. If you don't use this switch, directories with either attribute will be ignored. /I: (Ignore exit codes) If this option is not specified, GLOBAL will terminate if the command returns a non-zero exit code. Use /I if you want the command to continue in additional subdirectories even if it returns an error in one subdirectory. Even if you use /I, GLOBAL will normally halt execution if 4DOS receives a Ctrl-C or Ctrl-Break. /P: (Prompt) Forces GLOBAL to prompt with each directory name before it performs the command. Your options at the prompt are explained in detail under 045Page and File Prompts. /Q: (Quiet) Do not display the directory names as each directory is processed. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 629 GOSUB !TTY Purpose: Execute a subroutine in the current batch file. Format: GOSUB label [variables] label: The batch file label at the beginning of the subroutine. variables: Optional GOSUB variables !TTY See also: 599CALL, 630GOTO and 659RETURN. Usage GOSUB can only be used in batch files. 4DOS allows subroutines in batch files. A subroutine must start with a label (a colon [:] followed by a one-word label name) which appears on a line by itself. Case differences are ignored when matching labels. The subroutine must end with a RETURN statement. The subroutine is invoked with a GOSUB command from another part of the batch file. After the RETURN, processing will continue with the command following the GOSUB command. For example, the following batch file fragment calls a subroutine which displays the directory and returns: echo Calling a subroutine gosub subr1 echo Returned from the subroutine quit :subr1 dir /a/w return GOSUB searches the entire batch file for the label, starting at the beginning of the file. If the label does not exist, the batch file is terminated with the error message "Label not found." You can define GOSUB variables by placing them after the label name on the GOSUB line. For example: Gosub Sub1 abc 15 "Hello World" The variable names are defined on the label line. For example: :Sub1 [str n world] defines three variables - %str (set to "abc"), %n (set to 15), and %world (set to "Hello World"). Note that the square brackets are required on the label line. GOSUB variables are only defined for the duration of the subroutine. They are not inherited by nested GOSUBs, and are destroyed by the RETURN statement. GOSUB calls with variables are limited to a maximum of 22 levels deep. (There is no numerical limit on normal GOSUB calls.) GOSUB variables are placed in the environment in a special form for the duration of the subroutine, and will "mask" any environment variables of the same name that existed before the subroutine was called. GOSUB variables can be referenced like normal environment variables, but are not stored in the same way, and cannot be modified with the 663SET, 622ESET, or 680UNSET commands. You cannot use SET within a subroutine to change the value of a GOSUB variable. If you attempt to do so, the SET command will set the standard environment variable of the same name, not the GOSUB variable, but this value will be "masked" by the GOSUB variable and will remain inaccessible until the subroutine ends. GOSUB saves the 634IFF and 615DO states, so IFF statements inside a subroutine won't interfere with statements in the part of the batch file from which the subroutine was called. You cannot 659RETURN from a GOSUB while inside a 615DO loop. If 4DOS reaches the end of the batch file while inside a subroutine, it will automatically return to the command after the GOSUB, just as if an explicit 659RETURN command had been included as the last line of the file. Subroutines can be nested; the permissible nesting level depends on the amount of free space in 4DOS's internal stack. If you receive a stack overflow error when using GOSUB in complex, nested command sequences, see the notes under the 574StackSize directive. ;--------------------------------------------------------------------------- !TOPIC 630 GOTO !TTY Purpose: Branch to a specified line inside the current batch file. Format: GOTO [/I] label label: The batch file label to branch to. /I(FF and DO continue) !TTY See also: 629GOSUB. Usage GOTO can only be used in batch files. After a GOTO command in a batch file, the next line to be executed will be the one immediately after the label. The label must begin with a colon [:] and appear on a line by itself. The colon is required on the line where the label is defined, but is not required in the GOTO command itself. Case differences are ignored when matching labels. Note: The COMMAND.COM limitation that only the first 8 characters in labels are used does not exist in 4DOS. Batch files relying on this limitation may not run correctly under 4DOS. This batch file fragment checks for the existence of the file TEST.TXT. If the file exists, the batch file jumps to C_EXISTS and copies all the files from the current directory to the root directory on A:. Otherwise, it prints an error message and exits. if exist test.txt goto C_EXISTS echo TEST.TXT doesn't exist - exiting. quit :C_EXISTS copy *.* a:\ GOTO searches the entire batch file for the label, starting at the beginning of the file. If the label does not exist, the batch file is terminated with the error message "Label not found." To avoid errors in the processing of nested statements and loops, GOTO cancels all active 634IFF statements and 615DO / ENDDO loops unless you use /I. This means that a normal GOTO (without /I) may not branch to any label that is between an IFF and the corresponding ENDIFF or between a DO and the corresponding ENDDO. For compatibility with CMD.EXE in the 25Windows NT line, the command GOTO :EOF will end processing of the current batch file if the label :EOF does not exist. However, this is less efficient than using the 654QUIT or 600CANCEL command to end a batch file. Options !INDENT 5 5 0 5 /I: (IFF and DO continue) Prevents GOTO from canceling IFF statements and DO loops. Use this option only if you are absolutely certain that your GOTO command is branching entirely within any current IFF statement and any active DO / ENDDO block. Using /I under any other conditions will cause an error later in your batch file. !INDENT 5 5 5 5 You cannot branch into another IFF statement, another DO loop, or a different IFF or DO nesting level, whether you use the /I option or not. If you do, you will eventually receive an "unknown command" error (or execution of the UNKNOWN_CMD 595alias) on a subsequent ENDDO, ELSE, ELSEIFF, or ENDIFF statement. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 697 HEAD !TTY Purpose: Display the beginning of the specified file(s). Format: HEAD [/A:[[+|-]rhsad] /Cn /I"text" /Nn /P /Q /V] [@file] file... file: The file or list of files that you want to display. @file: A text file containing the names of the files to display, one per line (see 057@file lists for details). /A: (Attribute select) /P(ause) /C (Number of bytes) /Q(uiet) /I (match description) /V(erbose) /N (Number of lines) !TTY See also: 640LIST, 698TAIL, and 677TYPE. File Selection Supports extended 073wildcards, 074ranges, 079multiple file names, and 080include lists. Usage The HEAD command displays the first part of a file. It is normally only useful for displaying ASCII text files. Executable files (.COM and .EXE) and many data files may be unreadable when displayed with HEAD because they include non-alphanumeric characters. You can press Ctrl-S to pause HEAD's display and then any key to continue. To display the first 15 lines of the files MEMO1 and MEMO2: c:\> head /n15 memo1 memo2 To display text from the clipboard, use CLIP: as the file name. CLIP: will not return any data unless the clipboard contains text. See 051redirection for additional information on CLIP:, including details on when you can use the clipboard under 4DOS. Options !INDENT 5 5 0 5 /A:: (Attribute select) Select only those files that have the specified attribute(s) set. The colon [:] after /A is required. Preceding an attribute letter with a hyphen [-] will select files that do not have that attribute set. You can OR attributes by preceding each attribute letter with a plus sign [+]. !INDENT 5 5 5 5 The attributes are: R Read-only S System H Hidden A Archive If no attributes are listed at all (e.g., HEAD /A: ...), HEAD will select all files including hidden and system files. If attributes are combined, all the specified attributes must match for a file to be selected. For example, /A:RHS will select only those files with all three attributes set. !INDENT 5 5 0 5 /C: Display the specified number of bytes. /C accepts b, k, or m modifiers at the end of the number. b is the number of 512-byte blocks, k is 1000's of bytes, K is kilobytes, m is millions of bytes, and M is megabytes. /I"text": Select files by matching text in their descriptions. The text can include 073wildcards and extended wildcards. The search text must be enclosed in quotation marks, and must follow the /I immediately, with no intervening spaces. You can select all filenames that have a description with /I"[?]*", or all filenames that do not have a description with /I"[]". /N: The number of lines to display. The default is 10. /P: (Pause) Prompt after displaying each page. Your options at the prompt are explained in detail under 045Page and File Prompts. /Q: (Quiet) Don't display a header for each file. This is the default behavior unless /V is specified. /V: (Verbose) Display a header for each file. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 631 HELP !TTY Purpose: Display help for internal and external commands. Format: HELP [topic] topic: A help topic, internal command, or external command. !TTY Usage If you type the command HELP by itself (or press F1 when the command line is empty), the table of contents is displayed. If you type HELP plus a topic name, that topic is displayed. For example: help copy displays information about the COPY command and its options. For more information on this help system see 014Help Reference. ;--------------------------------------------------------------------------- !TOPIC 632 HISTORY !TTY Purpose: Display, add to, clear, or read the history list. Format: HISTORY [/A command /F /N /P /R filename] command: A command to be added to the history list. filename: The name of a file containing entries to be added to the history list. /A(dd) /P(ause) /F(ree) /R(ead) /N(o duplicates) !TTY See also: 613DIRHISTORY and 643LOG. Usage 4DOS keeps a list of the commands you have entered on the command line. See 033Command History and Recall for information on command recall, which allows you to use the history list to repeat or edit commands you have previously executed. The HISTORY command lets you view and manipulate the command history list directly. If no parameters are entered, HISTORY will display the current command history list: c:\> history With the options explained below, you can clear the list, add new commands to the list without executing them, save the list in a file, or read a new list from a file. The number of commands saved in the history list depends on the length of each command line. The history list size can be specified at startup from 256 to 8192 characters (see the 382History directive). The default size is 1024 characters. Your history list can be stored either locally (a separate history list for each copy of 4DOS) or globally (all copies of 4DOS share the same list). For full details see the discussion of local and global history lists under 033Command History and Recall. You can use the HISTORY command as an aid in writing batch files by redirecting the HISTORY output to a file and then editing the file appropriately. However, it may be easier to use the 643LOG /H command for this purpose. You can disable the history list or specify a minimum command-line length to save on the Command Line page of the 648OPTION dialogs, or with the 433HistMin directive in 4DOS.INI. You can save the history list by redirecting the output of HISTORY to a file. This example saves the command history to a file called HISTFILE and reads it back again immediately. If you leave out the HISTORY /F command on the second line, the contents of the file will be appended to the current history list instead of replacing it: c:\> history > histfile c:\> history /f c:\> history /r histfile If you need to save your history at the end of each day's work, you might use commands like this in your AUTOEXEC.BAT or other startup file: if exist c:\histfile history /r c:\histfile alias shut*down `history > c:\histfile` This restores the previous history list if it exists, then defines an alias which will allow you to save the history before shutting off the system. Options !INDENT 5 5 0 5 /A: (Add) Add a command to the history list. This performs the same function as the Ctrl-K key at the command line (see 033Command History and Recall). /F: (Free) Erase all entries in the command history list. /N: (No duplicates) Removes duplicate entries (oldest first) from the history list. Also see the 451HistDups .INI directive. /P: (Prompt) Wait for a key after displaying each page of the list. Your options at the prompt are explained in detail under 045Page and File Prompts. /R: (Read) Read the command history from the specified file and append it to the history list currently held in memory. Each line in the file must fit within the 044command line length limit. !INDENT 5 5 5 5 If you are creating a HISTORY /R file by hand, and need to create an entry that spans multiple lines in the file, you can do so by terminating each line, except the last, with an 086escape character. However, you cannot use this method to exceed the command line length limit. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 633 IF !TTY Purpose: Execute a command if a condition or set of conditions is true. Format: IF [NOT] condition [.AND. | .OR. | .XOR. [NOT] condition ...] command or IF [NOT] condition [.AND. | .OR. | .XOR. [NOT] condition ...] (command) ELSE (command) condition: A test to determine if the command should be executed. command: The command to execute if the condition is true. !TTY See also: 634IFF, 287@IF. Usage IF is normally used only in aliases and batch files. It is always followed by one or more conditions and then a command. First, the conditions are evaluated. If they are true, the command is executed. Otherwise, the command is ignored. If you add a NOT before a condition, the command is executed only when the condition is false. You can link conditions with .AND., .OR., or .XOR., and you can group conditions with parentheses (see Combining Tests below). You can also nest IF statements. The conditions can test strings, numbers, the existence of a file or subdirectory, the exit code returned by the preceding external command, and the existence of aliases and internal commands. The command can be an alias, an internal command, an external command, or a batch file. The entire IF statement, including all conditions and the command, must fit on one line. Some examples of IF conditions and commands are included below; additional examples are included in the EXAMPLES.BTM file which came with 4DOS. You can use 085command grouping to execute multiple commands if the condition is true. For example, the following command tests if any .TXT files exist. If they do, they are copied to drive A: and their extensions are changed to .TXO: if exist *.txt (copy *.txt a: ^ ren *.txt *.txo) (Note that the IFF command provides a more structured method of executing multiple commands if a condition or set of conditions is true.) If you receive a stack overflow error when using IF in complex, nested command sequences, see the notes under the 574StackSize directive. Conditions The conditional tests listed in the following sections are available in both the IF and IFF commands. They fit into two categories: string and numeric tests, and status tests. The tests can use environment variables, internal variables and variable functions, file names, literal text, and numeric values as their arguments. String and Numeric Tests Six test conditions can be used to test character strings. The same conditions are available for both numeric and normal text strings (see below for details). In each case you enter the test as: string1 operator string2 The operator defines the type of test (equal, greater than or equal, and so on). You should always use spaces on both sides of the operator. The operators are: Operator Tests EQ or == string1 equal to string2 NE or != string1 not equal to string2 LT string1 less than string2 LE string1 less than or equal to string2 GE string1 greater than or equal to string2 GT string1 greater than string2 EQC string1 equal to string2, including character case When IF compares two character strings, it will use either a numeric comparison or a string comparison. A numeric comparison treats the strings as numeric values and tests them arithmetically. A string comparison treats the strings as text. The difference between numeric and string comparisons is best explained by looking at the way two values are tested. For example, consider comparing the values 2 and 19. Numerically, 2 is smaller, but as a string it is "larger" because its first digit is larger than the first digit of 19. So the first of these conditions will be true, and the second will be false: if 2 lt 19 ... if "2" lt "19" ... IF determines which kind of test to do by examining the first character of each string. If both strings begin with a numeric character (a digit, sign, or decimal separator), a numeric comparison is used. (If a string begins with a decimal separator it is not considered numeric unless the next character is a digit, and there are no more decimal separators within the string. For example, ".07" is numeric, but ".a" and ".07.50" are not.) If either value is non-numeric, a string comparison is used. To force a string comparison when both values are or may be numeric, use double quotes around the values you are testing, as shown above. Because the double quote is not a numeric character, IF performs a string comparison. Case differences are ignored in string comparisons (except by EQC). If two strings begin with the same text but one is shorter, the shorter string is considered to be "less than" the longer one. For example, "a" is less than "abc", and "hello_there" is greater than "hello". When you compare text strings, you may need to enclose the arguments in double quotes in order to avoid syntax errors which can occur if one of the argument values is empty (e.g., due to an environment variable which has never been assigned a value). This technique will not work for numeric comparisons, as the quotes will force a string compare, so with numeric tests you must be sure that all variables are assigned values before the test is done. Numeric comparisons work with both integer and decimal values. The values to be compared must contain only numeric digits, decimal points, and an optional sign (+ or -). The number may contain up to 20 digits to the left of the decimal point, and 10 digits to the right. 161Internal variables and 241variable functions are very powerful when combined with string and numeric comparisons. They allow you to test the state of your system, the characteristics of a file, date and time information, or the result of a calculation. You may want to review the variables and variable functions when determining the best way to set up an IF test. This batch file fragment tests for a string value: input "Enter your selection : " %%cmd if "%cmd" == "WP" goto wordproc if "%cmd" NE "GRAPHICS" goto badentry This example calls GO.BTM if the first two characters in the file MYFILE are "GO": if "%@left[2,%@line[myfile,0]]" == "GO" call go.btm The next two examples test whether there is more than 500 KBytes of free memory or more than 2 MBytes of free EMS memory (the EMS example only applies to 4DOS): c:\> if %@dosmem[K] gt 500 echo Over 500K free c:\> if %@ems[M] gt 2 echo Over 2 MB EMS free Status Tests These conditions test the system or 4DOS status. You can use internal variables and variable functions to test many other parts of the system status. DEFINED variable If the variable exists in the environment, the condition is true. This is equivalent to testing whether the variable is not empty, for example the following two commands are equivalent: if defined abc echo Hello if "%abc" != "" echo Hello Note that DEFINED tests only for environment variables, not for internal variables like _4VER or _ANSI. ERRORLEVEL [operator] n This test retrieves the exit code of the preceding external program. By convention, programs return an exit code of 0 when they are successful and a number between 1 and 255 to indicate an error. The condition can be any of the operators listed above (EQ, !=, GT, etc.). If no operator is specified, the default is GE. The comparison is done numerically. Not all programs return an explicit exit code. For programs which do not, the behavior of ERRORLEVEL is undefined. EXIST filename If the file exists, the condition is true. You can use wildcards in the filename, in which case the condition is true if any file matching the wildcard name exists. Do not use IF EXIST to test for existence of a directory (use IF ISDIR instead). Due to variations in operating system internals, IF EXIST will not return consistent results when used to test for the existence of a directory. ISALIAS aliasname If the name is defined as an alias, the condition is true. ISDIR | DIREXIST path If the subdirectory exists, the condition is true. ISFUNCTION functionname If the name is defined as a user-defined function, the condition is true. ISINTERNAL command If the specified command is an active internal command, the condition is true. Commands can be activated and deactivated with the 664SETDOS /I command. ISLABEL labelname If the specified name exists as a label in the current batch file, the condition is true. Labels may be one or more words long. The first batch file fragment below tests for the existence of A:\JAN.DOC before copying it to drive C (this avoids an error message if the file does not exist): if exist a:\jan.doc copy a:\jan.doc c:\ This example tests the exit code of the previous program and stops all batch file processing if an error occurred: if errorlevel == 0 goto success echo "External Error -- Batch File Ends!" cancel Combining Tests You can negate the result of any test with NOT, and combine tests of any type with .AND., .OR., and .XOR.. When two tests are combined with .AND., the result is true if both individual tests are true. When two tests are combined with .OR., the result is true if either (or both) individual tests are true. When two tests are combined with .XOR., the result is true only if one of the tests is true and the other is false. This example runs a program called DATALOAD if today is Monday or Tuesday: if "%_dow" == "Mon" .or. "%_dow" == "Tue" dataload Test conditions are always scanned from left to right -- there is no implied order of precedence, as there is in some programming languages. You can, however, force a specific order of testing by grouping conditions with parentheses, for example (enter this on one line): if (%a == 1 .or. (%b == 2 .and. %c == 3)) echo something Parentheses can only be used when the portion of the condition inside the parentheses contains at least one ".and.", ".or.", or ".xor.". Parentheses on a simple condition which does not combine two or more tests will be taken as part of the string to be tested, and will probably make the test fail. For example, the first of these IF tests would fail; the second would succeed: if (a == a) ... if (a == a .and. b == b) ... Parentheses can be nested. Under 4DOS, the permissible nesting level depends on the amount of free space in 4DOS's internal stack; if you receive a stack overflow error when using nested parentheses, see the notes under the 574StackSize directive. ;--------------------------------------------------------------------------- !TOPIC 634 IFF !TTY Purpose: Perform IF / THEN / ELSE conditional execution of commands. Format: IFF [NOT] condition [.AND. | .OR. | .XOR. [NOT] condition ...] THEN ^ commands [ELSEIFF condition THEN ^ commands] ... [ELSE ^ commands] ^ ENDIFF condition: A test to determine if the command(s) should be executed. commands: One or more commands to execute if the condition(s) is true. If you use multiple commands, they must be separated by command separators or be placed on separate lines of a batch file. !TTY See also: 633IF and 287@IF. Usage IFF is similar to the IF command, except that it can perform one set of commands when a condition or set of conditions is true and a different set of commands when the conditions are false. IFF can also execute multiple commands when the conditions are true or false; IF normally executes only one command. IFF imposes no limit on the number of commands and is generally a "cleaner" and more structured command than IF. IFF is always followed by one or more conditions. If they are true, the commands that follow the word THEN are executed. Additional conditions can be tested with ELSEIFF. If none of these conditions are true, the commands that follow the word ELSE are executed. After the selected commands (if any) are executed, processing continues after the word ENDIFF. If you add a NOT before the condition, the THEN commands are executed only when the condition is false and the ELSE commands are executed only when the condition is true. The commands may be separated by command separators, or may be on separate lines of a batch file. You should include a command separator or a line break after a THEN, before an ELSEIFF, and before and after an ELSE. IFF supports all of the same conditions as IF including string and numeric comparisons, DEFINED, ERRORLEVEL, EXIST, ISALIAS, ISDIR / DIREXIST, ISFUNCTION, ISINTERNAL, and ISLABEL. See 633IF for details on these conditions, and on linking them together using the .AND. .OR. and .XOR. operators and parentheses. You can nest IFF statements up to 15 levels deep. The commands can include any internal command, alias, external command, or batch file. 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 above example uses 915ANSI color sequences in the prompt. See 652PROMPT for additional details. The alias in this second example 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): c:\> alias prune `iff isdir %1 then ^ del /sxz %1 ^ else ^ echo Not a directory!^endiff` Be sure to read the cautionary notes about GOTO and IFF under the 630GOTO command before using a GOTO inside an IFF statement. If you pipe data to an IFF, the data will be passed to the command(s) following the IFF, not to IFF itself. ;--------------------------------------------------------------------------- !TOPIC 635 INKEY !TTY Purpose: Get a single keystroke from the user and store it in an environment variable. Format: INKEY [/C /D /K"keys" /M /P /Wn /X] [prompt] %%varname prompt: Optional text that is displayed as a prompt. varname: The variable that will hold the user's keystroke. /C(lear buffer) /P(assword) /D(igits only) /W(ait) /K (valid keystrokes) /X (no carriage return) /M(ouse button) !TTY See also: 636INPUT and 638KEYSTACK. Usage INKEY optionally displays a prompt. Then it waits for a specified time or indefinitely for a keystroke, and places the keystroke into an environment variable. It is normally used in batch files and aliases to get a menu choice or other single-key input. Along with the INPUT command, INKEY allows great flexibility in reading input from within a batch file or alias. If prompt text is included in an INKEY command, it is displayed while INKEY waits for input. The following batch file fragment prompts for a character and stores it in the variable NUM: inkey Enter a number from 1 to 9: %%num INKEY reads standard input for the keystroke, so it will accept keystrokes from a redirected file or from the 53Keystack. You can supply a list of valid keystrokes with the /K option. Standard keystrokes with ASCII values between 1 and 255 are stored directly in the environment variable. Extended keystrokes (for example, function keys and cursor keys) are stored as a string in decimal format, with a leading @ (for example, the F1 key is @59). The Enter key is stored as an extended keystroke, with the code @28. See 911ASCII and Key Codes for a list of the ASCII and extended key codes. To test for a non-printing ASCII keystroke returned by INKEY use the 243@ASCII function to get the numeric value of the key. For example, to test for Esc, which has an ASCII value of 27: inkey Enter a key: %%key if "%@ascii[%key]" == "27" echo Esc pressed If you press Ctrl-C or Ctrl-Break while INKEY is waiting for a key, execution of an alias will be terminated, and execution of a batch file will be suspended while you are asked whether to cancel the batch job. A batch file can handle Ctrl-C and Ctrl-Break itself with the 647ON BREAK command. Options !INDENT 5 5 0 5 /C: (Clear buffer) Clears the keyboard buffer before INKEY accepts keystrokes. If you use this option, INKEY will ignore any keystrokes which you type, either accidentally or intentionally, before INKEY is ready to accept input. /D: (Digits only) Prevents INKEY from accepting any keystroke except a digit from 0 to 9. /K"keys": (Valid keystrokes) Specify the permissible keystrokes. The list of valid keystrokes should be enclosed in double quotes. For alphabetic keys the validity test is not case-sensitive. You can specify extended keys by enclosing their names in square brackets (within the quotes), for example: !INDENT 5 5 5 5 inkey /k"ab[Alt-F10]" Enter A, B, Alt-F10 %%var See 893Keys and Key Names for a complete listing of the key names you can use within the square brackets, and a description of the key name format. If an invalid keystroke is entered, 4DOS will echo the keystroke if possible, beep, move the cursor back one character, and wait for another keystroke. !INDENT 5 5 0 5 /M: (Mouse buttons) Returns @240 for the left button, @241 for the right button, and @242 for the middle button. /P: (Password) Prevents INKEY from echoing the character. /W: (Wait) Timeout period, in seconds, to wait for a response. If no keystroke is entered by the end of the timeout period, INKEY returns with the variable unchanged. This allows you to continue the batch file if the user does not respond in a given period of time. You can specify /W0 to return immediately if there are no keys waiting in the keyboard buffer. /X: (No carriage return) Prevents INKEY from displaying a carriage return and line feed after the user's entry. !INDENT 5 5 5 5 For example, the following batch file fragment waits up to 10 seconds for a character, then tests to see if a "Y" was entered: set net=N inkey /K"YN" /w10 Load network (Y/N)? %%net iff "%net" == "Y" then rem Commands to load the network go here endiff !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 636 INPUT !TTY Purpose: Get a string from the keyboard and save it in an environment variable. Format: INPUT [/C /D /E /Ln /N /P /Wn /X] [prompt] %%varname prompt: Optional text that is displayed as a prompt. varname: The variable that will hold the user's input. /C(lear buffer) /N(o colors) /D(igits only) /P(assword) /E(dit) /W(ait) /L(ength) /X (no carriage return) !TTY See also: 635INKEY and 638KEYSTACK. Usage INPUT optionally displays a prompt. Then it waits for a specified time or indefinitely for your entry. It places any characters you type into an environment variable. INPUT is normally used in batch files and aliases to get multi-key input. Along with the INKEY command, INPUT allows great flexibility in reading user input from within a batch file or alias. If prompt text is included in an INPUT command, it is displayed while INPUT waits for input. Standard command-line editing keys may be used to edit the input string as it is entered. If you use the /P password option, INPUT will echo asterisks instead of the keys you type. All characters entered up to, but not including, the carriage return are stored in the variable. The following batch file fragment prompts for a string and stores it in the variable FNAME: input Enter the file name: %%fname INPUT reads standard input, so it will accept text from a redirected file or from the KEYSTACK. If you press Ctrl-C or Ctrl-Break while INPUT is waiting for input, execution of an alias will be terminated, and execution of a batch file will be suspended while you are asked whether to cancel the batch job. A batch file can handle Ctrl-C and Ctrl-Break itself with the 647ON BREAK command. In 4DOS you can 052pipe text to INPUT from another command, which will stash the first line of the command's output in the specified variable. However, this trick will not work in 0204NT or Take Command, which implement pipes differently. The 265@EXECSTR function provides a more portable way to get the first line of a command's output. Options !INDENT 5 5 0 5 /C: (Clear buffer) Clears the keyboard buffer before INPUT accepts keystrokes. If you use this option, INPUT will ignore any keystrokes which you type, either accidentally or intentionally, before INPUT is ready. /D: (Digits only) Prevents INPUT from accepting any keystroks except digits from 0 to 9. /E: (Edit) Allows you to edit an existing value. If there is no existing value for varname, INPUT proceeds as if /E had not been used, and allows you to enter a new value. /Ln: (Length) Sets the maximum number of characters which INPUT will accept to "n". If you attempt to enter more than this number of characters, INPUT will beep and prevent further input (you will still be able to edit the characters typed before the limit was reached). /N: (No colors) Disables the use of input colors defined in the 465InputColors directive in 4DOS.INI, and forces INPUT to use the default display colors. /P: (Password) Tells INPUT to echo asterisks, instead of the characters you type. /W: (Wait) Timeout period, in seconds, to wait for a response. If no keystroke is entered by the end of the timeout period, INPUT returns with the variable unchanged. This allows you to continue the batch file if the user does not respond in a given period of time. If you enter a key before the timeout period, INPUT will wait indefinitely for the remainder of the line. You can specify /W0 to return immediately if there are no keys waiting in the keyboard buffer. /X: (No carriage return) Prevents INPUT from adding a carriage return and line feed after the user's entry. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 637 KEYBD !TTY Purpose: Set the state of the keyboard toggles: Caps Lock, Num Lock, and Scroll Lock. Format: KEYBD [/Cn /Nn /Sn] /C(aps lock) /S(croll lock) /N(um lock) n can be either 0 to turn off the toggle or 1 to turn on the toggle. !TTY Usage Most keyboards have 3 toggle keys, the Caps Lock, Num Lock, and Scroll Lock. The toggle key status is usually displayed by three lights at the top right corner of the keyboard. This command lets you turn any toggle key on or off. It is most useful in batch files and aliases if you want the keys set a particular way before collecting input from the user. For example, to turn off the Num Lock and Caps Lock keys, you can use this command: c:\> keybd /c0 /n0 If you use the KEYBD command with no switches, it will display the present state of the toggle keys. KEYBD works by performing a BIOS setting. Some memory resident programs that monitor the physical keyboard rather than BIOS settings may not recognize that the state of the toggle keys has changed after a KEYBD command. The toggle key state is typically the same for all sessions, and changes made with KEYBD in one session will therefore affect all other sessions. The only exception is when running under OS/2, where KEYBD affects only the current 4DOS session. Options !INDENT 5 5 0 5 /C: (Caps lock) Turn the Caps Lock key on or off. /N: (Num lock) Turn the Num Lock key on or off. /S: (Scroll lock) Turn the Scroll Lock key on or off. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 638 KEYSTACK !TTY Purpose: Feed keystrokes to a program or command automatically. Format: KEYSTACK [!] [/Wx] ["abc"] [keyname[n]] ... !: Signal to clear the Keystack and the keyboard buffer. x: Delay in clock ticks. "abc": Literal characters to be placed in the Keystack. keyname: Name or code for a key to be placed in the Keystack. n: Number of times to repeat the named key. /W(ait) !TTY Usage KEYSTACK takes a series of keystrokes and feeds them to a program or command as if they were typed at the keyboard. When the program has used all of the keystrokes in the keystack buffer, it will begin to read the keyboard for input, as it normally would. KEYSTACK places keystrokes into a buffer. When an application program (or 4DOS itself) requests another keystroke, the "stacked" keystroke is retrieved from the buffer. The KEYSTACK command must be executed before running the program which is going to receive the keystrokes in order to put the keystrokes into the buffer first, so the program can find them when it runs. KEYSTACK will only work if the memory-resident program 703KSTACK.COM has been loaded. KSTACK is usually loaded from 109AUTOEXEC.BAT. If KSTACK is not loaded, the KEYSTACK command will display an error message. To load KSTACK.COM, add this line to AUTOEXEC.BAT: d:\path\KSTACK.COM where d:\path is the directory where your 4DOS files are stored. Programs that bypass DOS and the BIOS for keyboard input cannot read keystrokes entered with KEYSTACK. If you use KEYSTACK and then run such a program, the keystrokes will not appear in the program, but may appear at the prompt when you exit the program and return to 4DOS. Characters entered within double quotes ("abc") will be sent "as is" to the application. The only items allowed outside double quotes are key names, key codes, the ! and /W options, and a repeat count. See 893Keys and Key Names for a complete listing of key names and a description of the key name and numeric key code format. If you want to send the same key name or numeric code several times, you can follow it with a repeat count in square brackets. For example, to send the Enter key 4 times, you can use this command: keystack enter [4] The repeat count works only with individual keystrokes, or numeric keystroke or character values. It cannot be used with quoted strings. An exclamation mark [!] will clear all pending keystrokes, both in the KEYSTACK buffer and in the BIOS keyboard buffer. For example, to start a program that needs a single space to skip its opening screen you could use the command: c:\comm> keystack 32 ^ progname This places a space (ASCII code 32) in the buffer, then runs the program. When the program looks for a keystroke to end the display of the opening screen the keystroke is already in the buffer, and the opening screen is removed immediately. You can store a maximum of 511 text or special characters in the KEYSTACK buffer. A delay takes two character slots in the buffer. Each time the KEYSTACK command is executed, it will clear any remaining keystrokes stored by a previous KEYSTACK command. You may need to experiment with your programs and insert delays (see the /W option) to find a keystroke sequence that works for a particular program. Advanced Options KEYSTACK treats the number 0 as a special case; it is used with programs that flush the keyboard buffer. When KEYSTACK processes a key value of 0, it tells the program the buffer is clear, so subsequent keystrokes will be accepted normally. Some programs will require several "0"s before they will accept input; you may need to experiment to determine the correct number. For example, the following batch file starts a spreadsheet program and loads the file specified on the command line when the batch file is invoked: pushd c:\finance keystack 0 Enter 0 Enter 0 Enter 0 Enter 0 Enter "/FR" 0 "%1" Enter spread popd The sequence of "0 Enter" pairs tells the program that the keyboard buffer is empty, then passes a carriage return, repeating this sequence five times. (You must determine the actual sequence required by your software through experimentation. Few programs require as long a startup sequence as is shown here.) This gets the program to a point where an empty spreadsheet is displayed. The rest of the KEYSTACK line issues a File Retrieve command (/FR), simulates an empty keyboard buffer once more, enters the file name passed on the batch command line (%1), and finally enters a carriage return to end the file name. Here's the same command defined as an alias (enter this on one line): alias sload `pushd c:\finance ^ keystack 0 Enter 0 Enter 0 Enter 0 Enter 0 Enter "/FR" 0 "%1" Enter ^ spread ^ popd` KEYSTACK mimics the BIOS by stacking both an ASCII code and a scan code for each key. It does so by calculating the code for each character, whether it is entered as part of a quoted string, as a key name, or as an ASCII value less than 128. However, if you are stacking keys for a program which distinguishes between keys with the same symbol, like the plus on the keyboard and the gray plus, you will have to calculate the codes for the keys on the numeric keypad yourself. Calculate the value ((256 * scan code) + ASCII code) and enter that numeric value as an argument for KEYSTACK. For example, for the Enter key on the numeric keypad, the scan code is 224 and the ASCII code is 13, so to stack both values use ((256 * 224) + 13) or KEYSTACK 57357. Try this approach if a "normal" KEYSTACK command does not work (for example, if you use KEYSTACK Enter for the Enter key and the program doesn't see the correct character). To stack such combined key codes you must use the numeric value, not the key name. See 911ASCII and Key Codes for a complete list of ASCII codes and scan codes. Option !INDENT 5 5 0 5 /W: (Wait) Delay the next keystroke in the KEYSTACK buffer by a specified number of clock "ticks". A clock tick is approximately 1/18 second. The number of clock ticks to delay should be placed immediately after the W, and must be between 1 and 65535 (65535 ticks is about 1 hour). You can use the /W option as many times as desired and at any point in the string of keystrokes except within double quotes. Some programs may need the delays provided by /W in order to receive keystrokes properly from KEYSTACK. The only way to determine what delay is needed is to experiment. Sometimes a combination of a delay and an "empty buffer" signal (a 0) are required. !INDENT 5 5 5 5 For example, to start the program CADX and send it an F7, a delay of one second, an indication that the keyboard buffer is empty, and a carriage return: c:\> keystack F7 /W18 0 Enter ^ cadx !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 687 LFNFOR !TTY Purpose: Enable and disable LFN support for FOR wildcards in vDosPlus. Format: LFNFOR [ON | OFF] !TTY See also: 626FOR, 334@ALTNAME, and 296@LFN. Usage If you use wildcards in the set of a FOR command, 4DOS returns long file names on an LFN volume by default. For example, the command: c:\> for %f in (*.*) do echo %f will, by default, display the long version of each filename in the current directory. You can alter this behavior with LFNFOR. After the command c:\> lfnfor off the same command will return the short version of each filename in the current directory. You can restore the default behavior with the command c:\> lfnfor on If you enter LFNFOR without either ON or OFF, 4DOS will report the current state of LFNFOR. LFNFOR is included for compatibilty with COMMAND.COM. Under 4DOS, you may find it easier to use 334@ALTNAME and 296@LFN to convert between long and short filenames returned by FOR. LFNFOR only affects the filenames and pathnames in a FOR command, and only when wildcards are used in the set. It has no effect on DIR, SELECT, or any other command which returns file and path names. ;--------------------------------------------------------------------------- !TOPIC 639 LH !TTY Purpose: Load a memory resident program into an Upper Memory Block (UMB). Format: LH [/L:r1,n1;r2,n2;... /S] filename or LOADHIGH [/L:r1,n1;r2,n2;... /S] filename filename: The name of the program to load into high memory. /L(oad region) /S(hrink) !TTY Usage LH and LOADHIGH are synonyms. You can use either one. If you load memory-resident programs into UMBs, you will have more room in conventional memory for application programs. If your system has no UMBs, or if the program is larger than the largest UMB, then LOADHIGH will load the program into conventional base memory. For example, to load the program C:\UTIL\CACHE.EXE into high memory: c:\> loadhigh c:\util\cache.exe The /L and /S switches are designed to aid in optimizing the use of upper memory by selecting one or more UMB regions for a particular memory-resident program to use. While a complete discussion of memory optimization techniques is well beyond the scope of this help system (see also the 65535external DOS help system), the basic technique is to load each memory-resident program into a specific region to free up the maximum possible amount of base memory. Options !INDENT 5 5 0 5 /L:r1,n1;r2,n2;... : (Load region) Specifies which region(s) should be used for the program, and optionally the minimum free space required in a region before the program is allowed access to that region. !INDENT 5 5 5 5 If /L is not used, all upper memory regions are available to the program. If /L is used, you must specify one or more regions (r1, r2, etc.); only those regions will be made available. Upper memory regions are numbered sequentially beginning with 1 (region 0 refers to low memory). If only a region number is given, the entire region is made available to the program (assuming there is free space in the region). If a size is given for a particular region (n1, n2, etc.), then the region is only made available if the free space in the region is equal to or greater than that size. All sizes are in bytes. Any region not available to a particular program is "locked out" while that program is loading and made available again once the program is loaded. If the combination of /L values you use does not provide sufficient upper memory space for the program to load, it will be loaded in low memory. You can combine /L values in several ways. In each of the following examples, if the requested space is not available or is insufficient the program is loaded into low memory: lh /l:2 filename The program can use region 2 only. lh /l:2;3 filename The program can use regions 2 and 3 only. lh /l:2,2048 filename The program can use region 2 only, and only if it has 2048 or more bytes free. lh /l:2,2048;3 filename The program can use region 2 if it has 2048 or more bytes free, and region 3 regardless of how many bytes it has free !INDENT 5 5 0 5 /S: (Shrink) Shrinks each region selected by /L to the minimum size used in /L before loading the program. This prevents memory-resident programs which take all available memory from using more than you want them to. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 640 LIST !TTY Purpose: Display a file, with forward and backward paging and scrolling. Format: LIST [/A:[[+|-]rhsad] /H /I /I"text" /Ln /N /R /S /T"text" /W /X] [@file] file... file: A file or list of files to display. @file: A text file containing the names of files to view, one per line (see 057@file lists for details). /A: (Attribute select) /R(everse) /H(igh bit off) /S(tandard input) /I(gnore wildcards) /T (search for text) /I"text" (match description) /W(rap) /L(ine offset) /X (heX display mode) /N (line Numbers) !TTY See also: 697HEAD, 698TAIL, and 677TYPE. File Selection Supports extended 073wildcards, 074ranges, 079multiple file names, and 080include lists. Use wildcards with caution on LFN volumes; see 081LFN File Searches for details. Usage LIST provides a fast and flexible way to view a file, without the overhead of loading and using a text editor. For example, to display a file called MEMO.DOC: c:\> list memo.doc LIST is most often used for displaying ASCII text files. It can be used for other files which contain non-alphabetic characters, but you may need to use hex mode (see below) to read these files. LIST uses the cursor pad to scroll through the file. The following keys have special meanings: Space Display the next page of the file (same as PgDn). Home Display the first page of the file. End Display the last page of the file. Esc Exit the current file. Del Prompt to delete the file. Insert Prompt to save the file or pipe to a new name. Tab Set a new tab size. Ctrl-PgUp Display previous file. Ctrl-PgDn Display next file. Ctrl-C Quit LIST. Up Scroll up one line. Down Scroll down one line. Left Scroll left 8 columns. Right Scroll right 8 columns. Ctrl-Left Scroll left 40 columns. Ctrl-Right Scroll right 40 columns. F1 Display online help Del Prompt whether to delete the file. Ins Prompt whether to save the pipe or file to a new name. Tab Prompt for a new default tab size. B Go back one file to the previous file in the current group of files. F Prompt and search for a string. Ctrl-F Prompt and search for a string, searching backward from the end of the file. G Go to a specific line, or, in hex mode, to a specific hexadecimal offset. H Toggle the "strip high bit" (/H) option. I Display information on the current file (the full name, size, date, and time). L Toggle the "line numbering" (/L) option. N Find next matching string. Ctrl-N Find previous match in the file. P Print the current page or the entire file. W Toggle the "line wrap" (/W) option. X Toggle the hex-mode display (/X) option. Text searches performed with F, N, Ctrl-F, and Ctrl-N are not case-sensitive unless you hold a Shift key while pressing F or Ctrl-F, in which case the searches become case-sensitive. If the display is currently in hexadecimal mode and you press F or Ctrl-F, you will be prompted for whether you want to search in hexadecimal mode. If you answer Y, you should then enter the search string as a sequence of 2-digit hexadecimal numbers separated by spaces, for example 41 63 65 (these are the 912ASCII values for the string "Ace"). Hexadecimal searches are case-sensitive, and search for exactly the string whose ASCII values you enter. The string can be any sequence of bytes in this mode, not just text. When the search string is found LIST displays the line containing the string at the top of the screen, and highlights the string it found. Any additional occurrences of the string on the same display page are also highlighted. Highlighting is intended for use with text files; in binary files the search string will be found, but may not be highlighted properly. You can use 073wildcards in the search string. For example, you can search for the string "to*day" to find the next line which contains the word "to" followed by the word "day" later on the same line, or search for the numbers "101" or "401" with the search string "[14]01". If you begin the search string with a back-quote [`], or enclose it in back-quotes, wildcard characters in the string will be treated as normal text with no special wildcard meaning. LIST saves the search string used by F, N, Ctrl-F, and Ctrl-N, so you can LIST multiple files and search for the same string simply by pressing N in each file, or repeat your search the next time you use LIST. You can use the /T switch to specify search text for the first file. When you do so, LIST begins a search as soon as the file is loaded. Use /I to ignore wildcards in the initial search string, and /R to make the initial search go backwards from the end of the file. When you LIST multiple files with a single LIST command, these switches affect only the first file; they are ignored for the second and subsequent files. You can use the G key to go to a specific line number in the file (or to a specified hexadecimal offset in hex mode). LIST numbers lines beginning with 1, unless 475ListRowStart is set to 0. A new line is counted for every CR or LF character (LIST determines automatically which character is used for line breaks in each file), or when line length reaches 511 characters, whichever comes first. LIST normally allows long lines in the file to extend past the right edge of the screen. You can use the horizontal scrolling keys (see above) to view text that extends beyond the screen width. If you use the W command or /W switch to wrap the display, each line is wrapped when it reaches the right edge of the screen, and the horizontal scrolling keys are disabled. To view output from another command simply pipe the output of the command to LIST, for example: c:\> dir | list Normally LIST will detect input from a pipe auomatically, but if it does not, use /S to explicitly specify piped input. To view text from the clipboard, use CLIP: as the file to be listed. CLIP: will not return any data unless the clipboard contains text. See 051redirection for additional information on CLIP:, including details on when you can use the clipboard under 4DOS. If you print the file which LIST is displaying, you will be asked whether you wish to print the entire file or the current display page. The print format will match the display format. If you have switched to hexadecimal or wrapped mode, that mode will be used for the printed output as well. If you print in wrapped mode, long lines will be wrapped at the width of the display. If you print in normal display mode without line wrap, long lines will be wrapped or truncated by the printer, not by LIST. Printed output normally goes to device LPT1. If you wish to send the printed output to another device, use the Commands page of the 648OPTION dialogs, or the 441Printer directive in 4DOS.INI. If you specify a directory name instead of a filename as an argument, LIST will display each of the files in that directory. Most of the LIST keystrokes can be reassigned with 481key mapping directives in 4DOS.INI. You can set the colors used by LIST on the Commands page of the 648OPTION dialogs, or the 467ListColors and 468ListStatBarColors directives in 4DOS.INI. If ListColors is not used, the LIST display will use the current default colors. If ListStatBarColors is not used, the status bar will use the reverse of the LIST display colors. By default, LIST sets tab stops every 8 columns. You can change this behavior on the Display page of the 648OPTION dialogs, or with the 444TabStops .INI file directive. LIST normally writes text directly to the screen. If you have an unusual display adapter which does not support direct video output, see the 572OutputBIOS directive. Options !INDENT 5 5 0 5 /A:: (Attribute select) Select only those files that have the specified attribute(s) set. The colon [:] after /A is required. !INDENT 5 5 5 5 Preceding an attribute letter with a hyphen [-] will select files that do not have that attribute set. You can OR attributes by preceding each attribute letter with a plus sign [+]. The attributes are: R Read-only S System H Hidden A Archive If no attributes are listed at all (e.g., LIST /A: ...), LIST will select all files including hidden and system files. If attributes are combined, all the specified attributes must match for a file to be selected. For example, /A:RHS will select only those files with all three attributes set. !INDENT 5 5 0 5 /H: (High bit off) Strip the high bit from each character before displaying. This is useful when displaying files created by some word processors that turn on the high bit for formatting purposes. You can toggle this option on and off from within LIST with the H key. /I: (Ignore wildcards) Only meaningful when used in conjunction with the /T "text" option. Directs LIST to interpret characters such as *, ?, [, and ] as literal characters instead of wildcard characters. /I affects only the initial search started by /T, not subsequent searches started from within LIST. /I"text": Select files by matching text in their descriptions. The text can include 073wildcards and extended wildcards. The search text must be enclosed in quotation marks, and must follow the /I immediately, with no intervening spaces. You can select all filenames that have a description with /I"[?]*", or all filenames that do not have a description with /I"[]". /Ln: (Line offset) Start at line n (no space is allowed between L and n). This option only affects the initial page display; it does not prevent you from subsequently scrolling back to the start of the file. If /X is also specified, n designates a hexadecimal offset from the start of file. Thus, the /L option is equivalent to the G (goto) key. /N: (line numbers) Display line numbers. This option is useful with source code listings and other text files where the exact line numbers are important. You can toggle this option on and off from within LIST with the L key. /R: (Reverse) Only meaningful when used in conjuction with the /T "text" option. Directs LIST to search for text from the end of the file instead of from the beginning of the file. Using this switch can speed up searches for text that is normally near the end of the file, such as a signature. /R affects only the initial search started by /T, not subsequent searches started from within LIST. /S: (Standard input) Read from standard input rather than a file. This allows you to redirect command output and view it with LIST. Normally, LIST will detect input from a redirected command and adjust automatically. However, you may find circumstances when /S is required. For example, to use LIST to display the output of DIR you could use either of these commands: !INDENT 5 5 5 5 c:\> dir | list c:\> dir | list /s !INDENT 5 5 0 5 /T: (Text) Search for text in the first file. This option is the same as pressing F, but it allows you to specify the search text on the command line. The text must be contained in quotation marks if it contains spaces, punctuation, or wildcard characters. For example, to search for the string 4DOS in the file README.DOC, you can use this command: !INDENT 5 5 5 5 c:\> list /t4dos readme.doc The search text may include 073wildcards and extended wildcards. For example, to search for the words Hello and John on the same line in the file LETTER.DAT: c:\> list /t"Hello*John" letter.dat When you LIST multiple files with a single LIST command, /T only initiates a search in the first file. It is ignored for the second and subsequent files. Also see /I and /R. If /X is also given, the argument of /T must be an enclosed in double quotes sequence of 2-digit hexadecimal numbers separated by spaces, for example "E8 0C 66 01 00". !INDENT 5 5 0 5 /W: (Wrap) Wrap the text at the right edge of the screen. This option is useful when displaying files that don't have a carriage return at the end of each line. The horizontal scrolling keys do not work when the display is wrapped. You can toggle this option on and off from within LIST with the W key. /X: (hex mode) Display the file in hexadecimal (hex) mode. This option is useful when displaying executable files and other files that contain non-text characters. Each byte of the file is shown as a pair of hex characters. The corresponding text is displayed to the right of each line of hexadecimal data. You can toggle this mode on and off from within LIST with the X key. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 641 LOADBTM !TTY Purpose: Switch a batch file to or from BTM mode. Format: LOADBTM [ON | OFF] !TTY Usage 4DOS recognizes two kinds of 102batch files: .BAT and .BTM. Batch files executing in BTM mode run two to ten times faster than in BAT mode. (However, BTM mode should not be used to load memory-resident programs in DOS, nor should BTM mode be used for self-modifying batch files.) Batch files automatically start in the mode indicated by their extension. The LOADBTM command turns BTM mode on and off. It can be used to switch modes in either a .BAT or .BTM file. If you use LOADBTM with no argument, it will display the current batch mode: LOADBTM ON or LOADBTM OFF. Using LOADBTM to repeatedly switch modes within a batch file is not efficient. In most cases the speed gained by running some parts of the file in BTM mode will be more than offset by the speed lost through repeated loading of the file each time BTM mode is invoked. LOADBTM can only be used within a batch file. It is most often used to switch a .BAT file into BTM mode after memory-resident programs are loaded, to convert a .BAT file to BTM mode without changing its extension, or to switch a .BTM file into BAT mode in order to load memory-resident programs. The following .BAT file fragment loads some memory resident programs (TSRs), and then switches to BTM mode: rem Because this file has a .BAT extension, rem the initial default state is LOADBTM OFF rem Loading TSRs... ansi.com mouse.com rem Switch to high-speed (BTM) mode now that rem TSRs are loaded loadbtm on path c:\;c:\util;c:\dos alias /r c:\aliases ..... ;--------------------------------------------------------------------------- !TOPIC 643 LOG !TTY Purpose: Save a log of commands to a disk file. Format: LOG [/E /H /W file] [ON | OFF | text] file: The name of the file to hold the log. text: An optional message that will be added to the log. /E(rror log) /W(rite to file) /H(istory log) !TTY See also: 632HISTORY. Usage LOG keeps a record of all internal and external commands you use, whether they are executed from the prompt or from a batch file. Each entry includes the shell level and the current system date and time, along with the actual command after any alias or variable expansion. You can use the log file as a record of your daily activities. The 399LogOn directive can be used to enable command logging by default when 4DOS starts. LOG with the /H option keeps a similar record called a "history log." The history log records only commands entered at the prompt; it does not record batch file commands. In addition, the history log does not record the date and time for each command, and it records commands before aliases and variables are expanded. The 400HistLogOn directive can be used to enable history logging by default when 4DOS starts. By default, LOG writes to the file 4DOSLOG in the root directory of C:. The default file name for LOG /H is 4DOSHLOG. You can set the default log file names on the Options 2 page of the 648OPTION dialogs, or with the 437LogName and 432HistLogName directives in the .INI file. Entering LOG or LOG /H with no parameters displays the name of the log file and the log status (ON or OFF): c:\> log LOG (C:\4DOSLOG) is OFF To enable or disable logging, add the word "ON" or "OFF" after the LOG command: c:\> log on or c:\> log /h on Entering LOG or LOG /H with text writes a message to the log file, even if logging is set OFF. This allows you to enter headers in the log file: c:\> log "Started work on the database system" The LOG file format looks like this: [date time] command where the date and time are formatted according to the country code set for your system. The LOG /H output can be used as the basis for writing batch files. Start LOG /H, then execute the commands that you want the batch file to execute. When you are finished, turn LOG /H off. The resulting file can be turned into a batch file that performs the same commands with little or no editing. Options !INDENT 5 5 0 5 /E: (Error log) This option saves all error messages to the log. It applies only to the command log; /E has no effect on the history log. /H: (History log) This option makes the other options on the command line (after the /H) apply to the history log. For example, to turn on history logging and write to the file C:\LOG\HLOG: !INDENT 5 5 5 5 c:\> log /h /w c:\log\hlog !INDENT 5 5 0 5 /W: (Write) This switch specifies a different filename for the LOG or LOG /H output. It also automatically performs a LOG ON command. For example, to turn logging on and write the log to C:\LOG\LOGFILE: !INDENT 5 5 5 5 c:\> log /w c:\log\logfile !INDENT 5 5 0 5 Once you select a new file name with the LOG /W or LOG /H/W command, LOG will use that file until you issue another LOG /W or LOG /H/W command, or until you restart the vDosPlus session. Turning LOG or LOG /H off or on does not change the file name. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 644 MD !TTY Purpose: Create a subdirectory. Format: MD [/N /S] path... or MKDIR [/N /S] path... path: The name of one or more directories to create. /N(o update) /S(ubdirectories) !TTY See also: 655RD. Usage MD and MKDIR are synonyms. You can use either one. MD creates a subdirectory anywhere in the directory tree. To create a subdirectory from the root, start the path with a backslash [\]. For example, this command creates a subdirectory called MYDIR in the root directory: c:\> md \mydir If no path is given, the new subdirectory is created in the current directory. This example creates a subdirectory called DIRTWO in the current directory: c:\mydir> md dirtwo To create a directory from the parent of the current directory (that is, to create a sibling of the current directory), start the pathname with two periods and a backslash [..\]. You must quote any path which contains whitespace or special characters (see 945File Names for details). If MD creates one or more directories, they will be added automatically to the 048extended directory search database unless the /N option is specified. Options !INDENT 5 5 0 5 /N: (No update) Do not update the 048extended directory search database, JPSTREE.IDX. This is useful when creating a temporary directory which you do not want to appear in the extended search database. /S: (Subdirectories) MD creates one directory at a time unless you use the /S option. If you need to create the directory C:\ONE\TWO\THREE and none of the named directories exist, you can use /S to have MD create all of the necessary subdirectories for you in a single command: !INDENT 5 5 5 5 c:\> md /s \one\two\three !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 645 MEMORY !TTY Purpose: Display the amount and status of system RAM. Format: MEMORY !TTY Usage MEMORY displays information about the RAM in your system. MEMORY lists the amount of total RAM in your system and the amount available for applications after DOS, 4DOS, and memory-resident programs have been loaded; the amount of EMS expanded memory, XMS extended memory, and total extended memory; the HMA status; and the amount of memory 4DOS is using for environment variable space, alias space, function space, and history space. You can use the information from the MEMORY display to fine tune your system, to aid in setting the proper alias and environment sizes in 4DOS.INI, and to be sure that you have sufficient memory for your largest applications. If you compare the free RAM displayed by MEMORY with the free RAM displayed by CHKDSK and some memory map programs, MEMORY will usually show a slightly higher value. The difference is the size of the environment passed to these external programs; most memory mapping programs do not count the passed environment as free space, but MEMORY does. ;--------------------------------------------------------------------------- !TOPIC 646 MOVE !TTY Purpose: Move files to a new directory and drive. Format: MOVE [/A:[[+|-]rhsad] /C /D /E /F /G /H /I"text" /M /N /O /P /Q /R /S /T /U /V /W /Z] [@file] source... destination source: A file or list of files to move. destination: The new location for the files. @file: A text file containing the names of the source files to move, one per line (see 057@file lists for details). /A: (Attribute select) /O (move if not exist) /C(hanged) /P(rompt) /D(irectory) /Q(uiet) /E (no error messages) /R(eplace) /F(orce delete) /S(ubdirectory tree) /G (percent moved) /T(otal) /H(idden and system) /U(pdate) /I (match descriptions) /V(erify) /M(odified files) /W(ipe) /N(othing) /Z (overwrite readonly files) !TTY See also: 606COPY and 658REN. File Selection Supports extended 073wildcards, 074ranges, 079multiple file names, and 080include lists. Date, time, size or file exclusion ranges anywhere on the line apply to all source files. Use wildcards with caution on LFN volumes; see 081LFN File Searches for details. Usage The MOVE command moves one or more files from one directory to another, whether the directories are on the same drive or not. It has the same effect as copying the files to a new location and then deleting the originals. Like COPY and RENAME, MOVE works with single files, multiple files, and sets of files specified with an include list. The simplest MOVE command moves a single source file to a new location and, optionally, gives it a new name. These two examples both move one file from drive C: to the root directory on drive A: c:\> move myfile.dat a:\ c:\> move myfile.dat a:\savefile.dat In both cases, MYFILE.DAT is removed from drive C: after it has been copied to drive A:. If a file called MYFILE.DAT in the first example, or SAVEFILE.DAT in the second example, already existed on drive A:, it would be overwritten. (This demonstrates the difference between MOVE and RENAME. MOVE will move files between drives and will overwrite the destination file if it exists; RENAME will not.) When you move a single file, the destination can be a directory name or a file name. If it is a directory name, and you add a backslash [\] to the end of the name, MOVE will display an error message if the name does not refer to an existing directory. You can use this feature to keep MOVE from treating a mistyped destination directory name as a file name, and attempting to move the source file to that name. If you MOVE multiple files, the destination must be a directory name. MOVE will move each file into the destination directory with its original name. If the destination is not a directory, MOVE will display an error message and exit. For example, if C:\FINANCE\MYFILES is not a directory, this command will display an error; otherwise, the files will be moved to that directory: c:\> move *.wks *.txt c:\finance\myfiles The /D option can be used for single or multiple file moves; it checks to see whether the destination is a directory, and will prompt to see if you want to create the destination directory if it doesn't exist. If MOVE creates one or more destination directories, they will be added automatically to the 048extended directory search database. You cannot move a file to a character device like the printer, or to itself. Be careful when you use MOVE with the 662SELECT command. If you SELECT multiple files and the destination is not a directory (for example, because of a misspelling), MOVE will assume it is a file name. In this case each file will be moved in turn to the destination file, overwriting the previous file, and then the original will be erased before the next file is moved. At the end of the command, all of the original files will have been erased and only the last file will exist as the destination file. You can avoid this problem by using square brackets with SELECT instead of parentheses (be sure that you don't allow the command line to get too long -- watch the character count in the upper left corner while you're selecting files). MOVE will then receive one list of files to move instead of a series of individual filenames, and it will detect the error and halt. You can also add a backslash [\] to the end of the destination name to ensure that it is the name of a subdirectory (see above). Advanced Features and Options MOVE first attempts to rename the file(s), which is the fastest way to move files between subdirectories on the same drive. If that fails (e.g., because the destination is on a different drive or already exists), MOVE will copy the file(s) and then delete the originals. If MOVE must physically copy the files and delete the originals, rather than renaming them (see above), then some disk space may be freed on the source drive. MOVE displays the amount of disk space recovered unless the the move is to the same drive, or /Q option is used (see below). It does so by comparing the amount of free disk space before and after the MOVE command is executed. However, this amount may be incorrect if you are using a deletion tracking system which retains deleted files for later recovery, or if another program performs a file operation while the MOVE command is executed. When physically copying files, MOVE preserves the hidden, system, and read-only attributes of the source files, and sets the archive attribute of the destination files. However, if the files can be renamed, and no copying is required, then the file attributes are not changed. Use caution with the /A: and /H switches (both of which can allow MOVE to process hidden files) when you are physically moving files, and both the source and destination directories contain file descriptions. If the source file specification matches the description file name (normally DESCRIPT.ION), and you tell MOVE to process hidden files, the DESCRIPT.ION file itself will be moved, overwriting any existing file descriptions in the destination directory. For example, if the C:\DATA directory contains file descriptions, this command would overwrite any existing descriptions in the D:\SAVE directory: c:\data> move /h d*.* d:\save\ If you remove the hidden attribute from the DESCRIPT.ION file the same caution applies even if you do not use /A:, /H, or /K, as DESCRIPT.ION is then treated like any other file. You can use an 078exclusion range to prevent the descriptions file from being moved: c:\data> move /[!%192_dname] /h d*.* d:\save\ In an LFN environment, if you MOVE files with long filenames to a volume which does not support them, 4DOS will store the destination files with their short, FAT-compatible names. You can view the short names before executing the MOVE with the 612DIR /X command. Use caution when using wildcards with MOVE in an LFN environment. For compatibility with COMMAND.COM, 4DOS's wildcard matching will match both short and long filenames. This can move files you did not expect. See 081LFN File Searches for additional details on the last two items above. Options !INDENT 5 5 0 5 /A:: (Attribute select) Select only those files that have the specified attribute(s) set. The colon [:] after /A is required. !INDENT 5 5 5 5 Preceding an attribute letter with a hyphen [-] will select files that do not have that attribute set. You can OR attributes by preceding each attribute letter with a plus sign [+]. The attributes are: R Read-only S System H Hidden A Archive If no attributes are listed at all (e.g., MOVE /A: *.* ...), MOVE will select all files including hidden and system files. If attributes are combined, all the specified attributes must match for a file to be selected. For example, /A:RHS will select only those files with all three attributes set. See the cautionary note under Advanced Features and Options above before using /A: when both source and destination directories contain file descriptions. !INDENT 5 5 0 5 /C: (Changed files) Move files only if the destination file exists and is older than the source (see also /U). This option is useful for updating the files in one directory from those in another without moving any newly-created files. (Before using /C in a network environment be sure to read the note under /U.) /D: (Directory) Requires that the destination be a directory. If the destination does not exist, MOVE will prompt to see if you want to create it. If the destination exists as a file, MOVE will fail with an "Access denied" error. Use this option to avoid having MOVE accidentally interpret your destination name as a file name when it's really a mistyped directory name. /E: (No error messages) Suppress all non-fatal error messages, such as "File not found." Fatal error messages, such as "Drive not ready," will still be displayed. This option is most useful in batch files and aliases. /F: (Force delete) This option has no effect in vDosPlus. /G: Displays the percent moved. This is useful when moving large files across a network to ensure the move is proceeding. /H: (Hidden) Move all files, including hidden and system files. See the cautionary note under Advanced Features and Options above before using /H when both source and destination directories contain file descriptions. /I"text": Select source files by matching text in their descriptions. The text can include 073wildcards and extended wildcards. The search text must be enclosed in quotation marks, and must follow the /I immediately, with no intervening spaces. You can select all filenames that have a description with /I"[?]*", or all filenames that do not have a description with /I"[]". /M: (Modified files) Move only files that have the archive bit set. The archive bit will remain set after the MOVE; to clear it use 596ATTRIB. /N: (Nothing) Do everything except actually move the file(s). This option is most useful for testing what a complex MOVE command will do. /N does NOT prevent creation of destination subdirectories when used with /S. /O: Don't move the file(s) unless the target doesn't exist. /P: (Prompt) Prompt the user to confirm each move. Your options at the prompt are explained in detail under 045Page and File Prompts. /Q: (Quiet) Don't display filenames, the total number of files moved, or the amount of disk space recovered, if any. This option is most often used in batch files. See also /T. /R: (Replace) Prompt for a Y or N response before overwriting an existing destination file. See also the 4DOS.INI 450CopyPrompt directive. /S: (Subdirectories) Move an entire subdirectory tree to another location. MOVE will attempt to create the destination directories if they don't exist, and will remove empty subdirectories after the move. When /D is used with /S, you will be prompted if the first destination directory does not exist, but subdirectories below that will be created automatically by MOVE. If MOVE /S creates one or more destination directories, they will be added automatically to the 048extended directory search database. !INDENT 5 5 5 5 If you attempt to use /S to move a subdirectory tree into part of itself, MOVE will detect the resulting infinite loop, display an error message, and exit. Do not use /S with @file lists; see 057@file lists for details. Note that MOVE /S will not search into subdirectories with the hidden or system attributes set unless you also specify /A: or /H. !INDENT 5 5 0 5 /T: (Total) Don't display filenames as they are moved, but display the total number of files moved and the amount of free disk space recovered, if any. /U: (Update) Move each source file only if it is newer than a matching destination file or if a matching destination file does not exist (also see /C). This option is useful for moving new or changed files from one directory to another. !INDENT 5 5 5 5 The time comparisons used with /U may not always work reliably across a network, due to differences in time zone and in the file time storage method between the local and remote systems. Be sure to do some non-destructive testing (e.g. with /N) before depending on this option to yield the results you want in a network environment. !INDENT 5 5 0 5 /V: (Verify) Verify each disk write. This is the same as executing the VERIFY ON command, but is only active during the MOVE. /V does not read back the file and compare its contents with what was written; it only verifies that the data written to disk is physically readable. /W: (Wipe) If the MOVE is to a different drive, overwrite the old file with zeros before deleting it (like DEL /W). /Z: (Overwrite) Overwrite read-only destination files. Without this option, MOVE will fail with an "Access denied" error if the destination file has its read-only attribute set. !INDENT 0 For comparison with the external DOS MOVE command refer to the 65535external DOS help system. ;--------------------------------------------------------------------------- !TOPIC 647 ON !TTY Purpose: Execute a command in a batch file when a specific condition occurs. Format: ON BREAK [command] or ON ERROR [command] or ON ERRORMSG [command] !TTY Usage ON can only by used in batch files. ON sets a "watchdog" that remains in effect for the duration of the current batch file. Whenever a BREAK or ERROR condition occurs after ON has been executed, the corresponding command is automatically executed. ON BREAK will execute the command if the user presses Ctrl-C or Ctrl-Break. ON ERROR and ON ERRORMSG will execute the command after any 4DOS or operating system error (including 083critical errors). That is, they will detect errors such as a disk write error, and 4DOS errors such as a COPY command that fails to copy any files, or the use of an invalid command option. ON ERROR executes the command immediately after the error occurs, without displaying any 4DOS error message (operating system errors may still be displayed in some cases). ON ERRORMSG displays the appropriate error message, then executes the command. If both are specified, ON ERROR will take precedence, and the ON ERRORMSG setting will be ignored. The remainder of this section discusses both settings together, using the term ON ERROR[MSG]. ON BREAK and ON ERROR[MSG] are independent of each other. You can use either one, or both, in any batch file. Each time ON BREAK or ON ERROR[MSG] is used, it defines a new command to be executed for a break or error, and any old command is discarded. If you use ON BREAK or ON ERROR[MSG] with no following command, that type of error handling is disabled. Error handling is also automatically disabled when the batch file exits. ON BREAK and ON ERROR[MSG] only affect the current batch file. If you CALL another batch file, the first batch file's error handling is suspended, and the CALLed file must define its own error handling. When control returns to the first batch file, its error handling is reactivated. The command can be any command that can be used on a batch file line by itself. Frequently, it is a 630GOTO or 629GOSUB command. For example, the following fragment traps any user attempt to end the batch file by pressing Ctrl-C or Ctrl-Break. It scolds the user for trying to end the batch file and then continues displaying the numbers: on break gosub gotabreak do i = 1 to 1000 echo %i enddo quit :gotabreak echo Hey! Stop that!! return You can use a 085command group as the command if you want to execute multiple commands, for example: on break (echo Oops, got a break!^quit) ON BREAK and ON ERROR[MSG] always assume that you want to continue executing the batch file. After the command is executed, control automatically returns to the next command in the batch file (the command after the one that was interrupted by the break or error). The only way to avoid continuing the batch file after a break or error is for the command to transfer control to another point with 630GOTO, end the batch file with 654QUIT or 600CANCEL, or start another batch file (without CALLing it). When handling an error condition with ON ERROR[MSG], you may find it useful to use 161internal variables, particularly %164_? and %218_SYSERR, to help determine the cause of the error. The ON ERROR[MSG] command will not be invoked if an error occurs while reading or writing a redirected input file, output file, or pipe. If a break or error occurs while the command specified in ON BREAK or ON ERROR[MSG] is executing, the command will be restarted. This means you must use caution to avoid or handle any possible errors in the commands invoked by ON ERROR[MSG], since such errors can cause an infinite loop and/or a stack overflow condition. ;--------------------------------------------------------------------------- !TOPIC 648 OPTION !TTY Purpose: Modify 4DOS configuration. Format: OPTION [//optname=value ...] optname: An .INI file directive to set or modify. value: A new value for that directive. !TTY See also: 356.INI File Directives and 018OPTION Reference. Usage If the OPTION command is used without any parameters, it displays a set of dialogs which allows you to modify many of the configuration options stored in the .INI file. OPTION handles most standard .INI file settings. More advanced settings, including all those listed under 481Key Mapping Directives and 550Advanced Directives cannot be modified with the OPTION dialogs. These settings must be inserted or modified in the .INI file manually. For more details see 353Modifying the .INI File. OPTION does not preserve comments when saving modified settings in the .INI file. To be sure .INI file comments are preserved, put them on separate lines in the file. See 353Modifying the .INI File for additional details. OPTION runs the external program OPTION.EXE to display the dialogs. If 4DOS cannot find OPTION.EXE it will display an error message. OPTION.EXE must be run with the OPTION command, and will not work if you invoke it directly. For information about using the OPTION dialogs, see 018OPTION Reference. Setting Individual Options If you follow the OPTION command with one or more sequences of a double slash mark [//] followed by an option=value setting, the OPTION dialogs or notebook will not appear. Instead, the new settings will take effect immediately, and will be in effect for the current session only. This example turns off batch file echo and changes the input colors to bright cyan on black (enter this all on one line): c:\> option //BatchEcho = No //InputColors = bri cya on bla Option values may contain whitespace. However, you cannot enter an option value which contains the "//" string. This feature is most useful for testing settings quickly, and in aliases or batch files which depend on certain options being in effect. If you are setting more than one directive, it is more efficient to combine them into one OPTION command because 4DOS must load the external OPTION.EXE program for each OPTION //... command. Changes made with // are temporary. They will not be saved in the .INI file, even if you subsequently load the option dialogs and select Save. ;--------------------------------------------------------------------------- !TOPIC 649 PATH !TTY Purpose: Display or alter the list of directories that 4DOS will search for executable files, batch files, and files with executable extensions that are not in the current directory. Format: PATH [directory[;directory...]] directory: The full name of a directory to include in the path setting. !TTY See also: 622ESET and 663SET. Usage When 4DOS is asked to execute an external command (a .COM, .EXE, .BTM, or .BAT file or executable extension), it first looks for the file in the current directory. If it fails to find an executable file in the current directory, it will search each of the directories specified in the PATH setting. For example, after the following PATH command, 4DOS will search for an executable file in four directories: the current directory, the root directory on drive C, then the DOS subdirectory on C, and then the UTIL subdirectory on C: c:\> path c:\;c:\dos;c:\util The list of directories to search can be set or viewed with the PATH command. The list is stored as an environment string named 138PATH, and can also be set or viewed with SET, and edited with ESET. Directory names in the path must be separated by semicolons [;]. Each directory name is shifted to upper case to maintain compatibility with programs which can only recognize upper case directory names in the path. If you modify your path with the 663SET or 622ESET command, you may include directory names in lower case. These may cause trouble with some programs, which assume that all path entries have been shifted to upper case. On drives which support long filenames, some directory names may include spaces or other special characters. Unlike other commands where quotes are required, such names should not be quoted in the PATH. If you enter PATH with no parameters, the current path is displayed. Entering PATH and a semicolon clears the search path so that only the current directory is searched for executable files (this is the default at system startup). Some applications also use the PATH to search for their data files. 4DOS normally searches the path for files with the extensions .COM, .EXE, .BTM, and .BAT (in that order). However, if you include an explicit file extension on a command name (for example, WP.EXE), the search will find files with that name and extension in the current directory and every directory in the path. It will not locate other executable files with the same base name (e.g., WP.COM). The standard list of extensions for which to search can be modified by setting 477PathExt to Yes in 4DOS.INI, then setting the 143PATHEXT variable. If you have an entry in the path which consists of a single period [.], the current directory will not be searched first, but instead will be searched when 4DOS reaches the "." in the path. This allows you to delay the search of the current directory for executable files and files with executable extensions. In rare cases, this feature may not be compatible with applications which use the path to find their files; if you experience a problem, you will have to remove the "." from the path while using any such application. In normal use, 4DOS can create a path as long as 506 characters (the command-line limit is 511 characters, and "PATH " takes five). However, some DOS applications expect a path no longer than the traditional limit of 123 characters. To create a path longer than the command line length limit, use PATH repeatedly to append additional directories to the path: path [first list of directories] path %path;[second list of directories] ... You cannot use this method to extend the path beyond 506 characters (the 511-byte internal buffer limit, with room for "PATH "). It is usually more efficient to use aliases to load application programs than to create a long PATH. See 595ALIAS for details. If you specify an invalid directory in the path, it will be skipped and the search will continue with the next directory in the path. ;--------------------------------------------------------------------------- !TOPIC 650 PAUSE !TTY Purpose: Suspend batch file or alias execution. Format: PAUSE [text] text: The message to be displayed as a user prompt. !TTY Usage A PAUSE command will suspend execution of a batch file or alias, giving you the opportunity to change disks, turn on the printer, etc. PAUSE waits for any key to be pressed and then continues execution. You can specify the text that PAUSE displays while it waits for a keystroke, or let it use the default message: Press any key when ready... If you press Ctrl-C or Ctrl-Break while PAUSE is waiting for a key, execution of an alias will be terminated, and execution of a batch file will be suspended while you are asked whether to cancel the batch job. In a batch file you can handle Ctrl-C and Ctrl-Break yourself with the 647ON BREAK command. ;--------------------------------------------------------------------------- !TOPIC 651 POPD !TTY Purpose: Return to the disk drive and directory at the top of the directory stack. Format: POPD [*] !TTY See also: 614DIRS, 653PUSHD, and 047Directory Navigation. Usage Each time you use the PUSHD command, it saves the current disk drive and directory on the internal directory stack. POPD restores the last drive and directory that was saved with PUSHD and removes that entry from the stack. You can use these commands together to change directories, perform some work, and return to the starting drive and directory. Directory changes made with POPD are recorded for display in the 040directory history window. Directory changes made with POPD are recorded in the directory history list and can be displayed in the directory history window. This example saves and changes the current disk drive and directory with PUSHD, and then restores it. The current directory is shown in the prompt: c:\> pushd d:\database\test d:\database\test> popd c:\> You can use the DIRS command to see the complete list of saved drives and directories (the directory stack). The POPD command followed by an asterisk [*] clears the directory stack without changing the current drive and directory. If the directory on the top of the stack is not on the current drive, POPD will switch to the drive and directory on the top of the stack without changing the default directory on the current drive. ;--------------------------------------------------------------------------- !TOPIC 652 PROMPT !TTY Purpose: Change the command-line prompt. Format: PROMPT [text] text: Text to be used as the new command-line prompt. !TTY Usage You can change and customize the command-line prompt at any time. The prompt can include normal text, and system information such as the current drive and directory, the time and date, and the amount of memory available. You can create an informal "Hello, Bob!" prompt or an official-looking prompt full of impressive information. The prompt text can contain special character sequences in the form $?, where ? is one of the characters listed below: a The ampersand character [&]. b The vertical bar character [|]. c The open parenthesis [(]. d Current date, in the format: Mon 6-19-00 (the month, day, and year are formatted according to your current country settings. D Current date, in the format: Mon Jun 19, 2000. e The ASCII ESC character (decimal 27). f The close parenthesis [)]. g The > character. h Backspace over the previous character. J Date in ISO 8601 international format (yyyy-mm-dd). K Date in ISO 8601 week date format (yyyy-Www-d). l The < character. m Time in hours and minutes using 24-hour format. M Time in hours and minutes using the default country format and retaining "a" or "p", e.g. 4:07p. n Current drive letter. p Current drive and directory (lower case). P Current drive and directory (upper case on drives which do not support long filenames; directory names shown in mixed case as stored on the disk on LFN drives.) q The = character. r The numeric exit code of the last external command. s The space character. t Current 24-hour time, in the format hh:mm:ss. T Current 12-hour time, in the format hh:mm:ss[a|p]. U The current user (the value of the environment variable 147LOGINNAME). v Operating system version number, in the format 7.10. w Current working directory in a shortened format (lower case). If the current directory is the root or a first level subdirectory, it is displayed as-is. If it is second level or deeper, the path is truncated in the display. W Current working directory in a shortened format (upper case on drives which do not support long filenames; directory names shown in mixed case as stored on the disk on LFN drives.) xd: Current directory on drive d:, in lower case, including drive letter. (Uses the actual case of the directory name as stored on the disk for LFN drives.) Xd: Current directory on drive d:, in upper case, including drive letter. z Current shell nesting level; the primary command processor is shell 0. + Display one + character for each directory on the PUSHD directory stack. $ The $ character. _ CR/LF (go to beginning of a new line). For example, to set the prompt to the current date and time, with a ">" at the end: c:\> prompt $D $t $g Mon Jun 19, 2000 10:29:19 > You can include the PROMPT command in your 109AUTOEXEC.BAT file to set the prompt whenever you start vDosPlus, in 1094START, or in any batch file that runs when 4DOS starts. The default prompt is $n$g (drive name plus ">") on drives A and B, and $p$g (current drive and directory plus ">") on all other drives. If you enter PROMPT with no arguments, the prompt will be reset to its default value. The current setting of the PROMPT will be stored in an environment variable named 139PROMPT. Along with literal text, special characters, and 915ANSI sequences, you can include any 131environment variable, 161internal variable, or 241variable function in a prompt. For example, if you want to display the amount of free memory in the command prompt, plus the current drive and directory, you could use this command: c:\> prompt (%%@dosmem[K]K) $p$g (601K) c:\data> Notice that the @DOSMEM function is shown with two leading percent signs [%]. If you used only one percent sign, the @DOSMEM function would be expanded once when the PROMPT command was executed, instead of every time the prompt is displayed. As a result, the amount of memory would never change from the value it had when you entered the PROMPT command. You can also use back-quotes to delay expanding the variable function until the prompt is displayed: c:\> prompt `(%@dosmem[K]K) $p$g` You can use this feature along with the 264@EXEC variable function to create a complex prompt which not only displays information but executes commands. For example, to execute an alias which checks battery status each time the prompt is displayed (enter the alias on one line): c:\> alias cbatt `if %_apmlife lt 30 beep 440 4 880 4 440 4 880 4` c:\> prompt `%@exec[@cbatt]$p$g` You can include 915ANSI escape sequences in the PROMPT text. This example uses ANSI sequences to set a prompt that displays the shell level, date, time and path in color on the top line of the screen (enter the command on one line: c:\> prompt $e[s$e[1;1f$e[41;1;37m$e[K[$z] $d Time: $t$h$h$h Path: $p$e[u$e[0;32m$n$g You may find it helpful to define a different prompt in secondary shells, perhaps including $z in the prompt to display the shell level. To do so, place a PROMPT command in your 1094START file and use 633IF or 634IFF statements to set the appropriate prompt for different shells. ;--------------------------------------------------------------------------- !TOPIC 653 PUSHD !TTY Purpose: Save the current disk drive and directory, optionally changing to a new drive and directory. Format: PUSHD [path] path: The name of the new default drive and directory. !TTY See also: 601CD, 602CDD, 614DIRS, 651POPD, and 047Directory Navigation. Usage PUSHD saves the current drive and directory on a "last in, first out" directory stack. The POPD command returns to the last drive and directory that was saved by PUSHD. You can use these commands together to change directories, perform some work, and return to the starting drive and directory. The DIRS command displays the contents of the directory stack. To save the current drive and directory, without changing directories, use the PUSHD command by itself, with no path. If a path is specified as part of the PUSHD command, the current drive and directory are saved and PUSHD changes to the specified drive and directory. If the path includes a drive letter, PUSHD changes to the specified directory on the new drive without changing the current directory on the original drive. This example saves the current directory and changes to C:\WORDP\MEMOS, then returns to the original directory: c:\> pushd \wordp\memos c:\wordp\memos> popd c:\> You should quote the path name if it contains whitespace or special characters. See 945File Names for additional details. If PUSHD cannot change to the directory you have specified it will attempt to search the 049CDPATH and the 048extended directory search database. You can also use 073wildcards in the path to force an extended directory search. See 047Directory Navigation for complete details on these and other directory navigation features. Directory changes made with PUSHD are also recorded in the 040directory history list and can be displayed in the directory history window. The directory stack can hold up to 511 characters, or between 20 and 40 entries (depending on the length of the names). If you exceed this limit, the oldest entry is removed before adding a new entry. ;--------------------------------------------------------------------------- !TOPIC 654 QUIT !TTY Purpose: Terminate the current batch file. Format: QUIT [value] value: The numeric exit code to return to 4DOS or to the previous batch file. !TTY See also: 600CANCEL and 624EXIT. Usage QUIT provides a simple way to exit a batch file before reaching the end of the file. If you QUIT a batch file called from another batch file, you will be returned to the previous file at the line following the original CALL. QUIT only ends the current batch file. To end all batch file processing, use the CANCEL command. If you specify a value, QUIT will set the ERRORLEVEL or exit code to that value. For information on exit codes, see the 633IF command and the %162? variable. You can also use QUIT to terminate an alias. If you QUIT an alias while inside a batch file, QUIT will end both the alias and the batch file and return you to the command prompt or to the calling batch file. ;--------------------------------------------------------------------------- !TOPIC 655 RD !TTY Purpose: Remove one or more subdirectories. Format: RD [/I"text"] [@file] path... or RMDIR [/I"text"] [@file] path... path: The name of one or more subdirectories to remove. @file: A text file containing the names of the directories to remove, one per line (see 057@file lists for details). /I: (match descriptions) !TTY See also: 644MD. File Selection Supports extended 073wildcards, 074ranges, 079multiple file names, and 080include lists. Usage RD and RMDIR are synonyms. You can use either one. RD removes directories from the directory tree. For example, to remove the subdirectory MEMOS from the subdirectory WP: c:\> rd \wp\memos Before using RD, you must delete all files and subdirectories (and their files) in the path you want to remove. Remember to remove hidden and read-only files as well as normal files (you can use DEL /Z to delete hidden and read-only files). You can use wildcards in the path. You must quote any path which contains whitespace or special characters. See 945File Names for additional details. If RD removes one or more directories, they will be deleted automatically from the 048extended directory search database. You cannot remove the root directory, the current directory (.), any directory above the current directory in the directory tree, or any directory in use by another process in a multitasking system. Option !INDENT 5 5 0 5 /I"text": Select directories by matching text in their descriptions. The text can include 073wildcards and extended wildcards. The search text must be enclosed in quotation marks, and must follow the /I immediately, with no intervening spaces. You can select all filenames that have a description with /I"[?]*", or all filenames that do not have a description with /I"[]". !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 656 REBOOT !TTY Purpose: Do a warm or cold system reboot or change the power state. Format: REBOOT [/C /M /P /S /V] /C(old reboot) /S(uspend) /M(onitor off) /V(erify) /P(ower off) !TTY Usage The /M, /P, /S and /V options of this command will work in vDosPlus. With the /V option it will prompt for confirmation (Y or N) before suspending or turning off the monitor or vDosPlus. For example, to power off vDosPlus: c:\> reboot /p Options !INDENT 5 5 0 5 /C: (Cold) Do a "cold" reboot. This option does not work in vDosPlus. !INDENT 5 5 0 5 /M: (Monitor off) Shut off the display, if the system has a VESA BIOS and VESA Display Power Management Signalling is supported. The monitor is turned back on when a typematic key is pressed. Like /S, this option does not actually reboot. !INDENT 5 5 5 5 If the current video mode is not supported by the VESA BIOS, it may switch the display to a supported mode (usually a text mode) before it turns the monitor off. !INDENT 5 5 0 5 /P: (Power off) Turn off vDosPlus using the APM functions. !INDENT 5 5 0 5 /S: (Suspend) Enter suspend state, if the system has APM version 1.1 or newer. vDosPlus lost focus when it enters this state. Like /M, this option does not actually reboot. !INDENT 5 5 0 5 /V: (Verify) Prompt for confirmation (Y or N) before rebooting or changing the power state. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 657 REM !TTY Purpose: Put a comment in a batch file. Format: REM [comment] comment: The text to include in the batch file. !TTY Usage The REM command lets you place a remark or comment in a batch file. Batch file comments are useful for documenting the purpose of a batch file and the procedures you have used. For example: rem This batch file provides a menu-based utility system. rem Clear the screen and get selection cls REM must be followed by a space or tab character and then your comment. Comments can be up to 511 characters long. 4DOS will normally ignore everything on the line after the REM command, including quote characters, redirection symbols, and other commands. If ECHO is ON, the comment is displayed. Otherwise, it is ignored. If ECHO is ON and you don't want to display the line, preface the REM command with an at sign [@]. You can also place a comment in a batch file by starting the comment line with two colons [::]. In essence this creates a batch file "label" without a valid label name. Such comments are processed slightly faster than those entered with REM, because they do not require 4DOS to handle a command. You can use REM to create a zero-byte file if you use a redirection symbol after the REM command. For example, to create the zero-byte file C:\FOO: c:\> rem > foo (This capability is included for compatibility with COMMAND.COM. A simpler method for creating a zero-byte file with 4DOS is to use >filename as a command, with no actual command before the [>] redirection character.) ;--------------------------------------------------------------------------- !TOPIC 658 REN !TTY Purpose: Rename files or subdirectories. Format: REN [/A:[[+|-]rhsad] /E /I"text" /N /P /Q /S /T][@file] old_name... new_name or RENAME [/A:[[+|-]rhsad] /E /I"text" /N /P /Q /S /T][@file] old_name... new_name old_name: Original name of the file(s) or subdirectory. new_name: New name to use, or new path on the same drive. @file: A text file containing the names of the source files to rename, one per line (see 057@file lists for details). /A: (Attribute select) /P(rompt) /E (no error messages) /Q(uiet) /I (match descriptions) /S(ubdirectory) /N(othing) /T(otal) !TTY See also: 606COPY and 646MOVE. File Selection Supports extended 073wildcards, 074ranges, 079multiple file names, and 080include lists. Use wildcards with caution on LFN volumes; see 081LFN File Searches for details. Usage REN and RENAME are synonyms. You may use either one. REN lets you change the name of a file or a subdirectory, or move one or more files to a new subdirectory on the same drive. (If you want to move files to a different drive, use MOVE.) In its simplest form, you give REN the old_name of an existing file or subdirectory and then a new_name. The new_name must not already exist -- you can't give two files the same name (unless they are in different directories). The first example renames the file MEMO.TXT to MEM.TXT. The second example changes the name of the \WORD directory to \WP: c:\> rename memo.txt mem.txt c:\> rename \word \wp You must quote any file names which contain whitespace or special characters. See 945File Names for additional details. You can also use REN to rename a group of files that you specify with wildcards, as multiple files, or in an include list. When you do, the new_name must use one or more wildcards to show what part of each filename to change. Both of the next two examples change the extensions of multiple files to .SAV: c:\> ren file1.txt file2.dat file3.idx *.sav c:\> ren *.txt *.sav REN can move files to a different subdirectory on the same drive. When it is used for this purpose, REN requires one or more filenames for the old_name and a directory name for the new_name: c:\> ren memo.txt \wp\memos\ c:\> ren oct.dat nov.dat \data\save\ The final backslash in the last two examples is optional. If you use it, you force REN to recognize the last argument as the name of a directory, not a file. The advantage of this approach is that if you accidentally mistype the directory name, REN will report an error instead of renaming your files in a way that you didn't intend. REN can also move files to a new directory and change their name at the same time if you specify both a path and file name for new_name. In this example, the files are renamed with an extension of .SAV as they are moved to a new directory: c:\> ren *.dat \data\save\*.sav If you use REN to rename a directory, the new_name must normally be specified explicitly, and cannot contain wildcards. You can override this restriction with /S. When you rename a directory the 048extended directory search database will be automatically updated to reflect the change. REN does not change a file's attributes. The new_name file(s) will have the same attributes as old_name. Options !INDENT 5 5 0 5 /A:: (Attribute select) Rename only those files that have the specified attribute(s) set. The colon [:] after /A is required. !INDENT 5 5 5 5 Preceding an attribute letter with a hyphen [-] will select files that do not have that attribute set. You can OR attributes by preceding each attribute letter with a plus sign [+]. The attributes are: R Read-only D subDirectory H Hidden A Archive S System If no attributes are listed at all (e.g., REN /A: ...), REN will rename all matching files (and subdirectories, if /S is specified or wildcards are not used), including those with the hidden or system attributes. If attributes are combined, all the specified attributes must match for a file to be selected. For example, /A:RHS will select only those files with all three attributes set. !INDENT 5 5 0 5 /E: (No error messages) Suppress all non-fatal error messages, such as "File not found." Fatal error messages, such as "Drive not ready," will still be displayed. This option is most useful in batch files. /I"text": Select files by matching text in their descriptions. The text can include 073wildcards and extended wildcards. The search text must be enclosed in quotation marks, and must follow the /I immediately, with no intervening spaces. You can select all filenames that have a description with /I"[?]*", or all filenames that do not have a description with /I"[]". /N: (Nothing) Do everything except actually rename the file(s). This option is useful for testing what a REN command will actually do. /P: (Prompt) Prompt the user to confirm each rename operation. Your options at the prompt are explained in detail under 045Page and File Prompts. /Q: (Quiet) Don't display filenames or the number of files renamed. This option is most often used in batch files. See also /T. /S: (Subdirectory) Normally, you can rename a subdirectory only if you do not use any wildcards in the new_name. This prevents subdirectories from being renamed inadvertently when a group of files is being renamed with wildcards. /S will let you rename a subdirectory even when you use wildcards. /S does not cause REN to process files in the current directory and all subdirectories as it does in some other file processing commands. To rename files throughout a directory tree, use a 628GLOBAL REN. /T: (Total) Don't display filenames as they are renamed, but report the number of files renamed. See also /Q. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 659 RETURN !TTY Purpose: Return from a GOSUB (subroutine) in a batch file. Format: RETURN [value] value: The exit code (0 to 255) to return to 4DOS or to the previous batch file. !TTY See also: 629GOSUB. Usage 4DOS allows subroutines in batch files. A subroutine begins with a label (a colon followed by a word) and ends with a RETURN command. The subroutine is invoked with a GOSUB command from another part of the batch file. When a RETURN command is encountered the subroutine terminates, and execution of the batch file continues on the line following the original GOSUB. If RETURN is encountered without a GOSUB, 4DOS will display a "Missing GOSUB" error. You cannot execute a RETURN from inside a 615DO loop. The following batch file fragment calls a subroutine which displays the files in the current directory: echo Calling a subroutine gosub subr1 echo Returned from the subroutine quit :subr1 dir /a/w return If you specify a value, RETURN will set the internal exit code to that value. The exit code should be tested immediately upon return from the subroutine and before it is reset by another command. For information on exit codes from internal commands, see the 164_? variable. ;--------------------------------------------------------------------------- !TOPIC 660 SCREEN !TTY Purpose: Position the cursor on the screen and optionally display a message. Format: SCREEN row column [text] row: The new row location for the cursor. column: The new column location for the cursor. text: Optional text to display at the new cursor location. !TTY See also: 619ECHO, 661SCRPUT, 671TEXT, and 684VSCRPUT. Usage SCREEN allows you to create attractive screen displays in batch files. You use it to specify where a message will appear on the screen. You can use SCREEN to create menus and other similar displays. For example, the following batch file fragment displays part of 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 does not change the screen colors. To display text in specific colors, use SCRPUT or VSCRPUT. SCREEN always leaves the cursor at the end of the displayed text. The row and column values are zero-based, so on a standard 25 line by 80 column display, valid rows are 0 - 24 and valid columns are 0 - 79. You can also specify the row and column as offsets from the current cursor position. Begin the value with a plus sign [+] to move the cursor down the specified number of rows or to the right the specified number of columns, or with a minus sign [-] to move the cursor up or to the left. This example prints a string 3 lines above the current position, in absolute column 10: screen -3 10 Hello, World! If you specify 999 for the row, SCREEN will center the text vertically on the display. If you specify 999 for the column, SCREEN will center the text horizontally. This example prints a message at the center of the display: screen 999 999 Hello, World SCREEN checks for a valid row and column, and displays a "Usage" error message if either value is out of range. ;--------------------------------------------------------------------------- !TOPIC 661 SCRPUT !TTY Purpose: Position text on the screen and display it in color. Format: SCRPUT row col [BRIght] [BLInk] fg ON [BRIght] bg text row: Starting row col: Starting column fg: Foreground character color bg: Background character color text: The text to display !TTY See also: 619ECHO, 660SCREEN, 671TEXT, and 684VSCRPUT. Usage SCRPUT allows you to create attractive screen displays in batch files. You use it to specify where a message will appear on the screen and what colors will be used to display the message text. You can use SCRPUT to create menu displays, logos, etc. SCRPUT works like SCREEN, but requires you to specify the display colors. See 892Colors and Color Names for details about colors and notes on the use of bright background colors. The row and column values are zero-based, so on a standard 25 line by 80 column display, valid rows are 0 - 24 and valid columns are 0 - 79. SCRPUT checks for a valid row and column, and displays a "Usage" error message if either value is out of range. You can also specify the row and column as offsets from the current cursor position. Begin the value with a plus sign [+] to move down the specified number of rows or to the right the specified number of columns, or with a minus sign [-] to move up or to the left. If you specify 999 for the row, SCRPUT will center the text vertically. If you specify 999 for the column, SCRPUT will center the text horizontally. SCRPUT normally does not move the cursor when it displays the text. However, if you have set 572OutputBIOS to Yes in 4DOS.INI, SCRPUT will leave the cursor at the end of the displayed text. The following batch file fragment displays part of a menu, in color: cls white on blue scrput 3 10 bri whi on blu Select an option: scrput 6 20 bri red on blu 1 - Word Processing scrput 7 20 bri yel on blu 2 - Spreadsheet ... If you have an unusual display adapter which does not support the direct video output used by SCRPUT, see the 572OutputBIOS directive. ;--------------------------------------------------------------------------- !TOPIC 662 SELECT !TTY Purpose: Interactively select files for a command. Format: SELECT [/1 /A[[:][+|-]rhsad] /C[HP] /D /E /H /I"text" /J /L /O[[:][-]acdeginrsu] /T:acw /X /Z] [command] ... (files...)... command: The command to execute with the selected files. files: The files from which to select. File names may be enclosed in either parentheses or square brackets. The difference is explained in the usage text. /1 (one selection) /J(ustify names) /A: (Attribute select) /L(ower case) /C[HP] (Compression) /O(rder) /D(isable color) /T(ime) /E (use upper case) /X (display short names) /H(ide dots) /Z (use FAT format) /I (match descriptions) !TTY File Selection Supports extended 073wildcards, 074ranges, 079multiple file names, and 080include lists. Ranges must appear immediately after the SELECT keyword. Use wildcards with caution on LFN volumes; see 081LFN File Searches for details. Usage SELECT allows you to select files for internal and external commands by using a full-screen "point and shoot" display. You can have SELECT execute a command once for each file you select, or have it create a list of files for a command to work with. The command can be an internal command, an alias, an external command, or a batch file. If you use parentheses around the files, SELECT executes the command once for each file you have selected. During each execution, one of the selected files is passed to the command as an argument. If you use square brackets around files, the SELECTed files are combined into a single list, separated by spaces. The command is then executed once with the entire list presented part of its command-line arguments. Using the SELECT File List When you execute the SELECT command, the file list is displayed in a full-screen format which includes a top-line status bar and shows the command to be executed, the number of files marked, and the number of Kbytes in those files. SELECT supports the mouse for selecting and scrolling the list. You can also use uses the cursor up, cursor down, PgUp, and PgDn keys to scroll through the file list. You can also use character matching to find specific files, just as you can in any 894popup window. While the file list is displayed you can enter any of the following keys to select or unselect files, display files, execute the command, or exit: !INDENT 5 5 5 5 + or space: Select a file, or unselect a marked file. -: Unselect a marked file. *: Reverse all of the current marks (except those on subdirectories). If no files have been marked you can use * to mark all of the files. /: Unselect all files. Ctrl-L: View the current highlighted file with 640LIST. When you exit from LIST, the SELECT screen will be restored. Enter: Execute the command with the marked files, or with the currently highlighted file if no files have been marked. Esc: Skip the files in the current display and go on to the next file specification inside the parentheses or brackets (if any). Ctrl-C or Ctrl-Break: Cancel the current SELECT command entirely. !INDENT 0 On FAT drives the file list is shown in standard FAT directory format, with names at the left an descriptions at the right. On LFN drives the format is similar but more space is allowed for the name, and the description is not shown. In this format long names are truncated if they do not fit in the allowable space. For a short-name format (including descriptions) on long filename drives, use the /X and / or /Z switches. When displaying descriptions in the short filename format, SELECT adds a right arrow [] at the end of the line if the description is too long to fit on the screen. This symbol will alert you to the existence of additional description text. You can use the left and right arrow keys to scroll the description area of the screen horizontally and view the additional text. You can display the filenames in color by using the 663SET command to create an environment variable called 133COLORDIR, or using the Commands page of the 648OPTION dialogs or a text editor to set the 463ColorDir directive in your .INI file. If you do not use the COLORDIR variable or the ColorDir directive, SELECT will use the default screen colors for all files. See the discussion of color-coded directories under 612DIR for more details. To disable directory color coding within SELECT, use the /D option. You can set the default colors used by SELECT on the Commands page of the OPTION dialogs or with the 469SelectColors and 470SelectStatBarColors directives in the .INI file. If SelectColors is not used, the SELECT display will use the current default colors. If SelectStatBarColors is not used, the status bar will use the reverse of the SELECT colors. Creating SELECT Commands In the simplest form of SELECT, you merely specify the command and then the list of files from which you will make your selection(s). For example: c:\> select copy (*.com *.exe) a:\ will let you select from among the .COM files on the current drive, and will then invoke the COPY command to copy each file you select to drive A:. After the .COM files are done, the operations will be repeated for the .EXE files. If you want to select from a list of all the .COM and .EXE files mixed together, create an 080include list inside the parentheses by inserting a semicolon: c:\> select copy (*.com;*.exe) a:\ Finally, if you want the SELECT command to send a single list of files to COPY, instead of invoking COPY once for each file you select, put the file names in square brackets instead of parentheses: c:\> select copy [*.com;*.exe] a:\ If you use brackets, you have to be sure that the resulting command (the word COPY, the list of files, and the destination drive in this example) does not exceed the command line length limit: 511 characters for internal commands or 126 characters for external commands. The current line length is displayed by SELECT while you are marking files to help you to conform to these limits. The parentheses or brackets enclosing the file name(s) can appear anywhere within the command; SELECT assumes that the first set of parentheses or brackets it finds is the one containing the list of files from which you wish to make your selection. You must quote any file names inside the parentheses which contain whitespace or special characters. See 945File Names for additional details. For example, to copy selected files from the "Program Files" directory to the E:\SAVE directory: c:\> select copy ("Program Files\*.*") e:\save\ File names passed to the command will be quoted automatically if they contain whitespace or special characters. The list of files from which you wish to select can be further refined by using 074date, time, size, and 078file exclusion ranges. The range(s) must be placed immediately after the word SELECT. If the command is an internal command that supports ranges, an independent range can also be used in the command itself. You cannot use command grouping to make SELECT execute several commands, because SELECT will assume that the parentheses are marking the list of files from which to select, and will display an error message or give incorrect results if you try to use parentheses for command grouping instead. (You can use a SELECT command inside command grouping parentheses, you just can't use command grouping to specify a group of commands for SELECT to execute.) Advanced Topics If you don't specify a command, the selected filename(s) will become the command. For example, this command defines an alias called UTILS that selects from the executable files in the directory C:\UTIL, and then executes them in the order marked: c:\> alias utils select (c:\util\*.com;*.exe;*.btm;*.bat) If you want to use 035filename completion to enter the filenames inside the parentheses, type a space after the opening parenthesis. Otherwise, the command-line editor will treat the open parenthesis as the first character of the filename. When displaying descriptions, SELECT adds a right arrow [] at the end of the line if the description is too long to fit on the screen. This symbol will alert you to the existence of additional description text. You can use the left and right arrow keys to scroll the screen horizontally and view the additional text. With the /I option, you can select files based on their descriptions. SELECT will display files if their description matches the text after the /I switch. The search is not case sensitive. You can use wildcards and extended wildcards as part of the text. When sorting file names and extensions for the SELECT display, 4DOS normally assumes that sequences of digits should be sorted numerically (for example, the file DRAW2 would come before DRAW03 because 2 is numerically smaller than 03), rather than strictly alphabetically (where DRAW2 would come second because "2" comes after "0"). You can defeat this behavior and force a strict alphabetic sort with the /O:a option. SELECT normally writes text directly to the screen. If you have an unusual display adapter which does not support direct video output, see the 572OutputBIOS directive. If you receive a stack overflow error when using SELECT in complex, nested command sequences, see the notes under the 574StackSize directive. Options !INDENT 5 5 0 5 /1: (1 selection) Limits selection to a single file. /A: (Attribute select) Display only those files that have the specified attribute(s) set. The colon [:] after /A is optional. !INDENT 5 5 5 5 Preceding an attribute letter with a hyphen [-] will select files that do not have that attribute set. You can OR attributes by preceding each attribute letter with a plus sign [+]. The attributes are: R Read-only D subDirectory H Hidden A Archive S System If no attributes are listed at all (e.g., SELECT /A ...), SELECT will display all files and subdirectories including hidden and system files. If attributes are combined, all the specified attributes must match for a file to be included in the listing. For example, /A:RHS will display only those files with all three attributes set. !INDENT 5 5 0 5 /C: (Compression) Display per-file and total compression ratios on compressed drives. The compression ratio is displayed instead of the file description. The ratio is left blank for directories and files with a length of 0 bytes, and for files on non-compressed drives. The compression ratios will not be visible on LFN drives unless you use /Z to switch to the traditional short filename format. !INDENT 5 5 5 5 Using /CH displays compression ratios like /C, but bases the calculation on the host drive's cluster size. This gives a more accurate picture of the space saved through compression than is given by /C. If /CP is used instead of /C, the compression is displayed as a percentage instead of a ratio. If /CHP is used instead of /CH, the host compression is displayed as a percentage. The /CHP option must be entered as shown; you can not use /CPH. See the 612DIR /C documentation for more details on how compression ratios are calculated. !INDENT 5 5 0 5 /D: (Disable color coding) Temporarily turn off directory color coding within SELECT. /E: (Use upper case) Display filenames in the upper case; also see 664SETDOS /U and the 446UpperCase directive in 4DOS.INI. /H: (Hide dots) Suppress the display of the "." and ".." directories. /I"text": Display filenames by matching text in their descriptions. The text can include 073wildcards and extended wildcards. The search text must be enclosed in quotation marks, and must follow the /I immediately, with no intervening spaces. You can select all filenames that have a description with /I"[?]*", or all filenames that do not have a description with /I"[]". /J: (Justify names) Justify (align) filename extensions and display them in the traditional format. /L: (Lower case) Display file and directory names in lower case; also see 664SETDOS /U and the 446UpperCase directive in 4DOS.INI. /O: (Order) Set the sort order for the files. The order can be any combination of the following options: !INDENT 5 5 5 5 - Reverse the sort order for the next option. a Sort names and extensions in standard ASCII order, rather than sorting numerically when digits are included in the name or extension. c Sort by compression ratio (the least compressed file in the list will be displayed first). If /O:c is used with /CH or /CHP, the sort will be based on the host-drive compression ratios. For information on supported compression systems, see /C above. d Sort by date and time (oldest first). e Sort by extension. g Group subdirectories first, then files. i Sort by the file description (ignored if /C or /O:c is also used). n Sort by filename (this is the default). r Reverse the sort order for all options. s Sort by size. u Unsorted. !INDENT 5 5 0 5 /T:acw: (Time display) Specify which of the date and time fields on an LFN drive should be displayed and used for sorting: !INDENT 5 5 0 5 a last access date and time (access time is not saved on LFN volumes). c creation date and time. w last write date and time (this is the default). !INDENT 5 5 0 5 /X: (Display short names): Display short filenames, in the traditional FAT format (like /Z), on LFN drives /Z: (Use FAT format) Display filenames on an LFN drive in the traditional FAT format, with the short filename at the left and the description at the right. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 663 SET !TTY Purpose: Display, create, modify, or delete environment variables. Format: SET [/A /E /M /P /R file...] [name[=][value]] file: One or more files containing variable definitions. name: The name of the environment variable to define or modify. value: The new value for the variable. /A(rithmetic) /P(ause) /E(nvironment) /R(ead from file) /M(aster) !TTY See also: 622ESET and 680UNSET. Usage Every program and command inherits an 131environment, which is a list of variable names, each of which is followed by an equal sign and some text. Many programs use entries in the environment to modify their own actions. If you simply type the SET command with no options or arguments, it will display all the names and values currently stored in the environment. Typically, you will see an entry called 134COMSPEC, an entry called 138PATH, an entry called CMDLINE, and whatever other environment variables you and your programs have established: set COMSPEC=C:\COMMAND.COM PATH=C:\;C:\DOS;C:\UTIL CMDLINE=E:\UTIL\MAPMEM.EXE To add a variable to the environment, type SET, a space, the variable name, an equal sign, and the text: set mine=c:\finance\myfiles The variable name is converted to upper case, the text after the equal sign will be left just as you entered it. If the variable already exists, its value will be replaced with the new text that you entered. Normally you should not put a space on either side of the equal sign. A space before the equal sign will become part of the name; a space after the equal sign will become part of the value. vDosPlus has a feature to access environment variables of Windows. Values enclosed in double %%'s will be converted to the value of that Windows variable if set. For instance: set mine=%%mine%% vDosPlus sets two DOS environment variables by default: set win_username=%%username%% set win_vdos=%%vdos%% (defaulting to not_set) If you use SET to create a variable with the same name as one of the 4DOS 161internal variables, you will disable the internal variable. If you later execute a batch file or alias that depends on that internal variable, it may not operate correctly. To display the contents of a variable, type SET plus the variable name: set mine If the name contains one or more 073wildcards, SET will display all matching environment variables. You can edit environment variables with the 622ESET command. To remove variables from the environment, use 680UNSET, or type SET plus a variable name and an equal sign: set mine= The variable name is limited to a maximum of 80 characters, the name and value together cannot be longer than 511 characters. Unless you use /M, SET only affects the environment of the current command processor and the programs it executes. If you EXIT to a parent command processor, the original environment will be unchanged. The size of the environment can be specified on the Startup page of the 648OPTION dialogs, with the 377Environment and 378EnvFree directives in 4DOS.INI, or with the /E: 352startup option. Options !INDENT 5 5 0 5 /A: (Arithmetic) Evaluate the value as an arithmetic expression; store the result in the specified variable and display it to standard output. SET /A supports the same operators as the 263@EVAL function. !INDENT 5 5 5 5 Warnings: SET /A was never an officially documented or sanctioned option. Use it at your own risk. While this feature was apparently introduced to provide some compatibility with Microsoft's CMD.EXE, be aware that 4DOS's SET /A differs from CMD's in features and syntax. Using SET /A in batch files to be run by either shell will require careful study: use only those operators supported by both; remember to space around all operators; 131variables in the expression require both leading and trailing percent signs; use 118double quotes around the expression if it contains troublesome characters like the 041caret, ampersand or 052vertical bar. Unless you need it for CMD.EXE compatibility, the documented 263@EVAL function should be used instead of SET /A. !INDENT 5 5 0 5 /E: (Environment) When used together with /M, set both the master and local environments. Note: SET /E /M does not propagate to any other environment instances. For example, if you do it in a 4th level 4DOS, the top level (master) and the current (local) environments are modified, but the level 2 and level 3 environments are not. /M: (Master) Display or modify the master environment rather than the local environment. This option is only useful in secondary shells. /P: (Pause) Wait for a key to be pressed after each screen page before continuing the display. Your options at the prompt are explained in detail under 045Page and File Prompts. /R: (Read) Read environment variables from a file. This is much faster than loading variables from a batch file with multiple SET commands. Each entry in the file must fit within the 511-byte command line length limit for 4DOS. The file is in the same format as the SET display (i.e., name=value), so SET /R can accept as input a file generated by redirecting SET output. For example, the following commands will save the environment variables to a file, and then reload them from that file: !INDENT 5 5 5 5 set > varlist set /r varlist You can load variables from multiple files by listing the filenames individually after the /R. You can add comments to a variable file by starting the comment line with a colon [:]. If you are creating a SET /R file by hand, and need to create an entry that spans multiple lines in the file, you can do so by terminating each line, except the last, with an 086escape character. However, you cannot use this method to exceed the command line length limit. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 664 SETDOS !TTY Purpose: Display or set the 4DOS configuration. Format: SETDOS [/A? /B? /C? /D? /E? /Fn.n /G?? /I+|- command /L? /M? /N? /P? /R? /S?:? /U? /V? /X[+|-]n /Y?] /A(NSI) /N(o clobber) /B(right background) /P(arameter character) /C(ompound) /R(ows) /D(escriptions) /S(hape of cursor) /E(scape character) /U(pper case) /F(ormat for @EVAL) /V(erbose) /G (numeric separators) /W (switch character) /I(nternal commands) /X (expansion, special characters) /L(ine) /Y (debug batch files) /M(ode for editing) !TTY Usage SETDOS allows you to customize certain aspects of 4DOS to suit your personal tastes or the configuration of your system. Each of these options is described below. You can display the value of all SETDOS options by entering the SETDOS command with no parameters. Most of the SETDOS options can be initialized when 4DOS executes the 410configuration directives in 4DOS.INI, and can also be set with on the Command Line, Windows, Options 1, or Options 2 pages of the 648OPTION dialogs. The name of the corresponding directive is listed with each option below; if none is listed, that option cannot be set with OPTION or from 4DOS.INI. You can also define the SETDOS options in your AUTOEXEC.BAT, 4START, or other startup file (see 109Automatic Batch Files), in aliases, or at the command line. Secondary shells automatically inherit most configuration settings currently in effect in the previous shell. If values have been changed by SETDOS since 4DOS started, the new values will be passed to the secondary shell. SETDOS /I settings are not inherited by secondary shells. If you want to use SETDOS /I- to disable commands in all shells, place the SETDOS command(s) in your 4START file, which is executed when any shell starts. Options !INDENT 5 5 0 5 /A: (ANSI) This option determines whether 4DOS will attempt to use ANSI escape sequences for the 604CLS and 605COLOR commands. 4DOS normally determines this itself, but if you are using a non-standard ANSI driver or your loading sequence is unusual, you may need to explicitly inform 4DOS. /A0 allows 4DOS to determine automatically whether an ANSI driver is installed (the default). /A1 forces 4DOS to assume an ANSI driver is installed. /A2 forces 4DOS to assume an ANSI driver is not installed. See the 412 ANSI directive. /B: (Bright background) This option determines whether 4DOS configures your video adapter for blinking text (/B0, the default) or bright background colors (/B1), or leave the video bright / blink configuration unchanged (/B2). See 892Colors and Color Names for a detailed discussion of this option. Also see the 461BrightBG directive. /C: (Compound character) This option sets the character used for separating 041multiple commands on the same line. The default is the caret [^]. You cannot use any of the redirection characters [<>|], or the blank, tab, comma, or equal sign as the command separator. The command separator is saved by 665SETLOCAL and restored by 621ENDLOCAL. This example changes the separator to a tilde [~]: !INDENT 5 5 5 5 c:\> setdos /c~ (You can specify either the character itself, or its ASCII code as a decimal number, or a hexadecimal number preceded by 0x.) If you want to share batch files or aliases between 4DOS and 0204NT or 021Take Command, see the 166%+ variable, which retrieves the current command separator, and 054Special Character Compatibility for details on using compatible command separators for all the products you use. Also see the 418CommandSep directive. !INDENT 5 5 0 5 /D: (Descriptions) This option controls whether file processing commands like 606COPY, 609DEL, 646MOVE, and 658REN process file descriptions along with the files they belong to. /D1 turns description processing on, which is the default. /D0 turns description processing off. Also see the 424Descriptions directive. !INDENT 5 5 5 5 You can also use /D to set the name of the hidden file in each directory that contains file descriptions. To do so, follow /D with the filename in quotes: c:\> setdos /d"files.bbs" Use this option with caution because changing the name from the default will make it difficult to transfer file descriptions to another system. This option is provided for bulletin board system operators and others who have special needs. Also see the 423DescriptionName directive. !INDENT 5 5 0 5 /E: (Escape character) This option sets the character used to suppress the normal meaning of the following character. Any character following the 086escape character will be passed unmodified to the command. The default escape character is Ctrl-X (ASCII 24, which appears on screen as an up-arrow []). (You can specify either the character itself, or its ASCII code as a decimal number, or a hexadecimal number preceded by 0x.) You cannot use any of the redirection characters [<>|] or the blank, tab, comma, or equal sign as the escape character. The escape character is saved by 665SETLOCAL and restored by 621ENDLOCAL. Certain characters (b, c, e, f, k, n, q, r, s, and t) have special meanings when immediately preceded by the escape character. !INDENT 5 5 5 5 If you want to share batch files or aliases between 4DOS and 4OS2, 0204NT, or Take Command, see the 165%= variable, which retrieves the current escape character, and 054Special Character Compatibility for details on using compatible escape characters for all the products you use. Also see the 426EscapeChar directive. !INDENT 5 5 0 5 /F: (Format for @EVAL) This option lets you set default decimal precision for the @EVAL variable function. The maximum precision is 20 digits to the left of the decimal point and up to 10 digits to the right of the decimal point. Also see the 427EvalMax and 428EvalMin directives. !INDENT 5 5 5 5 The general form of this option is /Fx.y, where the x value sets the minimum number of digits to the right of the decimal point and the y value sets the maximum number of digits. You can use =x,y instead of =x.y if the comma is your decimal separator. Both values can range from 0 to 10. You can specify either or both values: /F2.5, /F2, and /F.5 are all valid entries. If x is greater than y, it is ignored; if only x is specified, y is set to the same value (e.g. /F2 is equivalent to /F2.2). See the 263@EVAL function if you want to set the precision for a single computation. !INDENT 5 5 0 5 /G: (Numeric separators) This option sets the decimal and thousands separator characters. The format is /Gxy where "x" is the new decimal separator and "y" is the new thousands separator. Both characters must be included. The only valid settings are /G., (period is the decimal separator, comma is the thousands separator); /G,. (the reverse); or /G0 to remove any custom setting and use the default separators associated with your current country code (this is the default). !INDENT 5 5 5 5 The decimal separator is used for 263@EVAL, numeric 633IF and 634IFF tests, version numbers, and other similar uses. The thousands separator is used for numeric output, and is skipped when performing calculations in @EVAL. Also see the 421DecimalChar and 445ThousandsChar directives. !INDENT 5 5 0 5 /I: (Internal) This option allows you to disable or enable internal commands. To disable a command, precede the command name with a minus [-]. To re-enable a command, precede it with a plus [+]. For example, to disable the internal LIST command to force 4DOS to use an external command: !INDENT 5 5 5 5 c:\> setdos /i-list To re-enable all disabled commands use /I*. !INDENT 5 5 0 5 /L: (Line) This option controls how 4DOS gets its input from the command line. /L0 tells 4DOS to use character input (the default). /L1 tells it to use line input (like COMMAND.COM and CMD.EXE). /L1 will disable command-line editing, history recall, filename completion, and the directory history window. It should only be used if it is needed for compatibility with a specific program. If you have a program that requires line input, you can use the following line in an alias or batch file to change the line input option just for that single program: !INDENT 5 5 5 5 setdos /L1 ^ program %& ^ setdos /L0 See 751Compatibility for information on programs which require this option. Also see the 436LineInput directive. !INDENT 5 5 0 5 /M: (Mode) This option controls the initial line editing mode. To start in overstrike mode at the beginning of each command line, use /M0 (the default). To start in insert mode, use /M1. If any other digit is used, 4DOS will not force either editing mode when the prompt is displayed; the editing mode last used will be retained. Also see the 425EditMode directive. /N: (No clobber) This option controls output 051redirection. /N0 means existing files will be overwritten by output redirection (with >) and that appending (with >>) does not require the file to exist already. This is the default. /N1 means existing files may not be overwritten by output redirection, and that when appending the output file must exist. A /N1 setting can be overridden with the [!] character. If you use /N1, you may have problems with a few unusual programs that shell out to run a command with redirection, and expect to be able to overwrite an existing file. Also see the 438NoClobber directive and the table of all 055output redirection operators. /P: (Parameter character) This option sets the character used after a percent sign to specify all or all remaining command-line arguments in a 102batch file, 101alias, or 696user-defined function (e.g., %& or %n&). The default is the ampersand [&]. (You can specify either the character itself, or its ASCII code as a decimal number, or a hexadecimal number preceded by 0x.) The parameter character is saved by 665SETLOCAL and restored by 621ENDLOCAL. !INDENT 5 5 5 5 If you want to share batch files or aliases between 4DOS and 0204NT or Take Command, see 054Special Character Compatibility for details on selecting compatible parameter characters for all the products you use. Also see the 439ParameterChar directive. !INDENT 5 5 0 5 /R: (Rows) This option sets the number of screen rows used by the video display. Normally 4DOS detects the screen size, but if you have a non-standard display you may need to set it explicitly. This option does not affect screen scrolling (that is controlled by your video driver, the BIOS, or ANSI.SYS). It also does not set the screen size; it is used only to specify the screen height for LIST, SELECT, paged output options (i.e., TYPE /P), and error checking in screen output commands. Also see the 443ScreenRows directive. /S: (Shape) This option sets the cursor shape. The format is /So:i where o is the cursor size for overstrike mode, i the cursor size for insert mode. The size is entered as a percentage of the total character height. The default values are 10:100 (a 10% underscore cursor for overstrike mode, and a 100% block cursor for insert mode). Because of the way video BIOSes and drivers remap the cursor shape, you may not get a smooth progression in the cursor size from 0% - 100%. To disable the cursor, enter /S0:0. !INDENT 5 5 5 5 If either value is -1, 4DOS will not attempt to modify the cursor shape at all. You can use this feature to give another program full control of the cursor shape. You can retrieve the current cursor shape values with the 178_CI and 179_CO internal variables. Also see the 420CursorOver and 419CursorIns directives. !INDENT 5 5 0 5 /U: (Upper) This option controls the default case (upper or lower) for file and directory names displayed by internal commands like COPY and DIR. /U0 displays file names in lower case (the default). /U1 displays file names in the traditional upper case. Also see the 446UpperCase directive. !INDENT 5 5 5 5 The /U setting is ignored for filenames on LFN drives. Names on such drives are always displayed in the case in which they are stored. See 945File Names for additional details. !INDENT 5 5 0 5 /V: (Verbose) This option controls the default for command echoing in batch files. /V0 disables echoing of batch file commands unless 619ECHO is explicitly set ON. /V1, the default setting, enables echoing of batch file commands unless ECHO is explicitly set OFF. Also see 104Echoing in Batch Files. !INDENT 5 5 5 5 /V2 forces echoing of all batch file commands, even if ECHO is set OFF or the line begins with an "@". This allows you to turn echoing on for a batch file without editing the batch file and removing the ECHO OFF command(s) within it. /V2 is intended for debugging, and can be set with SETDOS, but not with the 648OPTION command or the 414BatchEcho directive in 4DOS.INI. For more information see 112Debugging Batch Files. !INDENT 5 5 0 5 /W: (Switch character) This option sets the DOS switch character (normally a slash [/]). It will not work in Datalight ROM-DOS. The DOS switch character setting may be ignored by application programs. Note that setting the switch character to anything but a slash [/] will probably break all of your existing batch files and aliases! /X[+|-]n: (Expansion and special characters) This option enables and disables alias and environment variable expansion, and controls whether special characters have their usual meaning or are treated as text. It is most often used in batch files to process text strings which may contain special characters. !INDENT 5 5 5 5 The features enabled or disabled by /X are numbered. All features are enabled when 4DOS starts, and you can re-enable all features at any time by using /X0. To disable a particular feature, use /X-n, where n is the feature number from the list below. To re-enable the feature, use /X+n. To enable or disable multiple individual features, list their numbers in sequence after the + or - (e.g. /X-345 to disable features 3, 4, and 5). The features are: 1 All alias expansion. 2 Nested alias expansion only. 3 All variable expansion (includes environment variables, batch file parameters, and alias parameters). 4 Nested variable expansion only. 5 Multiple commands, conditional commands, and piping (affects the command separator, ||, &&, |, and |&). 6 Redirection (affects < , >, >&, >&>, etc.). 7 Quoting (affects back-quotes [`], double quotes ["], and square brackets []). 8 Escape character. 9 User-defined functions. If nested alias expansion is disabled, the first alias of a command is expanded but any aliases it invokes are not expanded. If nested variable expansion is disabled, each variable is expanded once, but variables containing the names of other variables are not expanded further. For example, to disable all features except alias expansion while you are processing a text file containing special characters: setdos /x-35678 ... [perform text processing here] setdos /x0 !INDENT 5 5 0 5 /Y: (Debug batch file) /Y1 enables the built-in batch file debugger. The debuggger allows you to "single-step" through a batch file line by line, with the file displayed in a popup window as it executes. For complete details on using the debugger see 112Debugging Batch Files (this topic also covers additional debugging techniques which do not require stepping through each line individually). !INDENT 5 5 5 5 To start the debugger, insert a SETDOS /Y1 command at the beginning of the portion of the batch file you want to debug, and a SETDOS /Y0 command at the end. You cannot use the batch debugger with 116REXX files; it can only be used with normal 4DOS batch files. You can also invoke SETDOS /Y1 from the prompt, but because the debugger is automatically turned off whenever 4DOS returns to the prompt, you must enter the SETDOS command and the batch file name on the same line, for example: c:\> setdos /y1 ^ mybatch.btm !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 827 SETERROR !TTY Purpose: Set the ERRORLEVEL value and the DOS error code. Format: SETERROR errorlevel errorlevel: New value for ERRORLEVEL. !TTY Usage SETERROR set the value of the ERRORLEVEL (162?) internal variable (i.e. the exit code of the last external program) and the last-error code in DOS to the specified value. ;--------------------------------------------------------------------------- !TOPIC 665 SETLOCAL !TTY Purpose: Save a copy of the current disk drive, directory, environment, alias list, and special characters. Format: SETLOCAL !TTY See also: 621ENDLOCAL. Usage SETLOCAL is used in batch files to save the default disk drive and directory, the environment, the alias list and the command separator, escape character, parameter character, decimal separator, and thousands separator. You can then change their values and later restore the original values with ENDLOCAL. For example, this batch file fragment saves everything, removes all aliases so that user aliases will not affect batch file commands, changes the disk and directory, changes the command separator, runs a program, and then restores the original values: setlocal unalias * cdd d:\test setdos /c~ program ~ echo Done! endlocal SETLOCAL and ENDLOCAL are nestable up to 8 levels deep within a batch file. You cannot use SETLOCAL in an alias or at the command line. An ENDLOCAL is performed automatically at the end of a batch file if you forget to do so. If you invoke one batch file from another without using CALL, the first batch file is terminated, and an automatic ENDLOCAL is performed; the second batch file inherits the settings as they were prior to any unterminated SETLOCAL. Do not load memory-resident programs (TSRs) from a batch file while SETLOCAL is in effect, as SETLOCAL will have to temporarily set aside some amount of memory to store the current settings. If you do, when ENDLOCAL is executed and the memory used by SETLOCAL is released, a "hole" will be left in memory below the TSR. This is not usually harmful, but wastes memory. However, in most cases, it only applies when loading TSRs into conventional memory. A combination of SETLOCAL / ENDLOCAL and 680UNSET can be used to slightly reduce the memory footprint of most TSRs loaded into other memory regions (usually Upper Memory), or at least avoid some possible memory fragmentation in that region. (This mainly applies to TSRs which don't free their environment segment when becoming resident.) You can temporarily shrink the environment down to the required minimum for the TSR to work using UNSET * -- most TSRs do not need any environment variables at all, and those few which do will usually only look for very specific variables during initialization. In addition to this, it is often possible to temporarily assign a SUBST drive to make a long load path to the TSR as short as possible in order to reduce the size of the environment appendage under DOS 3.0 and above (which contains the full path to the loaded driver). For example: setlocal unset * subst b: d:\dir1\dir2\dir3\dir4\dir5\dir6\dir7\dir8 lh b:\tsr.com ... subst b: /d endlocal ;--------------------------------------------------------------------------- !TOPIC 666 SHIFT !TTY Purpose: Allows the use of more than 255 batch file parameters in a batch file. Format: SHIFT [n | /n] n: Number of positions to shift. !TTY Usage SHIFT is provided for compatibility with older batch files, where it was used to access more than 10 parameters. 4DOS supports 256 parameters (%0 to %255), so you don't need to use SHIFT for batch files running exclusively under JP Software command processors. SHIFT moves each of the batch file parameters n positions to the left. The default value for n is 1. SHIFT 1 moves the parameter in %1 to position %0, the parameter in %2 becomes %1, etc. You can reverse a SHIFT by giving a negative value for n (i.e., after SHIFT -1, the former %0 is restored, %0 becomes %1, %1 becomes %2, etc.). SHIFT also affects the special parameters %n& (command-line tail) and %# (number of command arguments). For compatibility with CMD.EXE, SHIFT does not affect the %* parameter. For example, create a batch file called TEST.BAT: echo %1 %2 %3 %4 shift echo %1 %2 %3 %4 shift 2 echo %1 %2 %3 %4 shift -1 echo %1 %2 %3 %4 Executing TEST.BAT produces the following results: c:\> test one two three four five six seven one two three four two three four five four five six seven three four five six If you add a slash before the value n, the value determines the postion at which to begin the shift. For example: shift /2 leaves parameters %0 and %1 unchanged, and moves the value of %3 to postion %2, %4 to %3, etc. The value after the slash cannot be negative, and shifts performed with the slash cannot be undone later in the batch file. ;--------------------------------------------------------------------------- !TOPIC 668 SWAPPING !TTY Purpose: Enable or disable 4DOS swapping, or display the swapping state. Format: SWAPPING [ON | OFF] !TTY Usage SWAPPING temporarily disables or enables the swapping of the transient portion of 4DOS to expanded memory, to XMS extended memory, or to disk (see the 391Swapping directive in 4DOS.INI for more information). Setting SWAPPING OFF may be useful for speeding up batch files (including AUTOEXEC.BAT) when 4DOS is using disk swapping. When you are running several small programs from a batch file, disk swapping can sometimes cause a noticeable delay. However, if you disable swapping, there will be about 245K less memory available for large application programs. The following batch file fragment disables swapping, runs several programs, and then re-enables swapping: swapping off c:\util\mouse c:\video\ansi.com c:\bin\cache.com swapping on If you enter SWAPPING with no arguments, 4DOS displays the current swapping type (XMS, EMS, Disk, or None) and state: c:\> swapping SWAPPING (XMS) is ON Note: 4DOS reports SWAPPING (XMS) is ON, it will actually swapped out of DOS completely by vDosPlus. Setting SWAPPING OFF does not close the disk swap file or release any reserved EMS memory. You may have trouble if you load memory-resident programs (TSRs) with SWAPPING OFF and unload them with SWAPPING ON, or vice versa. Many TSRs expect the system to be in the same state when they unload that it was in when they loaded, and variation from this norm may cause the TSR to unload improperly or hang your system. ;--------------------------------------------------------------------------- !TOPIC 669 SWITCH !TTY Purpose: Select commands to execute based on a value. Format: SWITCH expression CASE value1 [.OR. value2] ... commands CASE value3 commands [DEFAULT commands] ENDSWITCH expression: An environment variable, internal variable, variable function, text string, or a combination of these elements, that is used to select a group of commands. value1, value2, etc.: A value to test, or multiple values connected with .OR. commands: One or more commands to execute if the expression matches the value. If you use multiple commands, they must be separated by command separators or placed on separate lines in the batch file. !TTY See also: 633IF, and 634IFF. Usage SWITCH can only be used in batch files. It allows you to select a command or group of commands to execute based on the possible values of a variable or a combination of variables and text. The SWITCH command is always followed by an expression created from environment variables, internal variables, variable functions, and text strings, and then by a sequence of CASE statements matching the possible values of that expression. If one of the values in a CASE statement matches the expression, the commands following that CASE statement are executed, and all subsequent CASE statements and the commands which follow them are ignored. If no matches are found, the commands following the optional DEFAULT statement are executed. If there are no matches and there is no DEFAULT statement, no commands are executed by SWITCH. After all of the commands following the CASE or DEFAULT statement are executed, the batch file continues with the commands that follow ENDSWITCH. The SWITCH command must be the last (or only) command on the line. Each CASE, DEFAULT, or ENDSWITCH statement must appear on a line by itself. Multiple values in CASE must be separated by the .OR. operator; .AND. and .XOR. are not legal. For example, the following batch file fragment displays one message if the user presses A, another if user presses B or C, and a third if the user presses any other key: inkey Enter a keystroke: %%key switch %key case A echo It's an A case B .or. C echo It's either B or C default echo It's not A, B, or C endswitch In the example above, the value of a single environment variable was used for the expression. You will probably find that this is the best method to use in most situations. However, you can use other kinds of expressions if necessary. The first example below selects a command to execute based on the length of a variable, and the second bases the action on a quoted text string stored in an environment variable: switch %@len[%var1] case 0 echo Missing var1 case 1 echo Single character ... endswitch switch "%string1" case "This is a test" echo Test string case "The quick brown fox" echo It's the fox ... endswitch The SWITCH command is a multiline structure. You can't put it in a 085command group or pack it into a single line. (This is why SWITCH cannot be used in aliases.) However, commands within a CASE or DEFAULT block can use command groups or the 041command separator in the normal way. SWITCH commands can be nested. The permissible nesting level depends on the amount of free space in 4DOS's internal stack; if you receive a stack overflow error when using SWITCH in complex, nested command sequences, see the 574StackSize directive. You can exit from all SWITCH / ENDSWITCH processing by using 630GOTO to a line past the last ENDSWITCH. ;--------------------------------------------------------------------------- !TOPIC 698 TAIL !TTY Purpose: Display the end of the specified file(s). Format: TAIL [/A:[[+|-]rhsad] /Cn /I"text" /Nn /P /Q /V] [@file] file... file: The file or list of files that you want to display. @file: A text file containing the names of the files to display, one per line (see 057@file lists for details). /A: (Attribute select) /P(ause) /C (Number of bytes) /Q(uiet) /I (match description) /V(erbose) /N (Number of lines) !TTY See also: 697HEAD, 640LIST, and 677TYPE. File Selection Supports extended 073wildcards, 074ranges, 079multiple file names, and 080include lists. Usage The TAIL command displays the last part of a file. It is normally only useful for displaying ASCII text files. Executable files (.COM and .EXE) and many data files may be unreadable when displayed with TAIL because they include non-alphanumeric characters. You can press Ctrl-S to pause TAIL's display and then any key to continue. To display the last 15 lines of the files MEMO1 and MEMO2: c:\> tail /n15 memo1 memo2 To display text from the clipboard, use CLIP: as the file name. CLIP: will not return any data unless the clipboard contains text. See 051redirection for additional information on CLIP:, including details on when you can use the clipboard under 4DOS. Options !INDENT 5 5 0 5 /A:: (Attribute select) Select only those files that have the specified attribute(s) set. The colon [:] after /A is required. Preceding an attribute letter with a hyphen [-] will select files that do not have that attribute set. You can OR attributes by preceding each attribute letter with a plus sign [+]. !INDENT 5 5 5 5 The attributes are: R Read-only S System H Hidden A Archive If no attributes are listed at all (e.g., TAIL /A: ...), TAIL will select all files including hidden and system files. If attributes are combined, all the specified attributes must match for a file to be selected. For example, /A:RHS will select only those files with all three attributes set. !INDENT 5 5 0 5 /C: Display the specified number of bytes. /C accepts b, k, or m modifiers at the end of the number. b is the number of 512-byte blocks, k is 1000's of bytes, K is kilobytes, m is millions of bytes, and M is megabytes. /I"text": Select files by matching text in their descriptions. The text can include 073wildcards and extended wildcards. The search text must be enclosed in quotation marks, and must follow the /I immediately, with no intervening spaces. You can select all filenames that have a description with /I"[?]*", or all filenames that do not have a description with /I"[]". /N: The number of lines to display. The default is 10. /P: (Pause) Prompt after displaying each page. Your options at the prompt are explained in detail under 045Page and File Prompts. /Q: (Quiet) Don't display a header for each file. This is the default behavior unless /V is specified. /V: (Verbose) Display a header for each file. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 670 TEE !TTY Purpose: Copy standard input to both standard output and a file. Format: TEE [/A] file... file: One or more files that will receive the "tee-d" output. /A(ppend) !TTY See also: 686Y, 052piping and 051redirection. Usage TEE is normally used to "split" the output of a program so that you can see it on the display and also save it in a file. It can also be used to capture intermediate output before the data is altered by another program or command. TEE gets its input from standard input (usually the piped output of another command or program), and sends out two copies: one goes to standard output, the other to the file or files that you specify. TEE is not likely to be useful with programs which do not use standard output, because these programs cannot send output through a pipe. For example, to search the file DOC for any lines containing the string "4DOS", make a copy of the matching lines in 4.DAT, sort the lines, and write them to the output file 4D.DAT: c:\> find "4DOS" doc | tee 4.dat | sort > 4d.dat If you are typing at the keyboard to produce the input for TEE, you must enter a Ctrl-Z to terminate the input. When using TEE with a pipe, the previous command writes its output to a temporary file. When that command finishes, TEE begins operation and can read the temporary file, display the output, and write it to the file(s) named in the TEE command. Options !INDENT 5 5 0 5 /A: (Append) Append to the file(s) rather than overwriting them. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 671 TEXT !TTY Purpose: Display a block of text in a batch file. Format: TEXT . . . ENDTEXT !TTY See also: 619ECHO, 660SCREEN, 661SCRPUT, and 684VSCRPUT. Usage TEXT can only be used in batch files. The TEXT command is useful for displaying menus or multi-line messages. TEXT will display all subsequent lines in the batch file until terminated by ENDTEXT. Both TEXT and ENDTEXT must be entered as the only command on the line. To redirect the entire block of text, use redirection on the TEXT command itself, but not on the actual text lines or the ENDTEXT line. No environment variable expansion or other processing is performed on the lines between TEXT and ENDTEXT; they are displayed exactly as they are stored in the batch file. You can change screen colors by inserting 915ANSI escape sequences anywhere in the text block. You can also use a 604CLS or 605COLOR command to set the screen color before executing the TEXT command. The following batch file fragment displays a simple menu: @echo off cls screen 2 0 text Enter one of the following: 1 - Spreadsheet 2 - Word Processing 3 - DOS Utilities 4 - Exit endtext inkey /k"1234" Enter your selection: %%key ;--------------------------------------------------------------------------- !TOPIC 672 TIME !TTY Purpose: Display or set the current system time. Format: TIME [/T] [hh[:mm[:ss]]] [AM | PM] hh: The hour (0 - 23). mm: The minute (0 - 59). ss: The second (0 - 59), set to 0 if omitted. /T: (display only) !TTY See also: 608DATE. Usage If you don't enter any parameters, TIME will display the current system time and prompt you for a new time. Press Enter if you don't wish to change the time. You can supply a new time, but it is ignored by vDosPlus unless you set the SYNCTIME=OFF directive in its config file. time Mon Jun 19, 2015 9:30:06 New time (hh:mm:ss): Option !INDENT 5 5 0 5 /T: (Display only) Displays the current time, but does not prompt you for a new time. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 673 TIMER !TTY Purpose: TIMER is a system stopwatch. Format: TIMER [ON|OFF] [/1 /2 /3 /Q /S] ON: Force the stopwatch to restart. OFF: Force the stopwatch to stop. /1 (stopwatch #1, default) /Q(uiet) /2 (stopwatch #2) /S(plit) /3 (stopwatch #3) !TTY Usage The TIMER command turns a system stopwatch on and off. When you first run TIMER, the stopwatch starts. c:\> timer Timer 1 on: 12:21:46 When you run TIMER again, the stopwatch stops and the elapsed time is displayed. c:\> timer Timer 1 off: 12:21:58 Elapsed time: 0:00:12.06 There are three stopwatches available (1, 2, and 3) so you can time multiple overlapping events. By default, TIMER uses stopwatch #1. TIMER is particularly useful for timing events in batch files. For example, to time both an entire batch file, and an intermediate section of the same file, you could use commands like this: rem Turn on timer 1 timer rem Do some work here rem Turn timer 2 on to time the next section timer /2 rem Do some more work echo Intermediate section completed rem Display time taken in intermediate section timer /2 rem Do some more work rem Now display the total time timer The smallest interval TIMER can measure (same as the elapsed time resolution or granularity) is 0.01 seconds. The largest possible interval that TIMER can measure is 23 hours, 59 minutes, 59.99 seconds. Options !INDENT 5 5 0 5 /1: Use timer #1 (the default). /2: Use timer #2. /3: Use timer #3. /Q: (Quiet) Don't display any messages. /S: (Split) Display a split time without stopping the timer. To display the current elapsed time but leave the timer running: !INDENT 5 5 5 5 c:\> timer /s Timer 1 elapsed: 0:06:40.63 !INDENT 5 5 0 5 ON: Start the timer regardless of its previous state (on or off). Otherwise the TIMER command toggles the timer state (unless /S is used). OFF: Stops the timer. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 674 TOUCH !TTY Purpose: Change a file's date and time stamps. Format: TOUCH [/A:[[+|-]rhsad]/C /D[acw][mm-dd-yy] /E /F /I"text" /N /Q /R[:acw] reffile /S /T[acw][hh:mm]] [@file] file... reffile: A file whose date and / or time stamps are to be transferred to one or more other files. file: One or more files whose date and/or time stamps are to be changed. @file: A text file containing the names of the files to touch, one per line (see 057@file lists for details). /A: (Attribute select) /N(othing) /C(reate file) /Q(uiet) /D(ate) /R(epeat) /E (No error messages) /S(ubdirectories) /F(orce read-only files) /T(ime) /I (match descriptions) !TTY File Selection Supports extended 073wildcards, 074ranges, 079multiple file names, and 080include lists. Use wildcards with caution on LFN volumes; see 081LFN File Searches for details. Usage TOUCH is used to change the date and/or time of a file. You can use it to be sure that particular files are included or excluded from an internal command, backup program, compiler MAKE utility, or other program that selects files based on their time and date stamps, or to set a group of files to the same date and time for consistency. TOUCH should be used with caution, and in most cases should only be used on files you create. Many programs depend on file dates and times to perform their work properly. In addition, many software manufacturers use file dates and times to signify version numbers. Indiscriminate changes to date and time stamps can lead to confusion or incorrect behavior of other software. TOUCH normally works with existing files, and will display an error if the file you specify does not exist, or has the read-only attribute set. To create the file if it does not already exist, use the /C switch. To force a date and time change for read-only files, use the /F switch. TOUCH displays the date, time, and full name of each file whose timestamp is modified. To disable this output, use /Q. If you don't specify a date or a time, TOUCH will default to the current date and time from your system clock. For example, to set the time stamp of all .C files in the current directory to the current date and time: d:\source> touch *.c 6-12-00 11:13:58 D:\SOURCE\MAIN.C 6-12-00 11:13:58 D:\SOURCE\INIT.C ... If you specify a date but not a time, the time will default to the current time from your system clock. Similarly, if you specify a time but not a date, the date will be obtained from the system clock. If you enter /D or /T with no argument, TOUCH will preserve the existing date or time. To transfer the date and time from one file to another use /R; see below for details. Due to operating system limitations, TOUCH can not set the date and time for directories, even if you use the /A:d switch. On LFN files, TOUCH sets the "modified" or "last write" date and time by default. By adding the appropriate character to the /D or /T switch, you can set the other date and time stamps that are maintained for each file: !NOWRAP a last access date and time (access time can not be set on LFN volumes). c creation date and time. w last write date and time (default). !WRAP Options !INDENT 5 5 0 5 /A:: (Attribute select) Select only those files that have the specified attribute(s) set. The colon [:] after /A is required. Preceding an attribute letter with a hyphen [-] will select files that do not have that attribute set. You can OR attributes by preceding each attribute letter with a plus sign [+]. !INDENT 5 5 5 5 The attributes are: R Read-only D subDirectory H Hidden A Archive S System If no attributes are listed at all (e.g., TYPE /A: ...), TOUCH will select all files and subdirectories including hidden and system files. If attributes are combined, all the specified attributes must match for a file to be selected. For example, /A:RHS will select only those files with all three attributes set. !INDENT 5 5 0 5 /C: (Create file) Create the file (as a zero-byte file) if it does not already exist. You cannot use wildcards with /C, but you can create multiple files by listing them individually on the command line. /D: (Date) Specify the date that will be set for the selected files. If the date is not specified, TOUCH will use the current date. For LFN files you can use /Da, /Dc, or /Dw, followed by the date, to explicitly specify the last access, creation, or last write date stamp. The date must be entered using the proper format for your current country settings. You can also use the ISO 8601 international date format "yyyy-mm-dd", the ISO 8601 week date format "yyyy-Www-d", where yyyy = year, ww = week, d = week day, or the ISO 8601 ordinal date format "yyyy-ddd", where yyyy = year, ddd = day of the year. /E: (No error messages) Suppress all non-fatal error messages, such as "File not found." Fatal error messages, such as "Drive not ready," will still be displayed. This option is most useful in batch files. /F: (Force read-only files) Remove the read-only attribute from each file before changing the date and time, and restore it afterwards. Without /F, attempting to change the date and time on a read-only file will usually cause an error. /I"text": Select files by matching text in their descriptions. The text can include 073wildcards and extended wildcards. The search text must be enclosed in quotation marks, and must follow the /I immediately, with no intervening spaces. You can select all filenames that have a description with /I"[?]*", or all filenames that do not have a description with /I"[]". /N: (Nothing) Do everything but actually change the date and time. /Q: (Quiet) Do not display the new date and time and the full name for each file. /R: (Repeat) The date and time for the specified file(s) will be set to the current date and time for the reference file whose name immediately follows the /R. For LFN files, you can use /R:c or /R:w, followed by the file name, to specify the last creation or last write time stamp. However, files on FAT-based volumes do not have a last access time, so TOUCH /R:a will have no effect on such files. If /D or /T is used after /R, the specified date or time will override the date and/or time from the reference file. For example, to set the date for file X2 to match the date for X1, and also set the time for X2 to 11:42 AM, you could use: !INDENT 5 5 5 5 c:\> touch /r x1 /t11:42 x2 !INDENT 5 5 0 5 /S: (Subdirectories): TOUCH all matching files in the specified directory and its subdirectories. Unlike most 4DOS commands, TOUCH /S will search into subdirectories with the hidden or system attributes set. /T: (Time) Specify the time that will be set for the selected files, in hh:mm format. If the time is not specified, TOUCH will use the current time. For LFN files you can use /Tc or /Tw, followed by the time, to explicitly specify the last access, creation, or last write time stamp. However, files on FAT-based volumes do not have a last access time, so TOUCH /Ta will have no effect on such files. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 774 TRANSIENT !TTY Purpose: Toggle the shell's transient mode. Format: TRANSIENT [ON | OFF] !TTY Usage TRANSIENT can only be used in batch files. It allows you to change the shell's transient mode (i.e., whether it was started with a /C), so that you can make a transient session permanent (or vice versa). ;--------------------------------------------------------------------------- !TOPIC 675 TREE !TTY Purpose: Display a graphical directory tree. Format: TREE [/A /B /F /H /P /S /T[:acw]] dir... dir: The directory to use as the start of the tree. If more than one directory is specified, TREE will display a directory tree for each. /A(SCII) /P(ause) /B(are) /S (file size) /F(iles) /T(ime and date) /H(idden directories) !TTY Usage The TREE command displays a graphical representation of the directory tree using standard or extended ASCII characters. For example, to display the directory structure on drive C: c:\> tree c:\ You can print the display, save it in a file, or view it with 640LIST by using the usual 051redirection and 052piping operators. Be sure to review the /A option before attempting to print the TREE output. The options discussed below specify the amount of information included in the display. Options !INDENT 5 5 0 5 /A: (ASCII) Display the tree using standard ASCII characters. You can use this option if you want to save the directory tree in a file for further processing or print the tree on a printer which does not support the graphical symbols that TREE normally uses. /B: (Bare) Display the full pathname of each directory, without any of the line-drawing characters. /F: (Files) Display files as well as directories. If you use this option, the name of each file is displayed beneath the name of the directory in which it resides. /H: (Hidden) Display subdirectories with the hidden or system attributes set. If you combine /H and /F, hidden and system files will also be displayed. /P: (Pause) Wait for a key to be pressed after each screen page before continuing the display. Your options at the prompt are explained in detail in 045Page and File Prompts. /S: (Size) Display the size of each file. This option is only useful when combined with /F. /T: (Time and date) Display the time and date for each directory. If you combine /T and /F, the time and date for each file will also be displayed. For LFN files, the time and date of the last write will be shown by default. You can select a specific time and date stamp by using the following variations of /T: !INDENT 5 5 5 5 /T:a last access date and time (access time is not saved on LFN volumes). /T:c creation date and time. /T:w last write date and time (default). !INDENT 0 For comparison with the external DOS TREE.COM command refer to the 65535external DOS help system. ;--------------------------------------------------------------------------- !TOPIC 676 TRUENAME !TTY Purpose: Find the fully-expanded name for a file. Format: TRUENAME file file: The file whose name TRUENAME will report. !TTY See also: 325@TRUENAME variable function. Usage On LFN drives TRUENAME returns the short name for the file, for example: c:\> truename "Program Files" C:\PROGRA~1 ;--------------------------------------------------------------------------- !TOPIC 677 TYPE !TTY Purpose: Display the contents of the specified file(s). Format: TYPE [/A:[[+|-]rhsad] /I"text" /L /P /V] [@file] file... file: The file or list of files that you want to display. @file: A text file containing the names of the files to display, one per line (see 057@file lists for details). /A: (Attribute select) /L(ine numbers) /I (match description) /P(ause) /V(erbose) !TTY See also: 697HEAD, 640LIST, and 698TAIL. File Selection Supports extended 073wildcards, 074ranges, 079multiple file names, and 080include lists. Usage The TYPE command displays a file. It is normally only useful for displaying ASCII text files. Executable files (.COM and .EXE) and many data files may be unreadable when displayed with TYPE because they include non-alphanumeric characters. To display the files MEMO1 and MEMO2: c:\> type /p memo1 memo2 You can press Ctrl-S to pause TYPE's display and then any key to continue. To display text from the clipboard, use CLIP: as the file name. CLIP: will not return any data unless the clipboard contains text. See 051redirection for additional information on CLIP:, including details on when you can use the clipboard under 4DOS. You will probably find LIST to be more useful for displaying files. However, the TYPE /L command used with 051redirection is useful if you want to add line numbers to a file, for example: c:\> type /l myfile > myfile.num Options !INDENT 5 5 0 5 /A:: (Attribute select) Select only those files that have the specified attribute(s) set. The colon [:] after /A is required. Preceding an attribute letter with a hyphen [-] will select files that do not have that attribute set. You can OR attributes by preceding each attribute letter with a plus sign [+]. !INDENT 5 5 5 5 The attributes are: R Read-only S System H Hidden A Archive If no attributes are listed at all (e.g., TYPE /A: ...), TYPE will select all files including hidden and system files. If attributes are combined, all the specified attributes must match for a file to be selected. For example, /A:RHS will select only those files with all three attributes set. !INDENT 5 5 0 5 /I"text": Select files by matching text in their descriptions. The text can include 073wildcards and extended wildcards. The search text must be enclosed in quotation marks, and must follow the /I immediately, with no intervening spaces. You can select all filenames that have a description with /I"[?]*", or all filenames that do not have a description with /I"[]". /L: (Line numbers) Display a line number preceding each line of text. /P: (Pause) Prompt after displaying each page. Your options at the prompt are explained in detail under 045Page and File Prompts. /V: (Verbose) Display a file name header for each file. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 678 UNALIAS !TTY Purpose: Remove aliases from the alias list. Format: UNALIAS [/Q /R file] [alias...] or UNALIAS * alias: One or more aliases to remove from memory. file: One or more files to read for alias definitions. /Q(uiet) /R(ead file) !TTY See also: 595ALIAS and 622ESET. Usage 4DOS maintains a list of the aliases that you have defined. The UNALIAS command will remove aliases from that list. UNALIAS supports wildcards in the alias name, and you can remove one or more aliases by name, or you can delete the entire alias list by using the command UNALIAS *. For example, to remove the alias DDIR: c:\> unalias ddir To remove all the aliases: c:\> unalias * To remove all the aliases that begin with "DD": [c:\] unalias dd* If you keep aliases in a file that can be loaded with the 595ALIAS /R command, you can remove the aliases by using the UNALIAS /R command with the same file name: c:\> unalias /r alias.lst This is much faster than removing each alias individually in a batch file, and can be more selective than using UNALIAS *. Options !INDENT 5 5 0 5 /Q: (Quiet) Prevents UNALIAS from displaying an error message if one or more of the aliases does not exist. This option is most useful in batch files, for removing a group of aliases when some of the aliases may not have been defined. /R: (Read) Read the list of aliases to remove from a file. The file format should be the same format as that used by the 595ALIAS /R command. You can use multiple files with one UNALIAS /R command by placing the names on the command line, separated by spaces: !INDENT 5 5 5 5 c:\> unalias /r alias1.lst alias2.lst !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 699 UNFUNCTION !TTY Purpose: Remove user-defined variable functions. Format: UNFUNCTION [/Q /R file] [function...] or UNFUNCTION * function: One or more functions to remove from memory. file: One or more files to read for function definitions. /Q(uiet) /R(ead file) !TTY See also: 696FUNCTION. Usage 4DOS maintains a list of the 241variable functions that you have defined. The UNFUNCTION command will remove user-defined definitions from that list. UNFUNCTION supports wildcards in the function name, and you can remove one or more functions by name, or you can delete the entire function list by using the command UNFUNCTION *. Options !INDENT 5 5 0 5 /Q: (Quiet) Prevents UNFUNCTION from displaying an error message if one or more of the functions does not exist. This option is most useful in batch files, for removing a group of variable functions when some of them may not have been defined. /R: (Read) Read the list of function names to remove from a file. The file format should be the same format as that used by the 696FUNCTION /R command. You can use multiple files with one UNFUNCTION /R command by placing the names on the command line, separated by spaces: !INDENT 5 5 5 5 c:\> unfunction /r func1.lst func2.lst !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 680 UNSET !TTY Purpose: Remove variables from the environment. Format: UNSET [/M /Q /R file...] name... or UNSET * name: One or more variables to remove from the environment. file: One or more files containing variable definitions. /M(aster environment) /R(ead from file) /Q(uiet) !TTY See also: 622ESET and 663SET. Usage UNSET removes one or more variables from the environment. UNSET supports wildcards in the variable name, and you can remove one or more variables by name. You can delete all environment variables with the command UNSET *. For example, to remove the environment variable CMDLINE: c:\> unset cmdline To remove all of the environment variables: c:\> unset * To remove all the variables that begin with "P": [c:\] unalias P* UNSET can be used in a batch file, in conjunction with the 665SETLOCAL and 621ENDLOCAL commands, to clear the environment of variables that may cause problems for applications run from that batch file. For more information on environment variables, see the 663SET command and the general discussion of the 131environment. Use caution when removing environment variables, and especially when using UNSET *. Many programs will not work properly without certain environment variables; for example, 4DOS itself depends on 138PATH and 134COMSPEC. Options !INDENT 5 5 0 5 /M: (Master) Remove the variable from the master environment rather than the local environment. This option is only useful in secondary shells. /Q: (Quiet) Prevents UNSET from displaying an error message if one or more of the variables does not exist. This option is most useful in batch files, for removing a group of variables when some of the variables may not have been defined. /R: (Read) Read environment variables to UNSET from a file. This is much faster than using multiple UNSET commands in a batch file, and can be more selective than UNSET *. The file format should be the same format as that used by the 663SET /R command. If there is no filename argument and input is redirected, UNSET /R will read from stdin. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 681 VER !TTY Purpose: Displays the vDosPlus and emulated DOS version. Format: VER !TTY Usage The vDosPlus version is its release and build dates in yyyy.mm.dd. For example: ver vDosPlus 2016.10.01 (build 2017.03.15), reported DOS version: 7.10 ;--------------------------------------------------------------------------- !TOPIC 682 VERIFY !TTY Purpose: Enable or disable disk write verification or display the verification state. Format: VERIFY [ON | OFF] !TTY Usage If used without parameters, VERIFY will display the state of the verify flag: verify VERIFY is OFF This command/flag has no effect in vDosPlus! ;--------------------------------------------------------------------------- !TOPIC 683 VOL !TTY Purpose: Display disk volume label(s). Format: VOL [d:] ... d: The drive or drives to search for labels. !TTY Usage Each disk may have a volume label, created when the disk is formatted or with the LABEL command. Also, every floppy disk formatted with DOS version 4.0 or above, OS/2, or the 25Windows NT line has a volume serial number. The VOL command will display the volume label and, if available, the volume serial number of a disk volume. If the disk doesn't have a volume label, VOL will report that it is "unlabeled." If you don't specify a drive, VOL displays information about the current drive: c:\> vol Volume in drive C: is MYHARDDISK If available, the volume serial number will appear after the drive label or name. To display the disk labels for drives A and B: c:\> vol a: b: Volume in drive A: is unlabeled Volume in drive B: is BACKUP_2 ;--------------------------------------------------------------------------- !TOPIC 684 VSCRPUT !TTY Purpose: Display text vertically in the specified color. Format: VSCRPUT row col [BRIght] [BLInk] fg ON [BRIght] bg text row: Starting row number. col: Starting column number. fg: Foreground text color. bg: Background text color. text: The text to display. !TTY See also: 661SCRPUT. Usage VSCRPUT writes text vertically on the screen rather than horizontally. Like the SCRPUT command, it uses the colors you specify to write the text. VSCRPUT can be used for simple graphs and charts generated by batch files. See 892Colors and Color Names for details about colors and notes on the use of bright background colors. The row and column are zero-based, so on a standard 25 line by 80 column display, valid rows are 0 - 24 and valid columns are 0 - 79. VSCRPUT checks for a valid row and column, and displays a "Usage" error message if either value is out of range. You can also specify the row and column as offsets from the current cursor position. Begin the value with a plus sign [+] to move down the specified number of rows or to the right the specified number of columns before displaying text, or with a minus sign [-] to move up or to the left. If you specify 999 for the row, VSCRPUT will center the text vertically on the display. If you specify 999 for the column, VSCRPUT will center the text horizontally. VSCRPUT normally does not move the cursor when it displays the text. However, if you have set 572OutputBIOS to Yes in 4DOS.INI, VSCRPUT will leave the cursor at the end of the displayed text. The following batch file fragment displays an X and Y axis and labels them: cls bright white on blue drawhline 20 10 40 1 bright white on blue drawvline 2 10 19 1 bright white on blue scrput 21 20 bright red on blue X axis vscrput 8 9 bright red on blue Y axis VSCRPUT normally writes text directly to the screen. If you have an unusual display adapter which does not support direct video output, see the 572OutputBIOS directive. ;--------------------------------------------------------------------------- !TOPIC 685 WHICH !TTY Purpose: Display the command type and what it would execute. Format: WHICH command ... command: One or more commands or filenames to query. !TTY Usage WHICH displays information about internal and external commands, aliases, files, and executable extensions. The information it reports depends on the type of command or file you specify. For example: [c:\] which cdd buildtree test.btm test.exe donothing CDD is an internal command buildtree is an alias : cdd /s test.btm is a batch file : C:\test.btm test.exe is an external : C:\test.exe donothing is an unknown command If a filename includes white space or special characters, it must be enclosed in double quotes. If the command is an abbreviated alias, WHICH will display the full name. ;--------------------------------------------------------------------------- !TOPIC 686 Y !TTY Purpose: Copy standard input to standard output, and then copy the specified file(s) to standard output. Format: Y file ... file: The file or list of files to send to standard output. !TTY See also: 670TEE, 052piping and 051redirection. Usage The Y command copies input from standard input (usually the keyboard) to standard output (usually the screen). Once the input ends, the named files are appended to standard output. For example, to get text from standard input, append the files MEMO1 and MEMO2 to it, and send the output to MEMOS: c:\> y memo1 memo2 > memos The Y command is most useful if you want to add redirected data to the beginning of a file instead of appending it to the end. For example, this command copies the output of DIR, followed by the contents of the file DIREND, to the file DIRALL: c:\> dir | y dirend > dirall If you are typing at the keyboard to produce input text for Y, you must enter a Ctrl-Z to terminate the input. ;--------------------------------------------------------------------------- ; Command equates ---------------------------------------------------------- !TOPIC 688 =601 CHDIR !TOPIC 691 =609 ERASE !TOPIC 692 =639 LOADHIGH !TOPIC 693 =644 MKDIR !TOPIC 694 =655 RMDIR !TOPIC 695 =658 RENAME !TOPIC 700 =669 Case: SWITCH keyword !NOINDEX !TOPIC 701 =669 Default: SWITCH keyword !NOINDEX !TOPIC 702 =669 Endswitch: SWITCH keyword !NOINDEX !TOPIC 705 =703 KSTACK.COM !NOINDEX !TOPIC 706 =704 BATCOMP.EXE !NOINDEX !TOPIC 707 =615 Iterate: DO keyword !NOINDEX !TOPIC 708 =615 Leave: DO keyword !NOINDEX !TOPIC 709 =615 Enddo: DO keyword !NOINDEX !TOPIC 710 =634 Else: IFF keyword !NOINDEX !TOPIC 711 =634 Elseiff: IFF keyword !NOINDEX !TOPIC 712 =634 Endiff: IFF keyword !NOINDEX !TOPIC 713 =671 Endtext: TEXT keyword !NOINDEX ;--------------------------------------------------------------------------- !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 719 Error Messages !NOINDEX This section lists error messages generated by 4DOS, and includes a recommended course of action where appropriate. Error messages relating to files are generally reports of 218errors returned by DOS. You may find some of these messages (for example, "Access denied") vague enough that they are not always helpful. 4DOS includes the file name in file error messages, but is often unable to determine a more accurate explanation of these errors. The message shown is the best information available based on the error codes returned by DOS. For some errors you are instructed to "restart the session or reboot the system." This means that you should attempt to correct the error by closing and restarting the current vDosPlus session. The following list includes all error messages, in alphabetical order: !INDENT 5 0 5 0 4DOS.HLP file is out of date, please update it: Your copy of 4DOS.HLP appears to be one from an earlier version of 4DOS. Check the date and time on 4DOS.HLP. Also check the 384InstallPath setting (if any) in 4DOS.INI, it may point to an old directory. 4DOS internal stack overflow: You attempted to nest batch files or commands like 615DO, 623EXCEPT, 626FOR, 633IF, 634IFF, 628GLOBAL, or 662SELECT too deep, and 4DOS ran out of stack space. Restructure your command, alias, or batch file, or use the 648OPTION command or the 574StackSize directive in 4DOS.INI to increase the internal stack size. 4DOS initialization error --: An error occurred during the 4DOS startup process. Look up the rest of the message in this list for a more specific explanation. 4DOS server error --: An error occurred in communication between 4DOS's resident and transient portions. A more specific error message follows (the additional error message can be looked up in this list). 4DOS swapping failed, loading in non-swapping mode: None of the swapping options worked, so 4DOS loaded in non-swapping mode, which requires about 245K more memory than swapping mode. Check your Swapping specification with the 648OPTION command or in 4DOS.INI, and/or free some EMS memory or disk space. 4DOS unrecoverable error XX: An error occurred in the resident portion of 4DOS. These errors will terminate secondary shells and, and may require you to restart the vDosPlus session if they occur during a primary shell or if 4DOS cannot continue. The error codes are: BI Bad function code. DI Same as Disk swap file corrupted. DR Same as Swap file read error. DS Same as Swap file seek error. EI Same as EMS mapping error. NS No number for new shell. You have started too many 4DOS secondary shells without properly exiting some of them, perhaps by closing DESQview windows rather than EXITing. Clean up any work in process and restart the vDosPlus session. PT Illegal process termination. TS Terminated inactive shell. XI Same as XMS move failed. Access denied: You tried to write to or erase a read-only file, rename a file or directory to an existing name, create a directory that already exists, remove a read-only directory or a directory with files or subdirectories still in it, or access a file in use by another program in a multitasking system. Alias loop: An alias refers back to itself either directly or indirectly (i.e., a = b = a), or aliases are nested more than 16 levels deep. Correct your alias list. Already excluded files: You used more than one exclude range in a command. Combine the exclusions into a single range. Attempt to exit from root shell: Another program has probably destroyed a portion of 4DOS's memory. Restart the vDosPlus session. AUTOEXEC parameters too long, discarded: The full pathname and parameter list for AUTOEXEC.BAT was over 254 characters. This is usually due to data in the 375AutoExecPath and/or 374AutoExecParms directive in 4DOS.INI. Reduce the amount of data and restart the vDosPlus session. Bad environment: The DOS environment has a bad structure, probably because a program destroyed 4DOS's master environment space. Restart the vDosPlus session. Batch file missing: 4DOS can't find the batch (.BAT) file it was running. It was either deleted, renamed, moved, or the disk was changed. Correct the problem and rerun the file. Can't copy file to itself: You cannot COPY or MOVE a file to itself. 4DOS attempts to perform full path and filename expansion before copying to help ensure that files aren't inadvertently destroyed. Can't create: 4DOS can't create the specified file. The disk may be full or write protected, or the file already exists and is read-only, or the root directory is full. Can't delete: 4DOS can't delete the specified file or directory. The disk is probably write protected. Can't get directory: 4DOS can't read the directory. The disk drive is probably not ready. Can't make directory entry: 4DOS can't create the filename in the directory. This is usually caused by a full root directory. Create a subdirectory and move some of the files to it. Can't open: 4DOS can't open the specified file. Either the file doesn't exist or the disk directory or File Allocation Table is damaged. Can't remove current directory: You attempted to remove the current directory, which DOS does not allow. Change to the parent directory and try again. Can't set up disk swap file: The disk swap file you specified cannot be opened. The path or drive is invalid, the disk is full, DOS is out of file handles, or there is a hardware problem. Use the 648OPTION command or check 4DOS.INI to be sure your 391Swapping directive is correct. Clipboard is empty or not text format: You tried to retrieve some text from the Windows clipboard, but there is no text available. Correct the contents of the clipboard and try again. Clipboard is in use by another program: 4DOS could not access the Windows clipboard because another program was using it. Wait until the clipboard is available, or complete any pending action in the other program, then try again. Command line too long: A single command exceeded 511 characters, or the entire command line exceeded 511 characters during alias and variable expansion. Reduce the complexity of the command or use a batch file. Also check for an alias which refers back to itself either directly or indirectly. Command only valid in batch file: You have tried to use a batch file command, like DO or GOSUB, from the command line or in an alias. A few commands can only be used in batch files (see the individual commands for details). Command tail too long, truncated: A program attempted to pass a command in an improper format or a command longer than 126 characters to a 4DOS secondary shell. This is probably a bug in the program from which 4DOS was loaded. Contact the author of the program for technical assistance. Contents lost before copy: COPY was appending files, and found one of the source files is the same as the destination. That source file is skipped, and appending continues with the next file. Data error: DOS can't read or write properly to the device. This error may indicate a hardware problem. Retry the operation; if it fails again, correct the hardware problem. Data segment too large, truncating alias / history lists: The total amount of space required for aliases, history, directory history, and the 4DOS stack exceeded the space available. Reduce the values of the corresponding directives in 4DOS.INI and then Restart the vDosPlus session. Device not ready: The specified device can't be accessed. Directory stack empty: POPD or DIRS can't find any entries in the directory stack. Disk swap file corrupted: The 4DOS disk swapping file (4DOSSWAP.nnn or xxxxxxxx.4SW) has been moved, deleted, or damaged by another program. Restart the vDosPlus session. Divide by zero: The command or function you used tried to do a division by zero. Rearrange the expression, or pre-validate the input numbers, to prevent the zero in the divisor. Duplicate redirection: You tried to redirect standard input, standard output, or stand error more than once in the same command. EMS deallocation failed: 4DOS can't deallocate EMS memory when exiting from a secondary shell. The EMS map has been corrupted or the memory area used by 4DOS has been destroyed by a program. Clean up any work in process and restart the vDosPlus session. EMS mapping failed: 4DOS can't map EMS pages when swapping to or from EMS. The EMS map has been corrupted or the memory area used by the loader has been destroyed by a program. Restart the vDosPlus session. Encrypted batch files require the runtime version: Encrypted batch files cannot be run under the regular command line version of 4DOS, the runtime version is required. Run the file under the runtime product, or obtain an unencrypted version from the author. Environment already saved: You have already saved the environment with a previous 665SETLOCAL command. You cannot nest SETLOCAL / ENDLOCAL pairs. Error in command-line directive: You used the //iniline option to place a 4DOS.INI directive on the secondary shell command line, but the directive is in error. Usually, a more specific error message follows, and can be looked up in this list. Error on line [nnnn] of [filename]: There is an error in 3514DOS.INI. The following message explains the error in more detail. Correct the line in error and restart the vDosPlus session for your change to take effect. Error reading: DOS experienced an I/O error when reading from a device. This is usually caused by a bad disk, a device not ready, or a hardware error. Error writing: DOS experienced an I/O error when writing to a device. This is usually caused by a full disk, a bad disk, a device not ready, or a hardware error. Exceeded batch nesting limit: You have attempted to nest batch files more than 10 levels deep. Fatal error -- reboot the system or restart the session: 4DOS cannot continue due to the previous error. Restart the vDosPlus session. Fatal error, some directives may not have been processed: An I/O error occurred while reading your 4DOS.INI file. There may be a physical problem with data on the disk or a sharing error on a multitasking system. Check your 4DOS.INI file and try again. File exists: The requested output file already exists, and 4DOS won't overwrite it. File is empty: You attempted to use an empty file in 318@SELECT. Correct the file name or contents and try again. File not found: 4DOS couldn't find the specified file. Check the spelling and path name. General failure: This is usually a hardware problem, particularly a disk drive failure or a device not properly connected to a serial or parallel port. Try to correct the problem, restart and try again. Also see Data error above. I/O error in [filename], some directives may not have been processed: An I/O error occurred while reading 3514DOS.INI. There may be a physical problem with data on the disk or a sharing error on a multitasking system. Check your 4DOS.INI file and try again. IDLE is disabled: The BatteryMAX ($IDLE$) device driver has not been installed. Include file not found: You used the Include directive in the 4DOS.INI file, but the file you specified was not found or could not be opened. Include files nested too deep: You used the Include directive in the 4DOS.INI file, and attempted to nest include files more than three levels deep. Infinite COPY or MOVE loop: You tried to 606COPY or 646MOVE a directory to one of its own subdirectories and used the /S switch, so the command would run forever. Correct the command and try again. Insufficient disk space: 606COPY or 646MOVE ran out of room on the destination drive. Remove some files and retry the operation. Insufficient load space: There is not enough room in 4DOS's internal memory areas to include all of the options you requested in 3514DOS.INI. Internal DOS error: DOS encountered an internal bug and failed. Restart the vDosPlus session. Invalid AUTOEXEC filename: You specified an invalid path or filename for the AUTOEXEC file with the /P: startup switch. The default name will be used instead. Correct the filename, then restart the vDosPlus session. Invalid batch file: The batch file is corrupted or improperly 115compressed or encrypted. Retry with a new copy of the file. Invalid character value: You gave an invalid value for a character directive in 3514DOS.INI. Invalid choice value: You gave an invalid value for a "choice" directive (one that accepts a choice from a list, like "Yes" or "No") in 3514DOS.INI. Invalid color: You gave an invalid value for a color directive in 3514DOS.INI. Invalid count: The character repeat count for 638KEYSTACK is incorrect. Invalid date: An invalid date was entered. Check the syntax and reenter. Invalid directive name: 4DOS can't recognize the name of a directive in 3514DOS.INI. Invalid drive: A bad or non-existent disk drive was specified. Invalid .INI file path or name, file not processed: The path or name for the initialization file is invalid. Correct the @d:\path\inifile option to name the correct file. Invalid key name: You tried to make an invalid 481key substitution in 4DOS.INI, or you used an invalid key name in a keystroke 595alias or command. Correct the error and retry the operation. Invalid numeric value: You gave an invalid value for a numeric directive in 3514DOS.INI. Invalid parameter: 4DOS didn't recognize a parameter. Check the syntax and spelling of the command you entered. Invalid path: The specified path does not exist. Check the disk specification and/or spelling. Invalid path or file name: You used an invalid path or filename in a directive in 3514DOS.INI. Invalid startup switch, ignored: You passed 4DOS an invalid option. Correct the switch. Invalid Swapping option or path: The swap type or disk swap path in the 4DOS.INI 391Swapping directive is invalid. 4DOS ignores the bad swap type or path and attempts to scan the rest of the Swapping specification for a valid option. Multiple errors in the Swapping directive will cause this message to repeat. Use the 648OPTION command or an editor to check the Swapping setting in 4DOS.INI, then restart vDosPlus. Invalid time: An invalid time was entered. Check the syntax and reenter. Invalid unit: Generally caused by a disk drive hardware failure. Keystroke substitution table full: 4DOS ran out of room to store 481keystroke substitutions entered in 4DOS.INI. Reduce the number of key substitutions. KSTACK.COM not loaded: You attempted to execute a 638KEYSTACK command without loading KSTACK.COM. See the KEYSTACK command for more information. Label not found: A GOTO or GOSUB referred to a non-existent label. Check your batch file. Memory [allocation | deallocation] error: 4DOS can't allocate or deallocate memory while loading, or while reserving or releasing memory for internal use. DOS memory allocation has been corrupted, or another application has reserved memory incorrectly. Restart the vDosPlus session. Memory destroyed: The DOS memory control blocks have been corrupted. Restart the vDosPlus session. Missing ENDTEXT: A 671TEXT command is missing a matching ENDTEXT. Check the batch file. Missing GOSUB: 4DOS cannot perform the 659RETURN command in a batch file. You tried to do a RETURN without a 629GOSUB, or your batch file has been corrupted. Missing SETLOCAL: An ENDLOCAL was used without a matching SETLOCAL. No aliases defined: You tried to display aliases but no aliases have been defined. No closing quote: 4DOS couldn't find a second matching back-quote [`] or double-quote ["] on the command line. No expression: The expression passed to the %@EVAL variable function is empty. Correct the expression and retry the operation. No file handle available: This is an internal 4DOS disk swapping error. Change to another swapping method if possible. No room for .INI file name: 4DOS does not have enough space to pass the name of 3514DOS.INI to secondary shells; see String area overflow for more details. Any [Secondary] section in 4DOS.INI will be ignored in secondary shells until the problem is corrected and the system or session is restarted. No UMBs; loading low: The 639LOADHIGH (or LH) command can't find any UMBs for your program. The program is loaded into base memory. LH and LOADHIGH only work when sufficient upper memory space is available for the program. No upper memory available, low memory will be used for [resident portion | master environment | global aliases | global history | global directory history]: You asked 4DOS to load the block of memory named in the message into a UMB via the corresponding directive in 4DOS.INI (398UMBLoad, 395UMBEnvironment, 393UMBAlias, or 397UMBHistory), but no UMB was available. Free up some UMB space in use by another program. Not a directory: The name passed to 655RD is not a directory. Not an alias: The specified alias is not in the alias list. Not in environment: The specified variable is not in the environment. Not in swapping mode: You attempted to turn swapping on or off with the 668SWAPPING command, but 4DOS is loaded in non-swapping mode. Not same device: This error usually appears in RENAME. You cannot rename a file to a different disk drive. Out of environment/alias space: 4DOS has run out of space for environment variables or aliases. Edit the 377Environment directive in 4DOS.INI to increase the environment size, or the 373Alias directive in 4DOS.INI to increase the alias list size. Out of memory: 4DOS or DOS had insufficient memory to execute the last command, or the memory control blocks have been destroyed. If this error occurs in a 4DOS secondary shell, return to the primary shell before running the command. Otherwise, try to free some memory by removing memory-resident programs. If the base memory (DOS RAM) figures reported by MEMORY are unreasonable, the memory control blocks have probably been destroyed and you must restart the vDosPlus session. If you receive this error from DIR when MEMORY shows sufficient memory for the directory you are displaying, memory has probably been "fragmented," and contains a free area larger than 12K but not large enough for the entire directory. Use a memory mapping program like PMAP, MAPMEM, or the DOS MEM utility to locate the fragmentation, and experiment with your TSRs and applications to determine and remove its cause. Overflow: An arithmetic overflow occurred in the 263@EVAL variable function. Check the values being passed to @EVAL. @EVAL can handle 20 digits to the left of the decimal point and 10 to the right. Primary shell uses disk swapping, settings will not be inherited: This informational message tells you that primary shell options, aliases, etc. will not be passed on to secondary shells. See the 391Swapping directive in 4DOS.INI for additional information. Printer out of paper error: DOS detected an out-of-paper condition on one of the printers. Check your printer and add paper if necessary. Read fault error: DOS encountered a disk read error; usually caused by a bad or unformatted disk. Also see Data error above. Region unavailable, using first available region for [resident portion | master environment | global aliases | global history | global directory history]: You used a 3514DOS.INI directive to load the block of memory named in the message into a specific UMB region, but that region was unavailable. Check the use of upper memory for device drivers and other programs loaded before 4DOS, and/or change the requested region number. Seek error: DOS can't seek to the proper location on the disk. This is generally caused by a bad disk or drive. Also see Data error above. Sharing violation: You tried to access a file in use by another program. Wait for the file to become available, or change your method of operation so that another program does not have the file open while you are trying to use it. Specified .INI file not found: The file specified with the @inifile option on the 4DOS command line does not exist. String area overflow: 4DOS ran out of room to store the text from string directives in 3514DOS.INI. Reduce the complexity of 4DOS.INI. Swap file [seek | read | write] failed: 4DOS encountered an I/O error while accessing the disk swap file (4DOSSWAP.nnn or xxxxxxx.4SW). The disk was changed, the file has been destroyed by a program, or 4DOS's memory area has been overwritten by another program. Restart the vDosPlus session. Syntax error: A command or 241variable function was entered in an improper format. Check the syntax and correct the error. Syntax error in region number or size: You specified an invalid region number or size in the 639LH / LOADHIGH command. Correct the command. Too many open files: vDosPlus has run out of file handles. Unbalanced parentheses: The number of left and right parentheses did not match in an expression passed to the @EVAL variable function. Correct the expression and retry the operation. Unknown command: A command was entered that 4DOS didn't recognize and couldn't find in the current search path. Check the spelling or 138PATH specification. You can handle unknown commands with the UNKNOWN_CMD alias (see 595ALIAS). UNKNOWN_CMD loop: The UNKNOWN_CMD alias (see 595ALIAS) called itself more than ten times. The alias probably contains an unknown command itself, and is stuck in an infinite loop. Correct the alias. Variable loop: A nested environment variable refers to itself, or variables are nested more than 16 deep. Correct the error and retry the command. Write fault error: DOS encountered a disk write error; usually caused by a bad or unformatted disk. Also see Data error above. Write protect error: The disk cannot be written to. Check the disk and remove the write-protect tab or close the write-protect window if necessary. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 720 Troubleshooting !NOINDEX These topics may help you to solve problems you are having with 4DOS: 751Compatibility 752Troubleshooting Compatibility Problems 112Debugging Batch Files Note that support is not offered for this 731free release of 4DOS. ;--------------------------------------------------------------------------- !TOPIC 731 Unsupported Free Version !NOINDEX JP Software does not offer technical support for this free version of 4DOS. The best place to look for help where other 4DOS users can respond, is: https://groups.google.com/forum/#!forum/comp.os.msdos.4dos, The section on 720troubleshooting may help you resolve compatibility and batch file issues on your own. ;--------------------------------------------------------------------------- !TOPIC 732 Contacting JP Software !NOINDEX Website of JP Software: https://jpsoft.com. Note that technical support is not provided for this 731free release of 4DOS. ;--------------------------------------------------------------------------- !TOPIC 751 Compatibility !NOINDEX This section provides information on using 4DOS with other software products. It is intended for use whenever you have a question about using another product with 4DOS, or suspect a compatibility problem. 761DOS 841Other Products The following general comments apply to all of the compatibility information included in this help system. If you are having trouble with any other product you should review the information here, and also check the discussion of 752Troubleshooting Compatibility Problems for diagnostic techniques that may apply to your situation. Virtually all of your software will work with 4DOS with no trouble. Inclusion of a product here does NOT mean there are compatibility problems with it! It only indicates that we have some information that may be useful to you when you use the product with 4DOS. We have made every effort to ensure that our compatibility information is as accurate and up to date as possible. Our information is based on our own investigations, reports from 4DOS beta testers, technical support calls, discussions with manufacturers of other products, and reports from our customers. Unfortunately, varying conditions between systems or between software releases can easily invalidate the results of previous tests. Therefore we cannot guarantee that every item included here is accurate for all systems or will remain accurate over time; you may have to do your own testing to determine what works well on your system with the software you own. ;--------------------------------------------------------------------------- !TOPIC 752 Troubleshooting Compatibility Problems !NOINDEX As publishers of a product that replaces part of the operating system, we're very familiar with these issues -- not because 4DOS is more likely to cause problems, but because it sometimes gets blamed first when a problem appears. Our technical support department has developed a set of reliable techniques for finding out what's causing an apparent compatibility problem with 4DOS and other software. We are presenting these techniques here as a series of things to try when there seems to be a compatibility problem. Some may not make sense for the particular problem you're investigating. Others may not yield useful results. But as a group, they'll help you resolve many of the common software interactions that do appear, whether with 4DOS or anything else. Before you get started, be sure to check 751Compatibility to see if we've already solved the problem you're facing. Some of our suggestions help you figure out what's going on, but aren't intended to help you fix it. For example, when we suggest that you remove all your TSRs to look for the problem, we aren't suggesting that as a permanent solution, but only as a diagnostic test. The first thing to consider is whether the particular combination of software that's not working used to work together. If so, think carefully about what you have changed and see if reversing the change solves the problem. If it does, then you can narrow your search, using the following techniques to find out what it is about that specific change that is causing the problem. Second, make sure that your problem can be reproduced relatively easily, and make sure you know exactly what sequence of commands or other steps reproduces it. Most interactions are very easy to reproduce, but if you think there's an interaction and it occurs once every 10 days, it's going to be difficult to know when you have fixed it. Also, the process of carefully documenting how to reproduce a problem often helps you realize what the problem is without further effort. If you have a problem with a specific application hanging or working improperly, and the above techniques don't help, then try reducing your system configuration to the simplest possible level. This is the single most useful tool we know for finding compatibility problems. To do so, use all of the approaches listed below, and any other similar things you may be able to think of about your particular system after reading our suggestions. When you're modifying 3514DOS.INI in an attempt to resolve problems, you may find the 383INIQuery directive useful. If you set INIQuery to Yes for a section of 4DOS.INI, then 4DOS will prompt you for each line in that section. This allows you to test the effects of changing directives in the .INI file without actually modifying the file for each test. The troubleshooting approaches are divided into the categories: !NOWRAP 753Path Length 754Environment Size 755Testing for Interactions 756Memory Allocation Conflicts 758Advanced Configuration Options !WRAP ;--------------------------------------------------------------------------- !TOPIC 753 Path Length !NOINDEX The first thing to do is to check the length of your 138PATH variable. 4DOS lets you make it longer than the traditional limit of 123 characters. Some programs can't handle long PATHs and may behave strangely. If your PATH is over the traditional limit, reduce its size using the 649PATH, 622ESET, or 663SET command and see if the application starts working. If so, use a batch file or alias to set up an alternate path for running that one program, for example: setlocal path d:\myprog d:\myprog\myprog.exe endlocal The 665SETLOCAL / 621ENDLOCAL pair saves and restores the environment; when you're done, the old PATH will be restored automatically. ;--------------------------------------------------------------------------- !TOPIC 754 Environment Size !NOINDEX Next, check how much environment space is in use in your system. The 4DOS 645MEMORY command reports the total environment space and the amount free; a simple subtraction tells you how much is in use. Some programs simply don't work right if there's a lot of information in the environment (these programs don't usually care how big the total environment space is, only how much of it is actually in use). In most cases, these problems show up when the amount of space in use gets up to around 1K (1024) bytes or so, but they can occur at any point. To test for this, use the following simple batch file: setlocal unset var1 var2 var3 ... [command to run the program in question] endlocal where VAR1, VAR2, etc. are variables you can remove from the environment to decrease the space in use before running the program. ;--------------------------------------------------------------------------- !TOPIC 755 Testing for Interactions !NOINDEX To look for a multi-program interaction, you'll need to remove all TSRs you possibly can and still have enough software present to demonstrate the problem. Once you know what you can take out, don't skimp or guess where the interaction might be. Take out everything you possibly can from 4START and AUTOEXEC.TXT that loads or accesses another program. Remove all the lines you can that load memory-resident programs (and remember that some DOS utilities can be memory-resident). Of course, you should save copies of your configuration files before you delete anything. Better yet, use the REM command to remove lines temporarily without deleting them. REM can be used on any line in AUTOEXEC.TXT, in 4START, and in CONFIG.TXT. If you want to remove everything in AUTOEXEC.TXT you can rename it to another name (say AUOTEXEC.SAV), and rename it back when you are done testing. If the problem isn't there under Window 32-bit (NTVDM), try fiddling with the program's configuration. If you were loading it high, try loading it low. If you can change the way it uses memory, try doing so. All of these techniques will help you narrow down what it is about the program that's causing a problem. Once you have done that, you may have a simple workaround. Some problems can be resolved by modifying the order in which you load TSRs. If you've found a problem with a particular TSR, if possible try loading it earlier or later than you were and see if the problem goes away. ;--------------------------------------------------------------------------- !TOPIC 756 Memory Allocation Conflicts !NOINDEX A memory allocation conflict is very simple. It occurs when two (or more) programs try to use the same memory, or when a program behaves differently depending on where it is loaded in memory. Inevitably, at least one of the programs will operate incorrectly, report an error, or hang. These conflicts can be very hard to diagnose, because it's difficult to determine which programs are actually causing the conflict, and the symptoms may appear to be totally unrelated to the program responsible for the problem. 4DOS uses memory in a more complex way than COMMAND.COM. It can use base, XMS, or EMS memory, and store portions of itself and its data in UMBs (see 896How 4DOS Uses Memory for additional details). COMMAND.COM does not offer any of these capabilities. This added complexity makes it more likely that you'll encounter memory allocation conflicts with 4DOS. This isn't because 4DOS is less reliable than other programs, it's because the memory allocation conflict was there waiting to happen, and 4DOS triggered it through its access to additional memory. It's easy to check whether 4DOS's use of memory is a problem. If you configure 4DOS so that it swaps to disk, and disable all use of UMBs, then 4DOS uses only base memory, and (in terms of memory allocation) operates very much like COMMAND.COM. You can make this change in two simple steps. First, add a line containing the following 391Swapping directive to 4DOS.INI: Swapping = c:\ (change this if you prefer to swap to a different drive. Second, remove any lines in 4DOS.INI which allocate UMBs (398UMBLoad, 395UMBEnvironment, 393UMBAlias, 396UMBFunction, and 397UMBHistory), or place a semicolon at the start of such lines to temporarily turn them into comments. If these steps solve the problem, you've found a memory allocation conflict. The next thing to do is remove all the TSRs you can to see if you can determine where the conflict is. ;--------------------------------------------------------------------------- !TOPIC 758 Advanced Configuration Options !NOINDEX If none of the other techniques have proven useful, some of the advanced directives in 4DOS.INI may help solve very rare configuration problems. However, unless you are an experienced DOS user and understand the side effects of each directive, they should be used only as diagnostic tools and not as a workaround or fix. Any of the following can be tried for the conditions indicated: !INDENT 5 5 5 5 568Inherit = No or 556Reduce = No: If you have unexplained problems in starting secondary shells. 436LineInput = Yes (or 664SETDOS /L1): If you have memory-resident programs which do not recognize that you are at the prompt (see also 844Other Command Line Editors.) 575SwapReopen = Yes: If an application generates reproducible errors related to the 4DOS swap file (for example "Swap file seek failed" or similar errors). ; 555 MaxLoadAddress ; 557ReserveTPA Control shell memory allocation !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 761 DOS !NOINDEX This section covers compatibility questions that may arise when running 4DOS with vDosPlus, including external DOS programs. Most information here covers unusual situations and will not be needed by most users. For information on other DOS-related topics, see: 763Executing DOS Commands from Applications 135COPYCMD Variable 136DIRCMD Variable 16DOS HELP Command 770DOS MOVE Command 116REXX Support 771DOS SELECT Command ;--------------------------------------------------------------------------- !TOPIC 763 Executing DOS Commands from Applications !NOINDEX In general you should have no trouble running DOS commands or "shelling to DOS" from within your applications. If you do, first check your 134COMSPEC setting, and check that enough memory is available for 4DOS to execute as a secondary shell. This should resolve most problems with "shell to DOS" operations. If those techniques do not resolve the problem, it may be due to one of the issues covered below: either the application was developed with a compiler that does not handle the format of 4DOS.COM properly, or it is using interrupt 2E and you have disabled interrupt 2E support. Compilers and the Format of 4DOS.COM If you have an application which can run DOS commands from inside the application and that particular feature does not work, try to determine if the application was developed with Borland C or Lattice C. Some older versions of these compilers cannot properly execute 4DOS.COM to start a secondary shell, because 4DOS.COM (despite its name) is formatted as an EXE file, and the libraries shipped with these compilers do not use the proper method to determine what type of file they are. Re-Enabling Interrupt 2E Support COMMAND.COM contains an undocumented feature which allows programs to execute DOS commands by passing the command through software interrupt number 2E (hex). Not many programs use this feature, but full, 798documented support for it is available within 4DOS for those circumstances where it's needed. Interrupt 2E support is normally enabled within 4DOS, but can be disabled to save memory (INT 2E support requires about 100 bytes of resident memory). If you have a program which is supposed to execute DOS commands and it does not work under 4DOS, check your 4DOS.INI file. If you see a line like this: 566FullINT2E = No then you have disabled INT 2E support. If the line is there, try removing this line or replacing it with one reading: FullINT2E = Yes to re-enable support for interrupt 2E, then restart the vDosPlus session and test whether your program works properly. ;--------------------------------------------------------------------------- !TOPIC 770 DOS MOVE Command !NOINDEX DR DOS 6.0 and above as well as MS-DOS 6.0 or PC DOS 6.1 and above all include an external MOVE command which is generally compatible with the 4DOS 646MOVE command. The syntax and features of the DOS MOVE command are slightly different than those offered by 4DOS's MOVE, so batch files written for one command may not work exactly the same way with the other, especially if more advanced or complex features are used. If you write batch files which use both commands, check the 4DOS and 65535external DOS documentation for your particular usage. ;--------------------------------------------------------------------------- !TOPIC 771 DOS SELECT Command !NOINDEX In MS-DOS / PC DOS 4.01 and below, a SELECT command was included. This external command is totally unrelated to the 4DOS internal SELECT command. If you need to use both, you can set up aliases to adjust how the command names are handled. For example, the following two aliases set up SELECT to access the DOS 4.0 external SELECT command (assumed to be stored in C:\DOS\SELECT.EXE), and SEL to access the internal 4DOS SELECT command: alias select c:\dos\select.exe alias sel *select ;--------------------------------------------------------------------------- !TOPIC 841 Compatibility (Other Products) !NOINDEX This section includes compatibility information on a range of software product types and individual products. Because some products are listed by type rather than, or (rarely) in addition to, specific listings by product name, you should check the lists below carefully to see where any particular product may be covered. Virtually all of your software will work with 4DOS with no trouble; Most of the information here covers unusual situations and will not be needed by most users. Inclusion of a product in this section does NOT mean there are compatibility problems with it! It only indicates that we have some information that may be useful to you when you use the product with 4DOS. Product Types: 8444DOS and Other Command Line Editors !INDENT 5 5 5 5 The information below is listed alphabetically by product, with manufacturers' names included. Items marked with two asterisks [**] after the product name contain information supplied by users, and have not been tested by JP Software. Many popular software products are not covered here. If a program does not appear here, it simply means that as far as we know no additional information is necessary or useful when using that program with 4DOS. !INDENT 0 8611DIR+ (Bourbaki) [**] 862Bookshelf CD-ROM (Microsoft) [**] 863DESQview (Quarterdeck, now Symantec) 865Epsilon (Lugaru Software) [**] 867FoxPro (Microsoft) [**] 875TSRCOM Utilities (TurboPower Software) 876UltraVision (Personics) ;--------------------------------------------------------------------------- !TOPIC 844 4DOS and Other Command Line Editors !NOINDEX Programs such as Anarkey (Moderne Software), PCED (Cove Software), or ReDOS (Multisoft) will work properly with 4DOS. However these programs require the use of 664SETDOS /L1 to operate, which will disable 4DOS's command recall and command line editing. In most cases you will be able to switch back and forth between 4DOS editing and the other editor by toggling the SETDOS /L state. When another editor is used 4DOS's command history will be maintained, and can be viewed with the 4DOS 632HISTORY command, but will not be available for recall until a SETDOS /L0 is executed. 4DOS aliases, executable extensions, and other features will be active regardless of the SETDOS /L state. 101Aliases will be processed after any processing done by the other editing program. You must use care with other programs that provide an aliasing capability to avoid confusion if a command is expanded by both the other program and 4DOS! ;--------------------------------------------------------------------------- !TOPIC 861 1DIR+ (Bourbaki) !NOINDEX 1DIR+ will work properly under 4DOS in its partially resident or EMS modes when set up as described below. It will work in its fully resident mode but cannot reliably exit back to 4DOS once started. If your copy of 1DIR+ is set up for fully resident mode, you can load it into memory under 4DOS to switch it to partially resident or EMS mode. To do so, from the directory where you normally run 1DIR+, type the commands: setdos /l1 1dirplus When 1DIR+ starts go to the "Wonder" / "Setup" menu and switch the mode to partially resident or EMS. Hit Esc to exit, and take the "Exit/Save" option (not "Save/Reset"). Back at the main menu, exit with "Wonder" / "Exit". At this point the system will probably hang. Restart the vDosPlus session. You should then be able to run 1DIR+ as described below. The above steps only need to be done once, when you install or re-install 1DIR+. Once 1DIR+ is set to EMS or partially-resident mode, you can start it from 4DOS using the following alias: alias 1dir `setdos /L1 ^ 1dirplus` The SETDOS /L1 is necessary to allow 1DIR+ to send command lines to 4DOS. You must do a SETDOS /L0 when you are done with 1DIR+ in order to get normal 4DOS command-line editing back. You can NOT do this within the alias above, as 1DIR+ returns to 4DOS in order to accomplish its work, and you don't want to switch back to /L0 mode until 1DIRPLUS has been removed from memory. If, after exiting from 1DIR+, you find that 4DOS's command line editing and history are unavailable, it is because you forgot to do the SETDOS /L0. If you go in and out of 1DIR+ regularly aliases like the following can be used to make the process quick: alias 1d `setdos /L1 ^ 1dirplus` alias 1e setdos /L0 If you run batch files from the 1DIRPLUS "compose" feature, you may find that INPUT commands in the batch file don't work properly unless they are preceded by SETDOS /L0. You must also do a SETDOS /L1 before the end of the batch file, or 1DIRPLUS won't pop up properly when the batch file is finished. For example: setdos /l0 input Enter your name: %%name setdos /l1 ;--------------------------------------------------------------------------- !TOPIC 862 Bookshelf CD-ROM (Microsoft) !NOINDEX Microsoft Bookshelf uses the environment variable CDPATH, which is also used (for a totally different purpose) by 4DOS. If you are using MS Bookshelf and want to set a 049CDPATH variable for 4DOS, set 144_CDPATH instead. 4DOS will search for _CDPATH first; when it is found, 4DOS will use it, and ignore CDPATH. ;--------------------------------------------------------------------------- !TOPIC 863 DESQview (Quarterdeck, now Symantec) !NOINDEX 4DOS works well as both the primary shell loaded before DESQview, and as the secondary shell loaded inside any DESQview window. To use 4DOS as a secondary shell with DESQview, you must add it to your DESQview "Open Window" menu. To do this, select the Add a Program option, then press the "O" key (for Other Program). Press Enter and you will get an Add a Program window. You'll need to modify settings on the standard first screen, and on the second "advanced options" screen. Set the Program Name to C:\4DOS\4DOS.COM (adjust the drive and path for your own computer). Set the Parameters to whatever 4DOS startup options you want, but do not use /C or /P. For other DESQview parameters, the defaults are workable with the following changes: To run 4DOS in a full-screen window: Writes Text Directly to Screen: Y (screen 1) Virtualize Text / Graphics: N (screen 1) Close on Exit to DOS: Y (screen 2) Uses its Own Colors: Y (screen 2) To run 4DOS in a window smaller than the full screen: Writes Text Directly to Screen: N (screen 1) Virtualize Text / Graphics: Y/T (screen 1) Close on Exit to DOS: Y (screen 2) Uses its Own Colors: Y (screen 2) 4DOS is written to be "DESQview-aware", and will not "bleed through" to other windows when running full-screen commands such as HELP, LIST, or SELECT. You should normally exit a DESQview 4DOS window with the EXIT command, rather than with the Close option on DESQview's main menu. If you do use the Close option while at the 4DOS prompt, 4DOS will be notified of your action and will clean up its resources (for example, the shell number and disk swap file in use in that window). However this notification has a side-effect: it disables the Quit option on the DESQview main menu (this is a feature of DESQview). To disable the notification and reenable the Quit option, you can use a DVCleanup = No directive in 4DOS.INI. If you do so, be sure to exit 4DOS windows with the EXIT command to avoid leaving stray swap files on your disk or inadvertently using up 4DOS shell numbers. Some users report that DESQview uses all upper memory space when it loads, leaving no upper memory available to 4DOS. If you have 398UMBLoad and / or 395UMBEnvironment set to Yes in 4DOS.INI, this will result in a couple of harmless error messages when 4DOS is started under DESQview. To eliminate these messages, place the following lines at the end of 4DOS.INI: [Secondary] UMBLoad = No UMBEnvironment = No DESQview includes the ability to assign "logical drives" to subdirectory paths to make access to commonly used directories easier, or to support older applications that can't handle subdirectories. This is similar to the DOS SUBST command. 4DOS commands like DIR and COPY may not work as you expect on DESQview logical drives, because DESQview does not support certain standard DOS calls which 4DOS uses to determine whether a name you enter is the name of a file or a subdirectory. If you are using specific filenames without wildcards, 4DOS commands will generally work properly on DESQview logical drives. However problems may occur with "implied wildcards" (for example, when 4DOS interprets DIR A* as DIR A*.*), filename completion, and other wildcard file access. We know of no circumstances where these problems would cause a loss of data. However for the sake of safety, when using DESQview logical drives we suggest you use the /N switches on commands like COPY and MOVE to verify the command's operation before files are actually modified. Under 4DOS, the DESQview DOS Services option will not work in its default configuration. To make DOS Services work under 4DOS, you must first create a batch file, DOSSERV.BAT, in your DESQview directory to run DOS Services under COMMAND.COM. (We are assuming that DESQview is in directory C:\DV and COMMAND.COM is in directory C:\; you will need to modify the settings below if your system is configured differently.) The batch file is: set comspec=c:\command.com c:\dv\dosserv c:\command exit Then, make the following changes on the DESQview change a program screen for DOS Services (items marked ** are on the second page of the screen): * Memory Allocation = 128K or greater * Program Name = C:\DV\DOSSERV.BAT (modify from previous value of C:\DV\DOSSERV). ** Close on Exit to DOS = N ** System Memory = 10K or greater ** Allow Close Window = N Once these steps are taken, you should be able to open the DOS Services window normally. However you will not be able to close it with a close window command. Instead, go to the window where DOS Services allows you to compose a DOS command, and type EXIT to close the window. !TOPIC 865 Epsilon (Lugaru Software) !NOINDEX Epsilon can run 4DOS as a concurrent process, and pass commands to 4DOS for execution. In this mode it traps 4DOS's input requests and feeds the keystrokes to 4DOS. However it does not feed backspaces etc. -- only actual characters. This means that editing of input isn't seen by 4DOS. To fix the problem, either run 4DOS as a shell, and not as a concurrent process, or use a SETDOS /L1 for the copy of 4DOS that is run under Epsilon. To use the more flexible SETDOS /L1 approach you must use 4START.BAT (or .BTM) to set up the SETDOS /L1 before running Epsilon. Epsilon sets the environment variable EPSRUNS=Y whenever it starts a secondary shell; you can use this variable to set up 4START to work with Epsilon. Place the following line in 4START to issue the SETDOS /L1 command in a secondary shell started by Epsilon, but ignore it otherwise: if "%epsruns"=="Y" setdos /l1 ;--------------------------------------------------------------------------- !TOPIC 867 FoxPro (Microsoft) !NOINDEX FoxPro works well with 4DOS, but may have trouble if 4DOS or the master environment is loaded high (in a UMB). If you experience compatibility problems between FoxPro and 4DOS, try removing any 395UMBEnvironment = Yes line in 4DOS.INI; if that doesn't help, try removing any 398UMBLoad = Yes line as well. ;--------------------------------------------------------------------------- !TOPIC 875 TSRCOM Utilities (TurboPower Software) !NOINDEX The TSRCOM utilities will work properly with 4DOS as long as you use TSRCOM version 2.6 or later. The current release is version 3.5 or later, and is available on the 4DOS Utility Disk and on many bulletin boards and on-line systems. If you use TSRCOM's MARK and RELEASE to manage your TSRs, 4DOS swapping (as set with the SWAPPING command) must be in the same state when RELEASE is run as it was when MARK (or FMARK) was run. This is a characteristic of the design of MARK and RELEASE (or any other such products), and not a bug. If you do not observe this rule (for example, if you run MARK with SWAPPING OFF in AUTOEXEC and later run RELEASE from the prompt with SWAPPING ON), you may receive unusual error messages or hang your system. The same restriction applies to MARKNET and RELNET. ;--------------------------------------------------------------------------- !TOPIC 876 UltraVision (Personics) !NOINDEX The DE program distributed with UltraVision is written specifically for COMMAND.COM, and cannot be used to set directory colors with 4DOS. Use 4DOS's built-in directory colorization instead. ;--------------------------------------------------------------------------- !TOPIC 891 Miscellaneous Reference Information !NOINDEX For additional reference information see: 892Colors and Color Names 893Keys and Key Names 894Popup Windows 895Executable Files and File Searches 896How 4DOS Uses Memory 915ANSI Commands 798Technical Information for Programmers ;--------------------------------------------------------------------------- !TOPIC 892 Colors and Color Names !NOINDEX You can use color names in several of the directives in the 3514DOS.INI file and in many commands. The general form of a color name is: [BRIght] [BLInk] fg ON [BRIght] bg [BORder bc] where fg is the foreground or text color, bg is the background color, and bc is the border color. The available colors are: Black Blue Green Red Magenta Cyan Yellow White Color names and the words BRIght, BLInk, and BORder may be shortened to the first 3 letters. You can also specify colors by number instead of by name. The numbers are most useful in potentially long .INI file directives like ColorDir, where using color names may take too much space. The following numbers are recognized: 0 - Black 8 - Gray (bright black) 1 - Blue 9 - Bright blue 2 - Green 10 - Bright green 3 - Cyan 11 - Bright cyan 4 - Red 12 - Bright red 5 - Magenta 13 - Bright magenta 6 - Yellow 14 - Bright yellow 7 - White 15 - Bright white Use one number to substitute for the [BRIght] fg portion of the color name, and a second to substitute for the [BRIght] bg portion. For example, instead of bright cyan on blue you could use 11 on 1 to save space in a ColorDir specification. There are several subtleties that complicate the use of colors and color names. In order to understand them, you will need to read through the restrictions described below. These restrictions are due to the design of your PC video hardware, BIOS, and video drivers, and are not inherent in 4DOS. Some of the restrictions are complex, so feel free to skip over those that do not apply to color combinations you use. Color Errors A standard color specification allows sixteen foreground and eight background colors (sixteen if bright backgrounds are enabled, see below). However, most video adapters and monitors do not provide true renditions of certain colors. For example, most users see normal "yellow" as brown, and bright yellow as yellow; many also see normal red as red, and "bright red" as pink. Color errors are often much worse when running in windowed mode (see above), because the graphical environment that created the window may not map the text-mode colors the way you expect. These problems are inherent in the monitor, video adapter, and driver software. They cannot be corrected using 4DOS color specifications. Border Colors Border colors do not work in vDosPlus, and will be ignored. Blinking Text and Bright Background Colors The interactions between blinking characters, bright backgrounds, and your display mode can be complex. You will need to understand them if you use either attribute in your color specifications. ;--------------------------------------------------------------------------- !TOPIC 893 Keys and Key Names !NOINDEX Key names are used to define keystroke 595aliases, in several 3514DOS.INI directives, and with the 638KEYSTACK command. The format of a key name is the same in all three uses: [Prefix-]Keyname The key prefix can be left out, or it can be any one of the following: Alt followed by A - Z, 0 - 9, F1 - F12, or Bksp Ctrl followed by A - Z, F1 - F12, Tab, Bksp, Enter, Left, Right, Home, End, PgUp, PgDn, Ins, or Del Shift followed by F1 - F12 or Tab. The possible key names are: A - Z Enter PgDn 0 - 9 Up Home F1 - F12 Down End Esc Left Ins Bksp Right Del Tab PgUp All key names must be spelled as shown. Alphabetic keys can be specified in upper or lower case. You cannot specify a punctuation key. The prefix and key name must be separated by a dash [-]. For example: Alt-F10 This is okay Alt F10 The space will cause an error If you prefer, you can use a numeric value instead of a key name. Use the ASCII code for an ASCII, extended ASCII, or control character. Use the scan code preceded by an at sign [@] for extended key codes. For example, use 13 for Enter, or @59 for F1. In general, you will find it easier to use the names described above rather than key numbers. See 911ASCII and Key Codes for an explanation and list of ASCII and key codes. Some keys are intercepted by your operating system or BIOS and are not passed on to 4DOS. For example, Ctrl-S pauses screen output temporarily, and on some systems Ctrl-P toggles Print Echo mode (where text displayed on the screen is automatically echoed to the printer). Keys which are intercepted by DOS or the BIOS generally cannot be assigned to aliases or with 481key mapping directives, because 4DOS never receives these keystrokes and therefore cannot act on them. ;--------------------------------------------------------------------------- !TOPIC 894 Popup Windows !NOINDEX Several features of 4DOS display popup windows. A popup window may be used to display filenames, recently-executed commands, recently-used directories, the results of an extended directory search, or a list created by the SELECT command or the @SELECT internal function. Popup windows always display a list of choices and a cursor bar. You can move the cursor bar inside the window until you find the choice that you wish to make, then press the Enter key to select that item. Navigation inside any popup window follows the conventions described below. Additional information on each specific type of popup window is provided where that window is discussed. You can control the color, position and size of most popup windows from the Windows page of the 648OPTION dialogs. You can also control these features with directives in the .INI file, including 440PopupWinLeft, PopupWinTop, PopupWinWidth, and PopupWinHeight, and 464PopupWinColors. The 048extended directory search window has its own specific .INI 417directives and corresponding separate choices in the OPTION dialogs. You can also change the keys used in most popup windows with 481key mapping directives in the .INI file. Once a window is open, you can use the mouse or these keyboard navigation keys to find the selection you wish to make: Up Arrow Move the selection bar up one line. Down Arrow Move the selection bar down one line. Left Arrow Scroll the display left 4 columns. Right Arrow Scroll the display right 4 columns. PgUp Scroll the display up one page. PgDn Scroll the display down one page. Ctrl-PgUp Go to the beginning of the list. (or Home) Ctrl-PgDn Go to the end of the list. (or End) Esc Close the window without making a selection. Enter Select the current item and close the window. In addition to scrolling through a popup window, you can search the list using character matching. If you press a character, the cursor bar will move to the next entry that begins with that character. If you type multiple characters, the cursor will move to the entry that begins with the search string entered to that point (you can enter a search string up to 32 characters long). If no entry matches the character or string that you have typed, 4DOS beeps and does not move the cursor bar. ;--------------------------------------------------------------------------- !TOPIC 895 Executable Files and File Searches !NOINDEX Once 4DOS knows that it is supposed to run an external command, it tries to find an executable file (one with a .COM or .EXE extension) whose name matches the command name. It runs the executable file if it finds one. If 4DOS cannot find an executable program to run, it next looks for a batch file (a file with one or more commands in it) whose name matches the command name. 4DOS looks first for a .BTM file, and then for a .BAT file. See 103.BAT and .BTM Files for more information on these different types of batch files. If 4DOS finds such a file, it then reads each line in the file as a new command. If the search for a batch file fails, 4DOS checks to see if the command name matches the name of a file with an extension that is associated with a specific application (for example, if you have associated .DOC with your editor or word processor, and you type the name of a .DOC file). See 082Executable Extensions to learn how to associate file extensions with a particular program. If a match is found, 4DOS runs the program you specified when the association was defined. 4DOS first searches for an executable program, a batch file, and a file with an executable extension in the current directory. If the command name doesn't match a .COM, .EXE, .BTM, or .BAT file or an executable extension in the current directory, 4DOS repeats its search in every directory in your search path. (The standard list of extensions for which to search can be modified by setting 477PathExt to Yes in 4DOS.INI, then setting the 143PATHEXT variable.) The search path is a list of directories that 4DOS (and some applications) search for executable files. For example, if you wanted 4DOS to search the root directory of the C: drive, the \DOS subdirectory on the C: drive, and the \UTIL directory on the D: drive for executable files, your search path would look like this: PATH=C:\;C:\DOS;C:\UTIL Notice that the directory names in the search path are separated by semicolons. You can create or view the search path with the 649PATH command. You can use the 622ESET command to edit the path. Many programs also use the search path to find their own files. The search path is stored in the environment with the name 138PATH. Remember, 4DOS always looks for an executable file or a file with an executable extension in the current subdirectory, then in each directory in the search path. (You can change the search order so the current directory is not searched first; see the 649PATH command for details.) If you include an extension as part of the command name, 4DOS only searches for a file with that extension. Similarly, if you include a path as part of the command name, 4DOS will look only in the directory you specified, and ignore the usual search of the current directory and the PATH. If your command name includes a path, the elements must be separated with backslashes (e.g. c:\wp7\wp). If you are accustomed to Unix syntax where forward slashes are used in command paths, and want 4DOS to recognize this approach, you can set 476UnixPaths to Yes in 4DOS.INI. The following table sums up the possible search options (the term "standard search" refers to the search of the current directory and each directory in the search path): Command 4DOS Search Sequence !INDENT 21 5 5 5 WP Standard search for any executable file whose base name is WP. WP.EXE Standard search for WP.EXE; will not find files with other extensions. C:\WP7\WP Looks in the C:\WP7 directory for any executable file whose base name is WP. Does not check the standard search directories. C:\WP7\WP.EXE Looks only for the file C:\WP7\WP.EXE. LAB.DOC Standard search for LAB.DOC, if .DOC is defined as an executable extension. Runs the associated application if the file is found. C:\LI\LAB.DOC Looks only for the file C:\LI\LAB.DOC, and only if .DOC is defined as an executable extension. Runs the associated application if the file is found. !INDENT 0 If 4DOS cannot find an executable file, batch program, or a file with an executable extension in the current directory or any directory in the search path, it looks for an alias called UNKNOWN_CMD (see the 595ALIAS command for details). If you have defined an alias with that name, it is executed (this allows you to control error handling for unknown commands). Otherwise, 4DOS displays an "Unknown command" error message and waits for your next instruction. ;--------------------------------------------------------------------------- !TOPIC 896 How 4DOS Uses Memory !NOINDEX The memory in your computer is organized in bytes. Normally, the amount of memory in a computer is discussed in terms of kilobytes (KBytes or 1,024 bytes) and megabytes (MBytes or 1,048,576 bytes or 1,024 KBytes). The amount of memory available in your computer is determined by the number of memory chips or memory modules you have installed. In an ideal world, there would be little more to say about memory. But because of the history of PCs, the needs of large application programs, and the capabilities of advanced CPUs, there are many different kinds of memory. The original 8088 CPUs of the PC and PC/XT can address 1 MByte of memory. Of that, a maximum of 640KBytes is allocated as base, conventional, DOS, or low DOS memory (all these terms mean the same thing). The other 384 KBytes, known as upper memory, are set aside for the computer's built-in ROM BIOS, video adapter cards, hard disk controllers, and other expansion hardware. When base memory became too limiting, expanded memory (or EMS memory) was developed to give programs more data space. Expanded memory adds a maximum of 32 MBytes which programs can access, 64KBytes at a time, through a window in upper memory. In 8088 / 8086 (PC and XT), and 80286 (AT) based computers, expanded memory typically requires an add-on board and support software. In 386, 486, and Pentium computers, expanded memory is typically provided without additional hardware, using the capabilities of the 386 / 486 / Pentium chips. The 80286 CPU used in the AT, and modern 386, 486, and Pentium CPUs, can use much more than the 8088's original 1 MByte of memory. An 80286 can use a total of 16 MBytes, and the 386, 486, and Pentium can use up to 4,096 MBytes (4 GBytes) of physical memory. This extended memory is not normally available to DOS-based programs, however, without special programming techniques and the help of DOS extenders or memory managers. The memory terms used in the 4DOS help include: !INDENT 5 5 5 5 Base memory: The 640 Kbytes or less that has traditionally been available for DOS and DOS-based applications. EMS or LIM EMS Memory: Memory which conforms to the Expanded Memory Specification, developed by Lotus, Intel, and Microsoft, that lets programs and utilities share expanded memory. Extended Memory: Memory beyond 1 MB in 80286, 386, 486 and Pentium computers. This memory may be accessed directly, in which case it is referred to as Extended Memory, or through XMS software, in which case it is referred to as XMS Memory. XMS Memory: Extended memory managed by software which conforms to the Extended Memory Specification (XMS). XMS lets programs share extended memory without conflict. This specification divides extended memory into extended memory blocks (EMBs). XMS software also usually manages the HMA and the UMBs. HMA: The first 64K bytes of extended memory, located just above 1 MB. Certain specialized programs such as DESQview, some network drivers, as well as portions of MS-DOS / PC DOS 5.0 or later and of DR DOS 5.0 or later can be loaded into the HMA instead of taking up valuable space in base memory. UMBs: 386, 486, and Pentium computers can electronically "move" pieces of extended memory into unused space in the upper memory area between 640KB and 1 MB. Each block of this memory is called an Upper Memory Block (UMB). With MS-DOS / PC DOS 5.0 or later, DR DOS 5.0 or later, or third-party memory managers like 386MAX and QEMM, memory-resident programs can be loaded into these UMBs instead of taking up valuable space in base memory. Some 8086, 8088, and 80286 systems can also use UMBs with appropriate additional hardware and software. !INDENT 0 4DOS does its best to detect and properly access all types of memory that your computer can have. 4DOS always uses standard, documented methods to use the memory that you have installed. 4DOS uses memory in three ways: !INDENT 7 5 5 5 * By default, 4DOS uses base memory for its resident portion, the master environment, and the alias and history lists. Base memory is also used to hold the transient portion of 4DOS while your system is at the command prompt or executing a 4DOS command or batch file, and to create any necessary temporary data areas (for example, to hold the filenames to be listed in a directory display, or data being copied from one file to another). * 4DOS can use EMS memory or an XMS Extended Memory Block (EMB) to swap its transient portion, according to the 391Swapping directive in your 4DOS.INI file. * 4DOS can use Upper Memory Blocks (UMBs) for its resident portion, master environment, and global alias and history lists. See 897Upper Memory Blocks for more information. !INDENT 0 If you want to know whether 4DOS sees your system's memory accurately, check the output of the 645MEMORY command. It should correspond to your computer's memory configuration. The MEMORY command's output depends to some extent on your memory manager. Some memory managers turn your extended memory into either XMS or EMS memory as required, so that the same memory is shown both ways in the MEMORY report. If 1 MB of extended memory managed by such a memory manager is available, MEMORY will report 1 MB of free XMS memory and 1 MB of free EMS memory, even though it is all the same memory. Memory-related problems with 4DOS are usually due to programs which overwrite the extended memory block (EMB) that 4DOS uses for swapping its transient portion. When you exit from such a program, your system will hang, because 4DOS tried to swap itself back into base memory but its code and data in XMS have been destroyed by the program. The same problem can occur with EMS swapping but is less common because EMS memory is generally better defended against wayward programs. You can diagnose this kind of problem easily by changing to disk swapping with the 4DOS.INI 391Swapping directive and restart the vDosPlus session. If the problem goes away with disk swapping, then the program in question is probably destroying 4DOS's swap area in XMS or EMS memory. 4DOS EMS swapping sometimes has difficulty with EMS drivers which do not fully meet the EMS 3.2 specification (4DOS supports, but does not require, EMS 4.0 drivers). If you have trouble accessing EMS for swapping, check 751Compatibility to see if there are any known problems with your EMS board or the associated driver software. ;--------------------------------------------------------------------------- !TOPIC 897 Upper Memory Blocks (UMBs) !NOINDEX 4DOS uses UMBs for several purposes: !INDENT 7 5 5 5 * to move the 4DOS resident portion out of base memory, if you specify 398UMBLoad = Yes in your 4DOS.INI file. * to move the master environment out of base memory, if you specify 395UMBEnvironment = Yes in your 4DOS.INI file. * to move the global alias and history lists out of base memory, if you specify 393UMBAlias = Yes, 396UMBFunction = Yes, or 397UMBHistory = Yes in your 4DOS.INI file. * to load memory-resident programs (TSRs) "high" using the 639LOADHIGH / LH command. !INDENT 0 To load 4DOS, the master environment, or global alias and history lists into a UMB, you must be using a memory manager or XMS driver which provides both the ability to remap memory into the area between 640K and 1MB (to create the UMBs) and XMS or DOS 5.0 UMB support (to manage the UMBs). These are generally the same requirements which must be met to load TSRs "high." Upper Memory Regions Upper memory blocks are divided into one or more contiguous regions by your memory manager (see your memory manager documentation for additional details). All the 4DOS options and commands which allow access to UMBs also allow you to specify a particular UMB region. For example, you can load the resident portion of 4DOS into upper memory region 1 with a 398UMBLoad = 1 directive in 4DOS.INI. If you do not specify a particular region (for example, if you use UMBLoad = Yes rather than UMBLoad = 1), 4DOS will use the first available region. ;--------------------------------------------------------------------------- !TOPIC 911 ASCII and Key Codes !NOINDEX For ASCII and key code reference tables, see: 912ASCII Tables 913Key Code and Scan Code Tables The remainder of this section gives a detailed explanation of character sets, ASCII, and key codes. If you are troubleshooting a keyboard or character display problem be sure to read all of the explanation below before referring to the tables. The translation of a key you type on the keyboard to a displayed character on the screen depends on several related aspects of character handling. A complete discussion of these topics is well beyond the scope of this document. However, a basic picture of the steps in the keystroke and character translation process will help you understand how characters are processed in your system, and why they occasionally may not come out the way you expect. Internally, computers use numbers to represent the keys you press and the characters displayed on the screen. To display the text that you type, your computer and operating system require five pieces of information: !INDENT 7 5 5 5 * The numeric key code for the physical key you pressed. * The specific character that key code represents based on your current keyboard layout or country setting. * The character set currently in use on your system (see below). * The international code page in use for that character set. * The display font used to display the character. !INDENT 0 The numeric key code is determined by your physical hardware including the language that your keyboard is produced for. The character set is usually determined by the operating system. These items typically are not under your control. However, most systems do allow you to control the keyboard country setting, the code page, and the display font. For an explanation of how key codes work, see the 914Key Codes and Scan Codes Explanation. For a list of key codes and scan codes for keys on the standard U.S. keyboard see the 913Key Code and Scan Code Tables. If the key codes produced by your keyboard, the code page, and the font you choose are not fully compatible with each other, the characters displayed on the screen will not match what you type. The differences are likely to appear in line-drawing characters, "international" (non-English) characters, and special symbols, not in commonly-used U.S. English alphabetic, numeric, or punctuation characters. Most systems use a "single-byte" character set for keyboard and screen display. These sets define 256 characters or symbols, with a numeric representation for each. ("Double-byte" character sets, with up to 65,536 characters each, are used for languages with more than 256 symbols, and for some multi-lingual systems.) Most PC single-byte character sets are based on a code called ASCII, the American Standard Code for Information Interchange. For a complete list of ASCII codes see the 912ASCII Table. The original ASCII code was defined over 30 years ago for use in mainframe and minicomputer systems, and has 128 character values. These include the upper and lower case letters, numerals, and punctuation marks used in U.S. English, plus non-printing control codes (which can be entered on most keyboards by pressing the Ctrl key plus another character, or by pressing certain special keys like Tab, Enter, Backspace, and Esc). However, ASCII is not a complete character set for the IBM PC, because it defines only 128 of the 256 symbols used on PC systems. IBM, in its original PC, created a complete 256-character set (called the Original Equipment Manufacturer or "OEM" character set) by defining an additional 128 extended ASCII codes for math symbols, "international" characters, the characters used to draw boxes and lines, and some miscellaneous symbols. Some operating systems support other character sets; in particular, Windows uses the ANSI character set internally to store and display text, even though other parts of the system (e.g. the file system which stores file names on disk) use IBM's OEM character set. The ANSI character set is identical to the OEM character set for U.S. English printed characters, but may vary for "international" characters not used in U.S. English. In most cases, Windows automatically translates characters from one set to another as needed, but problems can sometimes result in errors in displayed text (e.g., differences between the appearance of accented characters in filenames in Windows and DOS applications). See your operating system documentation for more information about character sets, code pages, and country and language support. Refer to your operating system and/or font documentation for details on the full character set available in any particular font. The tables in this section are based on U.S. English conventions. Your system may differ if it is configured for a different country or language. See your operating system documentation for more information about country and language support. ;--------------------------------------------------------------------------- !TOPIC 912 ASCII Tables !NOINDEX For more details on ASCII, character sets, and key codes, see the general information topic on 911ASCII and Key Codes. Control Characters Dec Hex Chr Nam Ctrl � Dec Hex Chr Nam Ctrl --- --- --- --- ---- � --- --- --- --- ---- 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 07 BEL ^G � 023 17  ETB ^W 008 08 08 BS ^H � 024 18  CAN ^X 009 09 09 HT ^I � 025 19  EM ^Y 010 0A 10 LF ^J � 026 1A  SUB ^Z 011 0B 11 VT ^K � 027 1B  ESC ^[ 012 0C 12 FF ^L � 028 1C  FS ^\ 013 0D 13 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 � ;NOTE: Don't remove the "invisible" ASCII 255 in the line above! You can enter the extended ASCII characters (those with values between 128 and 255) on the keyboard by holding down the Alt key, entering the decimal numeric value of the key on the numeric keypad, and then releasing the Alt key. ;--------------------------------------------------------------------------- !TOPIC 913 Key Code and Scan Code Tables !NOINDEX (For more details on key codes, scan codes, and ASCII see the general information on 911ASCII and Key Codes, and the 914Key Codes and Scan Codes Explanation.) The following table lists all of the keys on the "enhanced" U.S. keyboard. Many non-U.S. keyboards are similar, but will not be exactly the same. The keys are arranged roughly in scan code order, which is generally left to right, moving from the top of the keyboard to the bottom. Column 1 shows the key's keycap symbol or name. Columns 2 and 3 show the scan code, and the ASCII code if the key is unshifted. Columns 4 and 5 contain the codes for the shifted key. Columns 6 and 7 show the codes for Ctrl plus the key. The last column contains the scan code for Alt plus the key (Alt keystrokes have no ASCII code and always generate an ASCII code of 0, which is not shown). Key names prefaced by np are on the numeric keypad. Those prefaced by cp are on the cursor keypad between the main typing keys and the number keypad. The numeric keypad values are valid if Num Lock is turned off. If you need to specify a number key from the numeric keypad when Num Lock is on, use the scan code shown for the keypad and the ASCII code shown for the corresponding typewriter key. For example, the keypad "7" has a scan code of 71 (the np Home scan code) and an ASCII code of 54 (the ASCII code for "7"). The chart is blank for key combinations that are not reported at all by the BIOS, like Ctrl-1 and Alt-PgUp. Some entries are shown in parentheses to indicate that they are not supported on all systems under all circumstances. Top Keyboard Row Shift Shift Ctrl Ctrl Alt Key Scan ASCII Scan ASCII Scan ASCII Scan Esc 1 27 1 27 1 27 1 1 ! 2 49 2 33 120 2 @ 3 50 3 64 3 0 121 3 # 4 51 4 35 122 4 $ 5 52 5 36 123 5 % 6 53 6 37 124 6 ^ 7 54 7 94 7 30 125 7 & 8 55 8 38 126 8 * 9 56 9 42 127 9 ( 10 57 10 40 128 0 ) 11 48 11 41 129 - _ 12 45 12 95 12 31 130 = + 13 61 13 43 131 Backspace 14 8 14 8 14 127 14 Second Keyboard Row Shift Shift Ctrl Ctrl Alt Key Scan ASCII Scan ASCII Scan ASCII Scan Tab 15 9 15 0 148 0 165 Q 16 113 16 81 16 17 16 W 17 119 17 87 17 23 17 E 18 101 18 69 18 5 18 R 19 114 19 82 19 18 19 T 20 116 20 84 20 20 20 Y 21 121 21 89 21 25 21 U 22 117 22 85 22 21 22 I 23 105 23 73 23 9 23 O 24 111 24 79 24 15 24 P 25 112 25 80 25 16 25 [ { 26 91 26 123 26 27 26 ] } 27 93 27 125 27 29 27 Enter 28 13 28 13 28 10 28 Third Keyboard Row Shift Shift Ctrl Ctrl Alt Key Scan ASCII Scan ASCII Scan ASCII Scan A 30 97 30 65 30 1 30 S 31 115 31 83 31 19 31 D 32 100 32 68 32 4 32 F 33 102 33 70 33 6 33 G 34 103 34 71 34 7 34 H 35 104 35 72 35 8 35 J 36 106 36 74 36 10 36 K 37 107 37 75 37 11 37 L 38 108 38 76 38 12 38 ; : 39 59 39 58 39 ' " 40 39 40 34 40 ` ~ 41 96 41 126 41 \ | 43 92 43 124 43 28 43 Fourth Keyboard Row Shift Shift Ctrl Ctrl Alt Key Scan ASCII Scan ASCII Scan ASCII Scan Z 44 122 44 90 44 26 44 X 45 120 45 88 45 24 45 C 46 99 46 67 46 3 46 V 47 118 47 86 47 22 47 B 48 98 48 66 48 2 48 N 49 110 49 78 49 14 49 M 50 109 50 77 50 13 50 , < 51 44 51 60 51 . > 52 46 52 62 52 / ? 53 47 53 63 53 Space 57 32 57 32 57 32 57 Function Keys Shift Shift Ctrl Ctrl Alt Key Scan ASCII Scan ASCII Scan ASCII Scan F1 59 0 84 0 94 0 104 F2 60 0 85 0 95 0 105 F3 61 0 86 0 96 0 106 F4 62 0 87 0 97 0 107 F5 63 0 88 0 98 0 108 F6 64 0 89 0 99 0 109 F7 65 0 90 0 100 0 110 F8 66 0 91 0 101 0 111 F9 67 0 92 0 102 0 112 F10 68 0 93 0 103 0 113 F11 (133) (0) (135) (0) (137) (0) (139) F12 (134) (0) (136) (0) (138) (0) (140) ;NOTE: F11 and F12 are not physically available on all keyboards, ; including old PC keyboards and some laptop / palmtop keyboards. Numeric Keypad Shift Shift Ctrl Ctrl Alt Key Scan ASCII Scan ASCII Scan ASCII Scan np * 55 42 55 42 150 0 55 np Home 71 0 71 55 119 0 np Up 72 0 72 56 (141) (0) np PgUp 73 0 73 57 132 0 np Minus 74 45 74 45 142 0 74 np Left 75 0 75 52 115 0 np 5 76 0 76 53 143 0 np Right 77 0 77 54 116 0 np Plus 78 43 78 43 144 0 78 np End 79 0 79 49 117 0 np Down 80 0 80 50 (145) (0) np PgDn 81 0 81 51 118 0 np Ins 82 0 82 48 (146) (0) np Del 83 0 83 46 (147) (0) np / 224 47 224 47 149 0 164 np Enter 224 13 224 13 224 10 166 ;NOTE: Entries in parentheses according to IBM documentation. Cursor Keypad Shift Shift Ctrl Ctrl Alt Alt Key Scan ASCII Scan ASCII Scan ASCII Scan ASCII cp Home (71) (224) (71) (224) (119) (224) (151) (224) cp Up (72) (224) (72) (224) (141) (224) (152) (224) cp PgUp (73) (224) (73) (224) (132) (224) (153) (224) cp Left (75) (224) (75) (224) (115) (224) (155) (224) cp Right (77) (224) (77) (224) (116) (224) (157) (224) cp End (79) (224) (79) (224) (117) (224) (159) (224) cp Down (80) (224) (80) (224) (145) (224) (160) (224) cp PgDn (81) (224) (81) (224) (118) (224) (161) (224) cp Ins (82) (224) (82) (224) (146) (224) (162) (224) cp Del (83) (224) (83) (224) (147) (224) (163) (224) ;--------------------------------------------------------------------------- !TOPIC 914 Key Codes and Scan Codes Explanation !NOINDEX (This section explains how key codes and scan codes work. For a reference chart, see 913Key Code and Scan Code Tables.) When you press a single key or a key combination, software built into your computer (the BIOS or Basic Input / Output System, or the operating system) translates your keystroke into two numbers: a scan code, representing the actual key that was pressed, and an ASCII code, representing the ASCII value for that key. The BIOS returns these numbers the next time a program requests keyboard input. This section explains how key codes work; for information on using them with 4DOS see 4DOS.INI 481key mapping directives, 595keystroke aliases, 635INKEY, and 638KEYSTACK. Most 4DOS commands that use the numeric key codes listed here also use key names, which are usually more convenient to use than the numeric codes. See 893Keys and Key Names for more information on key names. As PCs have evolved, the structure of keyboard codes has evolved somewhat haphazardly with them, resulting in a bewildering array of possible key codes. We'll give you a basic explanation of how key codes work. For a more in-depth discussion, refer to a BIOS or PC hardware reference manual. The nuances of how your keyboard behaves depends on the keyboard manufacturer, the computer manufacturer who provides the built-in BIOS, and your operating system. As a result, we can't guarantee the accuracy of the key code information for every system, but the discussion and reference table should be accurate for most systems. Our discussion is based on the "enhanced" keyboard commonly used on 286, 386, 486, and Pentium computers, but virtually all of it is applicable to the 84-key keyboards on older systems. The primary difference is that older keyboards lack a separate cursor pad and only have 10 function keys. All keys have a scan code, but not all have an ASCII code. For example, function keys and cursor keys are not part of the ASCII character set and have no ASCII value, but they do have a scan code. Some keys have more than one ASCII code. The A, for example, has ASCII code 97 (lower case "a") if you press it by itself. If you press it along with Shift, the ASCII code changes to 65 (upper case "A"). If you press Ctrl and A the ASCII code changes to 1. In all these cases, the scan code (30) is unchanged because you are pressing the same physical key. Things are different if you press Alt-A. Alt keystrokes have no ASCII code, so the BIOS returns an ASCII code of 0, along with the A key's scan code of 30. This allows a program to detect all the possible variations of A, based on the combination of ASCII code and scan code. Some keys generate more than one scan code depending on whether Shift, Ctrl, or Alt is pressed. This allows a program to differentiate between two different keystrokes on the same key, neither of which has a corresponding ASCII value. For example, F1 has no ASCII value so it returns an ASCII code of 0, and the F1 scan code of 59. Shift-F1 also returns an ASCII code 0; if it also returned a scan code of 59, a program couldn't distinguish it from F1. The BIOS or operating system translates scan codes for keys like Shift-F1 (and Ctrl-F1 and Alt-F1) so that each variation returns a different scan code along with an ASCII code of 0. On the enhanced keyboard there's one more variation: non-ASCII keys on the cursor keypad (such as up-arrow) return the same scan code as the corresponding key on the numeric keypad, for compatibility reasons. If they also returned an ASCII code of 0, a program couldn't tell which key was pressed. Therefore, these cursor pad keys return an ASCII code of 224 rather than 0. This means that older programs, which only look for an ASCII 0 to indicate a non-ASCII keystroke like up-arrow, may not detect these cursor pad keys properly. The number of different codes returned by any given key varies from one (for the spacebar) to four, depending on the key, the design of your keyboard, and the BIOS or operating system. Some keys, like Alt, Ctrl, and Shift by themselves or in combination with each other, plus Print Screen, SysReq, Scroll Lock, Pause, Break, Num Lock, and Caps Lock keys, do not have any code representations at all. The same is true of keystrokes with more than one modifying key, like Ctrl-Shift-A. The BIOS or operating system may perform special actions automatically when you press these keys (for example, it switches into Caps Lock mode when you press Caps Lock), but it does not report the keystrokes to whatever program is running. Programs which detect such keystrokes access the keyboard hardware directly, a subject which is beyond the scope of this help system. ;--------------------------------------------------------------------------- !TOPIC 915 ANSI Commands !NOINDEX This section is a quick-reference to commonly-used ANSI X3.64 commands. An ANSI.SYS command string consists of three parts: !NOWRAP 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. !WRAP 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 4DOS, you should use the 619ECHO 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 4DOS's internal 086escape character followed by a lower-case "e". For example, the sequence shown above could be transmitted from a batch file with either of these commands (the first uses an ESC character directly; the second uses %=e): echo  echo %=e[7;12H 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 (see 652PROMPT). Commands !NOWRAP Command Description ------------------ -------------------------------------------------- ESC[rowsA Cursor up (CUU) ESC[rowsB Cursor down (CUD) ESC[colsC Cursor right (CUF) ESC[colsD Cursor left (CUB) ESC[row;colH Set cursor position (top left: row 1, col 1) (CUP) ESC[2J Clear screen (ED) ESC[K Clear from cursor to end of line (EL) ESC[row;colf Set cursor position, same as "H" command (HVP) ESC[=modeh Set display mode; see mode table below (SM) ESC[=model Set display mode; see mode table below (RM) ESC[attr;attr;..m Set display attributes; see table of attribute values below (SGR) ESC[key;string;..p Substitute "string" for the specified key; see key substitutions section below. (KR) ESC[s Save cursor position (may not be nested) (SCP) ESC[u Restore cursor position after a save (RCP) !WRAP Display Attributes !NOWRAP Attribute Description --------- --------------------------------------------------- 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 (according to ISO 6429): 30=Black 31=Red 32=Green 33=Yellow 34=Blue 35=Magenta 36=Cyan 37=White 40-47 Set the background color (according to ISO 6429): 40=Black 41=Red 42=Green 43=Yellow 44=Blue 45=Magenta 46=Cyan 47=White !WRAP Settings are cumulative, so (for example) to set bright red foreground set all attributes off, then set red, then bold: echo _[0;31;1m. Display Modes !NOWRAP Mode Description ---- --------------------------------------------------- 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) !WRAP 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 912ASCII Tables. For a list of extended key codes see 913Key Code and Scan Code Tables. To clear a key substitution, "substitute" the original key for itself. ;--------------------------------------------------------------------------- !TOPIC 941 File Systems and File Name Conventions !NOINDEX !TTY You may have dozens, hundreds, or thousands of files stored on your computer's disks. Your operating system is responsible for managing all of these files. In order to do so, it uses a unique name to locate each file in much the same way that the post office assigns a unique address to every residence. The unique name of any file is composed of a drive letter, a directory path, and a filename. Each of these parts of the file's name is case insensitive; you can mix upper and lower case letters in any way you wish. The topics below are roughly divided according to the different parts of a file name, and cover the file system structure and naming conventions: !NOWRAP 942Drives and Volumes 944Directories and Subdirectories 945File Names 946File Attributes and Time Stamps !WRAP ;--------------------------------------------------------------------------- !TOPIC 942 Drives and Volumes !NOINDEX !TTY A drive letter designates which drive contains the file. In a file's full name, the drive letter is followed by a colon. Normally, drive C: is the first (or only) hard disk drive. Windows can divide a large hard disk into multiple logical drives or volumes that are usually called C:, D:, E:, etc. Network systems (LANs) give additional drive letters to sections of the network file server drives. Additional information about disk files and directories is available under 944Directories and Subdirectories, 945File Names, and 946File Attributes and Time Stamps. ;--------------------------------------------------------------------------- !TOPIC 944 Directories and Subdirectories !NOINDEX !TTY A file system is a method of organizing all of the files on an entire disk or hard disk volume. Directories are used to divide the files on a disk into logical groups that are easy to work with. Their purpose is similar to the use of file drawers to contain groups of hanging folders, hanging folders to contain smaller manila folders, and so on. Directories are also sometimes referred to as folders. Every drive has a root or base directory, and many have one or more subdirectories. Subdirectories can also have subdirectories, extending in a branching tree structure from the root directory. The collection of all directories on a drive is often called the directory tree, and a portion of the tree is sometimes called a subtree. The terms directory and subdirectory are typically used interchangeably to mean a single subdirectory within this tree structure. Subdirectory names follow the same rules as file names (see 945File Names). The drive and subdirectory portions of a file's name are collectively called the file's path. For example, the file name C:\DIR1\DIR2\MYFILE.DAT says to look for the file MYFILE.DAT in the subdirectory DIR2 which is part of the subdirectory DIR1 which is on drive C. The path for MYFILE.DAT is C:\DIR1\DIR2. The backslashes between subdirectory names are required. On NTFS, and LFN volumes the path and file name must each be 255 characters or less in length, and in addition the total length of the path and file name together cannot exceed 260 characters. The operating system remembers a current or default directory for every drive in your system. Whenever a program tries to create or access a file without specifying the file's path, the operating system uses the current drive (if no other drive is specified) and the current directory (if no other directory path is specified). The root directory is named using the drive letter and a single backslash. For example, D:\ refers to the root directory of drive D:. Using a drive letter with no directory name at all refers to the current directory on the specified drive. For example, E:README.DOC refers to the file README.DOC in the current directory on drive E:, whereas E:\README.DOC refers to the file README.DOC in the root directory on drive E:. There are also two special subdirectory names that are useful in many situations: a single period by itself [.] means "the current default directory." Two periods together [..] means "the directory which contains the current default directory" (often referred to as the parent directory). These special names can be used wherever a full directory name can be used. 4DOS allows you to use additional periods to specify directories further "up" the tree (see 072Extended Parent Directory Names). Additional information about disk files and file systems is available under 942Drives and Volumes, 945File Names, and 946File Attributes and Time Stamps. ;--------------------------------------------------------------------------- !TOPIC 945 File Names !NOINDEX !TTY A 8.3 filename consists of a base name of 1 to 8 characters plus an optional extension composed of a period plus 1 to 3 more characters. Traditional FAT filenames with an 8-character name and a 3-character extension are sometimes referred to as short filenames (SFNs) to distinguish them from long filenames (LFNs). You can use alphabetic and numeric characters plus the punctuation marks ! # $ % & ' ( ) - @ ^ _ ` { } and ~ in both the base name and the extension of a FAT filename. Because the exclamation point [!], percent sign [%], caret [^], at sign [@], parentheses [()], and back-quote [`] also have other meanings to 4DOS, it is best to avoid using them in filenames. The LFN file systems allow file names with a maximum of 255 characters, including spaces and other characters that are not allowed in a FAT system file name, but excluding some punctuation characters which are allowed in FAT file names. See your operating system documentation for details on the characters allowed. If you use file names which contain semicolons [;], see 073Wildcards for details on avoiding problems with interpretation of those file names under 4DOS. LFN file names are stored and displayed exactly as you entered them, and are not automatically shifted to upper or lower case. For example, you could create a file called MYFILE, myfile, or MyFile, and each name would be stored in the directory just as you entered it. However, case is ignored when looking for filenames, so you cannot have two files whose names differ only in case (i.e., the three names given above would all refer to the same file). This behavior is sometimes described as "case-retentive but not case sensitive" because the case information is retained, but does not affect access to the files. Files stored on LFN volumes often have "FAT-compatible" names: names which contain only those characters legal on a FAT volume, and which meet the 8 character name / 3 character extension limits. Programs which cannot handle long names (for example, DOS programs accessing a VFAT drive under Windows 95/98/ME) generally can access files by using FAT-compatible names. If a file name includes spaces or other characters that would not be allowed in a FAT name, you must place double quotes around the name. For example, suppose you have a file named LET3 on a FAT volume, and you want to copy it to the LETTERS directory on drive F:, a FAT32 partition, and give it the name "Letter To Sara". To do so, use either of these commands: c:\wp> copy let3 f:\LETTERS\"Letter To Sara" c:\wp> copy let3 "f:\LETTERS\Letter To Sara" LFN file systems do not explicitly define an "extension" for file names which are not FAT-compatible. However, by convention, all characters after the last period in the file name are treated as the extension. For example, the file name "Letter to Sara" has no extension, whereas the name "Letter.to.Sara" has the extension Sara. Additional information about disk files and file systems is available under 942Drives and Volumes, 944Directories and Subdirectories, and 946File Attributes and Time Stamps. ;--------------------------------------------------------------------------- !TOPIC 946 File Attributes and Time Stamps !NOINDEX !TTY Each file also has attributes, and one or more time stamps. Attributes define characteristics of the file which may be useful to the operating system, to you, or to an application program. Time stamps can record when the file was created, last modified, or last accessed. Most 4DOS file processing commands allow you to select files for processing based on their attributes and/or time stamp(s). Each file on your system has four standard attributes. Every time a program modifies a file, the operating system sets the Archive attribute, which signals that the file has been modified since it was last backed up. This attribute can be used by 4DOS to determine which files to 606COPY, and by backup programs to determine which files to back up. When the Read-only attribute is set, the file can't be changed or erased accidentally; this can be used to help protect important files from damage. The Hidden and System attributes prevent the file from appearing in normal directory listings. (Two additional attributes, Directory and Volume label, are also available. These attributes are controlled by the operating system, and are not modified directly by 4DOS.) Attributes can be set and viewed with the 596ATTRIB command. The 612DIR command also has options to select filenames to view based on their attributes, to view the attributes themselves, and to view information about normally "invisible" hidden and system files. When a file is created, and every time it is modified, the operating system records the system time and date in a time stamp in the file's directory entry. Several 4DOS commands and variable functions, and many backup and utility programs, use this time stamp to determine the relative ages of files. Files on LFN volumes have three sets of time and date stamps. The operating system records when each file was created, when it was last written or modified, and when it was last accessed. The "last write" time stamp matches the single time stamp used on traditional FAT volumes. Several 4DOS commands and variable functions let you specify which set of time and date stamps you want to view or work with on LFN volumes. These commands and functions use the letter "c" to refer to the creation time stamp, "w" for the last write time stamp, and "a" for the last access time stamp. Note that LFN volumes under Windows 95/98/ME store a date but no time in the "last access" time stamp; on these drives the time of last access will always be 00:00. Additional information about disk files and file systems is available under 942Drives and Volumes, 944Directories and Subdirectories, and 945File Names. ;--------------------------------------------------------------------------- !TOPIC 971 Glossary !NOINDEX The glossary contains over 235 terms, and is divided into sections by the first letter of each term. Select the section you want to review: 9724 973A 974B 975C 976D 977E 978F 979G 980H 981I 982K 983L 984M 985N 986O 987P 988R 989S 990T 991U 992V 993W 994X ;--------------------------------------------------------------------------- !TOPIC 972 Glossary - 4 !NOINDEX 9724 973A 974B 975C 976D 977E 978F 979G 980H 981I 982K 983L 984M 985N 986O 987P 988R 989S 990T 991U 992V 993W 994X 4EXIT: A batch file which is executed whenever 4DOS exits. 4START: A batch file which is executed whenever 4DOS starts. ;--------------------------------------------------------------------------- !TOPIC 973 Glossary - A !NOINDEX 9724 973A 974B 975C 976D 977E 978F 979G 980H 981I 982K 983L 984M 985N 986O 987P 988R 989S 990T 991U 992V 993W 994X Alias Parameter: A numbered variable (e.g. %2) included in an alias definition, allowing a different value to be used in the alias each time it is executed. Alias: A shorthand name for a command or series of commands. Alternate File Name: See LFN File System, and also SFN. AND: A logical combination of two true or false conditions. If both conditions are true, the result is true; if either condition is false, the result is false. ANSI: Usually a reference to 915ANSI X3.64 control sequences, standardized sequences of text characters which control colors on the screen, manipulate the cursor, and redefine keys. 4DOS includes support for ANSI screen and cursor control sequences. The abbreviation ANSI is for American National Standards Institute, an organization which sets standards for computer-related systems, including "ANSI" screen control sequences. ANSI.SYS or ANSI Driver: A device driver supplied with DOS which supports ANSI control sequences to provide enhanced screen display and keyboard macros, or one of the many similar programs available from other vendors. APM: Advanced Power Management, a standardized system used by manufacturers of battery-powered computers to control system power management, including shutdown of unused components or of the entire system based on usage patterns. APM can also report whether the system is on AC or battery power, the battery status, and the remaining battery life. Append: Concatenation of one file or string onto the end of another. Application: A program run from the command prompt or a batch file. Used broadly to mean any program other than the command processor; and more narrowly to mean a program with a specific purpose such as a spreadsheet or word processing program, as opposed to a utility. Archive: A file attribute indicating that the file has been modified since the last backup (most backup programs clear this attribute). Also sometimes refers to a single file (such as a .ZIP file) which contains a number of other files in compressed form. Argument: See Parameter. ASCII File: A file containing ASCII text, as opposed to a binary file which may contain numbers, or other information that cannot be sensibly interpreted as text. ASCII: The American Standard Code for Information Interchange, which defines numeric values for 128 different characters comprising the English alphabet, numbers, punctuation, and some control characters. Attribute: A characteristic of a file, which can be set or cleared. The standard attributes are Read-Only, Hidden, System, and Archive; other attributes include Directory and Volume Label. AUTOEXEC.BAT: A batch file which is executed automatically each time DOS starts. In vDosPlus this is the autoexec.txt file in the start-in directory of vDosPlus. Automatic Batch Files: See AUTOEXEC.BAT, 4START, and 4EXIT. Automatic Directory Change: A 4DOS feature which allows you to change directories by typing the directory name and a backslash [\] at the prompt. ;--------------------------------------------------------------------------- !TOPIC 974 Glossary - B !NOINDEX 9724 973A 974B 975C 976D 977E 978F 979G 980H 981I 982K 983L 984M 985N 986O 987P 988R 989S 990T 991U 992V 993W 994X Base Memory: The portion of memory available for use by DOS, the DOS command processor, and DOS application programs. This area generally consists of the first 640K or 655,360 bytes of memory. Base Name: The file name without a drive, path, or extension. For example, in the file name C:\DIR1\LETTER.DAT the base name is LETTER. BAT File: See Batch File. Batch File: A text file containing a sequence of commands for the command processor to execute. Batch files are used to save command sequences so that they can be re-executed at any time, transferred to another system, etc. The extension of a batch file may be .BAT or .BTM. Batch File Parameter: A numbered variable (e.g. %2) used within a batch file, allowing a different value to be used at that spot in the file each time it is executed. Binary File: A file containing information which does not represent or cannot sensibly be interpreted as text. See also ASCII File. BIOS or Basic Input Output System: The software (or "firmware") stored on chips inside PC systems. The BIOS provides basic low-level control of devices required to operate the system, such as the keyboard, floppy disk, and screen; it also handles system self-tests at startup, and initiates loading of the operating system. Block Device: A physical device for input or output which can transmit or receive large blocks of data while the computer is engaged in other activities. See also Character Device. Boot Directory: The current directory at the time the system is booted, in vDosPlus C:\. Boot Drive: The disk drive that the system is booted from, in vDosPlus this is always designated C:. Boot: The process of starting the computer and loading the operating system into memory. See also Reboot, Cold Reboot, and Warm Reboot. Border: A narrow strip surrounding the standard text display area of the screen. The color of the border area can be controlled by special video commands under some operating systems. Break: A signal sent to a program to tell it to halt what it is doing. The Ctrl-C key or Ctrl-Break key is used to send this signal. Some external commands abort when they receive a break signal; others return to a previous screen or menu, or abort the current operation. BTM File: A special type of 4DOS batch file which is loaded into memory to speed up execution. Buffer: An area of memory set aside for storage. For example, disk buffers are used to save information as it is transferred between your program and the disk, and the keyboard buffer holds keystrokes until a program can use them. ;--------------------------------------------------------------------------- !TOPIC 975 Glossary - C !NOINDEX 9724 973A 974B 975C 976D 977E 978F 979G 980H 981I 982K 983L 984M 985N 986O 987P 988R 989S 990T 991U 992V 993W 994X Character Device: A physical device for input or output which must communicate with your computer one character at a time. Examples include the console, communications ports, and printers. See also Block Device. Character Mode: A display mode in which output is displayed in a fixed font, typically with 80 columns in a line and 25 lines on the screen (some systems allow you to increase the number of rows and columns to other fixed sizes), and which cannot display graphics or pictures. See also Graphics Mode. CMD File: See Batch File. CMDLINE: An environment variable used to extend the command line passed to another program beyond its normal length limits. Code Page: A setting which tells DOS which character set to use and how to retrieve and display date, time, and other information in the format appropriate to a particular country. See also Country Settings. Cold Reboot: The process of restarting the computer in a way that physically resets most hardware devices, typically by pressing a reset button, or by turning the power off and back on. See also Warm Reboot. Command Completion: A 4DOS feature which allows you to recall a previous command by typing the first few letters of the command, then an up-arrow or down-arrow. Command Echoing: A feature which displays commands as they are executed. Echoing can be turned on and off. Command Grouping: A 4DOS feature which allows you to group several commands with parentheses, and have them treated as a single command for most purposes. Command History Window: A pop-up window used by 4DOS to display the command history, allowing you to choose a previous command to modify and/or execute. Command History: A 4DOS feature which retains commands you have executed, so that they can be modified and re-executed later. Command Processor: A program which interprets commands and executes other programs. Sometimes also called a Command Interpreter. Command Recall: See Command History. Command Separator: A character used to separate multiple commands on the same command line. Command Tail: The portion of a command consisting of all the arguments, i.e., everything but the command name itself. Compound Command: See Multiple Commands. Compression: An operating system feature which compresses data as it is stored in a disk file, and decompresses it as it is read back, resulting in more efficient use of disk space (at a slight cost in processor time to perform the compression and decompression). More generally, an approach to data storage which reduces repeated or redundant information to a smaller number of bytes in the compressed version than in the original, in order to minimize the space required to store the information. COMSPEC: An 134environment variable which defines where to find the character-mode command processor to start a secondary shell. Conditional Commands: A 4DOS feature allowing commands to be executed or skipped depending on the results of a previous command. See also Exit Code. CONFIG.SYS: A file used by DOS to specify which programs should be loaded when DOS starts (it has no function in vDosPlus). Console: The PC keyboard and display. Console Mode: See Character Mode. Control Character: A character which is part of the ASCII code, but does not have a normal text representation, and which can usually be generated by pressing the Ctrl key along with another key. Coprocessor: See Numeric Coprocessor. Country Settings: The internal settings which tell the operating system how to interpret keyboard characters which vary from country to country, which character set to use, and how to retrieve and display date, time, and other information in the format appropriate to a particular country. See also Code Page. CPU: The Central Processing Unit which performs all logic and most calculations in a computer. In PC-compatible systems, the CPU is on a single microprocessor chip. CR or Carriage Return: The ASCII character "carriage return" (decimal value 13), generated by pressing the Enter key on the keyboard, and stored in most ASCII files at the end of each line. Critical Error: An error, usually related to a physical or hardware problem with input, output, or network access, which prevents a program from continuing. Current Directory: The directory in which all file operations will take place unless otherwise specified. The current directory is typically displayed as part of the command prompt. Also called the Current Working Directory. Current Drive: The disk drive on which all file operations will take place unless otherwise specified. The current drive is typically displayed as part of the command prompt. Cursor: A movable marker on the screen to show where text will be entered when you type at the keyboard, or which object on the screen will be affected when a mouse button is clicked. In character mode only the text cursor is available; graphical systems typically show both a mouse cursor and, when text can be entered, a separate text cursor. ;--------------------------------------------------------------------------- !TOPIC 976 Glossary - D !NOINDEX 9724 973A 974B 975C 976D 977E 978F 979G 980H 981I 982K 983L 984M 985N 986O 987P 988R 989S 990T 991U 992V 993W 994X Date Range: A 4DOS feature which allows you to select files based on the date and time they were last modified. Date Stamp: Information stored in a file's directory entry to show the dates on which the file was created, last modified, and last accessed. Creation and last access dates are not available in the FAT file system. See also Time Stamp. Default Directory: See Current Directory. Default Drive: See Current Drive. Delete Tracking: An operating system or utility software feature which is designed to allow you to "undelete" or recover files which have recently been deleted. Delete tracking typically works by temporarily retaining the deleted files and / or information about the deleted files in a special area of the disk. Description: A string of characters assigned to describe a file with the 4DOS DESCRIBE command, typically stored in the DESCRIPT.ION file in each subdirectory. Destination: In file processing commands (e.g. COPY or MOVE), the name or directory files should have after any copying or modification has taken place, generally the last specification on the command line. See also Source. Detached Process: A program which is "detached" from the normal means of user input and output, and cannot use the keyboard, mouse, or video display. Device Driver: A program which allows the operating system to communicate with a device, and which is loaded into memory when the system boots. Device drivers are also used to manage memory or for other similar internal functions. Device: A physical device for input or output such as the console, a communications port, or a printer. Sometimes "device" is used to refer to character devices, and excludes block devices. Directive: An individual item in the 4DOS.INI file, used to control the configuration of 4DOS. Directory: A portion of any disk, identified by a name and a relationship to other directories in a "tree" structure, with the tree starting at the root directory. A directory separates files on the disk into logical groups, but does not represent a physical division of the data on the disk. Directory History: A 4DOS feature which allows you to recall recently-used directory names in a popup window, and choose one to switch to. Directory History Window: See Directory History. Directory Stack: A 4DOS feature, implemented through the PUSHD and POPD commands, which allows you to save the current directory and return to it later. See also Stack. Directory Tree: The branching structure of directories on a hard disk, starting at the root directory. The root of the tree is usually considered as the "top" of the structure, so the actual structure can be visualized as an upside-down tree with the root at the top and branches going "down." A portion or branch of the directory tree is sometimes called a "subtree." DOS Memory: See Base Memory. DOS Session: See Session. DPMI or DOS Protected Mode Interface: A specification which allows DOS programs to access memory beyond 1 MB in order to manage larger programs or larger amounts of information than will fit in base memory. Drive Letter: A letter used to designate a specific local disk volume, or part or all of a network server drive. In most cases drive letters range from A - Z, but some network operating systems allow the use of certain punctuation characters as drive letters in order to support more than 26 volumes. ;--------------------------------------------------------------------------- !TOPIC 977 Glossary - E !NOINDEX 9724 973A 974B 975C 976D 977E 978F 979G 980H 981I 982K 983L 984M 985N 986O 987P 988R 989S 990T 991U 992V 993W 994X Echo: See Command Echoing. EMS Memory: Memory which conforms to the Lotus / Intel / Microsoft Expanded Memory Specification (LIM EMS), which allows programs to access large amounts of memory outside of base memory or extended memory. EMS Swapping: A type of swapping in which the transient portion of 4DOS is stored in EMS memory while an application is running. Environment: An area of memory which contains multiple entries in the form "NAME=value". See also Master Environment and Passed Environment. Environment Variable: The name of a single entry in the environment. Error Level: A numeric value between 0 and 255 returned from an external command to indicate its result (e.g., success, failure, response to a question). See also Exit Code. Escape Character: In some contexts, the 4DOS escape character, which is used to suppress the normal meaning of or give special meaning to the following character. In other cases, the specific ASCII character ESC. The meaning must be determined from the context. Escape Sequence: A sequence of text characters which has a special meaning and is not treated as normal text. For example, the character sequence [K (where is the ASCII "escape" character, decimal value 27) will clear the screen from the cursor to the end of the current line, rather than simply displaying the string "ESC[K" on the screen. Similarly, in 4DOS, the escape sequence f on the command line (where is the ASCII Ctrl-X character, decimal value 24) is translated to a form feed, and is not treated as the literal characters "f". Executable Extensions: A 4DOS feature which allows you to specify the application to be executed when a file with a particular extension is named at the command prompt. Executable File: A file, usually with the extension .COM or .EXE, which can be loaded into memory and run as a program. Exit Code: The result code returned by an external command or an internal command. 4DOS internal commands return an exit code of 0 if successful, or non-zero if unsuccessful. See also Errorlevel. Expansion: The process 4DOS goes through when it scans a command line and substitutes the appropriate actual values for aliases, alias parameters, batch file parameters, and environment variables. See also Parsing. Extended ASCII Character: A character which is not part of the standard set of 128 ASCII characters, but is used on the PC as part of an extended set of 256 characters. These characters include international language symbols, and box and line drawing characters. Extended Directory Search: A 4DOS feature which maintains a directory search "database" or list, typically including all directories in your system, and allows you to change quickly to any directory in the list. Extended Key Code: The code for a key on the PC keyboard which has no representation in the standard ASCII character set, such as a function key, cursor key, or Alt plus another key. The extended key code for a key is often the same as the scan code for that key. Extended Memory: Any memory on a computer system with a 286, 386, 486, or Pentium processor which is above the first 1 MB (one megabyte, or 1024*1024 bytes) of memory. See also XMS. Extended Parent Directory Names: A 4DOS feature which allows you to use additional periods in a directory name to represent directories which are successively higher in the directory tree. Extended Wildcard: A 4DOS feature which extends the traditional wildcard syntax and allows you to use multiple wildcard characters, and character ranges (e.g. [a-f] for the letters A through F). See also Wildcard. Extension: The final portion of a file name, preceded by a period. For example, in the file name C:\DIR1\LETTER.DAT the extension is .DAT. In a long filename which contains multiple periods, the extension is usually considered to be the portion of the name after the final period. External Command: A program which resides in an executable file, as opposed to an internal command which is part of 4DOS. ;--------------------------------------------------------------------------- !TOPIC 978 Glossary - F !NOINDEX 9724 973A 974B 975C 976D 977E 978F 979G 980H 981I 982K 983L 984M 985N 986O 987P 988R 989S 990T 991U 992V 993W 994X FAT File System: The traditional file system used by DOS to store files on diskettes and hard disks. Uses a File Allocation Table to keep track of allocated and unallocated space on the disk. FAT32 File System: An extension of the FAT file system. FAT32 supports long filenames, and supports much larger hard disks than the FAT system. See also VFAT File System. FAT-Compatible File Name: See SFN. FF or Form Feed: The ASCII character "form feed" (decimal value 12), which typically causes a printer to skip to a new page. The FF character is not normally entered from the keyboard, but in many cases it can be generated, if necessary, by holding the Alt key, pressing 0-1-2, and releasing the Alt key. File Attribute: See Attribute. File Description: See Description. File Exclusion Range: A 4DOS feature which allows you to exclude files from processing by internal commands based on their names. Filename Completion: A 4DOS feature which allows you to type part of a filename on the command line, and have 4DOS fill in the rest for you. Free Memory: Usually, the amount of total memory which is unoccupied and available for applications. ;--------------------------------------------------------------------------- !TOPIC 979 Glossary - G !NOINDEX 9724 973A 974B 975C 976D 977E 978F 979G 980H 981I 982K 983L 984M 985N 986O 987P 988R 989S 990T 991U 992V 993W 994X Global Aliases: A 4DOS option which allows you to store aliases in a global area accessible to all copies of 4DOS, so that any change made by one copy is immediately available to all other copies. See also Local Aliases. Global Directory History: A 4DOS option which allows you to store the directory history in a global area accessible to all copies of 4DOS, so that any change made by one copy is immediately available to all other copies. See also Local Directory History. Global History: A 4DOS option which allows you to store the command history in a global area accessible to all copies of 4DOS, so that any change made by one copy is immediately available to all other copies. See also Local History. Graphics Mode: A display mode in which output is displayed in any one of a range of fonts, typically in resizable windows with a variable number of text rows and columns, and which supports the display of graphics and pictures along with text. See also Character Mode. ;--------------------------------------------------------------------------- !TOPIC 980 Glossary - H !NOINDEX 9724 973A 974B 975C 976D 977E 978F 979G 980H 981I 982K 983L 984M 985N 986O 987P 988R 989S 990T 991U 992V 993W 994X Hidden: A file attribute indicating that the file should not be displayed with a normal DIR command, and should not be made available to programs unless they specifically request access to hidden files. History Window: See Command History Window and Directory History. History: See Command History. HMA or High Memory Area: The area of PC memory located in the first 64K bytes above the 1 megabyte that DOS can address directly. The HMA can be made addressable from DOS programs using special hardware facilities, or an XMS driver. ;--------------------------------------------------------------------------- !TOPIC 981 Glossary - I !NOINDEX 9724 973A 974B 975C 976D 977E 978F 979G 980H 981I 982K 983L 984M 985N 986O 987P 988R 989S 990T 991U 992V 993W 994X Include List: A concise method of specifying several files or groups of files in the same directory, for use with all 4DOS commands which take file names as arguments. Inheritance: A feature which allows one copy of 4DOS to "inherit" the .INI file data, aliases, command history, and directory history from a previous copy. More generally, a system which allows one program to pass information or settings on to another, often to a second copy of the same program. .INI File: The 4DOS initialization file containing directives which set the initial configuration of 4DOS. Insert Mode: When editing text, a mode in which newly typed characters are inserted into the line at the cursor position, rather than overwriting existing characters on the line. See also Overstrike Mode. Internal Command: A command which is part of 4DOS, as opposed to an external command. Internal Variables: Environment variables created by 4DOS to provide information about your system. Internal variables are evaluated each time they are used, and are not actually stored in the environment. ;--------------------------------------------------------------------------- !TOPIC 982 Glossary - K !NOINDEX 9724 973A 974B 975C 976D 977E 978F 979G 980H 981I 982K 983L 984M 985N 986O 987P 988R 989S 990T 991U 992V 993W 994X Key Code: The code passed to a program when a key is pressed on the keyboard. Depending on the key that is pressed, and the software handling the keyboard, the code can be an ASCII code, a scan code, or an extended key code. Key Mapping: A 4DOS feature which allows you to assign new keystrokes for command line functions such as manipulating the command history or completing file names. Keyboard Buffer: A buffer which holds keystrokes you have typed that have not yet been used by the currently executing program. Keystroke Alias: An alias assigned to a key, so that it can be invoked or recalled with a single keystroke. ;--------------------------------------------------------------------------- !TOPIC 983 Glossary - L !NOINDEX 9724 973A 974B 975C 976D 977E 978F 979G 980H 981I 982K 983L 984M 985N 986O 987P 988R 989S 990T 991U 992V 993W 994X Label: A marker in a batch file, with the format :name, allowing GOTO and GOSUB commands to "jump" to that point in the file. See also Volume Label. LF or Line Feed: The ASCII character "line feed" (decimal value 10), stored in most ASCII files at the end of each line, after the CR character. The LF character is not normally entered from the keyboard, but in many cases it can be generated, if necessary, by pressing Ctrl-Enter. LFN or Long File Name: A file name which does not conform to the traditional DOS 8.3 filename restrictions, either because it is longer than the traditional 8.3 name, or because it contains periods, spaces, or other characters not allowed in a traditional DOS 8.3 filename. LFN File System: A file system which extends the DOS 8.3 filename system to support long filenames and possibly larger hard drives. An LFN file system stores both a long and short name for a file, not just a long name. The short name is sometimes called the "alternate" name. See also LFN, SFN, VFAT File System, and FAT32 File System. Local Aliases: A 4DOS option which allows you to store aliases in a local area only accessible to the current copy of 4DOS, so that a change made in the current copy of 4DOS does not affect other copies, and vice versa. See also Global Aliases. Local Directory History: A 4DOS option which allows you to store the directory history in a local area only accessible to the current copy of 4DOS, so that a change made in the current copy of 4DOS does not affect other copies, and vice versa. See also Global Directory History. Local History: A 4DOS option which allows you to store the command history in a local area only accessible to the current copy of 4DOS, so that a change made in the current copy of 4DOS does not affect other copies, and vice versa. See also Global History. Logging: A 4DOS feature, implemented via the LOG command, which allows you to save a record of the commands you execute. ;--------------------------------------------------------------------------- !TOPIC 984 Glossary - M !NOINDEX 9724 973A 974B 975C 976D 977E 978F 979G 980H 981I 982K 983L 984M 985N 986O 987P 988R 989S 990T 991U 992V 993W 994X Master Environment: The master copy of the environment maintained by 4DOS. Memory-Resident Mode: A method of installing 4DOS in which swapping is disabled, and all of 4DOS remains permanently resident in memory. Memory-Resident Program: See TSR. Modulo: The remainder after an integer division. For example 11 modulo 3 is 2, because when 11 is divided by 3 the remainder is 2. Multiple Commands: A 4DOS feature which allows multiple commands to be placed on a line, separated by a caret [^], or another user-defined character. Multitasking: A capability of some software (and the related hardware) which allows two or more programs to run apparently simultaneously on the same computer. ;--------------------------------------------------------------------------- !TOPIC 985 Glossary - N !NOINDEX 9724 973A 974B 975C 976D 977E 978F 979G 980H 981I 982K 983L 984M 985N 986O 987P 988R 989S 990T 991U 992V 993W 994X Network: A system which allows several computers to be connected together to share files, printers, modems, or other resources, and to pass electronic mail or other information between the systems on the network. Network File System: Software which runs over a network to allow access to files on the server. A network file system may support the same options as the file system used on local drives, or it may be more or less restrictive than the local file system about file names, disk volume capacity, and other similar features. Non-Swapping Mode: See Memory Resident Mode. NTFS or New Technology File System: A file system distributed with the 25Windows NT line which allows longer file names, supports larger drives and provides better performance than the traditional FAT file system. Numeric Coprocessor: A chip which works in conjunction with an Intel 8086, 80286, 80386, 80486, or Pentium CPU to perform decimal arithmetic ("floating point") calculations. Some 80486s and the Pentium CPU have the numeric coprocessor built into the CPU chip; in all other cases it is on a physically separate chip, and is optional (when the coprocessor is not avilable, the CPU performs decimal arithmetic through other, much slower methods). ;--------------------------------------------------------------------------- !TOPIC 986 Glossary - O !NOINDEX 9724 973A 974B 975C 976D 977E 978F 979G 980H 981I 982K 983L 984M 985N 986O 987P 988R 989S 990T 991U 992V 993W 994X Operating System: A collection of software which loads when the computer is started, provides services to other software, and ensures that programs don't interfere with each other while they are running. Option: See Switch. OR: A logical combination of two true or false conditions. If both conditions are false the result is false; if either condition is true the result is true. Overstrike Mode: When editing text, a mode in which newly typed characters overwrite existing characters on the line, rather than being inserted into the line at the cursor position. See also Insert Mode. ;--------------------------------------------------------------------------- !TOPIC 987 Glossary - P !NOINDEX 9724 973A 974B 975C 976D 977E 978F 979G 980H 981I 982K 983L 984M 985N 986O 987P 988R 989S 990T 991U 992V 993W 994X Parameter: A piece of additional information placed after a command or function name. For example, in the command DIR XYZ, XYZ is a parameter. Also used to refer to an alias parameter or batch file parameter. Parent Directory: The directory in which a particular subdirectory resides, often seen as the directory "above" a subdirectory. Parsing: The process 4DOS performs to analyze the command line, perform alias and environment variable expansion, and find the appropriate internal command or external command to execute. More generally, the process of breaking down a string or message into its individual components in order to process them properly. Passed Environment: A copy of the master environment created before running an application, so that any changes made by the application will not affect the master environment. Path: A specification of all the directories a file resides in. For example, the path for C:\WPFILES\MYDIR\MEMO.TXT is C:\WPFILES\MYDIR\. Also used to refer to the environment variable PATH, which contains a series of path specifications used when searching for external commands and batch files. Pipe: A method for collecting the standard output of one program and passing it on as the standard input of the next program to be executed, signified by a vertical bar "|" on the command line. See also Redirection. Previous Working Directory: The working directory used most recently, just prior to the current working directory. For example, if C:\DATA is the current working directory and you switch to D:\UTIL, C:\DATA then becomes the previous working directory. Primary Shell: The copy of the character-mode command processor which is loaded by the operating system when the system boots or a session opens. ;--------------------------------------------------------------------------- !TOPIC 988 Glossary - R !NOINDEX 9724 973A 974B 975C 976D 977E 978F 979G 980H 981I 982K 983L 984M 985N 986O 987P 988R 989S 990T 991U 992V 993W 994X RAM or Random Access Memory: The physical memory used to store data while a computer is operating. The information in most types of RAM is lost when power is turned off. RAM Disk: A pseudo "disk drive", created by software, which appears like a normal physical disk drive to programs. Sometimes also called a Virtual Disk. Range: See Date Range, Size Range, Time Range, and File Exclusion Range. Read-Only: A file attribute indicating that the file can be read, but not written or deleted by the operating system or 4DOS unless special commands are used. Reboot: The process of restarting the computer with software, with the keyboard (e.g. by pressing Ctrl-Alt-Del), by pressing a reset button, or by turning the power off and back on. See also Cold Reboot and Warm Reboot. Redirection: A method for collecting output from a program in a file, and/or of providing the input for a program from a file. See also Pipe. Registry: A hierarchically organized data file maintained by Windows to hold system parameters, hardware and software settings, and other similar information used by the operating system or by other software packages. Resident Portion: The small portion of 4DOS stored permanently in memory when swapping mode is in use, as opposed to the larger transient portion. REXX: A file and text processing language developed by IBM, and available on many PC and other platforms. ROM or Read Only Memory: A physical memory device used to store information which cannot be readily modified, such as the BIOS built into each PC system. The information in ROM is typically retained when power is turned off. Root Directory: The first directory on any disk, from which all other directories are "descended." The root directory is referenced with a single backslash [\]. ;--------------------------------------------------------------------------- !TOPIC 989 Glossary - S !NOINDEX 9724 973A 974B 975C 976D 977E 978F 979G 980H 981I 982K 983L 984M 985N 986O 987P 988R 989S 990T 991U 992V 993W 994X Scan Code: The physical code for a key on the PC keyboard. For the original U.S. English keyboard layout the scan code represents the physical position of the key, starting with 1 for the key in the upper left corner (Esc), and increasing from left to right and top to bottom. This order will vary for more recent keyboards or those designed for other countries or languages. Search Path: See 138PATH. Secondary Shell: A copy of the command processor which is started by another program, rather than by the operating system. Session: A general term for the individual windows or tasks started by a multitasking system. SFN or Short File Name: A file name which follows the rules of the traditional FAT file system: a name of 1 - 8 characters and an extension of 0 - 3 characters, each consisting of only alphabetic and numeric characters plus the punctuation marks ! # $ % & ' ( ) - @ ^ _ ` { } and ~. See also LFN. Shell: See Command Processor. Also used to refer to a program which gives access to operating system functions and commands through a menu- or mouse-driven system, or which replaces the primary user interface of the operating system. Size Range: A 4DOS feature which allows you to select files based on their size. Source: In file processing commands (e.g. COPY or MOVE), the original files before any copying or modification has taken place, i.e., those specified earlier on the command line. See also Destination. Stack: An area of memory used by any program to store temporary data while the program is running; more generally, any such storage area where the last item stored is normally the first one removed. Standard Error, Standard Input, and Standard Output: The file(s) or character device(s) where a program respectively displays error messages, obtains its normal input, and displays its normal output. Standard error, standard input, and standard output normally refer to the console, unless redirection is used. stderr, stdin, and stdout: Common abbreviations for standard error, standard input, and standard output respectively. Subdirectory: Any directory other than the root directory. Unlike the root directory, subdirectories have names, attributes, and time stamps; subdirectories are stored on disk in much the same way files are. Subtree: See Directory Tree. Swap File: A disk file created by an operating system or a program to store unused information on disk, and thereby free up memory for other purposes. Under 4DOS, a disk file created by 4DOS to store its transient portion when disk swapping is in use. Swapping: A 4DOS feature which removes the larger transient portion of 4DOS from base memory while an application is running, leaving the maximum possible amount of memory for the application. Switch: A parameter for an internal command or application which specifies a particular behavior or setting. For example, the command "DIR /P" might be referred to as "having the /P switch set." System: A file attribute indicating that the file belongs to the operating system, and should not be accessed by other programs. ;--------------------------------------------------------------------------- !TOPIC 990 Glossary - T !NOINDEX 9724 973A 974B 975C 976D 977E 978F 979G 980H 981I 982K 983L 984M 985N 986O 987P 988R 989S 990T 991U 992V 993W 994X Target: See Destination. Time Range: A 4DOS feature which allows you to select files based on the time they were last modified. Time Stamp: Information stored in a file's directory entry to show the times at which the file was created, last modified, and last accessed. Creation and last access times are not available in the FAT file system, and creation time is not available in the VFAT file system. See also Date Stamp. Transient Portion: The larger portion of 4DOS stored in memory temporarily when swapping is in use, as opposed to the smaller resident portion. Tree: See Directory Tree. TSR: A DOS Terminate and Stay Resident program, i.e., a program which "terminates" but remains resident in memory, to provide features such as network support, a pop-up notepad or telephone dialer, a disk cache, or mouse support. ;--------------------------------------------------------------------------- !TOPIC 991 Glossary - U !NOINDEX 9724 973A 974B 975C 976D 977E 978F 979G 980H 981I 982K 983L 984M 985N 986O 987P 988R 989S 990T 991U 992V 993W 994X UDF or User-Defined Function: A variable function defined with the 696FUNCTION command. UMB or Upper Memory Block: An XMS Upper Memory Block, whose address is above the end of base memory (normally, above 640K), but within the 1 megabyte of memory that DOS can address directly. UNC or Universal Naming Convention: A common method for accessing files on a network drive without using a "mapped" drive letter. Names specified this way are called UNC names, and typically appear as \\server\volume\path\filename, where server is the name of the network server where the files reside, volume is the name of a disk volume on that server, and the path\filename portion is a directory name and file name. ;--------------------------------------------------------------------------- !TOPIC 992 Glossary - V !NOINDEX 9724 973A 974B 975C 976D 977E 978F 979G 980H 981I 982K 983L 984M 985N 986O 987P 988R 989S 990T 991U 992V 993W 994X V86: A virtual 8086 mode in the 386 and later CPUs that allows execution of real mode (16-bit) programs in protected (32-bit) mode. Variable Expansion: The process of scanning a command line and replacing each environment variable name, alias parameter, or batch file parameter with its value. Variable Functions: Functions provided by 4DOS to manipulate strings, dates, and filenames; perform arithmetic; read and write files; and perform other similar functions. Variable functions are similar to static environment variables or internal variables, but have parameters and can perform actions rather than just returning static information. Variable: See Alias Parameter, Batch File Parameter, and Environment Variable. VCPI or Virtual Control Program Interface: A specification for managing memory beyond the first megabyte on PCs with 386 or later processors. VCPI support for DOS programs is provided by some DOS memory managers. See also DPMI. VDS or Virtual DMA (Direct Memory Access) Services: A programming interface that lets bus mastering devices cooperatively manage DMA when the CPU runs in protected mode. VDS are provided by some memory managers and Windows versions. See also V86. VESA or Video Electronics Standards Association: An international body that has issued some standards relating to the video peripherals in personal computers, such as the VESA BIOS Extensions, VESA Display Power Management Signalling, etc. VFAT File System: An extension of the FAT file system, which supports long filenames. Also see LFN and FAT32 File System. Virtual Disk: See RAM Disk. Volume Label: A special, hidden file placed on any disk, whose name constitutes a "label" for the entire disk. Volume: See Disk Drive. ;--------------------------------------------------------------------------- !TOPIC 993 Glossary - W !NOINDEX 9724 973A 974B 975C 976D 977E 978F 979G 980H 981I 982K 983L 984M 985N 986O 987P 988R 989S 990T 991U 992V 993W 994X Warm Reboot: The process of restarting the computer with software, or with the keyboard (e.g. by pressing Ctrl-Alt-Del), typically without physically resetting any hardware devices. See also Cold Reboot. White Space Character: A character used to separate arguments on the command line. The white space characters recognized by 4DOS are the space, tab, and comma. Wildcard: A character ("*" or "?") used in a filename to specify the possibility that any single character ("?") or sequence of characters ("*") can occur at that point in the actual name. See also Extended Wildcard. Windows NT: Microsoft's line of non-DOS-based operating systems. Windows NT File System: See NTFS. ;--------------------------------------------------------------------------- !TOPIC 994 Glossary - X !NOINDEX 9724 973A 974B 975C 976D 977E 978F 979G 980H 981I 982K 983L 984M 985N 986O 987P 988R 989S 990T 991U 992V 993W 994X XMS Memory: A software method for accessing extended memory under DOS. XMS memory is not additional memory, but is a software specification only. XMS Swapping: A type of swapping where the transient portion of 4DOS is stored in XMS memory while an application is running. XOR (exclusive OR): A logical combination of two true or false conditions. If both conditions are false or both conditions are true the result is false; if either condition is true and the other is false the result is true. ;--------------------------------------------------------------------------- !TOPIC 703 KSTACK !NOINDEX !TTY Purpose: The memory-resident utility which provides 053Keystack functionality. Format: [LH] [d:\path\]KSTACK [/I] [/U] /I (force Install) /U(ninstall) !TTY Usage Load the KSTACK TSR if you wish to use the 638KEYSTACK command. You will probably want to do this in 109AUTOEXEC.BAT. If KSTACK is not in a directory in your search 649path, you must specify the path to the KSTACK.COM file. If you have upper memory available, you can save about one and a third kilobytes of conventional memory by loading KSTACK high with the 639LH command. Options !INDENT 5 5 0 5 /I: (force Install) Normally KSTACK checks to see whether it is already installed, and refuses to install itself if a previous instance is present in memory. /I overrides this check, allowing you to install a second instance. /U: (Uninstall) Removes a previously installed copy of KSTACK from memory. Note that KSTACK cannot be uninstalled, if another utility that "hooks" interrupts 16h or 2Fh has been loaded after it, or if its keystroke buffer is not empty. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 704 BATCOMP !NOINDEX !TTY Purpose: Compress batch files. See 115Batch File Compression for additional details. Format: [d:\path\]BATCOMP [/Ekkkk /K /O /Q] InputFile [OutputFile] InputFile: A readable batch file to compress OutputFile: The name to give the compressed batch file /E(ncryption key) /O(verwrite) /K (remove comments) /Q(uiet) !TTY Usage BATCOMP is a batch file compressor and optionally allows for simple key-based encryption. It translates batch files into a smaller format which cannot be read or edited. You must specify the full name of the input file, including its extension, on the BATCOMP command line. If you do not specify OutputFile, it defaults to the InputFile name with a .BTM extension. If you specify OutputFile, you must give an extension or the output file will not have one. If OutputFile already exists it will not be overwritten unless /O is used. Even if you use the /O option, BATCOMP will not compress a file into itself. The output file will not be legible, but it will run under the current versions of 4DOS, 0204NT and Take Command. The behavior and performance of the file should be the same as if it were run in its original text form as a .BTM file. Compression is not effective for very small files and may even result in a slightly larger file. Unlike most 4DOS commands, BATCOMP is an external command: it is not built into 4DOS.COM. The shell needs to be able to find the file BATCOMP.EXE in order to run this command. You can arrange this by keeping it in a directory listed in your search path, e.g. by adding your 4DOS directory to your 649path; or by creating an 595alias: alias batcomp=c:\4dos\batcomp The BATCOMP.EXE utility does not support the usual 4DOS file selection features: attribute switches, wildcards, ranges, @file lists, and so on. It is only meant to process one file per invocation. In the unlikely event that you need to use multiple filenames or advanced file selection features with BATCOMP, use it in a 615DO loop or a 626FOR loop. Options !INDENT 5 5 0 5 /E: (Encryption) Specify a key (string) to be used for encryption. The key must be no longer than 4 characters, or will be truncated. /K: (Remove comments) By default, comments (lines starting with "REM" or "::" but not "REM >") are retained in the compressed file. /K forces those lines to be stripped for additional size reduction. /O: (Overwrite) Forces overwriting of any existing OutputFile. /Q: (Quiet) Supresses all progress reports (stdout). Errors (stderr) are still shown. !INDENT 0 ;--------------------------------------------------------------------------- !TOPIC 798 Technical Information for Programmers !NOINDEX !TTY Detecting the 4DOS Prompt 4DOS generates INT 2Fh calls before and after the prompt is displayed to allow TSRs to detect that 4DOS is at the prompt. The calls are: AX D44Eh BX 0 if 4DOS is about to display the prompt; 1 if 4DOS has displayed the prompt and is about to accept keyboard input; or 2 if keyboard input is complete and 4DOS is about to begin processing the line. Any routine intercepting these calls should preserve the SI, DI, BP, SP, DS, ES, and SS registers. Placing Keystrokes Into the Keystack You can put keystrokes into the 4DOS Keystack with an INT 2Fh call. First, you must make a call to check whether KSTACK.COM is loaded: AX D44Fh BX 0 If KSTACK.COM is not loaded, this call will return AX unchanged. If it is loaded, AX will be returned as 44DDh; other registers will be unchanged. Once you have determined that KSTACK.COM is loaded, you can send keystrokes with this call: AX D44Fh BX 1 CX number of words being passed (0 - 255) DS:DX address of the keystroke array On return, if the call succeeded then AX will be 0; if it failed, AX will be non-zero. BX, CX, and DX are destroyed; other registers are preserved. If the call succeeds, subsequent calls to INT 16h functions 0, 1, 10h, or 11h will receive the stacked keystrokes. The keystroke array passed to KSTACK must be an array of words containing the values to return from INT 16h. The high byte of each word is a scan code and the low byte is an ASCII code. Many programs accept keystrokes properly with only the ASCII code, but some require the scan code as well. See 913Key Code and Scan Code Tables for a list of ASCII and scan codes for most U.S. keyboards. To insert a delay in the keystroke sequence, include a word set to FFFFh followed by a word containing the desired delay in clock ticks. Writing Installable Commands An "installable command" is created with a memory-resident program (TSR) which can receive signals from 4DOS and process commands. 4DOS makes every command available to such TSRs before it is executed; if any TSR chooses to execute the command, 4DOS will do no further processing. Otherwise, 4DOS processes the command normally. The 4DOS "Installable Command" interface is compatible with an undocumented interface present in COMMAND.COM for MS-DOS and PC DOS 3.3 and above. This interface is documented more thoroughly in the excellent reference text Undocumented DOS by Schulman et. al., published by Addison Wesley. 4DOS looks for an installable command after alias and variable expansion and redirection, and after checking to see if the command is a drive change, but before checking for an internal or external command. 4DOS first makes an INT 2Fh call to determine whether any TSR loaded will respond to the command, with: AX AE00h BX offset of command line buffer: first byte = maximum length of command line second byte = actual length of command line, not including trailing CR remainder = command line, with a trailing CR CH FFh CL length of command line, not including the command name DX FFFFh SI offset of command name buffer: first byte = length of command name remainder = command name, shifted to upper case and padded with blanks to 11 characters DS segment for command line and command name buffers If the TSR does not recognize the command as its own, it must pass the INT 2Fh along with registers unchanged. If it does recognize the command, it must return 0FFh in AL. The command should not be executed at this point. 4DOS will then make another call (buffer formats are the same as above): AX AE01h BX offset of command line buffer CH 0 CL length of command name DX FFFFh SI offset of command name buffer DS segment for command line and command name buffers If the TSR executes the command line, it must set the command name length at DS:[SI] to 0. If the command name length is not set to 0, 4DOS will attempt to execute the command as an internal or external command. This allows the TSR to return a modified command line to 4DOS by modifying the command line buffer at DS:BX, and leaving the command name length byte at DS:[SI] set to a non-zero value. If the command is executed,the TSR should return the result of the command (zero for normal return or non-zero for an error) in AL. Using DESCRIPT.ION 4DOS uses the file DESCRIPT.ION (or the file named in the 423DescriptionName INI directive) to store file descriptions. This file is created as a hidden file in each subdirectory which has descriptions, and deleted when all descriptions are removed or when all files with descriptions are deleted. If you remove the hidden attribute from the file, 4DOS will not hide it again. Your programs can access DESCRIPT.ION to create, retrieve, or modify file descriptions, and to store other information. DESCRIPT.ION has one line per filename, and is unsorted. Each line is in the following format: filename.ext Description[Other program info]... There is normally one space between the description and filename, but additional spaces may be used in future JP Software products. The filename will be enclosed in double quotes if it contains spaces. The characters following the description allow extension of the description format for use by other programs. They are as follows:  is an ASCII Ctrl-D (04), and marks the end of the description text and the beginning of information for a program other than 4DOS. This symbol can appear multiple times on each line; each occurrence marks the beginning of information for another program. is an identification byte for the program which is using this area of the particular line. If you are writing a program which will store information in DESCRIPT.ION, test it using an ID byte of your own choosing. When you are ready to release the program, contact JP Software and we will provide you with an ID byte value that is not in use by others to the best of our knowledge. Other program info is any text the program wishes to store in its area of the line. The text should relate specifically to the file named on the line. It may not contain the Ctrl-D character, carriage returns, line feeds, or nulls (ASCII 0s). 4DOS will copy, delete, or move all the information on a line in DESCRIPT.ION, including information owned by other programs, when performing the same action on the corresponding file. 4DOS will also change the name if a file is renamed. To support DESCRIPT.ION properly, your program must do the same if it copies, deletes, moves, or renames files. Take care not to remove information which does not belong to your program, or delete lines which contain information for other programs. Your program should be able to handle a line terminated by a CR or LF alone, a CR/LF pair, an EOF (ASCII 26), or the physical end of the file. The lines it creates should be terminated with CR / LF. The line length limit is 4096 bytes; exceeding this limit will cause unpredictable results. If a file is accessed in both LFN and non-LFN environments -- e.g., both under vDosPlus and in MS-DOS mode -- then a file may have two lines in DESCRIPT.ION: one for the long filename, and one for the 8.3 name. Interrupt 2E 4DOS provides full, documented support for the undocumented COMMAND.COM "back door" entry, INT 2E (hex). INT 2E allows applications to call the primary copy of the command processor to execute commands, without loading a secondary shell. INT 2E support is enabled by default. It can be disabled with the !LINE 566FullINT2E = No directive in 4DOS.INI, in which case 4DOS "hooks" INT 2E, but any calls to it are ignored. INT 2E support adds about 100 bytes to the resident size of 4DOS, and applies only to the primary shell (it is ignored in secondary shells). To use INT 2E, set DS:SI to the address of a buffer containing the command, then issue an INT 2E. The buffer format is: First byte Length of the command, not including this byte or the last byte Text bytes The command text Last byte CR (ASCII 13) You must release enough memory for 4DOS to reload its transient portion, and provide about 80 bytes of available stack space for the INT 2E handler to use. INT 2E can not be called from a TSR while 4DOS is running (for example, a TSR popped up at the 4DOS prompt or from within LIST or SELECT), but can be called from within any application or from within a TSR while an application (including the 4DOS HELP system) is running. INT 2E can invoke any 4DOS command including an alias, an internal command, an external command, or a batch file. All changes to 4DOS data (such as aliases, environment variables, and SETDOS settings) which are made by a command executed via INT 2E calls will affect the primary shell, and the environment passed to a program called via INT 2E will be a copy of the primary shell's environment. INT 2E uses the same internal stack as the primary shell. If a complex command is used in the primary shell to start a program which eventually issues an INT 2E, the additional stack space required by commands executed through INT 2E may (in rare circumstances) cause a stack overflow. If this occurs, use the 574StackSize directive in 4DOS.INI to increase 4DOS's internal stack space. INT 2E also uses the same batch file "stack" as the primary shell. This means that if INT 2E is used to execute a batch file, this batch file is considered "nested" within any batch file(s) used in the primary shell to start the program which issued the INT 2E. This may cause batch nesting errors from within the INT 2E call which would not occur if the same command were executed at the prompt. On return from INT 2E, all registers will be destroyed except SS and SP. AX will be set as follows: FFFFh An error occurred before processing the command: not enough memory was available, INT 2E was called from a TSR, or another error made it impossible to handle the interrupt. 0 The command was processed without error. > 0 There was an error in processing the command. AX is the error number, equivalent to the %_? value from an internal command or the %? value from an external command. If a batch file is run, the value will be the error level returned by the batch file (via QUIT n or CANCEL n) or the last command within it. If an alias is run the value will be the exit code returned by the last command in the alias. !TTY Saving This Topic To save this topic as a text file, exit the help system and type: 4help tech /? > c:\4dostech.txt (You can substitute any legal filename for C:\4DOSTECH.TXT.) ;--------------------------------------------------------------------------- !TOPIC 920 An Embarrassment of Riches !NOINDEX 4DOS provides a wealth of features, and there is often more than one way to achieve an objective. Often you will discover different features which seem to do the same thing. There's a reason for this apparent redundancy. There may an elegant approach which works with internal commands, and a clumsier method that works with external programs. Or there may be a sophisticated multiline structure for use in batch files, and a more basic one-line approach for use in aliases and at the prompt. This section will guide you through some of the 4DOS's more easily confused features. 929Command log versus history log 922Directory history versus directory stack 923DO UNTIL versus DO WHILE 924Double quotes versus back-quotes 925EXCEPT versus exclusion ranges 926FOR versus DO 927GLOBAL, /S switch, and FOR /R 928IF versus IFF ;// 10XXInclude lists versus multiple filenames 930QUIT versus CANCEL 931SWITCH versus IFF / ELSEIFF / ELSE ;--------------------------------------------------------------------------- !TOPIC 921 =920 Riches !NOINDEX ;--------------------------------------------------------------------------- !TOPIC 922 Directory history, Directory stack !NOINDEX The directory history remembers recently-visited directories. It is updated whenever you change locations via drive change commands, 601CD, 688CHDIR, or 602CDD, 039automatic directory changes, 653PUSHD or 651POPD, or the history window itself. The directory history is a free-form list: you can select any directory in the list through a 040popup window, accessed with a single keystroke. You can save, reload or view the directory history with the 613DIRHISTORY command. The handy 602CDD - command revisits the location most recently recorded, and is worth assigning to a keystroke macro. The directory stack has a more formal structure. It is only affected by the 653PUSHD and 651POPD commands. Locations on the directory stack are revisited in reverse order -- the last directory pushed will be the next one popped. There is no keystroke popup window for the directory stack, and no mechanism for saving and reloading it. The 614DIRS command dumps the current contents of the stack to standard output. Use the interactive, free-form directory history as a quick and convenient way of navigating between directories while working at the prompt. The structured, command-driven directory stack is ideal for use in batch files and aliases, where changing to a specific drive and directory, and later returning to the original location, is a common task. ;--------------------------------------------------------------------------- !TOPIC 923 DO UNTIL versus DO WHILE !NOINDEX A 615DO UNTIL loop is an exit-condition loop: the condition is tested after executing the commands between DO and ENDDO. If the condition is false after the commands in the loop have been executed the first time, they will be repeated until the condition becomes true (or a LEAVE is executed.) A 615DO WHILE loop is an entry-condition loop: the condition is tested before executing the commands between DO and ENDDO. If the condition is false, the body of the loop is not executed. Otherwise, the commands in the loop will be repeated while the condition remains true (or until a LEAVE command is executed.) Note that the body of an UNTIL loop will always be executed at least once, but a WHILE loop may be skipped altogether. Also note the reversed logic: an UNTIL loop ends when the specified condition becomes true, but a WHILE loop ends when the condition becomes false. Use DO UNTIL for a block of commands which must be performed at least once (and possibly repeated); use DO WHILE for a block which may or may not need to be executed at all. ;--------------------------------------------------------------------------- !TOPIC 924 Double quotes versus back-quotes !NOINDEX Double quotes suppress the special meaning of some, but not all, special characters. Between double quotes, the 041command separator, 051redirection and 052piping operators, white space, and 084conditional operators all are treated as ordinary characters. Percent signs do not lose their meaning -- variable expansion is performed normally between double quotes. The 086escape character is not affected either. Double quotes are retained throughout the parsing process; when the command is executed, it will see the double quotes. Double quotes are typically used for filenames or other arguments which may contain spaces or other special characters. Back-quotes are the more potent form of quoting, and so are sometimes called strong quotes. Between back-quotes, all special characters including percent signs and escapes are treated as normal characters. (There is one exception: you can escape a back-quote within a back-quoted string.) No variable expansion is performed, and the back-quotes themselves will be stripped out of the string before the command is executed. Back-quotes have a more specialized purpose than double quotes. When you define 101aliases or functions using the 595ALIAS or 696FUNCTION commands, you will often want to store references to variables, functions, and parameters, command separators, redirection operators, and so forth in the definition. Using back-quotes prevents these special characters from being expanded at the time the alias or function is defined. Since the back-quotes are removed from the command line before the command is executed, they will not be stored in the alias or function definition. When you later use the alias or function which you have created, any special characters stored in it will be expanded or handled normally. In short, back-quotes are used to delay variable expansion and the handling of special characters. See 118Argument Quoting for more details on how the two kinds of quoting work in 4DOS. ;--------------------------------------------------------------------------- !TOPIC 925 EXCEPT versus exclusion ranges !NOINDEX All 4DOS internal file-handling commands support 078exclusion ranges to prevent specified files or directories from being processed. This support is straightforward and robust, and should be used instead of EXCEPT wherever possible -- with all internal commands. 623EXCEPT is a clumsier addition for the benefit of external commands. It simply sets the hidden 946attribute of the specified files before launching the specified program, and clears it afterwards. This approach has some drawbacks: programs which ignore the hidden attribute will not be affected by EXCEPT; the original state of the excluded files' Hidden attributes will be lost; if the external program crashes, EXCEPT will not have the opportunity to clear the attributes it has set. Use EXCEPT only for external programs which lack a file-exclusion capability. Even then, you may be better off applying an exclusion range to a 626FOR loop. copy /[!*.old *.bad] c:\working\*.* z:\backups\ except ( *.ion ) crc.exe *.* >! r:\chksums.txt for /[!*.ion] %i in ( *.* ) crc.exe "%i" >>! r:\chksums.txt There is one rare circumstance where you will need to use EXCEPT instead of an exclusion range. EXCEPT can take an 057@file list as an argument. If you have a file containing a list of files to be excluded, you must use EXCEPT even for internal commands (and watch out for commands which ignore the hidden attribute!) Fortunately this situation is unusual. ;--------------------------------------------------------------------------- !TOPIC 926 FOR versus DO !NOINDEX 626FOR and 615DO offer similar functionality: repeating commands for all files matching a wildcard or a set of wildcards, or for all lines in a text file; repeating a loop a set number of times; incrementing or decrementing a numeric variable. Often you can use either command for any of these tasks. DO is a multiline structure which can only be used in 102batch files. You can have any number of lines between the DO and its corresponding ENDDO. You can also use complex flow-control commands like 634IFF and 669SWITCH within a DO / ENDDO block, or even branch within a DO block using 630GOTO /I. The complexity of the code between DO and ENDDO is limited only by the 574stack size. You can restart the loop at any point using the ITERATE command, or exit at any point with LEAVE. Since DO is a multiline construct, you can (and should) use indentation to indicate structure. DO is cleaner than FOR and is usually the better choice in a batch file, unless you need to recurse into subdirectories. FOR is inherently a single-line command. You might use 085parentheses or 086escapes to spread a FOR command over more than one line, but all the lines will ultimately be collected together in the input buffer. This fact limits the complexity of a FOR loop. (You can work around this limitation in a batch file by having FOR call a subroutine using 629GOSUB.) Unlike DO, FOR can be used at the prompt or in an 101alias. It also offers a /R option which DO lacks. At the prompt or in an alias, FOR is your only option. In a batch file, use FOR if recursion into subdirectories is needed, or if the loop is very simple (one or two commands); otherwise DO is probably preferable. ;--------------------------------------------------------------------------- !TOPIC 927 GLOBAL, /S switch, and FOR /R !NOINDEX 4DOS provides three different methods of applying commands to nested subdirectories. The first is /S. Most internal file-handling commands use /S to visit subdirectories recursively. (In the 626FOR command, this option is called /R instead for compatibility with CMD.EXE.) When you need to use one command and have it affect all subdirectories below a certain location, the /S switch is usually the simplest way to go. The following internal commands support /S to recurse into subdirectories: 596ATTRIB, 606COPY, 609DEL/691ERASE, 612DIR, 625FFIND, 646MOVE, and 658REN/695RENAME. Many external commands have a similar ability. In some cases it will also be called /S; XCOPY, for example, has a /S. Other programs may call it something different; for instance, the popular archiver PKZIP uses -r for this purpose. See your external program's documentation to learn whether it has a similar option. If you need to use a command which does not offer /S or an equivalent ability, your second option is the 628GLOBAL command. GLOBAL is somewhat clumsier than /S, but it can be used with commands which don't support /S, or with multiple commands by using 085command grouping. GLOBAL works by changing the current directory to each nested subdirectory in turn, and running the specified command (or command group) once in each location. When GLOBAL has run out of subdirectories to visit, the original current working directory is restored. One consequence of this design is that you must first change to the desired location using 602CDD, 653PUSHD or similar before using GLOBAL. Another consequence is that you should not specify a path to the command's arguments. Write the command to operate on files in the current directory: rem Pack all .EXE files in C:\TEST\PACKTREE and below with UPX: pushd c:\test\packtree global /i upx --best *.exe popd Before using GLOBAL study its 628options carefully, particularly /I. If you do not specify /I and the command returns a nonzero exit code, GLOBAL will abort without visiting further subdirectories. GLOBAL is a rather odd command, and it doesn't support the usual rich set of 4DOS file-selection options. The third way of running a command in nested subdirectories is to use a 626FOR /R loop. FOR is more complicated to use than GLOBAL, but it supports all of 4DOS's file-selection features. You can use advanced 073wildcards, filter by 076date, 077time, 075size, 056attributes, or 056descriptions, use 078exclusion ranges, and so on. Like GLOBAL, FOR can be used to control external commands or command groups. Unlike GLOBAL, there is no changing of directories; the FOR index returns qualified filenames which will be passed to the specified command. You can massage the FOR index using variable functions if need be. In summary: To run one command in nested subdirectories, use that command's /S option if it has one; this is the easiest method. For commands which don't support /S or for multiple commands, use either GLOBAL or FOR /R. GLOBAL is the easier to use, but you must switch to the topmost directory before using it. GLOBAL doesn't support advanced wildcards, ranges, and so on. FOR /R is the more sophisticated alternative. It requires more typing, but supports all of 4DOS's file-selection 071features. In many cases, the choice between GLOBAL and FOR /R is a matter of taste. del "d:\my documents\memos\*.old" /s cdd a:\ global /i describe descript.ion "4DOS file descriptions" for /a: /r a:\ %i in ( *.ion ) describe %i "4DOS file descriptions" ;--------------------------------------------------------------------------- !TOPIC 928 IF versus IFF !NOINDEX 633IF is inherently a single-line command. You can use 085parentheses or 086escapes to spread an IF command over more than one line, but all the lines will ultimately be collected together in the input buffer. This limits the complexity of an IF command. By contrast, 634IFF was designed to be a multiline structure. You can have any number of lines between the IFF, ELSEIFF, ELSE, and ENDIFF commands. You can easily put complex flow-control commands like 669SWITCH, 615DO, or another IFF within an IFF block, or even branch within an IFF block using 630GOTO /I. The complexity of the code is limited only by your 574stack size. Since IFF is a multiline construct, you can (and should) use indentation to show structure. IF is often the easier command to use for very simple conditionals: only one or two commands to be conditionally executed, no ELSE clause. For anything more complex, IFF will be the better option. ;--------------------------------------------------------------------------- !TOPIC 929 Command log versus history log !NOINDEX The command log, controlled by 643LOG without the /H option, records all commands executed, whether typed at the command line or read in from a batch file. The lines are written to the log file after expansion of variables and aliases. The history log, 643LOG /H, records only commands entered at the prompt, not those read in from batch files. The lines are stored as typed, and do not reflect expansion of variables and aliases. Think of the history log as a way to track what the user does. It might be be particularly useful if more than one person uses the same computer. The command log, on the other hand, is more a record of what 4DOS itself does. You can use it while debugging troublesome batch files or aliases to see what commands were actually executed. ;--------------------------------------------------------------------------- !TOPIC 930 QUIT versus CANCEL !NOINDEX 654QUIT terminates only the current batch file; 600CANCEL aborts all batch files in the current shell and returns to the prompt. CANCEL is the more C-rious of the two. Use QUIT for an early exit from a 599CALLed batch file; use CANCEL when a serious error makes further batch processing problematic. iff not exist "%dir\*.tag" then echo No .TAG files to process in %dir quit else copy "%dir\*.tag" "%dir\*.old" for %i in ( "%dir\*.tag" ) process.exe /u "%i" endiff if %@ready[a:] == 0 ( echoerr Drive A: not ready! %+ cancel ) ;--------------------------------------------------------------------------- !TOPIC 931 SWITCH versus IFF / ELSEIFF / ELSE !NOINDEX 669SWITCH tests one expression which may take several specific values, and branches accordingly. It's elegant and easy to read, but can only check one expression. An 634IFF / ELSEIFF / ELSE structure, on the other hand, is more complex but also more flexible. It can test multiple conditions at once, or predicate one test on another. IFF can also be used to test inequalities and ranges, while SWITCH can only compare against specific values. In general, where there is only one expression to test and a few known values which it can take, the simpler SWITCH is preferred. Otherwise, use IFF. switch %_dow case thu echo Collect timesheets today case fri echo Issue paychecks today case sat .or. sun echo Overtime rules in effect today default echo Normal workday endswitch iff %_dow == mon .and. %_day lt 8 then echo First Monday of the month: Rent is due! endiff ;--------------------------------------------------------------------------- ;End of file