MAILMAN: Server API    ICR (1151)

^XMS1 contains the following application programmer
functions:

$$STATUS^XMS1(MSGIEN,RDUZ) which extracts the status from network messages
only.

$$SRVTIME(MSGIEN,RDUZ,Status) which sets status of recipients in a message.





Appendix 1 -- Message Server Protocol


Overview

A server is an option which is invoked when a mail message that has been
addressed to it has been delivered.  As an option, many of the parameters
associated with the servers are embedded in the definition of the option.
Therefore, in order to understand servers completely, you should refer to the
server documentation in Kernel 7.0 manuals.  Options are listed in the Menu
Management documentation.

Servers may or may not receive data.  The received data usually comes in the
form of the text of the message being delivered to it, but the data may also
be pointed to by the message, and exist in the system either because it was
there in the beginning, or because it arrived independently.

Servers may be addressed from a remote  site.  A server on DNS may receive a
message addressed to it from DNS.  In fact, this is very common.  There are
security features as parameters of the option that has been designated as a
server because of the fact.  Please be aware of these security parameters.
Messages addressed to servers will not be scheduled if security is not passed.
Filegrams work through use of a server.  Data is loaded into a mail message,
addressed and when delivered, processed by the filegram server into the
receiving database.

Servers are always invoked through tasks that are set up when the message is
delivered into the system locally or over the network.  One of the options is
to "Run Immediately".  Then the task is scheduled to run "NOW".

However, tasks may not need to be scheduled at all because the system manager
has stated so in the entry for the server in the Option file or because of a
problem.  See the Menu Management documentation in the MailMan Technical
Manual and Systems Management Guide for more information concerning this.
Server Statuses

Server recipients are recorded in the recipient chain of a message and appear
similarly to other users.  MailMan enters statuses on its own as stages in the
server process are reached.  First, the message is marked as "Awaiting
Server".  This indicates that the message has been received and the option is
a valid one.  At this point, a task has been created to actually invoke
MenuMan to schedule or perform the service (option) required.

The last status which MailMan sets is "Served", which means that MenuMan has
been called successfully and MenuMan has either performed the task in the case
of a server that runs immediately, or that some other action has been done.

At this point, a task could be scheduled to invoke the server or simply a
message could be sent to indicate that the task exists and needs to be
scheduled, or some other action that was required was performed.  MenuMan has
its own statuses which will be used.


$$SRVTIME^XMS1

This extrinsic function sets status of recipients in a message.

Usage: S X=$$SRVTIME^XMS1(A,B,C)

Where: A = XMZ (message number)
B = A string representing the recipient name
C = Status is free-text (String less than nine (9)
characters in length)

If successful, X = 0
...or If unsuccessful, X will be a number followed by a human
readable error

Addressing a Server

To address a server, precede the recipient name with "S." (e.g., S.XMECHO).
This example sends a message to the Mail Man Echo Tester server.  "S." must be
followed by an option name from the Option file in the Target Domain.  If not,
a "Recipient not Found" error will occur.

A "Recipient Ambiguous" error will occur, if there is more than one option
whose name partially matches the name addressed.

The District Registry server for admitting a new patient could be addressed as
follows:

S.DGDISTADMIT@DNS

The message is destined for the DGDISTADMIT option at San Francisco.  Replies
to this message would be from this same name.


Writing a Server Program

The server communicates with mail messages in specific ways.  Code is used to
interface the server to the message system.  The code below returns the
original message to the sender:

ECHO    ;
K XMY
S XMSUB=$E("Server echo of'"_XMBSUB_"`",1,65)
S XMY(XMFROM)="",XMTXT="^XMB(3.9,"_XMZ_",2,"
D ^XMD
Q

In this example, the variable XMFROM contains the sender address and is
supplied to the server when invoked.  Other variables also exist upon
invocation of the server.

The XMF.1 example server program is supplied with MailMan.  XMF1 uses some of
the other variables supplied to the server.

Execute variable XMREC to read a line of the message.  XMER and XMRG are
returned.
XMER  This variable returns the execution status of XMREC.  XMER<0, if there
is no more message text to read.  The value of XMER will be zero (0), if XMRG
is being returned as non-null.  XMRG, in that case, will have as its value the
text of the next line of the message.

XMRG   The value of XMRG will be the next line of message text.  XMRG will
always be defined, though it will be null when XMER<0.

XMPOS  This variable contains the current position of the text returned in the
variable XMGR.  It is initialized if it is undefined, but should be killed by
the server when it is finished "Reading" the message.

Here's another example of code, this time from XMF1:

S XMA=0
A  ;
X XMREC        ;       Receive a line
I $D(XMER) G Q;XMER<0  ;       Check for end of message
S XMA=XMA+1    ;       Increment local line count
S XMTEXT(XMA)=XMRG     ;       Set local array
G A    ;       Go back for another line

Double Serving Messages

On occasion, the transmission/receive process is interrupted by a system
back-up.  It appears to result in the same message being served twice.  The
Audit Log for the Options file shows two messages with the same message number
and subject, but with different Date/Times and Job Numbers.


To avoid this, application servers should be written such that they check for
and avoid processing of the same message being delivered to any particular
server.  MailMan transparently checks this and does not deliver twice to mail
boxes.  However, devices and servers do not have mail boxes to check against.
Servers can have some understanding of special mail baskets in the
Postmaster's mail box and can be written to check for duplicate deliveries
(See reference XMAIC entry points in the Callable Routines section of the
Technical Manual and System Manager's Guide).