Nick de Smith, 27-Oct-87,27-Feb-89
----------------------------------

This directory contains a template alternate protocol shareable image
for VMS MAIL. It works with V5.0.

MAIL.COM is a DCL implementation of the MAIL-11 protocol. It also understands the
format for SYS$SYSTEM:VMSMAIL_PROFILE.DATA

PHONE.COM is a DCL example of using the PHONE protocol (not discussed here).


1.0 MASTER operation
--------------------
Alternate protocols in MAIL are invoked when a '%' is found in the
"To:" field of a message header. The general format is:

	protocol%[node::]protocol_data

The "protocol" field is extracted and the following operations applied:

1.1 The logical name "MAIL$PROTOCOL_protocol" is translated. If a translation
    is found, then:

	a) If the translation starts with a '%' then the string to the right
	   of the '%' is taken to be a DECnet access string for a remote
	   object that can talk MAIL-11 V3.0. eg.

			%ATGQ50::"TASK=MYMAIL"
	   would invoke the network object "MYMAIL" on node "ATGQ50::" and
	   attempt to talk MAIL-11 V3.0 to it.

	b) If the translation does not start with a '%', a name of the form:

		SYS$SHARE:translation.EXE

	   is formed. This file must be INSTALLed. MAIL will attempt to invoke
	   this shareable image. It must have 3 universal symbols:

		MAIL$C_PROT_MAJOR	Protocol major version number
		MAIL$C_PROT_MINOR	   ''    minor    ''     ''
		MAIL$PROTOCOL		Alternate protocol action routine

	   The example shareable image, PROTO, demonstrates this.

1.2 If no translation for "MAIL$PROTOCOL_protocol" is found, then the
    image "SYS$SHARE:protocol.EXE" is used. This shareable image must be
    installed. The same rules as for 1.1b above apply.

2.0 SLAVE operation
-------------------
If MAIL is invoked with the /PROTOCOL=protocol qualifier, and the process
has DETACH and SYSPRV privileges, then MAIL will assume that it is a network
slave and invoke "SYS$SHARE:protocol.EXE". The same rules as in 1.1b above
apply.

3.0 TEMPLATE PROTOCOL
---------------------
The template alternate protocol, PROTO, analyzes all calls from MAIL to the
MAIL$PROTOCOL alternate protocol handler. You should keep the PROTO.C and
PROTO_ACTION.MAR routines, and replace all the PROTO_IN_xxx, PROTO_OUT_xxx and
PROTO_IO_xxx routines with your own code. Change the PROTO.OPT LINK options
file to remove the default stubs and to include your own code as you write
it.

The command file INSTALL.COM installs the example protocol.
Install the example, then try sending a message to PROTO%someone.

BUILD.COM builds all the template sources.

LINK.COM		Link a protocol
	P1	Name of options file to use (defaults=PROTO.OPT)

INSTALL.COM
	P1	Name of protocol to install (default=PROTO)