' PINE AND IMAP FOR VMS		--- Version 3.91  ---------------------   L Yehavi Bourvine ported version 3.91 of the PINE code and the IMAPD server toF VMS. His last release was known as 3.91 Beta 5. However, this port wasN incomplete (Mainly the IMAPD daemon). I have progressed the port to a workableL state and upgraded the code since then; This note summarizes the changes. My version starts at 3.91 Beta 6.  O Note - the changes here have been tested ONLY with NETLIB and MULTINET. Support J is only partial for direct UCX support although NETLIB support provides anN alternative for UCX users. If anyone wishes to contribute the relevant mods toF make direct UCX support work properly, please let me know. I'll try toM integrate them as and when I can. I only update this in my limited spare time ! or as needed for our local users.   K The code will compile with VAX C 3.2 and DECC 5.3 and works on both VAX and  ALPHA with Multinet 3.5B.   O Note: for those who used a previous port (3.89 beta 10 or 3.89 beta 11) which I K released, all the facilities of those versions have been included into this  release.    M -----------------------------------------------------------------------------   * SETTING UP PINE AND THE IMAP DAEMON ON VMS* ==========================================   Applies to Version 3.91 Beta 7     INTRODUCTION ============  M This kit contains all you need to build a working PINE mailer and IMAP server O for VMS (except for a C compiler). The code has been tested with the following: K     VAX C 3.2 on VAX and OpenVMS 5.5-2, using Netlib 2.0J and Multinet 3.5B I     DEC C 5.3 on VAX and OpenVMS 6.2, using Netlib 2.0J and Multinet 3.5B K     DEC C 5.2 on Alpha and OpenVMS 6.1, using NETLIB 2.0J and Multinet 3.5B   N Other combinations are LIKELY to work. It's just that they've not been tested.  / See below for details of bug fixes and history.   L See the file README.VMS for other information, mainly about how to configure PINE.     	 BUILDING: 	 ========= K    1.	Create a directory for the code and unpack to create a directory tree - 	into it, preserving the directory structure.   K    2.   From the top level of this tree, execute the VMSBUILD.COM procedure C 	with a single parameter of either NETLIB (recommended) or MULTINET ;         to build the code for your preferred network stack.   B 	NETLIB allows the code to execute on any of the supported VMS TCPD 	stacks, such as UCX, MULTINET, CMU, Pathway etc. It is available asK         freeware from ftp://madgoat.com/madgoat/netlib020.zip and should be  	installed first.   E 	MULTINET support restricts the image to MULTINET stacks only but may 3 	execute slightly faster as there is less overhead.   F 	NOTE: makefiles are included but are untested. They will likely fail.* 	Please use the procedure described above.  F 	NOTE: The PICO and IMAPD parts of the package can be built separatelyE 	if required. SImply make sure that the VMSBUILD.COM procedure exists 3 	in the appropriate subdirectory and execute it as:  	  @VMSBUILD stacknameD         where stackname is either NETLIB or MULTINET as appropriate.  N         NOTE:  If building each item separately, PINE must be built last as it: 	requires the object libraries created for PICO and IMAPD.     INSTALLING:  ===========   D    1.	Create a directory for the production system. You can have oneG 	directory for the PINE stuff and another for the IMAP server stuff, or H 	you can combine them into the same directory. In either case, reference; 	to the various places should be through logical names (see 3 	PINE_SETUP.COM and IMAPD_SETUP.COM for more info).   5    2.	The directory structure that is recommended is:  	 1 	  PINE_ROOT:[000000]	-- Top level for pine stuff . 		[.BIN_VAX]		For VAX architecture executables2 		[.BIN_ALPHA]		For Alpha architecture executables$ 		[.CONFIG]		For configuration files 		[.LOGS]			For log files   <           IMAPD_ROOT:[000000]   -- Top level for IMAPD stuff. 		[.BIN_VAX]		For VAX architecture executables2 		[.BIN_ALPHA]		For Alpha architecture executables$ 		[.CONFIG]		For configuration files 		[.LOGS]			For log files   E 	Note -- IMAPD_ROOT and PINE_ROOT can be defined to the same thing if  	preferred.   B    3.   Define some system level logical names to the directories:  7 		$ define/system/exec pine_dir  pine_root:[bin_'arch'] 8 		$ define/system/exec imapd_dir imapd_root:[bin_'arch']  * 	And some logical names for various files:  1 		$ define/system/exec pine_exe	pine_dir:pine.exe 7 		$ define/system/exec pine_conf_dir	pine_root:[config] 5 		$ define/system/exec imapd_exe	imapd_root:imapd.exe   6 	And various (mainly optional) configuration logicals:  > 		$ define/system/exec pine_mail_protocol mx  [see note below]  3 		$ define/system/exec imapd_log		imapd_root:[logs] 8 		$ define/system/exec imapd_logfile	imapd_dir:imapd.log' 		$ define/system/exec imapd_loglevel	2 % 		$ define/system/exec imapd_logtry	3 D 		$ define/system/exec imapd_alertfile	imapd_root:[config]alerts.txt) 		$ define/system/exec imapd_node_xxx	yyy   E 	See the files PINE_SETUP.COM and IMAPD_SETUP.COM for further details ( 	of the logical names and their function    D   4.	Set up suitable values in the configuration files to suit local 	requirements.
 	  For IMAPD: 5 		IMAPD_CONF_DIR:IMAPD.CONF	is the configuration file - 			[ Currently, nothing is required in this ]    	  For PINE:< 		PINE_CONF_DIR:PINE.CONF		is the general configuration fileF 		PINE_CONF_DIR:PINE.CONF-FIXED	is the fixed system configuration file. 			[ See elsewhere for the contents of these ]  < 		The fixed system config file should define system specific< 		things which the user MUST not and CANNOT alter (eg system 		name, smtp server).   9 		The general system config file defines things which are < 		standard defaults but which the user can override in their% 		personal .PINERC configuration file    	 B   5.	Finally, arrange for the users to be given access to the PINE= 	executable by some means, perhaps by defining a symbol thus:    		$ PINE == "$PINE_EXE"      ACTIVATING THE IMAPD SERVER  ===========================   K The IMAPD server provides the user with the ability to access their mailbox F over the network. PINE uses IMAP protocols to access remote mailboxes.  O The IMAPD server is an implementation of IMAP2bis for VMS and will run directly M over MULTINET, or less directly over NETLIB which gives it the ability to run O over any VMS TCP/IP stack. Any mail client (not just PINE) that conforms to the K same standard (see RFC 1176 for the IMAP2 standard and ??? for the IMAP2bis M extended standard) may use the IMAPD server to access a mailbox from a remote  client.   L The IMAPD server is designed to be started by a master server process ratherK than as a permanently running process that 'listens' for connections. Thus, O although it is directly supported to run over any stack, the stack must have an M ability to act as a master server, accept connections, start the IMAP process 4 and then pass the connection on to the IMAP process.  K All master servers should be configured to listen on port 143 (The official < IMAP port) and run the IMAPD_EXE image when a call comes in.  
 Special Note: M   * If using UCX (via the NETLIB support), then UCX mail should be configured K     to insert the RFC822 mail headers at the top of the message, using this      command:  2 	$ UCX SET CONFIGURATION SMTP /OPTIONS=TOP_HEADERS  !     Then restart the SMTP server.   N     The IMAPD server will only recognize headers at the top of the message and     not at the bottom.    M -----------------------------------------------------------------------------    Configuration Notes  -------------------   < There may be a few warnings during the link - ignore them...O On VAX we have to link the objects themselves and can't use libraries since the > linker/librarian lose the global variables; on AXP it is ok...  N Due to a readonly definition of _ctype_ in the source files we use an externalM #define to redefine it to something else. Because of this,  CTYPE.H fails, so J we use a private copy of it. This is relevant only to VAX C; DEC C handles things better.     Using  -----   L   The user needs access only to the PINE.EXE image. This reads mail directly7   from the user's mailbox using callable MAIL routines.   -   Mail can be sent out by one of two methods:   M     * If any of the pine configuration files (see below) contain a definition        of the form:         smtp-server=hostname  K       Then all outgoing mail is sent to the named host for onwards routing. K       Note that the named host is contacted directly. No attempt is made to        use MX records.   J     * If no such definition appears, then you MUST define the logical nameI       PINE_MAIL_PROTOCOL to specify which shareable mail foreign protocol J       module is to be used. For example, if you normally send network mailI       within VMS MAIL using addresses of the form SMTP%"....", you should J       define the logical name to the string "SMTP". PINE will then use the       callable image.   G       With this method, the message that PINE sends out has TWO sets of M       RFC822 mail headers separated by a blank line. One is generated by PINE K       itself; the other by the foreign mail protocol. Currently there is no O       way around this. The only practical effect is to mess up any MIME encoded        attachments.  @     * It is an error if neither of the above methods are set up.     Pine.Conf Restrictions ----------------------  N PINE was originally written for a non-VMS environment and some of its conceptsF are alien to the way in which VMS MAIL works. As such, there are a few? restrictions on what can be done/configured. Principally these:   J 1. In order not to modify the source too much, the handling of the specialL    INBOX folder was not modified. Hence, it always tries to open the (empty)#    INBOX folder instead of NEWMAIL.   B    It is possible to define in the system-wide PINE.CONF file that      inbox-path=NEWMAIL.  N    In this case NEWMAIL will be opened when PINE is started. However, the userG    must not then switch to another folder as long as NEWMAIL has items.   & 2. The WASTEBASKET folder is not used.  O 3. ..PINE-DEBUGx, .PINERC and .ADDRBOOK are fixed to the user's login directory E    and cannot be defined to be elsewhere (the definition is ignored).     4. Messages cannot be postponed.   5. FCC cannot be used.     Example PINE.CONF file.  ----------------------  ? Here is an example PINE.CONF file used at HUJI. Default-FCC and K Folder-collections MUST be defined as is here; if not (or if missing), Pine  won't work correctly.   & # PINE.CONF for the Hebrew University.   user-domain=vms.huji.ac.il   smtp-server=vms.huji.ac.il   image-viewer=xv    inbox-path=NEWMAIL   default-fcc=""   folder-collections=SYS/[]     M -----------------------------------------------------------------------------   ' 3.91 Beta 7 - Changes since 3.91 Beta 6 ' ---------------------------------------    1.	PINE  	====     N   *  Fixed a bug in the use of a foreign protocol mail interface (used only ifL      the smtp-server is not defined in the pine configuration interface, andL      selected with the logical name PINE_MAIL_PROTOCOL).  There were several;      problems found and fixed in the vms_mail_send routine:   O        - No distinction was made between addresses in the TO: field and the CC:           field.   P        - Each line of pine's mail file was copied separately to the message bodyL          (This seemed to have a bug causing an access violation) rather than<          using the special filename option in callable mail.  J        - The calls to the callable mail interface specified that a routineK          should be called for each successful delivery but this routine was L          define with the wrong number of parameters (zero instead of three). 								12-SEP-1996     J   *  Fixed a very strange timing bug in the purge_status_message() routineM      which supplied sleep with a zero value and somehow locked up when trying J      to send a message.  I've inserted a check to always supply a positive      value to sleep. 								11-SEP-1996   G   *  With debugging (-d switch) active, the .PINE-DEBUGx file was being I      created correctly but the code to rename the highest version did not O      delete any previous version. Of course, it was originally written for unix O      where renaming into an existing file destroys the existing copy. On VMS it F      doesn't, but preserves the older version. As this is not requiredK      behaviour, the code has been modified to explicitly delete the highest       version if it exists. 								11-SEP-1996     F   *  Merged changes and installation/configuration files into a single      aaareadme.txt file. 								11-SEP-1996     K   *  Added some info to the aaareadme.txt file about the configuration file       usage and contents. 								11-SEP-1996     J   *  The version ID was still at 3.91-vms-b4; changed it to 3.91-vms-beta74      to properly reflect the current version number. 								11-SEP-1996     L   *  The DEBUG code is now compiled in to the PINE utility by default. It is<      controlled by the '-d' switch on the PINE command line. 								11-SEP-1996     J   *  PINE was attempting to read the default system configuration from theH      SYS$MANAGER directory rather than from the directory defined by the       logical name PINE_CONF_DIR.      This has now been fixed.  								11-SEP-1996   H   *  PINE was attempting to read the fixed system configuration from theK      directory defined by the logical name UTIL$ rather than PINE_CONF_DIR.       This has now been fixed.  								11-SEP-1996     N   *  The wrong build procedure for PINE was inadvertently supplied. It did notK      have appropriate changes added to properly distinguish VAX C and DEC C L      and could confuse compilations under both compilers.  This has now beenJ      corrected and the right build procedure is now supplied. This did not6      prevent the building of PICO or the IMAPD daemon. 								11-SEP-1996           ' 3.91 Beta 6 - Changes since 3.91 Beta 5 ' ---------------------------------------      1.	IMAPD
         =====   K   *  In the VMS header parsing, also treat "Via:" as a valid rfc822 header.  								Sept 4, 1996  L   *  Bug fixes to the code which parses the messages to sort out the headersO      from the text and return the length of each. This was not being done under K      all circumstances and resulted in some short string counts which could       confuse the clients.  								Sept 3, 1996      I   *  Added fuller checks on I/O status checks to/from the network. Should H      prevent the code hanging or looping if the network connection dies. 								Sept 3, 1996    O   *  Fixed the NETLIB support code. This let me find some interesting DEC C and H      VAX C header conflict bugs. If compiling with DEC C, it is probablyL      inadvisable to point logicals like SYS, ARPA etc. to the SYS$LIBRARY IfO      you also have, or previously had, VAXC installed. The logicals cause DEC C N      to pick up certain header files from there, rather than from the standardL      DEC C library. Unfortunately, they conflict in their contents and causeN      various facilities to become unavailable (Someone really should shoot theM      inventor of C header files - they are a facility that is grossly misused O      and abused even by professional programmers! DEC C writers have not helped I      matters with their proliferation of ifdefs and modes of compilation)   G      Also had to slightly edit the code to call the right TCP interface #      routine to get the local name.  								Sept 2, 1996    K   *  Found a more effective/efficient way of dealing with VMS/RFC822 header I      selection in VMS_MAIL.C. Basically, start by extracting the VMS MAIL M      headers into a buffer. If the first line after this set of headers looks N      like it's an RFC822 style header, copy those over the top of the VMS MAILN      headers rather than reading them into a separate buffer. It's cleaner and      uses less memory. 								Sept 2, 1996    J *   Added logging to the IMAPD code.  Each activation of IMAPD will createL     a logfile if the logical name IMAPD_LOGFILE is defined with a valid fileM     name. The logical is checked each time the IMAPD program starts so it canAN     be dynamically assigned/deassigned for selective logging only when there'sM     a problem to solve.  The level of logging sent to this file is controlledkO     by the logical name IMAPD_LOGLEVEL. If defined with a numeric value greateryF     than zero, then logging messages are written to the IMAPD_LOGFILE.  2     The level of logging currently recognized are:$       0 or non-numeric: (No logging)  	0 - nothing written to log file  8       1-10: progressively higher levels of IMAP tracing 6         1 - Basic trace of IMAP commands and responses  O       11-20: internal trace of I/O routines and other technical debugging stuffs8 	10: Trace of each read/write of an I/O buffer to stdout- 	11: Trace of every character read from stdind  O     IMAPD Logging consists (currently) of all commands read by the IMAPD daemon N     and their parameters. NOTE that this includes login passwords at present!!J     Command responses are logged too, though not the data generated by the     command.  H   *  The alert facility has been implemented. A logical name of the formN      IMAPD_ALERTFILE can be defined to point to a text file. If this text fileK      can be opened, it is copied to the IMAP user at the start of each IMAPt2      session. Each line in the file is printed as:         * OK [ALERT]  text  L      Whether or not the IMAP client can detect and print them is, of course,      client dependent. 								August 30, 19960    H *   The idle timeout code was originally written using the ANSI functionF     setitimer. As this is not available with VAX C or with DEC C untilL     VMS 7, the code was originally commented out for VMS. It's been put back     and uses alarm() now..  J     Previously the idle timeout was fixed via a define in the source. I'veM     changed this so that the value can be specified via a system wide logical      name IMAPD_TIMEOUT.a       For example:0        $ define /system /exec imapd_timeout 1800  I     Sets an idle timeout of 1800 seconds (30 minutes).  A value of 0 (thes"     default) sets no idle timeout. 								August 30, 1996r    H *   Added the ability to remap DECNET node names via logicals. With this"     facility,  a name of the form:  @ 	node::username		(or Namespace:.node::username under DECnet/OSI)  +     attempts to translate the logical name:e           IMAPD_NODE_node   2     And the translation is used to replace 'node'.       For example:  K       Suppose the logical name  IMAPD_NODE_BLACK is defined to "campus.edu"o       then the address:i           BLACK::JOHNs         is mapped into::         JOHN@campus.eduu  4       With no logical name, the translation will be:         JOHN@BLACK 								August 30, 1996     K *   The program was originally written for unix, where INETD can fork off a G     process with stdin and stdout automatically connected to the clientcK     channels. This has the advantage of allowing things like printf to workeH     directly to the sockets. With VMS, we can't do this (easily) so I'veN     resorted to a rather nasty trick of redefining the standard i/o calls withN     macros to our own special routines which attempt to detect how to properlyH     handle the I/O. Not a pretty sight but it seems to work! Handling ofK     network read/write error returns is still a bit flaky though. More worknE     needed. It does now work with MULTINET and (shortly) with NETLIB.s  N     I can't claim credit for the idea of intercepting the I/O code - that goesO     to Yehavi Bourvine who added something similar to the 3.89 port. I've taken_N     the idea and refined it to make it cleaner and QIO free. The original codeH     had no concept of restrictions on I/O buffer length so would merrilyL     overwrite code and data structures. My rewrite is careful not to do this,     and splits reads/writes where necessary. 								August 30, 1996c    L   *  When a local or DECnet message is found (IE one sent through normal VMSL      mechanisms rather than via SMTP software), the IMAPD daemon returns theL      usual VMS mail header lines. These are, of course, not in rfc822 formatI      and confuse various mail header parsers. The code now modifies these/H      headers (the FROM:, TO: and CC: fields) into an RFC822-like syntax.  (      The following forms are recognized:2          username		   maps to	username	(No DECnet)=          node::username		   maps to	username@node	(DECnet IV)rC          namespace:.node::username maps to	username@node	(DECnet V)p  K      Additionally, a comma separated list of names in each field is allowedsK      and each is converted as above. I don't support space separated names!i 								August 15, 1996s    N   *  I've further tidied up all the memory allocation bugs I can find in IMAPDN      and it appears to be fairly stable now. Big messages may still confuse it      though. 								August 14, 1996l    G   *  The IMAP daemon reads each message into memory. It allocates spaceEM      for the message using a primitive and inefficient technique and does notiI      check whether the allocation succeeded. This leads to random crashesuN      later when the invalid pointers are used (well, it was written originally>      for unix where error checking is not necessary ..   :-) )  N      The algorithm has been modified to greatly reduce the memory requirementsN      for each message. This won't stop the crashes but should make them happenG      less often. I could not find a way to die gracefully if the memoryoO      allocation failed. At the moment, the check simply prints an error message J      and dies rather than crashing; whether the mail client can print this!      message is client dependent.t  K      One way to circumvent the problem is to increase the amount of virtuallI      memory allocated to the imapd process. If run under MULTINET via theE9      superserver, you can use the MU CONF/SERVER command:h         SET PQL-PGFLQUOTA xxxxx   K      To a suitably large value. Really though, the code needs to be heavilyv9      modified to not read each message into memory first.o 								August 12 1996    
 2.	GENERAL         =======r  & *   I've added two startup procedures:L       IMAPD_STARTUP.COM can  be called from system startup to initialize theK       logical names IMAPD uses. Note that this should be tailored for localP       use first!  J       PINE_STARTUP.COM can be called from system startup to initialize theJ       logical names PINE uses. Note that this should be tailored for local       use first!  N       Both files contain examples of the optional logicals. Tailor and comment       to personal taste. 								August 16, 1996      Andy Harpern+ Kings College London,					September 12 1996s