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

Message-Id:  <8908102033.AA00808@crdgw1.ge.com>
Received: From KL.SRI.COM by CRVAX.SRI.COM with TCP; Thu, 10 AUG 89 11:48:18 PDT
Received: from NSFnet-Relay.AC.UK by KL.SRI.COM with TCP; Thu, 10 Aug 89 11:31:59 PDT
Received: from oak.cc.kcl.ac.uk by NSFnet-Relay.AC.UK   via Janet with NIFTP
           id aa09552; 10 Aug 89 18:20 BST
Date: 		Thu, 10 AUG 89 18:18:12 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) 5/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 5 -+-+-+-+-+-+-+-+
X    Inform("I","DBGPAR", "Params: Share_File = """ + Share_File + """");
XENDIF;
X`012
X! INITIALIZE STUFF TO GO THROUGH FILES
XStart_Of_Filenames := MARK(NONE);
XPartNo := 0;
XMax_Bytes := 512 * Max_Blocks;
X
X! Reserve space in the part buffers for 1 start and 1 end part + CR/LF chars
X! + a bit spare! They may not always be used but this is the worst case!
XReserved  := LENGTH(FAO(FAO_start_part,Max_Parts))
X           + LENGTH(FAO(FAO_end_part,  Max_Parts))
X           + 6;
X
X
X! CREATE THE INITIAL SHARE FILE HEADER
XCreate_Prologue_Head(work_buf, Username, Max_Blocks, Start_Of_Filenames);
XAdd_To_Part(work_buf,SPLIT_permit_goto);
X
XCreate_Prologue_Unpacker(work_buf);
XAdd_To_Part(work_buf,SPLIT_disallowed);
X
XCreate_Prologue_Trail(work_buf);
XAdd_To_Part(work_buf,SPLIT_permit_goto);
X
XPOSITION(Start_Of_Filenames);
X
X! LOOP AROUND, FILLING THE PART BUFFER WITH DATA FROM FILES
XLOOP
X   POSITION(info_buf);
X   EXITIF MARK(NONE) = END_OF(info_buf);
X
X   file_info := CURRENT_LINE;   MOVE_VERTICAL(1);
X   separator := INDEX(file_info,' ');
X   fname     := SUBSTR(file_info,1,separator-1);
X   chksum    := SUBSTR(file_info,separator+1,LENGTH(file_info)-separator);
X
X   IF DEBUG_state THEN
X      Inform("I","DBGPAR", "Params: filename = """ + fname + """");
X   ENDIF;
X
X   Create_File_Header(work_buf);
X   Add_To_Part(work_buf,SPLIT_permit_goto);
X
X   Create_File(work_buf,fname);
X   Quote_Buffer(work_buf, ANY(Funny_Chars));
X   Quote_Buffer(work_buf, " "&LINE_END);
X   Wrap_Lines(work_buf,Max_Line_Length);
X   Add_To_Part(work_buf,SPLIT_inhibit_goto);
X
X   Create_File_Trailer(work_buf,fname,chksum);
X   Add_To_Part(work_buf,SPLIT_permit_goto);
X
XENDLOOP;
X
XCreate_Epilogue(work_buf);
XAdd_To_Part(work_buf,SPLIT_permit_goto);
X
X
XPartNo := PartNo + 1;
XPOSITION(BEGINNING_OF(pt1_buf));
X
X
XIF PartNo > 1
X  THEN`009! Modify the inital message to state exact number of parts
X     POSITION(SEARCH( "$!+", FORWARD) );
X     POSITION( SEARCH( STR(Max_Parts), FORWARD) );
X     ERASE_CHARACTER(3);
X     COPY_TEXT( STR(PartNo) );
X
X  ELSE`009! Erase initial attention message as there's only 1 part!
X     MOVE_TEXT(part_buf);
X     POSITION(BEGINNING_OF(pt1_buf));
X     POSITION(SEARCH( "$!+", FORWARD) );
X     ERASE_LINE; ERASE_LINE; ERASE_LINE;
XENDIF;
X
XFlush_Buffer(part_buf, PartNo);
XFlush_Buffer(pt1_buf,  1);
X
XInform("I","NOOFPTS",FAO("Share file written in !UL part!%S",PartNo));
X
Xexit;
X$ delete /nolog /noconfirm 'temp';*
X$ v=f$verify(v)
$ CALL UNPACK VMS_SHARE.COM;64 1820193153
$ create/nolog 'f'
X! Version 7.1-004 OF VMS_SHARE
X!      - 4 AUG 1989,   Andy Harper,  Kings College London UK
X1 VMS_SHARE
XPackage a series of files into a form suitable for mailing out
Xacross the network.`032
X
XFormat:
X     $ VMS_SHARE filespec sharefile
X2 Errors
XThe following error codes may be produced. Errors are normally in
Xthe form of standard VMS error messages although they cannot be`032
Xsuppressed with SET MESSAGE.
X3 ABORT
XThe user has aborted the procedure with CTRL-Y or CTRL-C.`032
X3 CANTSPLIT
XIndicates that VMS_SHARE has tried to split the share file into
Xtwo or more parts and the split point boundary is in a place
Xwhere it is not allowed to be. In this case, this is usually in
Xthe packed TPU code which is written to the output share file.`032
X
XThe usual cure is to increase the minimum size of a part so that
Xthe split point boundary moves to a new position, hopefully past
Xthe offending section.`032
X3 CHKSMFAIL
XIndicates that the file just unpacked from the archive is in some
Xway damaged as its checksum does not match that of the original.
XThe share file should be checked for corruption around this file.
X3 CREDIR
XIndicates that the file is to be unpacked into a subdirectory and
Xthis subdirectory needs to be created. An attempt to create that
Xsubdirectory will be made.`032
X3 CREDIRFAIL
XIndicates that an attempt to create the directory for the output
Xfile, during unpacking, has failed for some reason. Probably due
Xto lack of disk quota or no access to the parent directory.`032
XIt may also be because more than 8 levels of directory are`032
Xrequired in which case, change the default directory up`032
Xsufficient levels to reduce the requirement to 8.
X3 CURLINEIS
XAn error during the processing of one of the lines of an input
Xfile has occurred and the current line being processed is listed
Xfor reference. This should be preceded by an actual error message
Xdescribing the problem.`032
X3 DBG
XVarious DBGxxxxxx message can be produced but only if the
Xdebugging flag within VMS_SHARE has been turned on. This option
Xis restricted to the system manager.`032
X3 FILRDERR
XIndicates that some kind of error occurred trying to read the
Xcontents of one of the input files into the buffer. Either it has
Xgone away since the filename parameters were parsed or the user
Xhas no read access to the file contents. The name of the
Xoffending file is shown in the message.`032
X3 FILWRERR
XAn error has occurred writing to the indicated file. This is most
Xlikely due to lack of disk quota or no write access to the parent
Xdirectory.`032
X3 NOOFPTS
XAn informational message confirming the number of parts created.`032
X3 NOOUTDIR
XThe use has specified a file to hold the created share file but
Xthe directory in which to create that file does not exist. It
Xmust exist before running VMS_SHARE and is not created
Xautomatically.`032
X3 NOPARFIL
XThe temporary file used to pass parameters into the TPU program
Xcannot be created. This is likely due to insufficient disk quota
Xor no access to the parent directory. Also check the SHARE_TEMP
Xlogical to ensure it is either not defined or defined with the
Xcorrect scratch file name.`032
X3 NOTINTREE
XThe specified file was not within or below the current directory.
XThis is a requirement of VMS_SHARE to prevent the recipient of a
Xshare file unpacking and having files created in random parts of
Xthe directory structure. If it is truly necessary to package
Xfiles in other directories, then set the default directory to a
Xlevel which is higher than all of them.`032
X3 OLDVER
XThe version of VMS currently running is not of a sufficiently
Xrecent version to allow the unpacking of the share file to take
Xplace. The required minimum version is stated in the message.`032
X3 OLDVMS
XThe version of VMS currently running is not of a sufficiently
Xrecent version to allow VMS_SHARE to run. A minimum revision is
Xneeded because of certain VMS features used that do not exist in
Xearlier versions. The required minimum version is indicated in
Xthe error message.`032
X3 PROCESS
XIndicates that file unpacking is now being performed and that the
Xnamed file will be created.`032
X3 SELECTED
XAn informational message indicating that a particular file has
Xbeen selected for inclusion into the share file.
X3 SHRNOTPACK
XA file with the same name as one of the generated share file
Xparts has been discovered. It is not possible to package a share
Xfile into itself and so this file is rejected.`032
X3 TPULONGREC
XProcessing of a line of input has resulted in a record that is
Xtoo long to be handled by the current version of TPU and hence
Xcannot be processed. The line will be left as it is and probably
Xcause errors during transmission (such as truncation).`032
X2 Examples
X     $ VMS_SHARE *.for SOURCE
X          Package all the files ending in .FOR into the sharefile
X          'SOURCE'. Parts will be created called SOURCE.1, SOURCE.2 ...
X          etc.
X
X     $ VMS_SHARE `091...`093*.* SBDIR
X          Package all the files in all subdirectories below the
X          current one. The directory structure, relative to the current
X          directory, will be preserved and recreated at the unpacking
X          stage.
X2 Filespec
XA comma-separated list of wildcarded filename specifications. All
Xfiles which match the pattern(s) are packaged.`032
X
XThere are some restrictions:-
X     - The output share file name may not be included in the list.
X     - files ending in .DIR (normally directory files) are ignored.
X     - Files must exist in or below the current directory.
X
XA prompt is issued if no files are specified.
X2 Logical_Names
XSeveral logical names can be configured to control the operation
Xof VMS_SHARE.`032
X3 SHARE_EXCLUDE_DIRS
XIf defined with a comma separated list of directory
Xspecifications, enclosed in quotes, any file matching any of the
Xlisted directories will be excluded from the packaging operation.
X
XWildcards are not permitted; all directories must be listed in
Xfull.`032
X3 SHARE_EXCLUDE_NAMES
XIf defined with a comma separated list of names, enclosed in
Xquotes, any file whose NAME part matches any of the listed names
Xwill be excluded from the packaging operation.`032
X
XWildcards are not permitted.
X3 SHARE_EXCLUDE_TYPES
XIf defined with a comma separated list of file types, enclosed in
Xquotes, any file whose TYPE part matches any of the listed types
Xwill be excluded from the packaging operation.`032
X
XWildcards are not permitted.
X3 SHARE_LOG
XIf defined with a logical value (YES/NO, TRUE/FALSE etc.)
Xdetermines whether the unpacking stage produces informational
Xmessages about its progress. Error messages are always output.`032
X
XThe default is to produce the informational messages.
X3 SHARE_PART_SIZE
XIf defines, sets the maximum part size. The value is specified in
Xblocks and must be greater than 6. A zero value causes the
Xdefault size to be used otherwise a value less than 6 causes 6 to
Xbe used.`032
X
XThe default size is 30 blocks.
X3 SHARE_REAL_NAME
XDefines a string which is included at the head of the created
Xshare file following the username of the user who created it.  It
Xis intended that it will contain the real name of the user (For
Xexample, "FRED SMITH").`032
X3 SHARE_VERIFY
XIf defined with the value "TRUE" (or 1 or "YES" etc.) then
Xverification of the VMS_SHARE procedure is turned on. If defined
Xwith "FALSE" (or 0 or "NO" etc.) verifications is turned off.`032
X
XIf the logical is not defined at all, verification is off.
X
XNote that the user must have READ access to the procedure for
Xverification to be enabled.`032
X3 SHARE_TEMP
XDefines the name of a file to be used as a scratch file during
Xthe packaging operation.`032
X
XDefaults are taken from the name`032
XSYS$SCRATCH:SHARE_TEMP.TMP_'pid' where 'pid' is the current
XProcess Identification number.`032
X2 Operational_Notes
XVMS_SHARE packages all the specified files into one or more parts
Xhaving a common filename prefix. The suffix will be the part
Xnumber. Multiple parts will be created if the total size of a
Xpart exceeds the specified maximum size (taken from the logical
XSHARE_PART_SIZE).`032
X
XEach part is encoded so that it can survive destruction when
Xmailed across the network through unfriendly mailers which wrap
Xlines, transpose characters etc. A checksum is included which can
Xdetect damage at the receiving end.`032
X
XTo unpack, all parts must be concatenated in order and the whole
Xexecuted as a command procedure. It is preferable to be in an
Xempty scratch directory when doing this. If the parts have been
Xreceived via mail then it is NOT necessary to remove the mail
Xheaders between parts before concatenating them.  The unpack code
Xwill ignore them if present. However, mail headers should be
Xremoved from the initial part.`032
X2 PAKMAIL
XThe PAKMAIL utility may be used to send the generated parts of
Xthe sharefile to one or more recipients over the electronic mail
Xnetwork. Consult the separate help entry for full details.`032
X2 Sharefile
XThe name of the packed output file. This name will be suffixed by
Xthe part number even if there is only 1 part created.`032
X
XA prompt is issued if no sharefile name is specified.
$ CALL UNPACK VMS_SHARE.HLP;11 1450259994
$ create/nolog 'f'
X        `009`009`009V M S _ S H A R E
X
X    `009`009`009   R E L E A S E   N  O T E S
X
X
X
X    `009`009`009`009`009`009`009`009Version 7.1
X    `009`009`009`009`009`009`009`009Aug 1989
X
X
X1. INTRODUCTION
X
XVersion 7.1 of VMS_SHARE has been completely rewritten to eliminate long
Xstanding bugs, and to improve performance by utilising new algorithms for th
Ve
Xpacking and upacking of files. Details of the changes from the previous
Xversions are given below.
X
X
X
X2. NEW FEATURES
X
X2.1 Subdirectories
X
XVMS_SHARE now supports subdirectories.  The user may package a series of fil
Ves
Xexisting in the directory tree within/below the current directory. The
Xdirectory structure will be recreated at the unpacking stage as an equivalen
Vt
Xtree beneath the current directory. All required directories are automatical
Vly`032
Xcreated as required.
X
XFor example:
X
X    $ VMS_SHARE `091.TPU...`093*.*,`091.DATA`093*.* PACKAGE.SHAR
X        Will package the directory tree beneath `091.TPU`093 and the subdire
Vctory
X        `091.DATA`093.  During unpacking, these subdirectories will be creat
Ved
X        automatically below the current directory.
X
X
XIt was originally decided to make the directory handling a bit like BACKUP,`
V032
Xallowing any directory to be packaged and individual items to be selected at
Xunpack time. However this proved to be extremely difficult in DCL and so was
Xabandoned. It may appear in a future release.  In order to prevent files
Xappearing in essentially random directories it was decided to adopt the abov
Ve
Xcompromise. It retains sufficient flexibility to deal with most package`032
Xstructures but maintains a known directory structure that will avoid files`0
V32
Xbeing placed randomly as far as the receiving user is concerned.
X
X
X
X2.2 DEBUG code
X
XTo assist those who enhance and develop VMS_SHARE, a large amount of
Xdebug/trace code is included into the source.  By redefining a simple global
Xconstant value, this debug code can be turned on or off to assist in trackin
Vg
Xdown faults.
X
X
X
X
X2.3 New Part Splitting Algorithms
X
XThe algorithms used for splitting parts have been extensively redesigned to
Xensure minimal use of memory for buffers. Essentially, VMS_SHARE now uses on
Vly
Xenough memory to hold the sum of two parts and the largest file. We read a
Xsingle file, add as much as possible to the part buffer and then write the
Xpart buffer, removing the equivalent info from the original file buffer.
X
XThe algorithm for finding the optimum part breakpoint now uses a binary sear
Vch
+-+-+-+-+-+-+-+-  END  OF PART 5 +-+-+-+-+-+-+-+-

