vDOSPlus/4DOS/4DOS.TXT

;---------------------------------------------------------------------------
; 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 ¿JP 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
<command name]> (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
<Enter> 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 <Enter> 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 <F9> 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 <F9>
     2   c:\> edit \data\
     3   c:\> edit \data\f <F9>
     4   c:\> edit \data\frank.doc <F9>
     5   c:\> edit \data\finance\
     6   c:\> edit \data\finance\map <F9>
     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 [<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         <DIR>    .
     12-08-2002  12:17         <DIR>    ..
      1-04-2003  16:21         <DIR>    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\*.*

     .           <DIR>     12-08-02  12:17 C:\4DOS
     ..          <DIR>     12-08-02  12:17 C:\
     TEST         <DIR>     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
"<DIR>" 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 "<D>" 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 <ESC>[K (where <ESC> 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 <Ctrl-X>f on the command line
(where <Ctrl-X> is the ASCII Ctrl-X character, decimal value 24) is
translated to a form feed, and is not treated as the literal characters
"<Ctrl-X>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[<ID>Other program info]...<CR>

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.

<ID> 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