  -85-


  CHAPTER 4 / ALIASES AND BATCH FILES


  This chapter introduces two of the most powerful features of 4DOS,
  4OS2, and 4NT:  aliases and batch files.  It also discusses the
  environment (a list of information available to all programs),
  along with the command processor's internal variables and variable
  functions.  The discussion of the environment, variables, and
  variable functions is included in this chapter because they are
  most often used in aliases and batch files.


  Aliases

       Much of the power of 4DOS, 4OS2, and 4NT comes together in
       aliases, which give you the ability to create your own
       commands.  An alias is a name that you select for a command
       or group of commands.  Simple aliases substitute a new name
       for an existing command.  More complex aliases can redefine
       the default settings of internal or external commands,
       operate as very fast in-memory batch files, and perform
       commands based on the results of other commands.

       This section of the manual will show you some examples of the
       power of aliases.  See the ALIAS command (page 178) 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
       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 DIR command can sort a directory in various
       ways.  You can create an alias called DE that means "sort the
       directory by filename extension, and pause after each page
       while displaying it" like this:

            c:\> alias de = dir /oe /p

       Aliases can be used to execute sequences of commands as well.
       The following command creates an alias called 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
  -86-

       alias contains multiple commands, environment variables,
       parameters (see below), redirection, or piping.  See the
       ALIAS command for full details.  Also, please note that
       throughout this section we use the 4DOS command separator, a
       caret [^], to separate multiple commands.  If you are using
       4OS2 or 4NT, substitute an ampersand [&] for the caret in the
       examples.

       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, the command processor will
       execute the PUSHD 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 POPD command, and return to the prompt.

       You can use aliases to change the default options for both
       internal commands and external commands.  Suppose that you
       always want the DEL command to prompt before it erases a
       file:

            c:\> alias del = *del /p

       An asterisk [*] is used in front of the second "del" to show
       that it is the name of an internal command, not an alias.
       See page 180 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 LIST 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
  -87-

       naming the alias with an at sign [@] followed by a key name.
       After you enter this next example, you will see a 2-column
       directory with paging whenever you press Shift-F5, then
       Enter:

            c:\> alias @Shift-F5 = *dir /2/p

       This alias will put the DIR command on the command line when
       you press Shift-F5, then wait for you to enter file names or
       additional switches.  You must press Enter when you are ready
       to execute the command.  To execute the command immediately,
       without displaying it on the command line or waiting for you
       to press Enter, use two at signs at the start of the alias
       name:

            c:\> alias @@Shift-F5 = *dir /2/p

       The next example clears the 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.  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 ALIAS command.

       Your copy of 4DOS, 4OS2, or 4NT  includes a sample alias file
       called ALIASES which contains several useful aliases and
       demonstrates many alias techniques.  Also, see the ALIAS and
       UNALIAS commands on pages 178 and 397 for more information
       and examples.  See page 95 for tips about using aliases
       inside your batch files.
  -88-

  Batch Files

       A batch file is a file that contains a list of commands to
       execute.  4DOS, 4OS2, and 4NT read and interpret each line as
       if it had been typed at the keyboard.  Like aliases, batch
       files are handy for automating computing tasks.  Unlike
       aliases, batch files can be as long as you wish.  Batch files
       take up separate disk space for each file, and can't usually
       execute quite as quickly as aliases, since they must be read
       from the disk.


       .BAT, .CMD, and .BTM Files

       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 under DOS.

       The batch file's extension determines its mode.  Files with a
       .BAT extension (in 4DOS and 4NT), or a .CMD extension (in
       4OS2 and 4NT) are run in the slower, traditional mode.  Files
       with a .BTM extension are run in the faster, more efficient
       mode.  You can change the execution mode inside a batch file
       with the LOADBTM command (see page 313).

       4NT and 4OS2 can handle .BTM files of any length.  Under
       4DOS, .BTM files must be less than 64K (65536) bytes long.

4NT  ! Using .BAT Files Under 4NT

       In most cases under 4NT your batch files will be stored as
       .CMD or .BTM files.  However, you may also choose to use some
       .BAT files, especially if you are moving from DOS to Windows
       NT.  If you do, you you need to be aware of the way 4NT
       executes .BAT files, which is slightly different from the
       method used by CMD.EXE.

       CMD.EXE passes all .BAT files to Windows NT's DOS command
       processor, typically COMMAND.COM, for execution (yes, there
       is a DOS command processor in Windows NT!).  COMMAND.COM
       handles a few DOS-related commands, but passes most internal
       commands to a second copy of CMD.EXE so that they are
       executed in the Windows NT environment.  This convoluted
       system allows you to load memory-resident DOS programs
       (TSRs), and run other programs which use them, all from the
       same .BAT file.  However, it reduces performance for all .BAT
       files in order to support those rare files which load DOS
       TSRs under Windows NT.

       4NT does not use this system; it executes .BAT files in the
       normal way, just like .CMD and .BTM files.  This works better
  -89-

       for most files, but may render DOS TSRs loaded from a .BAT
       file ineffective because other commands in the file are not
       executed in DOS-based environment.

       In most cases this difference will not affect your .BAT
       files, because you will not be loading DOS TSRs in Windows
       NT.  If you do need to load TSRs from .BAT files, we
       recommend that you obtain a copy of our DOS command
       processor, 4DOS, start it from your Windows NT desktop, and
       run the .BAT files from a 4DOS session (you could also use a
       CMD.EXE session, but of course the .BAT files then cannot use
       4DOS or 4NT features).  While we do not generally recommend
       using 4DOS under Windows NT, it can work well in this
       specific situation.


       Echoing

       By default, each line in a batch file is displayed or
       "echoed" as it is executed.  You can change this behavior, if
       you want, in several different ways:

            Any batch file line that begins with an [@] symbol will
            not be displayed.

            The display can be turned off and on within a batch file
            with the ECHO OFF and ECHO ON commands.

            The default setting can be changed with the SETDOS /V
            command (see page 368), on the Options 1 page of the
            OPTION dialogs (see page 329), or the BatchEcho
            directive in the .INI file (see page 154).

       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

       Your command processor also has a command line echo that is
       unrelated to the batch file echo setting.  See the ECHO
       command on page 249 for details about both settings.


       Batch File Parameters

       Like aliases and application programs, batch files can
       examine the command line that is used to invoke them.  The
       command tail (everything on the command line after the batch
       file name) is separated into individual parameters (also
       called arguments or batch variables) by scanning for the
       spaces, tabs, and commas that separate the parameters.  A
       batch file can work with the individual parameters or with
       the command tail as a whole.

       These parameters are numbered from %1 to %127.  %1 refers to
       the first parameter on the command line, %2 to the second,
  -90-

       and so on.  It is up to the batch file to determine the
       meaning of each parameter.  You can use quotation marks to
       pass spaces, tabs, commas, and other special characters in a
       batch file parameter; see page 140 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 in 4DOS %n& contains the complete command-line
       tail starting with argument number "n" (for example, %3&
       means the third parameter and all those after it).  The
       default value of "n" is 1, so %& contains the entire command
       tail.  The values of these special parameters will change if
       you use the SHIFT command (see page 371).

4OS2,  By default, 4OS2 and 4NT use a dollar sign [$] instead of an
4NT    ampersand [&] to indicate the remainder of the command tail.
       For example, %$ means all the parameters, and %2$ means the
       second parameter and all those after it.  If you want to
       share batch files or aliases between 4DOS and these command
       processors, see page 136 for information on selecting
       compatible parameter characters for all products.

       For example, if your batch file interprets the first argument
       as a subdirectory name then the following line would move to
       the specified directory:

            cd %1

       A friendlier batch file would check to make sure the
       directory exists and take some special action if it doesn't:

            iff isdir %1 then ^ cd %1
            else ^ echo Subdirectory %1 does not exist! ^ quit
            endiff

       (see the IF and IFF commands on pages 284 and 291).


       Using Environment Variables

       Batch files can also use environment variables, internal
       variables, and variable functions.  See pages 110 - 136 for a
       complete list of the internal variables and variable
       functions available.  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
  -91-

       (including date and time arithmetic), manipulate strings and
       substrings, extract parts of a filename, and read and write
       files.

       To create temporary variables for use inside a batch file,
       just use the SET command to store the information you want in
       an environment variable.  Pick a variable name that isn't
       likely to be in use by some other program (for example, PATH
       would be a bad choice), and use the UNSET command (page 399)
       to remove these variables from the environment at the end of
       your batch file.  You can use SETLOCAL (page 370) and
       ENDLOCAL (page 252) to create a "local" environment so that
       the original environment will be restored when your batch
       file is finished.

       Environment variables used in a batch file may contain either
       numbers or text.  It is up to you to keep track of what's in
       each variable and use it appropriately; if you don't (for
       example, if you use %@EVAL to add a number to a text string),
       you'll get an error message.


       Batch File Commands

       Several 4DOS, 4OS2, and 4NT commands are particularly suited
       to batch file processing.  Each command is explained in
       detail in the Command Reference section of this manual,
       beginning on page 170.  Here is a list of some of the
       commands you might find most useful:

            ACTIVATE activates another window (4OS2 only).

            BEEP produces a sound of any pitch and duration through
            the computer's speaker.

            CALL executes one batch file from within another.

            CANCEL terminates all batch file processing.

            CLS and COLOR set the screen display colors.

            DO starts a loop.  The loop can be based on a counter,
            or on a conditional test like those used in IF and IFF.

            DRAWBOX draws a box on the screen.

            DRAWHLINE and DRAWVLINE draw horizontal and vertical
            lines on the screen.

            ECHO and ECHOS print text on the screen (the text can
            also be redirected to a file or device).  ECHOERR and
            ECHOSERR print text to the standard error device.

            GOSUB executes a subroutine inside a batch file.  The
            RETURN command terminates the subroutine.

            GOTO branches to a different location in the batch file.
  -92-

            FOR executes commands for each file that matches a set
            of wildcards, or each entry in a list.

            IF and IFF execute commands based on a test of string or
            numeric values, program exit codes, or other conditions.

            INKEY and INPUT collect keyboard input from the user and
            store it in environment variables.

            KEYSTACK sends keystrokes to applications  (4DOS and
            4OS2 only).

            LOADBTM changes the batch file operating mode.

            ON initializes error handling for Ctrl-C / Ctrl-Break,
            or for program and command errors.

            PAUSE displays a message and waits for the user to press
            a key.

            QUIT ends the current batch file and optionally returns
            an exit code.

            REM places a remark in a batch file.

            SCREEN positions the cursor on the screen and optionally
            prints a message at the new location.

            SCRPUT displays a message in color.

            SETLOCAL saves the current disk drive, default
            directory, environment, alias list, and special
            character settings.  ENDLOCAL restores the settings that
            were saved.

            SHIFT changes the numbering of the batch file
            parameters.

            START starts another session or window in certain
            multitasking environments.

            SWITCH selects a group of statements to execute based on
            the value of a variable.

            TEXT displays a block of text.  ENDTEXT ends the block.

            TIMER starts or reads a stopwatch.

            TITLE changes the 4OS2 window title.

            VSCRPUT displays a vertical message in color.

       These commands, along with the internal variables and
       variable functions, make the enhanced batch file language
       extremely powerful.  Your copy of 4DOS, 4OS2, or 4NT includes
       a sample batch file, in the file EXAMPLES.BTM, that
  -93-

       demonstrates some of the many things you can do with batch
       files.


       Interrupting a Batch File

       You can usually interrupt a batch file by pressing Ctrl-C or
       Ctrl-Break.  Whether and when these keystrokes are recognized
       will depend on whether the command processor or an
       application program is running, how the application (if any)
       was written, whether BREAK is ON or OFF under DOS (see page
       194), and whether the ON BREAK command is in use (see page
       327).

       If 4DOS, 4OS2, or 4NT detects a Ctrl-C or Ctrl-Break (and ON
       BREAK is not in use), it will display a prompt, for example:

            Cancel batch job C:\CHARGE.BTM ? (Y/N/A) :

       Enter N to continue, Y to terminate the current batch file
       and continue with any batch file which called it, or A to end
       all batch file processing regardless of the batch file
       nesting level.  Answering Y is similar to the QUIT command
       (page 341); answering A is similar to the CANCEL command
       (page 196).


       Automatic Batch Files

       4DOS, 4OS2, and 4NT support "automatic" batch files, files
       that run without your intervention, as long as the command
       processor can find them.

       Each time 4DOS, 4OS2, or 4NT starts as either a primary or a
       secondary shell, it looks for an automatic batch file called
       4START.BTM, 4START.BAT (for 4DOS), or 4START.CMD (for 4OS2
       and 4NT).  If the 4START batch file is not in the same
       directory as your command processor itself, you should use
       the Startup page of the OPTION dialogs or the 4StartPath
       directive in your .INI file (see page 148) to specify its
       location.  4START is optional, so the command processor 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, LOG the start of a shell, or
       put other special startup or configuration commands.  Under
       4OS2 and 4NT, it is one way to set aliases and environment
       variables (under 4DOS, these are normally set in
       AUTOEXEC.BAT).

    ## With the exception of some 4DOS initialization switches, the
       entire startup command line passed to the command processor
       is available to 4START via batch 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
  -94-

       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 [%&]

