OS/2 Shareware BBS: 35 Internet/35-Internet.zip/popit01e.zip/POPit.INF

OS/2 Help File | 1995-03-28 | 26KB | 571 lines

ΓòÉΓòÉΓòÉ 1. POPit 3.0 Beta ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 2. POP3 Client For OS/2 ΓòÉΓòÉΓòÉ

POPit is a POP client for OS/2.  I wrote it to solve some mail handling
problems I was experiencing.  There were a number of postings on USENET that
lead me to believe that I was not alone in these problems.  This prompted me to
make POPit available in two previous public Beta releases.  This is the Third
public Beta.

The main purpose of POPit is to manipulate your remote message queue, and to
that end LaMail and Elm are fully supported.  However, to make use of all of
POPit's features the Elm mail reader must be used (possibly in conjunction with
Elm's filter program).

POPit is a little different from most in that it has a graphical user
interface, this should give you a hint as to the kind of control POPit attempts
to provide.  Before you are too disappointed, I must hasten to add that the GUI
is not the primary purpose of POPit, and though it is functional some of you
will find that it is a bit 'raw'.


ΓòÉΓòÉΓòÉ 2.1. Requirements ΓòÉΓòÉΓòÉ

POPit's user interface is written using Watcom's VX-REXX, and so VROBJ.DLL 2.1b
is required.  Since it is very large and is readily available on Internet and
CompuServe, you will not find it included in the POPit package.  If you do not
have this DLL it is available in the CIS POWERSOF forum in the Watcom VX-REXX
library (This forum is being 'renovated', you should be able to get there using
the 'GO WATCOM' command).  It is also available via FTP at most of the OS/2
archive sites on the internet but certainly at
rexx.uwaterloo.ca:/pub/os2/vxrexx or alternatively
http://www.watcom.on.ca/vxrexx/vxrexx.html

RXSOCK.DLL is no longer required.  It has been replaced by POPitX.DLL which is
included in this package.

You may also need IBM's TCP/IP 2.0, it is not clear at this time if POPit will
work with the IAK on WARP.  From what information I can gather it should work
with the IAK.  It is also unlikely that Ultimail will work with POPit.

As for IBM's TCP/IP, I suggest you obtain the most recent CSDs and apply them.
Some unpredictable behaviour of POPit and IBM's WebExplorer seems to have
disappeared with the August 1994 CSDs.


ΓòÉΓòÉΓòÉ 2.2. Features ΓòÉΓòÉΓòÉ

I've tried to keep the functionality to a minimum yet provide enough to be
useful.  At least that was the idea.  As soon as I made POPit available a
number of requests started to roll in.

o   will deposit mail into the LaMail inbox

o   will deposit mail into Elm's inbox

o   will pass mail through Elm's mail filter

