Customizing Character Output

The SOM character-output function is invoked by all of the SOM error-handling and debugging macros whenever a character must be generated (see "Debugging" and "Exceptions and error handling" in Using SOM Classes in Client Programs, "Using SOM Classes in Client Programs"). The default character-output routine, pointed to by the global variable SOMOutCharRoutine, simply writes the character to "stdout", then returns 1 if successful, or 0 otherwise.

For convenience, SOMOutCharRoutine is supplemented by the somSetOutChar function. The somSetOutChar function enables each task to have a customized character output routine, thus it is often preferred for changing the output routine called by somPrintf (because SOMOutChrRoutine would remain in effect for subsequent tasks). On Windows, the somSetOutChar function is required (rather than SOMOutCharRoutine); it is optional on other operating systems.

An application programmer might wish to supply a customized replacement routine to:

• Direct the output to stderr,

• Record the output in a log file,

• Collect characters and handle them in larger chunks,

• Send the output to a window to display it,

• Place the output in a clipboard, or

• Some combination of these.

With SOMOutCharRoutine, an application program would use code similar to the following to install the replacement routine:

#include <som.h>#pragma linkage(myCharacterOutputRoutine, system)
/* Define a replacement routine: */
int SOMLINK myCharacterOutputRoutine (char c)
{
     (Customized code goes here)
}

/* After the next stmt all output */
/* will be sent to the new routine   */
SOMOutCharRoutine = myCharacterOutputRoutine;

With somSetOutChar, an application program would use code similar to the following to install the replacement routine:

#include <som.h>
static int irOutChar(char c);

static int irOutChar(char c)
{
    (Customized code goes here)
}

main (...)
{
    ...
somSetOutChar((somTD_SOMOutCharRoutine *) irOutChar);
}