TURBOBAT - Turbo Batch File Compiler
_____________________________________________________________________


DESCRIPTION

  TurboBAT allows you to compile standard DOS batch files into .COM
  binary programs.  This will greatly enhance the speed of large batch
  files by allowing them to run in native code rather than interpreted
  DOS commands. The resulting .COM files may call nested batch files
  without loosing the parent since the parent calling program is now
  no longer a batch file.


COMMAND FORMAT


  TURBOBAT [/1][/4][/A][/Dname][/I][/L][/T][/X] file[.ext]

  /1      Insert single stepping code.  The creates a version of the
          output that is useful when debugging a batch file.  When the
          output .COM program is run, it will single step through each
          line of the original program.

  /4      Supress 4DOS warning messages.  Don't report any warning
          messages generated by the use of 4DOS specific commands.

  /A      Supress all warning messges (same as /4/I/L/X).  Don't
          display any warning messages, only error messages.

  /Dname  Include full symbolic tracing information.  If NAME is
          specified the information will be sent to the named file,
          otherwise is is displayed via the standard error device.
          There must not be any spaces between /D and NAME.

  /I      Ignore nonstandard labels.  DOS supports labels up to 8
          characters long for use with the goto statement.  Many
          people use the label as a comment field rather than a label
          and this can cause problems when a label that is used in a
          non standard fashion shows up during the compile stage of
          the batch file. DOS will noramally just ignore this error.

  /L      Relaxed label length checking.  The normal label size
          recognized by DOS is 8 characters.  In many cases people use
          the : as a place holder for the program without ever
          referencing the label. The problem is that if you have more
          than one long label name where the first 8 digits match
          another label, the file won't compile because it will look
          as though you have duplicate labels.  This switch relaxes
          that limit.

  /T      Compile with line number TRACE information.  The line number
          information is displayed via the standard error device.
          When running the output program compiled with this option on
          you will get a display of each line number as the program is
          running. This is useful when trying to determine where a
          program is failing.


TURBOBAT - Turbo Batch File Compiler
_____________________________________________________________________

  /X      Supress extension warning messages.  Normally during
          compilation, TurboBAT will warn you about any lines that
          make use of commands that are supported by the compiler but
          are not supported by DOS. Using the /X will tell TurobBAT
          not to warn you about any BATCH files that will not function
          under normal DOS conditions.

  /B-     Use ANSI escape sequences instead of the BIOS.  The default
          screen I/O is now handled by making calls to the video BIOS.
          This insures that the compiled batch file will work on any
          machine with or without ANSI.SYS installed.  The drawback
          to this is that BIOS calls are much slower than ANSI calls.
          If you know that the machine that will be running the
          compiled program then using the /B- command will speed up
          the video calls.


NOTES

  TurboBAT is a multipass batch file compiler.  It takes interpreted
  DOS batch files and turns them into binary programs that can execute
  up to as much as 4 times faster than normal batch files.  While
  supporting all of the normal DOS functions that can be called from
  within a batch file, TurboBAT also provides many additional features
  including support for many 4DOS/NDOS commands.


EXTENDED BATCH COMMANDS

  TurboBAT support many commands beyond those supported in normal
  batch files. Some of these commands are in support of J.P. Softwares
  4DOS Batch Enhancements and others are to replace small external DOS
  utilities.



TURBOBAT - Turbo Batch File Compiler
_____________________________________________________________________


INTERNALLY SUPPORTED COMMANDS


  DOS Commands and batch file commands that are directly supported by
  TurboBAT and require no external programs are:


  %?     "Internal" evironment variable.  Expands to the error level
         of the last executed program as a string.

         Example:  SET LASTERROR=%?


  BEEP   BEEP [frequency duration ...]

         Sounds a tone of the specified frequency for the duration in
         clock ticks.  The defaults are 440Hz (A below middle C) for 2
         clock ticks (about 1/4 second).

         The list of tones and durations can be repeated on a single
         line. This table is identical to the 4DOS tone table:

          ͻ
           C        131    262    523    1040    2093 
           C#/Db    139    277    554    1103    2217 
           D        147    294    587    1176    2349 
           D#/Eb    156    311    622    1241    2489 
           E        165    330    659    1311    2637 
           F        175    349    698    1391    2794 
           F#/Gb    185    370    740    1488    2960 
           G        196    392    784    1568    3136 
           G#/Ab    208    415    831    1662    3322 
           A        220    440    880    1760    3520 
           A#/Bb    233    466    932    1866    3729 
           B        248    494    988    1973    3951 
          ͼ


  BOOT   BOOT [WARM | COLD]

         Boots the computer.  If no options are specified or if WARM
         is specified a WARM boot will occur.  If COLD is specified
         the computer will go through the entire cold boot process.
         Under Desqview, a warm boot will only close the window.

  CDD    CDD drive:path

         Changes subdirectories and drives.  This command will change
         the current directory and drive to the one specified in
         [drive:path] and make the current DOS drive equal to the
         value in [drive]. Normally within dos the CD command will
         change directories on any drive that you specify but will
         keep the current drive the same. CDD allows you to switch to
         that drive rather than stay on the current drive.

