home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 10 Tools
/
10-Tools.zip
/
cset21v4.zip
/
OS2TK21
/
DEBUG
/
DBUGINST.DOC
< prev
next >
Wrap
Text File
|
1993-04-25
|
12KB
|
307 lines
[dbuginst] [v 0.103]
Debug Kernel / PM Install / Restore Procedure
═════════════════════════════════════════════
Introduction
────────────
This installation procedure for the debug utility and symbol files, the
debug kernel, and the debug version of Presentation Manager has been
designed to avoid having to boot from the OS/2 installation diskette.
This is achieved by leaving the retail PM dynamic link libraries where
they are (in \os2\dll), untouched, and installing the debug versions to
a separate directory (\os2\DEBUG\dll). The debug versions are then made
the active versions by simply editing the 'config.sys' file and then
rebooting.
The installation may now be done from a CD-ROM or remote disk, as well as
the diskettes previously used.
Quick Start Guide
─────────────────
Installing from Diskettes:
──────────────────────────
1. Insert "Toolkit Debug Diskette 1" in your diskette drive.
2. At any OS/2 prompt (windowed or full-screen), from any directory,
type the following command:
a:\install c a
where 'c' is the drive letter where OS/2 2.x is installed
and 'a' is your diskette dirve
NOTE: Do not type a colon after the drive letters.
3. When prompted to enter a debug install option, choose the options
in this order:
Option 1 - install utilities / symbols
Option 2 - install debug kernel
Option 3 - install debug PM [this is optional]
4. Make the necessary config.sys changes as described below.
5. Connect a debug terminal, and restart your system.
Installing from CD-ROM or Remote Disk:
──────────────────────────────────────
1. If using a CD-ROM, insert it in the drive. If using a remote disk,
be sure it's connected before starting the install process.
2. At any OS/2 prompt (windowed or full-screen), from any directory,
type the following command:
d:\OS2TK21\DEBUG\CDINST d c
where 'd' is the drive letter of the CD-ROM or remote drive
and 'c' is the drive letter where OS/2 2.x is installed
NOTE: Do not type a colon after the drive letters.
3. See steps 3 - 5 above.
Necessary "config.sys" file changes
───────────────────────────────────
1. Debug Kernel only
If you have installed only the debug kernel (i.e. not debug PM or the
PM Shell APIs), shutdown and restart your system.
Note: If you have a second communication port, then the output of the
debug kernel will go to that port (COM2) otherwise output will
go to COM1. Be sure to connect your cable to the active port.
2. Debug PM Install
If you install the debug version of PM and/or the PM Shell APIs, you
will need to make the following changes to your "config.sys" file,
prior to rebooting.
a. Invoke the debug version of "pmdd.sys" (from the \os2\debug\dll
directory instead of the retail version in \os2)
device=c:\os2\debug\dll\pmdd.sys /Cn
where c is your installation drive
n is the communication port for debug output
Allowed values for n are:
2 if COM2 is present or
1 if COM2 is not present
b. Add the debug DLL directory to the BEGINNING of your LIBPATH
LIBPATH=x:\os2\debug\dll; .... etc .....
where x is your installation drive
These changes are documented during the installation procedure, and
are recorded in the "dbinst.log" file which is created in the root
directory of the installation drive.
3. Restoring the retail PM
Remove "x:\os2\debug\dll" from the beginning of the LIBPATH, because
it is not possible to remove the debug versions of the DLLs from the
debug DLL directory while they are active.
Optionally, you may want to restore the PMDD.SYS line to the form as
described in 1, above.
4. Restoring the retail kernel
Run the Debug Installation Program and select "Restore Retail Kernel".
Subsequent Debug Installs / Restores
────────────────────────────────────
The debug installation command file and executable are copied to the
root directory of your OS/2 system partition as part of the inital debug
install process.
This means that you can do further installs or restore retail versions
in the following way:
1. If using diskettes, at any OS/2 (windowed or fullscreen) prompt, type :
c:
cd \
dbinst c
where 'c' is the letter of your OS/2 2.x drive without the trailing colon
or if using a CD-ROM, type:
d:\OS2TK21\DEBUG\CDINST d c
where 'd' is the drive letter of the CD-ROM or remote drive
and 'c' is the drive letter where OS/2 2.x is installed
NOTE: Do not type a colon after the drive letters.
2. Select options when prompted to do so.
3. Make config.sys changes if necessary, as described above.
Technical Description
═════════════════════
During installation, two files are copied to the root directory of your
specified installation drive. The files are:
1. dbinst.cmd - the basic command file, which can be executed
separately, and which calls dbuginst.exe with
the requested install drive as a command line
argument.
2. dbuginst.exe - this executable acts as the interface to the
user, allows him or her to choose which parts
of the debug system to install, or even which
parts to restore to the retail version.
This program now supports remote installation
from a CD-ROM or a remote drive.
The User Interface
──────────────────
The user interface consists of a menu selection in a tabular format. It
provides installation in 3 optional parts, and the ability to restore
two of those parts back to their corresponding retail versions.
┌──────────────────────────────────────────────────────────────────┐
│ │
│ ╔════════╤═══════════════════════════════╤═══════╤═══════════╗ │
│ ║ Option │ Description │ Drive │ Status ║ │
│ ╠════════╪═══════════════════════════════╪═══════╪═══════════╣ │
│ ║ 1 │ Install utilities / symbols │ d: │ ║ │
│ ║ 2 │ Install debug kernel │ d: │ ║ │
│ ║ 3 │ Install debug PM │ d: │ ║ │
│ ╟────────┼───────────────────────────────┼───────┼───────────╢ │
│ ║ 4 │ Restore retail kernel │ d: │ ║ │
│ ║ 5 │ Restore retail PM │ d: │ ║ │
│ ╟────────┼───────────────────────────────┴───────┴───────────╢ │
│ ║ E │ Exit ║ │
│ ╚════════╧═══════════════════════════════════════════════════╝ │
│ │
│ Please input your selection: │
│ │
└──────────────────────────────────────────────────────────────────┘
Installation Options
────────────────────
The install options make up options 1, 2, and 3. On the first occasion,
it is suggested that you install in numerical order (the presence of
the debug version of "pmdd.sys" in "\os2\debug\dll" from option 1, is
actually a pre-requisite for option 3).
The following describes just what each of the 3 options does:
1. Installing the utilities / symbols: copies all the symbol (.sym)
files that correspond to DLLs located in the "\os2\dll" directory
on the installation partition, to that directory.
Finally, the symbol file creation utility ("mapsym.exe"), and the
supplied terminal emulator ("t.exe") are copied to the \os2\apps
subdirectory. Move "t.exe" to your debug terminal machine, or use
any other terminal emulator you have available.
The tree structure is as follows:
root ─── os2 ─┬─── dll
│ ┌──────────────┐
│ │ doscall1.sym │
│ │ helpmgr.sym │
│ │ os2char.sym │
│ │ pmctls.sym │
│ │ pmdrag.sym │
│ │ pmgpi.sym │
│ │ pmmle.sym │
│ │ pmshapi.sym │
│ │ pmspl.sym │
│ │ pmwp.sym │
│ │ som.sym │
│ └──────────────┘
│
├─── debug ────── dll
│ ┌──────────────┐
│ │ pmdd.sys │
│ └──────────────┘
└─── apps
┌──────────────┐
│ mapsym.exe │
│ t.exe │
└──────────────┘
2. Installing the kernel: unhides "os2krnl" in the root directory;
renames it to "os2krnl.RTL"; replaces it with the debug version
from the "Toolkit Debug Diskette 2"; and copies the kernel symbol
file to the root directory (from "Toolkit Debug Diskette 2"):
root
┌──────────────┐
│ os2krnl │
│ os2krnl.sym │
├──────────────┤
│ os2krnl.rtl │
└──────────────┘
3. Installing the debug version of PM: unpacks debug versions of the
PM Window Manager and Graphics Engine DLL and symbol files to the
"\os2\debug\dll" directory (from "Toolkit Debug Diskette 1"):
root ──── os2 ──── debug ──── dll
┌──────────────┐
│ pmgre.dll │
│ pmgre.sym │
│ pmwin.dll │
│ pmwin.sym │
└──────────────┘
Restore Options
───────────────
The restore options (4 and 5) reverse the install procedure of options
2 and 3, respectively. Note that there is no restore for the utilities
and symbols (option 1), because those files will simply not be used by
the retail kernel. The mechanisms of the various restore operations are
as follows :
4. Restoring the kernel: replaces the active debug version of kernel
("os2krnl") with the retail version saved as "os2krnl.rtl" in the
root directory, and then deletes the "os2krnl.rtl" file.
(The kernel symbol file will be left in the root directory.)
root
┌──────────────┐
│ os2krnl │
└──────────────┘
5. Restoring the retail version of PM: reminds the user to edit the
config.sys file. It does not delete any of the debug versions of
the DLLs or PMDD.SYS from the \os2\debug\dll directory. (Trace
files in the \os2\system\trace directory are also left alone).