4DOS   Whenever it is started as a primary shell, 4DOS runs
       AUTOEXEC.BAT immediately after 4START.  On a DOS system,
       AUTOEXEC.BAT runs each time the computer boots up.  (If
       COMMAND.COM cannot find AUTOEXEC.BAT, it asks you for the
       time and date.  4DOS skips that step and immediately displays
       a prompt.)

       Normally, AUTOEXEC.BAT must be in the root directory of the
       boot drive.  You can store it in a different location (and
       even give it a different name) by using the 4DOS.INI
       directive AutoExecPath (see page 148).  You can also pass
       parameters to AUTOEXEC.BAT using the AutoExecParms directive
       in 4DOS.INI.

       4OS2 and 4NT do not execute AUTOEXEC.BAT.

       Whenever a 4DOS, 4OS2, or 4NT shell ends, it runs an
       automatic batch file called 4EXIT.BTM, 4EXIT.BAT (for 4DOS),
       or 4EXIT.CMD (for 4OS2 and 4NT).  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 LOG the end of the shell.

       Under 4DOS, 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, 4OS2, or 4NT starts, including when running
       a pipe in 4OS2 or 4NT (see page 61), or a transient copy of
       the command processor started with the /C startup option (see
       your Introduction and Installation Guide for details on /C).

       For example, suppose you enter a 4OS2 or 4NT command line
       like this, which uses a pipe:

            [c:\data] myprog | sort > out.txt

       Normally this command would create the output file
       C:\DATA\OUT.TXT.  However, if you have a 4START file which
       changes to a different directory, the output file will be
       written there -- not in C:\DATA.

       This is because both 4OS2 and 4NT start a second command
       processor session to run the commands on the right hand side
  -95-

       of the pipe, and that new copy runs 4START before processing
       the commands from the pipe.  If 4START changes directories,
       the command from the pipe will be executed in the new
       directory.  (This is not a problem in 4DOS because 4DOS does
       not start a second command processor session to run a pipe.)

       The same problem can occur if you use a transient session
       started with /C to run an individual command, then exit --
       the session will execute in the directory set by 4START, not
       the directory in which it was originally started.  For
       example, suppose you set up a Windows or OS/2 desktop object
       with a command line like this, which starts a transient
       session:

            Command:            d:\4dos\4dos.com /c list myfile.txt
            Working Directory:  c:\data

       Normally this command would LIST the file C:\DATA\MYFILE.TXT.
       However, if 4START changes to a different directory, the
       command processor will look for MYFILE.TXT there -- not in
       C:\DATA.

       Similarly, any changes to environment variables or other
       settings in 4START will affect all copies of the command
       processor, including those used for pipes and transient
       sessions.

       You can work around these potential problems with the IF or
       IFF command and the internal variables _PIPE (page 117; only
       available in 4OS2 and 4NT) and _TRANSIENT (page 117).  For
       example, to skip all 4START processing when running in a pipe
       or transient session, you could use a command like this at
       the beginning of 4START:

            if %_pipe != 0 .or. %_transient != 0 quit


   ##  Detecting 4DOS, 4OS2, or 4NT

       From a batch file, you can determine if 4DOS, 4OS2, 4NT, or
       Take Command is loaded by testing for the variable function
       @EVAL, with a test like this:

            if "%@eval[2+2]" == "4" echo 4DOS is loaded!

       This test can never succeed in COMMAND.COM or CMD.EXE.  Other
       variable functions could be used for the same purpose.


   ##  Using Aliases in Batch Files

       One way to simplify batch file programming is to use aliases
       to hide unnecessary detail inside a batch file.  For example,
       suppose you want a batch file to check for certain errors,
       and display a message and exit if one is encountered.  This
       example shows one way to do so (the command separator and
  -96-

       parameter characters used here are those for 4DOS; change
       these characters appropriately if you are using 4OS2 or 4NT):

            setlocal
            unalias *
            alias error `echo. ^ echo ERROR: %& ^ goto dispmenu`
            alias fatalerror `echo. ^ echo FATAL ERROR: %& ^ quit`
            alias in `pushd %1 ^ %2& ^ popd`
            if not exist setup.btm fatalerror Missing setup file!
            call setup.btm
            cls
            :dispmenu
            text


                      1. Word Processing
                      2. Spreadsheet
                      3. Communications
                      4. Exit
            endtext
            echo.
            inkey Enter your choice:  %%userchoice
            switch %userchoice
            case 1
               input Enter the file name:  %%fname
               if not exist fname error File does not exist
               in d:\letters c:\wp60\wp.exe
            case 2
               in d:\finance c:\quattro\q.exe
            case 3
               in d:\comm c:\comsw\pcplus.exe
            case 4
               goto done
            default
              error Invalid choice, try again
            endswitch
            goto dispmenu
            :done
            endlocal

       The first alias, ERROR, simply displays an error message and
       jumps to the label DISPMENU to redisplay the menu.  The "%&"
       in the second ECHO command displays all the text passed to
       ERROR as the content of the message.  The similar FATALERROR
       alias displays the message, then exits the batch file.

       The last alias, IN, expects 2 or more command-line arguments.
       It uses the first as a new working directory and changes to
       that directory with a PUSHD command.  The rest of the command
       line is interpreted as another command plus possible command
       line parameters, which the alias executes.  This alias is
       used here to switch to a directory, run an application, and
       switch back.  It could also be used from the command line.

       The following lines print a menu on the screen and then get a
       keystroke from the user and store the keystroke in an
       environment variable called userchoice.  Then the SWITCH
  -97-

       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 CD
       to CDD and you aren't expecting this, your file may not work
       as you intended.  There are two ways to address this problem.

       First, you can use SETLOCAL, ENDLOCAL, and UNALIAS to clear
       out aliases before your batch file starts and restore them at
       the end, as we did in the previous example.  Remember that
       SETLOCAL and ENDLOCAL will save and restore not only the
       aliases but also the environment, the current drive and
       directory, and various special characters (see page 370 for
       details).

       If this method isn't appropriate or necessary for the batch
       file you're working on, you can also use an asterisk [*]
       before the name of any command.  The asterisk means the
       command that follows it should not be interpreted as an
       alias.  For example the following command redirects a list of
       file names to the file FILELIST:

            dir /b > filelist

       However, if the user has redefined DIR with an alias this
       command may not do what you want.  To get around this just
       use:

            *dir /b > filelist

       The same can be done for any command in your batch file.  If
       you use the asterisk, it will disable alias processing, and
       the rest of the command will be processed normally as an
       internal command, external command, or batch file.  Using an
       asterisk before a command will work whether or not there is
       actually an alias defined with the same name as the command.
       If there is no alias with that name, the asterisk will be
       ignored and the command will be processed as if the asterisk
       wasn't there.


   ##  Debugging Batch Files

       4DOS, 4OS2, and 4NT include a built-in batch file debugger,
       invoked with the SETDOS /Y1 command (see page 369).  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 LIST
       command to display the contents of any file.
  -98-

       To start the debugger, insert a SETDOS /Y1 command at the
       beginning of the portion of the batch file you want to debug,
       and a SETDOS /Y0 command at the end.  You can also invoke
       SETDOS /Y1 from the prompt, but because the debugger is
       automatically turned off whenever the command processor
       returns to the prompt, you must enter the SETDOS command and
       the batch file name on the same line, for example:

            c:\> setdos /y1 ^ mybatch.btm

       If you use the debugger regularly you may want to define a
       simple alias to invoke it, for example (in 4OS2 and 4NT, use
       %$ rather than %&):

            c:\> alias trace `setdos /y1 ^ %&`

       This alias simply enables the debugger, then runs whatever
       command is passed to it.  You can use the alias to debug a
       batch file with a command like this:

            c:\> trace mybatch.btm

       When the debugger is running you can control its behavior
       with keystrokes.  Debugging continues after each keystroke
       unless otherwise noted:

            T(race), Enter, or F8    Execute the current command.
                                If it calls a subroutine with GOSUB,
                                or another batch file with CALL,
                                single-step into the called
                                subroutine or batch file.

            S(tep) or F10       Execute the current command, but
                                execute any subroutine or CALLed
                                batch file without single-stepping.
            J(ump)              Skip the current command and proceed
                                to the next command.
            X (Expand)          Display the next command to be
                                executed, after expansion of aliases
                                and environment variables.
            L(ist)              Prompt for a file name and then view
                                the file with the LIST command.
            V(ariables)         Open a popup window to display the
                                current environment, in alphabetical
                                order.
            A(liases)           Open a popup window to display the
                                current aliases, in alphabetical
                                order.
            O(ff) or Esc        Turn off the debugger and continue
                                with the remainder of the batch
                                file.
            Q(uit)              Quit the debugger and the current
                                batch file, without executing the
                                remainder of the file.

       The debugger highlights each line of the batch file as it is
       executed.  It executes the commands on the line one at a
  -99-

       time, so when a line contains more than one command, the
       highlight will not move as each command is executed.  To see
       the individual commands, use the X key to expand each command
       before it is executed.

       If you use a "prefix" command like EXCEPT, FOR, GLOBAL, or
       SELECT, the prefix command is considered one command, and
       each command it invokes is another.  For example, this
       command line executes four commands -- the FOR and three ECHO
       commands:

            for %x in (a b c) do echo %x

       You cannot use the batch debugger with REXX files (see page
       104) or EXTPROC files (page 106).  It can only be used with
       normal 4DOS, 4OS2, and 4NT batch files.

       The debugger gives you a detailed, step-by-step view of batch
       file execution, and will help solve particularly difficult
       batch file problems.  However, in some cases you will find it
       easier to diagnose these problems with techniques that allow
       you to review what is happening at specific points in the
       batch file without stepping through each line individually.

       There are several tricks you can use for this purpose.
       Probably the simplest is to turn ECHO on at the beginning of
       the file while you're testing it, or use SETDOS /V2 to force
       ECHO on even if an ECHO OFF command is used in the batch
       file.  This will give you a picture of what is happening as
       the file is executed, without stopping at each line.  It will
       make your output look messy of course, so just turn it off
       once things are working.  You can also turn ECHO on at the
       beginning of a group of commands you want to "watch", and off
       at the end, just by adding ECHO commands at the appropriate
       spots in your file.

       If an error occurs in a batch file, the error message will
       display the name of the file, the number of the line that
       contained the error, and the error itself.  For example:

            e:\test.bat [3] Invalid parameter "/d"

       tells you that the file E:\TEST.BAT contains an error on line
       3.  The first line of the batch file is numbered 1.

       Another trick, especially useful in a fast-moving batch file
       or one where the screen is cleared before you can read
       messages, is to insert PAUSE commands wherever you need them
       in order to be able to watch what's happening.  You can also
       use an ON ERRORMSG command (see page 327) 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
  -100-

       If you can't figure out how your aliases and variables are
       expanded, try turning LOG on at the start of the batch file.
       LOG keeps track of all commands after alias and variable
       expansion are completed, and gives you a record in a file
       that you can examine after the batch file is done.  You must
       use a standard LOG command; LOG /H (the history log) does not
       work in batch files.

       You may also want to consider using redirection to capture
       your batch file output.  Simply type the batch file name
       followed by the redirection symbols, for example:

            c:\> mybatch >& testout

       This records all batch file output, including error messages,
       in the file TESTOUT, so you can go back and examine it.  If
       you have ECHO ON in the batch file you'll get the batch
       commands intermingled with the output, which can provide a
       very useful trace of what's happening.  Of course, output
       from full-screen commands and programs that don't write to
       the standard output devices can't be recorded, but you can
       still gain a lot of useful information if your batch file
       produces any output.

       If you're using redirection to see the output, remember that
       any prompts for input will probably go to the output file and
       not to the screen, 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 KEYSTACK.  Under
       4OS2 and 4NT, you can also use the TEE command (see page 385)
       to both view the output while the batch file is running and
       save it in a file for later examination.


   ##  String Processing

       As you gain experience with batch files, you're likely to
       find that you need to manipulate text strings.  You may need
       to prompt a user for a name or password, process a list of
       files, or find a name in a phone list.  All of these are
       examples of string processing -- the manipulation of lines of
       readable text.

       4DOS, 4OS2, and 4NT include several features that make string
       processing easier.  For example, you can use the INKEY and
       INPUT commands for user input; the ECHO, SCREEN, SCRPUT, and
       VSCRPUT commands for output; and the FOR command or the
       @FILEREAD function to scan through the lines of a file.  In
       addition, variable functions offer a wide range of string
       handling capabilities (see page 119 for full details,
       including a list of string handling functions).

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

       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 SETLOCAL command at the beginning of this batch file
       saves the environment and aliases.  Then the UNALIAS *
       command removes any existing aliases so they won't interfere
       with the behavior of the commands in the remainder of the
       batch file.  The first block of lines ends with an INPUT
       command which asks the user to enter a name.  The user's
       input is stored in the environment variable NAME.

       The second block of lines extracts the user's first and last
       names from the NAME variable and calculates the length of
       each.  It stores the first and last name, along with the
       length of each, in additional environment variables.  Note
       that the @WORD function numbers the first word as 0, not as
       1.

       The IFF command in the third block of lines tests the length
       of both the first and last names.  If either is longer than 8
       characters, the batch file displays an error message and
       ends.  Finally, in the last block, the batch file executes
       the LOGIN program with the appropriate parameters, then uses
       the ENDLOCAL command to restore the original environment and
       alias list.  At the same time, ENDLOCAL discards the
       temporary variables that the batch file used (NAME, FIRST,
       FLEN, etc.).

       When you're processing strings, you also need to avoid some
       common traps.  The biggest one is handling special
       characters.

       Suppose you have a batch file with these two commands, which
       simply accept a string and display it:

            input Enter a string:  %%str
            echo %str
  -102-

       Those lines look safe, but what happens if the user enters
       the string "some > none" (without the quotes).  After the
       string is placed in the variable STR, the second line becomes

            echo some > none

       The ">" is a redirection symbol, so the line echoes the
       string "some" and redirects it to a file called NONE --
       probably not what you expected.  You could try using
       quotation marks (see page 140) to avoid this kind of problem,
       but that won't quite work.  If you use back-quotes (ECHO
       `%STR`), the command will echo the four-character string
       %STR.  Environment variable names are not expanded (replaced
       by their contents, see page 138) when they are inside back-
       quotes.

       If you use double quotes (ECHO "%STR"), the string entered by
       the user will be displayed properly, and so will the
       quotation marks.  With double quotes, the output would look
       like this:

            "some > none"

       As you can imagine, this kind of problem becomes much more
       difficult if you try to process text from a file.  Special
       characters in the text can cause all kinds of confusion in
       your batch files.  Text containing back-quotes, double
       quotes, or redirection symbols can be virtually impossible to
       handle correctly.

       One way to overcome these potential problems is to use the
       SETDOS /X command (see page 368) to temporarily disable
       redirection symbols and other special characters.  The two-
       line batch file above would be a lot more likely to produce
       the expected results if it were rewritten this way:

            setdos /x-15678
            input Enter a string:  %%str
            echo %str
            setdos /x0

       The first line turns off alias processing and disables
       several special symbols, including the command separator and
       all redirection symbols.  Once the string has been processed,
       the last line re-enables the features that were turned off in
       the first line.

       If you need advanced string processing capabilities beyond
       those provided by 4DOS, 4OS2, and 4NT, you may want to
       consider using the REXX language.  Our products support
       external REXX programs for this purpose; see page 104 for
       additional details.
  -103-

   ##  Line Continuation

       4DOS, 4OS2, and 4NT will combine multiple lines in the batch
       file into a single line for processing when you include the
       escape character (see page 83) as the very last character of
       each line to be combined (except the last).  For example,
       using the 4OS2 and 4NT escape character:

            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 255 characters in
       4DOS, or 1,023 characters in 4OS2 and 4NT.


   ##  Batch File Compression

       You can compress your batch files with a program called
       BATCOMP.EXE, which is distributed with 4DOS, 4OS2, and 4NT.
       This program condenses batch files by about a third and makes
       them unreadable with the LIST command and similar utilities.
       Compressed batch files run at approximately the same speed as
       regular .BTM files.

       You may want to consider compressing batch files if you need
       to distribute them to others and keep your original code
       secret or prevent your users from altering them.  You may
       also want to consider compressing batch files to save some
       disk space on the systems where the compressed files are
       used.  (However, you will not save space if you keep your
       compressed batch files on a disk compressed with a program
       like DBLSPACE, Stacker, or SuperStor.)

       The full syntax for the batch compression program is

            BATCOMP [/O] input file [output file]

       You must specify the full name of the input file, including
       its extension, on the BATCOMP command line.  If you do not
       specify the output file, BATCOMP will use the same base name
       as the input file and add a .BTM extension.  BATCOMP will
       also add a .BTM extension if you specify a base name for the
       output file without an extension.  For example, to compress
       MYBATCH.BAT and save the result as MYBATCH.BTM, you can use
       any of these three commands:

            c:\> batcomp mybatch.bat
            c:\> batcomp mybatch.bat mybatch
            c:\> batcomp mybatch.bat mybatch.btm

       If the output file (MYBATCH.BTM in the examples above)
       already exists, BATCOMP will prompt you before overwriting
       the file.  You can disable the prompt by including /O on the
       BATCOMP command line immediately before the input file name.
  -104-

       Even if you use the /O option, BATCOMP will not compress a
       file into itself.

