
                        ZDESC, RDESC, and CPDESC
                  Utilities for 4OS2 File Descriptions
                              Version 1.2
                             June 26, 1995

                             Gene Pizzetta
                             481 Revere St.
                            Revere, MA 02151
                         CompuServe:  72060,505

CPDESC.CMD is a simple OS/2 REXX program that copies a specified file's
description to one or more additional files.

ZDESC.CMD and RDESC.CMD are simple OS/2 REXX programs designed to save
and restore your 4OS2 file descriptions so they won't be lost when you
archive the files.  They are discussed in more detail below.

These utilities require REXX, OS/2, and 4OS2 to run properly.  They will
not work under OS/2's CMD.EXE.


                                 CPDESC
                                 ======

CPDESC copies the 4OS2 or 4DOS description for a given source file and
assigns that description to one or more target files.  The original
description is not changed.

Two filespecs are required:

    CPDESC source target

The source file name must refer to a single specific file.  The target
file name, however, may contain "?" and "*" wildcard characters.  The
description will be assigned to all matching target files.

If an existing DESCRIPT.ION file matches the target filespec (e.g.,
"*.*"), the match will be ignored.  In no case will a description be
assigned to a DESCRIPT.ION file.

There are no command line options, but brief usage instructions will be
displayed if "/?" or "-?" are given, or if the filespecs are missing.

LIMITATIONS
===========

CPDESC uses the 4OS2 @DESCRIPT[] function to obtain the file
description.  A limitation of 4OS2 does not allow the use of
double-quotes for filenames with embedded spaces when SETDOS /X-7 is
used.  Failure to use the /X-7 parameter with the @DESCRIPT[] function
could unceremoniously crash the program if the description contains a
grave accent (back-quote).  I haven't been able to find a way around
this problem, so I decided to disallow embedded spaces in the source
filename and exit gracefully in that case.

Long filenames without embedded spaces are okay for both source and
target files, and embedded spaces are okay for target filenames.


                            ZDESC and RDESC
                            ===============

ZDESC writes the descriptions for files in the current directory into a
batch file called MAKEDESC.BTM and, optionally, into MAKEDESC.BTM files
in lower subdirectories.  The batch file(s) can be saved into an archive
with the other files.

RDESC restores the file descriptions by executing the MAKEDESC.BTM batch
file in the current directory and, optionally, MAKEDESC.BTM files in
lower subdirectories.  Actually, the MAKEDESC.BTM files can be executed
directly, but RDESC makes the process more convenient if descriptions
must be restored in subdirectories.

OPTIONS
=======

If either program is called with no parameters, they will do their thing
only in the current directory.  If they are called with an "S" or "R"
option, they operate in the current directory and any lower
subdirectories.  "S" and "R" do the same thing, but I allowed both
because you might find it hard to remember whether to use "S" for
subdirectories or "R" for recursing into subdirectories.

The options may be preceded by a slash (/) or a dash (-) or nothing at
all.  I allowed that for the same reason.

If any other parameter is given on the command line, including "/?" or
"-?", the programs will display a brief usage message.

LIMITATIONS
===========

When entered interactively or with a description editor, file
descriptions can contain several characters that cause problems when
used from a 4DOS or 4OS2 command line.  ZDESC handles most of these
embedded special characters -- double-quotes, redirection and piping
characters, command separators, parameter flags, etc. -- with no problem
at all.  Embedded 4OS2 escape characters and grave accents
(back-quotes), however, are problems require special handling.  That
special handling is reliable with CPDESC, but less so with ZDESC.
Unfortunately, ZDESC writes a MAKEDESC.BTM file that will be run later,
and there is no guarantee that the escape character will be the same
when the BTM file is run as it was when the file was created.  If
MAKEDESC.BTM is run under 4DOS, the escape character will most likely be
different.

It is best to avoid using grave accents and escape characters in file
descriptions.  Nevertheless, 4OS2's default escape character is the
caret, and finding one in a file description is probably not that
unusual, especially if the description comes from 4DOS.

If a MAKEDESC.BTM file already exists when ZDESC runs, it will be
deleted without notice.

Executing MAKEDESC.BTM will not affect any existing descriptions of
other files in the directory.

ZDESC and RDESC operate only on the current directory and, optionally,
its subdirectories.

ZDESC assumes all the files in the directory will be included in the
archive.  There is no way to get ZDESC to save the descriptions of
selected files.

This last limitation is no problem if you create your archives from a
scratch directory dedicated to that purpose.  That's probably the best
way to go anyway.


FULLY-AUTOMATIC OPERATION
=========================

Saving the file descriptions into archives can be fully-automated by
incorporating ZDESC and RDESC with your favorite archiving tool in a
batch file.  The examples below use the free OS/2 ZIP and UNZIP
archivers from Info-Zip.

4ZIP.BTM and 4UNZIP.BTM give brief usage information if called with no
parameters.  Normally they are called with the name of the ZIP file to
be created or extracted.  4ZIP also allows including an additional
option for ZIP.EXE, such as "-9" for maximum compression.

4ZIP.BTM calls ZDESC.CMD with the "R" option to create MAKEDESC.BTM
files in the current directory and its subdirectories (if they exist).
It then calls ZIP.EXE with the "-r" option so that files in the current
directory and any subdirectories are included in the given ZIP archive.

4UNZIP.BTM calls UNZIP.EXE to extract all files in the given ZIP
archive.  UNZIP automatically creates any subdirectories saved in the
archive.  4UNZIP.BTM then calls RDESC.CMD with the "R" option to execute
MAKEDESC.BTM files in the current directory and its subdirectories (if
they exist).  Finally, 4UNZIP.BTM asks if you want to delete the
MAKEDESC.BTM files.  If you answer "Y", MAKEDESC.BTM files are deleted
in the current directory and any subdirectories.


4ZIP.BTM
--------

rem Creates ZIP archive and saves 4OS2 file descriptions.
rem Operates in the current directory and its subdirectories only.

@echo off

iff "%1"=="" then
  goto help
else
  goto doit
endiff

:help
  echo Create ZIP archive file with descriptions.
  echo Usage:
  echo   4ZIP archive_file
  echo Works in current directory only
  quit

:doit
zdesc -r
zip -r %1 %2 *


4UNZIP.BTM
----------

rem Extracts ZIP archive created by 4ZIP.BTM restoring 4OS2 file descriptions.
rem Operates in the current directory and its subdirectories only.

@echo off

iff "%1"=="" then
  goto help
else
  goto doit
endiff

:help
  echo Extract ZIP archive file with descriptions.
  echo Usage:
  echo   4UNZIP archive_file
  echo Works in current directory only.
  quit

:doit
unzip %1
rdesc -r
inkey /c/k"YyNn" Erase MAKEDESC.BTM files? [Y/N] %%YN
if %@upper[%YN] = Y del /s makedesc.btm


BUGS
====

These programs are free.  You can use them, hack them, give them away,
sell them, or whatever you want.  They come with no warranty and no
restrictions.  This is a hobby for me, not a business.

I will, however, attempt to fix any bugs, if you report them via
CompuServe mail to my user ID above.  I'll also be glad to entertain any
suggestions for enhancements, as long as you keep them simple. ;-)

        Enjoy,
        Gene

