
                  32-bit Command Interpreter "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 32-bit Command Interpreter is 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
guarantee information, are contained in the on-line help document CMD.INF.


Before Installation


Some commands in this package require the 32-bit Unicode Console API in
order to execute.  The Runtime DLLs for this API are not shipped with this
package, but are available separately.  You must obtain and install the
Runtime DLLs for the 32-bit Unicode Console API before installing the
command interpreter.

The Runtime DLLs for the 32-bit Unicode Console API are available from the
Hobbes FTP site run by New Mexico State University, from the LEO FTP site,
from TSR BBS in the U.S., and from Air Applewood BBS in Europe.  The
filename should be CONRT.ZIP or CONRT.RAR .  The distribution archive
contains its own set of full installation instructions.


Installation to a dedicated directory


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

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

( 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 into various subdirectories of
C:\Apps\JdeBP\CMD.  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 command interpreter and accompanying
utilities into the C:\Apps\JdeBP\CMD directory, you will need to

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

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

        which you then execute before using the command interpreter and
        accompanying 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\CMD\BIN;%PATH%
            setenv DPATH C:\Apps\JdeBP\CMD\DATA;%DPATH%
            setenv HELP C:\Apps\JdeBP\CMD\HELP;%HELP%
            setenv BOOKSHELF C:\Apps\JdeBP\CMD\BOOK;%BOOKSHELF%
            beginlibpath C:\Apps\JdeBP\CMD\DLL

        and log out and log back in again;

        or

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

            Add C:\Apps\JdeBP\CMD\BIN to your PATH environment variable
            Add C:\Apps\JdeBP\CMD\DATA to your DPATH environment variable
            Add C:\Apps\JdeBP\CMD\HELP to your HELP environment variable
            Add C:\Apps\JdeBP\CMD\BOOK to your BOOKSHELF environment variable
            Add C:\Apps\JdeBP\CMD\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, for link libraries is
C:\LOCAL\LIB, for C/C++ header files is C:\LOCAL\INCLUDE, and for README
files is C:\LOCAL\README, then you need to extract as follows:

    PKZIP -extract -dir=none CMD C:\LOCAL\BIN\ *.EXE *.CMD
    PKZIP -extract -dir=none CMD C:\LOCAL\DATA\ *.MSG
    PKZIP -extract -dir=none CMD C:\LOCAL\BOOK\ *.INF
    PKZIP -extract -dir=none CMD C:\LOCAL\HELP\ *.HLP
    PKZIP -extract -dir=none CMD C:\LOCAL\DLL\ *.DLL
    PKZIP -extract -dir=none CMD C:\LOCAL\LIB\ *.LIB
    PKZIP -extract -dir=none CMD C:\LOCAL\INCLUDE\ *.H
    PKZIP -extract -dir=none CMD C:\LOCAL\README\CMD\ *.TXT

( 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.  )


Replacing utilities supplied with OS/2


The command interpreter has, of course, the same name (CMD) as the command
interpreter supplied with OS/2, as do some of the external commands
supplied with it (e.g. HELPMSG).

This is deliberate, because they are intended to be enhanced 32-bit
replacements for IBM's 16-bit command interpreter and utilities, allowing
one to remove those particular 16-bit vestiges from OS/2 Warp.

Most OS/2 programs, including the Workplace Shell, locate the command
interpreter to use by inspecting the value of the COMSPEC and the
OS2_SHELL environment variables.  To replace IBM's command interpreter
with this one, you will need to modify those environment variables.  For
example, if you have unpacked the command interpreter and accompanying
utilities into the C:\Apps\JdeBP\CMD directory, you will need to

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

            setenv COMSPEC C:\Apps\JdeBP\CMD\BIN\CMD.EXE
            setenv OS2_SHELL C:\Apps\JdeBP\CMD\BIN\TEXTCMD.EXE

        and restart your system; or

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

            setenv COMSPEC C:\Apps\JdeBP\CMD\BIN\CMD.EXE
            setenv OS2_SHELL C:\Apps\JdeBP\CMD\BIN\TEXTCMD.EXE

        and log out and log back in again; or

    (c) Add the following directives to your CONFIG.SYS file

            SET COMSPEC=C:\Apps\JdeBP\CMD\BIN\CMD.EXE
            SET OS2_SHELL=C:\Apps\JdeBP\CMD\BIN\TEXTCMD.EXE

        and restart your system.

To use the 32-bit external utilities supplied with the command interpreter
in preference to the 16-bit utilities supplied with OS/2, place
C:\Apps\JdeBP\CMD\BIN (or whatever directory name that you have chosen)
ahead of C:\OS2 in your PATH environment variable.


Adding a folder to the Workplace Shell Desktop


One can add a folder to the Workplace Shell desktop, containing objects
that will invoke the command interpreter front ends and open the on-line
documentation.

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

    C:\Apps\JdeBP\CMD\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 32-bit Command
Interpreter does not install any modifications into the Workplace Shell
itself.


Setting global configuration options


The CMD_CMD_INIT, CMD_TEXTCMD_INIT, and CMD_PMCMD_INIT environment
variables are used to set command line option switches that apply to all
child command interpreter processes.

On OS/2 Warp, these environment variables can be set in CONFIG.SYS with
options that will apply (unless specifically overridden) to all command
interpreter processes in the system.  Alternatively (if you are using
those mechanisms) you can set them in your INIT.RUN or SHELL.RUN files.

For details of what options can be set, see the on-line documentation for
each of the command interpreter front ends.


Duplicating quirks of the IBM command interpreter


The front ends and the external utilities supplied with the 32-bit
command interpreter provide a consistent syntax and behaviour across all
commands.  This results in behavioural differences from the commands in
IBM's 16-bit command interpreter in several cases.

Some of the quirks of the IBM command interpreter can be replicated by
setting the following environment variables globally

    SET CMD_CMD_INIT=/AUTOSTARTVDM+ /AUTOSTARTPM+
    SET CMD_TEXTCMD_INIT=/AUTOSTARTVDM+ /AUTOSTARTPM+
    SET CMD_COPY_INIT=/OLDSRCDIR+
    SET CMD_DEL_INIT=/OLDSRCDIR+
    SET CMD_DIR_INIT=/OLDSRCDIR+
    SET CMD_ZDIR_INIT=/OLDSRCDIR+
    SET CMD_RENAME_INIT=/OLDSRCDIR+

and by editing the BIN\COPY.CMD file to read

    @copyplus %$

For details, see the on-line documentation.


Getting help after installation


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

    VIEW CMD

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

    VIEW CMD DIR

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 FOR command, type

    FOR /?

( See the note on message files below. )


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,
CMD.MSG and CMDH.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.
