Preliminary documentation for the HeartWare Commander:

Please remember, that HC is not completely finished yet! Any problems you may encounter is your own fault ;-) and should be reported to the author. There are still some bugs left in the program and not all the functionality that will be in the finished edition is made yet, but enough is made for you to see if you like what I have done so far. Please report any suggestions and error reports to InterNet krh@trekkies.dk or admin@heartware.dk. All complaints should be sent to /dev/nul.

NOTE: HeartWare commander is *Copyrighted* Software! Private users are granted a license to use it in non-commercial environments. This includes at people's home, but NOT at their jobs! If you want to use HC in a commercial environment you must obtain a license. Contact Keld R. Hansen on one of the above email addresses, then I will get back to you.

Keld "HeartWare" Hansen

The archive support is in many points only available on .ZIP and .ARJ files. "Why?" you ask? Because only .ZIP and .ARJ files can work properly with sub directories AND with indirect files (specified by @ or ! on the command tail). Since I may have a large number of files to process in an archive at any time (f.ex. when copying into or out of an archive) only archive programs which support the '@' (or '!') indirect file approach will be supported by HC. Also, other archive programs store the full path name in the archive instead of storing only the relative path name. F.ex. if you issue the command

	V:\DIR>LHA a -x -r TEST C:\TP\A*.PAS

then LHA will store the name \TP\DIR\AA.PAS, ie. with a leading backslash! If you then issue the command

	V:\DIR>LHA x TEST

then they are restored to \TP\ and sub dirs, whereas if you use PKZIP then the command

	V:\DIR>PKZIP -arP TEST C:\TP\A*.PAS

will store the file names as TP\ and sub dirs and if you then issue the command

	V:\DIR>PKUNZIP -o -d TEST

then the files are restored to V:\DIR\TP and sub dirs, which makes it possible for HC to restore the files to a temporary, newly created sub directory and then process the files there, ie. HC is able to completely control where the files are restored to if you use PKZIP/ARJ and NOT if you use LHA.

Only PKZIP and ARJ store relative path names AND allow indirect files. Sorry, folks, but until LHA is updated to function like PKZIP and ARJ, then it will not be fully supported by HC.

  Calling syntax;
    HC [<LeftMask> [<RightMask>]] [<Switches>]

  General Switches:
    /TMP=<Dir>   Override auto-detect of temporary directory
    /MAX=<No>    Only allocate room for this number of files in a directory
    /GDF=<File>  Define a global description file or directory
    /NC          Use Norton Commander 3.x compatible keys
    /Q           Quiet mode enable
    /DIR=<Dir>   Override location of DIRTREE.? files
  Memory allocation switches
    /XMS-        Disable use of XMS memory
    /XMS=nnn     Only use nnn K of XMS memory
    /XMS=-nnn    Leave nnn K of XMS memory unused by HC
    /EMS-        Disable use of EMS memory (also /EMS=nnn and /EMS=-nnn)
    /DSK[=<Dir>] Enable use of disk memory (also /DSK=nnn and /DSK=-nnn)
  Screen handling switches
    /CLOCK       Enable on-screen clock
    /WxH         Use specific screen mode (ie. as in /90x28)
    /COL=<File>  Load a specific colour file
    /MONO[-]     Force/Disable monochrome colours
    /1           Start-up in single-column mode
    /PS          Use this switch if your screen flashes when scrolling
    /VESA-       Disable support for VESA extended text modes & VESA graphics
    /SNOW-       Disable snow prevention on CGA systems
  BIOS support switches
    /BIOS        Use BIOS for screen output
    /EGA-        Don't use EGA BIOS function 13h for screen output (only if /BIOS)
    /FASTEGA-    Disable use of FastEGA resident driver
  SoundBlaster support switches
    /FM-         Don't use SBFMDRV even if found resident
    /MIDI-       Don't use SBMIDI even if found resident
    /VOC-        Disable all use of CTVDSK.DRV (ie: force external .VOC player)
  Network related switches
    /NET[:<Usr>] Use another base name for configuration files
    /DTU         Always use another base name - even for local Dir Tree files
  CD-ROM related switches
    /CDROM:<Drv> Define which drives are CD-ROM drives, in case HCs autodetection
  	         should fail (as in /CDROM:OY to tell HC that both O: and Y: are
  	         CD-ROM drives)
    /CDBD=<Dir>  Define a base directory for CD-ROM descriptions (see the section
  	         on CD-ROMs for further explanation)
  Compatibility modification switches
    /DV-         Disable DesqView support
    /TV-         Disable TaskView/OmniView support
    /DDOS-       Disable DoubleDos support
    /VESA-       Disable VESA enhanced text modes support as well as VESA graphic
  	         mode support.

If you have some options that you want enabled at all times in HC, you can create an environment variable called HC and set it equal to all the options you want permanent:

	SET HC=/COL=MYCOL /PS /1 /MONO- /DIRECT

and if you then want to override it occasionally you just do so on the command line...

