mapsymw.pl v0.4
2019-04-09

== Introduction ==

Mapsymw.pl is a Perl script that takes an OpenWatcom map file as input and
generates a sym file compatible with the kernel debugger, pmdf, exceptq and
other tools that accept sym files generated by mapsym.

== Prerequisites ==

You need to have Perl installed.  The script uses the GetOpt and File
packages which exist on most Perl installations.  If you don't have them
installed, use cpan to install them.

Mapsym needs to be installed somewhere in the PATH.

The TMP environment variable must point to a directory that exists.

== Installation ==

Unzip the distribution zip file to a directory of your choice.

If you run 4OS2 and your Perl is installed in the PATH and you install the
mapsymw.pl to a directory in the PATH, add the following to your config.sys:

  set .pl=perl -w

This will allow you to run Perl scripts just like any other shell script.

== Usage ==

Run the script as

  perl mapsymw.pl mapfile-name

If you have the .pl environment variable defined as described above, run the
script as

  mapsymw mapfile-name

The script writes a mapsym compatible version of the map file to the TMP
directory and runs mapsym and places the sym file in the current directory.

For usage help, run the script as

  perl mapsymw.pl -h

== Mapsym hints ==

Some tools get confused if a segment has no symbols.  If this occurs,
mapsymw generates a dummy symbol.

Some tools get confused if a 32-bit segment has no symbols with values
larger than 0x10000.  If this occurs, mapsymw creates a dummy symbol.

Some tools care about module name case.  Pmdf is an one of these tools.  If
pmdf cannot locate symbols you know exist, verify that the module name case
in the map file matches the module name case in the executable.  Use lxlite
-c:exehdr to view the module name.  To resolve the issue, edit the
OpenWatcom map file so that the module name shown on the Executable Image:
line matches what is reported by lxlite.

Many tools can not handle sym files with blocks larger than 64KB.  The
workaround is to edit the map file and remove symbols that are not needed.
The script contains logic to do this for libc map files.

C++ symbols contain characters not accepted by the kernel debugger or pmdf.
Mapsymw implements a number of conversions with the goal of generating a
label that is legal and easy to use.  See the code near line 160 of the
script for the conversions that are implemented.

If a symbol has a trailing underscore, it is stripped under the assumption
that the calling convention is watcall.

If a symbol has a leading underscore, it is stripped under the assumption
that the calling convention is cdecl.

If you are working with an application that uses the mis-feature of giving
the executable and the dll the same base name, tools such as the kernel
debugger and pmdf will not work as you would like them to.  The workaround
is to change the module name of the executable.  If you are the developer
change the module name with the linker.  Otherwise, use your favorite hex
editor to change the module name in the executable header and rename the map
file to match.

== Future stuff ==

The script does not yet handle overloaded C++ methods.  The conversions
result in duplicate symbols and most tools ignore all but this first
occurrence in the sym file.  If there are sufficient requests, the script
will be updated to avoid the duplicate symbols. The code to support this
already exists in mapsymb.pl, which supports Borland C++ map files.

Have fun,

Steven
