            Welcome to BATSH version 1.53
            -----------------------------

Usage:    To run WINDOWS commands from a file. Line by Line.
------    Like BATCH (.BAT) files in DOS, but with some WINDOWS
          specific commands, and not all the DOS features.
          For WINDOWS 3.1

Install:
--------
Place the files BATSH.EXE and BATSH.TXT anywhere on the disk.
Then write with NOTEPAD a text file with one command per line.
  (See below a description of available commands.)
Give the text file an extension .BSH and associate with
File-Manager the program BATSH.EXE. [File - Associate...].
  (Include the exact program location in the association.)
Run your new command-file with a double click. 

To install your command-file in Program-Manager, you can drag the
file with the mouse from File-Manager to a Program-Manager group.
For this procedure, both File- and Program-Manager must be visible
on the WINDOWS screen.

License:
--------
I give this program away for free. 
It's features will never reach the standard of a commercial
product, but it may suit you, if you need a few commands only.
You are not allowed to modify the program, sell it, or use it
as part of a commercial software package.
The Author has no warranty, obligations or liability for any problems
that may be encountered using this program.


Commands:
---------
Parameters in [] brackets are marked as optional, for using the
option, you must type it without the brackets.
For commands returning an ERRORLEVEL, the value for successful 
operation is 0, 

ASK var txt 
   (let the user assign a value to a variable.)
   (The old value of an existing variable is given as default.)
   txt - message
         The combination backslash-n \n is translated to newline.
         Limits: total text ~90 characters  total lines - 3
   var - variable name to assign response.( For the variable
         $PASSWORD, typed characters are shown as *.)
   return value - errorlevel 2 if empty

CHOICE k1,k2,k3 txt
   (select by different keys  -with errorlevel returned- )
   (not exactly the DOS 6.x equivalent)
   (k1 is the default key on time-out -errorlevel 1-)
   (you must mention the options in the text message.)
   (the keys are not shown)
   k1-k9 - a key letter (k1 is the default key)
           (never case sensitive)
   txt   - message
           The combination backslash-n \n is translated to newline.
           Limits: total text ~120 characters  total lines - 3
   return value - errorlevel according to the position on the 
                  command line: k1 ->1  k2 ->2 ....

   special keys: $S Space     
                 $E Enter
                 $A any other key -except ALT- that is not in the key list
                 # and number - time-out value in seconds 

CLOSE txt
   (close window with title -txt- [with save])
    txt  :substring of a window title
    return value - errorlevel 2 if window not found

COPY file1 file2 
    (copy files - single files only)
    file1,file2   - full filename
    ! existing files will be overwritten
    ! compressed (MS compress) files will be expanded
    return value - errorlevel 2 if file not found
                   errorlevel 3 for copy errors

DEL file
    (delete a file - single file only)
    ! if possible, access restrictions are reset before deletion
    return value -  errorlevel 2 if file not found
                    errorlevel 3 for file access errors

EXACT sw
   (all txt parameters are treated case sensitive by default)
    sw   ON   (default)
         OFF
EXIT
   (stop processing and quit BATSH.EXE.)

file
   (run a DOS or WINDOWS program -including PIF and BAT files)
    file  :program filename with optional startup parameters
    return value - errorlevel 2 if file not found
                   >2 for other errors
    if wait is on, processing waits for launched program to close

GOTO txt 
:txt
   (jump with processing to line :txt, never case sensitive)

ICON [file]
   (change the icon image) 
   file: (optional) the first icon from this file is loaded.
         without file parameter, the default BATSH icon is assigned.
         WINDOWS default icons are loaded with the reserved words
             STOP
             INFO
             EXCLAMATION
             QUESTION
   return value - errorlevel 2 if file not found. 
                  errorlevel 3 if icon is invalid. 
IF [not] condition statement
   (specify the conditions under which a statement will be executed)
   conditions:
      ERRORLEVEL number - true for equal or higher errorlevel
      EXIST file  (the first matching name will be assigned to the
                   variable $FILE )
      NETPORT dev (check if the devicename -dev- is a remote device.
                   The network name is returned in the variable $NET)
                   dev   : device name  LPT1-9 or D:-Z:
                   errorlevel 2 if network not installed or
                                network-error
      REMOTE txt  (substring of a remote service 
                   returns the corresponding device name in $NET)
                   errorlevel 2 if network not installed or
                                network-error
      WINDOW 'window title substring' in quotes if it includes spaces
      string1==string2  - compare two strings
   statement :BATSH command
LABEL [txt]
   (change the title of the BATSH.EXE icon)
   txt :new title  (default :filename of running script file as title)
MESSAGE [lbl]
   txt
   [txt]
.[lblok],[sec]
   (multiple lines of text txt are displayed.)
   lbl   - messagebox title (default MESSAGE)
   txt   - single or multiple text lines.
            a line should not be longer than 50 characters
            variables get translated 
   .     - the end of the message lines.
            until here, all lines are treated as message.
   the end-line must start with a dot (with optional parameters)
   lblok - The default button label is OK.
            You may type your own label.
   sec   - optional time-out value in seconds. (default 20 seconds)
           A value of 0 will disable the time-out function.
NETADD dev txt [pass]
    (new connection or reconnect)
    dev   : device name  LPT1-LPT9 or D:-Z: ?:
              LPT4: - LPT9: are not supported in all the networks.
              ?: takes the first free disk name for connection
                 and returns the connected drive name in $NET
    txt   : connection string
                \\server-name\service-name
            or  \\server\service%%user-name   with optional user-name
            Due to variable substitution, the character % must be 
            typed in BATSH files as %%
            Microsoft Network, has a limit of 12 characters for
            the service-name (including optional user-name).
    pass  : optional password
    return value - errorlevel >0 for various network errors
