Configuring Routes

A route is a defined pathway that determines how messages will travel from input to output communication points. A route has input communication points to receive messages and output communication points to which it delivers messages. Between these communication points, a route may contain any number of filters.

Routes are configured through a route's Properties dialog:

You can configure the following configuration properties for a route:

Route Name

You can edit the route name in the Route Name field.

Route Message Definition

Adding a message definition (an S3D file) to a route allows Rhapsody to intelligently process matching messages. Associated definitions are listed as tabs at the top of the route's Properties dialog; switch to viewing a definition's properties by selecting the corresponding tab title. 

To associate a new definition with the route, select the Add Definition... button; this can be repeated to add multiple definitions. The added message definition is displayed as a tab in route's Properties dialog. To remove it from the route, right-click a definition's tab. Refer to Adding a Definition to a Route for details.

It is unlikely you would ever need to associate definition files of other types, such as a Mapper definition (.mdf) or stylesheet (.xsd), with a route.

Route Priority

Rhapsody is often used for online message processing where realtime messaging is expected, regardless of background processing tasks that may be taking place.

When creating a route, you can select the route priority from the Route Priority drop-down list:

• Low
• Below Normal
• Normal
• Above Normal
• High Realtime 

The default priority is Normal, however, you can select the required priority for each route. If you select a route priority of Realtime, Rhapsody ensures that messages on these routes are not impacted by message flows elsewhere.

If there are messages:

• Available for processing on a realtime priority route, these always take priority over messages waiting on a non-realtime route (that is, no attempt to prevent starvation of lower priority routes is made in this scenario).
• Waiting on multiple realtime priority routes, scheduling is done so that one realtime route does not starve another realtime route.

Startup State

The startup state of a route determines if it is automatically started when the Rhapsody engine is started. It also allows some control over the order that routes are started in.

Rhapsody normally waits for all communication points and routes in a given startup level to start before progressing to the next level. If a route cannot be configured and is not runnable, this component is ignored and the startup level progression is continued.

There are six available options for the startup state:

• Manual Restart Required - the route is not automatically started by Rhapsody. It needs to be manually restarted by an administrator.
• Startup First, ..., Startup Last - allows the startup order to be controlled. All routes at the same startup level are started at approximately the same time.

The Start only if previously running checkbox is only available when the startup state is not set to Manual Restart Required. If selected, Rhapsody remembers the startup state of the route even after the engine is restarted.

If a route is not started because its tracked startup state is 'should not be started', then a log message is generated in <RhapsodyInstallDirectory>\logs\log.txt.

FIFO Mode

FIFO Mode enables an administrator to configure FIFO rules on a route and each route can have different FIFO behavior. The FIFO mode can be configured by selecting the required option from the FIFO Mode drop-down list:

• Disable FIFO Enforcement - there is no restriction on the message order when they leave a route. Rhapsody will attempt to process messages in order, but this is not guaranteed.
• Enforce FIFO By Route Input Order (default) - messages must enter and leave the route in the same order. If messages are split, they are treated equally from that point on. Rhapsody will attempt to process messages within a route in order, but this is not guaranteed (this is the default behavior).
• Enforce FIFO By Absolute Message Order (De-batching) - messages must enter and leave the route in the same order. If messages are split or debatched within a route, they are kept in the same order in which they were split or debatched. Rhapsody will attempt to process messages within a route in order, but this is not guaranteed.
• Enforce FIFO Within Route (Single-Threaded) - messages must enter and leave the route in the same order. If messages are split or debatched within a route, they are kept in the same order in which they were split or debatched. Additionally, only a single thread will process messages on this route at a time, therefore ensuring that messages are processed in order.

When loading an RLC file, the route FIFO mode is saved and loaded as a part of the standard Rhapsody configuration. If a route without a FIFO mode is loaded from an RLC, the default setting is used.

Maintaining FIFO Order for Error Messages

When a message is sent to the Error Queue from a route, it is removed from the route and the FIFO ordering of the original messages is lost. Reprocessing the message adds it to the end of the route processing queue. FIFO ordering is applied to the reprocessed message as if the message has been newly received by the route.

To maintain FIFO order in the event messages are sent to the Error Queue:

1. Ensure the route is single-threaded and check the Stop the route when a message is sent to the Error Queue checkbox to enable the 'stop on error message' option. Rhapsody then stops the route when it sends a message to the Error Queue and alerts users to the presence of an error message and that the route has stopped in error through notifications. 
2. Manually resolve the error message and reprocess it on the route.
3. Restart the route. The error message is the next message to be processed, thereby preserving FIFO ordering.

If the route is not single-threaded, then as a workaround:

1. Enable the route 'stop on error message' option.
2. Create a duplicate copy of the route to process the error message.
3. Restart the original route to continue processing all other queued messages.