V M S _ S H A R E A guide to use for the general user By Andy Harper Kings College London __________________________________________________________________________ C O N T E N T S 1. INTRODUCTION 2. OVERVIEW 3. USING VMS_SHARE 3.1 Input File specification 3.2 Output File specification 3.3 Examples 3.4 Restrictions on files 4. USING PAKMAIL 4.1 User specification 4.2 File specification 4.3 Part specification 4.4 Comment specification 5. CONTROLLING OPERATION WITH LOGICAL NAMES 5.1 Exclusion by directory 5.2 Exclusion by name 5.3 Exclusion by type 5.4 Logging 5.5 Setting the size of a part 5.6 Inclusion of user's real name 5.7 Location of temporary files 5.8 Verification 6. HOW TO UNPACK A SHARE FILE 6.1 Command file 6.2 Dealing with multiple part share files 7. REFERENCES: [1] VMS_SHARE Technical Information supplement [2] VMS_SHARE Release notes [3] On-line HELP _________________________________________________________________________ Version 7.2-007 22 FEB 1990 Revision 2 1. INTRODUCTION With the advent of worldwide computer networks and electronic mail systems, it becomes possible to use these as a means of distributing software packages. This has the advantage of providing a quick, cheap and relatively reliable means of getting them to the end user. Unfortunately, mail systems are not necessarily 100 % reliable! In many cases, they are fussy about the format of the information they will accept and may corrupt information if the format strays outside certain boundary conditions. The VMS_SHARE package is designed to allow complete software packages to be sent without worrying about these limitations. It has a knowledge of a wide range of limitations and encodes the information into a form that is more acceptable to the network mail systems. This document describes how to use the components of the system; in particular, the VMS_SHARE utility itself and the PAKMAIL utility for mailing the output to one or more recipients. Also described is the mechanism for recombining the parts and recreating the original input files. The release notes for the package describe new features and general changes from previous releases [Reference 2]. 2. OVERVIEW There are two basic components to the VMS_SHARE package. The first is the VMS_SHARE utility itself: From a user specified set of input files, VMS_SHARE 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 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]. The second utility is PAKMAIL. This gathers the generated pieces of the share file and mails them to one or more recipients across the electronic mail network using the VMS MAIL utility. 3. USING VMS_SHARE VMS_SHARE is usually made available via a global symbol, so the command for activating it is: $ VMS_SHARE where is an input file specification (see below) and 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 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.2 Output File specification The output file name is used as a template to construct the individual parts of the share file. The name supplied here is suffixed by a 'part number' from 1 upwards. For example: An output filename of: PACKAGE.PRELIM would generate files called: PACKAGE.PRELIM_1 PACKAGE.PRELIM_2 ... As many parts as necessary to contain the whole package are generated. 3.3 Examples Typical examples of the use of VMS_SHARE would be: $ VMS_SHARE [...]*.*;* ARCHIVE.SET Archive the whole of the directory tree, starting from the current directory into a share file with a template name of "ARCHIVE.SET". This would generate files called "ARCHIVE.SET_1", "ARCHIVE.SET_2" etc. $ 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." ie "VI.1", "VI.2" etc. When unpacked, the tree structure of the original files will be preserved. 3.4 Restrictions on files 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 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. 4. 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 parts [comment] Each of the parameters is explained below. 4.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""" 4.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.TEST" will cause the package to send these files: PACKAGE.TEST_1 PACKAGE.TEST_2 ... 4.3 Part specification This is simply the total number of parts in the package. It controls how many files to be sent to each recipient. A typical example of a PAKMAIL command would be $ PAKMAIL NET%"""FRED@SCROUNGING-SITE""" PACKAGE.TEST 5 4.4 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.TEST 1/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.TEST 5 "(Beta-Test v2)" Then the generated subject line would look like this: Subj: PACKAGE.TEST (Beta-Test v2) 1/5 5. CONTROLLING OPERATION WITH LOGICAL NAMES VMS_SHARE will operate satisfactorily with all of its default settings. However a number of options are available to tailor its operations to local requirements. Each of these options is controlled through a logical name definition of the form "SHARE_xxxx" where xxxx is the particular option in question. Options are available to exlude files on the basis of directory, name or type; to log or not log certain informational messages; to determine the maximum size of each part; to force inclusion of an identifying string into the share file; to specify the location of temporary files, and to verify operation of the code. 5.1 Exclusion by directory If the logical name SHARE_EXCLUDE_DIRS is defined with a comma-separated list of non-wildcarded directory names, then any file which has a similar directory specification will be excluded from the share file. For example, $ define share_exclude_dirs "[JIM.EXE],[JIM.OBJ]" Any files in these two directories will be excluded. Note that the directory name MUST be given in full. If the logical name is not defined, then files are not excluded on the basis of their directory name. 5.2 Exclusion by name If the logical name SHARE_EXCLUDE_NAMES is defined with a comma-separated list of non-wildcarded filenames, then any file which has a similar name specification will be excluded from the share file. For example, $ define share_exclude_names "TEST,DUMMY" Any files with either of the two names will be excluded. If the logical name is not defined, then files are not excluded on the basis of their file name. 5.3 Exclusion by type If the logical name SHARE_EXCLUDE_TYPES is defined with a comma-separated list of non-wildcarded file types, then any file which has a similar file type specification will be excluded from the share file. For example, $ define share_exclude_types ".EXE,.DIR,.OBJ" Any files with these file types will be excluded. Files with a type of .DIR are always excluded regardless. If the logical name is not defined, then files are not excluded on the basis of their file type, except that .DIR files are always excluded. 5.4 Logging Informational messages are normally sent to SYS$OUTPUT by default. The logical name SHARE_LOG can be defined with a TRUE or FALSE value to determine whether such messages are produced. If undefined, a TRUE value is assumed. For example: $ define SHARE_LOG FALSE will turn off informational messages. Not all messages can be turned off. In particular, error messages are always produced on SYS$ERROR. 5.5 Setting the size of a part Each part of the share file is limited to a maximum size of 30 blocks by default. VMS_SHARE will split at a point just below this in general (never above) to guarantee that no share file part is more than 30 blocks long. The default of 30 blocks can be changed by defining the logical name SHARE_PART_SIZE to whatever size is required. The only restriction is that it must be a minimum of 6 blocks. Values below 6 are treated as 6. When determining the best part size to use, remember that passage through mail systems generally add a lot of headers to the message, increasing its size by several blocks. Allow for this when choosing the maximum part size. For example: $ define SHARE_PART_SIZE 200 changes the maximum part size to 200 blocks. 5.6 Inclusion of user's real name If the logical name SHARE_REAL_NAME is defined, then its value is included following the username at the head of the created share file. The normal translation of this logical name should be the user's real name. For example: $ define SHARE_REAL_NAME "Fred Smith" 5.7 Location of temporary files VMS_SHARE creates temporary files in the SYS$SCRATCH directory with a unique name based on the process identification number. If the logical name SHARE_TEMP is defined, this redefines the name/location of the temporary file. For example: $ define SHARE_TEMP SYS$SCRATCH:DUMMY.TMP redefines the temporary file name. 5.8 Verification If the user has read access to the procedure, then verification of its actions may be turned on by defining the logical name SHARE_VERIFY to have a TRUE value. If the logical name is undefined or has a FALSE value then no verification takes place. For example: $ define SHARE_VERIFY TRUE turns on verification IF the user has read access. In general, only the system manager has read access to the procedure and so this option is restricted. 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. 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