putmsg - handle a formatted message mmsgfh - FILE pointer for output mmsgfname

putmsg - handle a formatted message mmsgfh - FILE pointer for output mmsgfname - filename for output

SYNOPSIS

#include <stdio.h>
#include ``api3.h''
#include ``mmsg.h''
#include ``cgi.h''

int  putmsg(msgn,fn,fmt,...)
int  msgn;
char *fn;
char *fmt;

FILE *mmsgfh;
char *mmsgfname;

DESCRIPTION

msgn  is the number of the message or (-1).
fn    is the name of the function issuing the message or (char *)NULL.
fmt   is the htpf() format (similar to printf() but extended).
...   is the argument list for fmt if necessary.

These functions handle all output from the Metamorph API. The API reports its status periodically at points of interest. Each message has a number associated with it that indicates what type of message it is. Left alone the Metamorph API will generate message file output just like the Metamorph 3 product.

Messages consist of four basic parts:

the message number followed by a space
the text of the message
the name of the function issuing the message
a newline.

Message numbers are broken into various levels or types. The levels are grouped in hundreds. The levels are:

000-099  messages indicate total failure of the process
100-199  messages indicate potential failure or hazard to the process
200-299  messages are informative messages on the operation of a process
300-399  messages are hit information coming from a Metamorph 3 engine
400-499  messages are non-error messages coming from a mindex engine
500-599  messages about query/hit logic
600-699  query information/debugging info
700-999  undefined as yet (reserved)

Output formatting:

putmsg() will output msgn formatted with %03d if msgn!=(-1), followed by the results of fmt and its arguments if fmt!=(char *)NULL, followed by fn formatted with "in the function: %s" if fn!=(char *)NULL, followed by a newline. The output buffer is flushed to disk after every message so that any process reading the message file will always be able to get the latest messages.

Summary of formatting control:

to suppress msgn : pass -1
to suppress fn   : pass (char *)NULL
to suppress fmt  : pass (char *)NULL

Output destination:

mmsgfh and mmsgfname control where putmsg() will send its output. Each time putmsg() or datamsg() is called they will attempt to make mmsgfh point to a legal file, named by mmsgfname, and send their output there. Setting mmsgfh is accomplished by the function fixmmsgfh() (See `putmsg()` extensions"). How it works is described below.

If mmsgfh becomes (FILE *)NULL or the name pointed to by mmsgfname changes mmsgfh will be closed, if it was not (FILE *)NULL, and reopened for binary append with the new mmsgfname. If the open fails mmsgfname will be set to point to "",the empty string, mmsgfh will be set to stderr, and a warning message will be be issued via putmsg(). Only the first 127 characters in mmsgfname will be remembered between calls, so changes beyond that point will not be noticed.

If you want to set mmsgfh yourself and not have it changed set mmsgfname to (char *)NULL. This will preempt the checks described above. mmsgfh will, however, be checked for (FILE *)NULL and will be reset to stderr if it is.

The initial setting for mmsgfh is (FILE *)NULL and the initial setting for mmsgfname is (char *)NULL. This will, by default, cause all output to go to stderr.

EXAMPLE

call:
   putmsg(MERR,"parse expression","invalid escapement");
output:
   000 invalid escapement in the function parse expression\n

call:
   putmsg(-1,"parse expression","invalid escapement");
output:
   invalid escapement in the function parse expression\n

call:
   char *filename="myfile";
   putmsg(MERR+FOE,(char *)NULL,"can't open file %s",filename);
output:
   002 can't open file myfile\n

DIAGNOSTICS
putmsg() returns 0 for success or -1 if there was an error writing the output file. If there was an error the standard library variable errno may be checked for the reason. The output file will not be closed if there is an error.

NOTES
putmsg() may be overridden by writing your own function with the same name, arguments and return value so that messages can be handled in an application specific manner.

When putmsg() outputs a newline it will be the correct type for the host operating system (CRLF on MS-DOS, LF on Unix).

MS-DOS applications:

MS-DOS does not allow real multi-tasking so the contents of the message file will not become available to another program until the message file is closed (this is an MS-DOS limitation). To read the message file while a search is in progress you must access mmsgfh directly. If you move the mmsgfh file position by seeking, remember to reposition it to the end with fseek(mmsgfh,0L,SEEK_SET) before allowing the Metamorph 3 API to continue.