The TimerCreate node icon
This page
contains information on:
The TimerCreate and TimerCancel nodes are
a pair of nodes that allow timer instances to be created and destroyed. A
timer instance can be thought of as an object that periodically generates a
timer event message.
The TimerCreate
node is responsible for creating a timer instance, the characteristics of which
are based either on literal values specified in the TimerCreate configuration,
or values derived from the creation message itself, or a combination of
both. Each timer instance may optionally have a name, either a literal
value specified by the TimerName attribute or a value derived from the creation
message. The expiry interval for the timer instance may also be a literal
or derived value and determines how frequently the timer instance will generate
a timer event message. The timer instance will continue to generate event
messages every IntervalSeconds interval until the maximum number of expiries
has been reached or it is explicitly cancelled by a TimerCancel node. The
lifetime of the timer instance is controlled by the setting of the
TimerPopCount attribute. By default this is set to 1 which means that the
timer instance will be deleted following its initial expiry. However, any
valid integer value can be specified, including the special value 0 (zero)
which indicates an infinite timer lifetime.
A timer
instance must be unique within the specified scope. For named timers, any
timer within scope with the same name is replaced. For un-named timers,
any timer within scope with the same MsgId and CorrelId values is replaced.
The TimerCreate
node has one input terminal called in and two output terminals, out
and failure. When a message is received in the input terminal, the
node extracts both the MsgId and CorrelId values and locates the syntax
elements within the creation message for any of the derived values (e.g.
TimerName, IntervalSeconds or MessageData). Any MessageData
specified is copied from the creation message and a new timer instance is
created. Its expiry time is set to the literal or derived value and if
not 0 (zero), it is added to an alarm chain. Depending on the setting of the
TimerScope attribute, the timer instance is added to the local indexes (visible
to message flows within the same Execution Group) and the global timer chain
(visible to all Message Flows within all Execution Groups within the broker
domain). The input creation message is then propagated unchanged to the out
terminal. If any of the specified syntax elements for derived values
cannot be found within the creation message, or they contain no data value, the
message is propagated to the failure terminal. All other errors
also result in the message being propagated to the failure terminal and
a message logged to the MQSI V2 message log.
The TimerCreate node provides the
following terminals:
in |
The input terminal that accepts a creation message for processing
by the node. |
out |
The output terminal to which the message is propagated if the
timer instance is successfully created. |
failure |
The output terminal to which the message is propagated if any
errors are encountered while processing the creation message. |
When you have put an instance of the
TimerCreate node into a message flow you can configure it. Right click on the
node in the Message Flow Definition pane and select Properties.
Click on the Basic tab
and (optionally) enter the name that you wish to give the timer instance.
Alternatively, you can enter the path for a syntax element in the creation
message. If you do this, at runtime, the value of the specified element
will be retrieved and used as the timer instance name. If you specify the
name of the syntax element from which to extract the name, the name must begin
with 'Root' or 'Root.'. By giving the timer a name you
provide an alternative and simpler mechanism for identifying the timer instance
in the TimerCancel node. A named timer instance can only be cancelled by
a TimerCancel node that specifies the same name (either literally or as a
derived value). . The lifetime of the timer can be specified by the
TimerPopCount which represents the number of times the timer instance expiry
can be reached. When this threshold is reached, the timer instance is
automatically deleted. The special value of 0 (zero) may be specified for
the TimerPopCount, in which case, the timer instance lifetime is infinite.
Property |
Default |
Description |
TimerName |
|
Optional value used to identify the timer instance. In
order to cancel a named timer, a TimerCancel node must also specify a
matching name; the MsgId and CorrelId values have no significance for a named
timer instance. Within both
the local and global scope, the timer name must be unique. Should a
timer instance with the same name already exist, it is removed as part of
creating the new timer instance. The new named timer instance
effectively replaces any existing instance with the same name within the
specified scope. The TimerName
value can be a literal or a derived value, i.e. a value to be extracted from
the creation message. For the latter, the value specified for the
TimerName attribute must begin with either 'Root' or 'Root.'. |
TimerQueue |
|
The name of the queue to which timer event message will be sent. |
MessageData |
|
Optional value specifying data to be included in the body of the
event message(s). It can consist of either a literal value or a derived
value, i.e. a value to be extracted from the creation message. For the
latter, the value specified for the MessageData attribute must begin with
either 'Root' or 'Root.'. Any data thus
specified will be converted to XML format (if necessary) before inclusion in
any event messages. |
IntervalSeconds |
15 |
Specifies the expiry interval (in seconds) of the timer. A
value of 0 indicates an INFINITE expiry, i.e. the timer will never expire and
no event message will ever be generated.. If a non-zero value is specified,
an alarm is set to the expiry interval and, if the timer instance still
exists when the timer expires, an event message is generated. If the
maximum number of expiries has been reached (see TimerPopCount), the timer
instance is automatically deleted otherwise, the timer is reset once more to
the expiry interval and the process is repeated. |
TimerPopCount |
1 |
Specifies the maximum number of times the timer can expire.
The special value of 0 (zero) indicates that the timer instance has an
unlimited lifetime. Unless such a timer is explicitly cancelled via a
TimerCancel node, it will exist until the Execution Group that created it is
stopped. |
Click on the
Advanced tab and (optionally) to modify the scope of the timer and/or the
expiry interval for the timer messages.
TimerScope |
Execution Group |
The value set for this property determines the scope of the timer
instance. It can take 2 possible values
|
MessageExpiry |
0 |
Specified the period of time, expressed in seconds, after which
the timer message will become eligible to be discarded by the queue manager
if it has not been removed from the timer queue. The default value is 0, which means that the timer message
will have no expiry value set. |
(C) IBM Corporation 2001. All Rights Reserved