pkg://XITE-3.3-3.i386.rpm:4505295/
usr/
xite/
doc/
ReferenceManual/xite_app_std_usage_text_3.html
info downloads
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
<title>message</title>
<meta name="author" content="Svein Bøe">
<meta name="keywords" content="XITE message">
<meta name="description" content="XITE Reference Manual - message">
<link rev="made" href="mailto:svein@ifi.uio.no">
<link rel="up" href="Contents.html">
</head>
<body background="../mona_canny.jpg">
<h1>message</h1>
[ <a href="Contents.html">XITE Reference Manual</a> | <a href="http://www.ifi.uio.no/~blab/Software/Xite/">XITE home</a> ]
<hr>
</p>
<h2>Contents</h2>
<ul>
<li> <a href="#Name">Name</a>
<li> <a href="#Syntax">Syntax</a>
<li> <a href="#Description">Description</a>
<li> <a href="#Example">Example</a>
<li> <a href="#Restrictions">Restrictions</a>
<li> <a href="#Return value">Return value</a>
<li> <a href="#Author">Author</a>
</ul>
<hr>
<h2>Name</h2>
message, Info, Message, Warning, Error, Usage, InitMessage,
PushMessage, PopMessage, Verbose, ExitOnError, LastMessage,
MessageStream, DefaultMessage, DefaultNoMessage,
xite_standard_options_usage_text, xite_app_std_usage_text -
print error/warning/info/usage messages
</p>
<h2><a NAME="Syntax">Syntax</a></h2><pre>
#include <xite/message.h>
typedef int (*messagefunc)(int, char *);
typedef int (*Messagefunc)(int, char *, ...);
int InitMessage( int* argc, char* argv[],
char* usage );
int PushMessage( messagefunc info,
messagefunc warning, messagefunc error,
int exitonerror );
int PopMessage( void );
int Info( int id, char* format, ...);
int Message( int id, char* format, ...);
int Warning( int id, char* format, ...);
int Error( int id, char* format, ...);
int Usage( int id, char* format, ...);
int Verbose( void );
int ExitOnError( void );
char *LastMessage( void );
FILE *MessageStream( void );
int DefaultMessage( int id, char* message );
int DefaultNoMessage( int id, char* message );
char *xite_standard_options_usage_text( void );
char *xite_app_std_usage_text( char *usage );
</pre>
<h2><a NAME="Description">Description</a></h2>This module defines a set of routines to
give information/warning/error/usage messages
in a standard way.
</p>
The system is initialized by <em>InitMessage</em>.
This routine will save the program name and
usage text. All occurrences of %s in the usage text
is replaced by the program name (max 5 times).
Then it will search the command line
for -help, -usage, -whatis, -man and -verbose switches.
If -help/-usage/-whatis/-man is
on the command line, the program will exit after
printing out the usage text/man page. -verbose will set
the verbose flag for the system.
At last it will search for the environment variables
VERBOSE and MESSAGEPROG. If the environment variable
VERBOSE exists, the verbose flag is set. If the
environment variable MESSAGEPROG exists the program
$MESSAGEPROG is started. All output from the message
system is sent to $MESSAGEPROG.
</p>
<em>Info</em>, <em>Message</em>, <em>Warning</em>, <em>Error</em>, and <em>Usage</em> are used
to inform the user. The first parameter <em>id</em>
is the message number. This may be used as identification
for installed action routines. A common way to use <em>id</em>
is to set id=0 for info, id=1 for warning, and id>=2 for
error. The format on the rest of the parameters behaves
exactly like the printf function. <em>Info</em> will only be
executed if the verbose flag is set. <em>Message</em> behaves
exactly like <em>Info</em> except that the message is printed without
regard to the <em>verbose</em> flag. <em>Usage</em> will print out a
formatted error message followed by the usage text and
then terminate the program with status <em>id</em>.
<em>Info</em>, <em>Warning</em> and <em>Error</em> will invoke their action
routines with the parameter <em>id</em> and the formatted
text string. If the flag <em>exitonerror</em> is set, the Error
routine will terminate the program with status <em>id</em>.
When <em>Error</em> is used from library routines it is
important to keep in mind that <em>exitonerror</em> may be FALSE.
An advice is to use: return(Error(...)) in library routines.
</p>
<em>PushMessage</em> will install a new set of action routines
and set a new status for the <em>exitonerror</em> flag.
Default action routine is <em>DefaultMessage</em>. This routine
prints the message to stderr. Another predefined
action routine is <em>DefaultNoMessage</em> which does nothing.
The installed action routine takes two arguments,
<em>int id</em> and <em>char *message</em>.
If NULL is used as an action routine parameter, the
action remains unchanged. To go back to the previous
state use the function <em>PopMessage</em>.
</p>
<em>Verbose</em> and <em>ExitOnError</em> will read the current settings
of the flags <em>verbose</em> and <em>exitonerror</em>.
</p>
<em>LastMessage</em> will return a pointer to the last message
sent to the message system.
</p>
<em>MessageStream</em> returns a pointer to a stream
for output messages.
</p>
<em>xite_app_std_usage_text</em> returns the concatenation of
<em>usage</em> and the standard usage text for
XITE (given by <em>xite_standard_options_usage_text</em>).
</p>
<em>xite_standard_options_usage_text</em> returns a string with
a short description of the standard XITE options -help, -usage,
-man, -whatis and -verbose.
</p>
<h2><a NAME="Example">Example</a></h2><pre>
#include <xite/message.h>
int my_error(int id, char *message)
{
FILE *msg;
msg = MessageStream();
fprintf(msg, "**** Error no %d ****\\n", id);
return(id);
}
int lib_func(char *a, char *b)
{
Info(0, "Library function(%s, %s)\\n", a,b);
if (a==NULL || b == NULL)
return Error(2,
"Argument a or b is NULL in lib_func\\n");
/ * Do something * /
return(0); / * Status code 0 = OK * /
}
main(int argc, char *argv[])
{
int stat;
InitMessage(&argc, argv,
"Usage: %s <infile> <outfile>\\n");
Info(0, "Test number of arguments\\n");
if (argc != 3)
Usage(2,"Wrong number of parameters\\n");
Info(0, "Test Warning message\\n");
Warning(0, "This is only a test version\\n");
Info(0, "Test PushMessage and PopMessage\\n");
PushMessage(NULL, NULL, my_error, 0);
stat = Error(3, "This text is not printed\\n");
PopMessage();
lib_func(argv[1], argv[2]);
Info(0, "Test exit on Error\\n");
Error(4, "Stat = %d\\n", stat);
Warning(0,
"The program will never reach this line\\n");
}
</pre>
<h2><a NAME="Restrictions">Restrictions</a></h2>The composed message string must not exceed 2047 bytes.
<h2><a NAME="Return value">Return value</a></h2></p>
<h2><a NAME="Author">Author</a></h2>Otto Milvang
</p>
</body>
</html>
