this is a inet loadmod that contains functions to sendmail, check/retrieve 
mail, retrieve web pages, and ftp functions.  The following illistrates how 
to call the individual functions:


     call  "inet;sendmail"    using SmtpServer,to,from,subject,message
     call  "inet;sendmaila"   using SmtpServer,to,from,subject,message,attach

     call  "inet;pop3stat"    using pop3Server,user,pass,Buffer[,callback]
     call  "inet;pop3getmsg"  using pop3Server,user,pass,msgid,anOpenfile[,callback]
     call  "inet;pop3getmsgd" using pop3Server,user,pass,msgid,anOpenfile[,callback]
     call  "inet;pop3getAlmsg"  using pop3Server,user,pass,anOpenfile[,callback]
     call  "inet;pop3getAlmsgd" using pop3Server,user,pass,anOpenfile[,callback]

     call  "inet;httpget"     using URL,anOpenfile

     call  "inet;ftpcmd"
     call  "inet;FTPGETdir"   using localip,FTPSERVER,dir,FTPNAME,FTPPASS [,callback]
     call  "inet;FTPGETfile"  using localip,FTPSERVER,FTPFILEname,user,pass[,callback]
     call  "inet;FTPPUTfile"  using localip,FTPSERVER,FTPFILEname,user,pass[,callback]
     call  "inet;FTPGETdirP"  using FTPSERVER,dir,FTPNAME,FTPPASS[,callback]
     call  "inet;FTPGETfileP" using FTPSERVER,FTPFILEname,user,pass[,callback]
     call  "inet;FTPPUTfileP" using FTPSERVER,FTPFILEname,user,pass[,callback]

and here is a discription of the varibles used by these functions:


 SmtpServer    = DIM      outgoing mail server name or ip addr
 pop3Server    = DIM      incomming mail server name or ip addr
 URL           = DIM      a web page url (www.sunbelt-plb.com)
 FTPServer     = DIM      FTP server name or ip address
 localip       = dim      your local ip address
 to/from       = DIM      e-mail address of sender/reciepiant
 subject       = DIM      Subject of message
 attach        = DIM      path and filename of file to attach to an e-mail
 Buffer        = DIM      return parameter
 message       = DIM      the actual e-mail message to be sent
 anOpenFile    = FILE     an open file handel to be used as workspace
 user/pass     = DIM      the username and password used to login to a server
 FTPFILEname   = DIM      the name of a file to upload/download to/form a FTP
                          server
 msgid         = FORM     the message number you wish to download from a pop3 
                          server
 dir           = dim      the path of a directory to retrieve

 callback      = dim    this is an optional feature to the routines that
                        is used to 'call back' into your program to relay
                        status information.  This is the only varible that
                        is NOT declared as a pointer so a constant can be
                        used.  To use this optional parameter, the string 
                        must contain the name of your plc followed by a
                        semicolon and the function name. e.g. "myprog;funct"

  your callback function, if you elect to use it, must be declaired as a 
routine and has a dim type parameter.  For example:

status  dim     ^
funct  routine status
 return

You can do anything you want from this funct but keep in mind that the longer 
you take to return, the longer the routines will take to compleate.

  The status for FTP is it is a packed list that looks like:

stat    list
bytesTransfered form 10
status          dim  250
        listend

bytesTransfered has no meaning until a file up/down load has started and is 
given for the purpose of updateing a progress bar or similar and your callback
will be called every 1024 bytes received.


"inet;ftpcmd" starts an interactive ftp session on the main window.  It takes 
no parameters.   WINSHOW will need to be executed before calling this 
funcition.

All of these varibles are diclared as pointer types so a program cannot pass 
in constants. (with the exception of the optional callback parameter)

on error, most of these functions will set the over flag.

Note: all modules require the Sockets loadmod.
      SendmailA   requires the base64 loadmod
      FTPPutFileP currently does not work do to limitation in the runtime


This document will try to explain how to use each function.

------------------------------------------------------------------------------
httpget
-------
site	dim	80
wwwfile	file

	prep	wwwfile,"wwwtext.htm"
	move	"www.yahoo.com",site
	call	"inet;httpget"    using site,wwwfile
	if (OVER)
...........communications error
	endif

the over flag is set only if there was an error while connecting or recieving data.  If there was a problem with your URL on the other hand, any responce the web server returned will be found in the file.  You can even specify detailed URLs like:
	"http://www.geocities.com/plbdev"
and the functions will retrieve the correct information.

------------------------------------------------------------------------------
sendmail
sendmailA
--------

This is a simple functions that can be used to send TEXT ONLY e-mail messages 
up to 64k in size.  To use this function, you will need to know either the 
name or ip address of your outgoing SMTP e-mail server.  If you are currently 
useing netscape or outlook for your e-mail, you can copy the name of your 
outgoing mail server into your program.  A typical call would look something 
like....

mailserver	dim	80
to		dim	80
from		dim	80
subject		dim	80
message		dim	100

	move	"mail.myisp.com",mailserver
	move	"myfriend@aol.com",to
	move	"myaddr@myisp.com",from
	move	"what I want to talk about",Subject
	move	"the contents of the actual e-mail message",message
