Mark a Message as Seen - OMMKSEEN

Mark a Message as Seen (OMMKSEEN) ^RI

Required Parameter Group:

API Overview:
The Mark a Message as Seen API (OMMKSEEN) is used to remove a message from one or more user's unseen list without those users having to actually read the message via the QTRACS User Interface. A call to this API may be placed from some custom external application that has determined that it wants to remove a message from the unseen list of one or more user's message directories.
This API accepts the Global Message Handle of the message to be 'marked', as well as several other parameters that further control how the message should be marked when it is removed from the unseen list(s). The features of this API have been extended over time; therefore, the 4th and 5th parameters to this API are optional. In other words, this API will operate correctly when called with three, four, or five parameters. A caller need only specify the 4th and/or 5th parameter if he chooses to take advantage of the extended features that are controlled by those parameters.
This API will operate on return or local text messages that were received by one or more users. This API will not operate on forward messages, binary messages sent in either direction, or return messages that were received by applications only.

Required Parameter Group Details:
(1) Global Message Handle
INPUT; PACKED(9,0)
This parameter must contain the unique global message handle of a valid text message that:

1. is return or local (not a forward) message, and
2. currently exists in the caller's mailbox (or in the optionally specified user's mailbox)

(2) Return Status
OUTPUT; CHAR(1)
Status value returned to the caller will be set as follows:

(3) Reason Code
OUTPUT; CHAR(4)
This parameter contains a reason code. Possible values returned include;

(4) Mark All
INPUT; CHAR(1)
If specified, this optional input parameter must contain Y, N, or I. If set to Y or I, the API will mark every recipient's copy as SEEN or IGND respectively, rather than just the caller of the API. None of the recipient's copies will be set to CLMD. Calling the API with this flag set to Y or I has the effect of removing the message from all recipients' unseen list.

(5) User Mailbox
INPUT; CHAR(10)
If specified, this optional input parameter must contain a registered QTRACS user or address list. This user or address list must also have received a copy of the message specified by the global message handle parameter. Also, a value of 'N' or 'I' must be specified for the Mark All parameter if a user is specified. If an address list is specified, the Mark All parameter must contain an 'I'.

Possible Implementations
One possible implementation of this API is to call it from a user's homegrown (non-QTRACS) interactive message viewer. When a user views a message from outside of QTRACS, he needs a way to remove the message from his unseen list. This can be achieved by imbedding a call to OMMKSEEN from within his application. In so doing, the QTRACS Message Database is updated the same as if the user had used the QTRACS message display to view his message.

Another possible implementation of this API is to call it from a background external application. This application may handle a message and decide that it wants to 'claim it' or 'ignore it' on behalf of one of the users or a coverage who received the message. This can be achieved by imbedding a call to OMMKSEEN from within the external application. In this instance, the optional PMUSER parameter is specified to indicate for which user or group of users the message should be claimed or ignored. In so doing, the QTRACS Message Database is updated the same as if the specified user had used the QTRACS message display to view his message.
Another possible usage of this API is that it may be called from a user's break message handler

If a user's return message notification is set to *BRKWDW, then a popup window breaks to the user whenever a return message from a vehicle arrives for him. This popup window displays the first five lines of the message. After reading the message, the user may choose to hit F7=Mark Message which would call this API. In this way he would 'mark seen' (or claim) the message without using the actual Message Directory option to display the message.

Effect
A successful call to this API will have one of six effects on the specified message depending upon which parameters are specified on the call.

1. If PMMARK is not given (or it is given but set to N), and PMUSER is not specified, then the API will 'mark SEEN' (or CLMD, or IGND, etc...) the caller's copy of the specified message.
2. If PMMARK is specified (and set to Y), and PMUSER is not specified, then the API will 'mark SEEN' every recipient's copy of the specified message. In other words, the message will be removed from everyone's unseen list. This will happen regardless of who called the API and whether or not they are an actual message recipient. Additionally, no user will be set to CLMD or IGND, everyone's copy will simply be marked SEEN.
3. If PMMARK is specified (and set to I), and PMUSER is not specified, then the API will 'mark IGND' every recipient's copy (providing the user is eligible for ignoring messages) of the specified message. In other words, the message will be removed from everyone's unseen list, unless the user is ineligible for ignoring messages. If the user is ineligible for ignoring messages, the message remains UNSEEN. This will happen regardless of who called the API and whether or not they are an actual message recipient. Additionally, no user will be set to CLMD or SEEN, everyone's copy will simply be marked IGND.
4. If PMUSER is specified and is a registered QTRACS user (and PMMARK is set to N), then the API will 'mark SEEN' (or CLMD, or IGND, etc...) the specified user's copy of the specified message.
5. If PMUSER is specified with a registered QTRACS user (and PMMARK is set to I), then the API will 'mark IGND' the specified user's copy of the specified message. The specified user must be eligible for ignoring messages, otherwise the message will remain UNSEEN.
6. If PMUSER is specified with a registered QTRACS address list (and PMMARK is set to I), then the API will 'mark IGND' every address list recipient's copy of the specified message. The user must be eligible for ignoring messages, otherwise the message will remain UNSEEN.

Another way to understand how this API will operate is to examine the following table. The various permutations of the three input parameters will yield the described results.