README file for the Character Conversion Callout Example
------------------------------------------------------------

Last modified: 01 May 2002 [for MX V5.3]

This module provides an example of the routines used by
MX to convert between the character set used locally on the
system and a standard character set used in Internet mail
messages.

When installed, the routines in this module are called
directly by MX's VMS MAIL interface to convert the following from
the local native character set to the network character set:
    - the VMS MAIL subject line -> RFC822 Subject: header
    - the sending user's "personal name" -> RFC822 From: header
    - the message text
If the result of the conversion includes any control characters
or characters with the high bit set, MX will encode the resulting
text using quoted-printable encoding rules.

The LOCAL agent calls these routines to convert the following
from the network character set to the local character set:
    - the RFC822 Subject: header -> VMS MAIL Subject line
    - the RFC822 From: header -> VMS MAIL From: header
    - the message text

Building the Callout Module
---------------------------

1.  Compile the module using DEC C:

    $ CC/DECC CHARCONV_EXAMPLE.C

2.  Create the shareable image:

    VAX:
    	$ LINK/SHARE/NOTRACE/EXEC=CHARCONV_EXAMPLE.EXE -
    	    CHARCONV_EXAMPLE.OBJ,SYS$INPUT:/OPT
    	UNIVERSAL=INIT,CONVERT,GETCSNAME,FINISH
    	<ctrl/Z>

    Alpha:
    	$ LINK/SHARE/NOTRACE/EXEC=CHARCONV_EXAMPLE.EXE -
    	    CHARCONV_EXAMPLE.OBJ,SYS$INPUT:/OPT
    	SYMBOL_VECTOR=(INIT=PROCEDURE,CONVERT=PROCEDURE,-
    	    	       GETCSNAME=PROCEDURE,FINISH=PROCEDURE)
    	<ctrl/Z>


Installing the Callout Module
-----------------------------

1.  Specify the local character set name:

    $ DEFINE/SYSTEM/EXEC MX_SITE_LOCAL_CHARSET "charsetname[=CRTL-charset-name]"

    The "charsetname" should be the preferred MIME name for the character set,
    or at least one of the registered names from the IANA character set registry.
    If this name differs from the name used by the DEC C run-time library, you
    should specify the mapping from the standard name to the CRTL name by separating
    the two names with "=".

    If you do not define this logical name, the module assumes that the local
    character set is the DEC Multinational Character Set.

2.  Specify the network character set name:

    $ DEFINE/SYSTEM/EXEC MX_SITE_NETWORK_CHARSET "charsetname[=CRTL-charset-name]"

    The "charsetname" should be the preferred MIME name for the character set,
    or at least one of the registered names from the IANA character set registry.
    If this name differs from the name used by the DEC C run-time library, you
    should specify the mapping from the standard name to the CRTL name by separating
    the two names with "=".

    If you do not define this logical name, the module assumes that the local
    character set is the ISO Latin-1 character set (ISO-8859-1).

3.  Copy the image to an appropriate location.  MAKE SURE it
    is set for WORLD:RE access.  Then define the following
    logical name:

    $ DEFINE/SYSTEM/EXEC MX_SITE_CHARACTER_CONVERSION dev:[dir]CHARCONV_EXAMPLE.EXE

4.  Make sure the DEFINEs above are in your system startup, BEFORE
    MX is started.

5.  If the character sets you select are other than DEC-MCS and ISO-8859-1 for
    the local and network character sets, respectively, make sure that the
    appropriage ICONV tables are installed in SYS$I18N_ICONV:, so the DEC C RTL
    can find them.

Known Problems and Restrictions
-------------------------------

You may need to modify the example code to properly handle multi-byte character
sets.