4DOS   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
       uncompress 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
       or .CMD 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 LOADBTM command (see page 313).

       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).

       BATCOMP is a DOS and OS/2 character-mode application designed
       to run in any environment where our command processors run.
       Each of our command processors includes the same version of
       BATCOMP.EXE, and a batch file compressed with any copy of
       BATCOMP can be used with any current JP Software command
       processor.

       If you plan to distribute batch files to users of different
       platforms, be sure to read the compatibility discussion on
       page 136.


   ##  REXX Support

       REXX is a a powerful file and text processing language
       developed by IBM, and available on many PC and other
       platforms.  You can invoke REXX programs from 4DOS, 4OS2, or
       4NT.  REXX is an ideal extension to the 4DOS, 4OS2, and 4NT
       batch language, especially if you need advanced string
       processing capabilities.

       The REXX language is not built into 4DOS, 4OS2, or 4NT, and
       requires a separate REXX processor.  REXX support is built in
       to IBM PC-DOS 7.0 and above, and IBM OS/2.  You can also
  -105-

       purchase add-on REXX software such as Enterprise
       Alternatives' Enterprise REXX, available for Windows 3.x,
       Windows 95, and Windows NT; or Quercus's Personal REXX,
       available for DOS, OS/2, Windows 3.x, Windows 95, and Windows
       NT.  (If you want to learn about or purchase one of these
       REXX packages, contact JP Software's sales department for
       more information.)

4DOS   Under 4DOS, REXX programs are stored either in .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
       executable extension (see page 75) that tells 4DOS to load
       Personal REXX when you invoke a .REX file.  For example:

            set .rex=c:\prexx\rexx.exe

       If you store REXX programs in .BAT files, the way you enable
       REXX support depends on whether you are running PC-DOS 7 or
       above (which includes REXX), or another operating system such
       as MS-DOS or an OS/2 DOS session, where native REXX support
       is not available and a third-party product must be used.  The
       differences are:

            *  If you are using PC-DOS 7 or above, 4DOS
               automatically checks each .BAT file to see if it
               contains a REXX program (see below).  If a REXX
               program is found, 4DOS searches the PATH for
               REXX.EXE, the REXX interpreter included with the
               operating system.  You can use the Options 2 page of
               the OPTION dialogs or the REXXPath directive in
               4DOS.INI (see page 151) to specify the location of
               the REXX interpreter if REXX.EXE is not on your PATH,
               or if you wish to use a different REXX system whose
               interpreter is not named REXX.EXE.

            *  If you are not using PC-DOS 7 or above, 4DOS does not
               assume that it should check each .BAT file to see if
               it contains a REXX program.  To enable this feature
               you must explicitly set the REXXPath directive in
               4DOS.INI to define the name and path for your REXX
               interpreter.

       Once you have enabled REXX execution of .BAT files by setting
       REXXPath or using PC-DOS 7 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.

