Print Page as PDF
MAILBOX AND BASKET API ICR (2723)

MAILBOX AND BASKET API    ICR (2723)

Name Value
NUMBER 2723
IA # 2723
DATE CREATED 1999/01/25
CUSTODIAL PACKAGE MAILMAN
CUSTODIAL ISC San Francisco
USAGE Supported
TYPE Routine
DBIC APPROVAL STATUS APPROVED
ROUTINE XMXAPIB
NAME MAILBOX AND BASKET API
GENERAL DESCRIPTION
The APIs in this DBIA perform mailbox and basket
actions.

If any errors occur, the following variables will be defined:

XMERR - The number of errors

^TMP("XMERR",$J,<error number>,"TEXT",<line number>)=<error text>

Following is information on some common input parameters:

XMDUZ   - The user (DUZ or enough of the user's name, alias, initials, or
nickname for a positive ID) for whom the API is being called.  An FM lookup
into the ^VA(200, NEW PERSON file will be performed.

XMK     - The basket (IEN or enough of its name for a positive ID) for which
the API is being called.

XMTROOT - (optional) The target root to receive the requested list.  This
quoted string must be a closed root.  The node "XMLIST" will be added
underneath it.  This is an optional parameter.  It defaults to
^TMP("XMLIST",$J).
STATUS Active
ID XMXAPIB
COMPONENT/ENTRY POINT
COMPONENT/ENTRY POINT COMPONENT DESCRIPTION VARIABLES
CRE8MBOX
Create a mailbox for a user.  That is, add the user
to file ^XMB(3.7, MAILBOX.  The user's IEN in this file is the same as the
user's IEN in ^VA(200, NEW PERSON file, that is, the user's DUZ.

Usage: D CRE8MBOX^XMXAPIB(XMDUZ,XMDATE)
VARIABLES TYPE VARIABLES DESCRIPTION
XMDUZ Input
The user for whom a mailbox should be created.  User
must already exist in ^VA(200,.  See General Description for further
information.
XMDATE Used
(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.
FLTRMBOX
Filter all messages in a user's mailbox.  Runs all
messages in all baskets in the user's mailbox through any filters which may
exist for the mailbox.  Only the user or a surrogate may use this API.

Usage: D FLTRMBOX^XMXAPIB(XMDUZ,.XMMSG)
VARIABLES TYPE VARIABLES DESCRIPTION
XMDUZ Input
See General Description.
XMMSG Output
If filtering is completed successfully, contains the
message, "Mailbox filtered".
QMBOX
Query a mailbox for new messages.  Only the user or a
surrogate may use this API.

Usage: D QMBOX^XMXAPIB(XMDUZ,.XMMSG)
VARIABLES TYPE VARIABLES DESCRIPTION
XMDUZ Input
See General Description.
XMMSG Output
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)
TERMMBOX
Remove all traces of a user from MailMan globals.
Only a Postmaster surrogate or XMMGR key holder may use this API.

Usage: D TERMMBOX^XMXAPIB(XMDUZ)
VARIABLES TYPE VARIABLES DESCRIPTION
XMDUZ Input
The user whose mailbox is to be terminated.  User
must still exist in ^VA(200,.  See General Description for further
information.
CRE8BSKT
Create a basket.  Only the user or a surrogate may
use this API.  If the user is SHARED,MAIL, then the surrogate must be a
Postmaster surrogate or XMMGR key holder.

Usage: D CRE8BSKT^XMXAPIB(XMDUZ,XMKN,.XMK)
VARIABLES TYPE VARIABLES DESCRIPTION
XMDUZ Input
The user for whom a basket is to be created.  See
General Description for more information.
XMKN Input
The name of the basket to be created.  It must be
free text, from 2 to 30 characters.
XMK Output
The IEN of the basket which was created.
DELBSKT
Delete a basket.  The special baskets (IN and WASTE)
may not be deleted.  Only empty baskets may be deleted, unless XMFLAGS
contains "D".  Only the user or a surrogate may use this API.  If the user is
SHARED,MAIL, then the surrogate must be a Postmaster surrogate or XMMGR key
holder.

Usage: D DELBSKT^XMXAPIB(XMDUZ,XMK,XMFLAGS)
VARIABLES TYPE VARIABLES DESCRIPTION
XMDUZ Input
The user for whom a basket is to be deleted.  See
General Description for more information.
XMK Input
Basket to be deleted.  See General Description for
more information.
XMFLAGS Used
(optional) Used to control processing.  May contain
any of the following:

D - Delete this basket even if there are messages in it.
FLTRBSKT
Filter messages in a basket.  Runs all messages in a
basket through any filters which may exist for the mailbox.  Only the user or
a surrogate may use this API.  If the user is SHARED,MAIL, then the surrogate
must be a Postmaster surrogate or XMMGR key holder.

Usage: D CRE8MBOX^XMXAPIB(XMDUZ,XMK,.XMMSG)
VARIABLES TYPE VARIABLES DESCRIPTION
XMDUZ Input
The user whose basket is to be filtered.  See General
Description for more information.
XMK Input
The basket to be filtered.  See General Description
for more information.
XMMSG Output
If filtering is completed successfully, contains the
message, "Basket filtered".
LISTBSKT
Get a list of baskets in a mailbox.  Gets a list
(similar in format to that produced by LIST^DIC) of a user's baskets,
optionally restricting the list to only those baskets with new mail, and/or
those baskets whose name starts with a certain string.

Note:  Regardless of the alphabetic order you request, lower-case names sort
separately from upper-case names.  Therefore, an all upper-case cross
reference (under "BSKT") is provided if you do not limit the number of entries
returned.

Usage: D LISTBSKT^XMXAPIB(XMDUZ,XMFLAGS,XMAMT,.XMSTART,XMPART,XMTROOT)
VARIABLES TYPE VARIABLES DESCRIPTION
XMDUZ Input
The user for whom a basket list is to be compiled.
See General Description for more information.
XMFLAGS Used
(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.
XMAMT Used
(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.
XMSTART Both
(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.
XMPART Used
(optional) Get a list only of those baskets whose
name starts with this string.
XMTROOT Used
(optional) The target root to receive the message
list.  See General Description for more information.
LISTMSGS
Get a list a messages in a mailbox or in the Message
file.

Gets a list (similar in format to that produced by LIST^DIC) of messages in
one basket or all baskets, optionally based on certain criteria.  Also can get
a list of messages in the Message file which were sent to or by the user and
are not necessarily still in the user's mailbox.  The IENs of the messages (in
the message file 3.9) are returned.  Only the user or a surrogate may use this
API.

Also enables 'Super Search' of all messages in the message file, regardless of
who sent them.  This search should only be used in coordination with the
site's ISO, and is intended to be used to gather evidence in cases such as EEO
harassment.  Only holders of the XM SUPER SEARCH key may use this capability.

Usage: D
LISTMSGS^XMXAPIB(XMDUZ,XMK,XMFLDS,XMFLAGS,XMAMT,.XMSTART,.XMCRIT,XMTROOT)
VARIABLES TYPE VARIABLES DESCRIPTION
XMDUZ Input
The user for whom a message list is to be compiled.
See General Description for more information.
XMK Input
The basket to look in.

Possible values:

IEN or name - look in this basket only

* - look in all baskets

! - look in the Message file.
XMFLDS Used
(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
XMFLAGS Used
(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)
XMAMT Used
(optional) How many messages should be returned?

Possible values:

<number> - this many

*        - all (default)
XMSTART Both
(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.)
XMCRIT Used
NAMEBSKT
Change the name of a basket.  The IN and WASTE
baskets may not be renamed.  Only the user or a surrogate with 'write'
privilege may use this API.  If the user is SHARED,MAIL, then the surrogate
must be a Postmaster surrogate or XMMGR key holder.

Usage: D NAMEBSKT^XMXAPIB(XMDUZ,XMK,XMKN)
VARIABLES TYPE VARIABLES DESCRIPTION
XMDUZ Input
The user whose basket is to be renamed.  See General
Description for more information.
XMK Input
The basket to be renamed.  See General Description
for more information.
XMKN Input
The new name of the basket.  It is free text, from 2
to 30 characters.
QBSKT
Get information about a basket.  Only the user of a
surrogate may use this API.

Usage: D QBSKT^XMXAPIB(XMDUZ,XMK,.XMMSG)
VARIABLES TYPE VARIABLES DESCRIPTION
XMDUZ Input
The user whose basket is to be queried.  See General
Description for more information.
XMK Input
The basket to be queried.  See General Description
for more information.
XMMSG Output
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
RSEQBSKT
Resequence messages in a basket.  Before any
resequencing is done, a basket integrity check is performed, and any errors
detected are corrected.  Only the user or a surrogate may use this API.  If
the user is SHARED,MAIL, then the surrogate must be a Postmaster surrogate or
XMMGR key holder.

Usage: D RESEQBSKT^XMXAPIB(XMDUZ,XMK,.XMMSG)
VARIABLES TYPE VARIABLES DESCRIPTION
XMDUZ Input
The user whose basket messages are to be resequenced.

See General Description for more information.
XMK Input
The basket to be resequenced.  See General
Description for more information.
XMMSG Output
If resequencing is completed successfully, string
contains the message: "Resequenced from 1 to <number of messages in basket>".

MAIL MESSAGE 28881098
Generated from SEP 10, 2019@ IA Listing Descriptions