IBM Integration Bus, Version 9.0.0.8 Operating Systems: AIX, HP-Itanium, Linux, Solaris, Windows, z/OS

See information about the latest product version

cciUserDebugTrace

Use cciUserDebugTrace to write a message from a message catalog (with inserts) to user trace when user trace is active at debug level.

If user trace is not active at debug level, an entry is written to service trace when service trace is active.

Syntax

void cciUserDebugTrace(
  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 parameter indicates that the user-defined node does not handle errors. All exceptions that are thrown during the execution of this call are thrown again to the next upstream node in the flow. If the input parameter is not NULL, the output signifies the success status of the call. If an exception occurs during execution, *returnCode is set to CCI_EXCEPTION on output. Call CciGetLastExceptionData to obtain 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 you specify a CciNode*, the name of that node is written to trace. If you specify 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 is written to trace. The entry is written only if trace is active for the node. Nodes inherit their trace setting from the message flow.

If this parameter is NULL, the trace level for the integration server is returned.

messageSource

The fully qualified location and name of the Windows message source or the Linux, UNIX, or z/OS® message catalog.

To use the current broker 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 broker on one operating system, read the log on that operating system, then format the log on a different operating system. For example, if the broker is running on Linux, UNIX, or z/OS 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.

If this parameter is NULL, the effect is the same as specifying an empty string. That is, all other information is written to the log, and the catalog field has an empty string value. Therefore, the log formatter cannot find the message source and fails 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, 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, you might have 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 is a static literal string in the source and therefore the same string is in both the source code file and the formatted trace file.

...

A C variable argument list that contains other 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. The last argument in this list must be (char*)0.

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).

These requirements apply to all char* arguments in traceText and the variable argument list of inserts (...).

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;

const char* mbElementName  = mbString((CciChar*)&elementName,BIP_DEF_COMP_CCSID);
const char* mbElementValue = mbString((CciChar*)&elementValue,BIP_DEF_COMP_CCSID);
const char* traceTextFormat = "Switch Element: name=%s, value=%s";
char* traceText = (char*)malloc(strlen(traceTextFormat) + 
                                strlen(mbElementName) + 
                                strlen(mbElementValue));
sprintf(traceText,traceTextFormat,mbElementName,mbElementValue);
    
cciUserDebugTrace(&rc,
                 (CciObject*)thisNode,
                 myMessageSource,
                 2,
                 traceText,
                 mbElementName,
                 mbElementValue,
                 (char*)0);
free((void*)mbElementName);
free((void*)mbElementValue);
free((void*)traceText);

as24510_.htm |

Last updated Friday, 21 July 2017