  -113-




  CHAPTER 5 / ALIASES AND BATCH FILES


  This chapter introduces two of the most powerful features of Take
  Command:  aliases and batch files.  It also discusses the
  environment (a list of information available to all programs),
  along with Take Command'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 Take Command comes together in aliases,
       which give you the ability to create your own commands.  An
       alias is a name that you select for a command or group of
       commands.  Simple aliases substitute a new name for an
       existing command.  More complex aliases can redefine the
       default settings of internal or external commands, operate as
       very fast in-memory batch files, and perform commands based
       on the results of other commands.

       This section of the manual will show you some examples of the
       power of aliases.  See the ALIAS command (page 206) for
       complete details about writing your own aliases.  You can
       create aliases either from the command line, as described in
       this section, or with the Aliases dialog which is available
       from the Utilities menu.

       The simplest type of alias gives a new name to an existing
       command.  For example, you could create a command called R
       (for Root directory) to switch to the root directory this
       way:

            [c:\] alias r = cd \

       After the alias has been defined this way, every time you
       type the command R, you will actually execute the command CD
       \.

       Aliases can also create customized versions of commands.  For
       example, the DIR command can sort a directory in various
       ways.  You can create an alias called DE that means "sort the
       directory by filename extension, and pause after each page
       while displaying it" like this:

            [c:\] alias de = dir /oe /p

       Aliases can be used to execute sequences of commands as well.
       The following command creates an alias called MUSIC which
       saves the current drive and directory, changes to the SOUNDS
       directory on drive C, runs the program E:\MUSIC\PLAYER.EXE,
  -114-



       and, when the program terminates, returns to the original
       drive and directory (enter this on one line):

            [c:\] alias music = `pushd c:\sounds &
            e:\music\player.exe & popd`

       This alias is enclosed in back-quotes because it contains
       multiple commands.  You must use the back-quotes whenever an
       alias contains multiple commands, environment variables,
       parameters (see below), redirection, or piping.  See the
       ALIAS command for full details.  Also, please note that
       throughout this section we use the Take Command/32 and Take
       Command for OS/2 command separator, an ampersand [&], to
       separate multiple commands.  If you are using Take
       Command/16, substitute a caret [^] for the ampersand in the
       examples.

       When an alias contains multiple commands, the commands are
       executed one after the other.  However, if any of the
       commands runs an external Windows or OS/2 application (such
       as the fictitious PLAYER.EXE shown above), you must be sure
       the alias will wait for the application to finish before
       continuing with the other commands.  See Waiting for
       Applications to Finish on page 74 for additional details.

       Aliases can be nested; that is, one alias can invoke another.
       For example, the alias above could also be written as:

            [c:\] alias play = e:\music\player.exe
            [c:\] alias music = `pushd c:\sounds & play & popd`

       If you enter MUSIC as a command, Take Command will execute
       the PUSHD command, detect that the next command (PLAY) is
       another alias, and execute the program E:\MUSIC\PLAYER.EXE,
       and -- when the program exits -- return to the first alias,
       execute the POPD command, and return to the prompt.

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

            [c:\] alias del = *del /p

       An asterisk [*] is used in front of the second "del" to show
       that it is the name of an internal command, not an alias.
       See page 208 for more information about this use of the
       asterisk.

       You may have a program on your system that has the same name
       as an internal command.  Normally, if you type the command
       name, you will start the internal command rather than the
       program you desire, unless you explicitly add the program's
       full path on the command line.  For example, if you have a
  -115-



       program named DESCRIBE.COM in the C:\WUTIL directory, you
       could run it with the command C:\WUTIL\DESCRIBE.EXE.
       However, if you simply type DESCRIBE, the internal DESCRIBE
       command will be invoked instead.  Aliases give you two ways
       to get around this problem.

       First, you could define an alias that runs the program in
       question, but with a different name:

            [c:\] alias desc = c:\winutil\describe.exe

       Another approach is to rename the internal command and use
       the original name for the external program.  The following
       example renames the DESCRIBE command as FILEDESC and then
       uses a second alias to run DESCRIBE.EXE whenever you type
       DESCRIBE:

            [c:\] alias filedesc = *describe
            [c:\] alias describe = c:\winutil\describe.exe

       You can also assign an alias to a key, so that every time you
       press the key, the command will be invoked.  You do so by
       naming the alias with an at sign [@] followed by a key name.
       After you enter this next example, you will see a 2-column
       directory with paging whenever you press Shift-F5, then
       Enter:

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

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

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

       The next example clears the Take Command window whenever you
       press Ctrl-F1:

            [c:\] alias @@Ctrl-F1 = cls

       Aliases have many other capabilities as well.  This example
       creates a simple command-line calculator.  Once you have
       entered the example, you can type CALC 4*19, for example, and
       you will see the answer:

            [c:\] alias calc = `echo The answer is:  %@eval[%$]`

       Our last example in this section creates an alias called IN.
       It will temporarily change directories, run an internal or
  -116-



       external command, and then return to the current directory
       when the command is finished:

            [c:\] alias in = `pushd %1 & %2& & popd`

       Now if you type:

            [c:\] in c:\sounds play furelise.wav

       you will change to the C:\SOUNDS subdirectory, execute the
       command PLAY FURELISE.WAV, and then return to the current
       directory.

       The above example uses two parameters:  %1 means the first
       argument on the command line, and %2& means the second and
       all subsequent arguments.  Parameters are explained in detail
       under the ALIAS command.

       Your copy of Take Command includes a sample alias file called
       ALIASES which contains several useful aliases and
       demonstrates many alias techniques.  Also, see the ALIAS and
       UNALIAS commands on pages 206 and 416 for more information
       and examples.  See page 123 for tips about using aliases
       inside your batch files.


  Batch Files

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


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

       The batch file's extension determines its mode.  Files with a
       .BAT extension, or a .CMD extension (in Take Command/32 and
       Take Command for OS/2) are run in the slower, traditional
       mode.  Files with a .BTM extension are run in the faster,
  -117-



       more efficient mode.  You can change the execution mode
       inside a batch file with the LOADBTM command (see page 335).

       Take Command/32 and Take Command for OS/2 can handle .BTM
       files of any length.  Under Take Command/16, .BTM files must
       be less than 64K (65536) bytes long.


       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 388), the BatchEcho directive in the
            .INI file (see page 182), or from the Options 1 page of
            the Configuration dialogs.

       For example, the following line turns off echoing inside a
       batch file.  The [@] symbol keeps Take Command from
       displaying the ECHO OFF command:

            @echo off

       Take Command also has a command line echo that is unrelated
       to the batch file echo setting.  See the ECHO command on page
       279 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 them.  A batch file
       can work with the individual parameters or with the command
       tail as a whole.

       These parameters are numbered from %1 to %127.  %1 refers to
       the first parameter on the command line, %2 to the second,
       and so on.  It is up to the batch file to determine the
       meaning of each parameter.  You can use quotation marks to
       pass spaces, tabs, commas, and other special characters in a
       batch file parameter; see page 172 for details.
  -118-



       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 Take Command/32 and Take Command for OS/2,
       %n$ contains the complete command 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 391).

