MAIL GROUP API ICR (3006)

Name

Value

NUMBER

3006

IA #

3006

DATE CREATED

1999/11/30

CUSTODIAL PACKAGE

MAILMAN

CUSTODIAL ISC

San Francisco

USAGE

Supported

TYPE

Routine

DBIC APPROVAL STATUS

APPROVED

ROUTINE

XMXAPIG

NAME

MAIL GROUP API

GENERAL DESCRIPTION

The APIs in this DBIA perform mail group functions and
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:

XMGROUP  - Mail group IEN or name (exact, case-sensitive)

STATUS

Active

XMXAPIG

COMPONENT/ENTRY POINT

COMPONENT DESCRIPTION

VARIABLES

$$GOTLOCAL

Find out whether or not a mail group has any active
local members.  Function returns 1 if it does; 0 if it doesn't.

This can be important information.  Just because a mail group may have local
members, doesn't mean that any messages will be delivered to them.  They must
be active (have an access code and a mail box.)

If the mail group does not exist or if there are no active local members, the
function will return 0, XMERR will be defined, and there will be an
appropriate error message in ^TMP("XMERR",$J), as noted above, in the General
Description.

Usage: I '$$GOTLOCAL^XMXAPIG(XMGROUP[,XMDAYS][,XMMBRS) D error

Example: I '$$GOTLOCAL^XMXAPIG("GROUP") D error

If the mail group named GROUP has no active local members, do an error routine
to notify someone.  Otherwise, go ahead and send the message.

Optionally, you may specify an additional constraint, that at least one member
must have used MailMan in the last few days.

Example: I '$$GOTLOCAL^XMXAPIG("GROUP",9) D error

If the mail group named GROUP doesn't have at least one active local member
who has used MailMan in the last 9 days, do an error routine to notify
someone.  Otherwise, go ahead and send the message.

Optionally, you may specify an additional constraint, that there must be not
just 1, but at least XMMBRS active local members.

Example: I '$$GOTLOCAL^XMXAPIG("GROUP","",3) D error

There must be at least 3 active local members in the group.

VARIABLES

TYPE

VARIABLES DESCRIPTION

XMGROUP

Input

See General Description.

XMDAYS

Used

(optional) Active members of the group must have used
MailMan within the past number of days specified by XMDAYS.  If XMDAYS is 0 or
null or is not supplied, it is ignored.

XMMBRS

Used

Optional requirement that the group must contain at
least this many active local members.  Default is 1.

ADDMBRS

Add members to mail group(s).

Local users, devices, server options, mail groups, and remote users may be
added to mail groups using this API.  (Distribution lists, fax recipients, and
fax groups are not handled by this API.)

Optionally, find and forward existing mail group messages to the local users.

Usage: D ADDMBRS^XMXAPIG(XMDUZ,[.]XMGROUP,[.]XMMBR,.XMINSTR,.XMTSK)

VARIABLES	TYPE	VARIABLES DESCRIPTION
XMDUZ	Input	The user who is adding the members to the group(s). The user must be authorized to edit the mail groups. Group coordinators or organizers may edit their own groups. The following users may edit public groups or unrestricted private groups: - Clinical Application Coordinators - Anyone possessing the XMMGR key - Anyone possessing the XM GROUP EDIT MASTER key
XMGROUP	Input	The group(s) to be edited. May either be passed by value (for a single group) or by reference (for one or more groups). May be the ien(s) of the group(s) in the MAIL GROUP file 3.8, or their name(s) (full and exact). XMGROUP="GROUP A" - or - XMGROUP("GROUP A")="" XMGROUP("GROUP B")=""
XMMBR	Input	The new member(s). May be passed by value (for one member) or by reference (for one or more members). The same rules apply for specifying XMMBRs as apply when you're addressing a message.
XMINSTR	Used	Optional special instructions to forward past messages to the local members. XMINSTR("FLAGS") - May contain any combination of the following: "F" - Forward messages to users, if the users aren't already on the messages. XMINSTR("FDATE") - Add users to messages originating on or after this date. Must be any exact date recognized by FileMan. Default is from the beginning of time. Used in conjunction with FLAGS. XMINSTR("TDATE") - Add users to messages originating on or before this date. Must be any exact date recognized by FileMan. Default is the present. Used in conjunction with FLAGS.
XMTSK	Output	The number of the task which will find and forward past mail group messages to local users. Returned only if XMINSTR("FLAGS") is passed in.

JOIN

A user chooses to join one group, and optionally have
past mail group messages forwarded.

Usage: D JOIN^XMXAPIG(XMDUZ,XMGROUP,.XMINSTR,.XMTSK)

VARIABLES	TYPE	VARIABLES DESCRIPTION
XMDUZ	Input	The user who wants to join the group.
XMGROUP	Input	The group the user wants to join. See the General Description for more information.
XMINSTR	Used	Special instructions. See the description of the XMINSTR variable for entry ADDMBRS for more information. Additionally, if XMINSTR("FLAGS")=["F", may specify: XMINSTR("SELF BSKT") - the basket (name or ien) to which to deliver the messages
XMTSK	Output	Task number. See the description of XMTSK for entry ADDMBRS for more information.

DROP

User chooses to drop from one mail group.

Usage: D DROP^XMXAPIG(XMDUZ,XMGROUP)

VARIABLES	TYPE	VARIABLES DESCRIPTION
XMDUZ	Input	The user who wants to drop from the mail group.
XMGROUP	Input	The group from which the user wants to drop. See the General Description for more information.

$$MEMBER

Find out whether a user is a member of a mail group.
Function returns 1 if yes; 0 if no.

If the user isn't a direct member, optionally check to see if the user is a
member of any of the group's member groups.

Usage: I $$MEMBER^XMXAPIG(XMDUZ,XMGROUP[,XMCHKSUB]) D ...

VARIABLES	TYPE	VARIABLES DESCRIPTION
XMDUZ	Input	The user in question.
XMGROUP	Input	The group to check. See the General Description for more information.
XMCHKSUB	Used	If the user isn't found in the group, should we check the member groups? 1=yes; 0=no. Default is no.