The Error Logging Facility Design
Error Log Information
Enabling Error Logging
Calling the Error Logging Facility
An Error Logging Example
The Error Logging Facility Interface
The NonStop DOM Error Logging Facility operates in an OSS environment and uses the Event Management Server (EMS) to report log information.
The Error Logging Facility consists of an object and an API that you use to write NonStop DOM exception and error conditions to an EMS collector. You can use the data recorded in the log file to help you track and fix problems that occur during the execution of your NonStop DOM applications.
The Error Logging Facility shields the user from the details of logging errors. The user need not be concerned with the error-log file format or with creating, opening, and closing the error log.
The Error Logging Facility is implemented in the object NSDOM_Error_Log. This object provides several methods for logging exceptions and error conditions. When you call a method in NSDOM_Error_Log, it creates the log message and performs the appropriate operations to write the message to the EMS collector.
The Error Logging Facility composes a log message based on both user-supplied data and data that NSDOM_Error_Log obtains during the call.
Note: The error log is also used internally by NonStop DOM; messages that you write to the error-log will be interspersed with those that are generated by NonStop DOM.
Each time a log entry is generated, the Error Logging Facility writes an error message to a user-specified EMS collector. You specify the collector in the NonStop DOM configuration database using the log_file key value.
You must start the EMS collector before you can write to it. Refer to Enabling Error Logging and the Event Management Service (EMS) Manual for details on starting and running the EMS collector.
Log messages consists of the information shown here in Table 1.
| Field Description | Field name |
|---|---|
| Date and time the exception was logged | No field name |
| Error number for this entry | No field name |
| Text description of the exception | No field name |
| Severity level of the exception | Severity |
| Name of the component that logged the error | Component |
| Name of the process that logged the error | PName |
| Process Id of the process that logged the error | PId |
| Thread Id of the thread that logged the error | TId |
| Exception type | ExcptType |
| Exception name | ExcptName |
| Name of source file that logged the error | File |
| Line number of the source file that logged the error | Line |
While much of this information is composed by the Error Logging Facility at the time the call is made, some of the information must be supplied by the user.
When using the Error Logging Facility to log runtime exceptions, you must supply the following information in your calls to the error-logging API:
CORBA::Environment object (optional)
When a call is made to the Error Logging Facility, NSDOM_Error_Log compiles several pieces of information from the configuration database. Specifically, NSDOM_Error_Log composes the date, time, process name, process id, thread id, component id, expectation name, error description, and error number for each log message generated.
The use of the EMS collector is hidden from the user. The Error Logging Facility seamlessly uses this facility in the background while processing your NSDOM_Error_Log calls. However, the user must start the specified EMS collector before any calls can be issued to the logging facility. The EMS collector is specified in the configuration database with the log_file key value.
To enable error logging in NonStop DOM, start the EMS distributor from your TACL prompt by entering the following OSS commands:
> ADD DEFINE =_EMS_TEMPLATES, FILE $SYSTEM.ZDOMSD20.newnres > EMSACOLL /NAME $xxx, NOWAIT/ BLOCKING OFF
Note: If you installed the Software Development Kit (SDK) version of NonStop DOM, your files are installed into the subdirectory ZDOMSD20. If you are using the runtime version of NonStop DOM, your NonStop DOM fileset is located in the subdirectory ZDOMRT20.
Here, $xxx is the process name for the collector that is specified for the log_file entry in the database configuration file (default.db by default).
For specific details on starting the EMS collector, refer to the Event Management Service (EMS) Manual.
Each call to the Error Logging Facility must constitute one of the following three severity levels: Error, Warning, or Informational. These severity levels are defined as follows:
When a call is made to log an exception message, the Error Logging Facility must write the data to log file before it can return to the caller.
The Error Logging Facility itself does not raise any exceptions or return any errors. If the Error Logging Facility cannot write to the error log file, it writes to the standard output (<stdout>) file.
You log runtime exceptions by placing calls to the Error Logging Facility in the error-handling routines of your NonStop DOM applications.
To ease the task of adding error-logging messages to your code, NonStop DOM supplies several predefined macros, one for each exception severity level. When using these macros, you must supply the following information to each error-logging call you make:
CORBA::Environment object (optional)
Note that the location of the error (the source file name and line number) is added to the call when you use the pre-defined macros.
To simplify the error logging process, NonStop DOM provides the following error-logging macros:
/* Log message where severity = ERROR */ NSDOM_LOG_ERR ( ErrorNum, ErrorText, Environment); /* Log message where severity = WARNING */ NSDOM_LOG_WARN ( ErrorNum, WarningText, Environment); /* Log message where severity = INFORMATIONAL */ NSDOM_LOG_INFO ( ErrorNum, InfoText, Environment); /* Set component id */ NSDOM_LOG_SET_COMPONENT_NAME (ComponentName); |
Refer to the section An Error Logging Example for an example of how you can use these macros.
Each NonStop DOM component must be assigned a unique component name so NonStop DOM can identify the process that is logging the error message. Component names are assigned once for each process, and must be done before an error message can be logged. If the user does not set the component name, the Error Logging Facility assigns the default value Application as the component name.
NonStop DOM provides the following macro to perform component id initialization:
NSDOM_LOG_SET_COMPONENT_NAME (<ComponentName>);
When using this macro, you must supply your own <ComponentName>. The following predefined names are used by the NonStop DOM components:
| Predefined NonStop DOM Component Names |
|---|
| CommServer |
| LSD |
| InterfaceRepository |
| EventService |
| NameService |
| ConfigManagement |
| OTS |
Error numbers identify a problem that may occur in the NonStop DOM environment. While NonStop DOM reserves the error numbers ranging from 0 to 6,999, you can add user-defined error numbers in the numbers ranging of 7,001 to 7,100.
See the Event Management Service (EMS) Manual manual for details on adding error numbers.
Each error number is associated with the following information:
The following code snippet shows how to log an error using a predefined macro. This example shows how to first set the component name using the NSDOM_LOG_SET_COMPONENT_NAME( ) macro. Then in an error-handling subroutine, the code calls the NSDOM_LOG_ERR( ) predefined macro to log a message that has a severity level of error.
#include errorlog.h
main ( )
{
CORBA::Environment lv_env;
// set the component name (done once per component)
NSDOM_LOG_SET_COMPONENT_NAME( "Bank Server" );
...
// log an error
NSDOM_LOG_ERR ( 7003,
"Error writing to CustDB", lv_env);
...
}
|
As a user of the Error Logging Facility, you need not know the actual API calls NSDOM_Error_Log. You should use the error logging macros provided and let them call the API methods. However, you might find it useful to know how the Error Logging Facility works.
The public interface section to the Error Logging Facility is based on the severity levels of the messages you log: Error, Warning, or Informational. These severity levels are reflected in the methods defined in the NSDOM_Error_Log class, as shown below:
//C++ NSDOM_Error_Log Class
class NSDOM_Error_Log
{
public:
static void set_component_name (char *ppComponentName);
static void log_error_msg (char *ppSourceFileName, // name of the src file
long ppSourceLineNum, // line number of src file
long pvErrNumber, // error number
char *ppErrorText, //error msg text
CORBA::Environment &prEnv);
static void log_warning_msg (char *ppSourceFileName, //name of the src file
long ppSourceLineNum, // line number of src file
long pvErrNumber, // error number
char *ppWarningText, //warning text
CORBA::Environment &prEnv);
static void log_info_msg (char *ppSourceFileName, // name of the src file
long ppSourceLineNum, // line number of src file
long pvErrNumber, // error number
char *ppInfoText, //info msg text
CORBA::Environment &prEnv);
};
|
Three NSDOM_Error_Log methods calls support logging of error messages. The following methods offer support for logging Error, Warning, and Information messages, respectively:
NSDOM_Error_Log::log_error_msg( )
NSDOM_Error_Log::log_warning_msg( )
NSDOM_Error_Log::log_info_msg( )
Calling any of these NSDOM_Error_Log methods causes the Error Logging Facility to do the following:
CORBA::Environment object.
In addition to the above methods, NSDOM_Error_Log contains a method that adds the support for setting the name of the component:
NSDOM_Error_Log::set_component_name( )