C user-defined message processing nodes life cycle
A user-defined message processing node for the C programming language goes through various stages.
- Registration
- Instantiation
- Processing
- Destruction
The information in this topic applies to both output nodes and message processing nodes. Both of these node types can be considered together, because although a message processing node is typically used to process a message, and an output node is used to provide an output in the form of a bit stream, you can use either type of node to perform either of these functions.
Registration
A user-defined message processing node is registered with the integration node when the LIL that contains the node has been loaded and initialized by the operating system.
The integration node calls bipGetMessageflowNodeFactory to establish the function of the LIL, and how the LIL should be called.
The bipGetMessageflowNodeFactory function in turn calls the cniCreateNodeFactory function, which returns a factory or group name for all of the nodes that are supported by your LIL.
The LIL should then call the utility function cniDefineNodeClass to pass both the name of each node and a virtual function table of the function pointers of the implementation functions.
Instantiation
During the instantiation phase, an instance of a user-defined message processing node is created. The phase starts when the integration node creates a message flow and calls the cniCreateNodeContext function for each instantiation of the user-defined node in that message flow. The cniCreateNodeContext function is that which is specified in the iFpCreateNodeContext field of the CNI_VFT struct passed to cniDefineNodeClass for that node type. This function should allocate the resources required for that node, including memory such that the instantiation of the user-defined node can hold the values for the configured attributes.
- Message flow is created:
- Integration node is being started (user has run mqsistart). Any message flows previously deployed are re-created when the integration node starts.
- Integration server is being reloaded (user has run mqsireload). Any message flows that have been deployed previously are re-created when the integration server reloads.
- A severe error has occurred within the integration server which results in the integration server being restarted.
- Message flow is redeployed. When a message flow is changed and redeployed, the integration node processes redeploy by deleting all nodes in the flow and then re-creating them with the new configuration.
Within cniCreateContext, the user-defined extension calls the two functions cniCreateInputTerminal and cniCreateOutputTerminal in order to establish what input and output terminals the message processing node has.
Processing
During the processing phase of the life cycle of a user-defined message processing node, the message is transformed in some way, when some processing operation takes place on the input message.
When the integration node retrieves a message from the queue and that message arrives at the input terminal of your user-defined node, the integration node calls the implementation function cniEvaluate. This function is used to decide what to do with the message.
You can use a range of node utility functions in your user-defined message processing node to perform a range of message processing functions, such as accessing the message data, accessing ESQL, transforming a message object, and propagating a message. You should include the node utility functions you are going to use to process the message within the cniEvaluate function.
This interface does not automatically generate a properties subtree for a message. It is not a requirement for a message to have a properties subtree, although you might find it useful to create one to provide a consistent message tree structure regardless of input node. If you want a properties subtree to be created in a message, and you are also using a user-defined input node, you must do this yourself
Destruction
When a user-defined message processing node has processed a message, you should ensure that it is destroyed, to release any system resources that it used, and to release any data areas specific to the node instance, such as context, that were acquired when the message was constructed or processed.
An instance of a user-defined message processing node is destroyed when the integration node calls the cniDeleteNodeContext function.
- Controlled termination of the integration server process:
- Integration node is being stopped (user has run mqsistop)
- Integration server is being reloaded (user has run mqsireload)
- A severe error has occurred within the integration server, which results in the integration server being restarted.
Note: This does NOT include stopping an integration server. Stopping an integration server simply stops all flows, and does not delete the flow or bring the process down. - Message flow is deleted.
- Message flow is redeployed. When a message flow is changed and redeployed, the integration node processes redeploy by deleting all nodes in the flow and then re-creating them with the new configuration.