The BPC environment variable can be used under OS/2 to make HC calculate the correct number of bytes needed for tagged files on HPFS drives, even when the HPFS drive reports 32K cluster size under DOS but only uses 1K cluster sizes. Use it as:

	SET BPC=E:1024,F:1024

which will override the number reported by DOS for drive E: and F: and reset it to 1K per cluster, thus giving you more precise readings.

When running HC.EXE off a network drive, HC will change the names of some of the support files. The HC.LAY, HC.EXT and HC.CFG will now be called .* where is your network logon name (obtained with INT 21h/AX=5E00h). This allows multiple users on a network to have independent configurations.

In case your network doesn't support INT 21h/AX=5E00h to get user logon name, (or if you want to specify an alternate name) you can give a /NET command line switch on the command tail, as in

	HC /NET=MyName

which will make the HC.EXT file be called MYNAME.EXT (etc.) for that session. For convenience, you should include this switch in your HC alias or environment variable.

HC is fully DesqView-aware. This means that you do not need to virtualize the screen buffer and can have 'Writes Directly to Screen' set to No.

Unfortunately, due to a design flaw, you may experience some screen update problems when runnig LIST from within HC under DesqView. The technical reason is this:

Whenever DesqView runs, it scans the virtual screen buffer for any changes. Thus you do not need to inform DesqView of any changes to the buffer. However, you *can* do so with INT 10h/AH=FFh (which result in better screen updating), and when DesqView sees this call, it disables the automatic scan.

Unfortunately, this disabling is on the entire session and not only the current program. This means that when HC is running in DesqView and executes another DesqView aware program that *doesn't* use INT 10h/AH=FFh, then the screen won't be updated. This is not a fault of neither HC nor LIST, but of DesqView. It should keep this flag local for each process within a window.

One unique feature of HC is the ability to make descriptions of files on CD- ROMs, completely transparent for the user.

Whenever HC detects a drive is a CD-ROM drive, it scans the root directory of the CD-ROM to create a sort of 32-bit CRC of the CD-ROM disk. This should result in a unique 32-bit number for any CD you may care to insert into your CD-ROM drive.

This 32-bit number is then used as the base name for a directory tree list file and a file descriptions file. So if you see some funny files in your HC home directory by the names *.CDD or *.DIR (where '*' is an 8-digit hexadecimal number), then it is files for HCs CD-ROM support.

The *.CDD file contains descriptions for all the files on the CD-ROM in standard FILES.BBS format, but instead of only having the file name as the first word, the complete path to the file is listed. That way HC is able to keep all the descriptions in a single file.

For use with SysOps that put CDs for download on their BBS, HC can also use a FILES.BBS file for each directory. The FILES.BBS is placed in a subdirectory by the same name as the subdirectory on the CD. This subdirectory is a sub- directory under a directory named *.CDD where '*' is the 32-bit CRC. An example will clarify it:

The file on the CD-ROM that you want to describe is called

	Y:\SATURN\ZIPFILES\TITAN.ZIP

and the CRC of your CD is 12349876. The complete name of the FILES.BBS file is then

	<BaseDir>\12349876.CDD\SATURN\ZIPFILES\FILES.BBS

where <BaseDir> is the directory specified on the command tail with /CDBD, or HC's home directory if no /CDBD switch is defined.

As a last possibility, HC can also work in multi-file mode. In this mode, each directory has its own FILES.BBS style file in the .CDD directory. F.ex. the above mentioned file would be described in

	<BaseDir>\12349876.CDD\ZIPFILES.BBS

Any directory with an extension (such as Y:\SATURN\FILES.ALL\TITAN.ZIP) would retain that extension in the description file (which would then be <BaseDir>\12349876.CDD\FILES.ALL). The root directory is treated in the same way as a subdirectory named ROOT would be, ie. Y:\PACKAGE.LST would have its description stored in

	<BaseDir>\12349876.CDD\ROOT.BBS

In case HC can't auto-detect your CD-ROM drive(s), you can create an environ- ment string CDROM which contains the letters that are CDROM drives, or you can use the command line switch of the same name. Below is an example of both methods:

	SET CDROM=O:,Y:
	HC /CDROM=OY

Both of these will tell HC that your O: drive and your Y: drive are CD-ROM drives and should be treated as such (ie. the disk should be perceived as R/O media).

HC will auto-load colour file HC.MDA on Monochrome systems (or VGA/EGA cards in Monochrome modes), HC.VGA on VGA systems, HC.EGA on EGA systems, HC.CGA on CGA systems or HC.COL if none of the above is found. Auto-loaded colour files must be located in the same directory as HC.EXE

When running off a network, HC will search for .MDA before HC.MDA and likewise for all the other files. The priority is therefore:

	/COL file  if /COL specifies an existing file
	<User>.MDA if Monochrome Display Adapter and running from network
	<User>.CGA if Colour Graphics Adapter and running from network
	<User>.EGA if Enhanced Graphics Adapter and running from network
	<User>.VGA if Video Graphics Array and running from network
	<User>.COL if running from network
	HC.MDA	   if Monochrome Display Adapter
	HC.CGA	   if Colour Graphics Adapter
	HC.EGA     if Enhanced Graphics Adapter
	HC.VGA     if Video Graphics Array
	HC.COL

