Logs a trace message and a buffer to the Natural Access trace log.
DWORD dispLogTrace (CTAHD ctahd, unsigned tracesource, CTA_TRACE_SEVERITY traceseverity, unsigned tracetag, void *tracevalue, unsigned tracesize)
|
Argument |
Description |
|
ctahd |
Context handle. It is used to retrieve the user-supplied context name and user ID, and is stored in the trace record as the main way of indicating where the trace message originated. |
|
tracesource |
Service ID of the service reporting the trace message. |
|
traceseverity |
Indicates if the message is informational, a warning, or an error message. See the Details section for acceptable values. |
|
tracetag |
Type of the parameter passed by reference in tracevalue. Use either a service defined tracetag or one of the following values: CTA_TRACETAG_API_EVENT CTA_TRACETAG_DWORD CTA_TRACETAG_INT32 CTA_TRACETAG_STRING CTA_TRACETAG_ERROR |
|
tracevalue |
Pointer to a location containing the byte values to be written to the log file. |
|
tracesize |
Size of tracevalue in bytes. |
|
Return value |
Description |
|
SUCCESS |
|
|
CTAERR_INVALID_CTAHD |
Specified ctahd is invalid. |
|
CTAERR_NOT_INITIALIZED |
Natural Access is not initialized. |
|
CTAERR_SVR_COMM |
Natural Access Server is not running. |
If tracing is enabled for the process, dispLogTrace writes a trace message and an optional buffer to the shared memory segment owned by ctdaemon. It does this in a process and thread-safe manner by acquiring a system-wide trace lock before writing to the shared memory. It then signals an event that causes ctdaemon to wake up, read the trace message and buffer, display it on the screen, and, optionally, log it to a file.
If a service wants to log an informational trace message, the service must call dispLogTrace directly. It should do this after checking the global and service trace masks to determine if the bits that correspond to the level of tracing necessary to generate the trace record are set.
traceseverity can have the following values specified by the enum CTA_TRACE_SEVERITY in ctadef.h:
|
Value |
Use this value for... |
|---|---|
|
CTA_TRACE_SEVERITY_INFO |
Command, event, or internal service tracing. These are not error conditions. They are informational tracing information. They do not typically cause a backtrace error dump when backtrace on error mode is specified in the call to ctaInitialize. |
|
CTA_TRACE_SEVERITY_WARNING |
Warnings. Warnings are not generated by the dispatcher or any core Natural Access service. Note: Warnings are treated as errors by the dispatcher. |
|
CTA_TRACE_SEVERITY_ERROR |
Errors. |
To define a service-specific trace format, define a trace tag value that contains the service ID in the upper word. When processing trace records containing a service-specific tag, the dispatcher calls xxxFormatTraceBuffer.
ctdaemon must be initialized with all the services that could be initialized in applications so that it has access to the binding functions necessary to format service-specific trace records.
Tracetags are defined in the same way as other codes. The high word is reserved for the service ID and the low word must be in the range from 0x4000 to 0x4FFF.
dispApiError, dispError, dispGetTracePointer, xxxSetTraceLevel