Various stages exist in the life of a user-defined message flow parser.
This topic describes the interactions that take place between WebSphere® Message Broker 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.
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 broker. This phase starts when the execution group starts.
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 broker starts and loads the Loadable Implementation Library (LIL) and the parser factory. Before the cpiCreateContext function is called, the broker 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 execution group process creates an instance of the parser, and the broker makes a call to cpiCreateContext to allow the parser object to acquire the appropriate section of the message.
The broker 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 broker. 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.
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 broker'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.
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 broker requires a syntax element tree to be built or extended.
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.
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 broker for the parser to use need to be released.
The destruction phase begins when the mqsistop command is used to stop the execution process.