                             BATCHMON v2.1
                        The simple batch monitor
                                   by
                  Ian "I didn't really do this" Lepore

-----------------------------------------------------------------------
                             Release Notes
-----------------------------------------------------------------------

Version 2.1 added the following new features:

     - Support for environment strings.
     - The ability to change the default and exe paths.
     - It  can be compiled with a  vanilla Sozobon  C  setup.   Anything   
       using  my custom  libraries  has been  converted  to  the   dLibs   
       functions, or has been included in source form.

Version 2.0 added the following new features:

     - Big batch files.
     - A couple built-in commands to help lighten up on floppy disk I/O.
     - Something that works well with TurboST's bugs.

-----------------------------------------------------------------------
                              Batch Files
-----------------------------------------------------------------------

Batch files are a series of command statements with optional  parameters 
to be processed by the command.   Some commands are processed internally 
by the monitor; anything that doesn't fall into the internal category is 
assumed  to be a program command,  and it is Pexec'd.   Batch files  can 
contain variables,  and the value of those variables can be supplied  at 
runtime,  with  the batch monitor substituting the runtime text for  the 
variable  symbols  as  they are encountered  in  the  batch  file.   The 
commands  in the batch file are not case-sensitive.   The first word  on 
each  line  (command  or  program name)  will  be  forced  to  uppercase 
internally,  but  the rest of the command line (parms to passed  to  the 
called  program)  are NOT changed in terms  of  case.   When  specifying 
program names, a drive and path specification may be included as part of 
the program name, if necessary.

-----------------------------------------------------------------------
                           Internal Commands
-----------------------------------------------------------------------

The batch monitor recognizes the following internal commands:

     COM
     REM      -  These  commands are totally ignored,  allowing  you  to 
                 insert  comments in your batch files.  In  addition  to 
                 these,  any line starting with '!', '*', or ';' will be 
                 considered  a  comment,  but the character MUST  be  in 
                 column 1.

     DEL
     DELETE   -  These commands delete 1-10 files,  as specified on  the 
                 rest of the command line.
                  Example:
                    DEL     myfile1.txt myfile2.txt  
                    DELETE  %1.tmp %1.obj
     WAIT
     PAUSE    -  These commands stop and wait for you to hit a key.  Any 
                 parms on the line will be ignored,  so you can  include 
                 comments on the line that pauses the run.

     RCSTOP
     NORCSTOP -  These  commands turn on or off a flag which  will  stop 
                 and prompt you if any program returns a non-zero return 
                 code.   Some  compiler pieces are smart enough to  exit 
                 with  a non-zero code if errors occurred.   Some  badly 
                 written programs always (or randomly) return  non-zero.  
                 You can use these codes to toggle the status on and off 
                 around such programs.   When the batch montitor starts, 
                 the default is RCSTOP.
                  Example:
                   NORCSTOP    Stupid 'badprog' always returns 1!
                   BADPROG.PRG parm1 %1 %2 parm2
                   RCSTOP      Resume RC checking.
                 Note that parms are ignored, so you can put comments on 
                 same line as the commands.

     SETENV   -  This  command allows access to the  environment  string 
                 that will be passed to all called  programs.   Whatever 
                 follows  the 'setenv' on the command line is passed  to 
                 the  dLibs 'putenv()' function as is.   The  rules  for 
                 'putenv' are as follows:
                    <VARIABLE>
                    <VARIABLE>=<string of characters>
                 The  first  format (just a variable name)  will  remove 
                 that variable from the current env string if it exists.  
                 The  second  format allows you to set a variable  to  a 
                 string.  
                  Example:
                    SETENV PATH=c:\bin\;a:\
                    SETENV INCLUDE
                 (I  have no idea whether this command  works.   If  the 
                 dLibs  putenv() function works,  then this  should.   I 
                 have no easy way of testing it, though.)

     EXEPATH  -  This  command  allows  you  to set  a  new  path  which 
                 BATCHMON  will  use to find the programs  specified  in 
                 the  rest of the batch file.   Note that this does  not 
                 affect  the  DOS  default path;  any  programs  run  by 
                 BATCHMON will inherit the current default path  (either 
                 the path BATCHMON was run from,  or the path  specified 
                 in  the  last 'DEFPATH'  command).   The  pathname  you 
                 specify  for this command may include a drive,  and  it 
                 may  end  with  a  '\'  character  or  not,   at   your 
                 preference.
                  Examples:
                    EXEPATH c:\bin
                    EXEPATH \sozobon\bin
                    EXEPATH
                 The  last example is equivelant to specifying  '\';  it 
                 sets the path to the root of the current default drive.

     DEFPATH  -  This  command sets the DOS default  path.   Unless  you 
                 have  used  the  EXEPATH  command,   this  will  affect 
                 BATCHMON  (and where it will look for the programs  you 
                 want run). It will always affect the programs called by 
                 BATCHMON;   those   programs  will  also  inherit   the 
                 specified default path.   If you specify a drive letter 
                 as  part of the path,  that drive will become  the  new 
                 default  drive.    You  may  specify  a  trailing   '\' 
                 character or not, as you prefer.
                  Examples:
                    DEFPATH \data
                    DEFPATH d:\source\
                    DEFPATH
                 The  last example is equivelant to specifying  '\';  it 
                 sets the path to the root of the current default drive.

