From:	CRDGW2::CRDGW2::MRGATE::"SMTP::CRVAX.SRI.COM::RELAY-INFO-VAX" 10-AUG-1989 17:07
To:	MRGATE::"ARISIA::EVERHART"
Subj:	VMS_SHARE (7.1-004) 6/8

Message-Id:  <8908102039.AA00941@crdgw1.ge.com>
Received: From KL.SRI.COM by CRVAX.SRI.COM with TCP; Thu, 10 AUG 89 11:48:28 PDT
Received: from NSFnet-Relay.AC.UK by KL.SRI.COM with TCP; Thu, 10 Aug 89 11:34:33 PDT
Received: from oak.cc.kcl.ac.uk by NSFnet-Relay.AC.UK   via Janet with NIFTP
           id aa09554; 10 Aug 89 18:20 BST
Date: 		Thu, 10 AUG 89 18:18:21 GMT
From: UDAA055%oak.cc.kcl.ac.uk@NSFnet-Relay.AC.UK
To: info-vax <@NSFnet-Relay.AC.UK:info-vax@kl.sri.com>
Subject:        VMS_SHARE (7.1-004) 6/8
Sender: "JANET UDAA055@UK.AC.KCL.CC.OAK" <UDAA055%oak.cc.kcl.ac.uk@NSFnet-Relay.AC.UK>
Mailer:         Janet_Mailshr V3.4 (23-May-1989)

