home *** CD-ROM | disk | FTP | other *** search
/ IBM CD Showcase / OS2_CD_ROM.iso / smce0001 / cfirst11 / os2tk11 / debug / dbuginst.doc < prev    next >
Encoding:
Text File  |  1993-04-25  |  11.5 KB  |  307 lines
  1.  
  2.  
  3. [dbuginst]                                                    [v 0.103]
  4.  
  5.              Debug Kernel / PM Install / Restore Procedure
  6.              ═════════════════════════════════════════════
  7.  
  8. Introduction
  9. ────────────
  10.  
  11. This installation procedure for the debug utility and symbol files, the
  12. debug  kernel,  and the debug version of Presentation Manager  has been
  13. designed to avoid having to boot from the OS/2 installation diskette.
  14.  
  15. This is achieved by leaving the  retail PM dynamic link libraries where
  16. they are (in \os2\dll), untouched, and installing the debug versions to
  17. a separate directory (\os2\DEBUG\dll). The debug versions are then made
  18. the active versions  by simply editing  the 'config.sys' file  and then
  19. rebooting.
  20.  
  21. The installation may now be done from a CD-ROM or remote disk, as well as
  22. the diskettes previously used.
  23.  
  24. Quick Start Guide
  25. ─────────────────
  26.  
  27.   Installing from Diskettes:
  28.   ──────────────────────────
  29.  
  30.   1. Insert "Toolkit Debug Diskette 1" in your diskette drive.
  31.  
  32.   2. At any OS/2 prompt (windowed or full-screen),  from any directory,
  33.      type the following command:
  34.  
  35.         a:\install  c  a
  36.  
  37.         where 'c' is the drive letter where OS/2 2.x is installed
  38.           and 'a' is your diskette dirve
  39.  
  40.      NOTE: Do not type a colon after the drive letters.
  41.  
  42.   3. When prompted to enter a debug install option,  choose the options
  43.      in this order:
  44.  
  45.         Option 1 - install utilities / symbols
  46.         Option 2 - install debug kernel
  47.         Option 3 - install debug PM             [this is optional]
  48.  
  49.   4. Make the necessary config.sys changes as described below.
  50.  
  51.   5. Connect a debug terminal, and restart your system.
  52.  
  53.  
  54.   Installing from CD-ROM or Remote Disk:
  55.   ──────────────────────────────────────
  56.  
  57.   1. If using a CD-ROM, insert it in the drive.  If using a remote disk,
  58.      be sure it's connected before starting the install process.
  59.  
  60.   2. At any OS/2 prompt (windowed or full-screen),  from any directory,
  61.      type the following command:
  62.  
  63.         d:\OS2TK21\DEBUG\CDINST  d  c
  64.  
  65.      where 'd' is the drive letter of the CD-ROM or remote drive
  66.        and 'c' is the drive letter where OS/2 2.x is installed
  67.  
  68.      NOTE: Do not type a colon after the drive letters.
  69.  
  70.   3. See steps 3 - 5 above.
  71.  
  72.  
  73.  
  74. Necessary "config.sys" file changes
  75. ───────────────────────────────────
  76.  
  77. 1. Debug Kernel only
  78.  
  79.    If you have installed only the debug kernel (i.e. not debug PM or the
  80.    PM Shell APIs), shutdown and restart your system.
  81.  
  82.    Note:  If you have a second communication port, then the output of the
  83.           debug kernel will go to that port (COM2) otherwise output will
  84.           go to COM1.  Be sure to connect your cable to the active port.
  85.  
  86. 2. Debug PM Install
  87.  
  88.    If you install the debug version of PM and/or the PM Shell APIs, you
  89.    will need to make the following changes to your  "config.sys"  file,
  90.    prior to rebooting.
  91.  
  92.      a. Invoke the debug version of "pmdd.sys" (from the \os2\debug\dll
  93.         directory instead of the retail version in \os2)
  94.  
  95.                 device=c:\os2\debug\dll\pmdd.sys /Cn
  96.  
  97.          where    c  is your installation drive
  98.                   n  is the communication port for debug output
  99.                      Allowed values for n are:
  100.                        2 if COM2 is present or
  101.                        1 if COM2 is not present
  102.  
  103.      b. Add the debug DLL directory to the BEGINNING of your LIBPATH
  104.  
  105.                 LIBPATH=x:\os2\debug\dll; .... etc .....
  106.  
  107.          where    x  is your installation drive
  108.  
  109.    These changes are documented during the installation procedure,  and
  110.    are recorded in the  "dbinst.log"  file which is created in the root
  111.    directory of the installation drive.
  112.  
  113. 3. Restoring the retail PM
  114.  
  115.    Remove "x:\os2\debug\dll" from the beginning of the LIBPATH, because
  116.    it is not possible to remove the debug versions of the DLLs from the
  117.    debug DLL directory while they are active.
  118.  
  119.    Optionally, you may want to restore the PMDD.SYS line to the form as
  120.    described in 1, above.
  121.  
  122. 4. Restoring the retail kernel
  123.  
  124.    Run the Debug Installation Program and select "Restore Retail Kernel".
  125.  
  126.  
  127. Subsequent Debug Installs / Restores
  128. ────────────────────────────────────
  129.  
  130.   The debug installation  command file and  executable are copied to the
  131.   root directory of your OS/2 system partition as part of the inital debug
  132.   install process.
  133.  
  134.   This means that you can do further installs or restore retail versions
  135.   in the following way:
  136.  
  137.   1. If using diskettes, at any OS/2 (windowed or fullscreen) prompt, type :
  138.  
  139.         c:
  140.         cd \
  141.         dbinst   c
  142.  
  143.         where 'c' is the letter of your OS/2 2.x drive without the trailing colon
  144.  
  145.  
  146.      or if using a CD-ROM, type:
  147.  
  148.         d:\OS2TK21\DEBUG\CDINST  d  c
  149.  
  150.      where 'd' is the drive letter of the CD-ROM or remote drive
  151.        and 'c' is the drive letter where OS/2 2.x is installed
  152.  
  153.      NOTE: Do not type a colon after the drive letters.
  154.  
  155.  
  156.   2. Select options when prompted to do so.
  157.  
  158.   3. Make config.sys changes if necessary, as described above.
  159.  
  160.  
  161.  
  162.  
  163.                         Technical Description
  164.                         ═════════════════════
  165.  
  166. During installation, two files are copied to the root directory of your
  167. specified installation drive. The files are:
  168.  
  169.     1.  dbinst.cmd      - the basic command file, which can be executed
  170.                           separately, and which calls dbuginst.exe with
  171.                           the requested install drive as a command line
  172.                           argument.
  173.  
  174.     2.  dbuginst.exe    - this executable acts as the interface to  the
  175.                           user, allows him or her to choose which parts
  176.                           of the debug system to install, or even which
  177.                           parts to restore to the retail version.
  178.                           This program now supports remote installation
  179.                           from a CD-ROM or a remote drive.
  180.  
  181. The User Interface
  182. ──────────────────
  183.  
  184. The user interface consists of a menu selection in a tabular format. It
  185. provides installation in  3 optional parts,  and the ability to restore
  186. two of those parts back to their corresponding retail versions.
  187.  
  188.   ┌──────────────────────────────────────────────────────────────────┐
  189.   │                                                                  │
  190.   │  ╔════════╤═══════════════════════════════╤═══════╤═══════════╗  │
  191.   │  ║ Option │           Description         │ Drive │  Status   ║  │
  192.   │  ╠════════╪═══════════════════════════════╪═══════╪═══════════╣  │
  193.   │  ║    1   │ Install utilities / symbols   │  d:   │           ║  │
  194.   │  ║    2   │ Install debug  kernel         │  d:   │           ║  │
  195.   │  ║    3   │ Install debug  PM             │  d:   │           ║  │
  196.   │  ╟────────┼───────────────────────────────┼───────┼───────────╢  │
  197.   │  ║    4   │ Restore retail kernel         │  d:   │           ║  │
  198.   │  ║    5   │ Restore retail PM             │  d:   │           ║  │
  199.   │  ╟────────┼───────────────────────────────┴───────┴───────────╢  │
  200.   │  ║    E   │  Exit                                             ║  │
  201.   │  ╚════════╧═══════════════════════════════════════════════════╝  │
  202.   │                                                                  │
  203.   │ Please input your selection:                                     │
  204.   │                                                                  │
  205.   └──────────────────────────────────────────────────────────────────┘
  206.  
  207.  
  208.  
  209. Installation Options
  210. ────────────────────
  211.  
  212. The install options make up options 1, 2, and 3. On the first occasion,
  213. it is suggested that  you install in  numerical order  (the presence of
  214. the debug version of "pmdd.sys" in "\os2\debug\dll"  from option 1,  is
  215. actually a pre-requisite for option 3).
  216.  
  217. The following describes just what each of the 3 options does:
  218.  
  219.    1. Installing the utilities / symbols:  copies all the symbol (.sym)
  220.       files that correspond to DLLs located in the "\os2\dll" directory
  221.       on the installation partition, to that directory.
  222.  
  223.       Finally, the symbol file creation utility ("mapsym.exe"), and the
  224.       supplied terminal emulator ("t.exe")  are copied to the \os2\apps
  225.       subdirectory. Move "t.exe" to your debug terminal machine, or use
  226.       any other terminal emulator you have available.
  227.  
  228.       The tree structure is as follows:
  229.  
  230.         root ─── os2 ─┬───  dll
  231.                       │        ┌──────────────┐
  232.                       │        │ doscall1.sym │
  233.                       │        │ helpmgr.sym  │
  234.                       │        │ os2char.sym  │
  235.                       │        │ pmctls.sym   │
  236.                       │        │ pmdrag.sym   │
  237.                       │        │ pmgpi.sym    │
  238.                       │        │ pmmle.sym    │
  239.                       │        │ pmshapi.sym  │
  240.                       │        │ pmspl.sym    │
  241.                       │        │ pmwp.sym     │
  242.                       │        │ som.sym      │
  243.                       │        └──────────────┘
  244.                       │
  245.                       ├───  debug  ──────   dll
  246.                       │                        ┌──────────────┐
  247.                       │                        │ pmdd.sys     │
  248.                       │                        └──────────────┘
  249.                       └───  apps
  250.                                ┌──────────────┐
  251.                                │ mapsym.exe   │
  252.                                │ t.exe        │
  253.                                └──────────────┘
  254.  
  255.    2. Installing the kernel:  unhides "os2krnl"  in the root directory;
  256.       renames it to  "os2krnl.RTL";  replaces it with the debug version
  257.       from the "Toolkit Debug Diskette 2"; and copies the kernel symbol
  258.       file to the root directory (from "Toolkit Debug Diskette 2"):
  259.  
  260.         root
  261.        ┌──────────────┐
  262.        │ os2krnl      │
  263.        │ os2krnl.sym  │
  264.        ├──────────────┤
  265.        │ os2krnl.rtl  │
  266.        └──────────────┘
  267.  
  268.    3. Installing the debug version of PM: unpacks debug versions of the
  269.       PM Window Manager and Graphics Engine DLL and symbol files to the
  270.       "\os2\debug\dll" directory (from "Toolkit Debug Diskette 1"):
  271.  
  272.         root ────  os2  ────  debug  ──── dll
  273.                                             ┌──────────────┐
  274.                                             │ pmgre.dll    │
  275.                                             │ pmgre.sym    │
  276.                                             │ pmwin.dll    │
  277.                                             │ pmwin.sym    │
  278.                                             └──────────────┘
  279.  
  280.  
  281.  
  282. Restore Options
  283. ───────────────
  284.  
  285. The restore options (4 and 5)  reverse the install procedure of options
  286. 2 and 3, respectively.  Note that there is no restore for the utilities
  287. and symbols (option 1),  because those files will simply not be used by
  288. the retail kernel. The mechanisms of the various restore operations are
  289. as follows :
  290.  
  291.    4. Restoring the kernel: replaces the active debug version of kernel
  292.       ("os2krnl") with the retail version saved as "os2krnl.rtl" in the
  293.       root directory, and then deletes the "os2krnl.rtl" file.
  294.  
  295.       (The kernel symbol file will be left in the root directory.)
  296.  
  297.         root
  298.        ┌──────────────┐
  299.        │ os2krnl      │
  300.        └──────────────┘
  301.  
  302.    5. Restoring the retail version of PM:  reminds the user to edit the
  303.       config.sys file.  It does not delete any of the debug versions of
  304.       the DLLs  or PMDD.SYS from the  \os2\debug\dll directory.  (Trace
  305.       files in the  \os2\system\trace directory are also left alone).
  306.  
  307.