|
|
udi_log_write(3udi)
Record log data
#include <udi.h>void udi_log_write ( udi_log_write_call_t *callback, udi_cb_t *gcb, udi_trevent_t trace_event, udi_ubit8_t severity, udi_index_t meta_idx, udi_status_t original_status, udi_ubit32_t msgnum, ... ); typedef void udi_log_write_call_t ( udi_cb_t *gcb, udi_status_t correlated_status ); /* Values for severity */#define UDI_LOG_DISASTER 1 #define UDI_LOG_ERROR 2 #define UDI_LOG_WARNING 3 #define UDI_LOG_INFORMATION 4ARGUMENTS callback, gcb are standard arguments described in the "Asynchronous Service Calls" section of "Calling Sequence and Naming Conventions". Note that no init context pointer is required (unlike with udi_trace_write), since region identity is established through the gcb.
trace_event is the type of trace event to be logged. For log data that is not associated with trace events, use UDI_TREVENT_LOG.
severity specifies the severity level of the log data.
meta_idx is a metalanguage index number that identifies the metalanguage to which trace_event is relative, for metalanguage-selectable trace events. It must match the value of <meta_idx> in the corresponding "child_meta", "parent_meta", or "internal_meta" declaration of the driver's Static Driver Properties (see Chapter 30), or 0 for the Management Metalanguage. If the event is not metalanguage-selectable, meta_idx is ignored.
original_status is the UDI status value, if any, that was either generated by the driver or received from another driver. The environment will generate appropriate information in the log file for this status value; the driver may provided supplemental information with the msgnum and associated arguments.
msgnum is the index value of a message string provided in the driver's static properties file (see Section 30.4.9, "Message Declaration"). This selects the text of the message to be logged. Any embedded formatting codes in the text of that message will be used to format the traced message with the remaining arguments supplied to this call. The formatting is performed as if the message string and remaining arguments were passed to the udi_snprintf utility function (see udi_snprintf).
... are the remaining arguments which provide the values used for the formatting codes contained in the message identified by msgnum. Arguments formatted with %c or %s format codes must not contain newline (`\n') or other control characters.
correlated_status is the original_status value, possibly modified to include a new correlation value. (See the Fundamental Types Chapter for more information on the correlation field of the udi_status_t type.) The correlation value allows multiple log entries related to a single event to be correlated based on the correlation value assigned; if there is already a correlation value in the status code the udi_log_write call will preserve that original correlation.
WARNINGS Control block usage must follow the rules described in the "Asynchronous Service Calls" section of "Calling Sequence and Naming Conventions".
DESCRIPTION This routine logs events that can affect functionality of the driver, controlled hardware or other subsystems using the driver. Each of the data records may be automatically time stamped by the environment; the driver is not expected to supply timestamp information.
The following severity levels are defined:
UDI_LOG_DISASTER This severity indicates that the driver detected a severe and unrecoverable error condition that will likely affect multiple users of a driver and may jeopardize system integrity. Environments may take actions that result in killing the driver or the system upon logging this severity.
UDI_LOG_ERROR This severity indicates that the driver encountered an error condition that might cause some error conditions in its users, but from which it was able to recover.
UDI_LOG_WARNING This severity indicates minor abnormal conditions, likely caused by other subsystems.
UDI_LOG_INFORMATION This severity is used for expected events such as driver start-up or shutdown.
If the trace_event is not UDI_TREVENT_LOG, an implicit call to udi_trace_write will be made if tracing for the corresponding event type is enabled.
udi_log_write allows the environment to associate related events in different drivers with each other. It can do this by modifying the status codes it is passed to include a correlation value. This allows errors related to the same event to be correlated.