-+-+-+-+-+-+-+-+ START OF PART 6 -+-+-+-+-+-+-+-+
Xinstead of a sequential search for speed.
X
X
X
X
X2.4 New Unpacking Algorithms
X
XThe algorithm used to unpack code, embedded in the TPU code stored in the
Xoutput share file, has been redesigned to need less error checking and hence
Xless code.  The TPU code is also packed more compactly than before giving
Ximproved compilation speed as well as execution speed.`032
X
X
X
X
X2.5 Error and Status Messages
X
XVMS_SHARE now produces messages similar to the standard VMS form. Messages a
Vre
Xproduced to keep the user informed of progress (these normally go to
Xsys$output) and error messages (which normally go to sys$error).
X
XInitial informational messages from TPU, as it reads in the source, are also
Xprinted. It is hoped that in a future release some way can be found to turn
Xthis off.
X
X
X
X2.6 Exclusion Files
X
XBy defining certain logical names, it is possible to force the exclusion of`
V032
Xparticular files from the sharefile. There are three possibilities: exclusio
Vn`032
Xby directory, exclusion by name, and exclusion by type.
X
XEach logical name may be defined as a comma separated list of items (the lis
Vt`032
XMUST be enclosed within quotes). Any file that matches is excluded from the
Xsharefile. Wildcards are not permitted. Each must be a fixed string.`032
X
XThanks go to Joe Meadows (JOE@BITNET.FHCRCVAX) for the general idea and basi
Vc
Xmechanism.`032
X
X
X
X2.6.1 SHARE_EXCLUDE_DIRS
X
XThis logical is a list of directory names (in their full format). Any file`0
V32
Xwith the same directory name is automatically excluded.
X
XFor example:
X
X   DEFINE SHARE_EXCLUDE_DIRS "`091X`093,`091X.Y`093,`091X.Y.Z`093,`091TWEETY
V`093"
X
Xexcludes any file in any of the listed directories.
X
XIf this logical is absent, then no files are excluded on the basis of their`
V032
Xfull directory name.
X
X
X2.6.2 SHARE_EXCLUDE_NAMES
X
XThis logical is a list of filenames. Any file with the a matching NAME part
V is
Xautomatically excluded.`032
X
XFor example:
X
X   DEFINE SHARE_EXCLUDE_NAMES "MAIN,TRACE,MAIN_CLD"
X
X
XIf this logical is absent, then no files are excluded on the basis of their`
V032
Xfilename.
X
X
X2.6.3 SHARE_EXCLUDE_TYPES
X
XThis logical is a list of file types. Any file with a matching TYPE part is`
V032
Xautomatically excluded. Files with a type of .DIR are automatically excluded
V`032
Xas these are directory files with no valid contents at the time of unpacking
V.
X
XFor example:
X
X   DEFINE SHARE_EXCLUDE_TYPES ".OBJ,.EXE"
X
Xexcludes any file with a type of .OBJ, .EXE or .DIR
X
XIf this logical is absent, then no files are excluded on the basis of their`
V032
Xfile type (except .DIR).
X
X
X
X3. BUG FIXES
X
XA number of long standing bugs have been fixed.
X
X
X
X3.1 Bad split points
X
XOccasionally, the split point was chosen badly such that the part separators
Xwere wrong. In particular, the $GOTO/Label: sequence could appear right afte
Vr
Xthe $COPY command due to the method by which use of $GOTO was decided. This
Xalgorithm has been redesigned and the problem should no longer occur.
X
X
X
X3.2 Hangs During Trailing Blank Processing
X
XWhen wrapping lines containing trailing blanks, the code would sometimes han
Vg
Xin an infinite loop or fail to split on a non-blank character. This has now
Xbeen fixed.
X
X
X
X3.3 Temporary Files
X
XAll temporary files now have a unique name derived from the PID of the curre
Vnt`032
Xprocess and are created in the SYS$SCRATCH directory by default. The choice
V of`032
Xtemporary filename and location may be overridden by defining the logical na
Vme`032
XSHARE_TEMP to whatever is desired.
X
X
X
X
X4. CHANGES IN OPERATION
X
XThere are several significant changes in the operation of VMS_SHARE.
X
X
X
X4.1 Name of Share File
X
XPreviously, the share file name was suffixed by a string of the form '_n_OF_
Vm'
Xwhere 'n' was the part number and 'm' was the total no of parts.
X
XThe share file name is now suffixed only by the 'n' value - part number. Thi
Vs
Xchange is a consequence of the new algorithms used to create the parts,
Xwhereby the total number of parts is not known at the time of writing a
Xparticular part to a file.
X
X
X
X4.2 Obsolete logical names
X
XLogical names supported in previous versions of VMS_SHARE to control`032
Xverification of the operation of the package are no longer supported. These`
V032
Xfunctions have been replaced by the new debugging code.
X
XThese logicals were  SHARE_VERIFY  and  SHARE_DISPLAY.
X
X
X
X4.3 CHECKSUM display
X
XMessages regarding checksums are now suppressed if they are correct, making
V it`032
Xeasier to spot those that are incorrect.
X
X
X
X
X4.4 Version Numbers
X
XThe original version numbers of the packaged files are preserved at the`032
Xunpacking stage. Previously, all files created would have a version number o
Vf`032
X1. This change allows multiple versions of the same file to be packaged if`0
V32
Xrequired.
X
X
X
X4.5 Check Output File Existence
X
XDuring unpacking, the output file is checked to see if it already exists. If
V`032
Xit does, then the file is not overwritten. Instead the file is skipped and a
V`032
Xmessage written to that effect.  This prevents the previous problem where th
Ve`032
Xexistence of the file caused the new version to be ignored without comment a
Vnd`032
Xa checksum failure to be produced.
X
X
X
X
X5.0 TESTING
X
XThe software has been tested under VMS 4.7 and VMS 5.1-1. It should be noted
V`032
Xthat this version of VMS_SHARE is not supported on other versions of VMS,`03
V2
Xalthough it is believed to work on all versions between 4.4 and 5.1-1
Xinclusive.`032
$ CALL UNPACK VMS_SHARE.RELEASE_NOTES;17 625447834
$ create/nolog 'f'
X        `009TECHNICAL INFORMATION ABOUT VMS_SHARE
X
X    `009`009`009`009`009`009`009`009Version 7.1
X    `009`009`009`009`009`009`009`009Aug 1989
X
X
X
X1. INTRODUCTION
X
XVMS_SHARE is designed to package a series of files into a form that can be`0
V32
Xeasily mailed across many different networks. Difficulties arise with doing`
V032
Xthis because of the many and varied possibilities for corruption of data in`
V032
Xtransit.  For example, line wrapping, case folding, transposition of key`032
Xcharacters etc.
X
XVMS_SHARE encodes files before transmission so that these things may be kept
V`032
Xunder control and proper restoral effected at the receiving end.
X
XFor a given series of files to be packaged, VMS_SHARE combines them into a`0
V32
Xsingle large 'text archive' file that can be unpacked into its component fil
Ves`032
Xsimply by running it as a command procedure at the receiving end. For`032
Xconvenience, VMS_SHARE will optionally split the result into multiple parts`
V032
Xthat can be individually mailed and recombined at the receiving end.
X
X
X
X2. WHAT VMS_SHARE DOES NOT DO
X
XObviously, there are no protocols that VMS_SHARE can use between the
Xtransmitting and receiving ends. It relies on the underlying mail system to
Xget things there in one piece.  Should a single line get missed or corrupted
V,
XVMS_SHARE cannot detect this and ask for retransmission. VMS_SHARE should
Xtherefore be used only over essentially reliable communications links
X(reliable in the sense of getting lines whose characters fall within certain
Xbounds, there in one piece!).`032
X
XVMS_SHARE does not deal with binary files, although it will encode any non
Xprinting 8-bit byte into a transmittable format. However, record and file
Xformats are not preserved.  VMS_SHARE should generally be used only with tex
Vt
Xfiles.`032
X
X
X
X3. LIMITATIONS OF MAILERS AND HOW VMS_SHARE GETS AROUND THEM
X
XVarious mail systems have different limitations within them. For instance,`0
V32
Xthey will wrap or truncate lines that are too long, they may limit the size
V of`032
Xan individual mail message, they may transpose characters incorrectly if the
V`032
Xunderlying character set is different from the transmitter (ASCII/EBCDIC is
V a
Xgood example of this).`032
X
XVMS_SHARE encodes the files in different ways to get around the problems.
XPlease note however, that the encoding techniques are NOT foolproof. We have
Xmerely tried to anticipate all possible corruptions and devise an encoding
Xscheme that ensures the conditions under which corruption occurs does not
Xarise. If a form of corruption that has not been anticipated occurs, corrupt
Vion
Xto the transmitted files will be irreparable except through manual editing.`
V032
X
X
X
X3.1 Maximum Size of a Mail Message
X
XMany mail systems cannot cope with single mail messages larger than a fixed`
V032
Xnumber of bytes and will truncate messages or maybe even fail to deliver the
Vm`032
Xaltogether.
X
XThis is a real problem if a large software package is being sent.  VMS_SHARE
V`032
Xtries to overcome this by splitting the packaged files into several parts,`0
V32
Xeach part being smaller than some fixed size. For example, we might send a`0
V32
Xtotal of 300 blocks of code as 15 parts each of 20 blocks or less. VMS_SHARE
V`032
Xwill automatically split at the 20 block boundary.  The actual value is`032
Xconfigurable via a logical name (SHARE_PART_SIZE).
X
XIt should be noted that mail headers added on route can account for several
Xblocks worth of extra space so this should be realised when setting the
Xmaximum part size.
X
X
X
X
X3.2 Maximum Line Length
X
XMany mail systems do not like lines longer than some fixed maximum length, a
V`032
Xmaximum length of 80 characters is typical. This results in longer lines bei
Vng
Xwrapped or truncated at seemingly arbitrary positions.`032
X
XVMS_SHARE tries to cope with this by wrapping long lines itself and insertin
Vg`032
Xmarkers to allow them to be rejoined at the receiving end. What VMS_SHARE do
Ves`032
Xis to prefix each line with a flag character. This flag character says EITHE
VR`032
X'this is the first part of a line' OR 'this line is a continuation of the`03
V2
Xprevious line'.  The wrapping point is chosen carefully to avoid leaving any
V`032
Xtrailing blanks at the end of a line as these are sometimes removed by mail`
V032
Xsystems in transit - the trailing blanks are moved to the start of the`032
Xcontinued line.`032
X
XThe maximum line size is configured into the TPU code as a global value and`
V032
Xcan be easily changed if required. It is not intended that this value should
V`032
Xbe altered by the average user however.
X
X
X
X
X3.3 Trailing Blanks
X
XWhile on the subject of trailing blank removal, VMS_SHARE will translate the
V`032
Xlast character on a line if it is a blank character, into a special 'escape`
V032
Xsequence' that can be recognized by the receiving end and translated back.`0
V32
XThus, the transmitted file is immune to trailing blank removals or additions
V`032
Xbecause there are none.
X
X
X3.4 Escaped Characters
X
XProbably the biggest problem is that a mail message moving through many`032
Xdifferent systems on route to the destination may undergo character`032
Xconversions (for example - ASCII to EBCDIC if moving from VAX to an IBM).`03
V2
XUnfortunately, not all systems keep similar translation tables and character
Vs`032
Xcan get translated into something unexpected at the remote end. Culprits are
V`032
Xcaret (`094), tilde (`126), square and curly brackets ( `091 `093 `123 `125
V ) and a few others.
X
XVMS_SHARE deals with this problem by replacing each of the troublesome`032
Xcharacters - the ones mentioned above plus any non-printing character - by a
Vn
Xescape sequence. The escape sequence is recognized at the receiving end and
V is`032
Xtranslated back to the original character.  Obviously, to work correctly, th
Ve`032
Xescape sequence itself must be immune from translation problems.`032
X
XThe escape technique used is to replace each character by a string of the fo
Vrm`032
X`096nnn   where the `096 symbol flags the start of an escape sequence and th
Ve 'nnn'`032
Xis a 3-digit string which is the ASCII code for the character. Naturally, th
Ve`032
X`096 character itself must be escaped in this form to avoid confusion. For`0
V32
Xexample, a space would be replaced by  `096032   and a tab by  `096009.
X
X
X
X3.5 Detecting Damaged Files with Checksums
X
XIn cases where some corruption occurs despite the encodings used by VMS_SHAR
VE,`032
Xdetection of damage (BUT NOT REPAIR!) should be possible because each file i
Vs`032
Xchecked for accuracy using a checksum once it has been unpacked.
X
XVMS_SHARE uses the currently undocumented CHECKSUM command to produce a`032
Xchecksum value for the source file. This checksum is carried across in the`0
V32
Xpacked share file and checked when the file is restored. A failed match caus
Ves`032
Xa message and the receiver can take action to try to locate and repair the`0
V32
Xdamage.
X
XThe DCL command     CHECKSUM filename     writes the checksum value into a D
VCL
Xsymbol called CHECKSUM$CHECKSUM.
X
X
X
X
X4. VMS_SHARE IMPLEMENTATION
X
XVMS_SHARE is provided as a combination of DCL and TPU code in order to ensur
Ve`032
Xthat it will run on any VMS system.  A specific program would be faster of`0
V32
Xcourse but then portability is not guaranteed.
X
XThe DCL part of the software is used merely to pick up parameters and parse`
V032
Xfilenames, passing them to the TPU code in a scratch file.
X
XThe TPU code does the hard work of packaging the files, wrapping lines,`032
Xescaping characters and generating multiple parts.
X
XAs distributed, the DCL and TPU code are bundled into a single large procedu
Vre`032
Xbut there is no reason why the TPU code could not be extracted and made into
V a`032
Xsection file for enhanced speed. The modifications required are quite`032
Xstraightforward.
X
X
X
X
X
X5. USING VMS_SHARE
X
XAs distributed, VMS_SHARE is run as a command procedure (usually via a`032
Xsuitable symbol set up to point to it) thus:-
X
X     $ @VMS_SHARE filespecs sharefile
X
Xwhere 'filespecs' is a comma separated list of wildcarded filenames to be`03
V2
Xpackaged, and 'sharefile' is the name to be given to the packaged files (the
V`032
Xname will be suffixed by the part number)
X
XThere are some restrictions on the filenames that can be used:
X
X     - Subdirectories may be used provided that they are beneath the current
X       directory. It is not permitted to package files in other directories.
X
+-+-+-+-+-+-+-+-  END  OF PART 6 +-+-+-+-+-+-+-+-

