Get Next Unseen Message - OMGETUNS
Get Next Unseen Message (OMGETUNS)
Required Parameter Group:
| 1 | User Mailbox | Input | Char(10) |
| 2 | Function Code | Input | Char(1) |
| 3 | Mark Message as Seen | Input | Char(1) |
| 4 | GMH of Next Unseen Message | Output | Packed(9,0) |
| 5 | Return Status | Output | Char(1) |
API Overview:
The Get Next Unseen Message API (OMGETUNS) is used to return the Global Message Handle of the 'next' unseen message in a specified user's mailbox. This API accepts input parameters which specify which unseen message GMH to retrieve from a given user's mailbox.
This API will be useful for external applications that need to process the 'unseen list' for a user from outside of the QTRACS user interface. The returned GMH may then be used by the integration code to call other QTRACS APIs, i.e. OMGETMSG (to get other message info), OMQTDSP (to display the message via the QTRACS user interface).
Required Parameter Group Details:
(1) User Mailbox
INPUT; CHAR(10)
This parameter specifies the user mailbox from which to retrieve the message. This required field must be a valid QTRACS user identifier.
(2) Function Code
INPUT; CHAR(1)
This parameter specifies which unseen message to return from the specified user's mailbox. Valid values are:
| 1 | Get the GMH of the oldest unseen message for the user |
| 2 | Get the GMH of the 'next' oldest unseen message for the user (this assumes the file cursor has been set by a previous call) |
| 9 | Don't return anything; just reclaim memory, close files and return to the calling application |
(3) Mark Message as Seen
INPUT; CHAR(1)
This parameter specifies whether the unseen message should be marked as seen (or claimed) prior to returning control to the calling application. Valid values are:
| Y | Mark the message as seen (or claimed) |
| N | Don't update the message status, just leave it as unseen |
(4) GMH of Next Unseen Message
OUTPUT; PACKED(9,0)
This parameter contains the Global Message Handle of the unseen message (if found).
(5) Return Status
OUTPUT; CHAR(1)
Status value returned to the caller will be set as follows:
| 0 | Success, GMH found & returned |
| 1 | Failure, no GMH found |
| 2 | Failure, invalid user mailbox parameter |
| 3 | Failure, invalid function code parameter |
| 4 | Failure, invalid mark message as seen parameter |
| 5 | Failure, begin or end of file condition found on get next operation |
| 6 | Failure, message could not be claimed |