C user-defined message processing nodes life cycle

A user-defined message processing node for the C programming language goes through various stages.

This topic covers the objects that are created and destroyed, and the implementation functions and classes that are called in the following 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.

The integration node will create a node instance and call cniCreateNodeContext on the following occasions:
  • 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.
Note: A message flow is not created when starting an integration server. Stopping an integration server simply stops all flows and does not delete the flow or bring the process down. Restarting an integration server, starts the message flows but does not re-create the message flows.

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.

The integration node calls cniDeleteNodeContext when the instance of the node is deleted. The following events can cause a node to be deleted:
  • 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.