Message Arrival & Disposition Notification - OMMSNOTE
Message Arrival & Disposition Notification (OMMSNOTE)
Required Parameter Group:
| 1 | Global Message Handle | Input | Packed(9,0) |
| 2 | Event Type | Input | Char(3) |
| 3 | Sender / Receiver Identifier | Input | Char(10) |
| 4 | Sender / Receiver Entity Type | Input | Char(1) |
| 5 | Message Priority | Input | Char(1) |
| 6 | Message Body Type | Input | Char(1) |
| 7 | Message Direction | Input | Char(1) |
| 8 | Macro Number | Input | Packed(3,0) |
| 9 | Macro Version | Input | Packed(3,0) |
| 10 | Global Forward Message Number | Input | Packed(10,0) |
| 11 | Message Time | Input | Packed(13,0) |
| 12 | Completion Status Code | Input | Char(4) |
| 13 | Reserved | Input | Char(15) |
| 14 | Number of Users to Notify | Input | Packed(3,0) |
| 15 | Array of Users to Notify | Input | Char(500) |
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 Message Arrival & Disposition Notification API (OMMSNOTE) is called by the QTRACS Message Router Notifier (OMRTRNFY) during message arrival notification processing. It is provided so that sites can customize the handling of notification beyond that provided by QTRACS.
The regular notification processing in QTRACS is controlled by a set of user preferences that control message arrival and message disposition notification. Control of these preferences is no longer possible outside of the QTRACS Router. The router will notify the user based on his preferences regardless of the changes to this API.
This routine is called once for each message that is received by the QTRACS Router. Previous versions of QTRACS called the MNOTIFY routine once for each addressee of each message. This is no longer the case.
Required Parameter Group Details:
(1) Global Message Handle
INPUT; PACKED(9,0)
This parameter contains the unique global message handle associated to the message.
(2) Event Type
INPUT; CHAR(3)
This parameter contains an event type. Valid values are:
| 000 | A text or binary message has arrived |
| 001 | A forward message has been received by a vehicle |
| 002 | A forward message has been read by a vehicle operator |
(3) Sender / Receiver Identifier
INPUT; CHAR(10)
For Event Type 000 this parameter contains the identifier of the sender. For Event Types 001 or 002 this parameter contains the identifier of the receiver.
(4) Sender / Receiver Entity Type
INPUT; CHAR(1)
This parameter contains the entity type for the Sender/Receiver Identifier. Valid values are:
| A | Message is from an application |
| U | Message if from a user |
| V | Message if from a vehicle |
(5) Message Priority
INPUT; CHAR(1)
This parameter contains the message priority. Valid values are:
| 0 | Normal priority |
| 1 | Important priority |
| 2 | Sleepy priority |
| 3 | Sleepy plus priority |
| 4 | Low (if text or binary message) |
| 9 | Emergency priority |
(6) Message Body Type
INPUT; CHAR(1)
This parameter contains the type of message body. Valid values are:
| B | Binary message |
| T | Text message |
(7) Message Direction
INPUT; CHAR(1)
This parameter contains the direction of the message. Valid values are:
| F | Forward message |
| R | Return message |
(8) Macro Number
INPUT; PACKED(3,0)
This parameter contains a binary data type when the Message Body Type parameter is 'B'. It contains a macro number when the Message Body Type parameter is 'T'. A zero value indicates free form in this case.
(9) Macro Version
INPUT; PACKED(3,0)
This parameter contains a binary data subtype when the Message Body Type parameter is 'B'. It contains a macro version number when the Message Body Type parameter is 'T'.
(10) Global Forward Message Number
INPUT; PACKED(10,0)
This parameter contains the unique global forward message number associated to the message.
(11) Message Time
INPUT; PACKED(13,0)
This parameter contains the time that message was received or the time that the forward message disposition changed. This time is represented in GMT seconds.
(12) Completion Status Code
INPUT; CHAR(4)
This parameter contains the QTRACS 4-character completion status code for the message. This value may be appended to "CRC" to obtain a TRAQMSGF message identifier that describes the completion status.
(13) Reserved
INPUT; CHAR(15)
The contents of this parameter should be ignored.
(14) Number of Users to Notify
INPUT; PACKED(3,0)
This parameter indicates the number of entries in the Array of Users to Notify. Its valid range is from 1 - 50. It should always be 1 for Event Types 001 and 002.
(15) Array of Users to Notify
INPUT; CHAR(500)
This parameter contains the QTRACS identifiers of the users who have been notified. This is a list of addressees for when the Event Type parameter is 000, otherwise, it contains one entry (the sender identifier).
Effect
The effect of this API is entirely dependent on site-specific changes. Message notification is hard coded into the QTRACS system and may provide all of the functionality required at your site. Do not modify this API if that is the case. It is possible to use this API as a trigger to call in services that need to be executed whenever a message arrives. The MNOTIFY module was used for this purpose at selected sites. Please note that this API is called from within the OMRTRNFY process. Site-specific replacement versions of this module that take significant time to execute can cause the OMRTRNFY process to fall behind in servicing its input queue. This can result in late notifications and large queue sizes.