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

Message-Id:  <8908102143.AA01909@crdgw1.ge.com>
Received: From KL.SRI.COM by CRVAX.SRI.COM with TCP; Thu, 10 AUG 89 11:48:49 PDT
Received: from NSFnet-Relay.AC.UK by KL.SRI.COM with TCP; Thu, 10 Aug 89 11:35:53 PDT
Received: from oak.cc.kcl.ac.uk by NSFnet-Relay.AC.UK   via Janet with NIFTP
           id aa09583; 10 Aug 89 18:21 BST
Date: 		Thu, 10 AUG 89 18:18:27 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) 7/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 7 -+-+-+-+-+-+-+-+
X     - The name of the sharefile must not appear in the 'filespecs' list
X       because the software cannot package a file into itself.
X
X     - At least one valid file must be given in 'filespecs' or no sharefile
X       will be produced.
X
X
X6. UNPACKING A VMS_SHARE FILE
X
XIn general, a package delivered using the VMS_SHARE software will arrive in
V a`032
Xnumber of parts, from 1 up to 'n'.  All parts should be concatenated togethe
Vr`032
Xin order. It is NOT necessary to remove superfluous mail headers from any pa
Vrt`032
Xother than part 1 prior to concatenation.
X
XThe resulting combined file should then be executed as a command procedure i
Vn`032
Xorder to unpack the resulting files.
X
X
X
X6.1 Typical Unpack Sequence
X
XA typical sequence of events goes like this:
X
X - Set your default directory to a scratch directory which is empty.
X
X - Go into MAIL and select the folder which contains the parts of the
X   package.
X
X - Extract part 1 into a file, using the command 'EXTRACT/NOHEADER        fi
Vle'
X   Extract part 2 into a file, using the command 'EXTRACT/NOHEADER/APPEND fi
Vle'
X   ...
X   ...
X   Extract part n into a file, using the command 'EXTRACT/NOHEADER/APPEND fi
Vle'
X
X - Read warning below BEFORE proceeding!!!
X
X - Execute as a command procedure, using the following command:
X      $ @file
X
X
X
X6.2 Warning
X
XIt is strongly suggested that the generated command procedure ('file.SHAR' i
Vn`032
Xthe above example) be carefully checked before execution. It is possible tha
Vt`032
Xunscrupulous persons might tamper with the source before sending it and`032
Xintroduce a virus into the VMS_SHARe'd code. There is nothing that VMS_SHARE
V`032
Xcan do about this automatically. However, since all the files should be huma
Vn`032
Xreadable it should be possible to detect fraudulent code by manual checking.
V`032
XCertainly the lines starting with '$' symbols should be checked carefully as
V`032
Xthese are most likely to be troublesome.
X
X
X
X
X7. DECLARATION AND DISCLAIMER
X
XThis software is in the public domain and may be freely distributed without`
V032
Xcharge as required. However, all copyright notices and references to the
Xauthor in the source must be left intact.`032
X
XThird party modifications may be made to the source but any errors arising`0
V32
Xfrom their use are entirely the responsibility of the modifier.
X
XThe author accepts no responsibility for the suitability of this software fo
Vr
Xany specific purpose. Any errors arising from its use are entirely the
Xresponsibility of the user.`032
X
X
X
XAndy Harper
XKings College London UK
$ CALL UNPACK VMS_SHARE.TECHNICAL_INFO;11 1499878101
$ create/nolog 'f'
X
X
X    `009`009         V M S _ S H A R E
X
X    `009`009 A guide to use for the general user
X
X    `009`009`009        By
X
X    `009`009`009    Andy Harper
X    `009`009`009Kings College London
X
X__________________________________________________________________________
X
X
X    `009`009`009  C O N T E N T S
X
X
X    `009`0091.`009INTRODUCTION
X
X    `009`0092.`009OVERVIEW
X
X    `009`0093.`009USING VMS_SHARE
X    `009`009`0093.1 Input File specification
X    `009`009`0093.2 Output File specification
X    `009`009`0093.3 Examples
X    `009`009`0093.4 Restrictions on files
X
X    `009`0094.`009USING PAKMAIL
X    `009`009`0094.1 User specification
X    `009`009`0094.2 File specification
X    `009`009`0094.3 Part specification
X    `009`009`0094.4 Comment specification
X
X    `009`0095.`009CONTROLLING OPERATION WITH LOGICAL NAMES
X    `009`009`0095.1 Exclusion by directory
X    `009`009`0095.2 Exclusion by name
X    `009`009`0095.3 Exclusion by type
X    `009`009`0095.4 Logging
X    `009`009`0095.5 Setting the size of a part
X    `009`009`0095.6 Inclusion of user's real name
X    `009`009`0095.7 Location of temporary files
X    `009`009`0095.8 Verification
X
X    `009`0096.`009HOW TO UNPACK A SHARE FILE
X    `009`009`0096.1 Command file
X    `009`009`0096.2 Dealing with multiple part share files
X
X
X    `009`0097.`009REFERENCES:
X
X    `009`009`009`0911`093 VMS_SHARE Technical Information supplement
X    `009`009`009`0912`093 VMS_SHARE Release notes
X    `009`009`009`0913`093 On-line HELP
X
X
X_________________________________________________________________________
X
XVersion 7.1-004`009`009`009`009`009     `009`0094 AUG 1989
XRevision 1
X`012
X1.`009INTRODUCTION
X
XWith the advent of worldwide computer networks and electronic mail systems,
V it
Xbecomes possible to use the computer networks as a means of distributing
Xsoftware packages. This has the advantage of providing a quick, cheap and
Xrelatively reliable means of getting it to the end user.`032
X
XHowever, not all mail systems are 100 % reliable. They will not necessarily`
V032
Xlose information but may corrupt that information if its format strays outsi
Vde`032
Xcertain boundary conditions.
X
XThe VMS_SHARE package is designed to allow complete software packages to be`
V032
Xsent without worrying about these limitations. It has a knowledge of a wide`
V032
Xrange of limitations and encodes the information into a form that is more`03
V2
Xacceptable to the network mail systems.
X
XThis document describes how to use the components of the system; in`032
Xparticular, the VMS_SHARE utility itself and the PAKMAIL utility for mailing
V`032
Xthe output to one or more recipients. Also described is the mechanism for`03
V2
Xrecombining the parts and recreating the original input files.
X
XThe release notes for the package describe new features and general changes`
V032
Xfrom previous releases `091Reference 2`093.
X
X
X2.`009OVERVIEW
X
XThere are two basic components to the VMS_SHARE package. The first is the`03
V2
XVMS_SHARE utility itself:
X
XFrom a user specified set of input files, VMS_SHARE packs and encodes the
Xinformation into a single file, known as an archive or 'share' file. It then
Xsplits up the file into pieces sufficiently small to be mailed individually
Xthrough an electronic mail system without truncation to a recipient. It is t
Vhe
Xrecipients responsibility to recombine the pieces into a single file which,
Xwhen executed as a command procedure, creates an exact copy of the original
Xinput files. Checksums are provided to ensure that if the information is
Xcorrupted by some unforeseen mechanism then it is at least detected.`032
X
XVMS_SHARE encodes the information to cope with different types of potential`
V032
Xcorruption, such as line wrapping/truncation, character code conversions,`03
V2
Xtrailing blank removal etc.  Full details can be found in the technical guid
Ve`032
X`091Reference 1`093.
X
XThe second utility is PAKMAIL. This gathers the generated pieces of the shar
Ve`032
Xfile and mails them to one or more recipients across the electronic mail`032
Xnetwork using the VMS MAIL utility.
X
X
X`012
X3.`009USING VMS_SHARE
X
XVMS_SHARE is usually made available via a global symbol, so the command for
Xactivating it is:`032
X
X     $ VMS_SHARE <input> <output>
X
Xwhere  <input> is an input file specification (see below) and <output> is th
Ve`032
Xname to be given to the output 'share' file (see below). If a parameter is n
Vot`032
Xsupplied, a prompt is issued.
X
X
X3.1 Input File specification
X
XThe input file specification is a comma separated list of standard VMS`032
Xfilenames, which may include wildcards anywhere. For example:
X
X     TEST
X    `009The specific file   "TEST."
X
X     *.FOR
X        All files ending in ".FOR"
X
X     `091...`093*.*;*
X        All files in and below the current directory.
X
X     *.FOR,*.MAR
X        All files ending in ".FOR", then all files ending in ".MAR"
X
X
XAny subdirectories will be recreated when the share file is unpacked. For th
Vis`032
Xreason and the fact that no useful information is contained within them,`032
Xdirectory files (those ending in .DIR) are always ignored.
X
X
X3.2 Output File specification
X
XThe output file name is used as a template to construct the individual parts
V`032
Xof the share file.  The name supplied here is suffixed by a 'part number' fr
Vom`032
X1 upwards. For example:
X
XAn output filename of:
X    PACKAGE.PRELIM
X
Xwould generate files called:
X    PACKAGE.PRELIM_1
X    PACKAGE.PRELIM_2
X     ...
X
XAs many parts as necessary to contain the whole package are generated.
X
X
X
X3.3 Examples
X
XTypical examples of the use of VMS_SHARE would be:
X
X     $ VMS_SHARE `091...`093*.*;* ARCHIVE.SET
X         Archive the whole of the directory tree, starting from the current
X         directory into a share file with a template name of "ARCHIVE.SET".`
V032
X         This would generate files called "ARCHIVE.SET_1", "ARCHIVE.SET_2"
X         etc.
X
X
X     $ VMS_SHARE `091.DOC`093*.*,`091.EXE`093*.*,`091.SRC`093*.*  VI
X        Archive all files in the three directories `091.DOC`093, `091.EXE`09
V3 and `091.SRC`093
X        and generate share files with a template name of "VI." ie "VI.1",
X        "VI.2" etc.
X
XWhen unpacked, the tree structure of the original files will be preserved.
X
X
X3.4 Restrictions on files
X
XIn order to ensure that the recipient receives the files in a known set of`0
V32
Xdirectories, only files within or below the current directory may be used as
V`032
Xinput.  The tree structure is preserved, from the current directory downward
Vs,`032
Xand will be recreated below the recipient's current directory at unpacking`0
V32
Xtime.
X
XFor example, if we archived the files "`091.SRC...`093*.*;*" the recipient w
Vould`032
Xfind an exact copy of the `091.SRC...`093 tree recreated below his current`0
V32
Xdirectory.
X
X
X`012
X4.`009USING PAKMAIL
X
XOnce the share file parts have been created, they can be transmitted over th
Ve`032
Xelectronic mail network to one or more recipients using the VMS MAIL utility
V.`032
XPAKMAIL is a utility to simplify the sending mechanism by providing a single
V`032
Xline command to send the complete package. Typically, PAKMAIL is made`032
Xavailable via a 'foreign command' so the command is:
X
X     $ PAKMAIL recipient file parts `091comment`093
X
XEach of the parameters is explained below.
X
X
X
X4.1 User specification
X
XThe recipient parameter is the mail address of the user, or users, who are t
Vo`032
Xbe sent the package. This can take any form of mail address acceptable to th
Ve`032
XVMS MAIL system when used from the command line. For example:
X
X   FRED
X   NODE::JIM
X   NODE::JIM,FRED
X
XThere are two small problems to watch out for. Firstly, the use of`032
Xdistribution lists requires an @ symbol to precede a file specification whic
Vh`032
Xcontains the recipient names. Used directly, DCL intercepts the @ before mai
Vl`032
Xdoes, and so the command does not work correctly. To avoid this, define a`03
V2
Xlogical name to point at the distribution list and specify the logical name
V as`032
Xthe recipient. For example:
X
X   $ DEFINE USERS "@BETA_TEST_USERS.DIS"
X   $ PAKMAIL USERS ...
X
XSecondly, usernames that contain quotes (") need special attention because o
Vf`032
Xthe way DCL/MAIL parse quoted strings. Typically, this is important when`032
Xsending network mail as the usual form of address is:
X
X   NET%"user@site"
X
XIn this instance, the quotes must be doubled, with another set around each`0
V32
Xto give an address specification of:
X
X   NET%"""user@site"""
X
X
X
X4.2 File specification
X
XThe file specification gives the name of the package to be sent. It should b
Ve`032
Xthe share file template name - omitting the part numbers. For example, a`032
Xspecification of "PACKAGE.TEST" will cause the package to send these files:
X
X   PACKAGE.TEST_1
X   PACKAGE.TEST_2
X   ...
X
X
X4.3 Part specification
X
XThis is simply the total number of parts in the package. It controls how man
Vy`032
Xfiles to be sent to each recipient.
X
X
XA typical example of a PAKMAIL command would be
X
X   $ PAKMAIL NET%"""FRED@SCROUNGING-SITE""" PACKAGE.TEST 5
X
X
X
X4.4 Comment specification
X
XThe subject line of the mail message sent to each recipient identifies the`0
V32
Xpackage, which part and the total number of parts in the form:
X
X   Subj: PACKAGE.TEST  1/5
X
X
XOptionally a further parameter can be given on the PAKMAIL command. This`032
Xparameter will be inserted verbatim into the subject line.
X
XFor example, if this command is issued:
X
X   $ PAKMAIL NET%"""FRED@SCROUNGING-SITE""" PACKAGE.TEST 5 "(Beta-Test v2)"
X
XThen the generated subject line would look like this:
X
X   Subj: PACKAGE.TEST (Beta-Test v2) 1/5
X
X
X`012
X5.`009CONTROLLING OPERATION WITH LOGICAL NAMES
X
XVMS_SHARE will operate satisfactorily with all of its default settings.`032
XHowever a number of options are available to tailor its operations to local`
V032
Xrequirements. Each of these options is controlled through a logical name`032
Xdefinition of the form "SHARE_xxxx"  where xxxx is the particular option in`
V032
Xquestion.
X
XOptions are available to exlude files on the basis of directory, name or typ
Ve;`032
Xto log or not log certain informational messages; to determine the maximum`0
V32
Xsize of each part; to force inclusion of an identifying string into the shar
Ve`032
Xfile; to specify the location of temporary files' and to verify operation of
V`032
Xthe code.
X
X
X5.1 Exclusion by directory
X
XIf the logical name  SHARE_EXCLUDE_DIRS is defined with a comma-separated li
Vst
Xof non-wildcarded directory names, then any file which has a similar directo
Vry
Xspecification will be excluded from the share file.`032
X
XFor example,
X
X   $ define share_exclude_dirs "`091JIM.EXE`093,`091JIM.OBJ`093"
X
XAny files in these two directories will be excluded. Note that the directory
V`032
Xname MUST be given in full.
X
XIf the logical name is not defined, then files are not excluded on the basis
V`032
Xof their directory name.
X
X
X
X5.2 Exclusion by name
X
XIf the logical name  SHARE_EXCLUDE_NAMES is defined with a comma-separated
Xlist of non-wildcarded filenames, then any file which has a similar name
Xspecification will be excluded from the share file.`032
X
XFor example,
X
X   $ define share_exclude_names "TEST,DUMMY"
X
XAny files with either of the two names will be excluded.`032
X
XIf the logical name is not defined, then files are not excluded on the basis
V`032
+-+-+-+-+-+-+-+-  END  OF PART 7 +-+-+-+-+-+-+-+-

