V M S _ S H A R E
A guide to use for the general user
By
Andy Harper
Kings College London
__________________________________________________________________________
A B S T R A C T
VMS_SHARE is designed to package a series of files into a multi-part
share file suitable for mailing across a network. Files are encoded to
be resistant to the corruption that many mailers and networks
generate. When all parts of the share file are combined and run as a
command procedure, the packaged directory tree is recreated in its
original format.
This software is copyright (C) of the author and comes with no
warranties either expressed or implied. It may be distributed free of
charge to anyone who may require a copy, provided that all copyright
notices remain intact. Any problems arising from its use are entirely
the responsibility of the user.
Andy Harper
Systems Manager
Computing Centre
Kings College London
The Strand
London WC2R 2LS
England
Tel: +44 (0) 71 873 2347
E-mail: UDAA055 @ UK.AC.KCL.CC.OAK (JANET)
UDAA055%OAK.CC.KCL.AC.UK @ NSFNET-RELAY.AC.UK (INTERNET)
_________________________________________________________________________
Version 8.4 Jun 1993
Revision 7
C O N T E N T S
1. INTRODUCTION
2. OVERVIEW
2.1 The VMS_SHARE Utility
2.2 The PAKMAIL Utility
2.3 The PAKEXTRACT Utility
3. USING VMS_SHARE
3.1 Simple Use
3.1.1 Input File specification
3.1.2 Output File specification
3.1.3 Examples
3.2 Subdirectory Restrictions
3.3 File Type Restrictions
3.4 Record Length Restrictions
3.5 Working Set and Virtual Memory Requirements
3.6 Checksum Validation
4. ADVANCED USE OF VMS_SHARE
4.1 Selectable Options
4.2 Default Settings
4.3 Customization Through Logical Names
4.3.1 SHARE_IDENT -- Share file creator identification
4.3.2 SHARE_REAL_NAME -- User's Real Name
4.3.3 SHARE_EMAIL_ADDRESS - Electronic mail address
4.3.4 SHARE_TEMP -- Temporary Files
4.3.5 SHARE_UNPACK_TEMP -- Temporary Files
4.3.6 SHARE_VERIFY -- Procedure Verification
4.4 Customization Via Command-Line Qualifiers
5. USING PAKMAIL
5.1 User specification
5.2 File specification
5.3 Part specification
5.4 Partlist specification
5.5 Comment specification
6. HOW TO UNPACK A SHARE FILE
6.1 Command file
6.2 Dealing with multiple part share files
6.3 Using PAKEXTRACT
7. REFERENCES
QUALIFIER REFERENCE SECTION
/BACKUP
/BEFORE
/COMPRESS
/CONFIRM
/CREATED
/DEBUG
/DIRECTORY
/EXCLUDE
/EXPIRED
/LOG
/LONGLINES
/MODIFIED
/NAME
/PACKAGE_INDEX
/PART_SIZE
/SHARE
/SINCE
/SPACE_ENCODE
/SPLIT
/TEMPORARY
/VERSION
/WORK
1. INTRODUCTION
The use of global networks and electronic mail has made it possible to
distribute software packages quickly, cheaply and easily in a relatively
reliable way. Unfortunately, the reliability cannot always be guaranteed since
many mail systems can introduce corruption into the transmitted messages.
Such corruption can usually be avoided if the message being sent conforms to
certain restrictions. The specific restrictions are dictated by the common
limitations of mail systems. For example, some mail systems will truncate long
lines, some will modify character sets. The VMS_SHARE utility is designed to
overcome these limitations. It has knowledge of a wide range of these
limitations and will encode a series of files into a format that avoids them.
As a result, messages encoded in this way will pass through almost all mail
systems uncorrupted, allowing the original information to be recovered at the
receiving end. So, provided there is an electronic mail link between two users,
any type of software package may be encoded and sent reliably.
The release notes for the package describe new features and general changes
from previous releases [Reference 2].
2. OVERVIEW
The VMS_SHARE package comes with three basic components - the VMS_SHARE
utility, the PAKMAIL utility and the PAKEXTRACT utility.
2.1 The VMS_SHARE Utility
From a user specified set of input files, the VMS_SHARE utility packs and
encodes the information into a single file, known as an archive or 'share'
file. It then splits up the file into pieces sufficiently small to be mailed
individually through an electronic mail system, without truncation, to a
recipient. It is the recipient's responsibility to recombine the pieces into a
single file which, when executed as a VMS command procedure, creates an exact
copy of the original input files. Checksums are provided to ensure that if the
information is corrupted by some unforeseen mechanism then it is at least
detected.
VMS_SHARE encodes the information to cope with different types of potential
corruption, such as line wrapping/truncation, character code conversions,
trailing blank removal etc. Full details can be found in the technical guide
[Reference 1].
2.2 The PAKMAIL Utility
Because the VMS_SHARE utility may create several parts for mailing, it can be
difficult to issue the necessary commands to mail each of them separately. The
PAKMAIL utility is designed to ease this difficulty by gathering all of the
generated pieces of the share file and mailing them to one or more recipients
across the electronic mail network. VMS MAIL is used as the mailer.
2.3 The PAKEXTRACT Utility
Packages mailed to a user are received by that user in their mail as a number
of separate messages. The user has the job of extracting all the parts, in the
correct order, joining them together and running the whole thing as a DCL
procedure.
For large packages, there may be many parts (messages) involved. PAKEXTRACT can
assist in the extraction process by locating all the MAIL messages related to
a specific package and extracting them into separate files. By default, it will
also join the parts together to form a single procedure that can be directly
executed without further action.
3. USING VMS_SHARE
VMS_SHARE is a command procedure but is usually provided to users via a
`Foreign' command symbol. The mechanism for defining this symbol is
site-dependent and the appropriate system management should be consulted for
details.
3.1 Simple use
The simplest use of VMS_SHARE is as follows:
$ VMS_SHARE
where:
is the name to be given to the output 'share' file (see below).
If a parameter is not supplied, a prompt is issued.
3.1.1 Input File specification
The input file specification is a comma separated list of standard VMS
filenames, which may include wildcards anywhere. For example:
TEST
The specific file "TEST."
*.FOR
All files ending in ".FOR"
[...]*.*;*
All files in and below the current directory.
*.FOR,*.MAR
All files ending in ".FOR", then all files ending in ".MAR"
Any subdirectories will be recreated when the share file is unpacked. For this
reason and the fact that no useful information is contained within them,
directory files (those ending in .DIR) are always ignored.
3.1.2 Output File specification
The output file name is used as a template to construct the individual parts
of the share file. The file type part of the name will be suffixed by a 'part
number identification' of the form:
nnn-OF-mmm
where nnn is the part number, starting at 1, and mmm is the total number of
parts generated.
For example:
An output filename of:
PACKAGE.
might generate files called:
PACKAGE.001-OF-100
PACKAGE.002-OF-100
...
PACKAGE.100-OF-100
As many parts as necessary to contain the whole package are generated.
3.1.3 Examples
Typical examples of the use of VMS_SHARE would be:
$ VMS_SHARE [...]*.*;* ARCHIVE
Archive the whole of the directory tree, starting from the current
directory into a share file with a template name of "ARCHIVE".
This would generate files called "ARCHIVE.1-OF-9", "ARCHIVE.2-OF-9"
etc. (assuming a total of 9 parts).
$ VMS_SHARE [.DOC]*.*,[.EXE]*.*,[.SRC]*.* VI
Archive all files in the three directories [.DOC], [.EXE] and [.SRC]
and generate share files with a template name of "VI." I.E.
"VI.01-OF-17", "VI.02-OF-17" etc. (assuming a total of 17 parts).
When unpacked, the tree structure of the original files will be preserved.
3.2 Subdirectory restrictions
In order to ensure that the recipient receives the files in a known set of
directories, only files within or below the current directory may be used as
input. The relative tree structure is preserved, from the current directory
downwards, and will be recreated below the recipient's current directory at
unpacking time.
For example, if we archived the files "[.SRC...]*.*;*" the recipient would
find an exact copy of the [.SRC...] tree recreated below his current
directory.
Note: advanced users can override this behaviour with the /NODIRECTORY
qualifier. This is described later.
3.3 File type Restrictions
VMS_SHARE supports only SEQUENTIAL files (Not INDEXED or RELATIVE). Within the
sequential file type, all record formats and carriage control options on the
file are supported and restored. However, other attributes of the file are not
restored - the normal file defaults are used.
Since fixed length records are supported, it is possible to package both .EXE
and .OBJ files without the need for external encoding. The binary data normally
found in such files is automatically handled and encoded appropriately.
Note: advanced users can use the /LONGLINES qualifier to allow BACKUP savesets
to be packaged. Any type of file may be shipped if it is first packaged inside
a BACKUP saveset.
3.4 Record Length Restrictions
The maximum record length supported is determined by the underlying TPU
language (in which a large portion of VMS_SHARE is implemented). Prior to VMS
5.4 only short records (less than 960 bytes) were permitted. Later versions of
VMS recognize records up to 65535 bytes. For compatibility, VMS_SHARE restricts
the maximum record length to the shorter length.
Note: Advanced users can select the longer record length using the /LONGLINES
option but this is available only on VMS 5.4 and above (VAX) and on any
version of OpenVMS on Alpha. It is necessary only for files which genuinely
contain records longer than 960 bytes. However, note that its use will prevent
recipients from unpacking if they have a version of VAX/VMS earlier than 5.4.
3.5 Working Set and Virtual Memory Requirements
VMS_SHARE packages files by first reading them, one at a time, completely into
memory. Therefore, large files can demand large virtual memory resources and
users should have sufficient page file quota (PGFLQUO) allocated to their
process to ensure that the files will fit. Later versions of TPU include
automatic use of a behind-the-scenes workfile to hold portions of the current
file and the need for larger page file quotas disappears (to be replaced by a
need for additional disk quota if this workfile is on a quota'd disk).
Because much of the work is in memory, VMS_SHARE works best if a large working
set is allocated to the process. The actual size depends on the files being
packaged, but the larger the better. Too small a working set will result in slow
execution speeds caused by excessive paging.
Note: Advanced users can control the use of virtual memory a little through the
use of the qualifiers /SPLIT and /WORK. These are fully described in the
qualifier reference section of this document.
3.6 Checksum Validation
Although files are encoded to resist many forms of corruption, there may be
some mechanisms which have not been anticipated. To allow the recipient to
detect this, a checksum validation scheme is applied to each file unpacked. Any
mismatch at the unpacking stage results in a warning message. It is then up to
the recipient to locate the corruption and fix it manually if possible.
Due to limitations of VMS, checksum validation cannot be applied to files with
certain types of record structure. In this instance, a warning message is
generated at the packaging stage and the file is ignored. Unfortunately, the
problem is serious enough to prevent VMS_SHARE from being able to package it.
4. ADVANCED USE OF VMS_SHARE
The simple use described earlier makes use of default values for each of the
user selectable options built in to VMS_SHARE. Each option may be set
differently, to select a different way of working. Options may be set either by
a logical name, which overrides the default value normally used, or by means of
a qualifier on the command line, which specifically selects the option for that
execution, overriding both the default value and the setting of any logical
name.
Typically, users will define logical names with their preferred default values
and override them occasionally with qualifiers.
4.1 Selectable Options
The following table lists the additional facilities that can be selected,
either by logical name or qualifier (or both, in some cases). A full
description of each is given later.
-------------------------------------------------------------------------------
Qualifier Logical Function
-------------------------------------------------------------------------------
File Selection:
--------------
/BACKUP Specify the last backup date as a date criteria
/BEFORE=date Select only files before a certain date
/CREATED Specify the creation date as a date criteria
/EXCLUDE=list SHARE_EXCLUDE Exclusion of files by directory, name, type and
version number; or any combination of each.
/EXPIRED Specify the expiry date as a date criteria
/MODIFIED Specify the last modified date as a date
criteria
/SINCE=date Select only files after a certain date
Interactive Selection Confirmation:
----------------------------------
/CONFIRM SHARE_CONFIRM Requires a TRUE/FALSE value to confirm each
file selected.
FileName Preservation:
---------------------
/DIRECTORY SHARE_DIRECTORY Selects the preservation of relative directory
names across the packaging operation.
/VERSION SHARE_VERSION Selects the preservation of file version
numbers across the packaging operation.
Informational:
--------------
/DEBUG=n SHARE_DEBUG Selects internal debugging messages to assist
development.
/LOG=n SHARE_LOG Selects logging of progress at various levels
SHARE_VERIFY Selects verification of the DCL code as it is
executed.
Use of Temporary Files:
----------------------
/TEMPORARY=file SHARE_TEMP Selects an alternative name for the temporary
file used during packaging
SHARE_UNPACK_TEMP
Selects an alternative name for the temporary
file used during unpacking of a share file.
/WORK=file SHARE_WORK Selects an alternative work file for the
storage of those parts of a big file that will
not fit in the available virtual memory.
User Identification:
--------------------
SHARE_EMAIL_ADDRESS
Defines a specific string as the user's email
address, overriding the automatic selection
which is inbuilt.
SHARE_IDENT Defines a specific string as the
identification line written at the head of
the share file. Overrides the use of the
user's email address.
SHARE_REAL_NAME Defines a specific string to be inserted into
the comment field of the users email address.
Miscellaneous:
/COMPRESS SHARE_COMPRESS Selects additional file compression to reduce
transit time through the network.
/LONGLINES SHARE_LONGLINES Selects support for long records supplied
with more recent VMS versions.
/NAME SHARE_NAME Select the name to be written into the share
file to identify the package.
/PACKAGE_INDEX SHARE_PACKAGE_INDEX
Selects the automatic creation of a package
index file for use with some mail based file
servers
/PART_SIZE SHARE_PART_SIZE Selects the maximum size of each part of the
share file.
/SHARE SHARE_SHARE Selects whether to write or not write the
generated share file parts.
/SPACE_ENCODE SHARE_SPACE_ENCODE
Select whether all spaces are encoded or just
those at the ends of lines in the share file.
/SPLIT SHARE_SPLIT Select the maximum size of file that can be
processed in memory. Files which are larger
will be split into small parts of this size and
processed independently.
-------------------------------------------------------------------------------
4.2 Default Settings
Each option has a default value which will be used if no specific value is
selected by the user's customization. In general, the defaults are suitable for
most applications and it will work satisfactorily with all of them.
4.3 Customization Through Logical Names
Many of the default settings can be changed by defining a logical name with the
selected value. While this logical name is defined, all executions of the
VMS_SHARE utility will use the defined value rather than the default.
For example:
To override the default part size of 30 blocks:
$ define SHARE_PART_SIZE 50
Subsequent executions of VMS_SHARE will now use a part size of 50 blocks rather
than the default of 30 blocks.
There are some options may be set only via logical names. These are described
below.
4.3.1 SHARE_IDENT -- Share file creator identification
The sharefile is created with a header that contains a string to identify the
user who created it. If this logical name is defined, then its translation is
used as this identification string.
For Example:
$ DEFINE SHARE_IDENT "Fred Bloggs on behalf of SoftSoap International"
If this logical name is not defined, VMS_SHARE uses a default string based on
the user's electronic mail address. This address is worked out automatically
from the logical names that are known to be provided by various underlying
network packages. If the e-mail address cannot be worked out, then the username
by itself is used.
For example:
FBLOGGS@LUXVAX.SOFTSOAP.COM
might be the default ident string for user FBLOGGS at site LUXVAX.SOFTSOAP.COM
If the system has no recognized network name, then the ident string would be
simply:
FBLOGGS
This ident string may be further modified by the logical names SHARE_REAL_NAME
and SHARE_EMAIL_ADDRESS. These are described below.
4.3.2 SHARE_REAL_NAME -- User's Real Name
If this logical name is defined, it's translation is added to the default ident
string to produce an e-mail address in the standard form.
For example:
$ define SHARE_REAL_NAME "Fred Bloggs"
would modify the default ident string to:
Fred Bloggs
If SHARE_IDENT is defined to override the default ident string, then the
translation of SHARE_REAL_NAME is ignored.
4.3.3 SHARE_EMAIL_ADDRESS -- Electronic Mail Address
If it is not possible to work out the e-mail address, or the user wishes a
different e-mail address to be used, then this logical name can be defined with
a replacement.
For example:
$ define SHARE_EMAIL_ADDRESS "FBLOGGS@CLEANVAX.SOFTSOAP.EDU"
would force this specific e-mail address and override the automatic
determination of the address.
If SHARE_IDENT is defined to override the default ident string, then the
definition of SHARE_EMAIL_ADDRESS is ignored.
4.3.4 SHARE_TEMP -- Temporary Files
During the packaging process, a number of temporary files are created. These
default to files of the form SYS$SCRATCH:SHARE_TEMP.pid where "pid" is the
unique process identification string. They are deleted after use.
The logical name SHARE_TEMP can be used to modify the location and name of
these temporary files, with any parts not specified being taken from the above
default.
For example:
$ define SHARE_TEMP SYS$LOGIN:X.TMP
Use the file SYS$LOGIN:X.TMP for the temporary file(s).
$ define SHARE_TEMP SYS$LOGIN:
Place the temporary file in the SYS$LOGIN directory but keep
everything else the same. The full name used is
SYS$LOGIN:SHARE_TEMP.pid
4.3.5 SHARE_UNPACK_TEMP -- Temporary files during unpacking
In a similar fashion to SHARE_TEMP, the logical name SHARE_UNPACK_TEMP can be
used to modify the location and name of the temporary files used during the
unpacking process, with any parts not specified being taken from the default:
`SYS$SCRATCH:SHARE_UNPACK_TEMP.pid'
4.3.6 SHARE_VERIFY -- verification of the VMS_SHARE procedure
Some users, mainly system managers or those who develop VMS_SHARE, may wish to
verify the operation of the code. The logical name SHARE_VERIFY may be defined
to a TRUE or FALSE value and this has the effect of a SET VERIFY or SET
NOVERIFY for the duration of execution of the procedure. Any user may define
the logical name but READ access to the procedure is needed and this is not
usually given. Typically then, only privileged users will be able to verify
the operation of the code.
4.4 Customization Via Command-Line Qualifiers
Many options can be enabled, disabled or selected by means of qualifiers placed
on the command line. For example:
$ VMS_SHARE /qualifiers
Each qualifier specifies a new setting for one option; any number of qualifiers
may be specified and they are processed from left to right. In the case of
conflicting qualifiers, the rightmost one specified takes precedence.
If a qualifier is given, it overrides any default setting or the value set by a
logical name.
For example:
$ VMS_SHARE [.PACKAGE]*.* PACKAGE /PART_SIZE=100
will create a package of 100 block files regardless of the setting of
the SHARE_PART_SIZE logical name.
The full list of qualifiers recognized, and a description of each, is given in
the qualifier reference section at the end of this guide.
5. USING PAKMAIL
Once the share file parts have been created, they can be transmitted over the
electronic mail network to one or more recipients using the VMS MAIL utility.
PAKMAIL is a utility to simplify the sending mechanism by providing a single
line command to send the complete package. Typically, PAKMAIL is made
available via a 'foreign command' so the command is:
$ PAKMAIL recipient file maxparts [partlist] [comment]
Each of the parameters is explained below.
5.1 User specification
The recipient parameter is the mail address of the user, or users, who are to
be sent the package. This can take any form of mail address acceptable to the
VMS MAIL system when used from the command line. For example:
FRED
NODE::JIM
NODE::JIM,FRED
There are two small problems to watch out for. Firstly, the use of
distribution lists requires an @ symbol to precede a file specification which
contains the recipient names. Used directly, DCL intercepts the @ before MAIL
does, and so the command does not work correctly. To avoid this, define a
logical name to point at the distribution list and specify the logical name as
the recipient. For example:
$ DEFINE USERS "@BETA_TEST_USERS.DIS"
$ PAKMAIL USERS ...
Secondly, usernames that contain quotes (") need special attention because of
the way DCL/MAIL parse quoted strings. Typically, this is important when
sending network mail as the usual form of address is:
NET%"user@site"
In this instance, the quotes must be doubled, with another set around each
to give an address specification of:
"NET%""user@site"""
5.2 File specification
The file specification gives the name of the package to be sent. It should be
the share file template name - omitting the part numbers. For example, a
specification of "PACKAGE." will cause the package to send these files:
PACKAGE.01-OF-10
PACKAGE.02-OF-10
...
PACKAGE.10-OF-10
5.3 Maximum Parts specification
This is simply the total number of parts in the package. It controls how many
files are to be sent to each recipient.
A typical example of a PAKMAIL command would be
$ PAKMAIL "NET%""FRED@SCROUNGING-SITE""" PACKAGE.TEST 5
5.4 Partlist Specification
By default, all parts of the package are sent. On occasion, it may be necessary
to resend a subset of the package. This parameter allows a list of parts to be
given and only those parts will be sent. The list is a comma separated set of
part numbers.
For example:
$ PAKMAIL "NET%""FRED@SCROUNGING-SITE""" PACKAGE.TEST 5 4,2
The addition of the "4,2" parameter restricts the parts sent out to
parts 4 and 2.
5.5 Comment specification
The subject line of the mail message sent to each recipient identifies the
package, which part and the total number of parts in the form:
Subj: PACKAGE.1-OF-5
Optionally a further parameter can be given on the PAKMAIL command. This
parameter will be inserted verbatim into the subject line.
For example, if this command is issued:
$ PAKMAIL "NET%""FRED@SCROUNGING-SITE""" PACKAGE 5 "" "(Beta-Test v2)"
(Note the use of a placeholder as the fourth parameter if a partlist is not
required).
Then the generated subject line would look like this:
Subj: PACKAGE.1-OF-5 (Beta-Test v2)
6. HOW TO UNPACK A SHARE FILE
6.1 Command file
A share file is designed to be run as a command procedure which will recreate
the original source files. So in theory, it is simply necessary to extract the
received mail message into a file, remove the mail headers, and then run it as
a command procedure.
For a single part share file, the following sequence of commands is necessary:
$ SET DEFAULT
$ MAIL
MAIL> READ
MAIL> EXTRACT/NOHEADER file
MAIL> EXIT
$
$ @file
6.2 Dealing with multiple part share files
The recipient of a multi-part package sent in this form will receive a number
of separate mail messages - one per part - but not necessarily in the correct
numeric order. These individual messages must be extracted and combined into
one file IN THE RIGHT ORDER. The exact sequence of events is similar to above
but slightly complicated by the need to extract them in the right order and
append them into a single file:
$ SET DEFAULT
$ MAIL
MAIL> READ
MAIL> EXTRACT/NOHEADER file
MAIL> READ
MAIL> EXTRACT/NOHEADER/APPEND file
MAIL> ... repeat last two steps for each part in sequence
MAIL> EXIT
$
$ @file
Strictly speaking, it is not necessary to remove the mail headers from each
part except the first, as the share file format is designed to skip these
automatically.
It is important to note that ALL parts must be extracted, and in the right
order, before trying to unpack. It is not possible to unpack each part
individually.
6.3 Using PAKEXTRACT
If the PAKEXTRACT utility is provided on your system (it is distributed with
the VMS_SHARE package), then it may be used to assist in the extraction
process.
A command of the form:
$ PAKEXTRACT package-name number-of-parts [mail-folder] [option]
may be used, where:
package-name is the name of the package to be extracted from MAIL.
number-of-parts is the total number of parts in the package.
mail-folder is the name of the MAIL folder holding the messages
(default: the NEWMAIL folder).
option The keyword NOJOIN, to prevent the parts being
concatenated together.
This command will scan the mail folder looking for subject lines that begin
with:
package-name.nnn-OF-mmm ...
where:
package-name is the name of the package (as above)
nnn is the part number
mmm is the total number of parts
... is optional text
This is the form of the subject line created by the PAKMAIL utility (from
version 2.0 and upwards) and so should only be used if the received messages
have subject lines of this form. For compatibility, subject lines generated by
previous versions of PAKMAIL are also recognized. These have the form:
package.n_OF_m
or package n/m
Once the messages have been located within MAIL, they are each written to an
external file, in the current directory, with names of the form:
package-name.nnn-OF-mmm
(format as above).
NOTE: this utility should not be used for parts that do not have subject lines
in exactly this format! It is possible that erroneous messages may be selected
and written to the external files.
NOTE: it is important that the content of the specified mail folder is not
altered while this procedure is running, other than adding new messages at the
end. If this restriction is not observed, then the wrong messages may be
selected and written to the external files.
Once the individual messages have been extracted, PAKEXTRACT will (unless the
NOJOIN option has been specified) attempt to join the parts together to form a
single DCL procedure called `package.SHAR' that can be directly executed to
unpack all of the files.
Example:
To extract and unpack all of the parts of a 10 part package called EXAMPLE,
where the messages are stored in the MAIL folder called NEWSOFT, the following
sequence of commands would be given:
$ PAKEXTRACT EXAMPLE 10 NEWSOFT
To extract the files, and join the files together into a single DCL
procedure.
$ @EXAMPLE.SHAR
To run the generated share file and unpack all the files it contains.
7. REFERENCES
The following references provide further information on VMS_SHARE and are
provided with each release of the software.
[1] VMS_SHARE Technical Information supplement
[2] VMS_SHARE Release notes
[3] On-line HELP
----------------------------------------------------------
QUALIFIER REFERENCE SECTION
----------------------------------------------------------
QUALIFIER:
/BACKUP
PURPOSE:
Specifies that the last backup date should be used for the
purpose of date based file selection by the /BEFORE and
/SINCE qualifiers
DEFAULT:
Use the last-modified date
ASSOCIATED LOGICAL NAME:
NONE
PRIVILEGES REQUIRED:
NONE
DESCRIPTION:
Files may be selected for packaging on the basis of the dates
associated with the file, using the /BEFORE and /SINCE
qualifiers. The /BACKUP qualifier says that the last backup
date should be used as the comparison date.
RESTRICTIONS:
The qualifier is ignored if neither the /SINCE or /BEFORE
qualifiers are specified.
Each of these qualifiers are mutually exclusive; only the last
one specified has any effect - /BACKUP, /CREATED, /EXPIRED and
/MODIFIED
QUALIFIER:
/BEFORE[=date]
PURPOSE:
Specifies that all files selected must have a date associated
with them which is before the specified date.
DEFAULT:
The dates associated with a file are not used for selection
purposes.
ASSOCIATED LOGICAL NAME:
NONE
PRIVILEGES REQUIRED:
NONE
DESCRIPTION:
If either of the /SINCE or /BEFORE qualifiers is specified,
then each file specified in the parameter list is checked to
see if the date associated with the file is within the
appropriate date range. The file is selected for packaging only
if it does. No check is made if neither qualifier is specified
and the file is selected.
There are four dates associated with a file - Creation, Last
Modified, Expiration and Last Backup. Any of these can be used
as the basis for selection.
To select which of the four dates to use, these qualifiers are
used:
/BACKUP Last backup date used
/CREATED Creation date used
/EXPIRED Expiration date used
/MODIFIED Last modified date used
To select the date range, these qualifiers are used:
/BEFORE[=date] Select files before the date
/SINCE[=date] Select files after the date
If neither qualifier is specified, then the corresponding
constraint on the date is lifted.
It is permitted to use /SINCE and /BEFORE together to specify
both an earliest date and a latest date for the files. If no
date/time specification is given on either the /SINCE or
/BEFORE qualifiers, then the default is "TODAY".
RESTRICTIONS:
Only one of /BACKUP, /CREATED, /EXPIRED or /MODIFIED should be
used. If several are specified only the last one is used. If
none are specified, /MODIFIED is assumed.
The format of the date specification is a standard VMS
date/time specification with these exceptions:
o The date/time spec must not contain spaces
o The date/time spec must not be quoted
o Missing fields are taken from the CURRENT date/time and
NOT from midnight as with other VMS commands.
EXAMPLES:
$ VMS_SHARE *.* PACKAGE /BEFORE
Package all files modified before today
$ VMS_SHARE *.* PACKAGE /BEFORE=1-JAN-1992:00:00:00.00 /CREATED
Package all files created before this year
$ VMS_SHARE *.* PACKAGE /SINCE=YESTERDAY /BEFORE=TODAY /BACKUP
Package all files that were backed up yesterday
$ VMS_SHARE *.* Z /BEFORE=TODAY
This will select all files which have a modified date (the
default) before today's date.
QUALIFIER:
/[NO]COMPRESS[=n]
PURPOSE:
Select the level of compression performed on each file packaged
DEFAULT:
/NOCOMPRESS No compression is performed
ASSOCIATED LOGICAL NAME:
SHARE_COMPRESS
This logical name may be defined to any true or false value, or
to a numeric value within the range 0-2. The value determines
the default for any subsequent run where the qualifier
/COMPRESS is not used.
PRIVILEGES REQUIRED:
NONE
DESCRIPTION:
VMS_SHARE packages files in the original forms where possible.
The only codings made are to characters or bytes which may
prove troublesome if transmitted through a text based mail
system. So most printing characters should remain visible.
The various encodings made to the file, to ensure trouble free
transmission, can increase the overall size significantly. By
default, no attempt is made to compress the data to reduce
this side effect. However, additional file compression may be
selected if required, in an attempt to reduce this overhead
and hence speed up transmission of the file through the mail
system.
Two compression options are offered - the first is a simple
run-length encoding algorithm to replace runs of the same
character by a shorter sequence, the second is a more complex
algorithm designed to seek out common substrings in a file and
encode them to shorter sequences. The latter algorithm is based
heavily on one known as Lempel-Ziv, although it has been
significantly modified for use here.
These compression qualifiers are recognized:
/NOCOMPRESS No compression performed
/COMPRESS Run-length compression
/COMPRESS=0 No compression performed
/COMPRESS=1 Run-Length compression
/COMPRESS=2 Lempel-Ziv compression
The share file, when unpacked, will automatically expand the
data back to its original form.
Selection of compression has two main effects:
First, in general, the overall size of the packaged files is
reduced; the exact compression ratio will vary depending on the
content of the file. In some cases, it may be of no benefit.
This implementation will never increase the size of a file
soley because of the additional compression options chosen.
Lempel-Ziv compression is considerably better than the
run-length encoding mechanism.
Second, It will generally take significantly longer to perform
additional compression on the file. Lempel-Ziv takes
significantly longer than run-length encoding (but does a
better job).
It is important to recognize the tradeoffs here; additional cpu
time is being traded for a potential (though not guaranteed)
reduction in the packaged file size. You should consider
whether it is really of benefit before selecting it. As a
general rule of thumb, select compression only if you are going
to place the package on a file server, where reduction in disk
space occupancy is desirable, or if you intend to mail a very
large package to hundreds of people, where a reduction in
network bandwidth is desirable. Otherwise, don't bother.
Note that the overhead involved in decompressing a file when it
is being unpacked from the sharefile is fairly small, and can
usually be ignored for the purposes of deciding upon the
tradeoffs.
Note that the built-in compression schemes are not the best
available. They are intended to provide reasonable compression
without resorting to external utilities, though at the cost of
considerable packaging time. Better or faster compression can
be obtained using external utilities but this complicates the
process of packaging files and assumes that the recipient has
the corresponding decompression utilities. VMS_SHARE makes it
simple and does not require the recipient to have any other
tools.
RESTRICTIONS:
NONE
EXAMPLES:
$ VMS_SHARE *.* COMPACT /COMPRESS
Package the files, using run length compression
$ VMS_SHARE *.* COMPACT /COMPRESS=2
Package the files, using Lempel-Ziv compression
QUALIFIER:
/[NO]CONFIRM
PURPOSE:
Require user confirmation of all files selected
DEFAULT:
/NOCONFIRM User is not asked to confirm each file
ASSOCIATED LOGICAL NAME:
SHARE_CONFIRM
This logical name can be defined with a true or false value. It
specifies the default for all subsequent executions which do
not specify the /CONFIRM qualifier.
PRIVILEGES REQUIRED:
NONE
DESCRIPTION:
The selection of files for packaging can be automatic, or with
confirmation. With confirmation, the user is asked about each
file matching the qualifiers and parameters to see if it should
be included in the package. A simple Y or N response is then
required from the user to select or not select it for
inclusion.
/NOCONFIRM specifies that confirmation is not required.
/CONFIRM specifies that confirmation is required.
RESTRICTIONS:
Because confirmation requires a response from the user, it is
not permitted in non-interactive environments. A warning
message will be issued and confirmation turned off.
EXAMPLE:
$ VMS_SHARE *.* PACKAGE /CONFIRM
Request confirmation from the user of each file selected. Each
file requires a Y (to select) or a N (to not select) response.
QUALIFIER:
/CREATED
PURPOSE:
Specifies that the creation date should be used for the
purpose of date based file selection by the /BEFORE and
/SINCE qualifiers
DEFAULT:
Use the last-modified date
ASSOCIATED LOGICAL NAME:
NONE
PRIVILEGES REQUIRED:
NONE
DESCRIPTION:
Files may be selected for packaging on the basis of the dates
associated with the file, using the /BEFORE and /SINCE
qualifiers. The /CREATED qualifier says that the creation
date should be used as the comparison date.
RESTRICTIONS:
The qualifier is ignored if neither the /SINCE or /BEFORE
qualifiers are specified.
Each of these qualifiers are mutually exclusive; only the last
one specified has any effect - /BACKUP, /CREATED, /EXPIRED and
/MODIFIED
QUALIFIER:
/[NO]DEBUG[=nnn]
PURPOSE:
Specify that debugging output is to be produced; nnn is the
level of debugging required, from 0 to 4.
DEFAULT:
/NODEBUG Debugging output is OFF
ASSOCIATED LOGICAL NAME:
SHARE_DEBUG
The logical name can be defined with any true or false value,
or an integer in the range 0-4. When defined, it will determine
the default value for subsequent executions that do not specify
the /DEBUG qualifier.
PRIVILEGES REQUIRED:
Either SETPRV or SYSPRV required in the user's list of
AUTHORIZED privileges
DESCRIPTION:
For developing VMS_SHARE, or investigating problems, it may be
helpful to use the debugging code built into the package.
Several levels of debugging are built in - Level 0 is no
debugging, level 4 is the most detailed and verbose level of
debugging. Debugging causes informational messages to be output
describing the state of VMS_SHARE and can be used to
investigate undocumented behaviour.
The following qualifier formats are recognized:
/NODEBUG Debugging is off
/DEBUG Debugging is on at level 1
/DEBUG=0 Debugging is off
/DEBUG=1 Debugging is on at level 1
/DEBUG=2 Debugging is on at level 2
/DEBUG=3 Debugging is on at level 3
/DEBUG=4 Debugging is on at level 4
RESTRICTIONS:
NONE
EXAMPLES:
$ VMS_SHARE *.* PACKAGE /NODEBUG
Package files, with a debug level of 0
$ VMS_SHARE *.* PACKAGE /DEBUG
Package files, with a debug level of 1
$ VMS_SHARE *.* PACKAGE /DEBUG=2
Package files, with a debug level of 2
QUALIFIER:
/[NO]DIRECTORY
PURPOSE:
Select preservation of subdirectory names on each file packaged
in order to re-create them during unpacking.
DEFAULT:
/DIRECTORY Directories are preserved
ASSOCIATED LOGICAL NAME:
SHARE_DIRECTORY
This logical name can be defined with any true or false value.
When defined it specifies the default value for all subsequent
executions that do not specify the /DIRECTORY qualifier.
PRIVILEGES REQUIRED:
NONE
DESCRIPTION:
When /NODIRECTORY is specified, the subdirectory name of each
file is discarded and all files will be recreated in the
directory current at the time of unpacking. The input files may
be from any source at all, although care should be taken with
multiple input directories to ensure that clashing filenames do
not occur.
When /DIRECTORY is specified, the relative subdirectory name
of each file is preserved so that the unpacking process can
recreate a copy of the directory tree below the current
directory. The input files must lie on the same disk at or
below the current subdirectory. This is to ensure that a
well-defined set of directories are recreated at unpacking
time.
This option is supplied primarily for compatibility with
previous versions of the utility which did not preserve version
numbers.
RESTRICTIONS:
NONE
EXAMPLES:
$ VMS_SHARE [...]*.* PACKAGE /DIRECTORY
Preserve the subdirectory names to cause recreation of the
directory tree when unpacked.
$ VMS_SHARE [...]*.* PACKAGE /NODIRECTORY
Do not preserve directory names; all files will be created in
the current directory when unpacked. Care must be taken to
avoid clashing file names.
QUALIFIER:
/[NO]EXCLUDE[=list]
PURPOSE:
Specify a list of file patterns which, if matched, prevent a
file from being packaged.
DEFAULT:
/NOEXCLUDE No files are excluded from packaging
ASSOCIATED LOGICAL NAME:
SHARE_EXCLUDE
This logical name may be defined with a comma separated list of
partial file specifications (see description below). When
defined, it specifies the default list of excluded files for
all subsequent executions that do not specify the /EXCLUDE
qualifier.
PRIVILEGES REQUIRED:
NONE
DESCRIPTION:
VMS_SHARE will normally package up all files matching the file
specifications given on the command line. Sometimes, it is
necessary to specifically exclude particular files. For
example, if generating a share file containing only sources, it
would be usual to exclude all files with a type of .EXE or .OBJ
VMS_SHARE allows files to be excluded from the packaging
operation based upon any combination of the Directory, Name,
Type and Version fields of the filename.
The /EXCLUDE qualifier is used to specify a list of file
exclusion clauses:
/EXCLUDE=list
`list' is a list of file specifications which match the files
to be excluded from the packaging operation. Each file
specification may be any combination of directory, name, type
or version field of a filename, with missing fields taken as
matching anything (equivalent to a `*' wildcard in that
particular field).
RESTRICTIONS:
Although wildcards are supported, it is limited support only.
The wildcard may be used only to represent a COMPLETE field
(directory, name, type or version) and not a partial field.
All directory names must be the full name. Relative directory
specifications are not permitted.
EXAMPLES:
/EXCLUDE=.EXE Excludes all files with a type of .EXE
/EXCLUDE=.EXE,.OBJ Excludes all files with a type of .EXE
or .OBJ
/EXCLUDE=NAME.TXT Excludes all files called NAME.DAT in
any directory
/EXCLUDE=;1 Exclude all version 1 files
/EXCLUDE=[XYZ] Exclude all files in directory [XYZ]
Note that a wildcard can be used to represent a whole field of
the specification but NOT a partial field. For example:
VALID:
/EXCLUDE=*.FOR Exclude all files with a type of .FOR
INVALID:
/EXCLUDE=XYZ*.FOR Cannot use the * as PART of a field
specification
QUALIFIER:
/EXPIRED
PURPOSE:
Specifies that the expiration date should be used for the
purpose of date based file selection by the /BEFORE and
/SINCE qualifiers
DEFAULT:
Use the last-modified date
ASSOCIATED LOGICAL NAME:
NONE
PRIVILEGES REQUIRED:
NONE
DESCRIPTION:
Files may be selected for packaging on the basis of the dates
associated with the file, using the /BEFORE and /SINCE
qualifiers. The /EXPIRED qualifier says that the expiration
date should be used as the comparison date.
RESTRICTIONS:
The qualifier is ignored if neither the /SINCE or /BEFORE
qualifiers are specified.
Each of these qualifiers are mutually exclusive; only the last
one specified has any effect - /BACKUP, /CREATED, /EXPIRED and
/MODIFIED
QUALIFIER:
/[NO]LOG[=nnn]
PURPOSE:
Specify that informational progress messages are to be
displayed at various stages of the packaging. nnn specifies the
level of information required (0 through 4).
DEFAULT:
/NOLOG Suppress all informational messages
ASSOCIATED LOGICAL NAME:
SHARE_LOG
This logical name can be defined with any true or false value,
or an integer in the range 0-4. When defined, it specifies the
default for all subsequent executions that do not specify the
/LOG qualifier.
PRIVILEGES REQUIRED:
NONE
DESCRIPTION:
Each stage in the packaging process, typically the name of each
file as it is processed, can be logged with an informational
message. The /LOG[=nnn] qualifier selects this option. The
value of nnn is an integer (default 1) which selects how much
information is displayed. It may take values between 0 and 4,
where 0 is no logging and 4 is the most comprehensive logging.
/NOLOG suppresses all log messages; this is the same as
specifying /LOG=0
/LOG=n selects logging at level n:
n=0 turns all log messages off.
n=1 displays a log message for each file processed.
n=2 includes everything at n=1, with the addition of statistics
on the file compression before and after packaging. This can be
useful for determining the effectiveness (or otherwise) of the
selected compression technique on a given file.
n=3 includes everything at level 2, with the addition of a
message each time a new part is written out.
n=4 includes everything at level 3, with the addition of a
progress message issued at approximately 3% intervals while
encoding each file.
/LOG without a numeric value defaults to level 1 logging.
RESTRICTIONS:
NONE
EXAMPLES:
$ VMS_SHARE *.* PACKAGE /LOG
Package all the files and log each one as it is processed.
$ VMS_SHARE *.* PACKAGE /LOG=2
Package all the files, log each one as it is processed and show
the compression statistics for each.
QUALIFIER:
/[NO]LONGLINES
PURPOSE:
Allow VMS_SHARE to take advantage of the support for long
records in recent versions of VMS and TPU.
DEFAULT:
/NOLONGLINES Long line support not enabled
ASSOCIATED LOGICAL NAME:
SHARE_LONGLINES
This logical name can be defined with any true or false value.
When defined, it specifies the default value for all subsequent
executions that do not specify the /LONGLINES qualifier.
PRIVILEGES REQUIRED:
NONE
DESCRIPTION:
The VMS_SHARE utility is layered upon the VAXTPU language. As
such, most of its restrictions are because of the limitations
of VAXTPU. One particular limitation is that of maximum record
length. Older versions of TPU (prior to VMS 5.4 on VAX) allowed
records to be no longer than 960 bytes. This restricted the
maximum record length of the files that could be packaged.
Versions of TPU at VMS 5.4 and later, and any version of TPU
on Alpha OpenVMS, allow much longer records, up to 65535 bytes.
To maintain backwards compatibility, the old record length is
used unless requested otherwise.
If /NOLONGLINES is specified, then the following restrictions
apply:
o Records may be no longer than 960 bytes
o The minimum version of VMS to run is 5.0 on VAX;
any version on Alpha.
o The minimum version of VMS to unpack is 4.4 on VAX;
any version on ALpha.
If /LONGLINES is specified, then the following restrictions
apply:
o Records may be up to 65535 bytes
o The minimum version of VMS to run is 5.4 on VAX;
any version on ALpha.
o The minimum version of VMS to unpack is 5.4 on VAX;
any version on Alpha.
An important use for the /LONGLINES qualifier is to allow
BACKUP savesets to be directly packaged. These have a minimum
record length of 2048 bytes so /LONGLINES is required. This
provides a convenient mechanism for shipping VMSINSTALable
products, and any type of file (including INDEXED and
RELATIVE).
It is helpful to recognize when to use and when not to use the
long line support:
First, there is NO advantage if none of the files to be
packaged have records greater than 960 bytes. In fact this may
turn out to be detrimental for the recipient as we mention
below.
Secondly, using it requires that the current version of VMS is
at least 5.4 on VAX (any version on Alpha). An error is issued
if not.
Finally, the recipient of the share file will require VMS 5.4
or greater (VAX), or any OpenVMS (Alpha) in order to unpack it
(if it needed long line support to pack it, it will also need
long line support to unpack it!). This is true even if none of
the files have lines longer than 960.
RESTRICTIONS:
This option is only valid with VMS 5.4 and above. Note
therefore that BACKUP savesets can only be packaged on VMS 5.4
systems and later, and require a similar system to unpack. If
on an Alpha, any version of OpenVMS is permitted.
VMS_SHARE examines the file header to determine the maximum
record size in the file. If it exceeds the maximum record
length supported, then the file is rejected. However, certain
types of record structure have misleading information stored
about the maximum record length (usually a 0 value to indicate
unknown or no fixed maximum). These files may be selected for
packaging but subsequently turn out to have records that are
too long, giving errors at either the packing or unpacking
stages, depending on the various combinations of VMS used.
EXAMPLES:
$ VMS_SHARE *.* PACKAGE /LONGLINES
Package all the files in the current directory, with long lines
support
$ BACKUP/BLOCK=2048 [...]*.*;* PACKAGE.BCK/SAVE
$ VMS_SHARE PACKAGE.BCK PACKAGE /LONGLINES /COMPRESS
Would be a means of packaging a complete subdirectory tree
containing any mixture of files.
QUALIFIER:
/MODIFIED
PURPOSE:
Specifies that the last modified date should be used for the
purpose of date based file selection on the /BEFORE and /SINCE
qualifiers
DEFAULT:
Use the last-modified date
ASSOCIATED LOGICAL NAME:
NONE
PRIVILEGES REQUIRED:
NONE
DESCRIPTION:
Files may be selected for packaging on the basis of the dates
associated with the file, using the /BEFORE and /SINCE
qualifiers. The /MODIFIED qualifier says that the last
modified date should be used as the comparison date.
RESTRICTIONS:
The qualifier is ignored if neither the /SINCE or /BEFORE
qualifiers are specified.
Each of these qualifiers are mutually exclusive; only the last
one specified has any effect - /BACKUP, /CREATED, /EXPIRED and
/MODIFIED
QUALIFIER:
/[NO]NAME[=ident]
PURPOSE:
Select the name written into the share file to identify the
package.
DEFAULT:
Selects a name based on the name of the output share file
ASSOCIATED LOGICAL NAME:
SHARE_NAME
PRIVILEGES REQUIRED:
NONE
DESCRIPTION:
Information is written at the head of the created share file
to identify it's origins. Optionally, an identifying name can
be selected for the package and this name will be written into
the share file. This allows several different share files to
be uniquely identified even if their file names change.
/NONAME Prevents any identifying name being written
/NAME Automatically selects the name of the output
share file and writes this into the header
as the package name. The name is taken from
the output share file name.
/NAME=ident Uses the specified name `ident' as the name
of the package, and writes this into the share
file header.
The default action is /NAME, unless overridden by the
definition of the SHARE_NAME logical name
RESTRICTIONS:
NONE
EXAMPLES:
$ VMS_SHARE *.* ZAP
Packages all files into a share file called ZAP and
writes the name ZAP into the share file header as the
name of the package.
$ VMS_SHARE *.* ZAP /NAME=BANG
As above, but writes the identifying name as BANG
rather than ZAP. The output share file remains as ZAP
however.
$ VMS_SHARE *.* ZAP/NONAME
As above but no package name is written into the share
file.
QUALIFIER:
/[NO]PACKAGE_INDEX[=suffix]
PURPOSE:
Select the automatic creation of a package index file for use
by file servers.
DEFAULT:
/NOPACKAGE_INDEX No package index file is created
ASSOCIATED LOGICAL NAME:
SHARE_PACKAGE_INDEX
This logical name may be defined with any true/false value OR
with a specific file type field (starting with a dot). If
defined, it specifies the default for all subsequent executions
that do not specify the /PACKAGE_INDEX qualifier.
PRIVILEGES REQUIRED:
NONE
DESCRIPTION:
The content of the package index file is a list of the parts of
the sharefile containing all the packaged files, one name per
line. Only the name part and the type part are listed. It is
common to find such package files on mail based file servers,
where a number of files may be retrieved by issuing a single
file request for the package. Each file listed in the package
index file will be sent in response to the request.
If /NOPACKAGE_INDEX is specified, then no package index file
will be created.
If /PACKAGE_INDEX is specified, then a package index file will
be created. This file will have the same name as the individual
parts of the generated share file but with a file type of
".$PACKAGE".
If /PACKAGE_INDEX=suffix is specified, the "suffix" string must
be a file type. This creates the package index file, as above,
but with the specified suffix as the file type. suffix must be
a valid file type, including the leading period character.
RESTRICTIONS:
NONE
EXAMPLES:
$ VMS_SHARE *.* FILESERV:ZIPPO /PACKAGE_INDEX
Creates the package files as a series of parts called
ZIPPO.nnn-OF-mmm in the directory FILESERV:. The package index
file is created in this directory too and is named
ZIPPO.$PACKAGE.
$ VMS_SHARE *.* FILESERV:ZIPPO /PACKAGE_INDEX=.LIBRARY
Creates the package files as a series of parts called
ZIPPO.nnn-OF-mmm in the directory FILESERV:. The package index
file is created in this directory too and is named
ZIPPO.LIBRARY
QUALIFIER:
/PART_SIZE=nnn
PURPOSE:
Define the maximum size in blocks of each part of the generated
share file.
DEFAULT:
/PART_SIZE=30 Part size is 30 blocks
ASSOCIATED LOGICAL NAME:
SHARE_PART_SIZE
This logical name may be defined with a positive numeric value
indicating the maximum size of a part in blocks. If defined, it
specifies the default for all subsequent executions that do not
specify the /PART_SIZE qualifier.
PRIVILEGES REQUIRED:
NONE
DESCRIPTION:
Some mail systems are known to truncate mail messages if they
are larger than a certain size. Experience has shown that
messages of 32 blocks or less are fairly safe from this
problem. Thus the default part size is 30 blocks, allowing 2
blocks for the additional mail headers that accumulate on the
journey through the network.
If it is known that larger messages can pass unscathed, then
the part size can be increased. using the /PART_SIZE=n
qualifier (where n is the part size in blocks).
RESTRICTIONS:
Although there are no restrictions on the part size that can be
specified, too small a value can cause packaging to fail. This
is because certain parts of the generated share file must be
kept together in one file. If VMS_SHARE is unable to do this
because the part size is too small, an error message will be
issued and the part size should be increased.
EXAMPLES:
$ VMS_SHARE *.* PACKAGE /PART_SIZE=100
Collect all files in the current directory into a multi-part
package called "PACKAGE", where each part is no larger than 100
blocks.
QUALIFIER:
/[NO]SHARE
PURPOSE:
Selects whether the created share file parts are written out.
DEFAULT:
All parts of a share file are written.
ASSOCIATED LOGICAL NAME:
SHARE_SHARE
PRIVILEGES REQUIRED:
NONE
DESCRIPTION:
The function of VMS_SHARE is to produce a set of share file
parts that contains all of the specified files, in a form that
can be mailed out to other users. These parts are written to
disk as they are generated by the packaging process.
The /NOSHARE qualifier may be used to suppress the writing of
these parts. If specified, parts are created from the packaged
files and all normal log messages are produced, but the parts
are simply discarded rather than written to disk. This is
mainly useful as a debugging tool.
/NOSHARE suppresses the writing of parts; /SHARE causes parts
to be written out.
RESTRICTIONS:
NONE
EXAMPLE:
$ VMS_SHARE *.* ZAP/NOSHARE
Package all files into a share file called ZAP, create
the parts in memory but discard them.
QUALIFIER:
/SINCE[=date]
PURPOSE:
Specifies that all files selected must have a date associated
with them which is at or after the specified date.
DEFAULT:
The dates associated with a file are not used for selection
purposes.
ASSOCIATED LOGICAL NAME:
NONE
PRIVILEGES REQUIRED:
NONE
DESCRIPTION:
If either of the /SINCE or /BEFORE qualifiers is specified,
then each file specified in the parameter list is checked to
see if the date associated with the file is within the
appropriate date range. The file is selected for packaging only
if it does. No check is made if neither qualifier is specified
and the file is selected.
There are four dates associated with a file - Creation, Last
Modified, Expiration and Last Backup. Any of these can be used
as the basis for selection.
To select which of the four dates to use, these qualifiers are
used:
/BACKUP Last backup date used
/CREATED Creation date used
/EXPIRED Expiration date used
/MODIFIED Last modified date used
To select the date range, these qualifiers are used:
/BEFORE[=date] Select files before the date
/SINCE[=date] Select files after the date
If neither qualifier is specified, then the corresponding
constraint on the date is lifted.
It is permitted to use /SINCE and /BEFORE together to specify
both an earliest date and a latest date for the files. If no
date/time specification is given on either the /SINCE or
/BEFORE qualifiers, then the default is "TODAY".
RESTRICTIONS:
Only one of /BACKUP, /CREATED, /EXPIRED or /MODIFIED should be
used. If several are specified only the last one is used. If
none are specified, /MODIFIED is assumed.
The format of the date specification is a standard VMS
date/time specification with these exceptions:
o The date/time spec must not contain spaces
o The date/time spec must not be quoted
o Missing fields are taken from the CURRENT date/time and
NOT from midnight as with other VMS commands.
EXAMPLES:
$ VMS_SHARE *.* Z /SINCE=TODAY
This will select all files which have a modified date (the
default) at or after today's date.
$ VMS_SHARE *.* Z /SINCE=YESTERDAY /BEFORE=TODAY
This will select all files which have a modified date (the
default) sometime during yesterday.
QUALIFIER:
/[NO]SPACE_ENCODE
PURPOSE:
Selects whether all spaces in each file packaged are to be
encoded or just those which occur at the end of lines in
the share file.
DEFAULT:
All spaces will be encoded.
ASSOCIATED LOGICAL NAME:
SHARE_SPACE_ENCODE
May be defined with a TRUE or FALSE value to set the default
for the space encoding option.
PRIVILEGES REQUIRED:
NONE
DESCRIPTION:
Many mailers are known to make unauthorized modifications to
spaces within a message. This may not be significant for
text messages, but can be crucial if the space is part of the
data or program. Mailers are particularly prone to truncating
trailing blanks from lines.
Two different mechanisms are offered to cirumvent this problem
and the /[NO]SPACE_ENCODE qualifier selects the mechanism to
use.
If /NOSPACE_ENCODE is selected, blanks are left untouched
unless they occur at the end of a line in the share file. In
this case, the last space will be encoded so that, to a mailer,
it no longer looks like a space.
If /SPACE_ENCODE is selected, all blanks in a file are encoded.
This may be used for more persistently troublesome mailers that
also convert blanks inside lines, often to one or more tabs.
The default is /SPACE_ENCODE, which should get files past all
known mailers. However, the share file that is created can be
significantly bigger than with /NOSPACE_ENCODE.
RESTRICTIONS:
NONE
EXAMPLE:
$ VMS_SHARE *.* ZAP /NOSPACE_ENCODE
Package all the files into ZAP, ensuring that only
spaces at ends of lines will be encoded.
QUALIFIER:
/[NO]SPLIT[=nnn]
PURPOSE:
Select the automatic splitting of large files to be packaged,
that will not fit into the available virtual memory in their
entirety.
DEFAULT:
Files will be split if they are bigger than some value which is
a function of the user's working set extent.
ASSOCIATED LOGICAL NAME:
SHARE_SPLIT
PRIVILEGES REQUIRED:
NONE
DESCRIPTION:
VMS_SHARE is layered upon the TPU text processing package. This
does all text processing in memory. When there is a large file
to be packaged that is bigger than the available memory, TPU
will store the excess in a swap file (if running a VMS later
than 5.2). Parts of the buffer will then be copied in and out
as required. For such files, the modifications made by
VMS_SHARE are usually substantial and result in a huge amount
of copying to and from memory. The actual amount is dependent
upon the size of the file, the available virtual memory and the
exact modifications needed to the file. Generally, the copying
overhead is very high, with the result that the large files are
processed extremely slowly.
One solution is to limit the amount of a file that is processed
at one time. This is controlled by the /SPLIT qualifier. With
this option active, large files are read in smaller pieces,
that will fit individually into memory without excessive
copying, and processed separately. Once completed, the next
piece of the file is processed and so on until the whole file
has been processed.
/NOSPLIT requests that no attempt be made to limit the amount
of a file in memory. This restores the previous default
behaviour of VMS_SHARE in versions prior to 8.4.
/SPLIT requests that large files be split at an appropriate
point and each piece processed separately. This allows
VMS_SHARE to function in restricted memory environments without
excessive copying to/from disk. The maximum size is chosen
automatically as a function of the user's working set extent
quota.
/SPLIT=nnn is as above but specifies an explicit maximum memory
size (in blocks) to be used. nn is a positive integer value
(though a value of 0 equates to /NOSPLIT).
The default action is /SPLIT.
The rationale for choosing the user's working set extent as
the default value is that, for files up to this size, it is not
necessary to swap information to and from disk. This
performance is likely to remain acceptable. This does depend
on the WSEXTENT memory being available of course, which it may
not be on heavily loaded systems. Beyond this value, the file
is bigger than the available memory and swapping is assured,
which will significantly degrade performance. It is not
recommended that values higher than the WSEXTENT value
generally be used.
RESTRICTIONS:
Use of this qualifier only makes sense under versions of
VMS at or later than version 5.2. Before this, files bigger
than the available virtual memory could not be processed at
all (see the /WORK Qualifier). However, VMS_SHARE will still
accept and use the specified value if possible.
EXAMPLE:
$ VMS_SHARE *.* ZAP/SPLIT=4000
Package all the files into ZAP. Any file bigger than
4000 blocks will be split into pieces no bigger than
4000 blocks and processed separately.
QUALIFIER:
/TEMPORARY=filename
PURPOSE:
Select an alternative location for the intermediate temporary
files created during execution.
DEFAULT:
/TEMPORARY=SYS$SCRATCH:SHARE_TEMP.pid
(where `pid' is the process ID of the current process).
ASSOCIATED LOGICAL NAME:
SHARE_TEMP
This logical name may be defined with a filename specification
to be used as the location of temporary files created during
execution.
PRIVILEGES:
NONE
DESCRIPTION:
During execution, VMS_SHARE creates a temporary file containing
various parameters describing the contents of the share file
and the actions to be taken. It may sometimes be necessary to
redefine the location of this file, perhaps because of quota
problems, or if a disk is off-line etc.
/TEMPORARY=filename specifies that `filename' is to be used
as the location for the temporary file.
RESTRICTIONS:
NONE
EXAMPLES:
VMS_SHARE TEST.* PACKAGE /TEMPORARY=SYS$LOGIN:TEMP.TMP
Packages the files "test.*" into a share file called
"PACKAGE" and uses a temporary file called
"SYS$LOGIN:TEMP.TMP"
QUALIFIER:
/[NO]VERSION
PURPOSE:
Select the preservation of version numbers across the packaging
operation.
DEFAULT:
/VERSION Version numbers are preserved
ASSOCIATED LOGICAL NAME:
SHARE_VERSION
This logical name may be defined with any true or false value.
If defined, it specifies the default for all subsequent
executions that do not specify the /VERSION qualifier.
PRIVILEGES REQUIRED:
NONE
DESCRIPTION:
Version numbers may be preserved across the packaging operation
if required.
If /NOVERSION is specified, version numbers are not preserved.
During unpacking, files will be created with the next highest
available version number. If a previous version already exists,
a warning message will be issued.
IF /VERSION is specified, version numbers are preserved. During
unpacking, files will be created with the same version number
irrespective of any other versions that may exist. However, if
the specific version number is already in use, a warning
message is issued and the file is not re-created.
This option is supplied primarily for compatibility with
previous versions of the utility which did not preserve version
numbers.
RESTRICTIONS:
NONE
EXAMPLES:
$ VMS_SHARE *.* PACKAGE /NOVERSION
Package all the files but do not preserve the version numbers.
$ VMS_SHARE *.*;* PACKAGE /VERSION
Package all versions of each file in the current directory and
preserve the version numbers to keep them distinct when
unpacked.
QUALIFIER:
/WORK[=filename]
PURPOSE:
Specify the location of the work file used to store parts of a
file that cannot fit in the available virtual memory.
DEFAULT:
On versions of VMS prior to VMS 5.2, there is no work file
available and big files cannot be processed. On later
versions, the default file used is
SYS$SCRATCH:TPU$WORK.TPU$WORK unless redefined with the
TPU$WORK logical name.
ASSOCIATED LOGICAL NAME:
SHARE_WORK
PRIVILEGES REQUIRED:
NONE
DESCRIPTION:
VMS_SHARE is layered upon the TPU text processing package. This
does all text processing in memory. When there is a large file
to be packaged that is bigger than the available memory, TPU
will store the excess in a swap file (if running a VMS later
than 5.2). Parts of the buffer will then be copied in and out
as required.
Excessive use of the work file, generally caused by processing
files that are bigger than available virtual memory, causes a
dramatic slowdown in processing because of the copying
overhead to and from memory.
The size of the workfile, together with the user's Page file
Quota limits the amount of virtual memory that VMS_SHARE can
use. This in turn limits the maximum file size. The /WORK
qualifier can be used to relocate the work file, perhaps to a
disk that has a larger quota or a faster response, as an aid
to improving the speed or maximum file size supported.
/WORK requests that the default work file be used, in case
the logical name SHARE_WORK has been used to redefine the
default.
/WORK=file requests that a specific file be used.
RESTRICTIONS:
The /WORK qualifier can be specified only on versions of VMS
from 5.2 onwards as this is the first version where the
workfile is supported by the underlying TPU package.
EXAMPLE:
$ VMS_SHARE *.* ZAP/WORK=BIGDISK:SCRATCH.TMP
Package all the files as ZAP; Place the work file
onto the disk BIGDISK: using a filename of SCRATCH.TMP