cciUserTrace
Use cciUserTrace to write 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 cciUserTrace(
int* returnCode,
CciObject* object,
const CciChar* messageSource,
int messageNumber,
const char* traceText,
...
);
Parameters
- returnCode
- Receives the return code from the function (output). A NULL pointer input signifies that the user-defined node does not want to deal with errors. Any exceptions thrown during the execution of this call are re-thrown to the next upstream node in the flow. If input is not NULL, output signifies the success status of the call. If an exception occurs during execution, *returnCode is set to CCI_EXCEPTION on output. A call to CciGetLastExceptionData provides 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*, the name of that node is written to trace. If it is a CciParser*, 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.
- messageSource
- The fully-qualified location and name of the Windows message source, or the Linux®, UNIX, or z/OS® message catalog (input).
To use the current integration node message catalog, specify BIPmsgs on all operating systems. Alternatively, you can create your own message catalog.
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.
You can run the integration node on one operating system, read the log on that operating system, then format it on a different operating system. For example, if the integration node is running on Linux, but no .cat file is available, you could read the log, then transfer it to Windows, where the log can be formatted by using the .properties file.
- 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, the log formatter fails to format this entry.
- traceText
- A string of characters that ends with NULL (input). This string is written to service trace, and provides an easy way to correlate trace entries with paths through the source code. For example, if several paths through the code result in the same message (messageSource and messageNumber) being written to trace, you can specify traceText to distinguish between these different paths. That is, the traceText string is a static literal string in the source, and therefore the same string appears 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 char
.
- For user-defined extensions that are running on distributed platforms,
the
char*
arguments must be in ISO-8859-1 (ibm-918) code page. - For user-defined extensions that are running on z/OS platforms, the
char*
arguments must be in EBCIDIC (1047).
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);
CciNode* thisNode = ((NODE_CONTEXT_ST*)context)->nodeObject;
cciUserTrace(&rc,
(CciObject*)thisNode,
myMessageSource,
1,
"propagating to add terminal",
"add",
(char*)0);
checkRC(rc);