Coding Actions

In the context of a running action, there is a lot of information available in the message body or in the environment tree. Table 1 shows the data that is available to an action implementer. Of particular interest is Environment.PMP.Variables.Transition[].TransObjects.Object[], which contains the selected columns for the object affected by the event. The other main source of information is held in the event that caused the transition, this is held on the Environment and should be indirectly referenced using a locally defined REFERENCE variable initialized by the function:

Actions.CurrentEvent(INOUT rEnv REFERENCE)

Because of possible event aggregation, or other object selectors that return multiple objects, the action may be called to act upon multiple objects. Templates for actions are provided and are documented in Action templates.

If an unexpected exception occurs during the execution of an action, it is trapped by the generic error flow and an E_UnexpectedError event is logged to the database. All other database operations within that unit of work are rolled back. Most data in the environment tree, under Environment.PMP.Variables, is logged with the unexpected error event. For this reason, it is useful to maintain any context data relating to the execution of an action in the environment. It is recommended that such data be stored under the current transition being processed, in the Environment.PMP.Variables.Transition[] array.

An API is provided to raise events. The following functions are provided:

CreateEvent: Builds an event message at a specified message location.
SendEvent: Called to send a fully built event message. The event is not sent immediately, but is added to an event cache in the environment tree. At the end of the message flow, all events in the cache are propagated.

If ISF data in an action is needed, specify the ISF_DATA column of the transaction level view on the FSM object selector template or on the transition object selector override. This data is stored as a CLOB in the database and must be parsed, using the ESQL CREATE PARSE statement, to be accessible in the action. The following code sample shows how to use the CREATE PARSE statement.

CREATE LASTCHILD OF OutputLocalEnvironment.PMP.ISF DOMAIN 'XMLNSC'
PARSE
(cIsfStr OPTIONS Common.GetBitstreamOptionsBitmask
         (refMapperParams.Channel.VALIDATE_ISF)
         ENCODING Root.Properties.Encoding
         CCSID Root.Properties.CodedCharSetId
         SET Common.MessageSet('ISF'));

The parsed ISF tree is built under OutputLocalEnvironment.PMP.ISF.XMLNSC from the string, cIsfStr, which contains the ISF XML.

It is always better to parse temporary trees into the local environment instead of the environment. This is because the memory that is associated with the parsers in the environment is not freed until the flow ends. Memory that is associated with parsers in other areas, such as the local environment, can be freed using the ESQL DELETE FIELD command (memory is released on exit from the flow node). This is particularly important when dealing with large batches where injudicious coding would lead to a very large number of unnecessary parsers occupying the memory resources.

Of course, if the action updates the ISF, it must also update the ISF_DATA column of the transaction record. To do this, the ISF message tree first must be written to a bit stream. The following code sample shows how this can be done. The ISF_DATA column of the TRANSACTION can then be updated with the isfBlob value.

SET isfBlob = ASBITSTREAM(Environment.PMP.ISF.XMLNSC
                          SET Common.MessageSet('ISF') );

Actions should never need to refer back to the original non ISF format. If during coding you find a need for this the mapper that has produced the ISF should be updated to provide a more complete mapping.

Table 1. Action context data
Location	Contents
Environment.PMP.Variables.Transition[]	Array of transitions potentially triggered by the input event. The fields available for each transition include: FSM The name of the FSM. OBJ_TYPE The type of object modeled by the FSM. SELECT_TEMPLATE The overall object selector template. OBJ_FILTER The transition object filter. EVENT_TYPE The type of event that triggered the transition. EVENT_TYPE_ID The unique ID for the event type. STATE1 The transition start state. STATE2 The transition target state. ACTION The name of the transition action. OVERRIDE_SELECTION The object selector to replace the overall FSM object selector for this transition. EVENT_FILTER A condition that must be met for the transition to be enabled. ObjectSelector The full ESQL statement executed that returned the objects affected by this transition. InputEvent The event that triggered the transition. This is a copy of the body.
Environment.PMP.Variables.IterationCount	The index into the transition array of the transition currently being processed.
Environment.PMP.Variables.TransitionCount	The total number of transitions in the transition array.
Environment.PMP.Variables.Transition[]. TransObjects.Object[]	The array of objects that are subject to the transition. The fields available in each object are determined by the fields returned by the FSM object select template or by the transition override object selector, if supplied.