Zoo 2.0 on VAX/VMS
by
Rahul Dhesi
The zoo archiver is used to create and maintain archives containing multiple files that may be stored in compressed format. Consult the zoo
manual for more details. This document describes those features of
VAX/VMS zoo that are specific to the VAX/VMS implementation.
INSTALLATION
The file "descrip.mms" is a makefile suitable for use with DEC's implementation of make, called MMS. To avoid any confusion, delete the file
called "makefile" as that is not for VAX/VMS systems and it might confuse MMS. With all source files in the current directory, simply type
MMS and wait while all files get compiled and linked. Then give the
command "mms fiz" to build "fiz.exe", and "mms blif" to build "bilf.exe".
If your system does not have MMS, execute the "vmsbuild.com" script.
The result should be the executable program, "zoo.exe", "fiz.exe",
and "bilf.exe".
Optionally, the command "mms zoobig.exe" will create a version of the
executable that is linked without the shareable library. This may be
more portable if you intend to transfer it to an VMS system that does
not have its own C compiler. But "zoobig.exe" will be about twice the
size of "zoo.exe".
To run zoo, bilf, and fiz, you will need to set up symbols by giving
commands similar to the following, either by typing them at the system
prompt or by putting them in your "login.com" file.
$ zoo :== $ user$disk:[userdir]zoo.exe
$ fiz :== $ user$disk:[userfir]fiz.exe
$ bilf :== $ user$disk:[userdir]bilf.exe
In place of "user$disk" use the name of the device on which
your login directory is located, and instead of "userdir" use
the name of the directory in which you have placed the executable
programs "zoo.exe" and "fiz.exe".
WARNING -- VMS BUGS
VAX/VMS peculiarities cause unusual bahavior.
- VMS C does not preserve uppercase characters in a command line. To
specify a command containing an uppercase character, enclose the
command in double quotes. For example, the command
zoo aM stuff *
will not work under VMS.
double quotes like this:
To make this command work under VMS, use
zoo "aM" stuff *
- For most text files that are not in stream-LF format, VMS returns
an incorrect file size to zoo. This will be evident if you use the
"f" modifier to tell zoo to archive files without compression.
Files that were in stream-LF format will be stored with the correct
size; other text files will be stored with an incorrect value for
the original size of the file.
When such files are extracted, however, they are extracted in
stream-LF format, which is the only file format that VMS seems to
handle correctly. Thus, so far as I can determine, no file contents are actually lost, and the only evidence of the problem is
that in archive listings, files stored without compression may
still appear to be compressed by about 1 to 5 percent, or occasionally by some meaningless value.
- VAX/VMS uses many different types of file structures. Zoo creates
archives in stream-LF format, and all archives used by zoo in any
way must be in this format. It is dangerous to use zoo on an
archive that is in any other format, because it may permanently
corrupt the archive contents. Thus, if you have uploaded an
archive to a VMS system using Kermit, do not try to manipulate it
with zoo until you have converted it to stream-LF format. File
conversion instructions are given later in this document.
- The VAX/VMS batch system causes the C statement
fflush(stdout);
to become equivalent to:
printf("\n");
The result is that if files are added to a zoo archive from a batch
run, the batch log will look very strange and contain spurious newlines.
ARCHIVING SELECTED FILES
Zoo can read filenames from standard input. This allows you to use an
external program to generate a list of files to be archived. When this
list is fed to zoo, it will archive only the selected files.
For this example, assume that files are to be archived in an archive
called "backups.zoo".
To achieve redirection of input under VAX/VMS, the following steps are
necessary:
1.
Create a file containing the filenames to be archived.
this file is called "names.lis".
2.
Redirect zoo's standard input thus:
Suppose
$ define /user_mode SYS$INPUT names.lis
3.
Invoke zoo thus:
$ zoo "aI" backups
This command
its standard
logical name
"names.lis",
line will cause zoo to read a list of filenames from
input, and archive them into "backups.zoo". Since the
SYS$INPUT was changed to refer to the file
zoo will read filenames from that file.
A good way of creating a list of files to be archived is to use the vms
"directory" command. Include at least the switches shown:
$ directory /noheading /notrailing /column=1 /output=names.lis
This tells VMS to produce a list of filenames, one per line, and to
store the resulting output in the file "names.lis". You can also add
additional selection options. For example, to select all files that
have been modified in the last 12 hours:
$ dir/nohead/notrail/col=1/out=names.lis/since=-12:00/modified
A good way to decrease the effort is to create a symbol as follows:
$ select:=="dir/nohead/notrail/col=1/out=names.lis/modified/since="
Now you can archive all *.c files modified in the last 60 minutes by
giving the following commands:
$ select -1:00:00 *.c
$ define/user sys$input names.lis
$ zoo "aI" backups
FILE TRANSFERS WITH KERMIT
Zoo archives can be uploaded to a VAX/VMS system and downloaded from it
using Kermit. Due to VMS limitations, some file conversions must be
done to avoid a corrupted zoo archive.
Zoo always expects zoo archives to be in stream-LF format. However, the
standard VAX/VMS Kermit does not create stream-LF files, and treats them
as text files when it reads them, resulting in corrupted downloads.
Thus you must handle Kermit transfers with care. The following discus-
sions refers solely to the standard Kermit-32, which I believe is from
the Stevens Institute of Technology. If the following instructions are
carefully followed, you should be able to transfer zoo archives between
a VAX/VMS system and a microcomputer running Kermit.
KERMIT UPLOADS: To transfer a zoo archive from a microcomputer to a
VAX/VMS system, do the following.
1.
Invoke VAX/VMS Kermit as shown below. It will prompt you with the
string "Kermit-32>". Give it a command as shown to tell it to
receive a binary file:
$ kermit
Kermit-32> set file type binary
Kermit-32> set block-check 3
Kermit-32> receive
Note: Do not use the command "set file type fixed".
it will not work.
In most cases
The command to set the block-check is optional, but tells Kermit to
use a 16-bit CRC, which is much more reliable than the default 6bit CRC. Use this command if your version of Kermit does not use a
16-bit CRC by default.
2.
At this point, VAX/VMS Kermit is waiting for you to send it a file.
Now tell your local Kermit to send the file. On an MS-DOS system,
using MS-Kermit, you would do this by first typing the local escape
sequence to get to the local mode, where the prompt is "MSKermit>", then telling your local Kermit to send the zoo archive as
a binary file. A typical sequence of commands is:
(type escape sequence to get back to local mode)
MS-Kermit> set eof noctrl-z
MS-Kermit> send stuff.zoo
It is important that your local Kermit send the zoo archive as a
binary file, not a text file. How you do this depends on your system; on MS-DOS systems it suffices to give say "set eof noctrl-z".
3.
Wait until the Kermit upload is complete. Then tell your local
Kermit to go into terminal mode (usually by giving the command CONNECT), and exit from VAX/VMS Kermit with the command EXIT. A typical sequence is:
MS-Kermit> connect
(stuff from MS-Kermit printed...)
(hit carriage return if necessary to get the next prompt)
Kermit-32> exit
$
Now you are back at the VAX/VMS prompt. At this point, you must
convert the uploaded zoo archive, which is currently in binary format, to stream-LF format so that it can be used by VAX/VMS zoo.
You do this by using the Bilf utility, which can convert files
between binary and stream-LF formats. Give the command:
$ bilf l stuff.zoo
4.
After Bilf has done the conversion, you will have a new generation
of stuff.zoo that is in stream-LF format. Now you can manipulate
it normally with VAX/VMS zoo.
DON'T TRY TO USE ZOO TO MANIPULATE AN UPLOADED ARCHIVE WITHOUT PERFORMING THE CONVERSION TO STREAM-LF FORMAT, ELSE YOU MAY PERMANENTLY DESTROY
ARCHIVE CONTENTS.
KERMIT DOWNLOADS: Before downloading a zoo archive from VAX/VMS to a
microcomputer, you must convert it to binary format.
Then use VMS
Kermit normally. A sample sequence is shown.
1.
Convert the zoo archive to binary format.
$ bilf b stuff.zoo
2.
Invoke VMS Kermit and tell it to send the file.
$ kermit
Kermit-32> set block-check 3
Kermit-32> send stuff.zoo
3.
Get back to your local Kermit and tell it to receive a binary file.
(type escape sequence to get into local mode)
MS-Kermit> set eof noctrl-z
MS-Kermit> receive
(transfer takes place)
FILE TRANSFER SUMMARY
Here are pictorial summaries of the steps involved in performing file
transfers of zoo archives using Kermit.
======================================================================
DOWNLOADS:
files on a VMS
system to be archived
using zoo
|
archive created |
using zoo.exe
|
or zoobig.exe
|
on a VMS system |
v
zoo archive on VMS
bilf b
zoo archive on VMS, in
in fixed-length
<---------------binary format
|
|
| archive transferred
| from VMS to microcomputer
| using Kermit; receiving
| Kermit must be told this
| is a binary file; sending
| Kermit may need to be told too
|
v
zoo archive
on microcomputer
system
in stream-LF format
======================================================================
UPLOADS:
zoo archive
on microcomputer
system
|
|
| archive uploaded to VMS using Kermit;
| receiving Kermit on VMS must be given
| command "set file type binary"
| (NOTE: "set file type fixed" will
| usually not work); sending Kermit
| must be told this is a binary file
|
v
zoo archive on VMS,
bilf l
zoo archive on VMS, in
in variable-length
---------------->
in stream-LF format
binary format
|
| extract
| normally using
| zoo on VMS
|
v
files extracted from zoo
archive on a VMS system
======================================================================
ENSURING ARCHIVE INTEGRITY
After performing a transfer of a zoo archive using Kermit (and performing any file conversion necessary for VMS), make it a habit to immediately test the integrity of the transferred archive with the -test command of zoo, illustrated for VMS:
$ zoo -test stuff
In addition, also get a listing of the archive contents:
$ zoo -list stuff
If neither command reports an error, it is reasonable to assume that
archive integrity was not harmed by the Kermit transfer.
The -test command tests the integrity of each stored file. The -list
command tests the integrity of the internal archive structure. Both are
checked using separate cyclic redundancy codes, one for each archived
file, and one for each directory entry in the archived. (Actually, the
-list command ignores deleted entries, so if the archive contains any,
use the "ld" command instead.)
WILDCARDS
All implementations of zoo on all systems use the same wildcard characters: "*" matches any sequence of zero or more characters, and "?"
matches any one character.
ADDING FILES: For specifying directory names when adding files, use the
usual VAX/VMS syntax. Thus, to recursively archive all files in the
current directory and all its subdirectories, the command syntax is:
$ zoo a stuff [...]*
The character range wildcard of the form "c-c" is also available, which
will select all files beginning with the specified character range.
For example,
$ zoo a stuff [...]a-d [...]x-z
will archive all files beginning with the characters a through d, and
with the characters x through z, in the current directory and all its
subdirectories. A side-effect of this is that during addition to
archives, dots in filenames must be explicitly matched. Thus to add
all files with an extension of DOC, you would type:
$ zoo a stuff *.doc
and "*doc" will not work. As a special case, a trailing "*.*" in any
filename you specify can always be replaced by just a trailing "*".
The safest rule to follow when adding files is to always specify the
dot in each filename.
EXTRACTING FILES: During extraction, both the directory name and the
filename must be specified according to zoo syntax. Thus you could say
$ zoo x stuff [*xyz*]*.doc
to extract all archived files with filenames that match "*.doc" and
that contain the string "xyz" in the directory name.
syntax for selecting directories won't work here:
$ zoo x stuff [...]*.doc
Note that VMS
! won't work for extraction
If you do not specify the directory name at all, zoo will only perform
the match against filenames; thus
$ zoo x stuff *.doc
will extract all files matching *.doc regardless of the directory name.
Also note that if you specify extraction of "*.*", as in
$ zoo x stuff *.*
it will result in the extraction of files whose filename contains at
least one dot. Similarly, the command
$ zoo x stuff *_*
will select all filename containing at least one underscore.
To extract all files, specify no filename, e.g.
$ zoo x stuff
or use "*" rather than "*.*".
SAFEST RULE OF THUMB: WHEN SELECTING FILES ON DISK, SPECIFY THE DOT IN
EACH FILENAME; WHEN SELECTING FILES INSIDE A ZOO ARCHIVE, SPECIFY A
DOT ONLY IF YOU NEED ONE. But to select all files, you can always just
use "*".
FILE GENERATIONS
When a file is added to an archive, the generation number (if any) that
it is given in the archive is not related to the generation number it
had in the VAX/VMS filesystem. At extraction time a new version is
always created for an extracted file. The overwrite option ("O") does
not cause overwriting, but simply suppresses the warning message that
zoo normally gives when it finds that a file about to be extracted
already exists.
FILE STRUCTURES
At extraction time, zoo preserves all data bytes in binary files, and
stores all text files as lines of text terminated with linefeeds. The
internal file structure maintained by DEC's RMS is not currently
preserved. (Support for this is planned for the distant future.)
Thus, the following two types of files can be safely archived and
restored:
- All text files are extracted in stream-LF format. Most VMS utilities that accept text files will accept such files. The EDT editor may complain, but will still work.
- VMS executable files, when stored and then extracted, are
extracted in stream-LF format. Such files can be restored to
their original state using Bilf with the "b" option. (However,
current versions of VAX/VMS seem to be able to load and execute
stream-LF files, so conversion may not be necessary.)
HANDLING VMS EXECUTABLE FILES.
called "xyz.exe":
You can archive an executable program
$ zoo a stuff xyz.exe
$ delete xyz.exe;*
Now the only copy of xyz.exe is in the archive "stuff.zoo".
it:
Extract
$ zoo x stuff xyz.exe
The extracted copy of "xyz.exe" is in stream-LF format and VMS may or
may not execute it. Now we convert it back to fixed-length record format thus:
$ bilf b xyz.exe
$ purge xyz.exe
Now "xyz.exe" has been converted to binary format and can be executed.
It should be identical to the original copy of "xyz.exe" that was
archived.
TEXT FILES FROM OTHER SYSTEMS. A text file archived on a different
computer system will use either linefeeds, or carriage returns plus
linefeeds, as line terminators. Text files with linfeeds only can be
be extracted and used exactly as if they had been archived on a VAX/VMS
system. Text files containing carriage returns plus linefeeds will,
when extracted, contain a spurious carriage return at the end of each
line. This extra carriage return can be removed using EDT's "substitute" command while in screen mode. Simply replace all carriage returns
with nothing. The VMS C compiler currently appears to accept trailing
carriage returns in files without any trouble.
Text files trasnferred from MS-DOS or CP/M or similar systems may contain a trailing control Z character. This may cause problems on VMS
and should be edited out with a text editor.
-- Rahul Dhesi 1988/02/04
Revised 1991/07/07