o   handles message body lines beginning with a '.' (all POP handlers are
    supposed to but, for what ever reason, some don't)

o   provides information about the messages waiting (number, total size, size
    of each message and, where supported, from header lines)

o   allows for an undelete of messages read in the current session

o   optionally saves the last configuration used

o   it can handle a lot of mail, and long mail messages

o   online 'hints' are provided

o   polling is implemented (undelete is not available when polling)

o   checks for valid elm environment before allowing either of the elm handlers
    to be selected

o   it keeps a time stamped transaction log which can be cleared using a
    context menu

o   tries to be a bit more forgiving of POP errors though is still probably
    overly conservative/paranoid

The following are new features for this release (this is not an exhaustive list).

o   use the environment variable UUPCSYSRC for elm

o   display elm environment in Config menu

o   reduced the timeout from 1sec intervals to .1 second intervals

o   use the XLST protocol to get From header line (manual connections only)

o   significant speed up in transfer times

o   start minimised and polling (until first successful connect the polling
    interval is 1 minute).

o   max download size when polling (manual ignores this limit)

o   changed font size to something small in the listbox

o   added a way to skip the first N messages waiting in the inbox

o   added an explicit 'delete' in manual mode (this helps in the case of
    skipping and big messages)

o   get messages one at a time (manual connections only)

o   optional interleaved fetch/delete (as opposed to fetch all mail then delete
    all messages from the server, this helps when there are messages in your
    queue that are causing you grief)

o   non-fatal errors and warnings are displayed in the transaction log not a
    warning dialog.

o   if you are using Elm you can use POPit to send mail for you, eliminating
    the use of TCP/IP's sendmail entirely.

The following are fixes included in this release (this is not an exhaustive list).

o   fixed the minutes and seconds of the next poll time estimate when m < 10 or
    s < 10

o   more thorough testing of POP errors and some socket errors

o   not fooled by 'mailbox' in MailDir

o   not case sensitive for MailBox and MailDir

o   handle '/' in UUPCSYSRC and UUPCUSRRC

o   locks the elm mailbox when writing to it

o   better handling multi-line To, From, Subject and References header lines

o   got rid of the highlighting in the listbox


ΓòÉΓòÉΓòÉ 2.3. Deficiencies ΓòÉΓòÉΓòÉ

I am not aware at this moment of any bugs (with the possible exception of one
that I'll describe below, and I'm sure this bug-free condition won't last much
past the release of this beta).  However, POPit is not without its deficiencies.

o   it is on the large side (it requires VROBJ.DLL >800k)

o   there is no online help

o   it is a bit harsh when a socket error is encountered while connected (no
    message is deleted until after it is retrieved, so hopefully this
    conservative approach will help ensure that no mail will be lost through
    dropped connections)

o   I've tried to ensure that the POP server is always closed, even after an
    error.  This is not always possible.  Some of the older POP servers do not
    detect a dropped connection and so you have to do something unpleasant,
    like use telnet to login and kill the server process, or phone for help.

o   it is interruptable only through the OS/2 window list or one of the kill
    utilities available.

o   it is single threaded so POPit's UI is locked up while transfers are in
    progress.  The log should be scrollable but this is of limited use.  In
    normal use I don't think this poses any difficulties, handling a mail queue
    isn't exactly an interactive task in usual circumstances.

There is a problem that was very intermittent until my Internet connection
provider 'upgraded' their system (it now happens once a day or so).  There is
an occasional error in the TCPIP DLL.  Both POPit and WebExplorer demonstrate
this problem.  I do not have any idea what is causing this it except that it
seems to be worse when the server is busy.  If anyone else experiences this
problem please let me know.


ΓòÉΓòÉΓòÉ 2.4. Unknowns ΓòÉΓòÉΓòÉ

The biggest single unknown is if POPit will work with the IAK.  As far as I can
tell, with the help of several current users, this should not present a
problem.  We will see.


ΓòÉΓòÉΓòÉ 3. Installation ΓòÉΓòÉΓòÉ

There are four files included in this distribution, this POPit.INF file, the
POPit.EXE executable, the POPitX.DLL communications DLL, and sndmail.EXE.

VROBJ.DLL 2.1b is required, and since it is very large and is readily available
on Internet and CompuServe, it will not be included in the POPit package.  If
you do not have this DLL it is available in the CIS POWERSOF forum in the
Watcom VX-REXX library.  It is also available via FTP at most of the archive
sites on the internet but certainly at rexx.uwaterloo.ca:/pub/os2/vxrexx or
alternatively http://www.watcom.on.ca/vxrexx/vxrexx.html

POPitX.DLL and VROBJ.DLL must be in some directory in your LIBPATH.

Put the POPit.exe file somewhere on your PATH.  Note that a POPit.INI file will
be created in the directory where you put POPit.EXE.  You will probably NOT
want to delete this file once you have POPit working.

If you are going to use sndmail.EXE put it in the same directory as POPit.EXE
and rename the sndmail.EXE that comes with Elm to something else (don't delete
it).  Elm comes with a sndmail.exe program that is its interface to the
sendmail.exe program.  POPit includes its own Sndmail.EXE, replacing elm's, and
is used to allow POPit to send mail for you.  This will work only if you are
using the ELM mail reader.

There is no icon for POPit.  You can put it on your desktop using the program
template if you wish.  I usually invoke it with a line like '@start POPit.exe'
just before SLIPUP.CMD returns.  POPit no longer has a problem if SLIP is not
already running, so in theory at least, you could put POPit into your startup folder.


ΓòÉΓòÉΓòÉ 4. Configuration ΓòÉΓòÉΓòÉ

You must configure POPit with connection information and tell it what mail
handler you want to use.

You must provide a host name, a port number, a user name, and a password.  This
information may be saved in a .INI file and so is available in your next POPit
session.  Some of you may be concerned about leaving passwords unencrypted in
.INI files, so the password may be excluded from being saved in the .INI (see
the section below that discusses the .INI file).

It is possible to disable POP timeouts.  These are the timeouts that occur
during POPit's conversation with your POP server.  The default is to timeout
after 60 seconds.  However, in some situations this is too short a time.  To
disable the POP timeouts, there is a menu item in the Config pulldown menu
called "POP timeout" which if checked indicates that timesouts will occur,
unchecked means they will not.

You must also indicate what your mail handler will be.  The default is filtered
elm.  However, if you do not have an elm environment set up POPit will disable
both the elm handler options.  If there is a suitable elm environment, but no
filter command on your path, then only filtered elm will be disabled.  If
filtered elm, the default, is disabled, then LaMail will be the default.

If you use LaMail or some other mailer that is expecting OS/2 sendmail to be
retrieving mail, select the LaMail option.

If you want to use elm, but are not using the filter program, select the Elm option.

If you are using elm and want to use the filter program, that's right you
guessed it, select the filtered elm option.

For those who are not familiar with elm's filter program...  It is a program
that is run on incoming messages.  Normally all mail is deposited into the elm
incoming mail box.  With the filter program you can do a pattern match on the
basic header lines and cause mail to be redirected to various elm folders,
deleted, or even execute some program.  If you get a lot of mail this can be
rather useful.  It handles mailing lists well.  Elm is free and available on
the Hobbes ftp site -- check it out.


ΓòÉΓòÉΓòÉ 4.1. LaMail ΓòÉΓòÉΓòÉ

When configured to use LaMail as your mail handler, POPit will deposit your
mail in the LaMail inbox directory.  POPit cannot tell exactly where that is,
so it guesses, and you may have to correct that guess.  The guess depends on
the ETC environment variable that normally points to the ?:\TCPIP\ETC
directory.  It assumes that the inbox directory will be in the MAIL
subdirectory.  If it isn't change the location in the text edit field.  Save
your change.

If you select this handler then the full address of the message's originator
along with the message's size will be put into the informational list box as
you retrieve mail.


ΓòÉΓòÉΓòÉ 4.2. Elm ΓòÉΓòÉΓòÉ

When configured to use Elm as your mail handler, POPit will attempt to locate
your .rc file by looking up the UUPCUSRRC environment variable (these are
defined in your config.sys file).  POPit will find the elm inbox by looking in
the rc file.  You may change by editing the text edit field.  Save your change.
Please note, that it is a .rc that is specified not the inbox itself.

If you select this handler then only the message number and size is put into
the transaction log as you retrieve mail unless your POP server supports
certain extensions.  If it does then the from address is displayed as well.

This option will be disabled if you do not have a properly set-up elm
environment.  The %UUPCUSRRC% environment variable must be defined and point at
a valid elm .rc file.  In addition the MailDir specified in the .rc must exist.

If you want to send mail they you must also define the POPIT_OUTBOX environment
variable.  This must point to an existing directory.  You must also install the
sndmail.exe program as described in the Installation section.  Any file found
in that directory with the .out file extension is considered to be mail and
will be sent to your POP server for mailing.  Note that some automated systems,
like mail list servers, will notice that this was done and may reject your
submissions unless you subscribed to the mail list using a message sent by your
POP server.


ΓòÉΓòÉΓòÉ 4.3. Elm Filtered ΓòÉΓòÉΓòÉ

When configured to use Filtered Elm, all messages are writen to a temporary
file.  POPit looks in the environment for the TMP or TEMP variable and uses
that directory for the temporary files.  If you do not want that directory used
change by editing the text edit field.  Save your change.  The elm filter
command is run with the temporary file as input, the temporary is then deleted.

In this configuration, POPit uses the UUPCUSRRC environment variable if
necessary.  This should be 'OK' since filter uses the same variable to
determine where to put things.  If you are having difficulties with this see
the discussion on configuring elm.

In this configuration part of the output of the filter command is captured and
an edited version is put in the list box.  The output line can be quite long so
only the 'interesting' part is put in the list box.

This option will be disabled if the regular elm environment is disabled, or if
filter.exe cannot be found in your PATH.

If you want to send mail using POPit see the section on configuring Elm.

Note well:  There are bugs in Elm's filter program.  Make sure that you can run
the command 'filter -r' from a command line before you let POPit use filter.exe
to filter mail.  'filter -r' lists the rules being used, filter can crash when
you have too many rules (and for other reasons).  If filter crashes when POPit
runs it you loose your mail.  I'm looking into ways to solve this, but it
really isn't a problem if 'filter -r' works.


ΓòÉΓòÉΓòÉ 5. Operation ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 5.1. Manual ΓòÉΓòÉΓòÉ

There are six Buttons in the Manual cluster.

When POPit first begins only the Connect button is enabled, the other four are
greyed out.

Until there is a connection established there isn't much you can do, so the
first thing to do is open the connection.  This is done by pressing the
'Connect' button.  A connection is attempted and if successful will display the
response from your server.  Then the number of messages and total bytes/octets
they represent are then obtained and displayed, then the number of bytes/octets
for each message is obtained and displayed in the transaction log.  If your POP
server supports the extension, POPit will also include the address of who sent
the mail to you in the log window.  Once connected, the 'Connect' button will
become a 'Disconnect' button, and the other buttons will be enabled.

Before we go any further you should take note of a spin button way over on the
other side of the transaction log called 'Skip'.  This tells POPit that it
should ignore, or skip, the first few messages.  This affects the remainder of
the functionality with the exception of 'Keep'.

The next step is to exchange messages.  First the messages  in the server's
message queue are retrieved, skipping the first few according to the 'Skip'
field, then any retrieved messages are deleted from the server, then any
messages that you are sending are sent.  Your messages are deleted from the
server either when all messages have been read or after each individual message
is read.  This is controlled by the Config/Delete as read menu item.  There is
currently no way to be selective about which messages are retrieved, aside from
skipping the first few.  As messages are retrieved some information about them
is displayed in the listbox, replacing what was put there by the connection
operation.  What information is displayed depends on what you have selected as
your mail handler.

There is a third button, called 'Keep' that performs an undelete of all the
messages, without regard for any messages that are to be skipped.  This only
works for the current session.  If you exchange then disconnect, you cannot
undelete those messages -- the server removes them from the queue when you disconnect.

There is a fourth button 'Delete' that will Delete all messages in the queue,
skipping the first few, even if they have not been read.

The fifth button, called '1' retrieves the next message in the queue.  What is
the next message?  It is the first message not to be skipped.  Once the message
is retrieved, and deleted, the skip value is incremented.

The sixth button, called 'S' just increments the skip field (so you don't have
to move the mouse too far).


ΓòÉΓòÉΓòÉ 5.2. Automatic ΓòÉΓòÉΓòÉ

Polling will allow you to leave POPit running and have it fetch any messages at
a regular interval.  The frequency spin button can be used to set the interval,
in minutes, between the end of one poll and the beginning of the next.  If the
frequency is 0, then the poll is performed once only -- this is equivalent to a
connect-exchange-disconnect sequence but with one button press.

There is a display of the number of polls made during this session.

The polling frequency can be any number of minutes.  The spin button is setup
for 5 minute intervals and will spin between 0 and 1440 (one day).  However you
can enter any positive number you wish.  The polling frequency is saved in your
POPit.INI file and will be restored the next time you start POPit.

If a connection fails, then the polling frequency will be one minute until the
connection succeeds.  From then on the polling frequency will be as indicated
in the spin button.  This was done to better support the poll on start option.

The transaction log contains information about each message retrieved.  This is
not cleared between polls so the list box will contain a history of messages
retrieved.  Remember, in OS/2 2.1 the listbox is limited in how much data can
be stored in it.  If it fills up, POPit will fail.  I try to keep track of how
much of the available space is used, but I cannot guarantee that the limit is
not exceeded because of hidden overhead.  You can clear the list box via the
context menu (the popup menu that pops up when you press the right mouse button
over the list box), alternatively you can disable the listbox.  Since the list
box now contains a history of messages retrieved, two additional pieces of
information are prefaced to the message entry, the time of retrieval and the
poll number.

You should take note of a spin button way over on the other side of the
transaction log called 'Skip'.  This tells POPit that it should ignore, or
skip, the first few messages.

There is a second spin button above the 'Skip' button called 'Max'.  This
defines the maximum size of a message that will be retrieved during a poll.  If
you want to retrieve this message it must be done manually (or you can increase
the maximum size).  A zero entry is interpreted as no limit.  If you have ever
retrieved a mail message over 4Meg in size, especially using the last release
of POPit, you will understand why this limit is there (if you don't already
know, I won't shock you).


ΓòÉΓòÉΓòÉ 6. Notes ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 6.1. Lines Begining with '.' ΓòÉΓòÉΓòÉ

The POP3 protocol is a bit unclear about what to do with lines beginning with a
'.'  -- there are three possibilities, but the protocol description only talks
about two of them.

According to the protocol definition, if a line begins with a '.'  then it is
the last line of the message.  There are two cases.  The first is where there
is a '.'  on a line of its own.  In this case this line is not part of the
message and should be dropped.  In the second case there are other characters
on the line.  In this case only the '.'  is to be removed and the remainder of
the line is the last line of the message.  POPit handles both cases.  (Well
actually, I think it does.  It seems that the POP server I have access to does
not do the second case, and so my testing has been a bit unrealistic).

The third case is when the original message contains a line with '.'  as the
first character.  The POP protocol does not seem to mention this situation.
Obviously POP cannot outlaw this situation.  I have implemented the NNTP
protocol solution where if a line in a message has a leading '.'  then the
server will duplicate the '.'  so there will be two leading '.'s.  In this case
POPit will remove the first '.'  and will not consider this to be the last line
of the message.  The POP server I use, fortunately for me, has taken this
approach as well so POPit does the right thing.


ΓòÉΓòÉΓòÉ 6.2. Error Messages and Handling ΓòÉΓòÉΓòÉ

Where ever possible I attempt to provide a useful error message.  In the case
of a POP3 error, the server is supposed to describe the error, POPit displays
the description.  In the case of a socket error, I rely on IBM's socket
implementation for an explanation.  In the case of an anticipated usage error,
POPit describes the situation.  In the case of an unanticipated error, well,
there isn't too much I can do :-)

The errors that do not result in the immediate termination of POPit (after
displaying the cause of course) is if an error occurs when trying to establish
the connection, or if the POP server returns a negative response.  In these
cases a message is displayed in the transaction log and POPit will accept
another try at connecting.

When there is a negative response from the POP server, POPit attempts to
immediately terminate the conversation.  However, this may not be possible.  If
this kind of error occurs be ready for the situation where the server is still
running and will not allow you to make another connection.

Whenever POPit terminates it attempts to gracefully end the POP session and
close the socket.  On occasion the POP session cannot be exited.  This is
especially true if the server has returned a negative response.  If this
happens it is possible that the POP server is still executing on your mail
host.  In this situation, you will not be able to connect with the server since
it will not allow multiple sessions with the same user (mail queue).  You will
need to talk with your internet connection provider to determine what should be
done in your case.  In my case, I start up a telnet session, login as the mail
user, see if the POP server is running, and if it is, kill it.  If it isn't
running, or if it has become a superuser process, there is nothing I can do
except to appeal to the sys admin folks to kill the server for me.


ΓòÉΓòÉΓòÉ 6.3. POPit.INI ΓòÉΓòÉΓòÉ

A POPit.INI file is created in the directory where you put POPit.exe.  It is
used to hold four types of information.  The first is basic connection
information like your mail host, the POP3 port on the host (should be 110), and
your login name.  The second is your password.  The third is your mail handler.
The fourth is misc. POPit configuration information.

If you change your configuration it is noted which of the first three kinds of
information you have changed.  When you terminate POPit you will be asked if
you want to save any of the changed kinds of information.  So, if you change
your user id, then you will be asked if you want to save your new user id, your
host name and your port number.  This means that if you change your host name
and your user id, you will be only able to save both changes.

The password is kept in its own 'kind' for those of you who are concerned with
security.  There is no default password defined, so if you do not save your
password you will have to enter it each time you run POPit.  Remember, that in
this release POPit will not prompt you for missing information, so if you do
not provide a password on your own initiative you will fail to connect.

There is a menu available that will allow you to save your configuration before
you terminate POPit.  There are two additional options available through this
menu.  The first restores your configuration to what it was the last time you
saved it.  The reset operation goes to the default configuration (i.e.  no
host, user or password, port is 110 and filtered elm mail handler).


ΓòÉΓòÉΓòÉ 6.4. POPitX.DLL ΓòÉΓòÉΓòÉ

This is a socket handler that I wrote for POPit.  It provides significantly
faster throughput and requires significantly less memory and CPU.  Some time
critical portions of POPit have been re-written in C++, replacing the original
REXX versions.


ΓòÉΓòÉΓòÉ 6.5. Handling Large Volumes of Mail and Large Messages ΓòÉΓòÉΓòÉ

As far as I know the only limitation on the number of messages internal to
POPit is the list box.  It is the standard OS/2 list box and so has a limit of
something less than 64k of data in OS/2 2.1 and something more than that in
WARP.  If you have many messages waiting, you may disable the list box. There
is a check box that will allow you to disable or enable it.


ΓòÉΓòÉΓòÉ 7. Terms of Use ΓòÉΓòÉΓòÉ

POPit is copyrighted software of RedRock but there is no charge for its use.
You may redistribute it.  You may not earn any money from POPit, nor may you
include it in any other product without the written consent of RedRock.  You
use it at your own risk.  Test it to your satisfaction before relying on it.

If you use POPit, I do ask that you send me email ([e-mail]) and tell
me who and where you are, how many users at your site, and if you wish to be
notified by email of future releases.  I also ask that you report any bugs to
me via email.

I expect to implement a number of features in POPit which will not be free.  It
is not my intention to charge for the basic POP client functionality.


ΓòÉΓòÉΓòÉ 8. Contacting Me for Help ΓòÉΓòÉΓòÉ

I may be contacted at:

  Bob Hutchison
  RedRock
  135 Evans Avenue
  Toronto Ontario Canada
  M6S 3V9

  Internet:  [e-mail]
  CIS:    72254,1315


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

POP3 is a mail retrieval protocol.  It allows for a client (POPit) to ask a
server about mail in a remote mail queue and retrieve it.  The protocol as
implemented by POPit is defined in RFC 1460.

There are extensions to the POP3 protocol that provide for such things as
detailed information about the messages in the remote queue and the ability to
ask the server to mail messages.  These extensions are not necessarily
supported by your POP3 server, never-the-less POPit will attempt to use two of
these extensions (if they are not available POPit will not crash, at least it