V M S _ S H A R E R E L E A S E N O T E S Version 7.2-007 Feb 1990 1. INTRODUCTION Version 7.2-007 of VMS_SHARE is a maintenance release that merely fixes a number of known bugs. It introduces no new features for the user. 2. NEW FEATURES There are no new features with this release 3. BUG FIXES The following bugs have been fixed. 3.1 Version Check (7.2-001) Both the VMS_SHARE code and the created share file include checks on the version of VMS under which they run. This ensures that attempts to run on unsupported (ie very OLD) versions of VMS are trapped with a suitable warning. In previous versions, this check was not altogether correct because it assumed that the version number obtained with f$getsyi("VERSION") started with the letter "V". In some releases, this is not the case - there are "A" and "B" versions around at least! Usually to be found in mixed version clusters. The fix corrects this problem by stripping off the "V" and just comparing the numeric part. 3.2 Use of /NOLOG (7.2-002) With the inclusion of a "SET SYMBOL/SCOPE=(NOLOCAL,NOGLOBAL)" command in a previous release of VMS_SHARE, the use of the /NOLOG qualifiers on certain commands in the generated share file is redundant. These have been removed and will make the share file very slightly shorter. 3.3 Variable names in the share file (7.2-003) The TPU unpacking code placed into the share file uses several variables to hold relevant information. To save space, these have been changed to be single letter variable names where possible. In some instances, the code is restructured to remove the variables altogether. 3.4 Part Separator Check and Infinite Looping Problems (7.2-004) Because VMS_SHARE allows the share file to be created in multiple parts for ease of mailing, it includes flags to allow it to skip over any intervening 'garbage', typically mail headers and mail signatures. Two special flag lines are inserted - one at the end of a part and one at the start of a part. The unpacking code however did not fully check for the start of part flag line and consequently could be confused by mail headers or mail signatures that looked like the start of flag lines. The code has been tightened up to more fully check that the line found is a real start of part. This avoids problems of the code being stuck in infinite CPU gobbling loops. 3.5 Replacement of EXIT (7.2-006) It has been reported that, under VMS 5.3, VMS_SHARE runs into problems at the TPU 'EXIT' statement. The exact problem is unclear but seems related to the flushing of buffers. To circumvent the problem, EXIT has been replaced by 'QUIT' in both VMS_SHARE and the generated share file. 3.6 Suppression of TPU messages. (7.2-007) Because TPU produces unwanted informational messages when it starts, the code diverts these to NL: via a user mode logical name assignment. However this has the side effect of also suppressing any TPU error messages. To allow these error messages to be seen if something is wrong, the share file now only assigns the output to NL: if verification is OFF (see the logical name SHARE_VERIFY). If verification is on, all output comes to SYS$OUTPUT. 4. CHANGES IN OPERATION The following major changes in operation have occurred. 4.1 Encoding of Special Characters (7.2-005) Previous versions encoded troublesome characters using a 3 digit decimal representation of the ASCII code prefixed by an escape character. This release uses a hex encoding thus saving 1 byte for each escaped character. For small files, the file may be slightly longer because of the extra code necessary to unpack hex characters. For long files, small space savings should occur. 5. DOCUMENTATION CHANGES A number of minor changes have been applied to the user guide and to the technical info documents. No new information has been added. 6. TESTING This version of VMS_SHARE has been tested on VMS 5.1-1 but is believed to work on all versions from VMS 4.4 to VMS 5.3. However, it is not supported formally on any version of VMS other than the one on which it has been tested. 7. PREVIOUS RELEASE NOTES Release notes for previous versions are appended at the end. These give details of changes and bug fixes for those versions. V M S _ S H A R E B U G F I X E S Version 7.1-004 1. INTRODUCTION This document is an addendum to the main release notes for VMS_SHARE describing all the bugs fixed since the last major release 7.1-001 2. BUG FIX DESCRIPTIONS 2.1 Verification (7.1-002) VMS_SHARE now turns verification of the DCL code on or off based on the definition of the logical name SHARE_VERIFY. Previously no attempt was made to alter the verification setting. The environment is restored on exit. If SHARE_VERIFY is defined as TRUE (or 1 or YES etc.) then verification is enabled. If defined as FALSE (or 0 or NO etc.) or is not defined at all, verification is disabled. Note that this logical defines verification both for VMS_SHARE itself and for any unpack operations performed on the created archive. Note also that if the user has no READ access to the procedure (recommended) then verification is always disabled. The .HLP file has been updated to include a reference to this logical and its definitions. NOTE that the Version 7.1 release notes contain a comment that this logical name has been removed. This was true with release 7.1-001 of VMS_SHARE but the logical has been reinstated with release 7.1-002 2.2 Symbol Redefinition (7.1-002) VMS_SHARE now uses the SET SYMBOL command to insulate itself from any symbol definitions made by the user. Both local and global definitions of any DCL symbols are ignored. If VMS_SHARE exits normally then the original setting is restored. However, an abnormal exit may cause the new settings to be retained. This may cause confusion if a user is unaware of what has happened. Previously any external symbol definitions matching commands used internally to VMS_SHARE would cause unexpected actions and usually cause VMS_SHARE to fail. 2.3 Spurious Rejection of certain files (7.1-002) VMS_SHARE contains code to reject any attempt to include the output files in the packed archive on the grounds that packing an archive into itself is not sensible. However the code for this check was faulty due to an undocumented 'feature' of the f$integer lexical which returns 1 if a string starts with T or Y (in other words, does a conversion from boolean to integer where T,Y = 1 and F, N = 0). This caused some perfectly valid filenames to be rejected on the grounds that they had the same name as the output file. As an example, if the output file is specified as 'V' then invalid input files would be anything starting with this name followed by a number, such as 'V.1', 'V.2' etc. The bug also caused files 'V.T' and 'V.Y' to be invalid. The code has now been fixed by avoiding the use of f$integer until the string has been checked with f$type to make sure it really is a number. 2.4 Movement Of Generated CUT HERE line (7.1-003) The inclusion of the verification option (SHARE_VERIFY) was inadvertently placed BEFORE rather than AFTER the ' ... CUT HERE ... ' line in the generated share file. It has now been moved to its proper place ensuring that cutting on the indicated line does not remove the VERIFY option. 2.5 Angle Brackets in Directory names (7.1-004) If the parameters to VMS_SHARE, or the current default directory, contained angle brackets around directory specifications (For example, rather than the more normal [TEST]) then VMS_SHARE treated each file as invalid because it was not designed to handle the <> notation, which is perfectly valid VMS syntax. This problem has been cured by ensuring that all occurrences of <..> notation are translated to the more normal [..] notation before processing the filenames. The way in which this is done relys on a little known feature of the f$parse lexical function: f$parse(P1,"[]") will translate any <..> directory to [..] f$parse(P1,"<>") will translate any [..] directory to <..> However if P1 contains a version number the conversion is not done! (WHY this should be so is a mystery at this time) 2.6 Check for correct VMS version in created share file (7.1-004) The check for a minimum revision of VMS was incorrect. The current version, obtained with f$getsyi("VERSION") was being checked against "4.4" instead of "V4.4". 2.7 Check for correct VMS version in main procedure (7.1-004) No check was made in the main VMS_SHARE procedure for the correct minimum revision of VMS required. This would cause it to fail if run on a pre-VMS 4.4 system. A check has now been included. 2.8 Information on errors in HELP (7.1-004) Explanations of the error codes for both VMS_SHARE and PAKMAIL have been included into the HELP files for the utilities. There are also some minor editorial changes to the help text. 2.9 User Guide (7.1-004) A preliminary user guide is issued with this release. This describes the rationale behind VMS_SHARE, from the user's viewpoint and details of how to use both VMS_SHARE and PAKMAIL. Details of unpacking share files are included also. 2.10 Location of Break Point (7.1-004) Corrected the check for a null buffer in the routine which locates the optimum break point for a share file part. 2.11 Part Separator Insertion (7.1-004) Corrected the check for the right part separator, GOTO/label or special flag lines, by only checking the line below the separation point and not the lines on either side. This ensures that the GOTO/LABEL code is only used when the split point immediately precedes DCL code. 3. KNOWN PROBLEMS There are no known problems at this time. Andy Harper 9-AUG-1989 V M S _ S H A R E R E L E A S E N O T E S Version 7.1 Aug 1989 1. INTRODUCTION Version 7.1 of VMS_SHARE has been completely rewritten to eliminate long standing bugs, and to improve performance by utilising new algorithms for the packing and upacking of files. Details of the changes from the previous versions are given below. 2. NEW FEATURES 2.1 Subdirectories VMS_SHARE now supports subdirectories. The user may package a series of files existing in the directory tree within/below the current directory. The directory structure will be recreated at the unpacking stage as an equivalent tree beneath the current directory. All required directories are automatically created as required. For example: $ VMS_SHARE [.TPU...]*.*,[.DATA]*.* PACKAGE.SHAR Will package the directory tree beneath [.TPU] and the subdirectory [.DATA]. During unpacking, these subdirectories will be created automatically below the current directory. It was originally decided to make the directory handling a bit like BACKUP, allowing any directory to be packaged and individual items to be selected at unpack time. However this proved to be extremely difficult in DCL and so was abandoned. It may appear in a future release. In order to prevent files appearing in essentially random directories it was decided to adopt the above compromise. It retains sufficient flexibility to deal with most package structures but maintains a known directory structure that will avoid files being placed randomly as far as the receiving user is concerned. 2.2 DEBUG code To assist those who enhance and develop VMS_SHARE, a large amount of debug/trace code is included into the source. By redefining a simple global constant value, this debug code can be turned on or off to assist in tracking down faults. 2.3 New Part Splitting Algorithms The algorithms used for splitting parts have been extensively redesigned to ensure minimal use of memory for buffers. Essentially, VMS_SHARE now uses only enough memory to hold the sum of two parts and the largest file. We read a single file, add as much as possible to the part buffer and then write the part buffer, removing the equivalent info from the original file buffer. The algorithm for finding the optimum part breakpoint now uses a binary search instead of a sequential search for speed. 2.4 New Unpacking Algorithms The algorithm used to unpack code, embedded in the TPU code stored in the output share file, has been redesigned to need less error checking and hence less code. The TPU code is also packed more compactly than before giving improved compilation speed as well as execution speed. 2.5 Error and Status Messages VMS_SHARE now produces messages similar to the standard VMS form. Messages are produced to keep the user informed of progress (these normally go to sys$output) and error messages (which normally go to sys$error). Initial informational messages from TPU, as it reads in the source, are also printed. It is hoped that in a future release some way can be found to turn this off. 2.6 Exclusion Files By defining certain logical names, it is possible to force the exclusion of particular files from the sharefile. There are three possibilities: exclusion by directory, exclusion by name, and exclusion by type. Each logical name may be defined as a comma separated list of items (the list MUST be enclosed within quotes). Any file that matches is excluded from the sharefile. Wildcards are not permitted. Each must be a fixed string. Thanks go to Joe Meadows (JOE@BITNET.FHCRCVAX) for the general idea and basic mechanism. 2.6.1 SHARE_EXCLUDE_DIRS This logical is a list of directory names (in their full format). Any file with the same directory name is automatically excluded. For example: DEFINE SHARE_EXCLUDE_DIRS "[X],[X.Y],[X.Y.Z],[TWEETY]" excludes any file in any of the listed directories. If this logical is absent, then no files are excluded on the basis of their full directory name. 2.6.2 SHARE_EXCLUDE_NAMES This logical is a list of filenames. Any file with the a matching NAME part is automatically excluded. For example: DEFINE SHARE_EXCLUDE_NAMES "MAIN,TRACE,MAIN_CLD" If this logical is absent, then no files are excluded on the basis of their filename. 2.6.3 SHARE_EXCLUDE_TYPES This logical is a list of file types. Any file with a matching TYPE part is automatically excluded. Files with a type of .DIR are automatically excluded as these are directory files with no valid contents at the time of unpacking. For example: DEFINE SHARE_EXCLUDE_TYPES ".OBJ,.EXE" excludes any file with a type of .OBJ, .EXE or .DIR If this logical is absent, then no files are excluded on the basis of their file type (except .DIR). 3. BUG FIXES A number of long standing bugs have been fixed. 3.1 Bad split points Occasionally, the split point was chosen badly such that the part separators were wrong. In particular, the $GOTO/Label: sequence could appear right after the $COPY command due to the method by which use of $GOTO was decided. This algorithm has been redesigned and the problem should no longer occur. 3.2 Hangs During Trailing Blank Processing When wrapping lines containing trailing blanks, the code would sometimes hang in an infinite loop or fail to split on a non-blank character. This has now been fixed. 3.3 Temporary Files All temporary files now have a unique name derived from the PID of the current process and are created in the SYS$SCRATCH directory by default. The choice of temporary filename and location may be overridden by defining the logical name SHARE_TEMP to whatever is desired. 4. CHANGES IN OPERATION There are several significant changes in the operation of VMS_SHARE. 4.1 Name of Share File Previously, the share file name was suffixed by a string of the form '_n_OF_m' where 'n' was the part number and 'm' was the total no of parts. The share file name is now suffixed only by the 'n' value - part number. This change is a consequence of the new algorithms used to create the parts, whereby the total number of parts is not known at the time of writing a particular part to a file. 4.2 Obsolete logical names Logical names supported in previous versions of VMS_SHARE to control verification of the operation of the package are no longer supported. These functions have been replaced by the new debugging code. These logicals were SHARE_VERIFY and SHARE_DISPLAY. 4.3 CHECKSUM display Messages regarding checksums are now suppressed if they are correct, making it easier to spot those that are incorrect. 4.4 Version Numbers The original version numbers of the packaged files are preserved at the unpacking stage. Previously, all files created would have a version number of 1. This change allows multiple versions of the same file to be packaged if required. 4.5 Check Output File Existence During unpacking, the output file is checked to see if it already exists. If it does, then the file is not overwritten. Instead the file is skipped and a message written to that effect. This prevents the previous problem where the existence of the file caused the new version to be ignored without comment and a checksum failure to be produced. 5.0 TESTING The software has been tested under VMS 4.7 and VMS 5.1-1. It should be noted that this version of VMS_SHARE is not supported on other versions of VMS, although it is believed to work on all versions between 4.4 and 5.1-1 inclusive.