PROGRAMMER API ICR (10064)

Name

Value

NUMBER

10064

IA #

10064

DATE CREATED

1995/01/31

CUSTODIAL PACKAGE

MAILMAN

CUSTODIAL ISC

San Francisco

USAGE

Supported

TYPE

Routine

DBIC APPROVAL STATUS

APPROVED

ROUTINE

NAME

PROGRAMMER API

ORIGINAL NUMBER

10064

GENERAL DESCRIPTION

^XM contains these programmer entry points:

^XM is the normal routine programmers invoke to use MailMan directly.  No menu
item leads to ^XM.  KILL^XUSCLEAN is invoked so only basic Kernel parameters
survive call.

EN^XM is the entry action for the top-level interactive MailMan option.  It
invokes INIT^XMVVITAE to set up the user's MailMan environment.  It invokes
HEADER^XM to greet the user and inform the user of new messages.  It is
normally used only in top-level options; other types of uses should invoke the
individual entry points directly.

CHECKIN^XM is the entry action for subordinate interactive MailMan options.

CHECKOUT^XM is the exit action for all interactive MailMan options.

HEADER^XM greets the user and informs of new messages.

KILL^XM kills MailMan variables.

$$NU^XM Returns the number of new messages a user has and may display the
message: "You have # new messages."

N1^XM and NEW^XM create a mailbox for a user.

STATUS

Active

COMPONENT/ENTRY POINT

COMPONENT DESCRIPTION

VARIABLES

EN^XM is the entry action for the top-level
interactive MailMan option.  It invokes INIT^XMVVITAE to set up the user's
MailMan environment.  It invokes HEADER^XM to greet the user and inform the
user of new messages.  It is normally used only in top-level options; other
types of uses should invoke the individual entry points directly.

Options at other than the top level should not use EN^XM as an entry action.
Instead, they should use CHECKIN^XM.

An example of how EN^XM is used in a top-level option's ENTRY ACTION follows:

NAME: XMUSER                            MENU TEXT: MailMan Menu
TYPE: menu                            CREATOR: BEUSCHEL,GARY
HELP FRAME: XMHELP                    PACKAGE: MAILMAN
E ACTION PRESENT: YES                 X ACTION PRESENT: YES
DESCRIPTION:   This is the main MailMan option menu for normal user
interaction.  It allows the user to Send and Receive messages, as well as
manage baskets.
ITEM: XMNEW                             SYNONYM: NML
DISPLAY ORDER: 1
ITEM: XMREAD                            SYNONYM: RML
DISPLAY ORDER: 2
ITEM: XMSEND                            SYNONYM: SML
DISPLAY ORDER: 3
ITEM: XMSEARCH                          DISPLAY ORDER: 4
ITEM: XMASSUME                          DISPLAY ORDER: 5
ITEM: XM PERSONAL MENU                  DISPLAY ORDER: 6
ITEM: XMOTHER                           DISPLAY ORDER: 7
ITEM: XMHELP                            DISPLAY ORDER: 8
EXIT ACTION: K XMMENU D CHECKOUT^XM
ENTRY ACTION: S XMMENU(0)="XMUSER" D EN^XM

Notice that XMMENU(0) is set in the entry action.  It doesn't have to be set
to "XMUSER".  It can be any string.  It is suggested that is be the option
name.  Setting this variable causes MailMan to check to see if the user
already has another MailMan session in progress.  If so, the user will be
notified that s/he won't be able to send mail in any but the primary session.
The reason for this is that when a user is creating a message, the message ID
(XMZ) is stored in the user's mailbox record.  If the user's session aborts
for some reason, when the user logs on again, MailMan informs the user of the
unsent message and asks if s/he wishes to continue with it.  There is only one
field to store the message ID, and that is why only one session may send
messages.

KILL

Kill all Mailman variables.

Usage: D KILL^XM

$$NU

Returns the number of new messages a user has, and
may display the message: "You have # new messages."

Compare to:
QMBOX^XMXAPIB, QBSKT^XMXAPIB (DBIA 2723)
$$BNMSGCT^XMXUTIL, $$TNMSGCT^XMXUTIL, $$NEWS^XMXUTIL (DBIA 2734)

Usage: S X=$$NU^XM(FORCE)

VARIABLES

TYPE

VARIABLES DESCRIPTION

DUZ

Input

The user's DUZ.

XMDUZ

Used

(optional) The user whose mailbox is to be checked.
Default is DUZ.

FORCE

Input

Should the message, "You have <x> new messages." be
displayed?

Possible values:

0 - Display the message only if the user has received new messages since the
last time the message was displayed.

1 - Display the message.

Create a mailbox for a user.

Compare to:
NEW^XM
CRE8MBOX^XMXAPIB (DBIA 2723)

Usage: S XMDUZ=<user's DUZ> D N1^XM

VARIABLES

TYPE

VARIABLES DESCRIPTION

XMDUZ

Input

The DUZ of the user for whom the mailbox should be
created.

XMZ

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 variable has
no effect and shouldn't be used.

Possible values:

If '$D(XMZ), then the user may access any message on the system which was ever
addressed to the user.

If $D(XMZ), then the user will not be able to access any message addressed to
the user on the system earlier than today's date, unless it is already in the
user's mailbox or if someone forwards it to the user.

NEW

Create a mailbox for a user.

Compare to:
N1^XM
CRE8MBOX^XMXAPIB (DBIA 2723)

Usage: S Y=<user's DUZ> D NEW^XM

VARIABLES	TYPE	VARIABLES DESCRIPTION
Y	Input	The DUZ of the user for whom the mailbox is to be created.
XMZ	Used	See the description for XMZ in entry N1.

HEADER

Meant to be part of the ENTRY action of the primary
MailMan option, whether called by itself, or as part of another call, such as
EN^XM.

Display user information and greeting upon entry into MailMan.

CHECKIN

Meant to be part of any subordinate MailMan option's
ENTRY action.

Example:

NAME: XMSEND                            MENU TEXT: Send a Message
TYPE: run routine                     CREATOR: BEUSCHEL,GARY
HELP FRAME: XM-U-M-SEND               PACKAGE: MAILMAN
E ACTION PRESENT: YES                 X ACTION PRESENT: YES
DESCRIPTION:   Enables the user to send MailMan messages.  Messages may be
sent to other users or groups of users.  The sender of the message may request
a confirmation message, to be sent to him as each recipient reads the message.
EXIT ACTION: D CHECKOUT^XM            ENTRY ACTION: D CHECKIN^XM
ROUTINE: SEND^XMJMS                   TIMESTAMP: 53272,53151
UPPERCASE MENU TEXT: SEND A MESSAGE

CHECKOUT

Meant to be part of every MailMan option's EXIT
action.

Example:

NAME: XMSEND                            MENU TEXT: Send a Message
TYPE: run routine                     CREATOR: BEUSCHEL,GARY
HELP FRAME: XM-U-M-SEND               PACKAGE: MAILMAN
E ACTION PRESENT: YES                 X ACTION PRESENT: YES
DESCRIPTION:   Enables the user to send MailMan messages.  Messages may be
sent to other users or groups of users.  The sender of the message may request
a confirmation message, to be sent to him as each recipient reads the message.
EXIT ACTION: D CHECKOUT^XM            ENTRY ACTION: D CHECKIN^XM
ROUTINE: SEND^XMJMS                   TIMESTAMP: 53272,53151
UPPERCASE MENU TEXT: SEND A MESSAGE