                               Message v1.1
                               ============

Contents
--------
	Notice
	File List
	Installation
	General Usage
	Message and Title
	Buttons
	Icon
	Exit Code
	Date/Time Substitution
	Revision History

-----------------------------------------------------------------------
Notice
------

Message is free software.

There is no warranty for damages caused by using this software.

Without written permission from the author (Rik Blok), you may not
distribute modified packages of this software, and may not distribute
this software for profit.

Before you send requests, questions and bug reports to the author,
please read this file carefully.  However, feedback is
appreciated.

You may find the latest version of this software at
http://rikblok.cjb.net/files.html#Message
(The address may be changed in future.)

Rik Blok
rikblok@mail.com
Rik Blok
rikblok@mail.com
http://rikblok.cjb.net/
March 10, 1999

-----------------------------------------------------------------------
File List
---------

Message.exe - the program itself (only required file)
Message.txt - documentation (this file)
ShowMe.bat  - sample usage for reading message text from file
ShowMe.txt  - file displayed by ShowMe.bat
source.zip  - Borland C++Builder 1.0 source code
test.bat    - sample usage of Message.exe

-----------------------------------------------------------------------
Installation
------------

Just copy Message.exe to any location you like.  That's it!  You can
rename the file if you like.  Message doesn't add any files or modify
your system in any way.

-----------------------------------------------------------------------
General Usage
-------------

The purpose of this program is to display a message box on the screen
with a user-defined message.  It should work with all 32-bit versions of
Microsoft Windows.

Usage: Message "message" ["title"] [buttons] [icon]

-----------------------------------------------------------------------
Message and Title
-----------------

The first parameter on the command-line is the message and the second,
if found, is the title.  The message and title are character strings,
which must be encased in quotes if they contains spaces.  The current
date/time can be substituted by using a format string encased in '$' as
discussed in "Date/Time Substitution".  Currently, there is a 256
character limit on the length of the command-line so all options must
fit within this constraint.

The message defaults to a help message and the title defaults to the name
of the program (probably "Message").

The message "-" has special meaning: it indicates that the message text
should be read from the standard input.  This allows piping of a short
file to the screen with the pipe operator "<".  Currently, this is the
only way to manually control the display of the message (carriage
returns, for example).

Examples:

	message - < ShowMe.txt
    message - "Viewing file...ShowMe.txt" < ShowMe.txt

-----------------------------------------------------------------------
Buttons
-------

The third parameter on the command-line, if found, is a single word 
which indicates which buttons to display in the message box.  It can be 
one of:

	Ok
	OkCancel
	AbortRetryIgnore
	YesNoCancel
	YesNo
	RetryCancel

The program is case-insensitive; "OkCancel" is treated the same as 
"oKcANCEL" or any other combination of upper- and lowercase.

If no button is specified or the choice is not recognized, the default
"Ok" button is shown.

-----------------------------------------------------------------------
Icon 
---- 

The fourth (last) parameter on the command-line, if found, is a single
word which indicates which icon to display beside the message text.  It 
can be one of:

	None
	Error
	Question
	Warning
	Information

If no icon is specified, none is shown.

-----------------------------------------------------------------------
Exit Code
---------

After the user presses a button the program sets an exit code and exits.  
The exit code indicates which button the user pressed:

	0 = error creating message box
	1 = user pressed Ok
	2 = user pressed Cancel
	3 = user pressed Abort
	4 = user pressed Retry
	5 = user pressed Ignore
	6 = user pressed Yes
	7 = user pressed No

The exit code can be used in a standard batch (.bat) via the "if 
errorlevel" test, as demonstrated:

	@echo off
	start /wait Message.exe "Are you happy?" Smile! YesNo Question
	if errorlevel 7 goto no
	if errorlevel 6 goto yes
	rem else error
	goto end
	:no
	echo Shucks!
	goto end
	:yes
	echo Yippee!
	:end

The usage of "start /wait ..." is mandatory in this case to tell the 
batch file to pause processing and wait for the user to press a button.  
If not used, the batch file would immediately continue processing the 
remaining lines in the file, assuming an errorlevel 0.

-----------------------------------------------------------------------
Date/Time Substitution
---------------------- 

