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:
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)
putmsg() will output msgn formatted with
followed by the results of fmt and its arguments if
fmt!=(char *)NULL, followed by fn formatted with "in the
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
Summary of formatting control:
to suppress msgn : pass -1
to suppress fn : pass (char *)NULL
to suppress fmt : pass (char *)NULL
mmsgfname control where
putmsg() will send its output.
datamsg() is called they will attempt to
mmsgfh point to a legal file, named by
mmsgfname, and send
their output there. Setting
mmsgfh is accomplished by the
`putmsg()` extensions"). How it works is
(FILE *)NULL or the name pointed to by
mmsgfh will be closed, if it was not
(FILE *)NULL, and
reopened for binary append with the new
mmsgfname. If the open
mmsgfname will be set to point to
"",the empty string,
mmsgfh will be set to
stderr, and a warning message will be be
putmsg(). Only the first 127 characters in
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
(char *)NULL. This will preempt the checks
mmsgfh will, however, be checked for
and will be reset to
stderr if it is.
The initial setting for
mmsgfh is (
FILE *)NULL and the initial
(char *)NULL. This will, by default,
cause all output to go to
putmsg(MERR,"parse expression","invalid escapement");
000 invalid escapement in the function parse expression\n
putmsg(-1,"parse expression","invalid escapement");
invalid escapement in the function parse expression\n
putmsg(MERR+FOE,(char *)NULL,"can't open file %s",filename);
002 can't open file myfile\n
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.
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.
putmsg() outputs a newline it will be the correct type for
the host operating system (CRLF on MS-DOS, LF on Unix).
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
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
apimmsg.c, apimmsg.h for specific message numbers and their macros