Main Page   Modules   Alphabetical List   Compound List   Compound Members  

Messages


Enumerations

enum  _cpl_msg_severity_
 Messaging verbosity. More...


Functions

cpl_error_code cpl_msg_start (void)
 Initialise the messaging system. More...

void cpl_msg_stop (void)
 Turn the messaging system off. More...

cpl_error_code cpl_msg_log_on (cpl_msg_severity verbosity)
 Open and initialise a log file. More...

cpl_error_code cpl_msg_log_off (void)
 Close the current log file. More...

const char * cpl_msg_log_file (void)
 Get the logfile name. More...

void cpl_msg_terminal_on (cpl_msg_severity verbosity)
 Set verbosity level of output to terminal. More...

cpl_msg_severity cpl_msg_log_level (void)
 Get current log verbosity level. More...

cpl_msg_severity cpl_msg_terminal_level (void)
 Get current terminal verbosity level. More...

void cpl_msg_time_tag_on (void)
 Attach a time tag to output messages. More...

void cpl_msg_time_tag_off (void)
 Disable the time tag in output messages. More...

void cpl_msg_domain_tag_on (void)
 Attach the domain tag to output messages. More...

void cpl_msg_domain_tag_off (void)
 Disable the domain tag in output messages. More...

void cpl_msg_component_tag_on (void)
 Attach the component tag to output messages. More...

void cpl_msg_component_tag_off (void)
 Disable the component tag in output messages. More...

void cpl_msg_set_domain_tag (const char *name)
 Set the domain name. More...

void cpl_msg_set_width (int width)
 Set the maximum width of the displayed text. More...

void cpl_msg_set_indent_step (int step)
 Set the indentation step. More...

void cpl_msg_indent (int level)
 Set the indentation level. More...

void cpl_msg_indent_more (void)
 Increase the message indentation by one indentation step. More...

void cpl_msg_indent_less (void)
 Decrease the message indentation by one indentation step. More...

void cpl_msg_error (const char *component, char *format,...)
 Display an error message. More...

void cpl_msg_warning (const char *component, char *format,...)
 Display a warning message. More...

void cpl_msg_info (const char *component, char *format,...)
 Display an information message. More...

void cpl_msg_debug (const char *component, char *format,...)
 Display a debug message. More...


Detailed Description

This module provides functions to display and log messages. The following operations are supported:

To activate and deactivate the messaging system, the functions cpl_msg_start() and cpl_msg_stop() must be used. These functions will typically be called at the beginning and at the end of a program. An attempt to use an uninitialised messaging system would generate an assertion failure. More functions may also be used to configure the messaging system, and here is an example of a possible initialisation:

   ...
   cpl_msg_start();
   cpl_msg_terminal_on(CPL_MSG_ERROR);
   cpl_msg_log_on(CPL_MSG_DEBUG);
   cpl_msg_time_tag_on();
   cpl_msg_component_tag_on();
   cpl_msg_set_domain_tag("Source detection");
   cpl_msg_domain_tag_on();
   ...

Three different tags may be attached to any message: time, domain, and component. The time tag is the time of printing of the message, and can optionally be turned on or off with the functions cpl_msg_time_tag_on() and cpl_msg_time_tag_off(). The domain tag is an identifier of the main program running (typically, a pipeline recipe), and can be optionally turned on or off with the functions cpl_msg_domain_tag_on() and cpl_msg_domain_tag_off(). Finally, the component tag is used to identify a component of the program running (typically, a function), and can be optionally turned on or off with the functions cpl_msg_component_tag_on() and cpl_msg_component_tag_off(). As a default, none of the above tags are attached to messages sent to terminal. However, all tags are always used in messages sent to the logfile. A further tag, the severity tag, can never be turned off. This tag depends on the function used to print a message, that can be either cpl_msg_debug(), cpl_msg_info(), cpl_msg_warning(), or cpl_msg_error(). The tags are all prepended to any message, and are not affected by the message indentation controlled by the functions cpl_msg_indent(), cpl_msg_indent_more(), cpl_msg_indent_less(), and cpl_msg_set_indent_step().

Synopsis:
   #include <cpl_messaging.h>

Enumeration Type Documentation

enum _cpl_msg_severity_
 

Messaging verbosity.