4OS2   Under 4OS2, REXX programs are stored in .CMD files.  4OS2
       checks to see if the first two characters on the first line
       of a .CMD file are [/*], the beginning of a REXX comment.  If
       so, it passes the file to OS/2's built-in REXX facility for
       processing.  If Personal REXX for OS/2 is installed, it
  -106-

       automatically replaces OS/2's built-in REXX, and handles all
       REXX commands passed by 4OS2.

4NT    Under 4NT, REXX programs may be stored in .CMD or .REX files.
       When 4NT loads, it asks Windows NT to locate the Enterprise
       REXX or Personal REXX libraries.  If they are available, 4NT
       checks each .CMD or .REX file you execute to see if the first
       two characters on the first line are [/*].  If so, it passes
       the file to Enterprise REXX or Personal REXX for Windows NT
       for processing.

       All of the REXX processors described above (Enterprise REXX,
       Personal REXX, OS/2's built-in REXX, and PC-DOS 7's built-in
       REXX) extend the interface between REXX and the command
       processor by allowing you to invoke 4DOS, 4OS2, or 4NT
       commands from within a REXX program.

4OS2,  When you send a command from a REXX program back to the
4NT    command processor to be executed (for example, if you execute
       a DIR command within a REXX script), the REXX software must
       use the correct "address" for the command processor.  In most
       cases it is best to use the default address of CMD, which is
       set up automatically by 4OS2 and 4NT.  If you choose to use
       an explicit address via the REXX ADDRESS command, under 4OS2
       you can use either CMD or 4OS2; under 4NT you must use CMD.

       For details on communication between REXX and the command
       processor, or for more information on any aspect of REXX, see
       your REXX documentation.


4OS2,##EXTPROC Support
4NT
       For compatibility with CMD.EXE, 4OS2 and 4NT offer an
       external processor (EXTPROC) option for batch files that lets
       you define an external program to process a particular .CMD
       file.  To identify a .CMD file to be used with an external
       processor, place the string "EXTPROC" as the first word on
       the first line of the file, followed by the name of the
       external program that should be called.  The command
       processor will start the program and pass it the name of the
       .CMD file and any command-line arguments that were entered.

       For example, suppose GETDATA.CMD contains the following
       lines:

            EXTPROC D:\DATAACQ\DATALOAD.EXE
            OPEN PORT1
            READ 4000
            DISKWRITE D:\DATAACQ\PORT1\RAW

       Then if you entered the command:

            [d:\dataacq] getdata /p17
  -107-

       The command processor would read the GETDATA.CMD file,
       determine that it began with an EXTPROC command, read the
       name of the processor program, and then execute the command:

            D:\DATAACQ\DATALOAD.EXE D:\DATAACQ\GETDATA.CMD /p17

       The hypothetical DATALOAD.EXE program would then be
       responsible for reopening the GETDATA.CMD file, ignoring the
       EXTPROC line at the start, and interpreting the other
       instructions in the file.  It would also have to respond
       appropriately to the command-line parameter entered (/p17).

       Do not try to use 4OS2, 4NT, or Take Command as the external
       processor named on the EXTPROC line in the .CMD file.  They
       will interpret the EXTPROC line as a command to re-open
       themselves.  The result will be an infinite loop that will
       continue until the computer runs out of resources and locks
       up.


  Using the Environment

       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.  For
       example, you can create a variable named BACKUP like this:

            c:\> set BACKUP=*.bak;*.bk!;*.bk

       If you then type

            c:\> del %BACKUP

       it is equivalent to the following command:

            del *.bak;*.bk!;*.bk

       In 4DOS, the size of the environment can be specified on the
       Startup page of the OPTION dialogs, with the Environment and
       EnvFree directives in 4DOS.INI (see page 149), or with the
       /E: startup switch (see your Introduction and Installation
       Guide).  In 4OS2 and 4NT, the size of the environment is set
       automatically.

   ##  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 255 characters of information.
  -108-

       Nested variable expansion can be disabled with the SETDOS /X
       command (see page 368).

    ## Environment variables may contain alias names.  The command
       processor 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,
       4OS2, or 4NT, 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:

            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 page 140 for details.

4DOS   Each copy of the command processor 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 SET
  -109-

       /M (page 360), UNSET /M (page 399), and ESET /M (page 253),
       and with the %@MASTER variable function (page 132).  Master
       environment access is not available in 4OS2 or 4NT.


       Configuration Variables

       The following environment variables have special meanings in
       4DOS, 4OS2, and 4NT.

            CDPATH tells the command processor where to search for
            directories specified by the CD, CDD, and PUSHD commands
            and in automatic directory changes.  (_CDPATH can be
            used as an alternative to CDPATH if you are using
            Microsoft Bookshelf, which uses a CDPATH variable for
            its own purposes.)  CDPATH is composed of a list of
            directories, separated by semicolons [;].  See page 56
            for more information about using CDPATH.

            CMDLINE is the fully expanded text of the currently
            executing command line.  CMDLINE is set just before
            invoking any .COM, .EXE, .BTM, .BAT, or .CMD file.  If a
            command line is prefaced with an "@" to prevent echoing
            (see page 38), it will not be put in CMDLINE, and any
            previous CMDLINE variable will be removed from the
            environment.

            COLORDIR controls directory display colors used by DIR
            and SELECT.  See page 230 for a complete description of
            the format of this variable.

            COMSPEC contains the full path and name of the command
            processor.  COMSPEC is most commonly used by
            applications which have a "shell to the command prompt"
            feature.  For details on how COMSPEC is set and used,
            see your Introduction and Installation Guide.

            COPYCMD is used by some versions of COMMAND.COM to hold
            default options for the COPY command.  4DOS and its
            cousins do not support this variable, but you can
            achieve the same effect with an alias.  For example, if
            you want the COPY command to default to prompting you
            before overwriting an existing file, you could use this
            alias:

                 c:\> alias copy = `*copy /r`

            If you wish to use COPYCMD for compatibility with
            systems that do not use 4DOS, you can define the alias
            this way:

                 c:\> alias copy = `*copy %copycmd`

            DIRCMD is used by some versions of COMMAND.COM and
            CMD.EXE to hold default options for the DIR command.
            4DOS and its cousins do not support this variable, but
            you can achieve the same effect with an alias.  For
  -110-

            example, if you want the DIR command to default to a 2-
            column display with a vertical sort and a pause at the
            end of each page, you could use this alias:

                 c:\> alias dir = `*dir /2/p/v`

            If you wish to use DIRCMD for compatibility with systems
            that do not use 4DOS, you can define the alias this way:

                 c:\> alias dir = `*dir %dircmd`

            FILECOMPLETION sets the files made available during
            filename completion for selected commands.  See page 43
            for a complete description of the format of this
            variable.

            PATH is a list of directories that 4DOS, 4OS2, or 4NT
            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 page
            18 and the PATH command on page 331 for a full
            description of this variable.

            PROMPT defines the command-line prompt.  It can be set
            or changed with the PROMPT command (see page 335).

4DOS        TEMP specifies the directory where 4DOS should store
            temporary pipe files if the TEMP4DOS variable doesn't
            exist.  Some other programs also use TEMP to define
            where they should place their temporary files.
            Temporary pipe files are not used in 4OS2 and 4NT.

4DOS        TEMP4DOS specifies where 4DOS should store temporary
            pipe files.  Temporary pipe files are not used in 4OS2
            and 4NT.

4NT    In addition, 4NT uses the environment to keep track of the
       default directory on each drive or hard disk volume.  DOS and
       OS/2 keep track of the default directory for each drive
       letter internally; Windows NT does not.  4NT overcomes this
       incompatibility by saving the default directory for each
       drive in the environment, using variable names that cannot be
       accessed by the user.  Each variable begins with an equal
       sign followed by the drive letter and a colon (for example,
       =C:).  You cannot view or change these variables with the SET
       command; they are only available for internal use by 4NT.


   ##  Internal Variables

       Internal variables are special environment variables built
       into 4DOS, 4OS2, and 4NT to provide information about your
       system.  They are not actually stored in the environment, but
       can be used in commands, aliases, and batch files just like
       any other environment variable.
  -111-

       The values of these variables are stored internally in the
       command processor, and cannot be changed with the SET, UNSET,
       or ESET command.  However, you can override any of these
       variables by defining a new variable with the same name.

       These internal variables are often used in batch files and
       aliases to examine system resources and adjust to the current
       computer settings.  You can examine the contents of any
       internal variable (except %= and %+) from the command line
       with a command like this:

            c:\> echo %variablename

       The variables are listed below.  The first list is by
       category, to assist you in locating the information you want
       quickly.  The second list includes all the variables in
       alphabetical order, and defines the meaning of each one.

       On disk volumes which do not support long filenames,
       variables which return a path or file name will return their
       result in upper or lower case depending on the value of the
       SETDOS /U switch (see page 367) or the UpperCase directive in
       the .INI file (see page 159).  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
       (see page 14 for more details).  Returned filename values
       which include long filenames are not quoted automatically;
       you must add quotes yourself if they are required for your
       use of the variable value.

       Some variables return values based on information provided by
       your operating system.  These variables will only return
       correct information if the operating system provides it.  For
       example, _APMBATT will not return accurate results if your
       operating system and Advanced Power Management drivers do not
       provide correct information on battery status to the command
       processor.

       A few examples of internal variable usage are located at the
       end of the lists, on page 118.  For a more comprehensive set
       of examples see the online help, or the EXAMPLES.BTM file
       which came with your command processor.


       Internal Variable Categories

       Hardware status:

          _APMAC         _APMBATT       _APMLIFE       _CPU
          _KBHIT         _MONITOR       _NDP           _VIDEO

       Operating system and software status:

          _ANSI          _BOOT          _CODEPAGE      _COUNTRY
          _DOS           _DOSVER        _DPMI          _DV
          _MOUSE         _WIN           _WINDIR        _WINSYSDIR
          _WINVER
  -112-

       Command processor status:

          _4VER          _ALIAS         _BATCH         _BATCHLINE
          _BATCHNAME     _DNAME         _ENV           _HLOGFILE
          _KSTACK        _LOGFILE       _PID           _PIPE
          _PPID          _PTYPE         _SHELL         _SID
          _SWAPPING      _TRANSIENT     _WINTITLE

       Screen and color:

          _BG            _CI            _CO            _COLUMN
          _COLUMNS       _FG            _ROW           _ROWS
          _XPIXELS       _YPIXELS

       Drives and directories:

          _CWD           _CWDS          _CWP           _CWPS
          _DISK          _LASTDISK

       Dates and times:

          _DATE          _DAY           _DOW           _DOWI
          _DOY           _HOUR          _MINUTE        _MONTH
          _SECOND        _TIME          _YEAR

       Error codes:

          ?              ??             _?             ERRORLEVEL
          _SYSERR

       Compatibility:

          =              +


       Internal Variable Details

       This alphabetical list includes all internal variables, and
       explains the value each variable returns.  In the list below
       the possible values for most variables are shown in double
       quotes for ease of understanding.  The actual values returned
       by the variables do not include the double quotes.

       ? 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.

4DOS   ?? 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).
  -113-

       _? 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.

       = returns the current escape character.  Use this variable,
       instead of the actual escape character, if you want your
       batch files and aliases to work regardless of how the escape
       character is defined.  For example, if the escape character
       is a caret [^] (the default in 4OS2 and 4NT), 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

       + returns the current command separator.  Use this variable,
       instead of the actual command separator, if you want your
       batch files and aliases to work regardless of how the command
       separator is defined.  %+ should always be surrounded by
       spaces.  For example, if the command separator is an
       ampersand [&] (the default in 4OS2 and 4NT), 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

       _4VER is the current 4DOS, 4OS2, or 4NT version (for example,
       "6.0").  The current decimal character is used to separate
       the major and minor version numbers (see DecimalChar on page
       155 for details).

4DOS   _ALIAS contains the free space in the alias list, in bytes.

       _ANSI contains "1" if internal flags indicate that ANSI.SYS
       or a compatible driver is installed; "0" if not.  Under 4NT,
       _ANSI always returns "0", because there is no ANSI support in
       Windows NT.

4DOS   In 4DOS, the internal flags which determine the value of
       _ANSI depend on the SETDOS /A option (see page 364) and the
       ANSI directive in 4DOS.INI (see page 154), as shown in the
       table below.  If SETDOS /A is 0 or ANSI is set to Auto, 4DOS
       tests for the presence of an ANSI driver.  In this case you
       may need to experiment to see if this variable works properly
       with your particular driver, because there is no standard and
       100% reliable way to detect an ANSI driver.  See page 25 for
       more information on ANSI drivers.
  -114-

            SETDOS /A         ANSI Directive _ANSI Value

               0 (default)    Auto (default) Result of test
               1              Yes            1
               2              No             0

4DOS,  _APMAC is the Advanced Power Management AC line status ("on-
4OS2   line", "off-line", or "unknown").  An empty string is
       returned if APM is not installed on your system.  (See the
       Glossary in the online help for a short description of APM.)

4DOS,  _APMBATT is the Advanced Power Management battery status
4OS2   "low", "critical", "charging", or "unknown").  An empty
       string is returned if APM is not installed.

4DOS,  _APMLIFE is the Advanced Power Management remaining battery
4OS2   life (0 - 100 or "unknown").  An empty string is returned if
       APM is not installed.

       _BATCH is the current batch nesting level.  It is "0" if no
       batch file is currently being processed.

       _BATCHLINE is the current line number in the current batch
       file.  It is "-1" if no batch file is currently being
       processed.

       _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.

       _BG is a string containing the first three characters of the
       screen background color at the current cursor location (for
       example, "Bla").

       _BOOT is the boot drive letter, without a colon.

       _CI is the insert-mode cursor shape, as a percentage (see
       SETDOS /S on page 367 and CursorIns on page 155).

       _CO is the overstrike-mode cursor shape, as a percentage (see
       SETDOS /S on page 367 and CursorOver on page 155).

       _CODEPAGE is the current code page number (see CHCP on page
       201).

       _COLUMN is the current cursor column (for example, "0" for
       the left side of the screen).

       _COLUMNS is the current number of screen columns (for
       example, "80").

       _COUNTRY is the current country code.
  -115-

       _CPU is the CPU type:

            86    8086 and 8088           386   i386
            186   80186 and 80188         486   i486
            200   NEC V20 and V30         586   Pentium
            286   80286                   686   Pentium Pro

       _CWD is the current working directory in the format
       d:\pathname.

       _CWDS has the same value as CWD, except it ends the pathname
       with a backslash [\].

       _CWP is the current working directory in the format
       \pathname.

       _CWPS has the same value as CWP, except it ends the pathname
       with a backslash [\].

       _DATE contains the current system date, in the format mm-dd-
       yy (U.S.), dd-mm-yy (Europe), or yy-mm-dd (Japan).

       _DAY is the current day of the month (1 to 31).

       _DISK is the current disk drive, without a colon (for
       example, "C").

       _DNAME is the name of the file used to store file
       descriptions.  It can be changed with the DescriptionName
       directive in the .INI file (see page 155).

       _DOS is the operating system and command processor type.
       Each JP Software command processor returns a different value,
       as follows:

            Product                  Returns
            -------                  -------

            4DOS                     "DOS"
            4OS2                     "OS2"
            4NT                      "NT"
            Take Command/16          "WIN"
            Take Command/32          "WIN95" (under Windows 95)
                                     "WIN32" (under Windows NT)
            Take Command for OS/2    "PM" (for OS/2 Presentation
                                     Manager)

       This variable is useful if you have batch files running in
       more than one environment, and need to take different actions
       depending on the underlying operating environment or command
       processor.

       _DOSVER is the current operating system version (for example,
       "6.22").  When running 4DOS in an OS/2 DOS session the
       version number will be 20.3 for OS/2 Warp 3, 20.4 for OS/2
       Warp 4, and so on.  When running 4DOS under Windows 95, the
       version number will be 7.00, 7.10 etc.  The current decimal
  -116-

       character is used to separate the major and minor version
       numbers (see DecimalChar on page 155 for details).

       _DOW is the first three characters of the current day of the
       week ("Mon", "Tue", "Wed", etc.).

       _DOWI is the current day of the week as an integer (1 =
       Sunday, 2 = Monday, etc.).

       _DOY is the day of the year (1 to 366).

4DOS   _DPMI returns the DPMI version number, or "0" if DPMI isn't
       present. (See the Glossary in the online help for a short
       description of DPMI.)

4DOS   _DV is "1" if DESQview is loaded or "0" otherwise.

4DOS   _ENV is the free space in the environment, in bytes.

4NT    ERRORLEVEL contains the exit code of the last external
       command.  This variable is equivalent to the ? variable
       described on page 112.  It is included only for compatibility
       with CMD.EXE.

       _FG is a string containing the first three letters of the
       screen foreground color at the current cursor position (for
       example, "Whi").

       _HLOGFILE returns the name of the current history log file
       (or an empty string if LOG /H is OFF).  See LOG on page 315
       for information on logging.

       _HOUR is the current hour (0 - 23).

       _KBHIT returns "1" if one or more keystrokes are waiting in
       the keyboard buffer, or "0" if the keyboard buffer is empty.

4DOS   _KSTACK returns "1" if KSTACK.COM is loaded or "0" otherwise.

       _LASTDISK is the last valid drive letter, without a colon.

       _LOGFILE  returns the name of the current log file (or an
       empty string if LOG is OFF).  See LOG on page 315 for
       information on logging.

       _MINUTE is the current minute (0 - 59).

4DOS,  _MONITOR is the monitor type ("mono" or "color").
4OS2

       _MONTH is the current month of the year (1 to 12).

       _MOUSE is "1" if a mouse driver is loaded, and "0" otherwise.
       This variable always returns "1" in 4OS2 and 4NT.
  -117-

       _NDP is the coprocessor type:

            0     no coprocessor is installed
            87    8087
            287   80287
            387   80387, 80486DX, 80487, Pentium, or Pentium Pro

4OS2,  _PID is the current process ID number.
4NT

4OS2,  _PIPE returns "1" if the current process is running inside a
4NT    pipe or "0" otherwise.

4OS2   _PPID is the process ID number of the parent process.

4OS2   _PTYPE is the current OS/2 process type:

            AVIO      Character mode, windowed
            DT        Detached (no screen in use)
            FS        Character mode, full-screen
            PM        Presentation Manager

       _ROW is the current cursor row (for example, "0" for the top
       of the screen).

       _ROWS is the current number of screen rows (for example,
       "25").

       _SECOND is the current second (0 - 59).

       _SHELL is the current shell nesting level.  The primary shell
       is level "0", and each subsequent secondary shell increments
       the level by 1.

4OS2   _SID is the session ID number.

4DOS   _SWAPPING returns the current swapping state.  The return
       value is "OFF" if swapping has been disabled with the
       SWAPPING 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 Swapping directive or if
       4DOS failed to initiate memory or disk swapping during
       initialization.

       _SYSERR is the error code of the last operating system error.
       You will need a technical or programmer's manual to
       understand these error values.

       _TIME contains the current system time in the format
       hh:mm:ss.  The separator character may vary depending upon
       your country information.

       _TRANSIENT is "1" if the current shell is transient (started
       with a /C, see your Introduction and Installation Guide for
       details), or "0" otherwise.
  -118-

4DOS,  _VIDEO is the video card type:  "mono", "cga", "ega", or
4OS2   "vga" in 4DOS; all of the above plus "8514", "IA/A" (for the
       PS/2 Image Adapter/A), and "xga" in 4OS2.

4DOS   _WIN is the current Microsoft Windows mode.  The possible
       values are:

            0       Windows is not running
            1       Windows 2
            2       Windows 3 in 386 enhanced mode
            3       Windows 3 in real or standard mode
            40      Windows 95

4NT    _WINDIR returns the name of the Windows NT directory.

4NT    _WINSYSDIR returns the name of the Windows NT system
       directory.

       _WINTITLE returns the title of the current window.  This
       variable is valid in 4OS2 and 4NT, and in 4DOS when it is
       running in a DOS session under OS/2.  If you are using 4DOS
       running under DOS or Windows, or using the default title in
       an OS/2 DOS session, the return value is an empty string.

4NT    _WINVER returns the current Windows NT version number.  The
       current decimal character is used to separate the major and
       minor version numbers (see DecimalChar on page 155 for
       details).

4OS2,  _XPIXELS returns the physical screen horizontal size in
4NT    pixels.

       _YEAR is the current 4-digit year (1980 to 2099).

4OS2,  _YPIXELS returns the physical screen vertical size in pixels.
4NT


       Internal Variable 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 your command processor.

       Some of these examples rely on the IF command (page 284) or
       the IFF command (page 291) to test the value of a variable
       and perform different actions based on that value.

       In a 4DOS or 4OS2 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
  -119-

       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 DIR 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 PROMPT on page 335 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 page 93):

            iff %_shell==0 then
              prompt $t $p$g
              color %_fg on blue
            else
              prompt [$z] $p$g
              color %_fg on cyan
            endiff


   ##  Variable Functions

       Variable functions are like internal variables, but they take
       one or more arguments (which can be environment variables or
       even other variable functions) and they return a value.

       Like all environment variables, these variable functions must
       be preceded by a percent sign in normal use (%@EVAL, %@LEN,
       etc.).  All variable functions must have square brackets
       enclosing their argument(s).  The argument(s) to a variable
       function cannot exceed 255 characters in length for all
       arguments taken as a group.

       The variable functions are useful in aliases and batch files
       to check on available system resources, manipulate strings
       and numbers, and work with files and filenames.

       A few examples of variable function usage are located at the
       end of the lists, on page 135.  For a more comprehensive set
       of examples see the EXAMPLES.BTM file which came with your
       command processor.


       Notes on Specific Functions and Arguments

       Some variable functions, like @DISKFREE, are shown with
       "b|k|m" as one of their arguments.  Those functions return a
       number of bytes, kilobytes, or megabytes based on the "b|k|m"
       argument:
  -120-

            b       return the number of bytes
            K       return the number of kilobytes (bytes / 1,024)
            k       return the number of thousands of bytes (bytes /
                    1,000)
            M       return the number of megabytes (bytes /
                    1,048,576)
            m       return the number of millions of bytes (bytes /
                    1,000,000)

       You can include commas (or the "thousands separator"
       character for your system) in the results from a "b|k|m"
       function by appending a "c" to the argument.  For example, to
       add commas to a "b" or number of bytes result, enter "bc" as
       the argument.  To set the thousands separator see the
       ThousandsChar directive on page 159.

       Functions which accept a date as an argument 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.

       Several functions return filenames or parts of filenames.  On
       an HPFS, NTFS, or LFN drive the strings returned by these
       functions may contain whitespace or other special characters.
       To avoid problems which could be caused by these characters,
       quote the returned name before you pass it to other commands,
       for example (either of these methods would work):

            set fname="%@findfirst[pro*.*]"
            echo First PRO file contains:
            type %fname
            .....

            set fname=%@findfirst[pro*.*]
            echo First PRO file contains:
            type "%fname"
            .....

       If you don't use the quotes in the SET or TYPE command in
       this example, TYPE will not interpret any whitespace or
       special characters in the name properly.

    !  In variable functions which take a drive letter as an
       argument, like @DISKFREE or @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 @FILEREAD, @FILEWRITE, @FILEWRITEB, @FILESEEK,
       @FILESEEKL, and @FILECLOSE functions allow you to access
       files based on their file handle.  These functions should
       only be used with file handles returned by @FILEOPEN!  If you
       use them with any other file handle you may damage other
       files opened by the command processor (or, in a secondary
       shell, the program which started the command processor), or
       hang your system.
  -121-

       A number of functions accept a file attribute string to help
       determine which files to process (see page 15 for more
       information on file attributes).  The string is typically
       shown as nrhsda in the function parameter list.  Wherever you
       see this argument, you can use any of the specified letters
       to refer to the desired file attributes, as follows:

            N    Normal (no attributes set)    S    System
            R    Read-only                     D    Directory
            H    Hidden                        A    Archive

       The attributes (other than N) can be combined; for example,
       HS would refer to hidden, system files.  In most cases the
       function will only find a file if all of the specified
       attributes match; any exceptions are noted in the text for
       the individual function.  You can prefix an attribute with
       "-" to mean "everything except files with this attribute;"
       for example, H-R refers to files marked hidden, but not read-
       only.

       Many functions return values based on information provided by
       your operating system.  Such functions will only return
       correct information if the operating system provides it.  For
       example, @READY will not return accurate results if your
       operating system does not provide correct disk drive status
       information to the command processor.

       The functions are listed below.  The first list is by
       category, to assist you in locating the function you want
       quickly.  The second list includes all the functions in
       alphabetical order, and defines the arguments and return
       value for each one.


       Variable Function Categories

       System status:

          @DOSMEM        @EMS           @EXTENDED      @MASTER
          @READSCR       @XMS

       Drives and devices:

          @CDROM         @DEVICE        @DISKFREE      @DISKTOTAL
          @DISKUSED      @FSTYPE        @LABEL         @LPT
          @READY         @REMOTE        @REMOVABLE

       Files:

          @ATTRIB        @DESCRIPT      @EAREAD        @EAWRITE
          @EXETYPE       @FILEAGE       @FILECLOSE     @FILEDATE
          @FILEOPEN      @FILEREAD      @FILES         @FILESEEK
          @FILESEEKL     @FILESIZE      @FILETIME      @FILEWRITE
          @FILEWRITEB    @FINDCLOSE     @FINDFIRST     @FINDNEXT
          @LINE          @LINES         @SEARCH        @UNIQUE
  -122-

       File names:

          @ALTNAME       @EXPAND        @EXT           @FILENAME
          @FULL          @LFN           @NAME          @PATH
          @SFN           @TRUENAME

       Strings and characters:

          @ASCII         @CHAR          @EXECSTR       @FORMAT
          @INDEX         @INSERT        @INSTR         @LEFT
          @LEN           @LOWER         @REPEAT        @REPLACE
          @RIGHT         @STRIP         @SUBSTR        @TRIM
          @UPPER         @WILD          @WORD          @WORDS

       Numbers and arithmetic:

          @COMMA         @CONVERT       @DEC           @EVAL
          @INC           @INT           @NUMERIC       @RANDOM

       Dates and times:

          @DAY           @DATE          @DOW           @DOWI
          @DOY           @MAKEAGE       @MAKEDATE      @MAKETIME
          @MONTH         @TIME          @YEAR

       Utility:

          @ALIAS         @CLIP          @EXEC          @EXECSTR
          @IF            @INIREAD       @INIWRITE      @REXX
          @SELECT        @TIMER


       Variable Function Details

       @ALIAS[name]:  Returns the contents of the specified alias as
       a string, or a null string if the alias doesn't exist.  When
       manipulating strings returned by @ALIAS you may need to
       disable certain special characters with the SETDOS /X command
       (see page 368).  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.

4NT    @ALTNAME[filename]:  Returns the alternate (short, "8.3" FAT-
       format) name for  the specified file.  If the filename is
       already in 8.3 format, returns the filename if the file
       exists or an empty string if it does not.  @ALTNAME will also
       return the shortened pathname if you provide a path in place
       of the filename.

       @ASCII[c]:  Returns the numeric value of the specified ASCII
       character as a string.  For example %@ASCII[A] returns 65.
       You can put an escape character [Ctrl-X] before the actual
       character to process.  This allows quotes and other special
       characters as the argument (e.g., %@ASCII[[Ctrl-X]`], where
       [Ctrl-X] represents the up-arrow character).
  -123-

       @ATTRIB[filename[,nrhsda[,p]]]: Returns a "1" if the
       specified file has the matching attribute(s); otherwise
       returns a "0".  See the note on page 121 for more information
       on the second argument.

       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).

       @CDROM[d:]:  Returns "1" if the drive is a CD-ROM or "0"
       otherwise.

       @CHAR[n]:  Returns the character corresponding to an ASCII
       numeric value.  For example %@CHAR[65] returns A.

       @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.  In 4DOS, this function will
       only work in a DOS session in Windows 3.x or Windows 95.  It
       will not work in a DOS session under OS/2.

       @COMMA[n]:  Inserts commas, or the "thousands separator"
       character for your system, into a numeric string.  To set the
       thousands separator see the ThousandsChar directive on page
       159.

       @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 (2,147,483,647).  No error is
       returned if value is outside that range.  For example, to
       convert "1010101" from binary to decimal, use this syntax:

            %@convert[2,10,1010101]

       @DATE[mm-dd-yy]:  Returns the number of days since January 1,
       1980 for the specified date.  See page 120 for information on
       acceptable date formats.

       @DAY[mm-dd-yy]:  Returns the numeric day of the month for the
       specified date.  See page 120 for information on acceptable
       date formats.
  -124-

       @DEC[%var]:  Returns the same value as @EVAL[%var - 1].  That
       is, it retrieves and decrements the value of a variable.  The
       variable itself is not changed; to do so, use a command like
       this:

            set var=%@dec[%var]

       @DESCRIPT[filename]:  Returns the file description for the
       specified filename (see the DESCRIBE command on page 219).

       @DEVICE[name]:  Returns "1" if the specified name is a
       character device (such as a printer or serial port), or "0"
       if not.

       @DISKFREE[d:,b|k|m]: 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.

       @DISKTOTAL[d:,b|k|m]:  Returns the total disk space on the
       specified drive.  See the note about large DOS network drives
       under @DISKFREE above.

       @DISKUSED[d:,b|k|m]:  Returns the amount of disk space in use
       by files and directories on the specified drive.  See the
       note about large DOS network drives under @DISKFREE above.

       @DOSMEM[b|k|m]:  In 4DOS, returns the amount of free base
       memory.  In 4OS2, returns the size of the largest free memory
       block (either in physical or virtual memory).  In 4NT,
       returns the amount of free physical memory.

       @DOW[mm-dd-yy]:  Returns the first three characters of the
       day of the week for the specified date ("Mon", "Tue", "Wed",
       etc.).  See page 120 for information on acceptable date
       formats.

       @DOWI[mm-dd-yy]:  Returns the day of the week for the
       specified date as an integer (1 = Sunday, 2 = Monday, etc.).
       See page 120 for information on acceptable date formats.

       @DOY[mm-dd-yy]:  Returns the day of year for the specified
       date (1-366).  See page 120 for information on acceptable
       date formats.

4OS2   @EAREAD[filename, EAname]:  Returns the specified extended
       attribute (EAname) for a file or an empty string if the
       extended attribute does not exist.  This function can only
       read EAs stored as text; it cannot read binary EAs.
       Wildcards cannot be used in the file name.  For example, to
       read the .SUBJECT extended attribute for README.TXT:

            set subject=%@earead[readme.txt,.subject]
  -125-

4OS2   @EAWRITE[filename, EAname, value]:  Creates or updates the
       extended attribute named EAname for the specified file.
       Returns "0" for success or "-1" for failure.  This function
       can only write EAs stored as text; it cannot write binary
       EAs.  Wildcards cannot be used in the file name.  For
       example, to set the .SUBJECT extended attribute for
       README.TXT (enter this on one line):

            if %@eawrite[readme.txt,.subject,Installation notes for
            latest version] != 0 echo EAWRITE failed!

4DOS   @EMS[b|k|m]:  Returns the amount of free EMS memory.

       @EVAL[expression]:  Evaluates an arithmetic expression.
       @EVAL supports addition (+), subtraction (-), multiplication
       (*), division (/), integer division (\, returns the integer
       part of the quotient), modulo (%%), and integer
       exponentiation (**).  The expression can contain environment
       variables and other variable functions.  @EVAL also supports
       parentheses, commas, and decimals.  Parentheses can be
       nested.  @EVAL will strip leading and trailing zeros from the
       result.  When evaluating expressions, **, *, /, \, and %%
       take precedence over + and -.  For example, 3 + 4 * 2 will be
       interpreted as 3 + 8, not as 7 * 2.  To change this order of
       evaluation, use parentheses to specify the order you want.

       The maximum precision is 16 digits to the left of the decimal
       point and 8 digits to the right of the decimal point.  You
       can alter the default precision to the right of the decimal
       point on the Options 2 page of the OPTION dialogs, or with
       the EvalMax and EvalMin .INI file directives (see page 156),
       and with the SETDOS /F command (see page 363).  You can alter
       the decimal character from the Options 1 page of the OPTION
       dialogs, with the DecimalChar directive (see page 155), or
       the SETDOS /G command.

       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 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.  If x is greater than y, it
       is ignored.  You can specify either or both arguments, for
       example:

            @eval[3/7=.4]       returns 0.4286
            @eval[3/7=2]        returns 0.42857143
            @eval[3/6=2.4]      returns 0.50

       Also see @DEC and @INC.
  -126-

       @EXEC[[@]command]:  Execute the command.  The command can be
       an alias, internal command, external command, or .BTM, .BAT,
       or .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.  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.

       @EXECSTR[command]:  Runs the specified command and returns
       the first line written to STDOUT by that command.  Be sure to
       read the cautionary note under @EXEC above.  @EXECSTR is
       useful for retrieving a result from an external utility --
       for example, if you have an external utility 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 TIME command you could also use it to set the time on
       your system:

            c:\> time %@execstr[d:\path\nettime.exe]

4OS2   @EXETYPE[filename]:  Returns the application type as a
       string:

            DOS            DOS .COM, .EXE, or .BAT file
            AVIO           OS/2 Character mode, windowed
            FS             OS/2 Character mode, full-screen
            PM             OS/2 Presentation Manager
            WIN            Windows 3
            UNKNOWN        Any other file

       @EXPAND[filename[,-nrhsda]]:  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.  See the note
       on page 121 for more information on this argument.  If the
       attribute argument is not used, hidden files, system files,
       and directories will be excluded from the returned list; all
       other files which match the filename will be included.

       @EXT[filename]:  Returns the extension from a filename,
       without a leading period.  On HPFS, NTFS, and LFN drives the
       extension can be up to 64 characters long.  On traditional
       FAT drives it can be up to 3 characters long.
  -127-

4DOS   @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.
       Therefore, when a memory manager is loaded this function will
       usually return 0.

       @FILEAGE[filename]:  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.  Also see @MAKEAGE.

       @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 occured.  Be sure to read the
       cautionary note about file functions on page 120.

       @FILEDATE[filename[,acw]]:  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, HPFS, or NTFS drive:  a
       means the last access date, c means the creation date, and w
       means the last modification (write) date, which is the
       default.

       @FILENAME[filename]:  Returns the name and extension of a
       file, without a path.

       @FILEOPEN[filename, read | write | append, [b|t]]:  Opens the
       file in the specified mode and returns the file handle as an
       integer.  The optional third parameter controls whether the
       file is opened in binary or text mode.  Text mode (the
       default) should be used to read text using @FILEREAD without
       a "length", and to write text using @FILEWRITE.  Binary mode
       should be used to read binary data with @FILEREAD with a
       "length", and to write binary data with @FILEWRITEB.  Returns
       "-1" if the file cannot be opened.  Be sure to read the
       cautionary note about file functions on page 120.

4OS2,  @FILEOPEN can also open named pipes.  The pipe name must
4NT    begin with \pipe\ in 4OS2, or \\.\pipe\ in 4NT.  @FILEOPEN
       first tries to open an existing pipe; if that fails, it tries
       to create a new pipe.  Pipes are opened in blocking mode,
       duplex access, byte-read mode, and inheritable.  For more
       information on named pipes see your OS/2 or Windows NT
       documentation.

       @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.  Be sure to read the cautionary
       note about file functions on page 120.

       @FILES[filename [,-nrhsda]]:  Returns the number of files
       that match the filename, which may contain wildcards and
  -128-

       include lists.  Returns "0"if no files match.  The filename
       must refer to a single directory; to check several
       directories, use @FILES once for each directory, and add the
       results together with @EVAL.  The second argument, if
       included, defines the attributes of the files that will be
       included in the search; see the note on page 121 for details.

       @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 on page 120.

       @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.  Be sure to read the
       cautionary note about file functions on page 120.  @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.

       @FILESIZE[filename,b|k|m[,a]]:  Returns the size of a file,
       or "-1" if the file does not exist.  If the filename includes
       wildcards or an include list, returns the combined size of
       all matching files.  The 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.

       @FILETIME[filename[,acw]]:  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,
       HPFS, or NTFS drive:  a means the last access time, c means
       the creation time, and w means the last modification (write)
       time, which is the default.  The last access time is always
       returned as 00:00 on LFN drives (see page 16 for additional
       details).

       @FILEWRITE[n,text]:  Writes a line to the file whose handle
       is n.  Returns the number of bytes written, or "-1" if an
       error occurred.  n must be a handle returned by @FILEOPEN; or
       1 (for standard output) or 2 (for standard error).  Be sure
       to read the cautionary note about file functions on page 120
       for additional details.

       @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.
  -129-

       Be sure to read the cautionary note about file functions on
       page 120.

       @FINDCLOSE[filename]:  Signals the end of a @FINDFIRST /
       @FINDNEXT sequence.  When running 4OS2, 4NT, or 4DOS under
       Windows 95, you must use this function to release the
       directory search handle used for @FINDFIRST / @FINDNEXT.

       @FINDFIRST[filename [,-nrhsda]]:  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.  Be sure to read the notes on page 120 about quoting
       returned long filenames, and the note on page 121 for more
       information on the attribute argument.

       When running 4OS2, 4NT, or 4DOS under Windows 95 you must use
       @FINDCLOSE after @FINDFIRST or the last @FINDNEXT to avoid
       running out of directory search handles.

       @FINDNEXT[[filename [,-nrhsda]]]:  Returns the name of the
       next file that matches the filename passed to @FINDFIRST.
       @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 (see the note on
       page 121 for details).  Returns an empty string when no more
       files match.

       Be sure to read the notes under @FINDFIRST above regarding
       the need to close your directory search handle with
       @FINDCLOSE, and the notes on page 120 about quoting returned
       long filenames.

       @FORMAT[[-][x][.y],string]: Reformats a string, truncating it
       or padding it with spaces as necessary.  If you use the minus
       [-], the string is left-justified; otherwise, it is right-
       justified.  The x value is the minimum number of characters
       in the result.  The y value is the maximum number of
       characters in the result.  You can combine the options as
       necessary.  For example:

            %@format[12,JPSoftware]  returns "  JPSoftware"
            %@format[.3,JPSoftware]  returns "JPS"

4OS2,  @FSTYPE[d:]:  Returns the file system type for the specified
4NT    drive.  Under 4OS2, @FSTYPE will return "FAT" for a DOS-
       compatible drive with a file allocation table, "HPFS" for a
       drive that uses OS/2's high performance file system, or
       "CDFS" for a CD-ROM drive.  It may return other values if
       additional file systems have been installed with the IFS=
       directive in CONFIG.SYS.  4NT will normally return "FAT",
       "HPFS", "CDFS", or "NTFS" for a drive that uses the Windows
       NT file system.  LFN drives will return "FAT".
  -130-

       @FULL[filename]:  Returns the full path and filename of a
       file.  Be sure to read the notes on page 120 about quoting
       returned long filenames.

       @IF[condition,true,false]:  Evaluates the condition and
       returns a string based on the result.  The condition can
       include any of the tests allowed in the IF command (see page
       284).  If the condition is true, @IF returns the first result
       string; if it is false, @IF returns the second string.  For
       example, %@IF[2 == 2,Correct!,Oops!] returns "Correct!"

       @INC[%var]:  Returns the same value as %@EVAL[%var + 1].
       That is, it retrieves and increments the value of a variable.
       The variable itself is not changed; to do so, use a command
       like this:

            set var=%@inc[%var]

       @INDEX[string1,string2]:  Returns the position of string2
       within string1, or "-1" if string2 is not found.  The first
       position in string1 is numbered 0.

4NT    @INIREAD[filename,section,entry]:  Returns an entry from the
       specified .INI file or an empty string if the entry does not
       exist.  For example:

            %@iniread[c:\4nt\4nt.ini,4nt,history]

       returns the size of the command history if it is specified in
       the [4NT] section of 4NT.INI.  If you don't specify a path
       for the .INI file, @INIREAD will look in the \WINNT and
       \WINNT\SYSTEM directories.

4NT    @INIWRITE[filename,section,entry,string]:  Creates or updates
       an entry in the specified .INI file.  For example:

            %@iniwrite[c:\4nt\4nt.ini,4nt,history,2048]

       sets the size of the command history to 2,048 bytes the next
       time 4NT is started.  @INIWRITE returns "0" for success or
       "-1" for failure.  If you don't specify a path for the .INI
       file, @INIWRITE will look in the \WINNT and \WINNT\SYSTEM
       directories.

       @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".

       @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;
  -131-

       %@INSTR[1,-2,%_TIME] extracts the seconds.  If the string
       includes commas, it must be quoted with double quotes ["] or
       back-quotes [`].  The quotes do count in calculating the
       position of the substring.  @SUBSTR (page 134) is an older
       version of the same function.

       @INT[n]:  Returns the integer part of the number n.

       @LABEL[d:]:  Returns the volume label of the specified disk
       drive.

       @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".

       @LEN[string]:  Returns the length of a string.

4DOS,  @LFN[filename]:  Returns the long filename for a short
4NT    ("8.3") filename.  In 4DOS, this function will only work if
       you are running under Windows 95.  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 on page 120 about quoting returned
       long filenames

       @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.

       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 (page 263), or @FILEOPEN and a
       sequence of @FILEREADs.

       You can retrieve input from standard input if you specify CON
       as the filename.  If you are redirecting input to @LINE using
       this feature, you must use command grouping (see page 81) or
       the redirection will not work properly (you can pipe to @LINE
       without a command group; this restriction applies only to
       input redirection).  For example:

            (echo %@line[con,0]) < myfile.dat

       @LINES[filename]:  Returns the line number of the last line
       in the file, or "-1" if the file is empty.  The first line in
       the file is numbered 0, so (for example) @LINES will return 0
       for a file containing one line.  To get the actual number of
       lines, use %@INC[%@LINES[filename]].  @LINES must read each
       line of the file in order to count it, and will therefore
       cause significant delays if used in a long loop or on a large
       file.

       @LOWER[string]:  Returns the string converted to lower case.
  -132-

4DOS   @LPT[n]:  Returns a "1" if the specified printer is ready;
       otherwise, returns "0".  n=1 checks the printer connected to
       LPT1, n=2 checks LPT2, and n=3 checks LPT3.  The value
       returned from @LPT may reflect the status of the printer
       port, or the printer itself, depending on your BIOS and
       printer port hardware.  You may need to experiment to
       determine what values are returned on your system.

       @MAKEAGE[date[,time]]:  Returns the date and time (if
       included) as a single value in the same format as @FILEAGE.
       @MAKEAGE can be used to compare the time stamp of a file with
       a specific date and time, for example:

            if %@fileage[myfile] lt %@makeage[1/1/85] echo OLD!

       The value returned by @MAKEAGE can be used for comparisons,
       but can not be used for date and time calculations because it
       is not in identifiable units.

       @MAKEDATE[n]:  Returns a date (formatted according to the
       current country settings).  n is the number of days since
       1/1/80.  This is the inverse of @DATE.

       @MAKETIME[n]:  Returns a time (formatted according to the
       current country settings).  n is the number of seconds since
       midnight.  This is the inverse of @TIME.

4DOS   @MASTER[varname]:  Returns the value of a variable from the
       master environment.

       @MONTH[mm-dd-yy]:  Returns the month number for the specified
       date (1-12).  See page 120 for information on acceptable date
       formats.

       @NAME[filename]:  Returns the base name of a file, without
       the path or extension.  Be sure to read the notes on page 120
       about quoting returned long filenames.

       @NUMERIC[string]:  Returns "1" if the argument 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.01" are not.

       @PATH[filename]:  Returns the path from a filename, including
       the drive letter and a trailing backslash but not including
       the base name or extension.  Be sure to read the notes on
       page 120 about quoting returned long filenames.

       @RANDOM[min, max]:  Returns a "pseudo-random" value between
       min and max, inclusive.  Min, max, and the returned value are
       all integers.  The random number generator is initialized
       from the system clock the first time it is used after the
       command processor starts, so it will produce a different
       sequence of random numbers each time you use it.
  -133-

       @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 column can be
       specified as an offset from the current cursor location by
       preceding either value with a [+] or [-].  For example:

            %@readscr[-2,+2,10]

       returns 10 characters from the screen, starting 2 rows above
       and 2 columns to the right of the current cursor position.

       You can also specify the row and column as offsets from the
       current cursor position.  Begin the value with a plus sign
       [+] to read the screen the specified number of rows below (or
       columns to the right of) the current position, or with a
       minus sign [-] to read the screen above (or to the left of)
       the current position.

       @READY[d:]:  Returns "1" if the specified drive is ready;
       otherwise returns "0".

       @REMOTE[d:]:  Returns "1" if the specified drive is a remote
       (network) drive; otherwise returns "0".

       @REMOVABLE[d:]:  Returns "1" if the specified drive is
       removable (e.g., a floppy disk or removable hard disk);
       otherwise returns "0".

       @REPEAT[c,n]:  Returns the character c repeated n times.

       @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.

4OS2,  @REXX[expr]:  Calls the REXX interpreter to execute the
4NT    expression.  Returns the result string from REXX; if the REXX
       expression does not return a string, @REXX returns the REXX
       numeric result code. See page 104 for more information on
       REXX support.

       @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."

       @SEARCH[filename[,path]]:  Searches for the filename using
       the PATH environment variable or the specified path,
       appending an extension if one isn't specified.  See page 18
       for details on the default extensions used when searching the
       PATH, and the order in which the search proceeds.  Returns
       the fully-expanded name of the file including drive, path,
       base name, and extension, or an empty string if a matching
       file is not found.  If wildcards are used in the filename,
       @SEARCH will search for the first file that matches the
       wildcard specification, and return the drive and path for
       that file plus the wildcard filename (e.g., E:\UTIL\*.COM).
  -134-

       @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 page 32 for details; to
       change the navigation keys see page 164).  @SELECT returns
       the text of the line the scrollbar is on if you press Enter,
       or an empty string if you press Esc.  The filename must be in
       quotes if it contains whitespace or special characters.  The
       file size is limited only by available memory.  To select
       from lines passed through input redirection or a pipe, use
       CON as the filename.  If you use the optional 1 argument
       after the window title, the list will be sorted
       alphabetically.

4DOS,  @SFN[filename]:  Returns the fully expanded short ("8.3")
4NT    filename for a long filename.  In 4DOS, this function will
       only work if you are running under Windows 95.  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.

       @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.

       @SUBSTR[string,start,length]:  This is an older version of
       @INSTR (see page 130).  The string parameter is at the start
       of the @SUBSTR argument list, and therefore cannot contain
       commas (because any commas in the string would be taken as
       argument separators).  @INSTR, which has the string argument
       last, does not have this restriction.

       @TIME[hh:mm:ss]:  Returns the number of seconds since
       midnight for the specified time.  The time must be in 24-hour
       format; "am" and "pm" cannot be used.

       @TIMER[n]:  Returns the current split time for a stopwatch
       started with the TIMER command (see page 388).  The value of
       n specifies the timer to read and can be 1, 2, or 3.

       @TRIM[string]:  Returns the string with the leading and
       trailing white space (space and tab characters) removed.

4DOS,  @TRUENAME[filename]:  Returns the true, fully-expanded name
4NT    for a file.  Wildcards may not be used in the filename.
       @TRUENAME can handle simple drive substitutions such as those
       created by JOIN, SUBST, or most network drive mappings.
       However, it may not be able to correctly determine the true
       name if you use "nested" JOIN or SUBST commands, or a network
       which does not report true names properly.  In 4DOS @TRUENAME
       requires DOS 3.0 or above.
  -135-

       @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, LFN,
       HPFS, or NTFS drive.  This function allows you to create a
       temporary file without overwriting an existing file.

       @UPPER[string]:  Returns the string converted to upper case.

       @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 PATH:

            if %@wild[%path,*\UTIL*] == 1 command

       @WORD[["xxx",]n,string]:  Returns the nth word in a string.
       The first word is numbered 0.  If n is negative, words are
       returned from the end of the string.  You can use the first
       argument, "xxx" to specify the separators that you wish to
       use.  If you want to use a double quote as a separator,
       prefix it with an escape character (see page 83).  If you
       don't specify a list of separators, @WORD will consider only
       spaces, tabs, and commas as word separators.  If the string
       argument is enclosed in quotation marks, you must enter a
       list of 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"

       @WORDS[["xxx"],string]:  Returns the number of words in the
       string.  The optional list of delimiters follows the same
       format as @WORD.  If the string argument is enclosed in
       quotation marks, you must enter a list of delimiters as well.

4DOS   @XMS[b|k|m]:  Returns the amount of free XMS memory.

       @YEAR[mm-dd-yy]:  Returns the year for the specified date.
       See page 120 for information on acceptable date formats.  The
       year can be specified as two digits or four digits; @YEAR
       returns the same number of digits included in its argument.


       Variable Function Examples

       You can use variable functions in a wide variety of ways
       depending on your needs.  We've included a few examples below
       to give you an idea of what's possible.  For a more
       comprehensive set of examples see the online help, or the
       EXAMPLES.BTM file which came with your command processor.
  -136-

       To set the prompt to show the amount of free memory (see the
       PROMPT command, page 335, 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
       %@DATE and %@TIME functions instead of using %@INSTR to
       extract substrings of the %_DATE and %_TIME variables; we
       used the approach shown to demonstrate the use of %@INSTR.

            rem  Temporary variables used to shorten example lines:
            rem    DD is _date, DY is yymmdd date, TM is _time
            set dd=%_date
            set dy=%@instr[6,2,%dd]%@instr[0,2,%dd]%@instr[3,2,%dd]
            set lastdate=0
            iff exist c:\onceaday.dat then
              set lastdate=%@line[onceaday.dat,0]
            endiff
            iff %dy gt %lastdate then
              set tm=%_time
              iff "%@instr[0,2,%tm]%@instr[3,2,%tm]" gt "0600" then
                rem Commands to be executed once a day go here
                echo %dy > c:\onceaday.dat
              endiff
            endiff


  Special Character Compatibility

       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 page 48),
       the Escape Character (page 83), and the Parameter Character
       (page 89).

       The default values of each of these characters in each
       product is shown in the following chart:

            Product                Separator    Escape   Parameter
            -------                ---------    ------   ---------

            4DOS, Take Command/16      ^       [Ctrl-X]      &
   -137-


            4NT, 4OS2, Take            &          ^          $
            Command/32, Take
            Command for OS/2

       (The [Ctrl-X] represents the up-arrow 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:

            *  Select a consistent set of characters from the
               Options 1 page of the OPTION dialogs (see page 329),
               or with .INI file directives (page 143).  For
               example, to set the 4DOS characters to match 4OS2 and
               4NT, use these lines in 4DOS.INI:

                      CommandSep = &
                      EscapeChar = ^
                      ParameterChar = $

            *  Use internal variables that contain the current
               special character, rather than using the character
               itself (see page 110).  For example, this command:

                      if "%1" == "" (echo Argument missing! ^ quit)

               will only work if the command separator is a caret.
               However, this version works regardless of the current
               command separator:

                      if "%1" == "" (echo Argument missing! %+ quit)

            *  In a batch file, use the SETLOCAL command (see page
               370) to save the command separator, escape character,
               and parameter character when the batch file starts.
               Then use SETDOS as described below to select the
               characters you want to use within the batch file.
               Use an ENDLOCAL command (page 252) at the end of the
               batch file to restore the previous settings.

       You can also use the SETDOS command (see page 363) 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.
  -138-

       For example, the following sequence of commands in a batch
       file will always set the special characters correctly to
       their standard 4OS2 and 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%=[Ctrl-X] /p%=&
            .....
            endlocal


  Command Parsing

       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, 4OS2, or 4NT, 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, the command processor
       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 page 315), 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, 4OS2, and 4NT begin 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 the command processor 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.
  -139-

       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, 4OS2, or 4NT
       next tries to match the command name with its list of
       internal commands.  If it is unsuccessful, the command
       processor 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, 4OS2, or 4NT 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, the command
       processor must scan the command tail to see if it includes
       redirection or piping.  If so, the proper internal switches
       are set to send output to an alternate device or to a file,
       instead of to the screen.  In 4OS2 and 4NT, a second process
       is started at this point, if necessary, to receive any piped
       output.

       Finally, it is time to execute the command.  If the command
       name matches an internal command, 4DOS, 4OS2, or 4NT will
       perform the activities you have requested.  Otherwise, the
       command processor 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 18).

       Once the internal command or external program has terminated,
       the command processor saves the result or exit code that the
  -140-

       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 page 368).


       Argument Quoting

       As it parses the command line, the command processor looks
       for command separators (carets [^] in 4DOS, or ampersands [&]
       in 4OS2 and 4NT), 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 the command
       processor to pass the string to the batch file as a single
       argument.

       For a more complex example, suppose the batch file QUOTES.BAT
       contains the following commands:
  -141-

            @echo off
            echo Arg1 = %1
            echo Arg2 = %2
            echo Arg3 = %3

       and that the environment variable FORVAR has been defined
       with this command:

            c:\> set FORVAR=for

       Now, if you enter the command

            c:\> quotes `Now is the time %%forvar` all good

       the output from QUOTES.BAT will look like this:

            Arg1 = Now is the time %forvar
            Arg2 = all
            Arg3 = good

       But if you enter the command

            c:\> quotes "Now is the time %%forvar" all good

       the output from QUOTES.BAT will look like this:

            Arg1 = "Now is the time for"
            Arg2 = all
            Arg3 = good

       Notice that in both cases, the quotes keep characters
       together and reduce the number of arguments in the line.

       The following example has 7 command-line arguments, while the
       examples above only have 3:

            c:\> quotes Now is the time %%forvar all good

       (The double percent signs are needed in each case because the
       argument is parsed twice, once when passed to the batch file
       and again in the ECHO command.)

       When an alias is defined in a batch file or from the command
       line, its argument can be enclosed in back-quotes to prevent
       the expansion of replaceable parameters, variables, and
       multiple commands until the alias is invoked.  See ALIAS on
       page 178 for details.

       You can disable and re-enable back-quotes and double quotes
       with the SETDOS /X command (see page 368).
