OS/2 Shareware BBS: 35 Internet/35-Internet.zip/dsptcha1.zip/readme.dis

Text File | 1997-05-30 | 12KB | 303 lines

Dispatch started as an exercise in socket programming with Object REXX.
There is virtually no socket documentation comprehensible to a
non-programmer -- especially someone who cannot even read C. So I used a
freeware REXX pop client I found on Hobbes as a model.  It did not work --
OREXX is more intolerant of extra 'END' statements than TREXX.  But at
least I understood the general structure.  There is little of that program
left in mine now.

As for protocols, I found that RFC's are easier to understand that I had
expected.  So I wrote a bunch of little utilities:  One to receive mail via
POP -- into a unique folder for each message with all attachments detached.
One to send mail via SMTP with files appended.  One to post news.  One to
download an entire newsgroup.  Etc.

The other day, I decided to combine three of these into one.  The result is
Dispatch.

Dispatch is a compiled OREXX program.  It will only run under Warp 4.0 or
on a system with Object REXX installed and active.  It uses REXXLIB
utilities and two shareware packages for mime and uuencoding.  I will
eventually write both into my program.  I have the Base64 model I need, but
does anyone have a REXX UUencoding model?  It also uses the excellent
SofTouch TCPIP functions.

There are three parts to the command line:
DISPATCH[space]FUNCTION[space]PARAM1[space]PARAM2....

DISPATCH is, of course, the name of the command file:  dispatch.cmd

FUNCTION is one of the following:

M[AIL] for SMTP mail out N[EWS] for newsgroup posting F[ILE] for file
transfer using FTP V[ERSION] for version info Anything else for function
help

PARAMS are different for each function.  They always take the form of a
space, a dash and a single letter followed, in most cases by some
information.  Avoid using any other space dash combinations within the
command line!  No space between the latter param identifier and the
following information.  For example:  -Ac:\test.tst adds an attachment
named test.txt located on the c drive to outgoing mail.

The -?  param will list out a list of parameters for the function
specified:

dispatch M -?

MAIL PARAMETERS

-T To Address Dispatch M [e-mail] -S Subject Dispatch M
-SWhat is this about?  -C Config File Dispatch M -Cdispatch.mle -A Text
File Dispatch M -Ac:\textfile.txt -A* Binary File Dispatch M
-A*c:\binary.tif -F From Addr Dispatch M [e-mail] -Z Time
Zone Dispatch M -Z-0500 -H Host Machine Dispatch M -HMyHost.domain.com -M
Mail Server Dispatch M -Mmailhost.domain.com -Y Reply-To Dispatch M
[e-mail]

I do not think you can use a '<' or '>' on the command line.  So, if you
want any address to be in the format:  Chris Barr<[e-mail]> you must
enter it as

[e-mail](Chris Barr) and the program will redo it.

The Reply-To address defaults to the same address as the From address
unless overridden.

The Config file is an optional file that loads in certain invariable
values.  More later.

-A designates files to be attached.  The first file attached is the 'note'
itself.  Subsequent files are all attachments.

-A by itself designates a plain text file to be appended without encoding.
The first file must be of this type and is treated as the 'note.'
Subsequent text files are attached without base64 encoding and their file
names indicated.

-A* designates a binary file that requires encoding in base64.

You may attach as many files as you can fit on the command line.

The time zone defaults to GMT if not entered.

The mail server must be entered by name and not by IP address.

Values for parameters are set in the order entered.  So, you can set the
zone in your config file to -0500 and override it in one case by putting
-Z-0400 (Note:  no space before the second dash) AFTER the -Cconfig.file.

Also set the Reply-To address after the From address.

The config file sets the following parameters:

FromAddr ReplyToAddr YourHost MailServer Zone

All info must be included.  One entry to a line.  No blank lines.  In this
exact order.  Addresses are not converted, so use the format Chris
Barr<[e-mail]> if that is what you want.  Do not prepend the param
designator.  Here is mine:

Chris Barr<[e-mail]> Chris Barr<[e-mail]> thinkpad.fsrl.com
mailhost.myisp.net -0500

NEWS PARAMETERS

-C Config File Dispatch M -Cdispatch.nws -X ControlFile Dispatch M
-Xdispatch.ctl -N NewsServer Dispatch M -Snetnews.isp.net -F FromAddr
Dispatch M -Fsomeone.domain.com -G News Groups Dispatch M
-Gcomp.os.os2.mail-news -R F/U Groups Dispatch M -Rcomp.os.os2.mail-news -A
Text File Dispatch M -Ac:\newspost.txt -E BinaryFile Dispatch M
-Ec:\picture.jpg -H HostName Dispatch M -Hmachinename -D Domain Dispatch M
-Ddomain.com -S Subject Dispatch M -SThis is a posting

The same general rules apply as for mail, with these exceptions and
additions:

The config file is a different file for news.  More later.

The control file is a special file that can take the place of some of the
command line parameters.  You might, for example, keep a template for each
group of newsgroups to which you cross post.  More later.

The newsserver is the name and not the IP address of the newsserver.

The Newsgroups are entered in one continuous stream separated by commas.
The Follow/Up group(s) default to the same as the post to groups, but can
be overridden by the -R parameter.

One text file and one uuencoded file are allowed.

The hostname is the machine name with no domain.

The config file format is as follows:

newsserver domain zone host FromAddr Organization

The same rules apply to this config file as to the mail config file.

The option Xternal Control file format is as follows:

SUBJECT Dispatch for OS/2 POSTGROUPS
alt.test,comp.os.os2.mail-news,comp.os.os2.advocacy FOLLOWUP alt.test FILE
c:\readme.dis UUENCODE NONE

