Before you start
Read the topic Creating a message processing or output node in C.
In many cases, the user-defined node needs to access the contents of the message that is received on its input terminal. The message is represented as a tree of syntax elements. Groups of utility functions are provided for message management, message buffer access, syntax element navigation, and syntax element access. (See C node utility functions for details of the utility functions.)
For example, to query the name and type of the first child of body:
void cniEvaluate( ... ){ ... /* Navigate to the target element */ rootElement = cniRootElement(&rc, message); bodyElement = cniLastChild(&rc, rootElement); bodyFirstChild = cniFirstChild(&rc, bodyElement); /* Query the name and value of the target element */ cniElementName(&rc, bodyFirstChild, (CciChar*)&elementname, sizeof(elementName)); bytes = cniElementCharacterValue( &rc, bodyfirstChild, (CciChar*)&eValue, sizeof(eValue)); ... }
To access the bit stream representation of an element tree you can use the cniElementAsBitstream function. Using this function, you can obtain the bit stream representation of any element in a message. See cniElementAsBitstream for details of how to use this function, and sample code.
The received input message is read-only, so before a message can be transformed, you must write it to a new output message using the cniCreateMessage function. You can copy elements from the input message, or you can create new elements and attach them to the message. New elements are typically in a parser's domain.
{ ... context = cniGetMessageContext(&rc, message)); outMsg = cniCreateMessage(&rc, context)); ... }
cniCopyElementTree(&rc, sourceElement, targetElement);
cniSetElementIntegerValue(&rc, targetElement, L"newValue", 8);
cniDeleteMessage(&rc, outMsg);
cniCreateElementAsFirstChildUsingParser cniCreateElementAsLastChildUsingParser cniCreateElementAfterUsingParser cniCreateElementBeforeUsingParser
cniCreateElementAsFirstChild cniCreateElementAsLastChild cniCreateElementAfter cniCreateElementBefore
Nodes can invoke ESQL expressions using Compute node ESQL syntax. You can create and modify the components of the message using ESQL expressions, and you can refer to elements of both the input message and data from an external database using the cniSqlCreateStatement, cniSqlSelect, cniSqlDeleteStatement, and cniSqlExecute functions.
For example, to populate the Result element from the contents of a column in a database table:
{ ... sqlExpr = cniSqlCreateStatement(&rc, (NODE_CONTEXT_ST *)context->nodeObject, L"DB", CCI_SQL_TRANSACTION_AUTO, L"SET OutputRoot.XMLNS.Result[] = (SELECT T.C1 AS Col1 FROM Database.TABLE AS T;"); ... cniSqlSelect(&rc, sqlExpr, localEnvironment, exceptionList, message, outMsg); cniSqlDeleteStatement(&rc, sqlExpr); ... }
For more information about ESQL, see ESQL overview.
If your user-defined node primarily uses ESQL, consider using a Compute node.
cniFinalize(&rc, outMsg, CCI_FINALIZE_NONE);
if (terminalObject) { if (cniIsTerminalAttached(&rc, terminalObject)) { if (rc == CCI_SUCCESS) { cniPropagate(&rc, terminalObject, localEnvironment, exceptionList, outMsg); } }
In the above example, the cniIsTerminalAttached function is used to test whether the message can be propagated to the specified terminal. If you do not use the cniIsTerminalAttached function and the terminal is not attached to another node by a connector, the message is not propagated and no warning message is returned. Use the cniIsTerminalAttached function to prevent this error occurring.
cniDeleteMessage(&rc, outMsg);
A transformed message must be serialized to a bit stream; a message can be serialized only once.
{ ... cniWriteBuffer(&rc, message); writeToDevice(cniBufferPointer(&rc, message), cniBufferSize(&rc, message)); ... }In this example, the method writeToDevice is a user-written method which writes a bit stream to an output device.
Do not write a user-defined output node to write messages to WebSphere MQ queues; use the supplied MQOutput node in this scenario. The broker internally maintains a WebSphere MQ connection and open queue handles on a thread-by-thread basis, and these are cached to optimize performance. In addition, the broker handles recovery scenarios when certain WebSphere MQ events occur; this recovery would be adversely affected if WebSphere MQ MQI calls are used in a user-defined output node.