You can create a file (HC.EXT) in the same directory as HC.EXE which tells HC which external command should be executed on which files. The format of this file is:

<FileMask>[,<Offset>=<Data>,<Data>]: <Command>

as in

*.CFG:		EDIT %1

which will execute the batch file/alias EDIT when you press <RETURN> on a file matching the *.CFG file mask.

or

*.ZIP,0="PK",03h,04h:	PKZIP -v %1

which will execute PKZIP -v on all *.ZIP files that has the first four bytes as the two letters "PK" followed by a byte of 3 and a byte of 4. You can specify hexadecimal numbers both as $4A 0x4A or 4Ah. Please note, that you can only override recognized archive formats if you are *not* regarding archives as directories.

or

*.*,0="Gif89a":		CSHOW %1

which will execute CSHOW on all files that has the string "Gif89a" as the first 6 bytes of the file.

An entry of *.* without any qualifier will be used on all the files that neither you nor HC has explicit support for, as in:

*.*:			LIST %1

which will execute LIST on all the files that you haven't defined explicit information for and that HC doesn't know about either.

In the command to be executed, you can use the following constructs:

	%1 = Full name of file (Disk, ':', Directory, Name, '.' and Extension)
%@NAME[%1] = Name part (ie. no extension, and no '.') of file
%@PATH[%1] = Path part (ie. Disk + Directory) of file (including trailing '\')
 %@EXT[%1] = Extension (without '.')
%@DISK[%1] = Disk drive + ':'

you can also use the following NC compatible notations:

	!.! = %@NAME[%1].%@EXT[%1]
	  ! = %@NAME[%1]
      !\!.! = %1
      !:!.! = %@DISK[%1]%@NAME[%1].%@EXT[%1]

The commands will be executed in the directory where the file is located, ie. you do not normally need a full path of the name. Normally "!.!" will be quite sufficient.

Calling syntax:
SCANMODE

ScanMode is a program that scans through all your VGA cards screen modes, noting which modes are which text resolutions. This information is then saved in a file that all programs (HeartWare and others) can use to change mode.

If you have an SVGA card with a VESA driver that supports high-resolution text modes, you do not need to do anything else. You can see if you have such support by running SHOWMODE. If you see any screen modes not 80, 90 or 94 characters wide, then you don't need to run SCANMODE.

You must create an environment variable - MODEINFO - and point it to a directory where you want to store the mode info file. Then run ScanMode and let it run through all the modes on your VGA card and update the file.

When ScanMode has finished, you can use the syntax /WxH in HC to switch to a specific text resolution before starting up HC. You can use ShowMode to show you what modes are supported by your screen card after running ScanMode.

If you have an SVGA card with extended text modes and ScanMode doesn't find them, then you can start ScanMode with the command line switch /LOG which will create the file SCANMODE.LOG in the same directory as SCANMODE.EXE and will log some information that can help me in diagnosing the problem. Send it to me on the BBS (the number is listed in the 1st paragraph).

You can also create the ModeInfo.Dat file yourself. The format is as follows:

  ModeInfo = RECORD
	       Version	: BYTE (6)
	       ModeData	: ARRAY[1..nn] OF RECORD
					    Mode   : BYTE
					    Width  : BYTE
					    Height : BYTE
					    Reserv : ARRAY[1..3] OF BYTE (0)
					  END
	     END

ie. the first byte must be 6 and then comes a bunch of records each 6 bytes long, where the first byte in the record is the mode number, the second one is the screen width and the third one is the screen height. You must then follow these three bytes with three bytes of zero before you continue with the next mode.

ShowMode is a program that shows you which screen modes HeartWare programs support. If you have a VGA and run it before ScanMode, then only the modes that are possible on a standard VGA card is shown, whereas if you run it after ScanMode, then it will show the modes that ScanMode found as well.

SetMode is a program you can use to switch into one of these high-res text modes. The calling syntax is quite simple:

	SetMode <Width>x<Height>

as in

	SetMode 90x28

If you run SetMode without any parameters, then it will show you some info about your current mode.

Calling syntax:
HCSETUP [<ColourFile>] [/WxH]

Colour installation program. Should be self-explanatory. Please note, that not all colour values are configurable at this point.

HCSETUP automatically switches into 100x40 text mode (if your card supports it AND you have run ScanMode or have a VESA BIOS extension installed that supports enhanced text modes). If your monitor isn't compatible with that resolution (800x600 pixels) then you must override the auto-detect mode at startup with /80x28 or any other screen mode your card supports that has at least 28 lines.

Thanks to Sverre Eplov for the design of the Directory Tree Scanning function.

Thanks to Ping Hansen for showing me how to make 94-character modes and how to make 60-lines mode on a standard VGA card.

Thanks to Sean Wenzel for his GIF decoding routine, upon which the one in HC is based.

Thanks to Max Maischein for his BMP decoding routine, upon which the non-RLE viewer in HC is based.