Psionmail a suite of programs program to transfer, off-line read and return SMTP email between Psion seies3 and Sun machines Written by Tim Graves (tim.graves@uk.sun.com), This document version is time stamped 11 July 1995 6:59 pm NOTE: This program is provided AS IS, no warrantee of ANY kind is provided either by Tim Graves or Sun Microsystems The mail program was written on a Sun SPARCstation running Solaris2 using the SunPRO SPARCWorks V2. The suncom program was written on a Sun SPARCstation using SPARC- works to manage the code with the Psion C Software developer kit running under the SunPC PC emulation environment. Copying: The same basic rules as the GNU license apply. You can copy this program as many times as you like and modify it in any way you like as long as you acknowledge my original authorship, make it obvious where you have made changes and agree to give anyone who asks for it the original code as you received it (or if you prefer with your modifications) for a rea- sonable copying fee only. If you chose to provide a warrantee that's up to you but I wont pro- vide any warrantee on these programs or ever will! So there! Source code: The source code should be available from the same location as you got this docu- ment. All the code for psion and suncom is held under SCCS but if you have SPARCworks you will probably find it easier to use that to work with the code. A SPARCworks source browser database may also be in the distribution. For the suncom application you will need the Psion Series 3 C software developers kit and some form of PC (yech) or emulation. The sun side source is written in K & R C and compiles cleanly (I haven't dared to run it through lint) the mail program on the psion should also compile correctly and is written in ANSI C. This Document: This document was written using FrameMaker V4 It will probably be reada- ble using subsequent versions of Frame but for use with earlier versions you will need do use the MIF (Maker Interchange Format) file enclosed. Changes from the previous version of this document are marked with change bars thus. Distribution the psionmail programs are distributed in binary (psionmail.tar.Z or psionmail.tar.Z.uu) format compiled for psion 3 and Solaris 2 on SPARC. A small source distribution (pmsmall- source.tar.Z or pmsmallsource.tar.Z.uu) is available containing the full source but NOT the SCCS histories or other SPARCworks files and finally the full source distribution (pmfull- source.tar.Z or fullsource.tar.Z.uu) which contains the entire source tree including SCCS and SPARCworks stuff Psionmail Psionmail is a suite of programs to extract SMTP email, download it to a psion where it can be read and new emails written and to upload the new emails. Email extraction is done using the POP3 mail system (Of which more later). It is designed to work with my psion/suncom pro- grams but by editing the shell scripts other programs could be used to transfer the files to / from the psion. It is assumed that readers are at least in outline familiar with these programs. If you need to get hold of psion/suncom programs they can be retrieved from the SunSite Northern Europe (src.doc.ic.ac.uk) or by contacting me on email. As with the psionmail suite of programs they can be obtained in binary (compiled for Solaris 2 on SPARC) or as a small and full source distribution. Installation To run any of the incoming mail functions you need to be running a POP3 (Post Office Proto- col) server on your mail server see the section on POP for details on where to get this. If you are only going to be composing email and not reading incoming email the POP server is not required. Once the files have been un-tared there will be a psionmail directory. This needs to be installed somewhere in your search path. the psion program should also be in your search path The files gettxt1.pscmd and puttxt1.pscmd should be places somewhere where the pscmd search path in the psion command will find them. You should have a unix2dos and dos2unix program somewhere in your unix search path. The commands convert between the differing file formats on dos and unix machines (They are standard on Solaris systems). If you do not have these programs you will need to find / build something similar and rewrite gettxt1.pscmd and puttxt1.pscmd to use your version From within the psionmail directory you install the applications onto the psion by running the command installapp. This will prompt you to start suncom when required. Once the applica- tions (mail.img and mailrdr.als) have been copied over you will need to install them on the psion system screen using the PSION-I key Once you have installed the applications all other commands can be run from any directory that is suitable. Be warned however that these programs create a large amount of temporary files. The tidying script tries to be selective but you may find some other files also get removed by it. I run these programs from a directory specially created to do these operations in. If you are using my psion / suncom programs please note that you should include the current directory e.g. .) in your pscmd search path You should now edit the setupenv script file and as a minimum change the setenv myaddr lint to include your email address. If you want to store the mail files on a different SSD or directory change the setenv indir and setenv outdir lines as required. NOTE the SSD and any higher directories must exist whenever you transfer files or read / compose email. It is OK to remove an SSD between transfers or when not running the mail application on the psion. DO NOT edit the setenv maildir line as this is hard coded into the mail application. The only time this can be changed is if the mail.img and mailrdr.als files are regenerated accordingly To initialise the mta files (See the section on files for a description of the file formats and names used) and directories the firsttime script should now be run. NOTE if you want to change the contents of setupenv you MUST run the lasttime script before doing so, edit setupenv and then run firsttime If you are going to be downloading incoming email you should now run the talktopopconfig program. This will build the config file for pop communications. With the exception of you password, pop-3 server name and the name of the machine running the pop server the defaults are generally safe to use. These are detailed below talktopopconfig can be rerun whenever you want and will use the last settings as the new defaults. NOTE the config file is stored in the current directory so cd to the directory you will be using to do transfers before running it. (Naff I know but I couldn't be bothered to work out the home directory, this is an RFE) username, the username mail is delivered to on your email server. should be the same as your current username password, your current password. for the username given on your email server The pass- word is not echoed to the screen but be warned. it is saves as clear text in the config file. If you do not enter your password you will be prompted for it when downloading incoming email.(If you enter it and subsequently change your password on your email server it you will need to rerun this talktopopconfig) POP-3 server, this is the name of the machine running the POP-3 server, Inside Sun this is called you mailhost Starting point for retrieved filenames, accept the default. This is so when talktopop retrieves emails it knows the sequence number to start saving them in delete downloaded emails, if set to true the pop server will delete these emails once they are downloaded. Setting to TRUE is more comfortable in that you only have to delete an email once but setting to FALSE is probably safer retrieve from the start or end of your email box, if this is TRUE emails will be retrieved from the first email in your inbox (i.e. the oldest emails) You will probably want to set this to FALSE to retrieve the most recent emails verbose, if you want to know what the pop download is doing set this to TRUE, if you done want this (or get tired of seeing it) set it to FALSE maximum email size, to prevent the psion running out of memory you should set this limit to the max size of email you want to download, Don't forget that email attachments can take up a LOT of space maximum number of emails, again this is to control the amount of memory used on the psion. The number here is the maximum number of emails that will be downloaded. (If you have not deleted previous downloaded emails they also form part of the count) If you are not happy with the default change it but I would use the default initially pop-3 server in the services file, talktopop looks up the name of the POP3 server to deter- mine which port to use. You should be able to get this from a cat of the services file on the server or the NIS/ NIS + master. or take the easy route and ask the system administrator transport mechanism. Unless you have rewritten talktopop you should probably leave this as tcp. Running the uploading / downloading applications on the Sun NOTE most of these scripts are VERY verbose. NOTE if you have not entered a password in talktopopconfig any operation involving down- loading email will require you to enter one (which will not be checked prior to download) NOTE all uploads / downloads will prompt you to start the suncom program on the psion at the relevant time. If you are running the mail reader on the psion you MUST exit it before contin- uing and starting suncom doemail is the command that downloads new email (if there is space), uploads and sends on any emails composed on the psion justincomming downloads any new emails (if there is space) justoutgoing just uploads and sends on any emails composed on the psion. This command does not require the use of pop Removing / suspending the configuration Sometimes you will not be using the psion mail reader for a while or you will want to change the configuration (See below) There are commands provided to do this. lasttime will upload any outgoing email and send it, upload and save any undeleted incoming mail (into files names in???.msg) and delete the configuration on the psion. if you subsequently want to restart the programs you will need to run the firsttime script which will reset the psion configuration. If you want to remove the applications from the psion you should run the removeapp script. This will delete the mail.img and mailrdr.als files on the psion. You will need to use the PSION-/ sequence to remove these apps from the system screen. Changing the configuration you can run the talktopopconfig script at any time to change the pop configurations. Remember to run it from the directory you use for uploading / downloading email If you want to change the settings in setupenv you MUST run the lasttime script. It is then safe to edit the setupenv file and the system can be re-initialised with the firsttime script. NOTE if you do this any undeleted incoming emails will be saves in files named in???.msg and will be removed when you run the firsttime script Running the mail reader on the psion The current implementation of the mail reader is a window based interface using a version of the program editor to read / compose emails (called the viewer) If you are in the reader and press one of the system buttons the reader remains active and the mail app continues waiting for it to exit. If you have installed the mailrdr.als app it will be highlighted in bold on the system screen indicating it is active. Moving the cursor to is and pressing return will move you back to the reader. If you have not installed the mailrdr.als app you should NEVER leave it except by exiting (PSION-X to see changes or on a 3s PSION- SHIFT-X to exit and lose changes). The ONLY way to get back to the reader is mailrdr.als is not installed if via the spy application provided in the C developers kit. I STRONGLY recom- mend installing the mailrdr.als app. Once the viewer has been started the mail program will wait untill it completes. To warn you of this the status line changes to "Running Mailrdr". it will change back when the viewer is exited. NOTE. In the viewer very long lines (approx 500 chars long) seem to cause all sorts of prob- lems resulting in the viewer locking in a save loop and not writting the file. The indication of this is that the viewer will display a flashing "Busy" but will never complete the save. The only remedy for this is to kill the viewer process (SHIFT PSION-K over the mailrdr icon on a 3a of to use the spy app / killproc command in suncom) By doing this you will lose the edits made in the viewer. On starting the mail app it will read in the state of the incoming and outgoing mail queues. All the commands listed below will work on either queue with the exception of the header modify command(Thus you can change your mind and delete an outgoing email) Once the mta files have been read the incoming queue is selected and the headers are displayed in the lower window and status messages displayed in the upper. Header window formats When viewing the incomming list the format used is as follows : When viewing the outgoing list the format is follows> : is the number of the email in the current list, note there are incomming and outgoing lists! is N if the email has not been read since down loading and R if it has been read. Note, if an email has been read but not deleted and further email is subsequently downloaded the undeleted email will be marked as New again Will contasin a D if the email is marked for deletion when the program exits, otherwise nothing The email address of the sender (i.e. the return path) the subject line> the names you have selected to send the email to Upto 5 emails are displayed and the current email will be displayed in bold text. Is the header line is to long it will be truncated to fit into the window. If there are emails above the top if the current list an up arrow is displayed in the top border and if there are emails below the current list a down arrow is displayed in the bottom boarder. Messages, Sometimes the program needs to present a message to you. It does this by display- ing s window containing the message text. Press Return or Esc to remove this popup window Navigating the headers window Navigation of the headers window to select the current email is done using the up and down arrow keys (sometimes with modifiers). It is Impossible to fall of the end of the list Use the Up Arrow to move Up the list one email Use the Down arrow to move Down the List one email Use the Up arrow with the CTRL key to move Up 2 emails Use the Down arro with the CTRL key to move Down 2 emails Use the Page Up (PSION key and Up Arrow) to move up one page Use the Page Down (PSION key and Down arrow) to move down one page Use the CTRL Page Up key (CTRL + PSION + Up Arrow) to move to the first email Use the CTRL Page Down key (CTRL + PSION + Down Arrow) to move to the last email Command keys The commands can either be obtained using the menus (press the menu buttom and navigate the menus as usual) or via the PSION- sequence where is the value listed in the menu lists Current Email Menu View Current (PSION-v), Bring up the viewer on the current email Delete Currend (PSION-d), Mark the current emil for deletion Undelete Current (PSION-u), Remove the delete marking on the current email Modify Header (PSION-m), Modify the to, subjct, cc and bcc lines in the header (Outgoing emails only) Compose Menu New Email (PSION-n), Ask for the header information and bring up the viewer on the new email Reply to sender (PSION-r), Generate a header to reply to the sender of the current email, provide an option to midify the header and then bring up the viewer on the current email Reply to all (PSION-a), Generate a header to reply to all recipients (to and cc lists only not bcc) of the current email provide an option to modify the current header and then bring up a viewer on the new email All of the Compose email functions also ask if the user wished to include the current email indented into the new email Special Menu Exit and Save State (PSION-x), Delete and emails in either list marked for deletion, save the current state and exit Exit and Lose State (PSION-c), Exit, all deletions are ignored, all new emails written are dropped Switch Between Lists (PSION-s), Switch between the incomming and outgoing email lists Files and formats All file formats are native to their current environment and the auto file filtering commands in psion comms program will convert from unix (NL terminated) to dos (CRNL terminated) The main file format is called the mta file. there are two of these, one for the incoming list and one for the outgoing list. The file format contains a header then repeated entries describing an email. The list is terminated with the string END, thus pathname of directory for data files ($indir or $outdir)\ your email address ($myaddr) datafile name 1 to list 1 from list 1 subject 1 cc list 1 bcc list 1 read / new status 1 datafile name 2 to list 2 from list 3 subject 3 cc list 3 bcc list 4 read / new status 2 END for example an inlist could look like a:\mailin\ tim.graves@uk.sun.com in000.msg tom dick harry fred psion to sun communications lindsey READ END and an outlist for a reply to the email including all recipients but adding george to the bcc list b:\mailout\ tim.graves@uk.sun.com out004.msg fred tom disk harry tim.graves@uk.sun.com Re: psion to sun communications lindsey george NEW END Note an empty field must be represented as an empty line. Also that the datafile name does not have to be sequential and can have gaps in the sequence. Datafiles for replies do not have ho have the same sequence number as the original. The incoming and outgoing email text is held in files called in???.msg and out???.msg where ??? is a three digit sequence number allocated by the program. A maximum of 100 outgoing emails can be stores and though there is no limit apart from memory on the number of incoming emails I use an effective maximum os 10. Note each email required approx. 0.5k to hold its data structure All in.???msg files have their lines wrapped to less than 100 characters (a semi intelligent proc- ess is used which tries to avoid splitting words so the include function can work. Obviously this can be overridden whilst viewing an incoming file but it is really not recommended and may cause trouble. There is no line length limit on outgoing email data files The Sun end of things can generate mta files with entries up to 1024 characters. To reduce the per email overhead on the psion any mta file entry longer that 100 bytes will be truncated to 100 bytes and when the user is composing an outgoing email they should keep their header lines to a maximum of 100 characters. (Note this is not enforced and the mail app may crash if long header lines are used) The in.mta, out.mta, in???.msg and out???.msg files are also generated on the Sun along with in???.msg.hdr and out???.msg.mf files as well. Whenever a transfer to / from the psion is done a file called trans.pscmd is generated along with the file /tmp/flist and /tmp/fred (used by the filtering stuff. Except in the case of the lasttime command all these files are deleted from the Sun when the upload / downloads exit POP3 To extract email from the users inbox I use the POP3 protocol and demon. If you do not have a running pop3 demon it can be found in many locations on the internet (I used the WWW archie search engine on Northern Europe SunSite (src.doc.ic.ac.uk) with the keyword pop3d). For users who have the Solarnet package from Sun a pop3 demon is included in it. (named popper). The Berkley ftp server (ftp.CC.Berkley.EDU, 128.32.136.9 or 128.32.206.12 is reputed to have the popper server located there in /pub/popper.tar.Z) You make need to redefine where the pop demon looks for the users inbox. The one I used for testing also required a private temporary directory. You will need root privileges to install the demon once it is compiled (The documentation that comes with it should indicate if it is for BSD or SVR? based systems). This is one area where the documentation seems to be lacking however. The following commands relate to Solaris 2 but should work for any SVR4 system.: First install the executable in a suitable location edit the /etc/services file on the NIS/NIS+ master to include a line of the form pop-3 2048/tcp # Post Office Note pop-3 refers to the service name not the demon executable name, 2048 is the port number. you should ensure you chose an unused port. I think that port number 109/tcp may be a pop-2 standard edit your /etc/inetd.conf file on the mail server to include a line of the form pop-3 stream tcp nowait root /usr/local/pop3d pop3d where pop-3 is the name used in the services file, /usr/local/pop3d is the executable image rebuild the NIS/NIS+ databases to include the new entry do a kill -HUP on the inetd process To test try telnet mailserver 2048 (or the port number) you should get a return something like +OK astir POP3 Server (Version 1.001) ready. NOTES. The POP3 demon I was using (A freebie version) did not seem to robust. it kept on disconnect- ing an leaving me with an empty mail box if anything went wrong with the link. My solution to this was to edit the pop3 demon so it looked for emails in /mymailbox. Before I ran the incoming email programs I then copied my real mail file (/var/mail/tim) to this holding point. The disadvantage of this is that it made deleting downloaded emails pointless as they were not deleted from the real inbox and also if I had a mail reader running on my workstation with emails deleted since I last saved changes I got the deleted emails included in the down- load. There was another advantage in that by copying my real inbox I did not have to work about any running mail readers getting confused as to the state of the real inbox. Of course I could have saved changes to my real inbox and copied the pop munged inbox back to the real inbox if it was not zero length but that was to complicated for the testing. One irritating (but not fatal) problem is that the pop demon I used did not seem to be able to handle included messages as it looks for lines like From fred as mail separators. With the sunmail tool that was a problem because many included emails include the full header so I received an email in two parts, the header of the email and then the included email. This causes some problems. It should however be possible to write a pop3 demon that understands the Content-Length: xxx header structure. The popper demon in Suns Solarnet product DOES operate using the Content-Length: xxx mechanism though it still suffers from the problem of two programs updating the mailbox at the same time To do The user interface on the psion needs a lot of work. It should rally be re-written in the style of other psion programs with menus etc. This will probably happen in the next release