From:	CSBVAX::MRGATE!RELAY-INFO-VAX@CRVAX.SRI.COM@SMTP 23-AUG-1988 18:02
To:	ARISIA::EVERHART
Subj:	VMS_SHAR V5.04 part 2/2


Received: From KL.SRI.COM by CRVAX.SRI.COM with TCP; Mon, 22 AUG 88 22:55:28 PDT
Received: from godot.psc.edu by KL.SRI.COM with TCP; Mon, 22 Aug 88 22:53:41 PDT
Received: by godot.psc.edu (5.51/umd.04)
        id AA08461; Tue, 23 Aug 88 01:52:37 EDT
Date: Tue, 23 Aug 88 01:52:37 EDT
From: David Gentzel <gentzel@godot.psc.edu>
Message-Id: <8808230552.AA08461@godot.psc.edu>
To: info-vax@kl.sri.com
Subject: VMS_SHAR V5.04 part 2/2

$Part2:
$File_is="VMS_SHAR.READ_ME"
$Check_Sum_is=543271189
$Copy SYS$Input VMS_SHAR_DUMMY.DUMMY
XVMS_SHAR.READ_ME:
X
XVMS_SHAR is an attempt to provide a tool to package source modules for
Xmail transmission. It will package any number of files into a self-unpacking
Xprocedure. A number of steps are taken to insure file integrity.
X
XVMS_SHAR is convenient for applications consisting of a number of source
Xmodules, because they are automatically created at the receiver's end;
Xit is necessary because various mailers may mutilate source code in a
Xnumber of ways:
X o split lines which are longer than 80 characters,
X o remove leading white space;
X o munge control characters like <TAB>, <ESC>, or <BEL>,
X o choke on 8-bit characters.
X
XFeatures:
X o Through the use of SET SYMBOL/SCOPE=(NOLOCAL,NOGLOBAL) both VMS_SHAR
X   and the procedures created by it are very rubust against local
X   idiosyncrasies with symbols. Imagine a user who does: IF=="!" !
X o The resulting file gives the username of its creator and date/time
X   of creation. If the global symbol REAL_NAME exists, its content is
X   also displayed.
X o The resulting file contains a list of all its files.
X o Each line is prepended by character "X" or "V" to preserve leading spaces 
X   through various mailers.
X o Lines longer than 79 characters will be split (and are prepended by "V").
X o All non-printable ASCII characters (0-31,127-255) are transmitted as
X   quoted decimal numbers.
X o Some mailers disallow postings above a certain size. VMS_SHAR will check
X   that the resulting file will not exceed MAX_PART_SIZE which is currently
X   set to 31 blocks (our mailer disallows postings >16000 characters).
X   If more than 31 blocks are to be posted, VMS_SHAR will create multiple
X   files by appending a 'part number' to the output file name.
X   If one single input file exceeds MAX_PART_SIZE the user will be notified,
X   and 'part number' will be incremented such that subsequent manual splitting
X   has free 'part numbers' available.
X   If the logical name SHAR_MAX_SIZE is defined as a number, that number
X   will be used as MAX_PART_SIZE.
X o At both creation and unpacking time, each file is CHECKSUMmed; the result
X   of the comparison of both values is displayed to the user.
X o Signatures and such, which might occur at the end of each part, don't
X   need to be stripped. They are skipped by the unpacking procedure.
X o The created procedure will check for VMS version 4.4 or higher.
X
XAbout Version 2.00:
XMainly a cleaning-up re-write. Fixed the case where full pathnames were
Xgiven. Also checks now whether the output filename is among the input
Xfilenames.
XThe procedure now performs in two distinct steps:
X a) collecting file names and their size information,
X b) actually packaging the files.
XThis allows to include an indication of the number of parts at the top
Xof the resulting file. It also allows to omit part-suffixes if not required.
XHowever, under rare circumstances this might not work.
XOne condition which springs to mind where it doesn't work is:
XYou package two files, the first one 30 blocks, the second 1 block.
XLet's call the difference between 512 and the number of bytes which are
Xactually used in the first file's last block "spare bytes".
XIf the number of lines in the first file is greater than 512+"spare bytes",
Xthen VMS_SHAR will attempt to create a filename for part 2, but it has not
Xbeen properly initialised and will fail. Well, not really. It will complain
Xabout an unknown symbol "I", and will not append its version suffixes, but
Xwill still create the files, only using standard VMS version increments.
X
XAnother case which is insufficiently handled is when one single file
Xexceeds MAX_PART_SIZE. The whole numbering scheme gets out of kilter
Xand the packager is left with a renaming task.
X
XAbout Version 3.00:
XI had some discussions with usenet members, particularly with
XEd <MCGUIRE@GRIN2.BITNET> about trailing white space.
XHe suggested to use a length count at the beginning of each line, and to
Xsplit lines longer than 80 characters and restore them at the receiving site.
XI didn't follow that suggestion for three reasons:
X 1. The unix shar doesn't cater for this either.
X 2. It would have increased processing time a lot.
X 3. I didn't ever experience serious difficulties due to lost trailing
X    white space.
X
XHowever, it was Ed who came up with a method to use EDT to insert/remove
Xthose leading "X"s. As this turned out to be 3 times faster than my
Xprevious method (OPEN/READ/lexical function/WRITE) this was implemented
Xin version 3.00
X
XSome days later, after some more good arguments and examples from Ed:
XOK, I'm convinced that splitting lines is a good idea.
XHowever, this will take some time to implement as it needs to be done
Xin TPU and I'm a complete TPU agnostic. But that's what producing these
Xtoys is all about, no? Playful learning.
X
XThe created procedure will now have "Goto <next part>" at the end of
Xeach part and "Exit" as its last statement. This should take care of
Xsignatures which might occur at the end of each part.
X
X3.07 introduced usage of TPU to add/remove leading Xs. I'm slowly getting
Xon top of TPU.
X
XOn Version 4.00:
XAfter some further useful contributions from the net - esp. BERNIE@UMBC2.EDU
X(Bernie Duffy) - a line splitting feature was introduced. I.e. if a line is
Xlonger than 79 characters it gets split. However, if a line contains TABs
Xthis may not be sufficient. The only way out is to compensate for TABs,
Xassuming standard 8-column-TABs. However, I couldn't get TPU to search for
Xa TAB within a line. So you have to de-TAB the files before you feed them
Xto VMS_SHAR. I hope to be able to present a TPU-deTAB soon.
X
X05-Aug-1987, after some holidays (Cook Islands, great spot):
XNow, thanks to
X TOLLIVER%ORN.MFENET@NMFECC.ARPA (John Tolliver) and
X STRASSER@RSBS0.ANU (Mike Strasser) and
X MSIEWEKE@GTRI01@BITNET
XI know how to search for TABs within a line, but this was of course a
Xdead end street, as detabbing would mess up the checksums.
XSo instead, I came up with a TPU detabbing procedure, called DETAB.COM
X
XOn Version 4.04 15-Sep-1987:
XOh boy, am I embarassed. How could this happen?
XThe TPU code checking for lines which need splitting was wrong. I should have
Xnoticed much earlier when somebody from the net (???) noticed that both
Xoccurrences of "79" should be changed to "78". The real problem, however, was
Xthat I subtracted 1 from Length(Current_Line). Why did I do that?
XAnyway, wiping off the egg from my face (until next time).
X
XOn Version 4.05 21-Sep-1987:
XCorrected a bug in the part counting code. All previously documented
Vrestrictions still apply, i.e.: due to added characters in the packaging proce
Xss
Xthe actual number of parts may still differ from what the procedure's first
Xpass through the files determines.
X
XOn Version 4.06 22-Sep-1987:
XAfter many useful exchanges with usenet members
X[special thanks to SDCSVAX!SDCC12.UCSD.EDU!GR65 (Steve Piper)
X and SLOANE@UKANVAX.BITNET (Bob Sloane) ]
XI added some informational messages when the packaging process creates more
Xfiles than originally anticipated.
XAlso, initialising Part_Size to 4 instead of zero improved the part-counting
Va lot. The rationale is that a packaged null-file will produce about 3.6 block
Xs.
X
XOn Version 5.00 24-Sep-1987:
XNow here is a good idea from Bob Sloane how to quote control characters.
VIts not entirely new, but Bob's example TPU code triggered my renewed interest
X.
XAll control characters (0...31,127...255) are translated to a 3-digit number,
Xquoted by "``" (accent grave); all "``" are doubled.
XSo <TAB>, <BEL>, <ESC> shouldn't be a problem any more.
XAgain, TPU exhibits a deficiency: no inverse function to ASCII.
X[string:=ASCII(integer); where is: integer:=FUNCTION(string) ? And why is this
Xfunction called ASCII, and not CHAR?]
X
XSome minor changes to the remaining code were also made. And the new encoding
XTPU code is heavily sprinkled with comments, which is not feasible for the
Xdecoding part, because that is transmitted every time VMS_SHAR is used.
X
XOn Version 5.01 01-Oct-1987:
VVMS_SHAR now checks for the logical name SHAR_MAX_SIZE. If that name is define
Xd
Xas a number, that number will be used as MAX_PART_SIZE.
X
XOn Version 5.02 06-Oct-1987:
VKen Wallewein (kenw@noah.arc.cdn) complained about lines being wrapped althoug
Xh
Xthey are exactly 80 characters. So, lines are now split after 78 characters.
XAlso, Barry Tannenbaum (TANNENBAUM%JHEREG.DEC@DECWRL.DEC.COM) and 
XJohn Tolliver (TOLLIVER%ORN.MFENET@NMFECC.ARPA) suggested a more
Xefficient method of determining the ASCII value of control characters,
Xusing the TPU function INDEX.
X
XOn Version 5.03 07-Oct-1987:
XCarlo Mekenkamp (BOTMAN@HLERUL5.BITNET) suggested to use "Create file"
Xinstead of "Copy NL: file". Tests indicate that CREATE is about 30% faster
Xand the image size of CREATE is only 11 blocks, compared to 62 for COPY.
XSo I followed that suggestion.
X
XOn Version 5.04 04-Feb-1987:
XWarner Losh (LOSH@NMTVAX.NMT.EDU) suggested:
X> The status message that it gives (now writing to xxx.a_of_b) doesn't appear
X> when a is 1.
XDone.
X
XStu Labovitz (LABOVITZ%ETD1.DECNET@AFWAL-AAA.ARPA) suggested (as have others
Xbefore) that the first of thetwo lines ``..... cut here .....' ``$!......'
Xshould also start with ``$!'. Done. There is only one such line now:
V$!...................... Cut on the dotted line and save .....................
X.
X
XI also tried to reduce the size of the transmitted files (minimally) by
Xremoving all superfluous blanks.
$GoSub Convert_File
$Exit

