PDA Software Library/pdasoftwarelib.iso/PSION/COMMS/PSIONMAI/PSIONMAI.TXT

Text File | 1995-07-13 | 23.7 KB | 561 lines

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 ([e-mail]), 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

<mail number> <read status> <deleted status> <Sender> : <Subject>

When viewing the outgoing list the format is follows>

<mail number> <deleted status> <To list> : <Subject>

<mail number> is the number of the email in the current list, note there are incomming and
outgoing lists!

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

<deleted status> Will contasin a D if the email is marked for deletion when the program exits,
otherwise nothing

<sender> The email address of the sender (i.e. the return path)

<Subject> the subject line>

<to list> 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-<key> sequence where <key> 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\

[e-mail]

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\

[e-mail]

out004.msg

fred tom disk harry

[e-mail]

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