Internal commands (and indeed, anything) can be entered in upper, lower, 
or  mixed  case in the batch file.   The first word on  each  line  (the 
command or program name) is upper-cased by the program  internally,  and 
the rest of the text and variables are left in the original case.   Note 
that the desktop uppercases things typed into a .TTP dialog box.

-----------------------------------------------------------------------
                               Variables
-----------------------------------------------------------------------

Variables  in  the  batch file are %0  through  %9.   The  percent  sign 
followed by a single digit will always be interpreted as a variable.   A 
percent  sign  followed by anything else is not,  so you don't  have  to 
double  up on percent signs to get a single one,  as with some  systems.  
On the other hand,  there is no way to include the literal text "%1", it 
will always be interpreted as a variable.  

The variable '%0' is a special case:   It is the name of the batch  file 
that's running.   Note that it is the name that was passed to the  batch 
monitor,  or  typed by the user,  and if it didn't have ".BAT" on it  at 
that time,  it won't at substitution (even if the monitor had to tack on 
a ".BAT" to open the file successfully,  this doesn't find its way  into 
'%0').  I dunno if the '%0' variable will ever be useful to anyone,  but 
it's a sort of freebie in the way the parser works).

The  variables '%1' through '%9' correspond to the first  through  ninth 
words  you  passed  to the batch monitor at startup (or  typed  in  when 
prompted).   By 'words' I mean groups of characters delimited by spaces.  
I think it's about time for an example.   Suppose you have the following 
batch file:

     COM      XMPL.BAT - A stupid example file.
     compile  %1.c
     asm      %2.s
     link     newprog=startup %1.obj %2.o %3 

And then suppose you click on BATCHMON.TTP from the desktop,  and  enter 
the  following in the dialog box (or you enter BATCHMON in  your  shell, 
followed by these parms):

     xmpl cprog asmprog some,link,parms

Then the batch monitor would do the substitutions as follows:
 
     COM      XMPL.BAT - A stupid example file.
     compile  cprog.c
     asm      asmprog.s
     link     newprog=startup cprog.obj asmprog.o some,link,parms

Notice that the commas weren't delimeters...to the batch monitor.   They 
are to most linkers, and that can be handy.

If your batch file contains a '%3' variable (for example),  and you only 
typed 2 parms at runtime,  you will see a warning message,  and the '%3' 
will disappear.  (You will only be warned on the first occurance of each 
non-existant variable.)  This lets you implement 'optional' variables in 
your batch files.   In the above example,  if you didn't enter the third 
parameter ('some,link,parms'), the last line would have substituted to:

     link     newprog=startup cprog.obj asmprog.o

The first word on a line in a batch file cannot be a variable (it  won't 
get substituted);  that is, you can't execute a command or program via a 
variable-supplied name.

-----------------------------------------------------------------------
                             General Notes
