USER ENVIRONMENT API ICR (2728)

Name

Value

NUMBER

2728

IA #

2728

DATE CREATED

1999/01/27

CUSTODIAL PACKAGE

MAILMAN

CUSTODIAL ISC

San Francisco

USAGE

Supported

TYPE

Routine

DBIC APPROVAL STATUS

APPROVED

ROUTINE

XMVVITAE

NAME

USER ENVIRONMENT API

GENERAL DESCRIPTION

Create the MailMan environment in which the user will
operate while in MailMan.

Set up the user's XMV array, which contains vital user information, user
preferences, and, if the user is a surrogate, the user's level of
authorization.  The information in this array is used throughout MailMan.

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>

STATUS

Active

XMVVITAE

COMPONENT/ENTRY POINT

COMPONENT DESCRIPTION

VARIABLES

INIT

Set up the user's MailMan environment in array XMV,
which contains vital user information, user preferences, and, if the user is a
surrogate, the user's level of authorization.

This entry point is meant to be called once, upon entry into MailMan.  It
should not be used at any other time.  Many of the MailMan APIs assume that
the information provided by this routine exists.  They may abort if it
doesn't.

Usage: D INIT^XMVVITAE

VARIABLES	TYPE	VARIABLES DESCRIPTION
DUZ	Input	Set by KERNEL when the user logs in to the system, it is a unique user ID, and the IEN for the user in the NEW PERSON file. It is also the IEN for the user in the MAILBOX file.
XMDUZ	Both	(optional) If the user (as identified by DUZ) is acting as a surrogate for another user, XMDUZ should be set by the calling routine to the DUZ of the other user. If XMDUZ is not set by the calling routine, it is assumed that the user is acting for himself, and XMDUZ will be set to DUZ (default) by this routine.
XMDISPI	Output	String containing two up-arrow-delimited pieces of information: Piece 1: Any combination of the following: A - Ask basket, if user sends message to self I - Show institution T - Show title Piece 2: One of the following IN basket message action defaults: I - Ignore the message D - Delete the message NOTE: MailMan does not use this variable, as it duplicates information provided in XMV.
XMDUN	Output	Provides same information as XMV("NAME"). NOTE: MailMan does not use this variable, as it duplicates information provided in XMV.
XMNOSEND	Output	=1, if XMV("NOSEND")=1. Otherwise, not defined. NOTE: MailMan does not use this variable, as it duplicates information provided in XMV.
XMPRIV	Output	If the user is acting as a surrogate, then this string contains two pieces of up-arrow-delimited information, concerning the user's privileges: Piece 1: Does the user have read privilege? y - Yes n - No Piece 2: Does the user have send privilege? y - Yes n - No If the user is acting as a surrogate, then this variable is defined. Otherwise, it isn't. NOTE: MailMan does not use this variable, as it duplicates information provided in XMV.
XMV	Output	An array of values defining the user's MailMan environment, giving information about the user, the user's MailMan preferences, and, if the user's acting as a surrogate, what privileges the user has. The information in this array is used throughout MailMan. The following items will always be set: XMV("ASK BASKET") If user sends a message to himself, should MailMan ask, "which basket?" (0=yes; 1=no) XMV("DUZ NAME") The user's name. (DUZ) XMV("LAST USE") String, in external format, showing when was the last time the user entered MailMan, and if it was a surrogate, which one. If the user never entered MailMan, the string will be "Never". (XMDUZ) XMV("MSG DEF") The default action for a message in the IN basket (I=ignore; D=delete). (DUZ) XMV("NAME") The user's name. (XMDUZ) XMV("NETNAME") The user's network name. (XMDUZ) XMV("NEW MSGS") The number of new messages in the user's mailbox. (XMDUZ) XMV("NOSEND") May the user send messages in this session? (1=no; 0=yes) The user may not send messages in any but the first of multiple concurrent sessions. (XMDUZ) XMV("ORDER") Display the user's messages in which order? (-1=reverse; 1=forward) (DUZ) XMV("PREVU") In the Classic reader, should message previews be displayed? (0=no; 1=yes) (DUZ) XMV("RDR ASK") Ask the user which message reader to use? (N=no; Y=yes) (DUZ) XMV("RDR DEF") User's default message reader (C=classic; D=detailed full screen; S=summary full screen) (DUZ) XMV("SHOW DUZ") Show user's DUZ? (0=no; 1=yes) (site) XMV("SHOW INST") Show user's institution? (0=no; 1=yes) (site) XMV("SHOW TITL") Show user's title? (0=no; 1=yes) (DUZ) XMV("VERSION") What version of MailMan is at this site? "VA MailMan "_version # (site) The following items will be set only if conditions warrant: XMV("BANNER") The user's banner, if one exists; otherwise not defined. (XMDUZ) XMV("ERROR",1) "You do not have a DUZ" if '$D(DUZ). XMV("ERROR",2) "There is no person with DUZ "_XMDUZ_"." if bogus XMDUZ. XMV("ERROR",3) "There is no Access Code for DUZ "_XMDUZ_"." XMV("ERROR",4) "There is no Mailbox for DUZ "_XMDUZ_"." XMV("PRIV") If user is acting as a surrogate, contains the user's privilege(s). Any or all of the following: R - read W - write (send) XMV("SYSERR",i) If Domain incorrectly set up, contains text. (site) XMV("WARNING",1) "Priority Mail" if user has priority mail (XMDUZ) XMV("WARNING",2) "Message in Buffer" (XMDUZ) XMV("WARNING",3) "No Introduction" if user has no intro, but site requires one. (XMDUZ) XMV("WARNING",4) "Multiple Signon" if user is in MailMan in more than one session. (XMDUZ) XMV("WARNING",5) "POSTMASTER has "_I_" baskets." if more than 900 (Only if XMDUZ=.5)

