message
[ XITE Reference Manual | XITE home ]
Contents
Name
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
#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 );
This module defines a set of routines to
give information/warning/error/usage messages
in a standard way.
The system is initialized by InitMessage.
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.
Info, Message, Warning, Error, and Usage are used
to inform the user. The first parameter id
is the message number. This may be used as identification
for installed action routines. A common way to use id
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. Info will only be
executed if the verbose flag is set. Message behaves
exactly like Info except that the message is printed without
regard to the verbose flag. Usage will print out a
formatted error message followed by the usage text and
then terminate the program with status id.
Info, Warning and Error will invoke their action
routines with the parameter id and the formatted
text string. If the flag exitonerror is set, the Error
routine will terminate the program with status id.
When Error is used from library routines it is
important to keep in mind that exitonerror may be FALSE.
An advice is to use: return(Error(...)) in library routines.
PushMessage will install a new set of action routines
and set a new status for the exitonerror flag.
Default action routine is DefaultMessage. This routine
prints the message to stderr. Another predefined
action routine is DefaultNoMessage which does nothing.
The installed action routine takes two arguments,
int id and char *message.
If NULL is used as an action routine parameter, the
action remains unchanged. To go back to the previous
state use the function PopMessage.
Verbose and ExitOnError will read the current settings
of the flags verbose and exitonerror.
LastMessage will return a pointer to the last message
sent to the message system.
MessageStream returns a pointer to a stream
for output messages.
xite_app_std_usage_text returns the concatenation of
usage and the standard usage text for
XITE (given by xite_standard_options_usage_text).
xite_standard_options_usage_text returns a string with
a short description of the standard XITE options -help, -usage,
-man, -whatis and -verbose.
#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");
}
The composed message string must not exceed 2047 bytes.
Otto Milvang