Inside Multimedia 1995 July/IMM0795.ISO/share/os2/zoo21_32/source/vmsbugs.doc

Text File | 1993-12-17 | 19KB | 483 lines

                           Zoo 2.0 on VAX/VMS
                                   by
                              Rahul Dhesi


The zoo archiver is used to create and maintain archives containing mul-
tiple 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 imple-
mentation of make, called MMS.  To avoid any confusion, delete the file
called "makefile" as that is not for VAX/VMS systems and it might con-
fuse 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.  To make this command work under VMS, use
     double quotes like this:

          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 con-
     tents 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 occasion-
     ally 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 new-
     lines.


                        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.  Suppose
     this file is called "names.lis".

 2.  Redirect zoo's standard input thus:

          $ define /user_mode SYS$INPUT names.lis


 3.  Invoke zoo thus:

          $ zoo "aI" backups

     This command line will cause zoo to read a list of filenames from
     its standard input, and archive them into "backups.zoo".  Since the
     logical name SYS$INPUT was changed to refer to the file
     "names.lis", 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".  In most cases
     it will not work.

     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 6-
     bit 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 "MS-
     Kermit>", 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 sys-
     tem;  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 CON-
     NECT), and exit from VAX/VMS Kermit with the command EXIT.  A typi-
     cal 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 for-
     mat, 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 PERFORM-
ING 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     <----------------    in stream-LF format
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

======================================================================

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 perform-
ing any file conversion necessary for VMS), make it a habit to immedi-
ately test the integrity of the transferred archive with the -test com-
mand 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 charac-
ters:  "*" 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.  Note that VMS
 syntax for selecting directories won't work here:

      $ zoo x stuff [...]*.doc        ! 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 utili-
      ties that accept text files will accept such files.  The EDT edi-
      tor 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.  You can archive an executable program
 called "xyz.exe":

      $ zoo a stuff xyz.exe
      $ delete xyz.exe;*

 Now the only copy of xyz.exe is in the archive "stuff.zoo".  Extract
 it:

      $ 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 for-
 mat 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 "substi-
 tute" 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 con-
 tain 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