TC16   By default, Take Command/16 uses an ampersand [&] instead of
       a dollar sign 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 168 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 312 and 319).


       Using Environment Variables

       Batch files can also use environment variables, internal
       variables, and variable functions.  See pages 141 - 168 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
  -119-



       was last modified), and other information (e.g., the current
       date and time).  You can also perform arithmetic operations
       (including date and time arithmetic), manipulate strings and
       substrings, extract parts of a filename, and read and write
       files.

       To create temporary variables for use inside a batch file,
       just use the SET command to store the information you want in
       an environment variable.  Pick a variable name that isn't
       likely to be in use by some other program (for example, PATH
       would be a bad choice), and use the UNSET command (page 418)
       to remove these variables from the environment at the end of
       your batch file.  You can use SETLOCAL (page 390) and
       ENDLOCAL (page 282) 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 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
       197.  Here is a list of some of the commands you might find
       most useful:

            ACTIVATE activates another window.

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

            CALL executes one batch file from within another.

            CANCEL terminates all batch file processing.

            CLS and COLOR set the Take Command display colors.

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

            DRAWBOX draws a box on the screen.

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

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



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

            GOTO branches to a different location in the batch file.

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

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

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

            KEYSTACK sends keystrokes to applications.

            LOADBTM changes the batch file operating mode.

            MSGBOX displays a dialog box with standard buttons like
            Yes, No, OK, and Cancel, and returns the user's
            selection.

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

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

            QUERYBOX displays a dialog box for text input.

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

            REM places a remark in a batch file.

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

            SCRPUT displays a message in color.

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

            SHIFT changes the numbering of the batch file
            parameters.

            START starts another session or window.

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

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



            TIMER starts or reads a stopwatch.

            TITLE changes the window title.

            VSCRPUT displays a vertical message in color.

       These commands, along with the internal variables and
       variable functions, make the enhanced batch file language
       extremely powerful.  Your copy of Take Command includes a
       sample batch file, in the file EXAMPLES.BTM, that
       demonstrates some of the 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 Take Command or an application program
       is running, how the application (if any) was written, whether
       BREAK is ON or OFF under DOS (see page 223), and whether the
       ON BREAK command is in use (see page 348).

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

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

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


       Automatic Batch Files

       Take Command supports two "automatic" batch files, files that
       run without your intervention, as long as Take Command can
       find them.

       Each time Take Command starts it looks for an automatic batch
       file called TCSTART.BTM, TCSTART.BAT, and / or TCSTART.CMD
       (for Take Command/32 and Take Command for OS/2 only).  If the
       TCSTART batch file is not in the same directory as your
       command processor itself, you should use the Startup page of
       the configuration dialogs, or the TCStartPath directive in
       your .INI file (see page 181) to specify its location.
       TCSTART is optional, so Take Command will not display an
       error message if it cannot find the file.

       TCSTART is a convenient place to change the color or content
       of the prompt for each session, LOG the start of a session,
  -122-



       or execute other special startup or configuration commands.
       It is also one way to set aliases and environment variables.

    ## With the exception of some initialization switches, the
       entire startup command line passed to Take Command is
       available to TCSTART via batch file parameters (%1, %2,
       etc.).  This can be useful if you want to see the command
       line passed to Take Command.  For example, to pause if any
       parameters are passed you could include this command in
       TCSTART (enter this on one line):

            if "%1" != "" pause Starting Take Command with
            parameters [%$]

       Whenever Take Command ends, it runs a second automatic batch
       file called TCEXIT.BTM, TCEXIT.BAT, or TCEXIT.CMD (for Take
       Command/32 or Take Command for OS/2).  This file, if you use
       it, should be in the same directory as your TCSTART batch
       file.  Like TCSTART, TCEXIT is optional.  It is not necessary
       in most circumstances, but it is a convenient place to put
       commands to save information such as a history list before a
       shell ends, or LOG the end of the shell.


       Pipes, Transient Sessions, and TCSTART

       When you set up the TCSTART file, remember that it is
       executed every time Take Command starts, including when
       running a pipe in Take Command/32 or Take Command for OS/2
       (see page 87), or a transient copy of Take Command started
       with the /C startup option (see your Introduction and
       Installation Guide for details on /C).

       For example, suppose you enter a command line like this,
       which uses a pipe:

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

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

       This is because both Take Command/32 and Take Command for
       OS/2 start a second command processor session to run the
       commands on the right hand side of the pipe, and that new
       copy runs 4START before processing the commands from the
       pipe.  If 4START changes directories, the command from the
       pipe will be executed in the new directory.  (This is not a
       problem in Take Command/16 because Take Command/16 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 --
  -123-



       the session will execute in the directory set by TCSTART, not
       the directory in which it was originally started.  For
       example, suppose you set up a desktop object with a command
       line like this, which starts a transient session:

            Command:            d:\tcmd\tcmd.exe /c list myfile.txt
            Working Directory:  c:\data

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

       Similarly, any changes to environment variables or other
       settings in TCSTART will affect all copies of Take Command,
       including those used for pipes and transient sessions.

       You can work around these potential problems with the IF or
       IFF command and the internal variables _PIPE (page 147; only
       available in Take Command/32 and Take Command for OS/2) and
       _TRANSIENT (page 148).  For example, to skip all TCSTART
       processing when running in a pipe or transient session, you
       could use a command like this at the beginning of TCSTART:

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


     ##Detecting Take Command

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

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

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


     ##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
       parameter characters used here are those for Take Command/32
       or Take Command for OS/2; change these characters
       appropriately if you are using Take Command/16):

            setlocal
            unalias *
            alias error `echo. & echo ERROR: %$ & goto dispmenu`
            alias fatalerror `echo. & echo FATAL ERROR: %$ & quit`
            alias in `pushd %1 & %2$ & popd`
  -124-



            if not exist setup.btm fatalerror Missing setup file!
            call setup.btm
            cls
            :dispmenu
            text


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

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

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

       The following 9 lines print a menu on the screen and then get
       a keystroke from the user and store the keystroke in an
       environment variable called userchoice.  Then the SWITCH
       command is used to test the user's keystroke and to decide
       what action to take.

       There's another side to aliases in batch files.  If you're
       going to distribute your batch files to others, you need to
  -125-



       remember that they may have aliases defined for the commands
       you're going to use.  For example, if the user has aliased CD
       to CDD and you aren't expecting this, your file may not work
       as you intended.  There are two ways to address this problem.

       The simplest method is to use SETLOCAL, ENDLOCAL, and UNALIAS
       to clear out aliases before your batch file starts, and
       restore them at the end, as we did in the previous example.
       Remember that SETLOCAL and ENDLOCAL will save and restore not
       only the aliases but also the environment, the current drive
       and directory, and various special characters (see page 390
       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

       Take Command includes a built-in batch file debugger, invoked
       with the SETDOS /Y1 command (see page 389).  The debuggger
       allows you to "single-step" through a batch file line by
       line, with the file displayed in a popup window as it
       executes.  You can execute or skip the current line, continue
       execution with the debugger turned off, view the fully-
       expanded version of the command line, or exit the batch file.
       The batch debugger can also pop up a separate window to view
       or edit current environment variables and aliases, and can
       pop up the LIST command to display the contents of any file.

       To start the debugger, insert a SETDOS /Y1 command at the
       beginning of the portion of the batch file you want to debug,
  -126-



       and a SETDOS /Y0 command at the end.  You can also invoke
       SETDOS /Y1 from the prompt, but because the debugger is
       automatically turned off whenever Take Command returns to the
       prompt, you must enter the SETDOS command and the batch file
       name on the same line, for example:

            [c:\] setdos /y1 & mybatch.btm

       If you use the debugger regularly you may want to define a
       simple alias to invoke it, for example (in Take Command/16,
       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.
  -127-



            O             (ff) or Esc        Turn off the debugger and continue
                                with the remainder of the batch
                                file.

            Q             (uit)              Quit the debugger and the current
                                batch file, without executing the
                                remainder of the file.

       The debugger highlights each line of the batch file as it is
       executed.  It executes the commands on the line one at a
       time, so when a line contains more than one command, the
       highlight will not move as each command is executed.  To see
       the individual commands, use the X key to expand each command
       before it is executed.

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

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

       You cannot use the batch debugger with REXX files (see page
       133) or EXTPROC files (page 134).  It can only be used with
       normal Take Command batch files.

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

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

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

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

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



       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 348) to pause if an
       error occurs, then continue with the rest of the file (the
       first command below), or to quit if an error occurs (the
       second command):

            on errormsg pause
            on errormsg quit

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

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

            [c:\] mybatch >& testout

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

       If you're using redirection to see the output, remember that
       any prompts for input will probably go to the output file and
       not to the screen.  Therefore, you will need to know in
       advance the sequence of keystrokes required to get through
       the entire batch file, and enter them by hand or with
       KEYSTACK.  Under Take Command/32 and Take Command for OS/2,
       you can also use the TEE command (see page 404) 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
  -129-



       examples of string processing -- the manipulation of lines of
       readable text.

       Take Command includes several features that make string
       processing easier.  For example, you can use the INKEY,
       INPUT, MSGBOX, and QUERYBOX commands for user input; the
       ECHO, SCREEN, SCRPUT, and VSCRPUT commands for output; and
       the FOR command or the @FILEREAD function to scan through the
       lines of a file.  In addition, variable functions offer a
       wide range of string handling capabilities (see page 149 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
       last names in upper case and neither name longer than 8
       characters.  Here is one way to write such a batch file:

            @echo off
            setlocal
            unalias *
            querybox "Name" Enter your name (no initials):  %%name

            set first=%@word[0,%name]
            set flen=%@len[%first]
            set last=%@word[1,%name]
            set llen=%@len[%last]

            iff %flen gt 8 .or. %llen gt 8 then
               echo First or last name too long
               quit
            endiff

            login /F:%@upper[%first] /L:%@upper[%last]
            endlocal

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

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

       The IFF command in the third block of lines tests the length
       of both the first and last names.  If either is longer than 8
  -130-



       characters, the batch file displays an error message and
       ends.  (QUERYBOX can limit the length of input text more
       simply with its /L switch.  We used a slightly more
       cumbersome method above in order to demonstrate the use of
       string functions in batch files.)

       Finally, in the last block, the batch file executes the LOGIN
       program with the appropriate parameters, then uses the
       ENDLOCAL command to restore the original environment and
       alias list.  At the same time, ENDLOCAL discards the
       temporary variables that the batch file used (NAME, FIRST,
       FLEN, etc.).

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

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

            input Enter a string:  %%str
            echo %str

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

            echo some > none

       The ">" is a redirection symbol, so the line echoes the
       string "some" and redirects it to a file called NONE --
       probably not what you expected.  You could try using
       quotation marks (see page 172) 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 170) 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.
  -131-



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

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

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

       If you need advanced string processing capabilities beyond
       those provided by Take Command, you may want to consider
       using the REXX language.  Our products support external REXX
       programs for this purpose; see page 133 for additional
       details.


     ##Line Continuation

       Take Command will combine multiple lines in the batch file
       into a single line for processing when you include the escape
       character (see page 110) as the very last character of each
       line to be combined (except the last).  For example, using
       the Take Command/32 and Take Command for OS/2 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 Take
       Command/16, or 1,023 characters in Take Command/32 or Take
       Command for OS/2.


     ##Batch File Compression

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

       You may want to consider compressing batch files if you need
       to distribute them to others and keep your original code
  -132-



       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 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
       DRVSPACE.)  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.
       Even if you use the /O option, BATCOMP will not compress a
       file into itself.