.
	call	"inet;sendmail"   using SmtpServer,to,from,subject,message
	if (OVER)
		display "sending mail failed"
	else
		display "message sent"
	endif

Typically, an e-mail program is much more complex but I want to keep the 
illistrations simple.

SendmailA is used to send an attachment with your message and takes an 
additional parameter (attach).  The attach parameter is a dim varable that
contains the a path specified filename to attach.  SendmailA the uses BASE64
encodeing to send the attachement using MIME 1.0 compliant message headers.

------------------------------------------------------------------------------
pop3stat
--------

this function although internally more complex, has a simple interface and returns in buffer a very simple mailbox status.  To use this function you will need the name or ip address of your incomming pop3 mail server.  IMAP is not supported and will not work.  If you are currently useing netscape or outlook for your e-mail, you can copy the name of your incomming mail server into your program.  To illistrate:

pop3Server  dim   60
user        dim   16    ;this is usually 8 but just to be safe...
pass        dim   16    ;this is usually 8 but some systems support long passwords
buffer      dim   100

      move  "mail.myisp.com",pop3server
      move  "smith",user
      move  "secret",pass

      call  "inet;pop3stat"   using pop3Server,user,pass,Buffer

when this function returns, Buffer contains some value that looks like '4 1534'.  This means that there are 4 messages that take up 1534 bytes.  This function actuall returns an error string in buffer if there was a problem.  Possible Error returns are:

(the over flag is set on error)

Comm error 1                             :comm error getting login responce (user)
Comm error 2                             :comm error getting login responce (password)
Comm error 3                             :comm error stat inquery send error
Comm error 4                             :comm error logoff verification
Cannot connect to pop-3 server           :self explanitory
Comm start error                         :we connected but the server is not responding
Connection refused                       :self explanitory
...                                      :any error returned by the pop3 server

------------------------------------------------------------------------------
pop3getmsg
pop3getmsgd
----------

this function will actually download a message from your pop3 mail box but it 
does not delete it.  Lets extend the example from pop3stat to download the
last e-mail in a pop3 mailbox:

the pop3getmsgd variation deletes the message after downloading it.  This can 
have the effect of changeing the msgids for subsequent calls.  All msgid's 
below the one you downloaded are typically moved up by one.  You could then
call pop3getmsgd multiple times with msgid '1' until you get a no such message
error back to retireve all the messages.


pop3Server  dim   60
user        dim   16    ;this is usually 8 but just to be safe...
pass        dim   16    ;this is usually 8 but some systems have long passwords
buffer      dim   100
msgfile     file

      move  "mail.myisp.com",pop3server
      move  "smith",user
      move  "secret",pass

      call  "inet;pop3stat"   using pop3Server,user,pass,Buffer

      scan        " ",buffer
      bump        buffer,-1
      lenset      buffer
      reset       buffer
      move        buffer,msgcount

      prep  msgfile,"inbox.txt",exclusive
      call  "inet;pop3getmsg" using pop3Server:
                              user,pass,msgcount,msgfile

the message file is formatted with a msg start an msg end lines. 

+OK 428 octets
<actual message would be here>
.

where the +OK 428 octets is the start of the message and message size.  
The end of the message is marked with a <CRLF>.<CRLF> or a line containing a 
singel period.

error return codes are the same as pop3stat.

------------------------------------------------------------------------------
pop3getAlmsg
pop3getAlmsgd
-------------
these functions are just like pop3getmsg with some exceptions.  First off it 
downloads all the messages in a pop3 mailbox.  Because it downloads all the
messages, no msgid parameter is used.  To illistrate the useage of these 
functions:

pop3Server  dim   60
user        dim   16    ;this is usually 8 but just to be safe...
pass        dim   16    ;this is usually 8 but some systems have long passwords
msgfile     file

      move  "mail.myisp.com",pop3server
      move  "smith",user
      move  "secret",pass
      prep  msgfile,"inbox.txt",exclusive
      call  "inet;pop3getALmsg" using pop3Server:
                              user,pass,msgfile


the pop3getALmsgd functions downloads all the messages from the server, then
deletes them from the server.


------------------------------------------------------------------------------
ftpcmd
-------

      this functions is rather simple....


     call  "inet;ftpcmd"
      
 this starts an interactive ftp session on the main window.  It talks no 
parameters and flags are undefined upon return.

------------------------------------------------------------------------------
The rest of the FTP command require parameters.  It needs to be pointed out 
that before any of them will work, localip must be set up correctly or 
the ftp server will not be able to send the requested data.  In windows, you 
can execute a 'route print >junk.txt' and parse the junk.txt file for your ip
address.  Generally, if you look at the first entry, Network Address 0.0.0.0
the interface column will contain your ip address.  In UNIX, you can parse the
returned information from 'ifconfig' but you need to be root to execute that.

  Also the FTPxxxP command are firewall friendly and do not require a localip 
parameter.

  Error checking in these loadmods are rather difficult because they are 
actually loadmod wrapers to the ftpcmd where any erros are displayed on the
screen and left to the user to handle.