NETSTOP [QUIT] dev
    (stop network connection)
    dev   : device name  LPT1-9 or D:-Z:
    QUIT  : use this keyword to ignore open files and print-jobs
            forced disconnection
    return value - errorlevel >0 for various network errors
PLAY file
   (play WAVE soundfile)
    return value - errorlevel 2 if file not found
PRINT file    !! file gets deleted !!
   (print a print-file to the WINDOWS defined default printer)
   file    -name of a file with raw-data.
   return value - errorlevel 2 if file not found
   !! The file is deleted automatically after printing.
      If you want to keep it, you must copy it first.
   !! This function is using PRINT-Manager. Some strange printer
      drivers do not print with the spooler active, and can therefore
      not be used with this command. 
PRINTER # txt
   (set WINDOWS default printer)
   #    number 1..9  - Output port LPT1: - LPT9:
   txt  substring of an installed printer driver
   return value - errorlevel 2 if printer driver not found
                  or printer not defined

QUIT txt
   (quit window with title -txt- [w/o save])
   txt     :substring of a window title
   return value - errorlevel 2 if window not found
REM  txt  
; txt
   (3 types of comment lines, including empty lines)
    txt     :comment
RESTART
   (restart WINDOWS)
    return value - errorlevel 2 if an application refuses to close
RUN [sw] txt
   (to define the display status at startup of a program) 
   (-some programs use their on startup display status- )
    sw (optional)
       hide :start program -txt- hidden
       icon :start program -txt- as icon
    txt     :program file name and optional parameters
    return value - errorlevel 2 if file not found 
                   >2 for other errors
    if wait is on, processing waits for launched program to close

SET var=txt - set variable to value txt
SET var=    - remove variable

SHOW sw txt
   ( modify the display status of an existing window)
    sw  HIDE 
        NORMAL
        ICON      
    txt      :substring of a window title
    no txt - the BATSH.EXE icon is hidden or visible
    return value - errorlevel 2 if window not found
TRACE sw
   (each command is shown in a message-box - before execution)
   (for debugging purpose)
    sw   ON   
         OFF  (default)
WAIT sw  
   (general wait on/off toggle or wait for a specific event)
    sw - ON   (default) wait for launched programs to be closed
         OFF 
         DROP - wait until a file is dropped on BATSH-icon
           The filename is returned in the variable $DROP.
           A hidden BATSH icon is made visible before the wait.
           For multiple files, the name of the first is kept.  
         time in seconds - wait processing 
WAITCLOSE [sec] txt
   (wait until window -txt- is closed.)
   (if more than one match, the first is monitored)
    sec      :time-out in seconds (optional)
    txt      :substring of a window title
    return value - errorlevel 2 if window not found
                   errorlevel 3 if time-out reached.
WAITOPEN [sec] txt
   (wait until window -txt- is open.)
    sec      :time-out in seconds (optional)
    txt      :substring of a window title
    return value - errorlevel 2 if window is already open
                   errorlevel 3 if time-out reached.


Special Environment variables:
------------------------------
BATSH variables can be at any place on a line
Before executing a command all text-parts with %1 - %9 
are replaced with the corresponding commandline parameters.
%var%  is replaced with a predefined variable or a set variable.
All variables are stored in uppercase. Values may have lower-
and upper-case text.
 
$FILE     - this variable is set from an IF EXIST command 
$DROP     - the first file-name from a WAIT DROP command
$PASSWORD - when set with the ASK command, typed characters
            are shown as *.
$HELP     - default: BATSH.TXT
$CLOSE    - nothing
            The variable $HELP and $CLOSE define a file or a program
            that activates, when the user selects the corresponding
            menu option. Programs (not files) may have parameters.
            The parameters get converted to upper case.
            You can disable the help option by setting $HELP to empty.
            The file BATSH.TXT should be read-only if the default TXT
            file viewer allows editing.
$INSTANCE - 1 if no other BATSH.EXE program is running. 
$NET      - device name from an IF REMOTE or NETADD ?: command.
          - network name from an IF NETPORT command.
$$var     - variables with $$ are kept in WINDOWS memory (global).
               they can be accessed from each instance of the
               BATSH.EXE program, and get deleted only when
               WINDOWS is stopped or when they are set to
               empty with the command SET $$var= 
            limitation: the global space is 256 characters only
               for names and assigned values.  

The DOS environment variables are defined at startup, but
BATSH variables with equal names do have priority. 


Hints:
------
BATSH command files are called from within a BATSH file
  with the command: BATSH.EXE file-name. If WAIT is on (default),
  processing waits for the branched BATSH file to return.
Be careful with searching window titles.
  The procedure:   LABEL Waiting to close Clock 
                   WAITCLOSE Clock              
  is waiting for the BATSH icon closing and not for the Clock
  program.
To use printer-ports LPT4 - LPT9 for network printing, BATSH 
  will add missing devices to the [ports] section of WIN.INI.
  Not all the networks support these devices, and some treat
  these ports different from LPT1-3:.
For missing DOS commands you can use BATSH to run DOS 
  batch-files. 
  To hide running DOS commands you must create a PIF file.
  Define the BAT file as ' display windowed' and 'close
  on exit'. Use the BATSH command RUN HIDE or RUN ICON to
  activate the PIF file. If you give the PIF file the same
  name as the BAT file, you can RUN the BAT file directly.
For more WINDOWS control you can run recorded macros.
  Use the WINDOWS supplied recorder and record a macro.
  Assign it a shortcut key and store the macro in a file.
  Run the macro from BATSH as RECORDER -H key macro-file.


----------------------------------------------------------------
    Thomas Nyffenegger, FMI, PoBox 2543, 4002 Basel, CH
    Email: nyffenegger@fmi.ch

----------------------------------------------------------------
 
