
                  OS/2 Command Line Utilities "read me!"

            Copyright (c) 1993-2004 Jonathan de Boyne Pollard.

              Jonathan de Boyne Pollard, FIDONET#2:257/609.3
              Jonathan de Boyne Pollard, FIDONET#1:109/921.70
           Jonathan de Boyne Pollard <J.deBoynePollard@Tesco.NET>


Guarantee and Software licence


The OS/2 Command Line Utilities are copyrighted software, with all rights
reserved by the author, which the author encourages everyone to share and
to use freely.  The terms and conditions of the software licence, and the
disclaimer of guarantee, are contained in the on-line help document
CLU21.INF.


Installation to a dedicated directory


To install the utilities to a directory dedicated to holding them, such as
C:\Apps\JdeBP\CLU, for example, simply unpack the distribution archive
into that directory.

    PKZIP -extract -dir=curr CLU21 C:\Apps\JdeBP\CLU\ *

( This assumes that the distribution archive that you received was in ZIP
  format, and that you are using PKZIP version 2.50 for OS/2.  )

This will extract the files that comprise the utilities into various
subdirectories of C:\Apps\JdeBP\CLU.  You will then need to add the
relevant subdirectories to the PATH, DPATH, LIBPATH, HELP, and BOOKSHELF
environment variables.  For example, if you have unpacked the utilities
into the C:\Apps\JdeBP\CLU directory, you will need to

    (a) Create a *.CMD file with the following statements in it

            PATH C:\Apps\JdeBP\CLU\BIN;%PATH%
            DPATH C:\Apps\JdeBP\CLU\DATA;%DPATH%
            SET HELP=C:\Apps\JdeBP\CLU\HELP;%HELP%
            SET BOOKSHELF=C:\Apps\JdeBP\CLU\BOOK;%BOOKSHELF%
            BEGINLIBPATH C:\Apps\JdeBP\CLU\DLL

        which you then execute before using the utilities (replacing the
        BEGINLIBPATH command with a SET command if your command
        interpreter requires it);

        or

    (b) Add the following statements to a SHELL.RUN file (if you are
        using that mechanism)

            setenv PATH C:\Apps\JdeBP\CLU\BIN;%PATH%
            setenv DPATH C:\Apps\JdeBP\CLU\DATA;%DPATH%
            setenv HELP C:\Apps\JdeBP\CLU\HELP;%HELP%
            setenv BOOKSHELF C:\Apps\JdeBP\CLU\BOOK;%BOOKSHELF%
            beginlibpath C:\Apps\JdeBP\CLU\DLL

        and log out and log back in again;

        or

    (c) Make the following changes to your CONFIG.SYS

            Add C:\Apps\JdeBP\CLU\BIN to your PATH environment variable
            Add C:\Apps\JdeBP\CLU\DATA to your DPATH environment variable
            Add C:\Apps\JdeBP\CLU\HELP to your HELP environment variable
            Add C:\Apps\JdeBP\CLU\BOOK to your BOOKSHELF environment variable
            Add C:\Apps\JdeBP\CLU\DLL to your LIBPATH directive

        and restart your system.


Installation to a multipurpose directory


If you already have general purpose catch-all directories where you like
to store your third-party tools, message files, and on-line help files,
then you simply need to extract the relevant parts of the distribution
archive into the different directories.

For example, if your general-purpose directory for executables is
C:\LOCAL\BIN, for message files is C:\LOCAL\DATA, for dynamic link
libraries is C:\LOCAL\DLL, for on-line help files is C:\LOCAL\HELP, for
on-line documentation files is C:\LOCAL\BOOK, and for README files is
C:\LOCAL\README, then you need to extract as follows:

    PKZIP -extract -path=none CLU21 C:\LOCAL\BIN\ *.EXE *.CMD
    PKZIP -extract -path=none CLU21 C:\LOCAL\DATA\ *.MSG
    PKZIP -extract -path=none CLU21 C:\LOCAL\BOOK\ *.INF
    PKZIP -extract -path=none CLU21 C:\LOCAL\HELP\ *.HLP
    PKZIP -extract -path=none CLU21 C:\LOCAL\DLL\ *.DLL
    PKZIP -extract -path=none CLU21 C:\LOCAL\README\CLU\ *.TXT *.HTML

( This assumes that the distribution archive that you received was in ZIP
  format, and that you are using PKZIP version 2.50 for OS/2.  )

Several of the commands (FF, GREP, WC, SUM, TOUCH) have common names, that
may duplicate other commands of the same name on your system.  Care should
thus be taken when extracting the files from the archive.  PKZIP will
prompt you whether to overwrite the existing utilities or extract to a new
name of your choosing in such cases.


Replacing utilities supplied with OS/2


Several of the commands (ATTRIB, COMP, FIND, HELP, SORT, TREE) have the
same names as commands supplied with OS/2.  This is deliberate, because
they are intended to be 32-bit replacements for those 16-bit OS/2
utilities, with additional features.  They allow one to remove those
particular 16-bit vestiges from OS/2 Warp.

Which command is used, the OS/2-supplied one or the CLU21 one, is
determined by the order in which the relevant directories appear in your
PATH environment variable.  To execute the CLU21 utilities in preference
to the ones supplied with OS/2, place C:\Apps\JdeBP\CLU (or whatever
directory name you have chosen) ahead of C:\OS2 in your PATH environment
variable.


Getting help after installation


The on-line documentation is in the book CLU21.INF.  To read it, either
double-click on the file on your Workplace Shell desktop or run the
command

    VIEW CLU21

at the command line.  You can go directly to the help for individual
commands by specifying the command name as a second argument:

    VIEW CLU21 FF

Each command also presents a short summary of its syntax in response to
the /? option.  To use this, /? must be the first option on the command
line for the command, and may not be combined with other options.  For
example, to see the summary for the GREP command, type

    GREP /?

( See the note on message files below. )


Adding a folder to the Workplace Shell Desktop


One can add a folder to the Workplace Shell desktop, containing objects
that will invoke some of the utilities and open the on-line documentation.

To create this folder, run the supplied MakeObj.CMD REXX command script.
If you have installed the command-line utilities in C:\Apps\JdeBP\CLU, run

    C:\Apps\JdeBP\CLU\Bin\NotPATH\MakeObj.CMD

The folder will be created in your "Programs" folder.  It may be deleted
by simply dragging and dropping it onto the Shredder.  The Command-Line
Utilities does not install any modifications into the Workplace Shell
itself.


Users of JP Software's 4OS2 and Take Command for OS/2


Users of JP Software's 4OS2 and Take Command for OS/2 should read the
section of the on-line documentation dealing with those command
interpreters.

    VIEW CLU21 JPSOFT


Message files


In order to make it easy to produce non-English versions of the utilities,
should anyone ever require them, all of the error messages and the on-line
help text for the /? option for each command are stored in message files,
CLU.MSG and CLUH.MSG, rather than being embedded within the EXEs
themselves.

The commands also require the OSO001.MSG file, supplied with OS/2 itself,
in order to display the error messages for various system errors.

Both of these message files must be in directories that are listed in the
DPATH environment variable.  If they aren't, then the commands will not be
able to display comprehensible error and help messages.