-----------------------------------------------------------------------

The  batch  monitor can be run as a .TOS or .TTP.   If you run  it  from 
desktop as a .PRG you'll get ugly output.   You can run it from within a 
shell,  if  the shell doesn't have a batch/script facility.   The  first 
parm  you  pass to the BATCHMON program should be the name  of  a  batch 
file, which usually ends in .BAT (it don't have to, but if you just pass 
the  name  MYBATCH the program will  assume  MYBATCH.BAT).   The  second 
through tenth parms (optional) correspond the the variables  %1-%9.   If 
you don't pass any parms, the program will prompt you to enter the batch 
filename and parms.

A  handy  way  to use the batch monitor is a method  which  doesn't  use 
variables.   You  build  a custom .BAT file to compile  the  application 
you're  working on (don't put any % variables in the  batch  file),  and 
then install BATCHMON.TTP as an application on the desktop for file type 
".BAT".   Then,  when you double-click on "filename.BAT",  it'll fire up 
the monitor and run the batch file.   Make sure the last command in  the 
batch  file is a WAIT/PAUSE so you can view the output before  returning 
to desktop.   If you're using this method, you can still run batch files 
which use variables by clicking on BATCHMON.TTP and typing in the  batch 
file name and parms.

To give the programs you're running in batch the appearance of commands, 
it's not necessary to add the .PRG part of the program name.   The batch 
monitor checks for a file type,  and if there is one,  fine;  if not, it 
adds ".PRG".

When you are prompted for input (even single-char Y or N type), you will 
have to hit <CR>.  No hotkey input for this kid!

The batch monitor does all it's console I/O with BIOS calls.   This  may 
defeat  any I/O redirection you have in effect,  but it sure makes  life 
easier if you have the fast-but-buggy TurboST software installed.   Good 
ol' TurboST makes a lot of DOS console calls buggy.

This version of the monitor is a little bigger than the last one (almost 
10k!),  but it should only matter to a floppy disk user, who'll notice a 
slightly longer load time.   The builtin wait and delete commands should 
help a lot,  though.   Also,  I haven't checked but I'll bet the runtime 
memory usage is about 15-17k,  I used lots of wasteful buffers (and now, 
the wasteful dLibs runtime library).

This monitor was intended to emulate the one delivered with the original 
ST  developer's package.   Not that that was a great batch monitor  that 
deserves  emulation,  it's  just  that ALL my  batch  files  (litterally 
hundreds) are set up for that.

-----------------------------------------------------------------------
                Notes about use with the Alcyon Compiler
-----------------------------------------------------------------------

A typical batch file to compile the application FUNPROG might look  like 
the following example (on my system, drive G is a ramdisk)...

     CP68         FUNPROG.C g:FUNPROG.I
     C068       g:FUNPROG.I g:FUNPROG.1 g:FUNPROG.2 g:FUNPROG.3 -f
     C168       g:FUNPROG.1 g:FUNPROG.2 g:FUNPROG.S
     DELETE     g:FUNPROG.I g:FUNPROG.1 g:FUNPROG.2 
     MAC        -6 -v -og:FUNPROG.o g:FUNPROG.s
     DELETE     g:FUNPROG.S 
     aln       -w -v -o FUNPROG.prg apstart.o g:FUNPROG.o libi.bnd 
     DELETE     g:FUNPROG.O 
     WAIT

A 'generic' batch file to compile a C application whose name is supplied 
when the batch is started might look like...

     CP68         %1.C g:%1.I
     C068       g:%1.I g:%1.1 g:%1.2 g:%1.3 -f
     C168       g:%1.1 g:%1.2 g:%1.S
     DELETE     g:%1.I g:%1.1 g:%1.2 
     MAC        -6 -v -og:%1.o g:%1.s
     DELETE     g:%1.S 
     aln       -w -v -o %1.prg apstart.o g:%1 libi.bnd %2 %3 %4 %5
     DELETE     g:%1.O 
     WAIT