TURBOBAT - Turbo Batch File Compiler
_____________________________________________________________________


  CHDIR/CD  CD path
            CD drive:path

            Change the current directory as specified in path.  If a
            drive is specified than change the current directory of
            that drive to the directory specified in path.

  CLS       CLS [[bright] [blink] fg on bg]

            Clears the screen and optionally sets the screen color.
            When setting the colors the syntax is identical to the
            COLOR command.

  COLOR     COLOR [bright] [blink] fg ON bg

            Uses ANSI escape squences to set the screen color. Only
            the first three letters of each command word are actually
            significant.  The following colors are allowed:

              BLAck     BLUe      GREen     RED
              MAGenta   CYAn      YELlow    WHIte

            Example:  COLOR BRIGHT WHITE ON BLUE


  DELAY     DELAY [seconds]

            Pauses for the specified interval in seconds.  If no
            duration is given it will pause for 1 second.



  ECHO      ECHO [message]

            If the /D switch was used at compile time you can enable
            or disable command echoing with ECHO OFF and ECHO ON.
            ECHO without any text will indicate if the /D switch was
            used when the file was compiled, not the current status of
            command echoing. To display a blank line use "ECHO:" or
            "ECHO.".


TURBOBAT - Turbo Batch File Compiler
_____________________________________________________________________

  ECHOS     ECHOS [message]

            Displays the message without appending a cr/lf to the end
            of the message like ECHO does.  (used to be ECHONLN but was
            updated to match the 4DOS command.


  ELSE      If the IFF condition was false the lines from ELSE to
            ENDIFF will be executed.

            See Also IFF.


  ELSEIFF   ELSEIFF condition [THEN]

            Similar structure to the IFF command. If the previous IFF
            was false and the current condition is true the code
            following will be executed to the next ELSE, ELSEIFF, or
            ENDIFF statement.  Each use of ELSEIFF counts as a nesting
            level.  The compiler actually converts this command into
            logical ELSE^IFF^ENDIFF statements.

            See Also IFF.

  ENDIFF    Terminates an IFF statement.

            See Also IFF.


  EXIT      EXIT is used when at the DOS level if you are running
            within a shelled version of the command interpretor and
            you wish to exit the shelled session.  The EXIT command is
            ignored by TurboBAT. See also QUIT.


  FOR       FOR %%var IN (file list) [DO] command

            Allows more than a single letter as the loop variable. Can
            be nested.  The loop variable can be tested from other
            lines by treating it as a normal environment variable.
            The word "DO" is required by DOS but is optional under
            4DOS and Turbobat.


TURBOBAT - Turbo Batch File Compiler
_____________________________________________________________________

  GOTO   GOTO label

         Will jump control to the label.  Labels are marked as a line
         begining with a :.


  GOSUB  GOSUB label

         Calls a label in the current batch file as a subroutine. Must
         have a matching RETURN statement. The end of the batch file
         does NOT act as a RETURN.


  IF     IF [NOT] first (== | EQ | NE | LT | LE | GT | GE) second command
         IF [NOT] ERRORLEVEL [== | EQ | NE | LT |LE | GT | GE] value command
         IF [NOT] ENVFREE [== | EQ | NE | LT |LE | GT | GE] value command
         IF [NOT] EXIST filename command.
         IF [NOT] ISDIR path command

         EQ (equal), also '==' and '='
         NE (not equal),
         LT (less than),
         LE (less or equal),
         GT (greater than),
         GE (greater or equal).

         If no compare command is used for ERRORLEVEL or ENVFREE the
         default of GE will be used.

         EXIST tests for the existence of a file.

            IF EXIST my.cfg GOTO continue
            ECHO Configuration file is missing
            QUIT 99
            :continue

         ISDIR tests if the given path specification is an existing
         subdirectory.

            IF NOT ISDIR \work MD \work

         ENVFREE tests the available environment space.

            IF ENVFREE LT 123 ECHO Insufficient environment space



TURBOBAT - Turbo Batch File Compiler
___________________________________________________________


  IFF    IFF condition [THEN]

         If the condition is true the lines up to ELSE, ELSEIFF or
         ENDIFF (whichever appears first) will be executed. IFF
         statements may be nested up to 15 levels deep.  See also IF.

                IFF %? EQ 0 THEN
                  GOTO CONTINE
                ELSEIFF %? EQ 99
                  THEN GOTO CRITICAL
                ELSE
                  GOTO ERROR
                ENDIFF


  INKEY  INKEY [/Wn] [message] %%var

         Gets a single keystroke and places it in the environment.
         %%var is the environment variable that will be assigned the
         keystroke. If /W is specified the command will wait up to
         that many seconds, e.g. /W10. It will also optionally display
         a message.  If a wait of zero is used (/W0) the command will
         return immediately if no keystrokes are pending.  The wait
         period can be specified in the environment, but the /W but be
         present on the line at compile time, e.g.:

             inkey /w%delay Press any key: %%key

         Displayable keystrokes (characters above the space) are
         stored as their corresponding character.  Keystrokes that do
         not have a corresponding character are displayed as a number,
         e,g. the carriage return as "13".  Extended keystrokes such
         as F1 are stored with a preceding '@', (@59 for F1).


  INPUT  INPUT [/Wn] [message] %%var

         Gets a string and places it in the environment.  %%var is the
         environment variable that will be assigned the string.  The
         string is terminated by a carriage return or end of file mark
         (^Z).  Extended keystrokes are ignored.  /Wn is the optional
         maximum time in seconds to wait for the first keystroke.
         Once a keystroke is entered this command will not time out.

  MKDIR  MKDIR [pathname]
  MD     MD [pathname]

         Will create a new directory of PATHNAME.


  PATH   Displays or Sets the Path.


TURBOBAT - Turbo Batch File Compiler
___________________________________________________________



  PAUSE   PAUSE [message]

          Displays an optional message.  If no message is specified the
          default of "Press a key when ready..." is used.  In addition,
          a CR/LF is not output until after the key is pressed.


  PROMPT  Displays or Sets the DOS Prompt


  QUIT    QUIT [exitcode]

          Unconditionally halts the compiled batch file.  If no
          exitcode is specified, zero will be used.  The exit code can
          refer to an environment variable.  If the variable is not a
          number or does not exist zero will be used.  Examples:

                SET var=1
                QUIT %var

          Exits with 1.

                SET var=test
                QUIT %var

          Exits with 0 because %var is not a number.


  REM     REM is the standard DOS Remark field.  REM lines are ignored
          by the TurboBAT Compiler.


  REPEAT/
  UNTIL   Similar to the Pascal structure.  May be nested up to 15
          deep. Redirection is not allowed on a line containing REPEAT
          or UNTIL.

                REPEAT
                  ECHO %1
                  SHIFT
                UNTIL "%1" EQ ""


  RETURN  Return from a subroutine call.  If no subroutines are
          pending it will terminate the batch file with an exit code of 255.

  RD
  RMDIR   Remove Directory.  This will remove the directory specified
          as long as there are no files in it.




TURBOBAT - Turbo Batch File Compiler
_____________________________________________________________________


  SCREEN  SCREEN row column [message]

          Positions the cursor using ANSI sequences and displays an
          (optional) message.  The cursor coordinates are 0 based, the
          normal range being 0-24 rows and 0-79 columns.


  SCRPUT  SCRPUT row col [bright][blink] fg ON bg message

          Writes the message at the specified screen coordinates using
          the specified colors.  The cursor position is restored to
          the position before the command.  ANSI escape sequences are
          used throughout.

  SET     Alone, Set will display the current environment variables,
          or followed by an environment variable, set will set the
          environment variable to the given value.


  SHIFT   Same as standard DOS.  I will be expanding this command for
          4DOS compatibility to accept a shift factor, with support
          for a negative number which will get back previously shifted
          parameters.

  SINGLESTEP    SINGLESTEP ON | OFF

          Enables or disables single stepping.  The /1 compiler switch
          must be used for this command to have any effect.  The
          options are resolved at compile time so you can not use an
          environment variable or command line parameter to set the
          status.



  TEXT/
  ENDTEXT The text that follows, up to ENDIFF will be displayed as if
          each line was preceded by an ECHO. Output redirection is
          more efficient using this command instead of individually
          redirected ECHO commands since the file will only be opened
          and closed once, while the file will be opened and closed
          for each ECHO command.

                TEXT
                This could be a menu
                or it could be help information
                ENDTEXT

                TEXT >dummy
                This text will be sent to the redirection file.
                Up to, but not including the ENDTEXT command.
                ENDTEXT



TURBOBAT - Turbo Batch File Compiler
_____________________________________________________________________


  UNSET   Deletes the environment variable from the master environment.

                UNSET RESULT


  WHILE/
  WEND    Similar to the Pascal structure. May be nested up to 15
          deep. Redirection is not allowed on a line containing WHILE
          or WEND.

                WHILE "%1" NE ""
                  ECHO %1
                  SHIFT
                WEND





COMMANDS HANDLED BY CALLING THE COMSPEC


  These commands are supported by calling COMMAND.COM:

  CALL, DIR, DEL, REN, VER, VOL, CTTY, CHCP, TYPE, COPY, DATE, TIME,
  ERASE, BREAK, RENAME, DELETE, VERIFY, COMMAND


  These commands will only work if 4DOS is the active COMSPEC:

  FREE, DRAWBOX, DRAWHLINE, DRAWVLINE, MEMORY



TURBOBAT - Turbo Batch File Compiler
_____________________________________________________________________

COMPILER ERROR MESSAGES

  TurboBat contains a library of internal error messages and will
  display the error number and message when an error or warning is
  found.  Files with just warnings will compile, files with errors
  will not compile.

  Warning Messages / Error Messages

   1  Duplicate label

      Each label must be unique for a file to compile correctly.  Use
      the /I to relax label checking when using the : for marking
      comments.


   2  Duplicate label (check size)

      Sometimes labels are used as comments in batch files.  If a
      label is unique, but after the 8th character the compiler won't
      pick it up as unique since DOS only supports the first 8
      characters of a label.  You can use the /L option to relax label
      length checking.


   3  Redirection not allowed here

      TurboBAT does not support the redirection of output or input at
      the location specified.


   4  Invalid IF statement

      The IF statement is using invalid syntax, check the manual for
      usage of IF and IFF commands.


   6  Invalid FOR statement

      The FOR statement is using invalid syntax, check the manual for
      the usage of the FOR command.


   7  EXIT can not be used in a compiled batch file

      EXIT is normally used to abort a batch file at any location.
      You can not do this with a compiled batch file.  Replace usage
      of EXIT with a GOTO command that jumps to a label at the end of
      the batch file.

   8  Label not Found.

      A reference was made to a label that does not exist.


TURBOBAT - Turbo Batch File Compiler
_____________________________________________________________________
   9  Program is too large

      The output of the compiled batch file is exceeding 64k bytes.
      TurboBAT currently only supports the .COM format of programs
      under 64k bytes large.  Reduce the commands in your batch file
      if possible.


  10  REPEAT nested too deeply

      You have too many levels of nesting with a REPEAT Loop.  Try
      breaking the repeat loop out of a nested piece of code.


  11  Unmatched UNTIL

      The UNTIL statement found has no opening REPEAT command.


  12  WHILE nested too deeply

      You have too many levels of nesting with a WHILE Loop.  Try
      breaking the while loop out of a nested piece of code.


  13  Unmatched WEND

      The WEND statement found has no opening WHILE command.


  14  Label longer than nn characters, truncated

      Labels that are longer than supported by TurboBAT will be
      truncated to the maximum characters allowed.


  15  IFF nested too deeply

      You have too many levels of nesting with an IFF Loop.  Try
      breaking the iff loop out of a nested piece of code.


  16  Unmatched ELSE statement

      The ELSE statement found has no opening IF or IFF command.


  17  Unmatched ENDIFF statement

      The ENDIFF statement found has no opening IFF command.

  18  Unexpected end of file, no matching ENDTEXT

      A TEXT command was used without an ENDTEXT command and TurboBAT
      read to the end of the input file before finding an ENDTEXT and
      could not finish the compile.

TURBOBAT - Turbo Batch File Compiler
_____________________________________________________________________


  19  Unmatched ENDTEXT

      The ENDTEXT statement found has no opening TEXT command.


  20  Syntax error

      Invalid command syntax was used.  Consult the TurboBAT manual
      for command usage.


  21  4DOS Specific command used

      A command was used that is normally only supported by the use of
      4DOS.  Make sure that the target system has 4DOS installed or
      the resulting .COM file may not work properly.


  22  TurboBAT extension used

      This is notifying you that a non standard command was used
      inside the batch file.  There is no problem with this usage,
      except that the .BAT file might not work unless compiled with
      TurboBAT.


  23  Open REPEAT statement

      A REPEAT command was used with no UNTIL command to close it.


  24  Open WHILE statement

      A WHILE command was used with no WEND command to close it.


  25  Open IFF/ELSEIFF statement

      An IFF or ELSEIFF statement was used with no ENDIFF to close it.


  26  Command not supported in this version of Turbobat

      A command was used that is not supported by TurboBAT.  Contact
      Foley Hi-Tech Systems for details on solving this problem.


  99  Internal error - please contact Foley Hi-Tech Systems

      An internal processing error has occured with TurboBAT.  Contact
      Foley Hi-Tech Systems technical support.



