C user-defined input node life cycle

This topic guides you through the various stages in the life of a user-defined input node written using the C programming language. It covers the following stages in an input node's life cycle:

Registration

During the registration phase, the broker discovers which resources are available and which LILs can provide them. In this instance, the resources available are nodes. The phase starts when an execution group starts. The LILs are loaded on the startup of an execution group, and the broker queries them to find out what resources they can provide.

A CciFactory structure is created during the registration phase, when the user-defined node calls cniCreateNodeFactory.

The following APIs are called by the broker during this stage:
  • biGetMessageflowNodeFactory
  • bipGetParserFactory
The following API is called by the user-defined node during this stage:
  • cniCreateNodeFactory

Instantiation

An instance of a user-defined input node is created when the mqsistart command starts or restarts the execution group process, or when a message flow that is associated with the node is deployed.

The following APIs are called during this phase:
  • cniCreateNodeContext. This API allocates memory for the instantiation of the user-defined node to hold the values for configured attributes. This API is called once for each message flow that is using the user-defined Input node.
  • cniCreateInputTerminal. This API is invoked within the cniCreateNodeContext API, and is used to tell the broker what input terminals, if any, your user-defined input node has.
    Note: Your user-defined input node will only have input terminals if it is also acting as a message processing node. If this is the case, it is usually better to use a separate user-defined message processing node to perform the message processing, rather than combine both operations in one, more complex, node.
  • cniCreateOutputTerminal. This API is invoked within the cniCreateNodeContext API, and is used to tell the broker what output terminals your user-defined input node has.
  • cniSetAttribute. This API is called by the broker to establish the values for the configured attributes of the user-defined node.

During this phase, a CciTerminal structure is created. This structure is created when cniCreateTerminal is called.

Processing

The processing phase begins when the cniRun function is called by the broker. The broker uses the cniRun function to determine how to process a message, including determining the domain in which a message is defined, and invoking the relevant parser for that domain.

A thread is demanded from the message flow's thread pool, and is started in the run method of the input node. The thread connects to the broker's queue manager, and retains this connection for its lifetime. When a thread has been allocated, the node enters a message processing loop while it waits to receive a message. It will remain in the loop until a message is received. If the message flow is configured to use multiple threads, thread dispatching is activated.

The message data can now be propagated downstream.

The following APIs are called by the broker during this phase:
  • cniRun. This function is called by the broker to determine how to process the input message.
  • cniSetInputBuffer. This function provides an input buffer, or tells the broker where the input buffer is, and associates it with a message object.

Destruction

A user-defined input node is destroyed when the message flow is redeployed, or when mqsistop is used to stop the execution group process. You can destroy the node by implementing the cniDeleteNodeContext function.

When a user-defined input node is destroyed in one of these ways, you should free any memory used by the node, and release any held resources, such as sockets.

The following APIs are called by the broker during this phase:
  • cniDeleteNodeContext. This function is called by the broker to destroy the instance of the input node.