From:	MERC::"uunet!WKUVX1.BITNET!FILESERV-Mgr"  6-JUL-1992 18:49:28.94
To:	galaxy::gleeve
CC:	
Subj:	VMS_SHARE.004-OF-005

-+-+-+-+-+-+-+-+ START OF PART 4 -+-+-+-+-+-+-+-+
XBy defining certain logical names, it is possible to force the exclusion of`
V20
Xparticular files from the sharefile. There are three possibilities: exclusio
Vn`20
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`20
XMUST be enclosed within quotes). Any file that matches is excluded from the
Xsharefile. Wildcards are not permitted. Each must be a fixed string.`20
X
XThanks go to Joe Meadows (JOE@BITNET.FHCRCVAX) for the general idea and basi
Vc
Xmechanism.`20
X
X
X
X2.6.1 SHARE_EXCLUDE_DIRS
X
XThis logical is a list of directory names (in their full format). Any file`2
V0
Xwith the same directory name is automatically excluded.
X
XFor example:
X
X   DEFINE SHARE_EXCLUDE_DIRS "`5BX`5D,`5BX.Y`5D,`5BX.Y.Z`5D,`5BTWEETY`5D"
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`
V20
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.`20
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`
V20
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`
V20
Xautomatically excluded. Files with a type of .DIR are automatically excluded
V`20
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`
V20
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`20
Xprocess and are created in the SYS$SCRATCH directory by default. The choice
V of`20
Xtemporary filename and location may be overridden by defining the logical na
Vme`20
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`20
Xverification of the operation of the package are no longer supported. These`
V20
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`20
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`20
Xunpacking stage. Previously, all files created would have a version number o
Vf`20
X1. This change allows multiple versions of the same file to be packaged if`2
V0
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`20
Xit does, then the file is not overwritten. Instead the file is skipped and a
V`20
Xmessage written to that effect.  This prevents the previous problem where th
Ve`20
Xexistence of the file caused the new version to be ignored without comment a
Vnd`20
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`20
Xthat this version of VMS_SHARE is not supported on other versions of VMS,`20
Xalthough it is believed to work on all versions between 4.4 and 5.1-1
Xinclusive.`20
$ CALL UNPACK [.VMS_SHARE]VMS_SHARE.RELEASE_NOTES;1 976603665
$ create 'f'
X        `09TECHNICAL INFORMATION ABOUT VMS_SHARE
X
X    `09`09`09`09`09`09`09`09Version 7.2
X    `09`09`09`09`09`09`09`09Feb 1990
X
X
X
X1. INTRODUCTION
X
XVMS_SHARE is designed to package a series of files into a form that can be`2
V0
Xeasily mailed across many different networks. Difficulties arise with doing`
V20
Xthis because of the many and varied possibilities for corruption of data in`
V20
Xtransit.  For example, line wrapping, case folding, transposition of key`20
Xcharacters etc.
X
XVMS_SHARE encodes files before transmission so that these things may be kept
V`20
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`2
V0
Xsingle large 'text archive' file that can be unpacked into its component fil
Ves`20
Xsimply by running it as a command procedure at the receiving end. For`20
Xconvenience, VMS_SHARE will optionally split the result into multiple parts`
V20
Xthat can be individually mailed and recombined at the receiving end.
X
X
X
X2. WHAT VMS_SHARE DOES NOT DO
X
XBecase VMS_SHARE relies on electronic mail to ship the files, there are no`2
V0
Xprotocols that can be used to check the accuracy of the received file(s).`20
XThere is a reliance on the underlying mail system to get everything there in
V`20
Xone piece and unchanged.  VMS_SHARE is unable to ask for retransmission of`2
V0
Xmissing or damaged pieces.
X
XVMS_SHARE should therefore be used to send files only via essentially reliab
Vle`20
Xmail systems which can get files, whose characters fall within certain bound
Vs,`20
Xthere intact.
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.`20
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,`2
V0
Xthey will wrap or truncate lines that are too long, they may limit the size
V of`20
Xan individual mail message, they may transpose characters incorrectly if the
V`20
Xunderlying character set is different from the transmitter (ASCII/EBCDIC is
V a
Xgood example of this).`20
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.`
V20
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`
V20
Xnumber of bytes and will truncate messages or maybe even fail to deliver the
Vm`20
Xaltogether.
X
XThis is a real problem if a large software package is being sent.  VMS_SHARE
V`20
Xtries to overcome this by splitting the packaged files into several parts,`2
V0
Xeach part being smaller than some fixed size. For example, we might send a`2
V0
Xtotal of 300 blocks of code as 15 parts each of 20 blocks or less. VMS_SHARE
V`20
Xwill automatically split at the 20 block boundary.  The actual value is`20
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`20
Xmaximum length of 80 characters is typical. This results in longer lines bei
Vng
Xwrapped or truncated at seemingly arbitrary positions.`20
X
XVMS_SHARE tries to cope with this by wrapping long lines itself and insertin
Vg`20
Xmarkers to allow them to be rejoined at the receiving end. What VMS_SHARE do
Ves`20
Xis to prefix each line with a flag character. This flag character says EITHE
VR`20
X'this is the first part of a line' OR 'this line is a continuation of the`20
Xprevious line'.  The wrapping point is chosen carefully to avoid leaving any
V`20
Xtrailing blanks at the end of a line as these are sometimes removed by mail`
V20
Xsystems in transit - the trailing blanks are moved to the start of the`20
Xcontinued line.`20
X
XThe maximum line size is configured into the TPU code as a global value and`
V20
Xcan be easily changed if required. It is not intended that this value should
V`20
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`20
Xlast character on a line if it is a blank character, into a special 'escape`
V20
Xsequence' that can be recognized by the receiving end and translated back.`2
V0
XThus, the transmitted file is immune to trailing blank removals or additions
V`20
Xbecause there are none.
X
X
X3.4 Escaped Characters
X
XProbably the biggest problem is that a mail message moving through many`20
Xdifferent systems on route to the destination may undergo character`20
Xconversions (for example - ASCII to EBCDIC if moving from VAX to an IBM).`20
XUnfortunately, not all systems keep similar translation tables and character
Vs`20
Xcan get translated into something unexpected at the remote end. Culprits are
V`20
Xcaret (`5E), tilde (`7E), square and curly brackets ( `5B `5D `7B `7D ) and
V a few others.
X
XVMS_SHARE deals with this problem by replacing each of the troublesome`20
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`20
Xtranslated back to the original character.  Obviously, to work correctly, th
Ve`20
Xescape sequence itself must be immune from translation problems.`20
X
XThe escape technique used is to replace each character by a string of the fo
Vrm
X`60xx   where the `60 symbol flags the start of an escape sequence and 'xx'
V is a
X2-digit string which is the hexadecimal form of the ASCII code for the
Xcharacter. Naturally, the `60 character itself must be escaped in this form
V to
Xavoid confusion. For example, a space would be replaced by  `6020   and a ta
Vb
Xby  `6009.`20
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,`20
Xdetection of damage (BUT NOT REPAIR!) should be possible because each file i
Vs`20
Xchecked for accuracy using a checksum once it has been unpacked.
X
XVMS_SHARE uses the currently undocumented CHECKSUM command to produce a`20
Xchecksum value for the source file. This checksum is carried across in the`2
V0
Xpacked share file and checked when the file is restored. A failed match caus
Ves`20
Xa message and the receiver can take action to try to locate and repair the`2
V0
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`20
Xthat it will run on any VMS system.  A specific program would be faster of`2
V0
Xcourse but then portability is not guaranteed.
X
XThe DCL part of the software is used merely to pick up parameters and parse`
V20
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,`20
Xescaping characters and generating multiple parts.
X
XAs distributed, the DCL and TPU code are bundled into a single large procedu
Vre`20
Xbut there is no reason why the TPU code could not be extracted and made into
V a`20
Xsection file for enhanced speed. The modifications required are quite`20
Xstraightforward.
X
X
X
X
X
X5. USING VMS_SHARE
X
XAs distributed, VMS_SHARE is run as a command procedure (usually via a`20
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`20
Xpackaged, and 'sharefile' is the name to be given to the packaged files (the
V`20
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
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`20
Xnumber of parts, from 1 up to 'n'.  All parts should be concatenated togethe
Vr`20
Xin order. It is NOT necessary to remove superfluous mail headers from any pa
Vrt`20
Xother than part 1 prior to concatenation.
X
XThe resulting combined file should then be executed as a command procedure i
Vn`20
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`20
Xthe above example) be carefully checked before execution. It is possible tha
Vt`20
Xunscrupulous persons might tamper with the source before sending it and`20
Xintroduce a virus into the VMS_SHARe'd code. There is nothing that VMS_SHARE
V`20
Xcan do about this automatically. However, since all the files should be huma
Vn`20
Xreadable it should be possible to detect fraudulent code by manual checking.
XCertainly the lines starting with '$' symbols, and the TPU code near the
Xstart, should be checked carefully as these are most likely to be troublesom
Ve.
X
X
X
X
X7. DECLARATION AND DISCLAIMER
X
XThis software is in the public domain and may be freely distributed without`
V20
Xcharge as required. However, all copyright notices and references to the
Xauthor in the source must be left intact.`20
X
XThird party modifications may be made to the source but any errors arising`2
V0
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.`20
X
X
X
XAndy Harper
XKings College London UK
$ CALL UNPACK [.VMS_SHARE]VMS_SHARE.TECHNICAL_INFO;1 1879223163
$ create 'f'
X
X
X    `09`09         V M S _ S H A R E
X
X    `09`09 A guide to use for the general user
X
X    `09`09`09        By
X
X    `09`09`09    Andy Harper
X    `09`09`09Kings College London
X
X__________________________________________________________________________
X
X
X    `09`09`09  C O N T E N T S
X
X
X    `09`091.`09INTRODUCTION
X
X    `09`092.`09OVERVIEW
X
X    `09`093.`09USING VMS_SHARE
X    `09`09`093.1 Input File specification
X    `09`09`093.2 Output File specification
X    `09`09`093.3 Examples
X    `09`09`093.4 Restrictions on files
X
X    `09`094.`09USING PAKMAIL
X    `09`09`094.1 User specification
X    `09`09`094.2 File specification
X    `09`09`094.3 Part specification
X    `09`09`094.4 Comment specification
X
X    `09`095.`09CONTROLLING OPERATION WITH LOGICAL NAMES
X    `09`09`095.1 Exclusion by directory
X    `09`09`095.2 Exclusion by name
X    `09`09`095.3 Exclusion by type
X    `09`09`095.4 Logging
X    `09`09`095.5 Setting the size of a part
X    `09`09`095.6 Inclusion of user's real name
X    `09`09`095.7 Location of temporary files
X    `09`09`095.8 Verification
X
X    `09`096.`09HOW TO UNPACK A SHARE FILE
X    `09`09`096.1 Command file
X    `09`09`096.2 Dealing with multiple part share files
X
X
X    `09`097.`09REFERENCES:
X
X    `09`09`09`5B1`5D VMS_SHARE Technical Information supplement
X    `09`09`09`5B2`5D VMS_SHARE Release notes
X    `09`09`09`5B3`5D On-line HELP
X
X
X_________________________________________________________________________
X
XVersion 7.2-007`09`09`09`09`09     `09`0922 FEB 1990
XRevision 2
X`0C
X1.`09INTRODUCTION
X
XWith the advent of worldwide computer networks and electronic mail systems,
V it
Xbecomes possible to use these as a means of distributing software packages.
XThis has the advantage of providing a quick, cheap and relatively reliable
Xmeans of getting them to the end user.`20
X
XUnfortunately, mail systems are not necessarily 100 % reliable!  In many`20
Xcases, they are fussy about the format of the information they will accept a
Vnd`20
Xmay corrupt information if the format strays outside certain boundary
Xconditions.`20
X
XThe VMS_SHARE package is designed to allow complete software packages to be`
V20
Xsent without worrying about these limitations. It has a knowledge of a wide`
V20
Xrange of limitations and encodes the information into a form that is more`20
Xacceptable to the network mail systems.
X
XThis document describes how to use the components of the system; in`20
Xparticular, the VMS_SHARE utility itself and the PAKMAIL utility for mailing
V`20
Xthe output to one or more recipients. Also described is the mechanism for`20
Xrecombining the parts and recreating the original input files.
X
XThe release notes for the package describe new features and general changes`
V20
Xfrom previous releases `5BReference 2`5D.
X
X
X2.`09OVERVIEW
X
XThere are two basic components to the VMS_SHARE package. The first is the`20
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
Xrecipient's 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.`20
X
XVMS_SHARE encodes the information to cope with different types of potential`
V20
Xcorruption, such as line wrapping/truncation, character code conversions,`20
Xtrailing blank removal etc.  Full details can be found in the technical guid
Ve`20
X`5BReference 1`5D.
X
XThe second utility is PAKMAIL. This gathers the generated pieces of the shar
Ve`20
Xfile and mails them to one or more recipients across the electronic mail`20
Xnetwork using the VMS MAIL utility.
X
X
X`0C
X3.`09USING VMS_SHARE
X
XVMS_SHARE is usually made available via a global symbol, so the command for
Xactivating it is:`20
X
X     $ VMS_SHARE <input> <output>
X
Xwhere  <input> is an input file specification (see below) and <output> is th
Ve`20
Xname to be given to the output 'share' file (see below). If a parameter is n
Vot`20
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`20
Xfilenames, which may include wildcards anywhere. For example:
X
X     TEST
X    `09The specific file   "TEST."
X
X     *.FOR
X        All files ending in ".FOR"
X
X     `5B...`5D*.*;*
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`20
Xreason and the fact that no useful information is contained within them,`20
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`20
Xof the share file.  The name supplied here is suffixed by a 'part number' fr
Vom`20
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 `5B...`5D*.*;* 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".`
V20
X         This would generate files called "ARCHIVE.SET_1", "ARCHIVE.SET_2"
X         etc.
X
X
X     $ VMS_SHARE `5B.DOC`5D*.*,`5B.EXE`5D*.*,`5B.SRC`5D*.*  VI
X        Archive all files in the three directories `5B.DOC`5D, `5B.EXE`5D an
Vd `5B.SRC`5D
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`2
V0
Xdirectories, only files within or below the current directory may be used as
V`20
Xinput.  The tree structure is preserved, from the current directory downward
Vs,`20
Xand will be recreated below the recipient's current directory at unpacking`2
V0
Xtime.
X
XFor example, if we archived the files "`5B.SRC...`5D*.*;*" the recipient wou
Vld`20
Xfind an exact copy of the `5B.SRC...`5D tree recreated below his current`20
Xdirectory.
X
X
X`0C
X4.`09USING PAKMAIL
X
XOnce the share file parts have been created, they can be transmitted over th
Ve`20
Xelectronic mail network to one or more recipients using the VMS MAIL utility
V.`20
XPAKMAIL is a utility to simplify the sending mechanism by providing a single
V`20
Xline command to send the complete package. Typically, PAKMAIL is made`20
Xavailable via a 'foreign command' so the command is:
X
X     $ PAKMAIL recipient file parts `5Bcomment`5D
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`20
Xbe sent the package. This can take any form of mail address acceptable to th
Ve`20
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`20
Xdistribution lists requires an @ symbol to precede a file specification whic
Vh`20
Xcontains the recipient names. Used directly, DCL intercepts the @ before mai
Vl`20
Xdoes, and so the command does not work correctly. To avoid this, define a`20
Xlogical name to point at the distribution list and specify the logical name
V as`20
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`20
Xthe way DCL/MAIL parse quoted strings. Typically, this is important when`20
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`2
V0
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`20
Xthe share file template name - omitting the part numbers. For example, a`20
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`20
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`2
V0
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`20
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`0C
X5.`09CONTROLLING OPERATION WITH LOGICAL NAMES
X
XVMS_SHARE will operate satisfactorily with all of its default settings.`20
XHowever a number of options are available to tailor its operations to local`
V20
Xrequirements. Each of these options is controlled through a logical name`20
Xdefinition of the form "SHARE_xxxx"  where xxxx is the particular option in`
V20
Xquestion.
X
XOptions are available to exlude files on the basis of directory, name or typ
Ve;`20
Xto log or not log certain informational messages; to determine the maximum`2
V0
Xsize of each part; to force inclusion of an identifying string into the shar
Ve`20
Xfile; to specify the location of temporary files, and to verify operation of
V`20
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.`20
X
XFor example,
X
X   $ define share_exclude_dirs "`5BJIM.EXE`5D,`5BJIM.OBJ`5D"
X
XAny files in these two directories will be excluded. Note that the directory
V`20
Xname MUST be given in full.
X
XIf the logical name is not defined, then files are not excluded on the basis
V`20
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.`20
X
XFor example,
X
X   $ define share_exclude_names "TEST,DUMMY"
X
XAny files with either of the two names will be excluded.`20
X
XIf the logical name is not defined, then files are not excluded on the basis
V`20
Xof their file name.
X
X
X5.3 Exclusion by type
X
XIf the logical name  SHARE_EXCLUDE_TYPES is defined with a comma-separated l
Vist
Xof non-wildcarded file types, then any file which has a similar file type
Xspecification will be excluded from the share file.`20
X
XFor example,
X
X   $ define share_exclude_types ".EXE,.DIR,.OBJ"
X
XAny files with these file types will be excluded. Files with a type of .DIR`
V20
Xare always excluded regardless.
X
XIf the logical name is not defined, then files are not excluded on the basis
V`20
Xof their file type, except that .DIR files are always excluded.
X
X
X
X5.4 Logging
X
XInformational messages are normally sent to SYS$OUTPUT by default. The logic
Val`20
Xname SHARE_LOG can be defined with a TRUE or FALSE value to determine whethe
Vr`20
Xsuch messages are produced.  If undefined, a TRUE value is assumed.
X
XFor example:
X
X   $ define SHARE_LOG FALSE
X
Xwill turn off informational messages.
X
XNot all messages can be turned off. In particular, error messages are always
V`20
Xproduced on SYS$ERROR.
X
X
X
X5.5 Setting the size of a part
X
XEach part of the share file is limited to a maximum size of 30 blocks by`20
Xdefault. VMS_SHARE will split at a point just below this in general (never`2
+-+-+-+-+-+-+-+-  END  OF PART 4 +-+-+-+-+-+-+-+-