TC16   Under Take Command/16, 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 335).

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



       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.
       Normally it can be run successfully from within Take Command
       without manually starting a separate DOS or OS/2 session.
       Each of our command processors includes the same version of
       BATCOMP.EXE, and a batch file compressed with any copy of
       BATCOMP can be used with any current JP Software command
       processor.

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


     ##REXX Support

       REXX is a powerful file and text processing language
       developed by IBM, and available on many PC and other
       platforms.  REXX is an ideal extension to the Take Command
       batch language, especially if you need advanced string
       processing capabilities.

       The REXX language is not built into Take Command, and must be
       obtained separately.  REXX support is built in to IBM OS/2.
       You can also purchase add-on REXX software such as Enterprise
       Alternatives' Enterprise REXX, available for Windows 3.x,
       Windows 95, and Windows NT; or Quercus's Personal REXX,
       available for OS/2, Windows 3.x, Windows 95, and Windows NT.
       (If you want to learn about or purchase one of these REXX
       packages, contact JP Software's sales department for more
       information.)

TC16   Take Command/16 supports REXX programs stored in .REX files.
       When Take Command loads, it asks Windows to locate for the
       Enterprise REXX or Personal REXX libraries.  If they are
       available, Take Command checks to see if you are running a
       .REX file.  If so, it passes the file to Enterprise REXX or
       Personal REXX for processing.