Messages may be printed with any of the functions cpl_msg_debug(), cpl_msg_info(), cpl_msg_warning() and cpl_msg_error(). Choosing one of these functions means to assign a level of severity to a given message. The messaging system can then be set to display just messages having a high enough severity. The highest verbosity level of the messaging system is CPL_MSG_DEBUG, that would ensure that all the messages would be printed. The verbosity would progressively decrease through the levels CPL_MSG_INFO, CPL_MSG_WARNING, and CPL_MSG_ERROR, where only messages served by the cpl_msg_error() function would be printed. The lowest verbosity level, CPL_MSG_OFF, would inhibit the printing of any message to the terminal.


Function Documentation

void cpl_msg_component_tag_off void   
 

Disable the component tag in output messages.

Returns:
Nothing.
The component tag is turned off in messages written to terminal, unless the verbosity level is set to CPL_MSG_DEBUG. The component tag cannot be turned off in messages written to the logfile.

void cpl_msg_component_tag_on void   
 

Attach the component tag to output messages.

Returns:
Nothing.
As a default, the component tag is attached just to messages written to the logfile. This function must be called to display the component tag also in messages written to terminal. To turn the component tag off the function cpl_msg_component_tag_off() should be called. However, the component tag is always shown when the verbosity level is set to CPL_MSG_DEBUG.

void cpl_msg_debug const char *    component,
char *    format,
...   
 

Display a debug message.

Returns:
Nothing.
Parameters:
component  Name of the function generating the message.
format  Format string.
...  Variable argument list associated to the format string.
See the description of the function cpl_msg_error().

void cpl_msg_domain_tag_off void   
 

Disable the domain tag in output messages.

Returns:
Nothing.
The domain tag is turned off in messages written to terminal.

void cpl_msg_domain_tag_on void   
 

Attach the domain tag to output messages.

Returns:
Nothing.
As a default, the domain tag is just written to the header of the logfile. This function must be called to attach the domain tag to all messages written to terminal. If the domain tag is on and no domain tag was specified, the string "Undefined domain" (or something analogous) would be attached to all messages. To turn the domain tag off the function cpl_msg_domain_tag_off() must be called.

void cpl_msg_error const char *    component,
char *    format,
...   
 

Display an error message.

Returns:
Nothing.
Parameters:
component  Name of the component generating the message.
format  Format string.
...  Variable argument list associated to the format string.
The format string should follow the usual printf() convention. Newline characters shouldn't generally be used, as the message would be split automatically according to the width specified with cpl_msg_set_width(). Inserting a newline character would enforce breaking a line of text even before the current row is filled. Newline characters at the end of the format string are not required. If component or format are NULL pointers, and assertion failure would be generated.

void cpl_msg_indent int    level
 

Set the indentation level.

Returns:
Nothing.
Parameters:
level  Indentation level.
Any message printed after a call to this function would be indented by a number of characters equal to the level multiplied by the indentation step specified with the function cpl_msg_set_indent_step(). Specifying a negative indentation level would set the indentation level to zero.

void cpl_msg_indent_less void   
 

Decrease the message indentation by one indentation step.

Returns:
Nothing.
Calling this function is equivalent to decrease the indentation level by 1. If the indentation level is already 0, it is not decreased.

void cpl_msg_indent_more void   
 

Increase the message indentation by one indentation step.

Returns:
Nothing.
Calling this function is equivalent to increase the indentation level by 1. See function cpl_msg_indent().

void cpl_msg_info const char *    component,
char *    format,
...   
 

Display an information message.

Returns:
Nothing.
Parameters:
component  Name of the function generating the message.
format  Format string.
...  Variable argument list associated to the format string.
See the description of the function cpl_msg_error().

const char* cpl_msg_log_file void   
 

Get the logfile name.

Returns:
Logfile name
The name of the logfile is returned.

cpl_msg_severity cpl_msg_log_level void   
 

Get current log verbosity level.

Returns:
Current verbosity level.
Get current verbosity level set for the output to the logfile.

cpl_error_code cpl_msg_log_off void   
 

Close the current log file.

Returns:
CPL_ERROR_NONE on success.
The logfile is closed. The name of the created logfile is always the same, and can be obtained by calling the function cpl_msg_log_file(). An attempt to close a non existing logfile would not generate an error condition. Typically this routine is called at the end of a program.

cpl_error_code cpl_msg_log_on cpl_msg_severity    verbosity
 

Open and initialise a log file.