If  you  started BATCHMON and supplied the single  parameter  'FUNPROG', 
this  batch file would run exactly like the previous  example.   If  you 
supplied  the parameters as 'FUNPROG VDI.LIB AES.LIB',  the batch  would 
run  like  the previous example except that your VDI and  AES  libraries 
would be added to the linker's command line.  

-----------------------------------------------------------------------
                Notes for use with the Sozobon Compiler
-----------------------------------------------------------------------

Sozobon  C  includes a 'cc' driver program which replaces the  need  for 
batch  files,  if you are using a command shell.   Because some  of  the 
compiler  pieces  recognize case-sensitive  switches,  it  is  virtually 
impossible  to  run Sozobon C directly from the desktop (and  from  some 
shells),  because all command line parms get forced to uppercase.  Using 
BATCHMON in place of 'cc' allows you to get around these  problems,  and 
allows  you to direct the intermediate files during the compiler  passes 
to a ramdisk,  something which is not available when using 'cc'.   Also, 
the  Sozobon  compiler pieces make certain assumptions about  the  paths 
where things can be found,  and allow you to override these  assumptions 
using envstring variables,  so BATCHMON includes support for setting env 
strings.  The following examples again assume device G is a ramdisk...

If Sozobon has been installed exactly as described in it's docs...

     hcc     %1.c
     top     %1.s g:%1.s
     jas     -o g:%1.o g:%1.s
     DEFPATH \sozobon\lib
     ld      -o %1.prg dstart.o g:%1.o dlibs.a otherlib.a
     DELETE  %1.s g:%1.s g:%1.o
     WAIT

Notice that DEFPATH in that example was used before the linker,  so that 
the  linker can find its input files in the location Sozobon  recommends 
installing them. 

Here's  an example of one of my batch files,  in which I use  the  Atari 
'aln' linker as the final step to the Sozobon compiler...

     hcc     %1.c
     top     %1.s g:%1.s
     jas     -o g:%1.o g:%1.s
     d:\aln  -o %1.prg apstart.o g:%1.o libi gemlib vdilib aeslib
     DELETE  %1.s g:%1.s g:%1.o
     WAIT

Note  that  the aln linker lives on a different drive than  the  Sozobon 
stuff,  but  rather  than  changing the default or  EXE  paths,  I  just 
explicitly  enter the full path to run for aln.   As a further  example, 
when  I get a new release of Sozobon for testing,  I put it in  its  own 
folder,  and  add  to  the start of the batch  file  the  line  'DEFPATH 
F:\NEWSOZ'.

If you are installing Sozobon on a floppy disk system,  you may get some 
performance  mileage  out  of the  following  concepts...  Put  all  the 
executable  files in the root directory of the floppy disk,  along  with 
the  big library files.   Put the most-used header files in  a  ramdisk, 
leave  the rest on floppies,  and work your source in the ramdisk or  on 
floppy  (whichever  feels  safer).   Your batch file  might  look  like: 
(ramdisk is C)

     EXEPATH A:\
     ! The following line will cause the source & intermediate
     ! files to be worked on the ramdisk...
     DEFPATH C:\
     SETENV  INCLUDE=C:\;A:\
     hcc     a:\%1.c
     top     %1.s
     jas     %1.s
     ! Default path back to a:\ for link (lib files are on A).
     DEFPATH A:\ 
     ld      -o %1.prg dstart.o c:%1.o dlibs.a
     WAIT
          
-----------------------------------------------------------------------
                       Statement of Public Domain
-----------------------------------------------------------------------

This  code  is  placed  into the  public  domain,  and  all  rights  and 
copyrights to the code are waived.  Yep, you can abuse this beast in any 
way  you see fit.   You can even include it as part of  your  commercial 
application,  if  you are foolish enough to do so.   This code has  been 
distributed  both independantly,  and as an adjunct to the Sozobon C  PD 
compiler;  it does not carry the same copyright restrictions as the rest 
of the Sozobon compiler, however.

I'll  be  happy to look at any bugs you discover,  if you can  get  your 
comments  to me.   I can be reached on the national STadel  network  (as 
'Ian'), and on BIX as userid 'ianl'.

  Ian Lepore
  11-05-88