TC32   Take Command/32 supports REXX programs stored in .CMD or .REX
       files.  When Take Command loads, it asks Windows to locate
       the Enterprise REXX or Personal REXX libraries.  If they are
       available, Take Command checks to see if you are running a
       .REX file, or if the first two characters on the first line
       of a .CMD file are [/*], the beginning of a REXX comment.  If
       either of these tests succeeds, Take Command passes the file
       to Enterprise REXX or Personal REXX for processing.
  -134-



TCOS2  Take Command for OS/2 supports REXX programs stored in .CMD
       files.  Take Command checks to see if the first two
       characters on the first line of a .CMD file are [/*], the
       beginning of a REXX comment.  If so, it passes the file to
       OS/2's built-in REXX facility for processing.  If Personal
       REXX for OS/2 is installed, it automatically replaces OS/2's
       built-in REXX, and handles all REXX commands passed by Take
       Command for OS/2.

       Take Command's REXX support will also work with other REXX
       processors such as PMREXX and VX-REXX.  It does not work with
       IBM's VREXX, because the internal design of VREXX does not
       permit reliable execution of REXX scripts from Presentation
       Manager programs like Take Command.

       When working with a REXX processor, Take Command
       automatically handles all input and output for the REXX
       program, and any standard REXX processor window for input and
       output is not displayed.  If you need to run a REXX program
       inside your REXX processor's window, and not under Take
       Command, you should start the REXX processor's executable
       file explicitly, then load and run the REXX program from
       there.

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

       When you send a command from a REXX program back to the
       command processor to be executed (for example, if you execute
       a DIR command within a REXX script), the REXX software must
       use the 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 Take Command.  If you choose to use
       an explicit address via the REXX ADDRESS command, under Take
       Command for OS/2 you can use either CMD or TCMD; under Take
       Command/16 and Take Command/32 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.


TC32,##EXTPROC Support
TCOS2

       For compatibility with CMD.EXE, Take Command offers an
       external processor (EXTPROC) option for batch files that lets
       you define an external program to process a particular .CMD
       file.  To identify a .CMD file to be used with an external
       processor, place the string "EXTPROC" as the first word on
       the first line of the file, followed by the name of the
       external program that should be called.  Take Command will
  -135-



       start the program and pass it the name of the .CMD file and
       any command-line arguments that were entered.

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

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

       Then if you entered the command:

            [d:\dataacq] getdata /p17

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

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

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

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


TC16,##DDE Support
TC32

       Take Command can communicate with other Windows applications
       by using Dynamic Data Exchange or DDE.  To use Take Command
       as a "DDE client" and send a message from Take Command to
       another application, see the DDEEXEC command on page 242.

       You can also use Take Command as a "DDE server" and send
       commands to it from another application.  To do so, use an
       application or server name of "TCMD" (for Take Command/16) or
       "TCMD32" (for Take Command/32), and a topic name of
       "Execute".  The message can be any valid command that you
       could enter on the Command line:  any alias, internal
       command, batch file, or external command.  To send more than
       one line in a single DDE string, separate the lines with
       carriage return and line feed characters.
  -136-



       When using Take Command as a DDE Server you should start Take
       Command, execute the desired command, and exit Take Command.
       The DDE server is not intended to be used with a copy of Take
       Command running at the prompt; attempting to do so may result
       in unusual displays or display of the prompt in an incorrect
       location.

       For example, if you use Microsoft Word for Windows you could
       use the following WordBasic fragment to send a DIR /W command
       to Take Command/32 from within Word:

            TCMDChannel = DDEInitiate("TCMD32", "Execute")
            DDEExecute TCMDChannel, "dir /w"
            DDETerminate TCMDChannel

       You could use the same approach to execute a batch file or
       any other Take Command command from within Word, and similar
       approaches are available in other applications which offer
       DDE support.  Consult your application manual for complete
       details.

       In most cases, when you use Take Command as a DDE server you
       will want to redirect output from the commands you execute,
       because output on the Take Command screen is not likely to be
       useful to the client program which invokes a command.


  Using 4DOS, 4OS2, and 4NT Batch Files and Aliases

       Take Command aliases are separate and independent from those
       defined for 4DOS, 4OS2, or 4NT.  Take Command does not
       automatically "inherit" aliases from a previously loaded copy
       of one of our character-mode command processors, and it
       cannot pass aliases on to one of those command processors
       started from the Take Command prompt.  However, you can load
       aliases from your Take Command startup batch file.  These can
       be the same aliases you use in 4DOS, 4OS2, or 4NT, or a set
       that is just for Take Command.

       While many of your 4DOS, 4OS2, or 4NT aliases will work well
       under Take Command, you'll probably want to create a separate
       set of Take Command aliases.  This will allow you to account
       for the differences in running applications (see page 72),
       and to create new aliases that take advantage of Take Command
       features that are unavailable in our character-mode products.

       If you want to write aliases or batch files that are used in
       both Take Command and one of our other products, but that
       behave differently in each environment, use the %_DOS
       variable to make the distinction.  For example, this batch
       file fragment uses the INPUT command to accept a string if it
       is run under 4DOS, but uses the Windows-style QUERYBOX if it
       is run under Take Command:
  -137-



            iff "%_dos" == "WIN" then
                 querybox "Enter your name:  " %%name
            else
                 input Enter your name:   %%name
            endiff

       Aliases and batch files which simply manipulate files or use
       other internal commands should work with little or no change
       under Take Command.  However, as a general rule, you should
       test any batch file developed for another command processor
       before assuming it will do exactly what you want under Take
       Command.  Pay particular attention to batch files which run
       complex sequences of external programs.

       If you use aliases or batch files to perform a sequence which
       mixes internal commands and character-mode applications, the
       sequence may not work the way you expect under Take Command.
       For example, suppose you have an alias that changes the
       screen color, starts a DOS application, and then resets the
       color again.  If the DOS application is started in a separate
       window, the color changes will not affect it -- a contingency
       you probably didn't have to consider when you wrote the batch
       file.

       Similarly, if you run a sequence of several character-mode
       applications, where each step in the sequence depends on the
       results of the previous step (for example, through the use of
       error levels), the sequence may not run the same way under
       Take Command as it would under character-mode command
       processors.  This is because under Take Command some
       applications may run in a separate window, whereas under a
       character-mode command processor where all programs run in
       sequence in the same "window".  See page 74 for more
       information on waiting for applications.

       You may also find that you want to take advantage of some of
       the new features of Take Command to improve your batch files.
       For example, the START command offers additional flexibility
       in starting applications.  MSGBOX and QUERYBOX can be used to
       create Windows-style input prompts, and KEYSTACK and ACTIVATE
       will help control your Windows applications.

       Once you get used to these enhancements and minor
       differences, you'll find that you can use Take Command to
       manage your system using the same techniques and features you
       are already familiar with from your experience with 4DOS,
       4OS2, 4NT, COMMAND.COM, or CMD.EXE.


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



       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:

            [c:\] del *.bak;*.bk!;*.bk

       You can create, alter, view, and delete environment variables
       with the Environment dialog (available from the Utilities
       menu) as well as with the SET, ESET, and UNSET commands.

       In Take Command, the size of the environment is set
       automatically and expanded as necessary.  You do not need to
       specify the size as you do under 4DOS or some traditional
       command processors.

    ## 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.
       Nested variable expansion can be disabled with the SETDOS /X
       command (see page 388).

    ## Environment variables may contain alias names.  Take Command
       will substitute the variable value for the name, then check
       for any alias name which may have been included within the
       value.  For example, the following commands would generate a
       2-column directory of the .TXT files:

            [c:\] alias d2 dir /2
            [c:\] set cmd=d2
            [c:\] %cmd *.txt

    ## The trailing percent sign that was traditionally required for
       environment variable names is not usually required in Take
       Command, which accepts any character that cannot be part of a
       variable name (including a space) as the terminator.
       However, the trailing percent can be used to maintain
       compatibility.
  -139-



       The trailing percent sign is needed if you want to join two
       variable values.  The following examples show the possible
       interactions between variables and literal strings.  First,
       create two environment variables called ONE and TWO this way:

            [c:\] set ONE=abcd
            [c:\] set TWO=efgh

       Now the following combinations produce the output text shown:

            %ONE%TWO            abcdTWO   ("%ONE%" + "TWO")
            %ONE%TWO%           abcdTWO   ("%ONE%" + "TWO%")
            %ONE%%TWO           abcdefgh  ("%ONE%" + "%TWO")
            %ONE%%TWO%          abcdefgh  ("%ONE%" + "%TWO%")
            %ONE%[TWO]          abcd[TWO] ("%ONE%" + "[TWO]")
            %ONE%[TWO]%         abcd[TWO] ("%ONE%" + "[TWO]%")
            %[ONE]%TWO          abcdefgh  ("%[ONE]" + "%TWO")
            %[ONE]%TWO%         abcdefgh  ("%[ONE]" + "%TWO%")

    ## If you want to pass a percent sign to a command, or a string
       which includes a percent sign, you must use two percent signs
       in a row.  Otherwise, the single percent sign will be seen as
       the beginning of a variable name and will not be passed on to
       the command.  For example, to display the string "We're with
       you 100%" you would use the command:

            echo We're with you 100%%

       You can also use back-quotes around the text, rather than a
       double percent sign.  See page 172 for details.

TC16   Due to the method Take Command/16 uses to start applications,
       it normally passes the original Windows environment to
       application programs.  As a result, applications will not
       "see" changes or additions you may have made to the
       environment from within Take Command.  You can alter the
       default behavior by using the START /E command (page 394) to
       start applications.  See page 75 for complete details on how
       Take Command/16 passes the environment to applications.


       Configuration Variables

       The following environment variables have special meanings in
       Take Command.

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



            CMDLINE is the fully expanded text of the currently
            executing command line.  CMDLINE is set just before
            invoking any .PIF, .COM, .EXE, .BTM, .BAT, or .CMD file.
            If a command line is prefaced with an "@" to prevent
            echoing (see page 61), 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.
            See page 259 for a complete description of the format of
            this variable.

            COMSPEC contains the full path and name of the
            character-mode command processor.  Take Command uses it
            when starting a character-mode or console session (e.g.,
            from the Apps menu).

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

                 [c:\] alias copy = `*copy /r`

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

                 [c:\] alias copy = `*copy %copycmd`

            DIRCMD  is used by some versions of COMMAND.COM and
            CMD.EXE to hold default options for the DIR command.
            Take Command does not support this variable, but you can
            achieve the same effect with an alias.  For example, if
            you want the DIR command to default to a 2-column
            display with a vertical sort and a pause at the end of
            each page, you could use this alias:

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

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

                 [c:\] alias dir = `*dir %dircmd`

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



            PATH is a list of directories that Take Command will
            search for executable files that aren't in the current
            directory.  PATH may also be used by some application
            programs to find their own files.  See page 19 and the
            PATH command on page 351 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 356).

TC16        TEMP specifies the directory where Take Command/16
            should store temporary pipe files.  Temporary pipe files
            are not used in Take Command/32 and Take Command for
            OS/2.

TC32   Under Windows NT, Take Command/32 uses the environment to
       keep track of the default directory on each drive or hard
       disk volume.  DOS, Windows 95, and OS/2 keep track of the
       default directory for each drive letter internally; Windows
       NT does not.  Take Command/32 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 Take Command.


     ##Internal Variables

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

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

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

            [c:\] echo %variablename

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



       Some variables have constant values (for example, _MOUSE is
       always 1 in Take Command/32 and Take Command for OS/2).
       These variables are included for compatibility with 4DOS,
       4OS2, or 4NT, to make it easier to write batch files and
       aliases which work with all of our command processors.

       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 387) or the UpperCase directive in
       the .INI file (see page 189).  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 Take
       Command.

       A few examples of internal variable usage are located at the
       end of the lists, on page 149.  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          _GDIFREE
          _MOUSE         _SYSFREE       _USERFREE      _WIN
          _WINDIR        _WINSYSDIR     _WINTITLE      _WINVER

       Command processor status:

          _4VER          _BATCH         _BATCHLINE     _BATCHNAME
          _DNAME         _HLOGFILE      _LOGFILE       _PID
          _PIPE          _PPID          _PTYPE         _SHELL
          _SID           _TRANSIENT
  -143-



       Screen, color, and cursor:

          _BG            _CI            _CO            _COLUMN
          _COLUMNS       _FG            _ROW           _ROWS
          _SELECTED      _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.

       _? 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 Take Command/32 and Take
       Command for OS/2), both of the commands below will send a
  -144-



       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.  For example, if the command separator
       is an ampersand [&] (the default in Take Command/32 and Take
       Command for OS/2), both of the commands below will display
       "Hello" on one line and "world" on the next.  However, if the
       command separator has been changed the first command will
       display "Hello & echo world", while the second command will
       continue to work as intended.

            echo Hello & echo world
            echo Hello %+ echo world

       _4VER is the current Take Command version (for example,
       "3.0").  The current decimal character is used to separate
       the major and minor version numbers (see DecimalChar on page
       183 for details).

       _ANSI is "1" if Take Command's ANSI support is enabled, and
       "0" if it is not.  To enable ANSI support use the Display
       page of the configuration dialogs, the ANSI directive in the
       .INI file, or the SETDOS /A command.  See page 90 for more
       information on ANSI support.  See the ANSI Codes Reference in
       the Reference section of the online help for information on
       the ANSI codes supported by Take Command.

TC16,  _APMAC is the Advanced Power Management AC line status ("on-
TCOS2  line", "off-line", or "unknown").  An empty string is
       returned if APM is not installed on your system.

TC16,  _APMBATT is the Advanced Power Management battery status
TCOS2  ("high", "low", "critical", "charging", or "unknown").  An
       empty string is returned if APM is not installed.

TC16,  _APMLIFE is the Advanced Power Management remaining battery
TCOS2  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.
  -145-



       _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 letters of the
       current background screen output color (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 387 and CursorIns on page 183).

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

       _CODEPAGE is the current code page number.

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

       _COLUMNS is the current number of virtual screen columns (for
       example, "80").  See page 33 for additional details on the
       virtual screen width.

       _COUNTRY is the current country code.

       _CPU is the CPU type:

            386   i386
            486   i486
            586   Pentium
            686   Pentium Pro

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

       _CWDS has the same value as CWD, except it always 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 always 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").
  -146-



       _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 184), or with the SETDOS
       /D command (see page 384).

       _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.  To differentiate between different versions of
       Windows within Take Command/16 and Take Command/32, use the
       _WIN variable (see below).

       _DOSVER is the current operating system version (for example,
       "3.10" for DOS plus Windows 3.1, or "4.00" for Windows 95 or
       Windows NT).  The current decimal character is used to
       separate the major and minor version numbers (see DecimalChar
       on page 183 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).

TC16   _DPMI returns the DPMI version number, or "0" if DPMI isn't
       present. (See the Glossary in the Take Command/16 online help
       system for a short description of DPMI.)

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

       _FG is a string containing the first three letters of the
       current foreground screen output color (for example, "Whi").
  -147-



TC16   _GDIFREE is the percentage of free Windows GDI resources.
       This information is also displayed on the Take Command/16
       status bar.

       _HLOGFILE returns the name of the current history log file
       (or an empty string if LOG /H is OFF).

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

       _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 336 for
       information on logging.

       _MINUTE is the current minute (0 - 59).

TC16   _MONITOR is the monitor type ("mono" or "color").

       _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 returns the actual mouse state in Take
       Command/16.  It always returns "1" in Take Command/32 and
       Take Command for OS/2

       _NDP is the coprocessor type:

            0     no coprocessor is installed
            387   80387, 80486DX, 80487, Pentium, or Pentium Pro

TC32,  _PID is the current process ID number.
TCOS2

TC32,  _PIPE is "1" if the current process is running inside a pipe,
TCOS2  and "0" otherwise.

TCOS2  _PPID is the process ID number of the parent process.

TCOS2  _PTYPE is the current OS/2 process type.  It is included for
       compatibility with 4OS2, but will always return "PM" in Take
       Command for OS/2.

       _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").  See page 33 for additional details on screen size.

       _SECOND is the current second (0 - 59).
  -148-



       _SELECTED returns the first line of text highlighed in the
       Take Command window.  If no text has been highlighted,
       SELECTED returns an empty string.

       _SHELL is the current shell nesting level.  The first copy of
       Take Command is shell level "0", and each subsequent copy
       increments the level by 1.

TCOS2  _SID is the session ID number.

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

TC16   _SYSFREE is the percentage of free Windows System resources.
       This information is also displayed on the Take Command/16
       status bar.

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

TC16   _USERFREE is the percentage of free Windows User resources.
       This information is also displayed on the Take Command/16
       status bar.

TC16   _WIN is the current Microsoft Windows version and mode:

            2       Windows 3.x in 386 enhanced mode
            3       Windows 3.x in real or standard mode
            20      WIN-OS/2

TC16,  _WINDIR returns the pathname of the Windows directory.
TC32

TC16,  _WINSYSDIR returns the pathname of the Windows system
TC32   directory.

       _WINTITLE returns the title of the current window.

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

       _XPIXELS returns the physical screen horizontal size in
       pixels.

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



       _YPIXELS returns the physical screen vertical size in pixels.


       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 online help, or
       the EXAMPLES.BTM file which came with your command processor.

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

       Store the current date and time in a file, then save the
       output of a DIR command in the same file:

            echo Directory as of %_date %_time > dirsave
            dir >> dirsave

       Use the IFF command to check whether there are enough
       resources free before running an application:

            iff %_GDIFREE lt 40 then
               echo Not enough GDI resources!
               quit
            else
               d:\mydir\myapp
            endiff

       Call another batch file if today is Monday:

            if "%_DOW" == "Mon" call c:\cleanup\weekly.bat


     ##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 167.  For a more comprehensive set
  -150-



       of examples see the online help, or 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:

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

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



    !  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, unless
       otherwise noted under the individual functions!  If you use
       them with any other file handle you may damage other files or
       hang your system.

       A number of functions accept a file attribute string to help
       determine which files to process (see page 16 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 Take Command.

       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        @MASTER        @READSCR
  -152-



       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        @TRUENAME
          @UNIQUE

       File names:

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

       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

       Input Dialog Boxes

          @GETDIR        @GETFILE

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



       disable certain special characters with the SETDOS /X command
       (see page 388).  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.

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

       @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 151 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 any of the attributes 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).  If the file does not exist, @ATTRIB will return an
       empty string.

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



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

       @CONVERT[input, output, value]:  Converts a numeric string
       (value) from one number base (input) to another (output).
       Valid bases range from 2 to 36.  The value must be between 0
       and 2**32-1 (2,147,483,647).  No error is returned if value
       is outside that range.  For example, to convert "1010101"
       from binary to decimal, use this command:

            %@convert[2,10,1010101]

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

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

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

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

       @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]:  Under Take Command/16, returns the amount of
       free space in Windows' global heap.  Under Take Command/32,
       returns the amount of free physical memory.  Under Take
  -155-



       Command for OS/2, returns the size of the largest free memory
       block (either in physical or virtual 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 150 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 150 for information on acceptable date formats.

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

TCOS2  @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]

TCOS2  @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!

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

       To ensure that your @EVAL expressions are interpreted
       correctly, spaces should be placed on both sides of each
       operator, for example:

            %@eval[(20 %% 3) + 4]
  -156-



       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 from the Options 2 page of the configuration dialogs,
       with the EvalMax and EvalMin .INI file directives (see page
       184), or with the SETDOS /F command (see page 384).  You can
       alter the decimal character from the Options 1 page of the
       configuration dialogs, with the DecimalChar directive (see
       page 183), or with the SETDOS /G command.

       You can alter the precision for a single evaluation with the
       syntax @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.

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

TCOS2  @EXETYPE[filename]:  Returns the application type as a
       string:
  -157-



            DOS            DOS .COM, .EXE, or .BAT file (OS/2 2.x
                      only)
            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,
       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 151 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 volumes which support long file
       names, the extension can be up to 64 characters long.  On
       traditional FAT drives it can be up to 3 characters long.

       @FILEAGE[filename]:  Returns the date and time of the file as
       a single numeric value, but can not be used for date and time
       calculations as it is not returned in identifiable units.
       The number can be used to compare the relative ages of two or
       more files.  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 151.

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



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

TC32,  @FILEOPEN can also open named pipes.  The pipe name must
TCOS2  begin with \\.\pipe\ in Take Command/32, or \pipe\ in Take
       Command for OS/2.  @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 Windows NT or OS/2 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 151.

       @FILES[filename [,-nrhsda]]:  Returns the number of files
       that match the filename, which may contain wildcards and
       include lists.  Returns "0"if no files match.  The filename
       must 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 151 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 151.

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



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

TC32,  @FINDCLOSE[filename]:  Signals the end of a @FINDFIRST /
TCOS2  @FINDNEXT sequence.  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 150 about quoting
       returned long filenames, and the note on page 151 for more
       information on the attribute argument.

TC32,  After @FINDFIRST or the last @FINDNEXT, you must use
TCOS2  @FINDCLOSE 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
  -160-



       page 151 for details).  Returns an empty string when no more
       files match.

TC32,  Be sure to read the notes under @FINDFIRST above regarding
TCOS2  the need to close your directory search handle with
       @FINDCLOSE, and the notes on page 150 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"

TC32,  @FSTYPE[d:]:  Returns the file system type for the specified
TCOS2  drive.  Under Take Command for OS/2, @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.  Take Command/32 will
       normally return "FAT", "HPFS", CDFS", or "NTFS" for a drive
       that uses the Windows NT file system.  LFN drives will return
       "FAT".

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

TC16,  @GETDIR[d:\path]:  Pops up a dialog box to select a
TC32   directory.  d:\path specifies the initial directory; if it is
       not specified, GETDIR defaults to the current directory.
       Returns the chosen directory as a string, or an empty string
       if the user selects "Cancel" or presses Esc.  The argument
       must be in quotes if it contains whitespace or special
       characters.  Be sure to read the notes on page 150 about
       quoting returned long filenames.

TC16,  @GETFILE[d:\path\filename[,filter]]:  Pops up a dialog box to
TC32   select a file.  d:\path\filename specifies the initial
       directory and filename shown in the dialog, and may include
       wildcards.  If it is not specified, GETFILE defaults to *.*
       in the current directory.  Returns the full path and name of
       the selected file or an empty string if the user selects
       "Cancel" or presses Esc.  The optional second argument
       specifies the file extension to use.  You can specify
       multiple extensions by separating them with a semicolon.  For
       example, %@getfile[c:\windows,*.exe;*.btm] lets the user
       select from .EXE and .BTM files only.  The arguments must be
  -161-



       in quotes if they contain whitespace or special characters.
       Be sure to read the notes on page 150 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
       312).  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.

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

            %@iniread[c:\tcmd\tcmd.ini,TakeCommand,history]

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

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

            %@iniwrite[c:\tcmd\tcmd.ini,TakeCommand,history,2048]

       will set the size of the command history to 2,048 bytes the
       next time Take Command 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 \WINDOWS and
       \WINDOWS\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
  -162-



       string is numbered 0; if the length is negative, the last
       character is numbered 0.  For example, %@INSTR[0,2,%_TIME]
       gets the current time and extracts the hour; %@INSTR[1,-
       2,%_TIME] extracts the seconds.  If the string includes
       commas, it must be quoted with double quotes ["] or back-
       quotes [`].  The quotes do count in calculating the position
       of the substring.  @SUBSTR (page 166) 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.

TC32   @LFN[filename]:  Returns the long filename for a short
       ("8.3") filename.  The filename may contain any valid
       filename element including drive letter, path, filename and
       extension; the entire name including all intermediate paths
       will be returned in long name format.  Be sure to read the
       notes on page 150 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.

       @LINE works with files having lines of no more than 255
       characters under Take Command/16 and 1023 characters under
       Take Command/32 and Take Command for OS/2; longer lines will
       not be counted accurately.

       The @LINE function must read each line of the file to find
       the line you request, and will therefore cause significant
       delays if used in a long loop or on a large file.  For a more
       effective method of processing each line of a file in
       sequence use the FOR command (page 292), 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 108) 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
  -163-



       @LINES[filename]:  Returns the line number of the last line
       in the file, or "-1" if the file is empty.  The first line in
       the file is numbered 0, so (for example) @LINES will return 0
       for a file containing one line.  To get the actual number of
       lines, use %@INC[%@LINES[filename]].

       @LINES works with files having lines of no more than 255
       characters under Take Command/16 and 1023 characters under
       Take Command/32 and Take Command for OS/2; longer lines will
       not be counted accurately.

       @LINES must read each line of the file in order to count it,
       and will therefore cause significant delays if used in a long
       loop or on a large file.

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

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

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

       @MONTH[mm-dd-yy]:  Returns the month number for the specified
       date (1-12).  See page 150 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 150
       about quoting returned long filenames.
  -164-



       @NUMERIC[string]:  Returns "1" if the string is composed
       entirely of digits (0 to 9), signs (+ or -), and the
       thousands and decimals separators.  Otherwise, returns "0".
       If the string begins with a decimal separator it is not
       considered numeric unless the next character is a digit, and
       there are no more decimal separators within the string.  For
       example, ".07" is numeric, but ".a" and ".07.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 150 about quoting returned long filenames.

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

       @READSCR[row, col, length]:  Returns the text displayed in
       the Take Command window at the specified location.  The upper
       left corner of the window 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 (i.e., 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,
  -165-



       %@replace[w,ch,warming] returns the string "charming."  The
       search is case-sensitive.

TC32,  @REXX[expr]:  Calls the REXX interpreter to execute the
TCOS2  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 133 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 19
       for details on the default extensions used when searching the
       PATH, the order in which the search proceeds, and the search
       of the \WINDOWS and \WINDOWS\SYSTEM directories in Take
       Command/16 and Take Command/32.)  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).

       @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 29 for details; to
       change the navigation keys see page 186).  @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.

TC32   @SFN[filename]:  Returns the fully expanded short ("8.3")
       filename for a long filename.  The filename may contain any
       valid filename element including drive letter, path, filename
       and extension; the entire name including all intermediate
       paths will be returned in short name format.

       @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,
  -166-



       enclose the entire first argument in quotes.  @STRIP will
       remove the quotes before processing the string.

       @SUBSTR[string,start,length]:  An older version of @INSTR
       (see page 161).  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" (elapsed) time for a
       stopwatch started with the TIMER command (see page 407).  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.

TC16,  @TRUENAME[filename]:  Returns the true, fully-expanded name
TC32   for a file.  TRUENAME will "see through" a JOIN or SUBST.
       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.

       @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,
       NTFS, or HPFS 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
  -167-



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

       @YEAR[mm-dd-yy]:  Returns the year for the specified date.
       See page 150 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.

       To set the prompt to show the amount of free memory (see the
       PROMPT command, page 356, 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
  -168-



       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 70),
       the Escape Character (page 110), and the Parameter Character
       (page 117).

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

            Product                Separator    Escape   Parameter

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

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

       (In this section, an up-arrow is used for the ASCII Ctrl-X
       character, numeric value 24.  The appearance of control
       characters depends on the font you use.  In many fonts Ctrl-X
       is displayed as a "block" or other non-descript character,
       but the Terminal font used by default in Take Command
       typically displays Ctrl-X as an up-arrow.)

       In your batch files and aliases, and even at the command
       line, you can smooth over these differences in three ways:

            *  Select a consistent set of characters on the Options
               1 page of the configuration dialogs (see page 45), or
               with .INI file directives (page 175).  For example,
               to set the Take Command/16 characters to match Take
  -169-



               Command/32 and Take Command for OS/2, use these lines
               in TCMD.INI:

                      CommandSep = &
                      EscapeChar = ^
                      ParameterChar = $

            *  Use internal variables that contain the current
               special character, rather than using the character
               itself (see page 141).  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
               390) 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 282) at the end of the
               batch file to restore the previous settings.

       You can also use the SETDOS command (see page 384) to change
       special characters on the command line.  However, when
       setting new special character values on the command line you
       must take into account the possibility that one of your new
       values will have a current meaning that causes problems with
       the setting.  For example, this command:

            [c:\] setdos /e^

       would not set the escape character to a caret [^] in Take
       Command/16 if the standard Take Command/16 special characters
       were currently in effect.  The ^ would be seen as a command
       separator, and would terminate the SETDOS command before the
       escape character was set.  To work around this, use the
       escape character variable %= before each setting to ensure
       that the following character is not treated with any special
       meaning.

       For example, the following sequence of commands in a batch
       file will always set the special characters correctly to
       their standard Take Command/32 and Take Command for OS/2
       values, no matter what their current setting, and will
       restore them when the batch file is done:

            setlocal
            setdos /c%=& /e%=^ /p%=$
            .....
  -170-



            endlocal

       A similar sequence can be used to select the standard Take
       Command/16 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 Take Command, which must figure out how to
       execute it.  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, Take Command 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 336), and the command did not come
       from a batch file.  Then, if the line contains multiple
       commands, the first command is isolated for processing.

       Take Command begins by dividing the command into a command
       name and a command tail.  The command name is the first word
       in the command; the tail is everything that follows the
       command name.  For example, in the command line

            dir *.txt /2/p/v

       the command name is "dir", and the command tail is " *.txt
       /2/p/v".

       Next, Take Command tries to match the command name against
       its list of aliases.  If it finds a match between the command
       name and one of the aliases you've defined, it replaces the
       command name with the contents of the alias.  This
       substitution is done internally and is not normally visible
       to you; however, you can view a command line with aliases
       expanded by pressing Ctrl-F after entering  the command at
       the prompt.

       If the alias included parameters (%1, %2, etc.), the
       parameter values are filled in from the text on the command
       line, and any parameters used in this process are removed
       from the command line.  The process of replacing a command
       name that refers to an alias with the contents of the alias,
  -171-



       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, Take Command next
       tries to match the command name with its list of internal
       commands.  If it is unsuccessful, it 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, Take Command 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, Take Command
       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 Take Command/32 and Take Command for OS/2,
       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, Take Command will perform
       the activities you have requested.  Otherwise, Take Command
       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 19).

       Once the internal command or external program has terminated,
       Take Command saves the result or exit code that the command
       generated, cleans up any redirection that you specified, and
       then returns to the original command line to retrieve the
       next command.  When all of the commands in a command line are
  -172-



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


       Argument Quoting

       As it parses the command line, Take Command looks for command
       separators (carets [^] in Take Command/16, or ampersands [&]
       in Take Command/32 or Take Command for OS/2), 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 Take Command 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:

            @echo off
            echo Arg1 = %1
  -173-



            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 206 for details.

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