HamLab Filter Source Code
Notes

Ed Hanway
23 February 1991

Please note:

	The source files included in this directory are copyrighted and
	reserved for the use of registered users of HamLab.  Please treat
	them the same as the .h files that come from your compiler vendor
	or Commodore-Amiga. You may distribute your own source code derived
	from these files, as well as any object code compiled from them,
	without restriction.

Compiler requirements:

	SAS 5.10  Conversion to Manx should be trivial.

What is this "#ifdef CHEAP" stuff?

	This is an option to use my "cheapio library," a very minimal
	subset of the basic "C" stdio functions.  Cheapio is much, much
	smaller than the Lattice stdio library, and a bit faster to boot,
	mainly because it only implements the bare necessities.

	At this time, I'm not distributing cheapio, mainly because every
	time I link a new program with it, I need to add another function
	or two,	thus it's in a constant state of flux.  The standard
	libraries provided with any C compiler should suffice, and be less
	trouble at this point.

General notes:

	The HamLab 24-bit temporary file format is documented in
	hl_filter.h. (There is also a 12-bit format documented there.
	Ignore it for now; HamLab 1.1 doesn't support it.)

	Basically, a HamLab filter gets invoked just like it was run from
	the CLI, like:

		mtv2hl <foo.mtv >foo.t24

	In fact, you can run any of the HamLab filters this way. HamLab
	will recognize its own temporary files, but the format wasn't
	exactly	designed for long-term space efficiency.

	However, because filters are run automatically you must follow a
	few conventions so that all filters will run consistently:

	1.	Don't use stderr.  Usually, stderr is created by
		calling Open("*", mumble), which returns a handle to
		the default console window.  However, hamlab may have
		been started from the workbench, in which case there
		won't be a console window, and this open will hang.
		This is why you MUST link with a modified version of
		the normal compiler startup code.  I provide context
		diffs for modifying the SAS startup code to eliminate
		the Open() call.

	2.	Check periodically for a control C break signal.  If the
		user decides to abort a filter, HamLab will send one of
		these signals and wait for the filter to die.  If your
		compiler's default break handler prints to stderr, you must
		replace it.

	3.	Return the appropriate exit code.  These are documented
		in hl_filter.h.  See the example source for their
		usage.  It's particularly important to distinguish between
		an error where the file is not the correct type and a real
		problem; more on this later.

	4.	Write the output sequentially.  HamLab may have opened
		a pipe for the output, instead of a disk file, and seeks
		don't work in pipes.  You may seek in the input, if
		necessary, but it's rarely needed.

	5.	If the format that you're filtering doesn't have a "magic
		number" at the beginning of the file, then your filter must
		be very robust, since when HamLab opens an unidentified
		file, it will run it through all of the unidentified
		filters until one of them works.  Your filter should be
		able to handle being passed absolute garbage, whereupon it
		should clean up	after itself and exit with the code
		EXIT_WRONGTYPE.

Incorporating filters into HamLab

	All that's required here is a new line in the HamLab.config file.
	The format is:

		Format "pattern" "name"

	where "pattern" is an identifying string that appears at the
	beginning of each file. For example, all GIF files start with
	"GIF". If your files don't have an identifying string like this,
	use "" for the string and reread point 5 above. "Name" is simply
	the name of the filter program, which should be in the FilterPath
	directory.