----------------------------------------------------------
FILENAME:	HCONSOLE.TXT
AUTHOR:		Heiko Hellweg, hellweg@uni-koblenz.de
CREATED:	Janurary 22nd, 1998
PURPOSE:	Quick info on executable 'HCONSOLE.EXE'
----------------------------------------------------------
Pease pardon my bad english - i am no native speaker  :-)
----------------------------------------------------------

** SHORT DESCRIPTION:

HCONSOLE is a little text display tool for the OS/2 Presentation manager,
developed for debugging PM-applications by showing their standard output.

It can be used to display static text files, texts dynamically 
appended to files and data streams.

HCONSOLE IS PROVIDED AS IS without any expressed or implied warranty 
to do anything else but exist. While it looks pretty stable to me, i 
can not guarantee, that it will work as described on your system
and/or be usefull to you at all.

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

** LITTLE BIT LONGER DESCRIPTION:

HCONSOLE presents itself as a OS/2 Presentation Manager Window, 
displaying a read-only textfield that allows you to view text
and find strings in it. You can hilight parts of the text using
either the mouse or the keyboard and can copy the highlighted
section to the clipboard (if it's not too big - see BUGS) using
the keyboard shortcuts.

The displayed text can either be the content of static or growing
files, or it can originate from data streams from other processes.

The feature of watching files and displaying, what is appended
to them, resembles (a bit) the unix tool 'tail'. It can be used
to monitor log files or the like.

The continuous display of data streams allows you to use HCONSOLE 
as a PM pager instead of commandline tools like 'more' or 'less'

As a special feature, HCONSOLE can start a child process whose
standard output and error streams are redirected and displayed.

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

** LICENSE TO USE AND DISTRIBUTE:

  Everyone may use HCONSOLE at their own risk for free.

  Everyone may freely distribute the unmodiefied executable
  'HCONSOLE.EXE' as long as it is accompanied by this unmodified
  documentation 'HCONSOLE.TXT' and no more than a nominal
  duplication or transfer fee is asked for.

  However, both this documentation and the executable remain
  the authors intellectual property !

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

** AUTHOR:

	Heiko Hellweg
	Hohenzollernstr 121a
	56068 Germany
	e-mail: hellweg@uni-koblenz.de

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

** HISTORY:

HCONSOLE started out as a little debugging tool i made while
developing another OS/2 PM application. Since i usually work on
unix platforms i am used to puting trace information into my 
code by simply placing lots of 'printf()' statements in it.

However, all of the OS/2 shells i know ignore the output of PM-applications
if it is not redirected by '>' or '|' operators. So i did not get
to see my traces easily - and the commandline pagers like 'more' 
or 'less' felt a bit clumsy for this purpose too.

Thats why i built HCONSOLE - which in the beginning only had the 
feature of displaying its standard input so i could start 
'myprog.exe args | hconsole.exe'   (which by now needs the option '-stdin')

Then came the ability to start and restart the debugged program:

'hconsole.exe -exec myprog.exe args' 

 makes HCONSOLE start 'myprog' with the given arguments and capture 
its standard output and error streams in order to display them in a 
PM window. Furthermore, 'myprog' could be killed and restarted.

Since i used a 'MLE' (a Multi-Line-Entry-Field), a standard control
of the OS/2 PM, it was easy to implement the interactive 'find'
functionality - it was already builtin.

Next came some cosmetic features: the ability to define window-size 
and -position, get rid of menu and titlebar, and specify which font
to use. (the MLE already accepted fonts dropped on it - but i wanted
to automate all this in parameters for WPS-ProgramObjects).

Then came the display of plain files and the monitoring of files
for appended lines. This last one allows  HCONSOLE to display
news from logfiles that are continuously written to - or to 
peek into the growing ouput of a long running process without having 
to run HCONSOLE from it's beginning...

And thats it ! 
Since it is usefull to me - take it and have fun if you want to :-)

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

** COMMANDLINE PARAMETERS

Most of HCONSOLEs basic features are invoked by passing
commandline arguments:

hconsole [options] {-tail <dynamicfile>} {<staticfile>} [-exec <myprog args>]

-tail <dynamicfile>  show all new lines that are appended to <dynamicfile>
		after the HCONSOLE started (can be used multiple times).
<staticfile>	display the contents of <staticfile> (can be used multiple 
		times too).
-exec <...>	must be the last commandline argument! Everything that follows
		is assumed to be the child programm and its arguments. This 
		program is started with redirected stdout and stderr pipes.
		(must be a binary executable (.EXE), including the extension) 

Options are:

-stdin		display whatever text comes in on the standart input
-notitle	hide the titlebar
-nomenu		hide the menu
-nohscroll	don't add a horizontal scrollbar
-novscroll	don't add a vertical scrollbar
-behind		open the window behind all existing windows
-font <font>	use the given font - if the fontname contains spaces, enclose
		it in quotes like in: -font "9.WarpSans Bold".
		The default font is "11.System VIO".
-geometry	window size and position (a bit like xclients) in the form 
		<width>x<height>+-<xpos>+-<ypos>        (in pixel units)
		a '-' prefix for x/y-pos refer to the top and right borders
		of the screen, a '+' refers to bottom and left.
		e.g. -geometry 500x100-1+1 places the window in the riht
		bottom corner and makes it 500 x 100 pixels big	(please 
		don't depend on plus and minus zero).
-bl		'bottom left' - a shortcut for my favourite geometry which is
		'-geometry 700x200+1+1'.

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

** BUGS

... well ... none so far :-) 

The Program was only tested on my own system (german OS/2 Warp 4) and
looks reliable to me. Some things might come surprising to you:

child process killed on exit:
	This happens on purpose: whenever you quit the programm, a child 
	process	started by the -exec feature is killed using DosKillProcess.

off screen geometry:
	If you specify an off screen geometry, HCONSOLE will be off screen !
	You won't see it again ! 
	Use external kill tools to get rid of the process.

nomenu and notitle
	If you specify both: -nomenu and -notitle, you can only terminate the
	program with keyboard shortcuts (F3 or ALT-F4).
	When specifying -notitle, you can only move the window on screen
	by resizing it multiple times.

delayed display of chlid-programs stdout:
	Most of the time, your own programs standard output will be buffered.
	If you want to see immediate results, use 'fflush()' or equivalent
	library functions in your code - or use standard error which is
	usually unbuffered.

buffer overflow while tracing PM message loop:
	If you want to trace what happens in your applications message 
	loop - be carefull !
	If you produce a lot of output inbetween 'WinBeginPaint' and
	'WinEndPaint', you might run into a deadlock: your code
	won't resume until something is written to stdout, the buffer
	of the stdout pipe is full (usually 8 or 16 k), HCONSOLEs
	internal buffer is full (100 lines of text ) and HCONSOLE waits to
	display it's text before it reads more from the pipe ... BANG!

clipboard problems:
	It looks like the MLE only copies text to the clipboard if less
	then 64 k of text are selected - if it's more, nothing happens...

If you find bugs, please report them by e-mail to hellweg@uni-koblenz.de

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

** SO WHAT ?

   Well - that's it so far. I don't have the intention to add
   any more whistles and bells to HCONSOLE.

   If however you want another feature so badly, that you are willing 
   to pay me for the implementation - feel free to contact me.

------------------------------------end of file HCONSOLE.TXT-
