User-defined parser life cycle

Various stages exist in the life of a user-defined message flow parser.

These stages are involved:
  • Registration
  • Instantiation
  • Processing
  • Destruction

This topic describes the interactions that take place between WebSphere® IBM® Integration components when you run a user-defined parser. It explains each stage in terms of the events that start each stage, and the events that occur during and after each stage, and the APIs that are called. Understanding the concepts here help you to design and develop your parser more effectively.

Registration

The first phase in the user-defined parser's life cycle is the registration phase. The purpose of the registration phase is to register the user-defined parser with the integration node. This phase starts when the integration server starts.

Instantiation

The parser is created during the instantiation phase of the parser life cycle. When an input message is received, or an output message is built in a Compute node, the relevant parser is identified, and parser requirements are taken from the message header, such as the MQMD. The integration node starts and loads the Loadable Implementation Library (LIL) and the parser factory. Before the cpiCreateContext function is called, the integration node creates a name element as the effective root element for the parser. However, this element is not named. The parser should name this element in the cpiSetElementName function. The integration server process creates an instance of the parser, and the integration node makes a call to cpiCreateContext to allow the parser object to acquire the appropriate section of the message.

The integration node then makes a call to cpiParseBuffer. cpiParseBuffer performs any necessary initialization, and returns the length of the message content that the parser is taking ownership of. The parser assesses how much of the message data to parse, and claims the appropriate number of bytes.

Whenever an instance of a user-defined parser object is created, the context creation implementation function cpiCreateContext is also invoked by the integration node. This call allows the parser to allocate instance data associated with the parser. A cpiDeleteContext function to delete the context of the parser object is also required.

Processing

During the processing phase, the parser manipulates, alters, and references elements within the message object. The message flow processing phase begins when any message processing activity occurs, such as navigation, that requires access to an element within a message that does not exist in the integration node's internal model representation of the message concerned.

During the message flow processing phase, the parser is invoked in response to attempts to navigate into the message tree. The parser examines the buffer that was allocated when cpiParseBuffer was called, and creates any necessary message elements.

The parser can then navigate through the message elements, using any or all of the following parser implementation functions:
  • cpiParseFirstChild
  • cpiParseLastChild
  • cpiParsePreviousSibling
  • cpiParseNextSibling

These functions are invoked when any form of navigation is made (such as a filter expression that specifies a message field) into the part of the syntax element tree that logically represents the data for a message format supported by a user-defined parser. This navigation occurs when an operation within the integration node requires a syntax element tree to be built or extended.

Consider the following points when deciding how best to navigate the syntax element tree:
  • A Syntax element has five pointers to its parents, siblings, and first and last children, so that a finite set of navigations is available.
  • The same internal classes are used to perform all of these navigations.
  • The parser does not control the navigation. The ESQL or a user-defined node makes the decision about the direction in which to navigate, and the order in which the navigational parser implementation functions are invoked. The user-defined parser has no control over the direction and order, and needs to respond correctly to the chosen navigation scheme; for example, parsing right to left, as well as left to right.
  • When writing a user-defined parser, place the parser code in a parseNextItem function. This function should build the syntax element tree one element at a time, setting names, values and complete flags appropriately. How you implement this function depends on the nature of the bit stream to be parsed. The supplied sample parser demonstrates this behavior.

When the parser has finished parsing the relevant parts of the syntax element tree, it calls cpiWriteBuffer. This function appends its portion of the syntax element tree to the bit stream in the message buffer that is associated with the parser object, and creates the output message.

Destruction

The Destruction phase is the final phase in the user-defined parser life cycle. When the parser has written its portion of the syntax element tree to the bit stream and created the output message, the system resources that were created by the integration node for the parser to use need to be released.

The destruction phase begins when the mqsistop command is used to stop the execution process.