It must be exactly as stated, with your entries, of course.  No blank
lines.  If you do not include a type of file, you must type 'NONE'.

FTP PARAMETERS

-U Logon User Dispatch M -Uyourname -P Password Dispatch M -Ppassword -Q
PutUnique?  Dispatch M -Q -A Account Dispatch M -Aaccountname (usually not
required) -D RemoteDir Dispatch M -Dpub/incoming -R RemoteName Dispatch M
-Rdispatch.zip -F LocalFile Dispatch M -Fc:\upload\dispatch.zip -H FTPHost
Dispatch H -Hhobbes.mnsu.com

The same rules apply as for mail, with these changes and additions:  If you
do not specify a remote file name, the local name (without path) will be
used.

WARNING

All three of these functions have been somewhat tested as free standing
modules.  FTP, however, was an afterthought and has not been tested since
it was added.

There is only primitive error detection and handling.  This program crashes
easily and cryptically.  But since it is a simple command line utility, it
usually does no harm -- and tells you that it has died.

BUT -- I will not be responsible for any damage of any kind that results
directly or indirectly from your use of this program.  You are warned that
I am a novice programmer and that this is an experiment.

FUTURE PLANS

Add fax dispatch support.  (I already posted a utility to do this, FxShell.
I will integrate it.)

Add optional, simple GUI for the functions.

Add an xternal control file feature and file lists for both mail and ftp.

THE INTELLIGENT QUEUE

I am rather proud of this feature -- although I have no idea if it actually
adds to performance.  At least I got it to work.

The original model I had to work with used LINEIN and LINEOUT methods.  The
pop client went like this:

Grab a handful of data from the socket Parse out the first line (by looking
for a CRLF) Save it using LINEOUT Parse out the second line Save it Etc.
Etc.  Retain the last bit of data in the buffer if it is a partial line
Grab another handful of data from the socket.

The program forgot to strip off any dot ('.') which begins a line.  This
would add more overhead.

It seemed to me that, even at disk access speeds, this method must add
overhead.  So I tried to create an Object REXX Queue object with built in
logic.

My intelligent Queue is a subclass of the standard queue object.  My pop
client, for example, does the following in place of what I described above:

Gets a bunch of data off the socket.  Checks to see if it has the EOF
marker at the end.  Queues it on the intelligent queue Gets another bunch
of data off the socket Etc.

Meanwhile, the queue process has been started as a concurrent process.  It
pulls data off itself, looks for dots that need stripping (without parsing
the data into lines) and saves the data using CHAROUT.

The program you are about to use uses the same idea.  The intelligent queue
reads in data in 10,000 character chunks.  It pads any beginning of line
dots with dots.  It queues the data on itself and goes back to the file for
more.  Meanwhile, the main process which created the queue starts pulling
data off the queue and sending it out.

It is fast.  With text files I have peaked at 115200 -- my port speed.

The most recent version of this program uses similar queues for moving
temporary data around.  For example, I use mpack to make base64 files, but
strip off the headers and boundaries.  To do this, I used to make a
temporary file and then copy it line by line onto the target file,
stripping out unwanted data.  Now, I let an intelligent queue do the
processing and use CHARIN and CHAROUT.  It is certainly faster than it was,
but I have no idea if the queue adds anything at all.

DOSFILE

There is one other aspect to this program I should mention.  I use a
version of a class I am working on called DOSFile.  It is an enhanced
subclass of the Stream class.  Instances of the DOSFile class have all the
methods of the stream class plus:  they can copy or move or delete or
create themselves, parse their paths, etc.  When it moves itself (or,
optionally, when it copies itself) it allows one to move its focus to the
new physical file.  Let me explain:

MyFile = .DOSFile~new('c:\example1.txt')

Yields a REXX instance of the .DOSFile class.  It is manipulated by
reference to the MyFile variable.  You get data out, for example, by using:

line = MyFile~linein

(I guess if it were REALLY object oriented they would have used LINEOUT,
but that would have created too much confusion.)

Let's say I need to move the underlying disk file into a directory.  I
might write:

MyFile~move('c:\temp\example2.txt','R','V')

MyFile now refers to c:\temp\example2.txt

So MyFile~delete, deletes the new file.

Or, let us say I want to copy data from example1.txt onto example2.txt and
start dealing with the target file instead of the source file.

MyFile~copy('example2.txt','A','V','COPY')

appends the data from MyFile onto example2.txt and then switches the focus
of MyFile to example2.txt.

The free standing version of DOSFile also includes methods for the file to
zip itself, email itself, fax itself, base64 encode itself, etc.  In light
of what I have learned from writing Dispatch I will have to rewrite DOSFile
completely.  It was intended to make programming easier.  I am not
completely satisfied with it from having used it, but the idea works and I
will continue work on it.

LICENSE

This grants you a license to experiment with this program at your own risk
until it is withdrawn.  The license will be deemed withdrawn upon release
of any shareware or commercial version of the product.

FEEDBACK

Feedback is solicited.  But be gentle.  I wrote my first OREXX program only
three months ago and my first real REXX program only a year ago.  And it is
hard to teach old -- 50 yo -- dogs new tricks.

INSTALLATION

Almost forgot this part.  Put Dispatch anywhere you want.  Activate OREXX
-- See the Warp 4 README Copy the GRXTCPIP.DLL to a directory in your
LIBPATH.  Install the REXXLIB DLL contained in the Demo package enclosed.
Install MPACK and UUENVIEW to directories in your PATH.

Chris Barr
[e-mail]

PS

I forgot the following --

FTP -- the default mode is text. For binary, prepend the name
of the file to send with an * just as a mime file is in mail:

-F*dsptcha1.zip