🚀 go-pugleaf

Submitted-by: "Andy, Systems Manager" <UDAA055@ELM.CC.KCL.AC.UK>
Posting-number: Volume 4, Issue 51
Archive-name: vms_share/part07
Supersedes: vms_share: Volume 3, Issue 87-89

-+-+-+-+-+-+-+-+ START OF PART 7 -+-+-+-+-+-+-+-+
Vtion`20of`20data`20in`20
Xtransit.`20`20For`20example,`20line`20wrapping,`20case`20folding,`20transposit
Vion`20of`20key`20
Xcharacters`20etc.
X
XVMS_SHARE`20encodes`20files`20before`20transmission`20so`20that`20these`20thin
Vgs`20may`20be`20kept`20
Xunder`20control`20and`20proper`20restoral`20effected`20at`20the`20receiving
V`20end.
X
XFor`20a`20given`20series`20of`20files`20to`20be`20packaged,`20VMS_SHARE`20comb
Vines`20them`20into`20a`20
Xsingle`20large`20'text`20archive'`20file`20that`20can`20be`20unpacked`20into
V`20its`20component`20files`20
Xsimply`20by`20running`20it`20as`20a`20command`20procedure`20at`20the`20receivi
Vng`20end.`20For`20
Xconvenience,`20VMS_SHARE`20will`20optionally`20split`20the`20result`20into`20m
Vultiple`20parts`20
Xthat`20can`20be`20individually`20mailed`20and`20recombined`20at`20the`20receiv
Ving`20end.
X
X
X
X2.`20WHAT`20VMS_SHARE`20DOES`20NOT`20DO
X
XBecause`20VMS_SHARE`20relies`20on`20electronic`20mail`20to`20ship`20the`20file
Vs,`20there`20are`20no`20
Xprotocols`20that`20can`20be`20used`20to`20check`20the`20accuracy`20of`20the
V`20received`20file(s).`20
XThere`20is`20a`20reliance`20on`20the`20underlying`20mail`20system`20to`20get
V`20everything`20there`20in`20
Xone`20piece`20and`20unchanged.`20`20VMS_SHARE`20is`20unable`20to`20ask`20for
V`20retransmission`20of`20
Xmissing`20or`20damaged`20pieces.
X
XVMS_SHARE`20should`20therefore`20be`20used`20to`20send`20files`20only`20via
V`20essentially`20reliable`20
Xmail`20systems`20which`20can`20get`20files,`20whose`20characters`20fall`20with
Vin`20certain`20bounds,`20
Xthere`20intact.
X
XVMS_SHARE`20is`20intended`20for`20sequential`20files`20only.`20Other`20file
V`20formats`20can`20be
Xpackaged`20into`20a`20backup`20saveset,`20whose`20file`20format`20is`20support
Ved`20by`20VMS_SHARE
X
X
X
X3.`20LIMITATIONS`20OF`20MAILERS`20AND`20HOW`20VMS_SHARE`20GETS`20AROUND`20THEM
V
X
XVarious`20mail`20systems`20have`20different`20limitations`20within`20them.`20F
Vor`20instance,`20
Xthey`20will`20wrap`20or`20truncate`20lines`20that`20are`20too`20long,`20they
V`20may`20limit`20the`20size`20of`20
Xan`20individual`20mail`20message,`20they`20may`20transpose`20characters`20inco
Vrrectly`20if`20the`20
Xunderlying`20character`20set`20is`20different`20from`20the`20transmitter`20(AS
VCII/EBCDIC`20is`20a
Xgood`20example`20of`20this).`20
X
XVMS_SHARE`20encodes`20the`20files`20in`20different`20ways`20to`20get`20around
V`20the`20problems.
XPlease`20note`20however,`20that`20the`20encoding`20techniques`20are`20NOT`20fo
Volproof.`20We`20have
Xmerely`20tried`20to`20anticipate`20all`20possible`20corruptions`20and`20devise
V`20an`20encoding
Xscheme`20which`20ensures`20that`20the`20conditions`20under`20which`20corruptio
Vn`20occurs`20does`20not
Xarise.`20If`20a`20form`20of`20corruption`20that`20has`20not`20been`20anticipat
Ved`20occurs,`20corruption
Xto`20the`20transmitted`20files`20will`20be`20irreparable`20except`20through
V`20manual`20editing.`20
X
X
X
X3.1`20Maximum`20Size`20of`20a`20Mail`20Message
X
XMany`20mail`20systems`20cannot`20cope`20with`20single`20mail`20messages`20larg
Ver`20than`20a`20fixed`20
Xnumber`20of`20bytes`20and`20will`20truncate`20messages`20or`20maybe`20even`20f
Vail`20to`20deliver`20them`20
Xaltogether.
X
XThis`20is`20a`20real`20problem`20if`20a`20large`20software`20package`20is`20be
Ving`20sent.`20`20VMS_SHARE`20
Xtries`20to`20overcome`20this`20by`20splitting`20the`20packaged`20files`20into
V`20several`20parts,`20
Xeach`20part`20being`20smaller`20than`20some`20fixed`20size.`20By`20default,
V`20a`20part`20size`20of`2030
Xblocks`20is`20chosen;`20this`20can`20be`20overriden`20by`20defining`20a`20logi
Vcal`20name
X(SHARE_PART_SIZE)`20or`20by`20a`20qualifier`20on`20the`20command`20line`20(/PA
VRT_SIZE=nn).`20For
Xexample,`20we`20might`20send`20a`20`20total`20of`20300`20blocks`20of`20code
V`20as`2010`20parts`20each`20of`2030
Xblocks`20or`20less.`20VMS_SHARE`20`20will`20automatically`20split`20at`20the
V`2030`20block`20boundary.
X
XIt`20should`20be`20noted`20that`20mail`20headers`20added`20on`20route`20can
V`20account`20for`20several
Xblocks`20worth`20of`20extra`20space`20so`20this`20should`20be`20realised`20whe
Vn`20setting`20the
Xmaximum`20part`20size.
X
X
X
X
X3.2`20Maximum`20Line`20Length
X
XMany`20mail`20systems`20do`20not`20like`20lines`20longer`20than`20some`20fixed
V`20maximum`20length,`20a`20
Xmaximum`20length`20of`2080`20characters`20is`20typical.`20This`20results`20in
V`20longer`20lines`20being
Xwrapped`20or`20truncated`20at`20seemingly`20arbitrary`20positions.`20
X
XVMS_SHARE`20tries`20to`20cope`20with`20this`20by`20wrapping`20long`20lines`20i
Vtself`20and`20inserting`20
Xmarkers`20to`20allow`20them`20to`20be`20rejoined`20at`20the`20receiving`20end.
V`20What`20VMS_SHARE`20does`20
Xis`20to`20prefix`20each`20line`20with`20a`20flag`20character.`20This`20flag
V`20character`20says`20EITHER`20
X'this`20is`20the`20first`20part`20of`20a`20line'`20OR`20'this`20line`20is`20a
V`20continuation`20of`20the`20
Xprevious`20line'.
X
XThe`20maximum`20line`20size`20is`20configured`20into`20the`20code`20as`20a`20g
Vlobal`20value`20and`20`20can`20be
Xeasily`20changed`20if`20required.`20It`20is`20not`20intended`20that`20this`20v
Value`20should`20`20be
Xaltered`20by`20the`20average`20user`20however.
X
X
X
X
X3.3`20Trailing`20Blanks
X
XSome`20mailers`20interfere`20with`20blanks`20at`20the`20start`20and`20end`20of
V`20lines.`20VMS_SHARE
Xencodes`20blanks`20(and`20tabs)`20as`20if`20they`20were`20troublesome`20charac
Vters`20(see`20below)
Xto`20get`20around`20this.`20During`20unpacking`20of`20an`20encoded`20file,`20a
Vny`20blank`20characters
Xare`20ignored.
X
X
X
X
X3.4`20Escaped`20Characters
X
XUndoubtedly`20the`20biggest`20problem`20is`20that`20a`20mail`20message`20movin
Vg`20through`20many`20
Xdifferent`20systems`20on`20route`20to`20the`20destination`20may`20undergo`20ch
Varacter`20
Xconversions`20(for`20example`20-`20ASCII`20to`20EBCDIC`20if`20moving`20from
V`20VAX`20to`20an`20IBM).`20
XUnfortunately,`20not`20all`20systems`20keep`20similar`20translation`20tables
V`20and`20characters`20
Xcan`20get`20translated`20into`20something`20unexpected`20at`20the`20remote`20e
Vnd.`20Culprits`20are`20
Xcaret`20(`5E),`20tilde`20(`7E),`20square`20and`20curly`20brackets`20(`20`5B
V`20`5D`20`7B`20`7D`20)`20and`20a`20few`20others.
X
XVMS_SHARE`20deals`20with`20this`20problem`20by`20replacing`20each`20of`20the
V`20troublesome`20
Xcharacters`20-`20the`20ones`20mentioned`20above`20plus`20any`20non-printing
V`20character`20-`20by`20an
Xescape`20sequence.`20The`20escape`20sequence`20is`20recognized`20at`20the`20re
Vceiving`20end`20and`20is`20
Xtranslated`20back`20to`20the`20original`20character.`20`20Obviously,`20to`20wo
Vrk`20correctly,`20the`20
Xescape`20sequence`20itself`20must`20be`20immune`20from`20translation`20problem
Vs.`20
X
XThe`20escape`20technique`20used`20is`20to`20replace`20each`20character`20by
V`20a`20string`20of`20the`20form
X`60xx`20`20`20where`20the`20`60`20symbol`20flags`20the`20start`20of`20an`20esc
Vape`20sequence`20and`20'xx'`20is`20a
X2-digit`20string`20which`20is`20the`20hexadecimal`20form`20of`20the`20ASCII
V`20code`20for`20the
Xcharacter.`20Naturally,`20the`20`60`20character`20itself`20must`20be`20escaped
V`20in`20this`20form`20to
Xavoid`20confusion.`20For`20example,`20a`20space`20would`20be`20replaced`20by
V`20`20`6020`20`20`20and`20a`20tab
Xby`20`20`6009.`20
X
X
X
X3.5`20Additional`20Compression`20Techniques
X
XTwo`20additional`20forms`20of`20character`20encoding`20can`20be`20optionally
V`20selected`20by`20the
Xuser`20to`20reduce`20the`20size`20of`20the`20packaged`20data`20-`20either`20ru
Vn-length`20encoding`20or`20a
Xmodified`20form`20of`20Lempel-Ziv`20compression.
X
XA`20file`20compressed`20with`20one`20of`20these`20options`20will`20be`20automa
Vtically`20decompressed
Xwhen`20unpacked.`20It`20is`20not`20necessary`20for`20the`20recipient`20to`20us
Ve`20external
Xdecompression`20tools.
X
X
X3.5.1`20Run-Length`20Encoding
X
XA`20form`20of`20run`20length`20encoding`20is`20used`20to`20encode`20sequences
V`20of`20the`20same`20character
Xinto`20a`205`20character`20sequence.`20In`20this`20instance,`20the`20generated
V`20sequence`20is:
X
X`20`20`20`26nnXX
X
Xwhere`20`26`20is`20the`20run`20length`20sequence`20flag,`20nn`20is`20the`20cou
Vnt`20(in`20hex)`20of
Xcharacters,`20and`20ZZ`20is`20the`20hex`20code`20of`20the`20ascii`20character.
V`20`20For`20example,`20a`20run
Xof`2015`20spaces`20would`20be`20replaced`20by`20`20`260F20`20(`600F'`20=`2015,
V`20`6020'`20=`20hex`20code`20for
Xspace).
X
XThe`20use`20of`20run`20length`20encoding`20dramatically`20increases`20the`20ti
Vme`20spent`20on
Xencoding`20the`20files.`20In`20many`20cases,`20it`20will`20be`20of`20no`20bene
Vfit.`20Because`20of`20this`20it
Xis`20not`20active`20by`20default.
X
X
X3.5.2`20Lempel-Ziv`20Compression
X
XThe`20Lempel-Ziv`20algorithm`20scans`20for`20common`20substrings`20in`20a`20fi
Vle`20and`20replaces
Xthem`20by`20a`20pointer`20back`20to`20a`20previous`20occurrence`20within`20the
V`20file.`20For`20this
Ximplementation,`20a`20number`20of`20changes`20have`20been`20made`20to`20the
V`20basic`20idea`20to`20fit`20the
Xrestrictions`20of`20the`20TPU`20utility,`20and`20the`20line`20wrapping`20and
V`20quoting`20schemes`20used
Xfor`20long`20lines`20and`20non-printable`20characters.
X
XThe`20file`20is`20scanned`20for`20the`20longest`20previously`20occurring`20sub
Vstring`20and`20is
Xreplaced`20by`20an`20escape`20sequence`20of`20the`20form:
X
X`20`20`20`5Cbbll
X
Xwhere`20`5C`20is`20the`20flag`20to`20indicate`20an`20lz`20encoded`20string,
V`20bb`20is`20a`202`20digit`20hex
Xencoded`20backwards`20count`20to`20the`20start`20of`20the`20original`20string,
V`20and`20ll`20is`20a`20two
Xdigit`20hex`20encoded`20length.`20Because`20of`20the`202`20digit`20hex`20encod
Ving,`20the`20maximum
Xbackwards`20search`20distance`20is`20255`20bytes`20and`20the`20maximum`20lengt
Vh`20is`20also`20255
Xbytes.`20Therefore`20up`20to`20255`20bytes`20can`20be`20compressed`20to`20a
V`205`20char`20sequence`20in`20the
Xoptimal`20case.`20In`20practice,`20compression`20ratios`20are`20nothing`20like
V`20as`20dramatic.
X
XThis`20form`20of`20compression`20is`20very`20slow`20in`20operation`20due`20to
V`20the`20repeated
Xsearching`20for`20substrings`20that`20have`20previously`20occurred.`20Some`20o
Vptimisations`20have
Xbeen`20made`20to`20the`20searching`20but`20it`20should`20still`20be`20selected
V`20only`20if`20it`20is
Xcertain`20to`20be`20of`20some`20benefit.
X
X
X
X3.6`20Detecting`20Damaged`20Files`20with`20Checksums
X
XIn`20cases`20where`20some`20corruption`20occurs`20despite`20the`20encodings
V`20used`20by`20VMS_SHARE,`20
Xdetection`20of`20damage`20(BUT`20NOT`20REPAIR!)`20should`20be`20possible`20bec
Vause`20each`20file`20is`20
Xchecked`20for`20accuracy`20using`20a`20checksum`20once`20it`20has`20been`20unp
Vacked.
X
XVMS_SHARE`20uses`20the`20currently`20undocumented`20CHECKSUM`20command`20to
V`20produce`20a`20
Xchecksum`20value`20for`20the`20source`20file.`20This`20checksum`20is`20carried
V`20across`20in`20the`20
Xpacked`20share`20file`20and`20checked`20when`20the`20file`20is`20restored.`20A
V`20failed`20match`20causes`20
Xa`20message`20and`20the`20receiver`20can`20take`20action`20to`20try`20to`20loc
Vate`20and`20repair`20the`20
Xdamage.
X
XThe`20DCL`20command:
X
X`20`20`20`20`20$`20CHECKSUM`20filename
X
Xwrites`20the`20checksum`20value`20into`20a`20DCL`20symbol`20called`20CHECKSUM$
VCHECKSUM.
X
XThe`20CHECKSUM`20command`20does`20not`20work`20with`20files`20that`20have`20ce
Vrtain`20types`20of
Xrecords`20(specifically,`20those`20with`20an`20MRS`20value`20of`200`20and`20re
Vcords`20exceeding`202048
Xbytes).`20Therefore,`20VMS_SHARE`20cannot`20verify`20such`20files.`20A`20warni
Vng`20message`20is
Xissued`20at`20both`20the`20packing`20and`20unpacking`20stages`20that`20the`20f
Vile`20will`20not/has`20not
Xbeen`20verified.`20It`20is`20then`20up`20to`20the`20user`20to`20take`20appropr
Viate`20action`20to`20verify
Xthe`20files.
X
X
X4.`20VMS_SHARE`20IMPLEMENTATION
X
XVMS_SHARE`20is`20provided`20as`20a`20combination`20of`20DCL`20and`20TPU`20code
V`20in`20order`20to`20ensure`20
Xthat`20it`20will`20run`20on`20any`20VMS`20system.`20`20A`20specific`20program
V`20would`20be`20faster`20of`20
Xcourse`20but`20then`20portability`20is`20not`20guaranteed.
X
XThe`20DCL`20part`20of`20the`20software`20is`20used`20merely`20to`20pick`20up
V`20parameters`20and
Xqualifiers,`20and`20parse`20filenames,`20passing`20them`20to`20the`20TPU`20cod
Ve`20in`20a`20scratch
Xfile.
X
XThe`20TPU`20code`20does`20the`20hard`20work`20of`20packaging`20the`20files,
V`20wrapping`20lines,`20
Xescaping`20characters,`20compressing`20if`20requested,`20`20and`20generating
V`20multiple`20parts.
X
XAs`20distributed,`20the`20DCL`20and`20TPU`20code`20are`20bundled`20into`20a
V`20single`20large`20procedure`20
Xbut`20there`20is`20no`20reason`20why`20the`20TPU`20code`20could`20not`20be`20e
Vxtracted`20and`20made`20into`20a`20
Xsection`20file`20for`20enhanced`20speed.`20The`20modifications`20required`20ar
Ve`20quite`20
Xstraightforward.
X
X
X4.1`20Long`20Lines
X
XBecause`20the`20code`20is`20based`20upon`20TPU,`20some`20limitations`20are`20i
Vmposed`20upon
XVMS_SHARE.`20In`20particular,`20early`20versions`20of`20TPU`20(pre-5.4)`20do
V`20not`20allow`20records
Xlonger`20than`20960`20bytes`20so`20it`20is`20impossible`20to`20package`20them.
V`20Versions`20of`20TPU`20at
XVMS`205.4`20and`20beyond`20allow`20records`20up`20to`2065535`20bytes,`20so`20t
Vhe`20problem`20virtually
Xdisappears.`20For`20compatibility,`20VMS_SHARE`20still`20uses`20the`20old`20re
Vcord`20length
Xunless`20requested`20by`20the`20user`20with`20the`20/LONGLINES`20qualifier.
V`20Use`20of`20this
Xrequires`20a`20minimum`20VMS`20of`205.4`20and`20the`20generated`20share`20file
V`20will`20only`20unpack`20on
X5.4`20or`20greater.
X
XTPU`20file`20handling`20is`20limited.`20Files`20can`20only`20be`20written`20wi
Vth`20variable`20length
Xrecords`20and`20CR`20carriage`20control.`20To`20allow`20other`20formats`20to
V`20be`20packaged,
XVMS_SHARE`20encodes`20selected`20file`20record`20attributes`20into`20the`20sha
Vre`20file`20and`20uses
Xthe`20CONVERT`20utility`20to`20restore`20those`20attributes`20during`20the`20u
Vnpacking`20phase.`20In
Xprinciple,`20this`20allows`20VMS_SHARE`20to`20package`20files`20of`20most`20ty
Vpes,`20including
X.EXE,`20.OBJ`20and`20.BCK`20files.`20In`20the`20case`20of`20.BCK`20files,`20th
Vis`20is`20subject`20to`20the
XBACKUP`20block`20length`20being`20compatible`20with`20the`20maximum`20record
V`20length`20selected`20by
Xthe`20user`20(960`20or`2065535`20as`20appropriate).`20Allowing`20BACKUP`20save
Vsets`20to`20be`20packaged
Xallows`20files`20of`20all`20other`20types`20to`20be`20packaged,`20provided`20t
Vhey`20are`20first`20stored
Xin`20a`20saveset.`20BACKUP`20requires`20a`20minimum`20block`20length`20of`2020
V48`20bytes,`20so`20the`20long
Xline`20support`20is`20a`20pre-requisite`20for`20this.
X
X
X4.2`20Part`20Size`20Determination
X
XThe`20size`20of`20a`20part`20is`20conceptually`20simple.`20Find`20the`20size
V`20of`20a`20buffer`20in`20bytes
Xand`20divide`20by`20512`20to`20get`20the`20number`20of`20blocks`20it`20will
V`20occupy.`20However,`20this`20is
Xcomplicated`20by`20several`20things.
X
XFirst,`20TPU`20does`20not`20count`20line`20ends`20when`20returning`20the`20
V`60LENGTH'`20of`20a`20buffer.
XSecond,`20when`20a`20buffer`20is`20written`20to`20disk,`20there`20is`20a`202
V`20byte`20overhead`20on`20each
Xrecord`20giving`20the`20length`20of`20the`20record.`20Finally,`20within`20a
V`20disk`20block,`20a`20record
Xalways`20starts`20on`20a`20word`20boundary`20so`20that`20some`20records`20may
V`20be`20padded`20with`20an
Xadditional`20null`20byte.
X
XTo`20accurately`20determine`20how`20much`20disk`20space`20a`20buffer`20would
V`20occupy`20would`20involve
Xsome`20complex`20computations.`20However,`20since`20we`20know`20that`20each
V`20record`20has`20either`20a
X2`20byte`20or`20a`203`20byte`20overhead`20we`20can`20get`20a`20reasonably`20ac
Vcurate`20approximation`20by
Xtaking`20the`20LENGTH`20of`20the`20buffer`20and`20adding`203`20bytes`20for`20e
Vach`20record.`20We`20use`203
Xbytes`20to`20allow`20for`20the`20worst`20case`20and`20ensure`20that`20the`20pa
Vrt,`20when`20written`20to
Xdisk,`20never`20exceeds`20the`20specified`20part`20size.`20In`20practice,`20th
Vis`20means`20that`20parts
Xwill`20sometimes`20be`20less`20than`20the`20part`20size`20-`20the`20discrepanc
Vy`20grows`20as`20the`20part
Xsize`20is`20increased.
X
X
X
X5.`20USING`20VMS_SHARE
X
XAs`20distributed,`20VMS_SHARE`20is`20run`20as`20a`20command`20procedure`20(usu
Vally`20via`20a`20
Xsuitable`20symbol`20set`20up`20to`20point`20to`20it)`20thus:-
X
X`20`20`20`20`20$`20@VMS_SHARE`20filespecs`20sharefile
X
Xwhere`20'filespecs'`20is`20a`20comma`20separated`20list`20of`20wildcarded`20fi
Vlenames`20to`20be`20
Xpackaged,`20and`20'sharefile'`20is`20the`20name`20to`20be`20given`20to`20the
V`20packaged`20files.`20Each
Xpart`20of`20the`20sharefile`20will`20be`20suffixed`20by`20a`20part`20number
V`20in`20the`20form:
X
X`20`20`20`20nnn-OF-mmm
X
Xwhere`20nnn`20is`20the`20part`20number`20and`20mmm`20is`20the`20total`20number
V`20of`20parts.
X
XThere`20are`20some`20restrictions`20on`20the`20filenames`20that`20can`20be`20u
Vsed:
X
X`20`20`20`20`20-`20Subdirectories`20may`20be`20used`20provided`20that`20they
V`20are`20beneath`20the`20current
X`20`20`20`20`20`20`20directory.`20It`20is`20not`20permitted`20to`20package`20f
Viles`20in`20other`20directories.
X
X`20`20`20`20`20-`20The`20name`20of`20the`20sharefile`20must`20not`20appear`20i
Vn`20the`20'filespecs'`20list
X`20`20`20`20`20`20`20because`20the`20software`20cannot`20package`20a`20file
V`20into`20itself.
X
X`20`20`20`20`20-`20At`20least`20one`20valid`20file`20must`20be`20given`20in
V`20'filespecs'`20or`20no`20sharefile
X`20`20`20`20`20`20`20will`20be`20produced.
X
X
X6.`20UNPACKING`20A`20VMS_SHARE`20FILE
X
XIn`20general,`20a`20package`20delivered`20using`20the`20VMS_SHARE`20software
V`20will`20arrive`20in`20a`20
Xnumber`20of`20parts,`20from`201`20up`20to`20'n'.`20`20All`20parts`20should`20b
Ve`20concatenated`20together`20
Xin`20order.`20It`20is`20NOT`20necessary`20to`20remove`20superfluous`20mail`20h
Veaders`20from`20any`20part`20
Xother`20than`20part`201`20prior`20to`20concatenation.
X
XThe`20resulting`20combined`20file`20should`20then`20be`20executed`20as`20a`20c
Vommand`20procedure`20in`20
Xorder`20to`20unpack`20the`20resulting`20files.
X
X
X
X6.1`20Typical`20Unpack`20Sequence
X
XA`20typical`20sequence`20of`20events`20goes`20like`20this:
X
X`20-`20Set`20your`20default`20directory`20to`20a`20scratch`20directory`20which
V`20is`20empty.
X
X`20-`20Go`20into`20MAIL`20and`20select`20the`20folder`20which`20contains`20the
V`20parts`20of`20the
X`20`20`20package.
X
X`20-`20Extract`20part`201`20into`20a`20file,`20using`20the`20command`20'EXTRAC
VT/NOHEADER`20`20`20`20`20`20`20`20file'
X`20`20`20Extract`20part`202`20into`20a`20file,`20using`20the`20command`20'EXTR
VACT/NOHEADER/APPEND`20file'
X`20`20`20...
X`20`20`20...
X`20`20`20Extract`20part`20n`20into`20a`20file,`20using`20the`20command`20'EXTR
VACT/NOHEADER/APPEND`20file'
X
X`20-`20Read`20warning`20below`20BEFORE`20proceeding!!!
X
X`20-`20Execute`20as`20a`20command`20procedure,`20using`20the`20following`20com
Vmand:
X`20`20`20`20`20`20$`20@file
X
X
X
X6.2`20Warning
X
XIt`20is`20strongly`20suggested`20that`20the`20generated`20command`20procedure
V`20('file.SHAR'`20in`20
Xthe`20above`20example)`20be`20carefully`20checked`20before`20execution.`20It
V`20is`20possible`20that`20
Xunscrupulous`20persons`20might`20tamper`20with`20the`20source`20before`20sendi
Vng`20it`20and`20
Xintroduce`20a`20virus`20into`20the`20VMS_SHARe'd`20code.`20There`20is`20nothin
Vg`20that`20VMS_SHARE`20
Xcan`20do`20about`20this`20automatically.`20However,`20since`20all`20the`20file
Vs`20should`20be`20human`20
Xreadable`20it`20should`20be`20possible`20to`20detect`20fraudulent`20code`20by
V`20manual`20checking.
XCertainly`20the`20lines`20starting`20with`20'$'`20symbols,`20and`20the`20TPU
V`20code`20near`20the
Xstart,`20should`20be`20checked`20carefully`20as`20these`20are`20most`20likely
V`20to`20be`20troublesome.
X
X
X
X
X7.`20DECLARATION`20AND`20DISCLAIMER
X
XThis`20software`20is`20in`20the`20public`20domain`20and`20may`20be`20freely
V`20distributed`20without`20
Xcharge`20as`20required.`20However,`20all`20copyright`20notices`20and`20referen
Vces`20to`20the
Xauthor`20in`20the`20source`20must`20be`20left`20intact.`20
X
XThird`20party`20modifications`20may`20be`20made`20to`20the`20source`20but`20an
Vy`20errors`20arising`20
Xfrom`20their`20use`20are`20entirely`20the`20responsibility`20of`20the`20modifi
Ver.
X
XThe`20author`20accepts`20no`20responsibility`20for`20the`20suitability`20of
V`20this`20software`20for
Xany`20specific`20purpose.`20Any`20errors`20arising`20from`20its`20use`20are
V`20entirely`20the
Xresponsibility`20of`20the`20user.`20
X
X
XAndy`20Harper
XKings`20College`20London`20UK
$ call unpack VMS_SHARE.TECHNICAL_INFO;22 1029234412 ""
$!
$ create 'f'
X`20`20`20`20`09`09`20`20`20`20`20`20`20`20`20V`20M`20S`20_`20S`20H`20A`20R`20E
V
X
X`20`20`20`20`09`09`20A`20guide`20to`20use`20for`20the`20general`20user
X
X`20`20`20`20`09`09`09`20`20`20`20`20`20`20`20By
X
X`20`20`20`20`09`09`09`20`20`20`20Andy`20Harper
X`20`20`20`20`09`09`09Kings`20College`20London
X
X__________________________________________________________________________
X
X
X
X`09`09`09`20`20A`20B`20S`20T`20R`20A`20C`20T
X
X
X`20`20VMS_SHARE`20is`20designed`20to`20package`20a`20series`20of`20files`20int
Vo`20a`20multi-part
X`20`20share`20file`20suitable`20for`20mailing`20across`20a`20network.`20Files
V`20are`20encoded`20to
X`20`20be`20resistant`20to`20the`20corruption`20that`20many`20mailers`20and`20n
Vetworks
X`20`20generate.`20`20When`20all`20parts`20of`20the`20share`20file`20are`20comb
Vined`20and`20run`20as`20a
X`20`20command`20procedure,`20the`20packaged`20directory`20tree`20is`20recreate
Vd`20in`20its
X`20`20original`20format.
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X`20`20This`20software`20is`20copyright`20(C)`20of`20the`20author`20and`20comes
V`20with`20no
X`20`20warranties`20either`20expressed`20or`20implied.`20`20It`20may`20be`20dis
Vtributed`20free`20of
X`20`20charge`20to`20anyone`20who`20may`20require`20a`20copy,`20provided`20that
V`20all`20copyright
X`20`20notices`20remain`20intact.`20Any`20problems`20arising`20from`20its`20use
V`20are`20entirely
X`20`20the`20responsibility`20of`20the`20user.
X
X
X`20`20Andy`20Harper
X`20`20Systems`20Manager
X`20`20Computing`20Centre
X`20`20Kings`20College`20London
X`20`20The`20Strand
X`20`20London`20WC2R`202LS
X`20`20England
X
X`20`20Tel:`20`20+44`20(0)`2071`20873`202347
X`20`20E-mail:`20`20`20UDAA055`20@`20UK.AC.KCL.CC.OAK`20(JANET)
X`20`20`20`20`20`20`20`20`20`20`20`20UDAA055%OAK.CC.KCL.AC.UK`20@`20NSFNET-RELA
VY.AC.UK`20(INTERNET)
X
X_________________________________________________________________________
X
XVersion`208.2`09`09`09`09`09`20`20`20`20`20`09`09Jan`201993
XRevision`205
X`0C
X
X
X`20`20`20`20`09`09`09`20`20C`20O`20N`20T`20E`20N`20T`20S
X
X
X`20`20`20`20`09`091.`09INTRODUCTION
X
X`20`20`20`20`09`092.`09OVERVIEW
X`09`09`092.1`20`20The`20VMS_SHARE`20Utility
X`09`09`092.2`20`20The`20PAKMAIL`20Utility
X
X`09`093.`09USING`20VMS_SHARE
X`09`09`093.1`20`20Simple`20Use
X`20`20`20`20`09`09`09`20`20`20`20`203.1.1`20`20Input`20File`20specification
X`20`20`20`20`09`09`09`20`20`20`20`203.1.2`20`20Output`20File`20specification
X`20`20`20`20`09`09`09`20`20`20`20`203.1.3`20`20Examples
X`09`09`093.2`20`20Subdirectory`20Restrictions
X`09`09`093.3`20`20File`20Type`20Restrictions
X`09`09`093.4`20`20Record`20Length`20Restrictions
X`09`09`093.5`20`20Working`20Set`20and`20Virtual`20Memory`20Requirements
X`09`09`093.6`20`20Checksum`20Validation
X
X`09`094.`09ADVANCED`20USE`20OF`20VMS_SHARE
X`09`09`094.1`20`20Selectable`20Options
X`09`09`094.2`20`20Default`20Settings
X`09`09`094.3`20`20Customization`20Through`20Logical`20Names
X`09`09`09`20`20`20`20`204.3.1`20SHARE_REAL_NAME`20--`20Owner`20Identification
X`09`09`09`20`20`20`20`204.3.2`20SHARE_TEMP`20--`20Temporary`20Files
X`09`09`09`20`20`20`20`204.3.3`20SHARE_UNPACK_TEMP`20--`20Temporary`20Files
X`09`09`09`20`20`20`20`204.3.4`20SHARE_VERIFY`20--`20Procedure`20Verification
X`09`09`094.4`20`20Customization`20Via`20Command-Line`20Qualifiers
X
X`20`20`20`20`09`095.`09USING`20PAKMAIL
X`20`20`20`20`09`09`095.1`20`20User`20specification
X`20`20`20`20`09`09`095.2`20`20File`20specification
X`20`20`20`20`09`09`095.3`20`20Part`20specification
X`09`09`095.4`20`20Partlist`20specification
X`20`20`20`20`09`09`095.5`20`20Comment`20specification
X
X`20`20`20`20`09`096.`09HOW`20TO`20UNPACK`20A`20SHARE`20FILE
X`20`20`20`20`09`09`096.1`20`20Command`20file
X`20`20`20`20`09`09`096.2`20`20Dealing`20with`20multiple`20part`20share`20files
V
X
X
X`20`20`20`20`09`097.`09REFERENCES:
X
X`20`20`20`20`09`09`09`5B1`5D`20VMS_SHARE`20Technical`20Information`20supplemen
Vt
X`20`20`20`20`09`09`09`5B2`5D`20VMS_SHARE`20Release`20notes
X`20`20`20`20`09`09`09`5B3`5D`20On-line`20HELP
X
X`09`09QUALIFIER`20REFERENCE`20SECTION
X`09`09`09/BACKUP
X`09`09`09/BEFORE
X`09`09`09/COMPRESS
X`09`09`09/CONFIRM
X`09`09`09/CREATED
X`09`09`09/DEBUG
X`09`09`09/DIRECTORY
X`09`09`09/EXCLUDE
X`09`09`09/EXPIRED
X`09`09`09/LOG
X`09`09`09/LONGLINES
X`09`09`09/MODIFIED
X`09`09`09/PACKAGE_INDEX
X`09`09`09/PART_SIZE
X`09`09`09/SINCE
X`09`09`09/VERSION
X
X`09`09APPENDIX
X`09`09`09A:`20Redundant`20Features
X`0C
X1.`09INTRODUCTION
X
XThe`20use`20of`20global`20networks`20and`20electronic`20mail`20has`20made`20it
V`20possible`20to
Xdistribute`20software`20packages`20quickly,`20cheaply`20and`20easily`20in`20a
V`20relatively
Xreliable`20way.`20Unfortunately,`20the`20reliability`20cannot`20always`20be
V`20guaranteed`20since
Xmany`20mail`20systems`20can`20introduce`20corruption`20into`20the`20transmitte
Vd`20messages.
X
XSuch`20corruption`20can`20usually`20be`20avoided`20if`20the`20message`20being
V`20sent`20conforms`20to
Xcertain`20restrictions.`20The`20specific`20restrictions`20are`20dictated`20by
V`20the`20common
Xlimitations`20of`20mail`20systems.`20For`20example,`20some`20mail`20systems
V`20will`20truncate`20long
Xlines,`20some`20will`20modify`20character`20sets.`20The`20VMS_SHARE`20utility
V`20is`20designed`20to
Xovercome`20these`20limitations.`20It`20has`20knowledge`20of`20a`20wide`20range
V`20of`20these
Xlimitations`20and`20will`20encode`20a`20series`20of`20files`20into`20a`20forma
Vt`20that`20avoids`20them.
XAs`20a`20result,`20messages`20encoded`20in`20this`20way`20will`20pass`20throug
Vh`20almost`20all`20mail
Xsystems`20uncorrupted,`20allowing`20the`20original`20information`20to`20be`20r
Vecovered`20at`20the
Xreceiving`20end.`20So,`20provided`20there`20is`20an`20electronic`20mail`20link
V`20between`20two`20users,
Xany`20type`20of`20software`20package`20may`20be`20encoded`20and`20sent`20relia
Vbly.
X
XThe`20release`20notes`20for`20the`20package`20describe`20new`20features`20and
V`20general`20changes`20
Xfrom`20previous`20releases`20`5BReference`202`5D.
X
X
X
X
X2.`09OVERVIEW
X
XThe`20VMS_SHARE`20package`20comes`20with`20two`20basic`20components`20-`20the
V`20VMS_SHARE`20utility
Xand`20the`20PAKMAIL`20utility.
X
X
X2.1`20The`20VMS_SHARE`20Utility
X
XFrom`20a`20user`20specified`20set`20of`20input`20files,`20the`20VMS_SHARE`20ut
Vility`20packs`20and
Xencodes`20the`20information`20into`20a`20single`20file,`20known`20as`20an`20ar
Vchive`20or`20'share'
Xfile.`20It`20then`20splits`20up`20the`20file`20into`20pieces`20sufficiently
V`20small`20to`20be`20mailed
Xindividually`20through`20an`20electronic`20mail`20system,`20without`20truncati
Von,`20to`20a
Xrecipient.`20It`20is`20the`20recipient's`20responsibility`20to`20recombine`20t
Vhe`20pieces`20into`20a
Xsingle`20file`20which,`20when`20executed`20as`20a`20VMS`20command`20procedure,
V`20creates`20an`20exact
Xcopy`20of`20the`20original`20input`20files.`20Checksums`20are`20provided`20to
V`20ensure`20that`20if`20the
Xinformation`20is`20corrupted`20by`20some`20unforeseen`20mechanism`20then`20it
V`20is`20at`20least
Xdetected.`20
X
XVMS_SHARE`20encodes`20the`20information`20to`20cope`20with`20different`20types
V`20of`20potential`20
Xcorruption,`20such`20as`20line`20wrapping/truncation,`20character`20code`20con
Vversions,`20
Xtrailing`20blank`20removal`20etc.`20`20Full`20details`20can`20be`20found`20in
V`20the`20technical`20guide`20
X`5BReference`201`5D.
X
X
X2.2`20The`20PAKMAIL`20Utility
X
XBecause`20the`20VMS_SHARE`20utility`20may`20create`20several`20parts`20for`20m
Vailing,`20it`20can`20be
Xdifficult`20to`20issue`20the`20necessary`20commands`20to`20mail`20each`20of
V`20them`20separately.`20The
XPAKMAIL`20utility`20is`20designed`20to`20ease`20this`20difficulty`20by`20gathe
Vring`20all`20of`20the
Xgenerated`20pieces`20of`20the`20share`20file`20and`20mailing`20them`20to`20one
V`20or`20more`20recipients
Xacross`20the`20electronic`20mail`20network.`20VMS`20MAIL`20is`20used`20as`20th
Ve`20mailer.
X`0C
X3.`09USING`20VMS_SHARE
X
XVMS_SHARE`20is`20a`20command`20procedure`20but`20is`20usually`20provided`20to
V`20users`20via`20a
X`60Foreign'`20command`20symbol.`20The`20mechanism`20for`20defining`20this`20sy
Vmbol`20is
Xsite-dependent`20and`20the`20appropriate`20system`20management`20should`20be
V`20consulted`20for
Xdetails.
X
X
X3.1`20Simple`20use
X
XThe`20simplest`20use`20of`20VMS_SHARE`20is`20as`20follows:
X
X`20`20`20`20`20$`20VMS_SHARE`20<input>`20<output>
X
Xwhere:
X
X`20`20<input>`20`20is`20an`20input`20file`20specification`20(see`20below).`20I
Vf`20a`20parameter`20is`20not
X`20`20`20`20`20`20`20`20`20`20`20supplied,`20a`20prompt`20is`20issued.
X
X`20`20<output>`20is`20the`20name`20to`20be`20given`20to`20the`20output`20'shar
Ve'`20file`20(see`20below).
X`20`20`20`20`20`20`20`20`20`20`20If`20a`20parameter`20is`20not`20supplied,`20a
V`20prompt`20is`20issued.`20
X
X
X
X3.1.1`20Input`20File`20specification
X
XThe`20input`20file`20specification`20is`20a`20comma`20separated`20list`20of
V`20standard`20VMS`20
Xfilenames,`20which`20may`20include`20wildcards`20anywhere.`20For`20example:
X
X`20`20`20`20`20TEST
X`20`20`20`20`09The`20specific`20file`20`20`20"TEST."
X
X`20`20`20`20`20*.FOR
X`20`20`20`20`20`20`20`20All`20files`20ending`20in`20".FOR"
X
X`20`20`20`20`20`5B...`5D*.*;*
X`20`20`20`20`20`20`20`20All`20files`20in`20and`20below`20the`20current`20direc
Vtory.
X
X`20`20`20`20`20*.FOR,*.MAR
X`20`20`20`20`20`20`20`20All`20files`20ending`20in`20".FOR",`20then`20all`20fil
Ves`20ending`20in`20".MAR"
X
X
XAny`20subdirectories`20will`20be`20recreated`20when`20the`20share`20file`20is
V`20unpacked.`20For`20this`20
Xreason`20and`20the`20fact`20that`20no`20useful`20information`20is`20contained
V`20within`20them,`20
Xdirectory`20files`20(those`20ending`20in`20.DIR)`20are`20always`20ignored.
X
X
X3.1.2`20Output`20File`20specification
X
XThe`20output`20file`20name`20is`20used`20as`20a`20template`20to`20construct
V`20the`20individual`20parts`20
Xof`20the`20share`20file.`20`20The`20file`20type`20part`20of`20the`20name`20wil
Vl`20be`20suffixed`20by`20a`20'part
Xnumber`20identification'`20of`20the`20form:
X
X`20`20`20`20nnn-OF-mmm
X
Xwhere`20nnn`20is`20the`20part`20number,`20starting`20at`201,`20and`20mmm`20is
V`20the`20total`20number`20of
Xparts`20generated.
X
XFor`20example:
X
XAn`20output`20filename`20of:
X`20`20`20`20PACKAGE.
X
Xmight`20generate`20files`20called:
X`20`20`20`20PACKAGE.001-OF-100
X`20`20`20`20PACKAGE.002-OF-100
X`20`20`20`20`20...
X`20`20`20`20PACKAGE.100-OF-100
X
XAs`20many`20parts`20as`20necessary`20to`20contain`20the`20whole`20package`20ar
Ve`20generated.
X
X
X
X3.1.3`20Examples
X
XTypical`20examples`20of`20the`20use`20of`20VMS_SHARE`20would`20be:
X
X`20`20`20`20`20$`20VMS_SHARE`20`5B...`5D*.*;*`20ARCHIVE
X`20`20`20`20`20`20`20`20`20Archive`20the`20whole`20of`20the`20directory`20tree
V,`20starting`20from`20the`20current
X`20`20`20`20`20`20`20`20`20directory`20into`20a`20share`20file`20with`20a`20te
Vmplate`20name`20of`20"ARCHIVE.SET".`20
X`20`20`20`20`20`20`20`20`20This`20would`20generate`20files`20called`20"ARCHIVE
V.1-OF-9",`20"ARCHIVE.2-OF-9"
X`20`20`20`20`20`20`20`20`20etc.`20(assuming`20a`20total`20of`209`20parts).
X
X
X`20`20`20`20`20$`20VMS_SHARE`20`5B.DOC`5D*.*,`5B.EXE`5D*.*,`5B.SRC`5D*.*`20
V`20VI
X`20`20`20`20`20`20`20`20`20Archive`20all`20files`20in`20the`20three`20director
Vies`20`5B.DOC`5D,`20`5B.EXE`5D`20and`20`5B.SRC`5D
X`20`20`20`20`20`20`20`20`20and`20generate`20share`20files`20with`20a`20templat
Ve`20name`20of`20"VI."`20I.E.
X`20`20`20`20`20`20`20`20`20"VI.01-OF-17",`20"VI.02-OF-17"`20etc.`20(assuming
V`20a`20total`20of`2017`20parts).
X
XWhen`20unpacked,`20the`20tree`20structure`20of`20the`20original`20files`20will
V`20be`20preserved.
X
X
X3.2`20Subdirectory`20restrictions
X
XIn`20order`20to`20ensure`20that`20the`20recipient`20receives`20the`20files`20i
Vn`20a`20known`20set`20of`20
Xdirectories,`20only`20files`20within`20or`20below`20the`20current`20directory
V`20may`20be`20used`20as`20
Xinput.`20`20The`20tree`20structure`20is`20preserved,`20from`20the`20current
V`20directory`20downwards,`20
Xand`20will`20be`20recreated`20below`20the`20recipient's`20current`20directory
V`20at`20unpacking`20
Xtime.
X
XFor`20example,`20if`20we`20archived`20the`20files`20"`5B.SRC...`5D*.*;*"`20the
V`20recipient`20would`20
Xfind`20an`20exact`20copy`20of`20the`20`5B.SRC...`5D`20tree`20recreated`20below
V`20his`20current`20
Xdirectory.
X
XNote:`20advanced`20users`20can`20override`20this`20behaviour`20with`20the`20/N
VODIRECTORY
Xqualifier.`20This`20is`20described`20later.
X
X
X3.3`20File`20type`20Restrictions
X
XVMS_SHARE`20supports`20only`20SEQUENTIAL`20files`20(Not`20INDEXED`20or`20RELAT
VIVE).`20Within`20the
Xsequential`20file`20type,`20all`20record`20formats`20and`20carriage`20control
V`20options`20on`20the
Xfile`20are`20supported`20and`20restored.`20However,`20other`20attributes`20of
V`20the`20file`20are`20not
Xrestored`20`20-`20the`20normal`20file`20defaults`20are`20used.
X
XSince`20fixed`20length`20records`20are`20supported,`20it`20is`20possible`20to
V`20package`20both`20.EXE
Xand`20.OBJ`20files`20without`20the`20need`20for`20external`20encoding.`20The
V`20binary`20data`20normally
Xfound`20in`20such`20files`20is`20automatically`20handled`20and`20encoded`20app
Vropriately.
X
XNote:`20advanced`20users`20can`20use`20the`20/LONGLINES`20qualifier`20to`20all
Vow`20BACKUP`20savesets
Xto`20be`20packaged.`20Any`20type`20of`20file`20may`20be`20shipped`20if`20it
V`20is`20first`20packaged`20inside
Xa`20BACKUP`20saveset.
X
X
X
X3.4`20Record`20Length`20Restrictions
X
XThe`20maximum`20record`20length`20supported`20is`20determined`20by`20the`20und
Verlying`20TPU
Xlanguage`20(in`20which`20a`20large`20portion`20of`20VMS_SHARE`20is`20implement
Ved).`20Prior`20to`20VMS
X5.4`20only`20short`20records`20(less`20than`20960`20bytes)`20were`20permitted.
V`20Later`20versions`20of
XVMS`20recognize`20records`20up`20to`2065535`20bytes.`20For`20compatibility,
V`20VMS_SHARE`20restricts
Xthe`20maximum`20record`20length`20to`20the`20shorter`20length.
X
XNote:`20Advanced`20users`20can`20select`20the`20longer`20record`20length`20usi
Vng`20the`20/LONGLINES
Xoption`20but`20this`20is`20available`20only`20on`20VMS`205.4`20and`20above.
V`20This`20is`20necessary`20only
Xfor`20files`20which`20genuinely`20contain`20records`20longer`20than`20960`20by
Vtes.
X
X
X3.5`20Working`20Set`20and`20Virtual`20Memory`20Requirements
X
XVMS_SHARE`20packages`20files`20by`20first`20reading`20them,`20one`20at`20a`20t
Vime,`20completely`20into
Xmemory.`20Therefore,`20large`20files`20can`20demand`20large`20virtual`20memory
V`20resources`20and
Xusers`20should`20have`20sufficient`20page`20file`20quota`20(PGFLQUO)`20allocat
Ved`20to`20their
Xprocess`20to`20ensure`20that`20the`20files`20will`20fit.`20Later`20versions
V`20of`20TPU`20include
Xautomatic`20use`20of`20a`20behind-the-scenes`20workfile`20to`20hold`20portions
V`20of`20the`20current
Xfile`20and`20the`20need`20for`20larger`20page`20file`20quotas`20disappears`20(
Vto`20be`20replaced`20by`20a
Xneed`20for`20additional`20disk`20quota`20if`20this`20workfile`20is`20on`20a
V`20quota'd`20disk).
X
XBecause`20much`20of`20the`20work`20is`20in`20memory,`20VMS_SHARE`20works`20bes
Vt`20if`20a`20large`20working
Xset`20is`20allocated`20to`20the`20process.`20The`20actual`20size`20depends`20o
Vn`20the`20files`20being
Xpackaged,`20but`20the`20larger`20the`20better.`20Too`20small`20a`20working`20s
Vet`20will`20result`20in`20slow
Xexecution`20speeds`20caused`20by`20excessive`20paging.
X
X
X
X3.6`20Checksum`20Validation
X
XAlthough`20files`20are`20encoded`20to`20resist`20many`20forms`20of`20corruptio
Vn,`20there`20may`20be
Xsome`20mechanisms`20which`20have`20not`20been`20anticipated.`20`20To`20allow
V`20the`20recipient`20to
Xdetect`20this,`20a`20checksum`20validation`20scheme`20is`20applied`20to`20each
V`20file`20unpacked.`20Any
Xmismatch`20at`20the`20unpacking`20stage`20results`20in`20a`20warning`20message
V.`20It`20is`20then`20up`20to
Xthe`20recipient`20to`20locate`20the`20corruption`20and`20fix`20it`20manually
V`20if`20possible.
X
XDue`20to`20limitations`20of`20VMS,`20checksum`20validation`20cannot`20be`20app
Vlied`20to`20files`20with
Xcertain`20types`20of`20record`20structure.`20In`20this`20instance,`20a`20warni
Vng`20is`20issued`20at
Xboth`20the`20packing`20and`20unpacking`20stages`20noting`20that`20checksum`20v
Validation`20for`20the
Xfile`20will`20not`20be`20done.
X`0C
X4.`20ADVANCED`20USE`20OF`20VMS_SHARE
X
XThe`20simple`20use`20described`20earlier`20makes`20use`20of`20default`20values
V`20for`20each`20of`20the
Xuser`20selectable`20options`20built`20in`20to`20VMS_SHARE.`20Each`20option`20m
Vay`20be`20set
Xdifferently,`20to`20select`20a`20different`20way`20of`20working.`20Options`20m
Vay`20be`20set`20either`20by
Xa`20logical`20name,`20which`20overrides`20the`20default`20value`20normally`20u
Vsed,`20or`20by`20means`20of
Xa`20qualifier`20on`20the`20command`20line,`20which`20specifically`20selects
V`20the`20option`20for`20that
Xexecution,`20overriding`20both`20the`20default`20value`20and`20the`20setting
V`20of`20any`20logical
Xname.
X
XTypically,`20users`20will`20define`20logical`20names`20with`20their`20preferre
Vd`20default`20values
Xand`20override`20them`20occasionally`20with`20qualifiers.
X
X
X4.1`20Selectable`20Options
X
XHere`20is`20a`20summary`20of`20the`20available`20options,`20together`20with
V`20the`20qualifier`20and/or
Xlogical`20name`20used`20to`20modify`20the`20default`20value.`20A`20full`20desc
Vription`20of`20each
Xappears`20later.
X
X
XFile`20Selection:
X
X`20`20`20`20`20o`20`20Exclusion`20of`20files`20by`20directory,`20name,`20type
V`20or`20version`20number;`20or`20any
X`20`20`20`20`20`20`20`20combination`20of`20each.`20Wildcards`20are`20not`20per
Vmitted.
X`20`20`20`20`20`20`20`20`20`20`20`20Qualifier:`20`20/EXCLUDE=list
X`20`20`20`20`20`20`20`20`20`20`20`20Logical:`20`20`20`20SHARE_EXCLUDE
X
X`20`20`20`20`20o`20`20Selection`20based`20on`20any`20of`20the`20dates`20associ
Vated`20with`20a`20file`20(created,
X`20`20`20`20`20`20`20`20expiration,`20backup`20or`20last`20modified).
X`20`20`20`20`20`20`20`20`20`20`20`20Qualifier:`20`20/SINCE=date,`20/BEFORE=dat
Ve,`20/CREATED,`20/MODIFIED,`20/BACKUP
X`20`20`20`20`20`20`20`20`20`20`20`20`20`20`20`20`20`20`20`20`20`20`20`20/EXPIR
VED
X`20`20`20`20`20`20`20`20`20`20`20`20Logicals:`20`20`20-`20NONE`20-
X
X`20`20`20`20`20o`20Interactive`20Confirmation`20of`20each`20file`20selected.
X`20`20`20`20`20`20`20`20`20`20`20`20Qualifier:`20/CONFIRM
X`20`20`20`20`20`20`20`20`20`20`20`20Logical:`20`20`20SHARE_CONFIRM
X
X
XFileName`20Preservation:
X
X`20`20`20`20`20o`20Preservation`20of`20sub-directory`20names`20across`20packag
Ving
X`20`20`20`20`20`20`20`20`20`20`20`20Qualifier:`20`20/DIRECTORY
X`20`20`20`20`20`20`20`20`20`20`20`20Logical:`20`20`20`20SHARE_DIRECTORY
X
X`20`20`20`20`20o`20Preservation`20of`20version`20numbers`20across`20packaging
X`20`20`20`20`20`20`20`20`20`20`20`20Qualifier:`20`20/VERSION
X`20`20`20`20`20`20`20`20`20`20`20`20Logical`20`20`20`20`20SHARE_VERSION
X
X
XInformational:
X
X`20`20`20`20`20o`20`20Logging`20of`20various`20key`20stages`20in`20execution
X`20`20`20`20`20`20`20`20`20`20`20`20Qualifier:`20`20/LOG=n
X`20`20`20`20`20`20`20`20`20`20`20`20Logical:`20`20`20`20SHARE_LOG
X
X`20`20`20`20`20o`20`20Selection`20of`20Debugging`20messages`20for`20VMS_SHARE
V`20development`20(must`20be
X`20`20`20`20`20`20`20`20privileged)
X`20`20`20`20`20`20`20`20`20`20`20`20Qualifier:`20`20/DEBUG=n
X`20`20`20`20`20`20`20`20`20`20`20`20Logical:`20`20`20`20SHARE_DEBUG
X
X`20`20`20`20`20o`20DCL`20Verification`20of`20the`20procedure`20as`20it`20execu
Vtes`20(Must`20have`20read`20access)
X`20`20`20`20`20`20`20`20`20`20`20`20Qualifier:`20-`20NONE`20-
X`20`20`20`20`20`20`20`20`20`20`20`20Logical:`20`20`20`20SHARE_VERIFY
X
X
XMiscellaneous:
X
X`20`20`20`20`20o`20Optional`20compression`20of`20the`20data`20by`20one`20of
V`20two`20different`20mechanisms-
X`20`20`20`20`20`20`20Run-length`20encoding`20or`20lempel-ziv`20encoding
X`20`20`20`20`20`20`20`20`20`20`20`20Qualifier:`20`20/COMPRESS=n
X`20`20`20`20`20`20`20`20`20`20`20`20Logical:`20`20`20`20SHARE_COMPRESS
X
X`20`20`20`20`20o`20Selection`20of`20the`20size`20of`20each`20part`20generated
X`20`20`20`20`20`20`20`20`20`20`20`20Qualifier:`20`20/PART_SIZE=n
X`20`20`20`20`20`20`20`20`20`20`20`20Logical:`20`20`20`20SHARE_PART_SIZE
X
X`20`20`20`20`20o`20Selection`20of`20support`20for`20long`20lines`20(only`20ava
Vilable`20on`20VMS`205.4`20and`20up)
X`20`20`20`20`20`20`20`20`20`20`20`20Qualifier:`20`20/LONGLINES
X`20`20`20`20`20`20`20`20`20`20`20`20Logical:`20`20`20`20SHARE_LONGLINES
X
X`20`20`20`20`20o`20Select`20the`20automatic`20creation`20of`20a`20package`20in
Vdex`20file`20for`20use`20by
X`20`20`20`20`20`20`20file`20servers`20which`20are`20going`20to`20make`20the
V`20package`20available
X`20`20`20`20`20`20`20`20`20`20`20`20Qualifier:`20`20/PACKAGE_INDEX=suffix
X`20`20`20`20`20`20`20`20`20`20`20`20Logical:`20`20`20`20SHARE_PACKAGE_INDEX
X
X`20`20`20`20`20o`20Inclusion`20of`20user`20identification`20into`20share`20fil
Ve.
X`20`20`20`20`20`20`20`20`20`20`20`20Qualifier:`20`20-`20NONE`20-
X`20`20`20`20`20`20`20`20`20`20`20`20Logical:`20`20`20`20SHARE_REAL_NAME
X
X`20`20`20`20`20o`20Definition`20of`20scratch`20files
X`20`20`20`20`20`20`20`20`20`20`20`20Qualifier:`20`20-`20NONE`20-
X`20`20`20`20`20`20`20`20`20`20`20`20Logicals:`20`20`20SHARE_TEMP,`20SHARE_UNPA
VCK_TEMP
X`20`20`20`20`20`20`20
X
X4.2`20Default`20Settings
X
XEach`20option`20has`20a`20default`20value`20which`20will`20be`20used`20if`20no
V`20specific`20value`20is
Xselected`20by`20the`20user's`20customization.`20In`20general,`20the`20defaults
V`20are`20suitable`20for
Xmost`20applications`20and`20it`20will`20work`20satisfactorily`20with`20all`20o
Vf`20them.
X
X
X
X4.3`20Customization`20Through`20Logical`20Names
X
XMany`20of`20the`20default`20settings`20can`20be`20changed`20by`20defining`20a
V`20logical`20name`20with`20the
Xselected`20value.`20While`20this`20logical`20name`20is`20defined,`20all`20exec
Vutions`20of`20the
XVMS_SHARE`20utility`20will`20use`20the`20defined`20value`20rather`20than`20the
V`20default.
X
XFor`20example:
X
XTo`20override`20the`20default`20part`20size`20of`2030`20blocks:
X
X`20`20`20$`20define`20SHARE_PART_SIZE`2050
X
XSubsequent`20executions`20of`20VMS_SHARE`20will`20now`20use`20a`20part`20size
V`20of`2050`20blocks`20rather
Xthan`20the`20default`20of`2030`20blocks.
X
XThere`20are`20some`20options`20may`20be`20set`20only`20via`20logical`20names.
V`20These`20are`20described
Xbelow.
X
X
X4.3.1`20SHARE_REAL_NAME`20`20--`20`20Owner`20identification
X
XThe`20sharefile`20is`20created`20with`20a`20header`20that`20identifies`20the
V`20version`20of`20VMS_SHARE
Xused,`20the`20date`20of`20creation`20and`20the`20person`20who`20created`20it
V`20(from`20the`20VMS
Xusername).`20An`20additional`20identification`20string`20may`20be`20included
V`20by`20defining`20the
Xlogical`20name`20SHARE_REAL_NAME`20to`20that`20string.
X
XFor`20example:
X
X`20`20$`20define`20SHARE_REAL_NAME`20"Fred`20Smith"
X
X
X
X4.3.2`20SHARE_TEMP`20`20--`20`20Temporary`20Files
X
XDuring`20the`20packaging`20process,`20a`20number`20of`20temporary`20files`20ar
Ve`20created.`20These
Xdefault`20to`20files`20of`20the`20form`20SYS$SCRATCH:SHARE_TEMP.pid`20where
V`20"pid"`20is`20the
Xunique`20process`20identification`20string.`20They`20are`20deleted`20after`20u
Vse.
X
XThe`20logical`20name`20SHARE_TEMP`20can`20be`20used`20to`20modify`20the`20loca
Vtion`20and`20name`20of
Xthese`20temporary`20files,`20with`20any`20parts`20not`20specified`20being`20ta
Vken`20from`20the`20above
Xdefault.
X
XFor`20example:
X
X`20`20`20$`20define`20SHARE_TEMP`20`20SYS$LOGIN:X.TMP
X`20`20`20`20`20`20`20`20`20Use`20the`20file`20SYS$LOGIN:X.TMP`20`20for`20the
V`20temporary`20file(s).
X
X`20`20`20$`20define`20SHARE_TEMP`20`20SYS$LOGIN:
X`20`20`20`20`20`20`20`20`20Place`20the`20temporary`20file`20in`20the`20SYS$LOG
VIN`20directory`20but`20keep
X`20`20`20`20`20`20`20`20`20everything`20else`20the`20same.`20The`20full`20name
V`20used`20is
X`20`20`20`20`20`20`20`20`20SYS$LOGIN:SHARE_TEMP.pid
X
X
X
X4.3.3`20SHARE_UNPACK_TEMP`20`20--`20`20Temporary`20files`20during`20unpacking
X
XIn`20a`20similar`20fashion`20to`20SHARE_TEMP,`20the`20logical`20name`20SHARE_U
VNPACK_TEMP`20can`20be
Xused`20to`20modify`20the`20location`20and`20name`20of`20the`20temporary`20file
Vs`20used`20during`20the
Xunpacking`20process,`20with`20any`20parts`20not`20specified`20being`20taken
V`20from`20the`20default:
X`60SYS$SCRATCH:SHARE_UNPACK_TEMP.pid'
X
X
X
X4.3.4`20SHARE_VERIFY`20`20--`20verification`20of`20the`20VMS_SHARE`20procedure
V
X
XSome`20users,`20mainly`20system`20managers`20or`20those`20who`20develop`20VMS_
VSHARE,`20may`20wish`20to
Xverify`20the`20operation`20of`20the`20code.`20The`20logical`20name`20SHARE_VER
VIFY`20may`20be`20defined
Xto`20a`20TRUE`20or`20FALSE`20value`20and`20this`20has`20the`20effect`20of`20a
V`20SET`20VERIFY`20or`20SET
XNOVERIFY`20for`20the`20duration`20of`20execution`20of`20the`20procedure.`20
V`20Any`20user`20may`20define
Xthe`20logical`20name`20but`20READ`20access`20to`20the`20procedure`20is`20neede
Vd`20and`20this`20is`20not
Xusually`20given.`20`20Typically`20then,`20only`20privileged`20users`20will`20b
Ve`20able`20to`20verify
Xthe`20operation`20of`20the`20code.
X
X
X4.4`20Customization`20Via`20Command-Line`20Qualifiers
X
XMany`20options`20can`20be`20enabled,`20disabled`20or`20selected`20by`20means
V`20of`20qualifiers`20placed
Xon`20the`20command`20line.`20For`20example:
X
X`20`20`20$`20VMS_SHARE`20<input>`20<output>`20/qualifiers
X
XEach`20qualifier`20specifies`20a`20new`20setting`20for`20one`20option;`20any
V`20number`20of`20quaLifiers
Xmay`20be`20specified`20and`20they`20are`20processed`20from`20left`20to`20right
V.`20In`20the`20case`20of
Xconflicting`20qualifiers,`20the`20rightmost`20one`20specified`20takes`20preced
Vence.
X
XIf`20a`20qualifier`20is`20given,`20it`20overrides`20any`20default`20setting
V`20or`20the`20value`20set`20by`20a
Xlogical`20name.
X
XFor`20example:
X
X`20`20`20$`20VMS_SHARE`20`5B.PACKAGE`5D*.*`20PACKAGE`20/PART_SIZE=100
X`20`20`20`20`20`20`20`20`20will`20create`20a`20package`20of`20100`20block`20fi
Vles`20regardless`20of`20the`20setting`20of
X`20`20`20`20`20`20`20`20`20the`20SHARE_PART_SIZE`20logical`20name.
X
XThe`20full`20list`20of`20qualifiers`20recognized,`20and`20a`20description`20of
V`20each,`20is`20given`20in
Xthe`20qualifier`20reference`20section`20at`20the`20end`20of`20this`20guide.
X
X`0C
X5.`09USING`20PAKMAIL
X
XOnce`20the`20share`20file`20parts`20have`20been`20created,`20they`20can`20be
V`20transmitted`20over`20the`20
Xelectronic`20mail`20network`20to`20one`20or`20more`20recipients`20using`20the
V`20VMS`20MAIL`20utility.`20
XPAKMAIL`20is`20a`20utility`20to`20simplify`20the`20sending`20mechanism`20by
V`20providing`20a`20single`20
Xline`20command`20to`20send`20the`20complete`20package.`20Typically,`20PAKMAIL
V`20is`20made`20
Xavailable`20via`20a`20'foreign`20command'`20so`20the`20command`20is:
X
X`20`20`20`20`20$`20PAKMAIL`20recipient`20file`20maxparts`20`5Bpartlist`5D`20
V`5Bcomment`5D
X
XEach`20of`20the`20parameters`20is`20explained`20below.
X
X
X
X5.1`20User`20specification
+-+-+-+-+-+-+-+-  END  OF PART 7 +-+-+-+-+-+-+-+-