Parameters:
verbosity  Verbosity level.
Returns:
CPL_ERROR_NONE on success. If a log file is already open, a CPL_ERROR_FILE_ALREADY_OPEN is returned. If no log file can be opened, a CPL_ERROR_FILE_NOT_CREATED is returned.
A logfile is created and initialised with a header containing the start logging time, the domain identifier set by the function cpl_msg_set_domain_tag(), and the chosen verbosity level. The verbosity specifies the lowest severity level that a message should have to be written to the log file. The name of the created logfile is always the same, and can be obtained by calling the function cpl_msg_log_file(). Typically this function is called at the beginning of a program. Calling it while a logfile is already open has no effect, but it will return an error code.

void cpl_msg_set_domain_tag const char *    name
 

Set the domain name.

Parameters:
name  Any task identifier, typically a pipeline recipe name.
Returns:
Nothing.
This routine should be called at a pipeline recipe start, and before a possible call to the function cpl_msg_log_on() or the proper task identifier would not appear in the logfile header. The domain tag is attached to messages sent to terminal only if the function cpl_msg_domain_tag_on() is called. If the domain tag is on and no domain tag was specified, the string "Undefined domain" (or something analogous) would be attached to all messages. To turn the domain tag off the function cpl_msg_domain_tag_off() should be called. If $em name is a NULL pointer, an assertion failure is generated.

void cpl_msg_set_indent_step int    step
 

Set the indentation step.

Parameters:
step  Indentation step.
Returns:
Nothing.
To maintain a consistent message display style, this routine should be called at most once, and just at program start. A message line might be moved leftward or rightward by a number of characters that is a multiple of the specified indentation step. Setting the indentation step to zero or to a negative number would eliminate messages indentation. If this function is not called, the indentation step defaults to 2.

void cpl_msg_set_width int    width
 

Set the maximum width of the displayed text.

Parameters:
width  Max width of the displayed text.
Returns:
Nothing.
If a message is longer than width characters, it would be broken into shorter lines before being diaplayed to terminal. However, words longer than width would not be broken, and in this case longer lines would be printed. This function is automatically called by the messaging system every time the terminal window is resized, and the width is set equal to the new width of the terminal window. If $em width is zero or negative, an assertion failure is generated.

cpl_error_code cpl_msg_start void   
 

Initialise the messaging system.

Returns:
CPL_ERROR_NONE on success. The error codes CPL_ERROR_DUPLICATING_STREAM or CPL_ERROR_ASSIGNING_STREAM are returned in case the stdout and stderr cannot be duplicated.
This function should be called to activate the messaging system, typically at the beginning of a program. An attempt to use any messaging function before turning the system on would generate an assertion failure. The messaging system can be deactivated by calling the function cpl_msg_stop(). Currently just the terminal width is determined (if possible), and the resized window signal handler is deployed to monitor possible changes of the terminal window width. The stdout and stderr streams are duplicated for greater flexibility of the system.

void cpl_msg_stop void   
 

Turn the messaging system off.

Returns:
Nothing
This function should be called to turn the messaging system off, typically at the end of a program. To turn the messaging system on the function cpl_msg_start() should be called. The default resized window signal handler is restored, and the duplicated output streams are closed. If a log file is still open, it is closed, and the log verbosity level set to CPL_MSG_OFF.

cpl_msg_severity cpl_msg_terminal_level void   
 

Get current terminal verbosity level.

Returns:
Current verbosity level.
Get current verbosity level set for the output to terminal.

void cpl_msg_terminal_on cpl_msg_severity    verbosity
 

Set verbosity level of output to terminal.

Parameters:
verbosity  Verbosity level.
Returns:
Nothing.
The verbosity specifies the lowest severity level that a message should have for being displayed to terminal. If this function is not called, the verbosity level defaults to CPL_MSG_INFO.

void cpl_msg_time_tag_off void   
 

Disable the time tag in output messages.

Returns:
Nothing.
The time tag is turned off in messages written to terminal. The time tag cannot be turned off in messages written to the logfile.

void cpl_msg_time_tag_on void   
 

Attach a time tag to output messages.

Returns:
Nothing.
As a default, time tags are attached just to messages written to the logfile. This function must be called to display the time tag also in messages written to terminal. To turn the time tag off the function cpl_msg_time_tag_off() should be called.

void cpl_msg_warning const char *    component,
char *    format,
...   
 

Display a warning message.

Returns:
Nothing.
Parameters:
component  Name of the function generating the message.
format  Format string.
...  Variable argument list associated to the format string.
See the description of the function cpl_msg_error().


Generated on Mon May 24 14:58:05 2004 for Common Pipeline Library Reference Manual by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002