MAILBOX AND BASKET API    ICR (2723)

The user for whom a mailbox should be created.  User
must already exist in ^VA(200,.  See General Description for further
information.

(optional) Users who are being reinstated after not
having worked here for a while may be restricted from seeing messages earlier
than a certain date.  If the user is a first-time user, then this parameter
has no effect and shouldn't be used.

Possible values:

=0 or null (default) - The user may access any message on the system which was
ever addressed to the user.

=date - The user may not access any message addressed to the user on the
system earlier than this date, unless it is already in the user's mailbox or
if someone forwards it to the user.  The date must be a FileMan date or any
date format which FileMan recognizes.

See General Description.

If filtering is completed successfully, contains the
message, "Mailbox filtered".

See General Description.

String giving information on the user's new messages.

If user has no new messages, string is 0 (zero).

If user has new messages, string contains the following up-arrow delimited
pieces of information:

Piece 1: number of new messages in the mailbox

Piece 2: does the user have priority mail (0=no; 1=yes)

Piece 3: number of new messages in the IN basket

Piece 4: date/time (FM format) that the last message was received

Piece 5: have there been any new messages since the last time this API was
called? (0=no; 1=yes)

The user whose mailbox is to be terminated.  User
must still exist in ^VA(200,.  See General Description for further
information.

The user for whom a basket is to be created.  See
General Description for more information.

The name of the basket to be created.  It must be
free text, from 2 to 30 characters.

The IEN of the basket which was created.

The user for whom a basket is to be deleted.  See
General Description for more information.

Basket to be deleted.  See General Description for
more information.

(optional) Used to control processing.  May contain
any of the following:

D - Delete this basket even if there are messages in it.

The user whose basket is to be filtered.  See General
Description for more information.

The basket to be filtered.  See General Description
for more information.

If filtering is completed successfully, contains the
message, "Basket filtered".

The user for whom a basket list is to be compiled.
See General Description for more information.

(optional) Used to control processing.  May be any
combination of the following:

B - Backwards alpha order (default is alpha order)

N - List only those baskets with new messages.

(optional) How many baskets should be in the list?

Possible values:

<number> - This many.  Upper case xref (under "BSKT") is NOT provided.

* - All baskets (default).  Upper case xref (under "BSKT") is provided.

(optional) Provides a starting point from which to
get the list.  It is used to start the lister going.  The calling routine does
not need to set it.  Default is to start with the lowest numbered basket IEN
and to start, in each successive call, where the previous call left off.  The
lister will keep it updated from call to call.

Note:  This parameter is used if XMAMT is a number, and you intend to call
this entry point repeatedly until there are no more baskets.

(optional) Get a list only of those baskets whose
name starts with this string.

(optional) The target root to receive the message
list.  See General Description for more information.

The user for whom a message list is to be compiled.
See General Description for more information.

The basket to look in.

Possible values:

IEN or name - look in this basket only

* - look in all baskets

! - look in the Message file.

(optional) A string containing a list, separated by
';', of fields to retrieve.  Default is none.

Possible values include any combination of the following, separated by ';':
(e.g., "SUBJ;DATE")

BSKT - basket (default: <basket IEN>^<basket name>)
Optionally followed by ":" and
I - for basket IEN only (no 2nd piece)
X - adds basket name xref
(If XMK="!", and the message is not in the user's mailbox, will
be set to "0^* N/A *".)

DATE - date sent (default:<internal date>^<dd mmm yy hh:mm>
Optionally followed by ":" and
I - for internal only (no 2nd piece)
F - for FM date as the 2nd piece
X - adds FM date xref

FROM - message from (default: <internal from>^<external from>)
Optionally followed by ":" and
I - for internal only (no 2nd piece)
X - adds external from xref

LINE - number of lines in the message

NEW  - is the message new? (0=no; 1=yes; 2=yes, and priority, too)

PRI  - is the message priority? (0=no; 1=yes)

READ - how much of the message has the user read?
<null>   - has not read the message at all
0        - has read the message, but no responses
<number> - has read through this response

RESP - how many responses does the message have?
0        - none
<number> - this many

SEQN - sequence number in basket

SUBJ - message subject (always external)
Optionally followed by ":" and
X - adds message subject xref

(optional) Flags control processing.  May be any
combination of the following:

B - backwards order (default is traverse forward)

U - Ignore the file screen on file 3.9 so that all messages can be
examined.  (valid only if XMK="!" and the user possesses the
XM SUPER SEARCH key)

If XMK="!", the following flags are ignored:

C - use basket C-xref (default is message IEN)

N - new messages only (C flag ignored)

P - new priority messages only (C, N flags ignored)

(optional) How many messages should be returned?

Possible values:

<number> - this many

*        - all (default)

(optional) This may be used to start the lister
going.  The lister will keep it updated from call to call.  This variable is
usually used when XMAMT is set to a number, and multiple calls to this API may
be required.  This variable ensures that each successive call resumes where
the previous call left off.

(If XMK="!", FileMan handles XMSTART, and you should look at FM documentation
for an explanation.  Messing with XMSTART is not advised if XMK="!", unless
you are sure you know what you're doing.)

The following variables may updated, depending on how the API is called:

XMSTART("XMK")  - Start with this basket IEN (valid only if XMK="*").
Continues from there, with each successive call, to the
end.
(Default is to start with basket .5, the WASTE basket.)

XMSTART("XMZ")  - Start AFTER this message IEN (valid only if
XMFLAGS'["C").
Continues from there, with each successive call, to the
end.
(Default is to start at the beginning (or end) of the
basket.)

XMSTART("XMKZ") - Start AFTER this message C-xref (valid only if
XMFLAGS["C").
Continues from there, with each successive call, to the
end.
(Default is to start at the beginning (or end) of the
basket.)

The user whose basket is to be renamed.  See General
Description for more information.

The basket to be renamed.  See General Description
for more information.

The new name of the basket.  It is free text, from 2
to 30 characters.

The user whose basket is to be queried.  See General
Description for more information.

The basket to be queried.  See General Description
for more information.

String containing the following up-arrow-delimited
pieces of information:

Piece 1: basket IEN

Piece 2: basket name

Piece 3: number of messages in the basket

Piece 4: number of new messages in the basket

The user whose basket messages are to be resequenced.

See General Description for more information.

The basket to be resequenced.  See General
Description for more information.

If resequencing is completed successfully, string
contains the message: "Resequenced from 1 to <number of messages in basket>".