------------------------------------------------------------------------------
FTPGetDir
FTPGetDirP
---------

  this functions returns a directory listing in buffer of the specified folder.
Do the the fact that this program makes not attemt to maintain state between 
calls, path names relitive to the starting path must be used.  FTPGetDirP uses
passive mode (which is firewall friendly).

localip     dim   15
ftpserver   dim   80
ftpdir      dim   80
ftpname     dim   15
ftppass     dim   20
buffer      dim   2000


      move  "123.456.789.012",localip     ;this obviously needs to be your 
                                          ;local ip

      move  "ftp.sunbelt-plb.com",ftpserver
      move  "download/",ftpdir
      move  "anonymous",ftpname
      move  "none@nowhere.com",ftppass
      
      call  "inet;FTPGETdir"  using localip:
             FTPSERVER,FTPdir,FTPNAME,FTPPASS,buffer
  -or-

      call  "inet;FTPGETdir"  using FTPSERVER,FTPdir:
            FTPNAME,FTPPASS,buffer


buffer will contain a directory listing of the 'download' folder and looks
like:

d---------   1 noone    nogroup          0 Jan 09 10:49 .
d---------   1 noone    nogroup          0 Jan 09 10:49 ..
----------   1 noone    nogroup        984 Nov 10 1995  asc2hex.pls
----------   1 noone    nogroup       2690 Dec 01 1998  ASCHEX.ZIP
----------   1 noone    nogroup      53187 Nov 04 1996  CGI.ZIP
----------   1 noone    nogroup       8037 Feb 18 1999  CGIWIN.ZIP
----------   1 noone    nogroup       4774 Mar 26 1996  COMM.ZIP
----------   1 noone    nogroup     916952 Nov 06 1998  CONF98.ZIP
----------   1 noone    nogroup     449101 Nov 05 1999  CONF99.ZIP
d---------   1 noone    nogroup          0 Jan 09 10:49 demo
----------   1 noone    nogroup      91558 Aug 14 1998  FONTEDIT.ZIP
----------   1 noone    nogroup       2207 Sep 28 1998  hteditmask.zip
----------   1 noone    nogroup       1787 Oct 02 1998  KEYINGUI.ZIP
----------   1 noone    nogroup      37443 Sep 22 1998  link361.zip
----------   1 noone    nogroup    3599076 Aug 01 2000  LINUXSUP.ZIP
----------   1 noone    nogroup       5550 Nov 06 1998  LVSORT.ZIP
----------   1 noone    nogroup       1294 Dec 10 1998  TCPIP.ZIP
----------   1 noone    nogroup    4118269 Nov 29 1999  TVEDT.ZIP
----------   1 noone    nogroup    1069607 Apr 12 1995  WHAT6.EXE
----------   1 noone    nogroup    7962743 Sep 15 1998  win32.zip

if an entry is prefixed with a d then it indecates a directory entry.  The
exact format of a directory listing varies from server to server but directories
are always prefixed with a d.

-------------------------------------------------------------------------------
FTPGETfile
FTPGETfileP
----------

  This function retrieves a file from a FTP server into the current working 
directory. FTPGETfileP uses passive mode (which is firewall friendly).

localip     dim   15
ftpserver   dim   80
FTPFILEname dim   80
user        dim   15
pass        dim   20


      move  "123.456.789.012",localip     ;this obviously needs to be your 
                                          ;local ip

      move  "ftp.sunbelt-plb.com",ftpserver
      move  "download/LVSORT.ZIP",FTPFILEname
      move  "anonymous",user
      move  "none@nowhere.com",pass

      call  "inet;FTPGETfile" using localip,FTPSERVER,FTPFILEname,user,pass
  -or-      
      call  "inet;FTPGETfileP" using FTPSERVER,FTPFILEname,user,pass


This example will download "LVSORT.ZIP" into the current working directory.  
It must be pointed out that the FTP protocall uses UNIX style pathing so a 
forward slash '/' needs to be used instead of the backslash '\'.

unfortunately, error checking proves difficult from inside the loadmod.  What
is recomended is it check the file size on the server with the FtpGetDir call
and check the local filesize after the transfer and compair the two.

------------------------------------------------------------------------------
FTPPutFile
FTPPutFileP
----------

  This functions upload a file in the current directory to a ftpserver.
FTPPutFileP uses passive mode (which is firewall friendly).

localip     dim   15
ftpserver   dim   80
FTPFILEname dim   80
user        dim   15
pass        dim   20


      move  "123.456.789.012"       ,localip

      move  "ftp.sunbelt-plb.com"   ,ftpserver
      move  "upload/myfile.ZIP"     ,FTPFILEname
      move  "anonymous"             ,user
      move  "none@nowhere.com"      ,pass

      call  "inet;FTPPUTfile" using localip,FTPSERVER,FTPFILEname,user,pass
   -or-      
      call  "inet;FTPPUTfileP" using FTPSERVER,FTPFILEname,user,pass

  In this example, the FTPPutFile call opens the local file myfile.zip in the 
current directory.  It then uploads the file to the ftpservers upload folder.
Again, error checking within the loadmod proves difficult so it is recomended
that you peform a ftpgetdir call and compair the file sizes...

