README file for the Character Conversion Callout Example (Kanji)
----------------------------------------------------------------

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
---------------------------

[Note that a pre-built shareable image is provided in this kit
 for systems running OpenVMS Alpha V7.0 or later.]

1.  Compile the module using DEC C:

    $ CC/DECC CHARCONV_KANJI.C

2.  Create the shareable image:

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

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


Installing and Using the Callout Module
---------------------------------------

1.  The local character set is assumed to be "EUC-JP" by default.  Users may
    override this setting by creating a file called MX_LOCAL_CHARSET.DAT in
    their login directory:

    $ CREATE SYS$LOGIN:MX_LOCAL_CHARSET.DAT
    ISO-2022-JP
    <ctrl/Z>

    This tells MX not to convert incoming messages that use the ISO-2022-JP
    characters set into the EUC-JP character set.  This is useful when the
    users receive their mail primarily through PC mail clients rather than
    VMS MAIL.

    Note that the VMS MAIL headers will still be converted to EUC-JP, since
    the per-user character set override is used only for conversion of the
    contents of the message.

2.  The network character set for outgoing messages is assumed to be ISO-2022-JP
    by default.  You may change this in the code - look for "ISO-2022-JP" in the
    INIT routine.  If you change this to the form "charsetname=CRTL-charset-name",
    the DEC C run-time library's iconv() routine will be used to perform the
    conversion; the character set name on the left-hand side of the "=" is the
    MIME character set name, while the one on the right-hand side of the "=" is
    the name used by the DEC C RTL.

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_KANJI.EXE

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