Skip to main content
Omnitracs Knowledge Base

Get Unseen Messages Count - OMGTUNSC

Get Unseen Messages Count (OMGTUNSC) RI

Required Parameter Group:

1 Company Identifier Input Char(15)
2 Entity Identifier Input Char(15)
3 Return Status Output Char(1)
4 Return Block Output Char(5044)

API Overview:
The Get Unseen Messages Count API (OMGTUNSC) is used to retrieve unseen message counts for one or more QTRACS entities.

Required Parameter Group Details:
(1) Company Identifier
INPUT; CHAR(15)
This parameter contains a company identifier. It is for future use and is currently ignored.

(2) Entity Identifier
INPUT; CHAR(15)
This parameter must contain a left-justified QTRACS entity identifier or wildcard. Valid values are:

User Valid user identifier
Address List Valid address list identifier
*ALL All mailboxes
*ALLUSERS All users
*ALLADDLS All address lists

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

0 Success, unseen message counts returned
1 Failure, last position of entity id not blank
2 Failure, entity identifier is blank
3 Failure, entity identifier is invalid
4 Failure, the first 360 mailbox entries were processed and returned, but there are more. The next call to this API with the same entity identifier will return additional entries and counts.
A Failure, API failed when called remotely

(4) Return Block
OUTPUT; CHAR(5044)

1-4 Number of Array Elements Packed(7,0)
5-1444 Unseen Message Count Array(7,0 x 360) Packed(1440,0)
1445-5044 Mailbox Identifier Array(10 x 360) Char(3600)

Effect
A successful call to this API will result in the return of a status code and of a count of the unseen messages for the specified entity. Output results will vary with the given entity id parameter. The following table describes the output results for each of the possible entities or wildcards.

Entity Identifier Description of Output Results
User The 1 st array element of the Mailbox Identifier Array contains the user identifier.
The 1 st array element of the Unseen Message Count Array contains the unseen message count for this user. This unseen message count does not include ignored or marked messages.
Address List The 1 st array element of the Mailbox Identifier Array contains the address list identifier.
The 1 st array element of the Unseen Message Count Array contains the unseen message count for this address list. This unseen message count includes all messages addressed to this address list that have not yet been seen by at least one of its members.
*ALL The 1 st array element of the Mailbox Identifier Array contains the *ALL wildcard.
The 1 st array element of the Unseen Message Count Array contains the system-wide unseen message count. It is the total number of local or return messages that have not yet been seen by at least one person.
*ALLUSERS The array elements of the Mailbox Identifier Array contain all of the QTRACS user ids that have one or more unseen messages in their mailbox (up to 360).
The array elements of the Unseen Message Count Array contain the count of unseen messages for each of those users. As before, this count does not include ignored or marked messages.
If status code '4' is returned, then that means that the maximum number of users was reached (360) and there are more. Subsequent calls with the entity identifier '*ALLUSERS' will result in the retrieval of additional users and counts. Repetitive calls may be made to this API to get all remaining users. When all users have been returned, a status of '0' will be returned.
*ALLADDLS The array elements of the Mailbox Identifier Array contain all of the QTRACS address list ids that have one or more unseen messages on the system. In other words, if an address list is in this array, then there are one or more local or return messages on the system that have not yet been read by any of the members of that address list.
The array elements of the Unseen Message Count Array contain the count of unseen messages for each of those address lists.
  • Was this article helpful?