edmiTrace

Operates the EDMinterface trace facilities. The EDMinterface trace facilities is a powerful trace mechanism to assist EDMinterface users in testing and bug hunting of their EDMinterface application.
Several filters for tracing can be defined. The resulting trace output is in plain ASCII that can be easily read and understood.
Running with the EDMinterface trace active will normally decrease the performance of EDMinterface operations considerably.
Header:
#include "sdai.h"
Prototype:
EdmiError edmiTrace(SdaiInteger traceFunction,
                     SdaiInteger traceCondition,
                     SdaiInteger maxTraceFileSize,
                     SdaiString  traceFile);
Arguments:

traceFunction	Specifies the actual EDMinterface trace operation to perform. The available operations are: DEFINE_TRACE: Define EDMinterface trace conditions. START_TRACE: Start or restart EDMinterface trace with the actual defined trace conditions. STOP_TRACE: Stop EDMinterface trace. CLOSE_TRACE: Stop EDMinterface trace and close the open EDMinterface trace file.
traceCondition	The <traceCondition> argument is only effective when the <traceFunction> = DEFINE_TRACE. This argument can be any combination (bitwise OR) of the following. TRACE_CALLS: Trace all EDMinterface function calls. The name of the EDMinterface function will be written in the trace record. TRACE_ARGS: The name and value of the arguments in the EDMinterface calls will be written in the trace record. TRACE_RETURNS: The name of the EDMinterface function to leave, the error status, and the return data will be written in the trace record. TRACE_ERRORS: Trace all errors detected by EDMinterface functions. TRACE_INTERNAL_CALLS : Trace EDMinterface functions invoked from other EDMinterface functions. TRACE_LOW_LEVEL_COMMUNICATIONS: Trace all xxx TRACE_TO_STDOUT: Write the trace output to the to the EDMinterface current output device. The EDMinterface current output device can be defined by the edmiDefineOutputFunction operation. TRACE_TO_FILE: Write the trace output to the specified trace file, i.e. to the file specified by the <traceFile> argument. TRACE_RINGFILE: The trace output file is a ring file, i.e. when the file size has reached the <maxTraceFileSize>, the file will be rewound and the trace output will start from the beginning of the file. TRACE_RINGFILE is only relevant in combination with TRACE_TO_FILE and <maxTraceFileSize>is unequal zero. The header of the trace file will contain information about current write pointer, enabling the user to find the first and last line in the trace file.
maxTraceFileSize	An integer specifying the maximum number of bytes in the <traceFile> before the file is closed or the file is rewound. This argument is only valid when <traceCondition> = DEFINE_TRACE and TRACE_TO_FILE is set in <traceCondition>. When TRACE_RINGFILE is set in <traceCondition>, then the <traceFile> will be rewound when the file size is equal to <maxTraceFileSize>number of bytes, else the file will be closed and trace output will terminate. When <maxTraceFileSize>= 0, then no check for maximum file size will be performed.
traceFile	Name of a file to write the EDMinterface trace records into. This argument is only valid for <traceFunction>=DEFINE_TRACE.

Returns:
A completion code of datatype EdmiError is the returned function value. The completion code has the following values:
Completion code = 0 : Operation successfully performed.
Completion code != 0: Error in operation. Completion code is an EDMinterface error code. Use edmiGetErrorText to get the error text corresponding to the error code.
Example:
EXAMPLE
EdmiError rstat;
...
if (rstat = edmiTrace(DEFINE_TRACE,
TRACE_CALLS | TRACE_ARGS | TRACE_RETURNS |
TRACE_ERRORS | TRACE_TO_FILE,
0,
"/usr/users/hkd/edmi_trace.txt")) {
/* Error in operation */
printf("\nError in edmiTrace(DEFINE_TRACE): %s",
edmiGetErrorText(rstat));
goto error;
}
if (rstat = edmiTrace(START_TRACE,0,0,NULL)) {
/* Error in operation */
printf("\nError in edmiTrace(START_TRACE): %s",
edmiGetErrorText(rstat));
goto error;
}
...
if (rstat = edmiTrace(CLOSE_TRACE,0,0,NULL)) {
/* Error in operation */
printf("\nError in edmiTrace(CLOSE_TRACE): %s",
edmiGetErrorText(rstat));
goto error;
}
...