! Version 7.2-007 OF VMS_SHARE
!      - 22 FEB 1990,   Andy Harper,  Kings College London UK
1 VMS_SHARE
Package a series of files into a form suitable for mailing out
across the network. 

Format:
     $ VMS_SHARE filespec sharefile
2 Errors
The following error codes may be produced. Errors are normally in
the form of standard VMS error messages although they cannot be 
suppressed with SET MESSAGE.
3 ABORT
The user has aborted the procedure with CTRL-Y or CTRL-C. 
3 CANTSPLIT
Indicates that VMS_SHARE has tried to split the share file into
two or more parts and the split point boundary is in a place
where it is not allowed to be. In this case, this is usually in
the packed TPU code which is written to the output share file. 

The usual cure is to increase the minimum size of a part so that
the split point boundary moves to a new position, hopefully past
the offending section. 
3 CHKSMFAIL
Indicates that the file just unpacked from the archive is in some
way damaged as its checksum does not match that of the original.
The share file should be checked for corruption around this file.
3 CREDIR
Indicates that the file is to be unpacked into a subdirectory and
this subdirectory needs to be created. An attempt to create that
subdirectory will be made. 
3 CREDIRFAIL
Indicates that an attempt to create the directory for the output
file, during unpacking, has failed for some reason. Probably due
to lack of disk quota or no access to the parent directory. 
It may also be because more than 8 levels of directory are 
required in which case, change the default directory up 
sufficient levels to reduce the requirement to 8.
3 CURLINEIS
An error during the processing of one of the lines of an input
file has occurred and the current line being processed is listed
for reference. This should be preceded by an actual error message
describing the problem. 
3 DBG
Various DBGxxxxxx message can be produced but only if the
debugging flag within VMS_SHARE has been turned on. This option
is restricted to the system manager. 
3 FILRDERR
Indicates that some kind of error occurred trying to read the
contents of one of the input files into the buffer. Either it has
gone away since the filename parameters were parsed or the user
has no read access to the file contents. The name of the
offending file is shown in the message. 
3 FILWRERR
An error has occurred writing to the indicated file. This is most
likely due to lack of disk quota or no write access to the parent
directory. 
3 NOOFPTS
An informational message confirming the number of parts created. 
3 NOOUTDIR
The use has specified a file to hold the created share file but
the directory in which to create that file does not exist. It
must exist before running VMS_SHARE and is not created
automatically. 
3 NOPARFIL
The temporary file used to pass parameters into the TPU program
cannot be created. This is likely due to insufficient disk quota
or no access to the parent directory. Also check the SHARE_TEMP
logical to ensure it is either not defined or defined with the
correct scratch file name. 
3 NOTINTREE
The specified file was not within or below the current directory.
This is a requirement of VMS_SHARE to prevent the recipient of a
share file unpacking and having files created in random parts of
the directory structure. If it is truly necessary to package
files in other directories, then set the default directory to a
level which is higher than all of them. 
3 OLDVER
The version of VMS currently running is not of a sufficiently
recent version to allow the unpacking of the share file to take
place. The required minimum version is stated in the message. 
3 OLDVMS
The version of VMS currently running is not of a sufficiently
recent version to allow VMS_SHARE to run. A minimum revision is
needed because of certain VMS features used that do not exist in
earlier versions. The required minimum version is indicated in
the error message. 
3 PROCESS
Indicates that file unpacking is now being performed and that the
named file will be created. 
3 SELECTED
An informational message indicating that a particular file has
been selected for inclusion into the share file.
3 SHRNOTPACK
A file with the same name as one of the generated share file
parts has been discovered. It is not possible to package a share
file into itself and so this file is rejected. 
3 TPULONGREC
Processing of a line of input has resulted in a record that is
too long to be handled by the current version of TPU and hence
cannot be processed. The line will be left as it is and probably
cause errors during transmission (such as truncation). 
2 Examples
     $ VMS_SHARE *.for SOURCE
          Package all the files ending in .FOR into the sharefile
          'SOURCE'. Parts will be created called SOURCE.1, SOURCE.2 ...
          etc.

     $ VMS_SHARE [...]*.* SBDIR
          Package all the files in all subdirectories below the
          current one. The directory structure, relative to the current
          directory, will be preserved and recreated at the unpacking
          stage.
2 Filespec
A comma-separated list of wildcarded filename specifications. All
files which match the pattern(s) are packaged. 

There are some restrictions:-
     - The output share file name may not be included in the list.
     - files ending in .DIR (normally directory files) are ignored.
     - Files must exist in or below the current directory.

A prompt is issued if no files are specified.
2 Logical_Names
Several logical names can be configured to control the operation
of VMS_SHARE. 
3 SHARE_EXCLUDE_DIRS
If defined with a comma separated list of directory
specifications, enclosed in quotes, any file matching any of the
listed directories will be excluded from the packaging operation.

Wildcards are not permitted; all directories must be listed in
full. 
3 SHARE_EXCLUDE_NAMES
If defined with a comma separated list of names, enclosed in
quotes, any file whose NAME part matches any of the listed names
will be excluded from the packaging operation. 

Wildcards are not permitted.
3 SHARE_EXCLUDE_TYPES
If defined with a comma separated list of file types, enclosed in
quotes, any file whose TYPE part matches any of the listed types
will be excluded from the packaging operation. 

Wildcards are not permitted.
3 SHARE_LOG
If defined with a logical value (YES/NO, TRUE/FALSE etc.)
determines whether the unpacking stage produces informational
messages about its progress. Error messages are always output. 

The default is to produce the informational messages.
3 SHARE_PART_SIZE
If defines, sets the maximum part size. The value is specified in
blocks and must be greater than 6. A zero value causes the
default size to be used otherwise a value less than 6 causes 6 to
be used. 

The default size is 30 blocks.
3 SHARE_REAL_NAME
Defines a string which is included at the head of the created
share file following the username of the user who created it.  It
is intended that it will contain the real name of the user (For
example, "FRED SMITH"). 
3 SHARE_VERIFY
If defined with the value "TRUE" (or 1 or "YES" etc.) then
verification of the VMS_SHARE procedure is turned on. If defined
with "FALSE" (or 0 or "NO" etc.) verifications is turned off. 

If the logical is not defined at all, verification is off.

Note that the user must have READ access to the procedure for
verification to be enabled. 
3 SHARE_TEMP
Defines the name of a file to be used as a scratch file during
the packaging operation. 

Defaults are taken from the name 
SYS$SCRATCH:SHARE_TEMP.TMP_'pid' where 'pid' is the current
Process Identification number. 
2 Operational_Notes
VMS_SHARE packages all the specified files into one or more parts
having a common filename prefix. The suffix will be the part
number. Multiple parts will be created if the total size of a
part exceeds the specified maximum size (taken from the logical
SHARE_PART_SIZE). 

Each part is encoded so that it can survive destruction when
mailed across the network through unfriendly mailers which wrap
lines, transpose characters etc. A checksum is included which can
detect damage at the receiving end. 

To unpack, all parts must be concatenated in order and the whole
executed as a command procedure. It is preferable to be in an
empty scratch directory when doing this. If the parts have been
received via mail then it is NOT necessary to remove the mail
headers between parts before concatenating them.  The unpack code
will ignore them if present. However, mail headers should be
removed from the initial part. 
2 PAKMAIL
The PAKMAIL utility may be used to send the generated parts of
the sharefile to one or more recipients over the electronic mail
network. Consult the separate help entry for full details. 
2 Sharefile
The name of the packed output file. This name will be suffixed by
the part number even if there is only 1 part created. 

A prompt is issued if no sharefile name is specified.
