cciUserTraceW

Writes a message from a message catalog (with inserts) to user trace. A message is also written to service trace, if service trace is active.

The message written to user trace has the following format:

<date-time stamp> <threadNumber> UserTrace <Message text with inserts> <Message Explanation>

Syntax

void cciUserTraceW(
  int*                returnCode,
  CciObject*          object,
  const CciChar*      messageSource,
  int                 messageNumber,
  const CciChar*      traceText,
                      ...
);

Parameters

returnCode
Receives the return code from the function (output). A NULL pointer input signifies that the user-defined node does not wish to deal with errors. Any exceptions thrown during the execution of this call will be re-thrown to the next upstream node in the flow. If input is not NULL, output will signify the success status of the call. If an exception occurs during execution, *returnCode will be set to CCI_EXCEPTION on output. A call to CciGetLastExceptionData will provide details of the exception.
object
The address of the object that is to be associated with the trace entry (input). This object can be a CciNode* or a CciParser*. If it is a CciNode*, then the name of that node is written to trace. If it is a CciParser*, then the name of the node that created the parser is written to trace. This object is also used to determine if the entry should be written to trace. The entry is only written if trace is active for the node. Currently nodes inherit their trace setting from the message flow.
If this parameter is NULL, the trace level for the execution group is returned.
messageSource
A string that identifies the Windows message source or the Linux and UNIX message catalog (input). When trace is formatted, a message from the NLS version of this catalog is written. The locale used is that of the environment where the trace is formatted. It is possible to run the broker on one type of platform, read the log on that platform, and then format the log on a different platform. For example, if the broker is running on Linux or UNIX but there is no .cat file available, the user could read the log, and then transfer it to Windows where the log can be formatted by using the .properties file.
If this parameter is NULL, the effect is the same as specifying an empty string. That is, all other information will be written to the log, and the catalog field will have an empty string value. Therefore, the log formatter will not be able to find the message source. Consequently, the log formatter will fail to format this entry.
messageNumber
The number that identifies the message within the specified messageSource (input). If the messageSource does not contain a message that corresponds to this messageNumber, then the log formatter will fail to format this entry.
traceText
A string of characters that ends with NULL (input). This string will be written to service trace and provides an easy way to correlate trace entries with paths through the source code. For example, there could be several paths through the code that result in the same message (messageSource and messageNumber) being written to trace. traceText can be used to distinguish between these different paths. That is, the traceText string will be a static literal string in the source and therefore the same string will be in both the source code file and the formatted trace file.
...
A C variable argument list that contains any message inserts that accompany the message (input). These inserts are treated as character strings and the variable arguments are assumed to be of type pointer to CciChar.
The last argument in this list must be (CciChar*)0.

Return values

None. If an error occurs, the returnCode parameter indicates the reason for the error.

Example

const CciChar*   myMessageSource=CciString("SwitchMSG",BIP_DEF_COMP_CCSID);
const CciChar*   text = CciString("propagating to add terminal",
                                   BIP_DEF_COMP_CCSID);
const CciChar*   insert = CciString("add", BIP_DEF_COMP_CCSID);
CciNode*         thisNode = ((NODE_CONTEXT_ST*)context)->nodeObject;
int              rc = CCI_SUCCESS;
 
cciUserTrace(&rc,
             (CciObject*)thisNode,
             myMessageSource,
             1,
             text,
             insert,
             (CciChar*)0);
checkRC(rc);