MAILMAN: Message Text - Direct Entry    ICR (10113)

Summary

Sites complain about the way their machines seems to slow down considerably
when Austin DPC transmissions are created.  Large messages may be created in a
more efficient way than is being used by most applications.  Since all DHCP
sites are mandated to migrate to Kernel 7.1 by 12/01/93, all applications can
now use this method of creating a message.


Technical Background

The simplest approach is probably the one people are using.  It is pretty
straight forward:

Load the text of a message into an array
Set a couple of variables
D ^XMD

With short messages, this is also fairly efficient if a local array is used.
However, when a large message is built, it usually must be stored in a global
array.  Then, MailMan must read it and re-write it.  This effectively doubles
the amount of work the system must do to compile the text of the message.  The
killing of the temporary global array built to store the data passed to the
MailMan programmer interface eats up additional resources.

So why not write the text of the message (the data) directly into the message,
especially now that it is possible and that all the entry points have been
made available and are documented?  Examine the examples on the following
lines.
Example

The following steps assume that the standard variables already exist in the
partition from either Log-on or because the job is a TaskMan task.

Step 1  --  Create a Message with No Text

S XMSUB="LARGE DATA TRANSMISSION";     Initialize Subject S XMDUZ="Application
X"          ;     Sender D GET^XMA2                       ;     Call Create
Message Module
See Note 1 below! I
XMZ<1 G RETRY        ;       Abort or retry, if returned value <1


Step 2  --  Put Text into Message
F L=1:1 S X=$$data^routine Q:X="stop value"  S ^XMB(3.9,XMZ,2,L,0)=X
S ^XMB(3.9,XMZ,2,0)="^3.92^"_L_"^"_L_"^"_DT


Step 3  --  Deliver Message to Recipients

S XMDUN="SENDER,LARGEMESSAGE"; A Sender can be free text or you can
;       Leave the variable undefined and the
;       message will appear to be from the
;       user who was logged on.  S XMY
("XXX@Q-AUSTIN_'Q'_DOMAIN")=""  ;  Remote Recipient S XMY(234567)=""
;   Individual as a recipient S XMY(234567)="basket name"  ;   Individual as
a recipient in a basket .
.
.
D ENT^XMD  ;                           Call for MailMan Delivery

The message will now be delivered.  This may not happen immediately because
the job of delivery the message is passed off to a 'background filer'.

------------------------------------------------------------------------

Note 1:        In versions of MailMan previous to Kernel Version 7, Step 1 may
occasionally fail!  The interface, upon failing, will cause the job to halt.
Because some applications require that a message be created as a result of a
background task, a new entry point has been created for Kernel 7 that will not
cause the process to be halted.  It will instead pass back to the caller an
indication of success (XMZ>0) or failure (XMZ<1).  The use of this new entry
point is illustrated below.  IT IS RECOMMENDED that all applications that use
the GET^XMA2entry point migrate to the XMZ^XMA2 entry point unless the
developers (being aware of the potential problem) decide otherwise.  If XMZ=-1
condition is not checked, this large message creation technique will stuff
data into ^XMTS(3.9,-1.  This may lead to other problems later on!


Note 2:        There is a way to tell MailMan to run silently via remote
domain when ENT1^XMD is called with the XMY("XXX@DOMAIN") set. If the XMCHAN
or ZTQUEUED variables are set, MailMan is usually silent.  MailMan is silent
when ZTQUEUED is present because it is a background job.  However, DO NOT set
the ZTQUEUED variable yourself! If anyone other than TaskMan ever sets
ZTQUEUED, the whole intent of the variable is lost.  Callers to the MailMan
API functions and callable entry points should set XMCHAN to ensure silent
operation.  Be sure to kill XMCHAN when completed.