TimerCreate node


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.

Node terminals

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.

Configuring the TimerCreate node

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.

TimerCreate node properties

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 

  • ExecutionGroup – the timer instance will only be visible to message flows within the same Execution Group.  This is the default value.
  • Broker - the timer instance is built in shared memory and will be visible to all message flows within the broker domain.  Such a timer instance can only be cancelled by a TimerCancel node which also specifies the same global scope.
  • Platform - the timer instance is built in shared memory and will be visible to all message flows within all brokers running on the current platform.  Such a timer instance can only be cancelled by a TimerCancel node which also specifies the same global scope.

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