OTHER

Set up MailMan user environment when user becomes a
surrogate.  INIT^XMVVITAE should already have been called.  If the XMV
variable does not exist, control will be passed to INIT^XMVVITAE, instead.

Usage: D OTHER^XMVVITAE

VARIABLES	TYPE	VARIABLES DESCRIPTION
XMV	Output	An array of values giving information about the user for whom the user is acting as a surrogate. Also specifies what surrogate privileges the user has. The information in this array is used throughout MailMan. The following items will always be set, as they pertain to the user for whom the user is acting as a surrogate. Please see entry INIT for a description of the variables. XMV("LAST USE") XMV("NAME") XMV("NETNAME") XMV("NEW MSGS") XMV("NOSEND") XMV("PRIV") The following items will be set only if conditions warrant: XMV("BANNER") XMV("ERROR",1) XMV("ERROR",2) XMV("ERROR",3) XMV("ERROR",4) XMV("WARNING",1) XMV("WARNING",2) XMV("WARNING",3) XMV("WARNING",4) XMV("WARNING",5)
XMDUZ	Both	OTHER^XMVVITAE is specifically designed for becoming a surrogate. Therefore, XMDUZ must be the DUZ of the user to become. It follows that XMDUZ should not equal DUZ. See the variable description for entry INIT for further information.
DUZ	Input	See the variable description for entry INIT.
XMDUN	Output	See the variable description for entry INIT.
XMNOSEND	Output	See the variable description for entry INIT.
XMPRIV	Output	See the variable description for entry INIT.

SELF

Return to the user's own MailMan user environment
after having finished acting as a surrogate.

Usage: D SELF^XMVVITAE

VARIABLES	TYPE	VARIABLES DESCRIPTION
DUZ	Input	See the variable description for entry INIT.
XMDUZ	Output	XMDUZ will be set equal to DUZ, as the first step in returning the user to his own identity.
XMDUN	Output	See the variable description for entry INIT.
XMNOSEND	Output	See the variable description for entry INIT.
XMV	Output	An array of values defining the user and the user's MailMan environment. The information in this array is used throughout MailMan. The following items will always be set. Please see entry INIT for a description of the variables. XMV("NAME") XMV("NETNAME") XMV("NEW MSGS") XMV("NOSEND") The following items will be set only if conditions warrant: XMV("BANNER") XMV("ERROR",1) XMV("ERROR",2) XMV("ERROR",3) XMV("ERROR",4) XMV("WARNING",1) XMV("WARNING",2) XMV("WARNING",3) XMV("WARNING",4) XMV("WARNING",5)