Both the message and the title accept date/time substitution.  Any text
encased in $ characters, both before and behind, is treated as a 
formatting string for the current date/time.  The $ characters are 
removed and the string is replaced with the current date/time as 
specified in the Borland C++Builder Help file:

**** Begin excerpt ****

	The following format specifiers are supported:
	
	Specifier	Displays
	
	c	Displays the date using the format given by the ShortDateFormat 
	global variable, followed by the time using the format given by the 
	LongTimeFormat global variable. The time is not displayed if the 
	fractional part of the DateTime value is zero.

	d	Displays the day as a number without a leading zero (1-31).
	
	dd	Displays the day as a number with a leading zero (01-31).
	
	ddd	Displays the day as an abbreviation (Sun-Sat) using the strings 
	given by the ShortDayNames global variable.

	dddd	Displays the day as a full name (Sunday-Saturday) using the 
	strings given by the LongDayNames global variable.
	
	ddddd	Displays the date using the format given by the ShortDateFormat 
	global variable.
	
	dddddd	Displays the date using the format given by the LongDateFormat 
	global variable.
	
	m	Displays the month as a number without a leading zero (1-12). If the 
	m specifier immediately follows an h or hh specifier, the minute rather 
	than the month is displayed.
	
	mm	Displays the month as a number with a leading zero (01-12). If the 
	mm specifier immediately follows an h or hh specifier, the minute rather
	than the month is displayed.
	
	mmm	Displays the month as an abbreviation (Jan-Dec) using the strings 
	given by the ShortMonthNames global variable.
	
	mmmm	Displays the month as a full name (January-December) using the 
	strings given by the LongMonthNames global variable.
	
	yy	Displays the year as a two-digit number (00-99).
	
	yyyy	Displays the year as a four-digit number (0000-9999).
	
	h	Displays the hour without a leading zero (0-23).
	
	hh	Displays the hour with a leading zero (00-23).

	n	Displays the minute without a leading zero (0-59).
	
	nn	Displays the minute with a leading zero (00-59).
	
	s	Displays the second without a leading zero (0-59).
	
	ss	Displays the second with a leading zero (00-59).
	
	t	Displays the time using the format given by the ShortTimeFormat 
	global variable.
	
	tt	Displays the time using the format given by the LongTimeFormat 
	global variable.
	
	am/pm	Uses the 12-hour clock for the preceding h or hh specifier, and 
	displays 'am' for any hour before noon, and 'pm' for any hour after 
	noon. The am/pm specifier can use lower, upper, or mixed case, and the 
	result is displayed accordingly.

	a/p	Uses the 12-hour clock for the preceding h or hh specifier, and 
	displays 'a' for any hour before noon, and 'p' for any hour after noon. 
	The a/p specifier can use lower, upper, or mixed case, and the result is
	displayed accordingly.
	
	ampm	Uses the 12-hour clock for the preceding h or hh specifier, and 
	displays the contents of the TimeAMString global variable for any hour
	before noon, and the contents of the TimePMString global variable for 
	any hour after noon.
	
	/	Displays the date separator character given by the DateSeparator 
	global variable.
	
	:	Displays the time separator character given by the TimeSeparator 
	global variable.
	
	'xx'/"xx"	Characters enclosed in single or double quotes are displayed 
	as is, and do not affect formatting.

	If the string given by the format parameter is empty, the TDateTime 
	value is formatted as if a c format specifier had been given.

***** End excerpt *****

Examples:

	message "Hello!" "$c$"
	message "Thank God It's $dddd$!"
	message "Long=$dddddd$, $tt$" "Short="$ddddd$,$t$"
	
To display the $ symbol itself, repeat the character twice, as in "$$".  
The $ symbol may not be used in a date/time format itself, but a 
workaround is possible: instead, separate the formatting into two 
formatting strings separated by an extra "$$".  For example, 
"$dddd$$$$hh:nn$" may expand to "Wednesday$11:23".

If an unmatched $ is found, it is not interpreted as the beginning of a 
formatting string, and is left unaltered.

-----------------------------------------------------------------------
Revision History
----------------

v1.1	March 10, 1999
	- added support for reading message text from a standard input pipe
      (ie. file)

v1.0	March 11, 1998
	- first release!
