Notification Break Message Handler - OMBRKMSG

Notification Break Message Handler (OMBRKMSG)

API Overview:
This is a customizable site-specific program whose source resides in the deliverable source library, OMNIDLVSRC. All site-specific programs should be compiled into the site library, OMNISITE.

The Notification Break Message Handler API (OMBRKMSG) is used to provide custom break message handling. Be sure to consider the items in the warnings section before implementing this API.

Several QTRACS user preferences are available that allow the user to control what type of notification message is sent to them at the occurrence of certain QTRACS events. Some types of notification styles require this custom break message handler to be implemented; other types do not. Refer to the following table for a list of the kinds of notification messages that may be requested by each user and whether or not it requires use of OMBRKMSG.

Notification Preference	Description	Requires Break Message Handler
*NO	Instructs QTRACS to disable all notification messages to a given user for the event that has just occurred.	No
*BREAK	Instructs QTRACS to send an OS/400 break message to a given user to notify him of the event that has just occurred.	No
*STATUS	Instructs QTRACS to send an non-intrusive status message to the bottom line of a given user's display to notify him of the event that has just occurred.	Yes
*REPLY	Instructs QTRACS to send an non-intrusive status message to the bottom line of a given user's display for reply messages only.	Yes
*QTMSG	Instructs QTRACS to send a QTRACS message to the given user's mailbox to notify him of the event that has just occurred.	No
*BRKWDW	Instructs QTRACS to display a pop-up window to the user to notify him of the event that has just occurred.	Yes

The values in this table are used to set a user's Message Notification Preferences via the 'Set My Preferences' option (12) from within the QTRACS main menu. Refer to the QTRACS User's Guide for more information.

Calling Sequence
The operating system (OS/400) is responsible for calling the break message handler for a given user whenever a message arrives at his queue. If it has been decided that a user would like to make use of one or more of the notification styles that require a break message handler, then follow the following steps:

Ensure that the user's AS/400 (not QTRACS) user profile is set so that his message delivery preference is *BREAK. This must be done only once.
Somewhere in the user's initial startup CL (or RPG) program, the following commands must be executed in order to inform OS/400 that we want to call a custom break message handler.CHGMSGQ MSGQ(*USRPRF) PGM(OMBRKMSG) MONMSG MSGID(CPF2451)Unfortunately there is no way to save this information in the user's profile. These commands must be executed each time the user signs on.
Each user that implements the break message handler must ensure that his library list contains the Omni libraries.

Effect
The QTRACS notification background task (OMRTRNFY) is responsible for notifying a user about the disposition of QTRACS messages. It retrieves each user's preference and then delivers the style of notification (if any) that the user has requested for a given event. Some of these notification styles, *STATUS and *BRKWDW, require the use of a break message handler.

If the user is configured to display notification messages in *STATUS mode, (and OMBRKMSG has been implemented), then the QTRACS notification messages will appear on the bottom of the user's display in the form of a non-intrusive status message.

If the user is configured to display notification messages in *BRKWDW mode, (and OMBRKMSG has been implemented), then the QTRACS notification message will be suppressed. Instead, a popup window will be displayed that will show the actual QTRACS message that was received from a vehicle. In addition, and Fkey will be available that will allow the user to hot-key directly to the QTRACS system.

If the user is configured to display notification messages in *STATUS or *BRKWDW, and OMBRKMSG has not been implemented, then the notification messages will be displayed in *BREAK mode.

Warnings
Due to the fact that the break message handler works in conjunction with OS/400 to deliver messages, there is limited control over its functionality. There are certain aspects of its behavior that cannot be changed. This utility cannot be all things to all people .

The following items should be considered when deciding if/how to implement OMBRKMSG:

The recommended usage for this program is to display all break messages as status messages. This includes all QTRACS notifications and all other non-QTRACS messages . This break message handler program performs this way as delivered; however, the program source is also delivered, and may be modified to suit.
The delivery of non-QTRACS messages is affected when the break message handler is installed for a user. The default implementation is to display them as status messages (see note #1).
The use of the break message handler is not recommended at sites where people use break messages to communicate with one another. The break message handler works best at sites where people do not receive critical information via break messages; but rather informational messages only. The delivery of a status message on the bottom of the display is a nice balance between no message at all, and having every message be delivered in *BREAK mode.
The use of the break message handler is not recommended at sites where people use System-Request-1 to toggle between two interactive sessions within the same job. Testing has revealed that the break message handler does not work well in this environment. The break message handler works best at sites where people use Alt-Jump (or some other means) to toggle between two or more job sessions.