\chapter{GPM-EMX}
{\bf\huge 32-bit \gpm\ for OS/2}

\section{Introduction}
\gpmemx\ is a port of \gpml\ which runs under OS/2, in 32-bit protected mode.
This version depends on the \emx\ runtime libraries and various utilities that are
part of the \emx
\footnote{\emx\ can be downloaded from
{\tt ftp.uni-stuttgart.de:/pub/systems/os2/emx-0.9a} and other mirror sites}
distribution.
This version is compatible with \gpml\ apart from the differences noted here.

\section{Installation}
The installation of \emx\ is quite separate to the installation of
\gpmemx.  You can do these two installation procedures in either order.

\subsection{Installation of \emx}
To install \emx, you must do the following:
\begin{itemize}
\item Read INSTALL.DOC that came with your \emx\ distribution

\item Un-zip these files for a minimum installation
\begin{verbatim}
    C:\> unzip emxrt.zip      (emx runtime package)
    C:\> unzip emxdev.zip     (emx development tools)
    C:\> unzip gnudev.zip     (gcc, gdb and other GNU tools)
\end{verbatim}

\item Un-zip optional documentation (a good idea if you have the room)
\begin{verbatim}
    C:\> unzip emxview.zip    (emx documentation in OS/2 .inf format)
    C:\> unzip gnuview.zip    (GNU documentation in OS/2 .inf format)
\end{verbatim}

\item Edit your {\tt CONFIG.SYS} file as specified in INSTALL.DOC.
\end{itemize}

\subsection{Installation of \gpmemx}
To install \gpmemx, you must do the following:
\begin{itemize}
\item Create a directory to install in, like \verb+C:\GPM+

\item Un-zip the gpm distribution in the install directory.
\begin{verbatim}
    C:\GPM> unzip gpmemxMay95.zip
\end{verbatim}

\item Edit your {\tt CONFIG.SYS} adding \verb+C:\GPM\BIN+ to your LIBPATH and
      including the following two lines
\begin{verbatim}
    SET M2LIB=C:\GPM\M2LIB
    SET M2SYM=C:\GPM\M2SYM
\end{verbatim}
All the environment variables that are used by \gpm\ are described in Chapter 7 of
the Reference Manual.

\item Don't forget to reboot your computer to enable the new LIBPATH to take effect.
\end{itemize}


\subsection{Compiling and linking}
As is the case for all current native code versions of \gpm, \gpmemx\ produces
output as assembler.  This is assembled and linked using the GNU utilities
provided by the \emx\ distribution.  \gpm\ creates Unix-style a.out object
({\tt .o}) files.  These {\tt .o} files are linked by {\bf build} with
Unix-style libraries ({\tt .a} files) to create a Unix-style a.out file.
Then, {\bf emxbind} is used to turn this file into a {\tt .exe} file that can
be executed under both OS/2 and DOS.  The \emx\ documentation refers to this as
``method E1''.  The advantage of this method is that it provides an environment
to which it is very simple to port existing \gpm\ programs.  Faulting programs
produce core dumps and programs can be debugged using \gdb. \emx\ provides these
facilities through a number of DLLs.

The \gpm\ compiler and utilities are all written in Modula-2 and have been
bootstrapped with \emx.  Thus the binaries supplied with the \gpmemx\
distribution require these DLLs to run, just as do the programs they create.

Object Module Format ({\tt .obj}) files can also be produced with \emx.
The libraries are {\tt .lib} files and the OS/2 linker LINK386 is used.
GPM does not directly support this format.  If you want to use this method,
\emx\ provides a number of tools for converting files from one format to the
other.  Use the {\tt BUILD -S} option to create a linker script for your
application in {\tt modbase.cmd} and then edit it to invoke {\bf emxomf} and
{\bf emxomfld}.  The \emx\ documentation explains how to use these tools.

\subsection{Debugging}
The \emx\ distribution includes a version of \gdb\ that accepts {\tt .exe} files
(and {\tt core} files) as program images and provides source level debugging
of your Modula-2 programs.  \gdb\ works exactly as on \gpml.\footnote{Using
\gdb\ with \gpm\ is described in the appendix {\em Debugging with gdb -- getting
started.}} As an example, in order to compile, build and debug a program
{\tt foo.mod} the following sequence of commands is required~---
\begin{quote}
{\tt C:> gpm -g foo.mod}\\
{\tt C:> build foo}\\
{\tt C:> gdb foo.exe}
\end{quote}
Alternatively, the same effect could be obtained by using {\bf gpmake}~---
\begin{quote}
{\tt C:> gpmake -g foo.mod}\\
{\tt C:> gdb foo.exe}
\end{quote}

\section{Differences from gpm-linux}

\subsection{Different behaviour for build --S}
As well as creating the temporary files {\tt modbase.dcf} and {\tt modbase},
{\bf build} for \gpmemx\ creates {\tt modbase.cmd}.  In this case {\tt modbase}
is the response file for the linker script in {\tt modbase.cmd}.

\subsection{New OS/2 Presentation Manager Option --W}
By default {\bf build} creates console applications.  The --W option will include
the appropriate runtime system and set the linker switches to create an
{\em OS/2 Presentation Manager} executable.  Runtime libraries that use
standard I/O {\tt (Terminal, InOut, RealInOut, TextInOut and StdError)} can
{\em NOT} be used.
Typically the application will need to create a message queue and windows in much
the same way as a $C$ language application for {\em OS/2 Presentation Manager}.
Runtime error messages are displayed in a dialog box before the application is
aborted.  The resources and window procedure required for this are in a
dynamically loaded DLL, {\tt gprts.dll}.

\subsection{The DOS specific libraries}
There are two special libraries for \gpmemx.  These are {\tt PcProcesses},
and a special version of the standard {\tt UxFiles} module that understands
{\em DOS} file attributes.  See Appendix A for details of these libraries.

\subsection{The OS/2 interface -- {\tt OS2.DEF}}
The standard $C$ header files for OS/2 provide a vast resource of information
about the OS/2 API and the types they manipulate.  The basic \gpm\ interface
definition provided should provide a good platform for users to add their own
definitions.  Adding a function definition or type is generally a simple 
matter of transliteration.  

Functions that take a pointer as a parameter can generally be defined
to take a {\tt VAR} or open array parameter, but this is a matter of style and using
a separate pointer type may in some cases be preferable.  In particular,
functions that take a string as a parameter have been defined to take a
pointer type, {\tt PSZ}, rather than {\tt ARRAY OF CHAR}.  This necessitates 
the use of a type conversion function {\tt MakePSTR()} in the case where 
it is required to pass a literal string as a parameter, since Modula-2 will not
allow the address of a literal to be taken.

An OS/2 Presentation Manager sample application is included in this release.
It demonstrates uses of many of the more common API and various interface
issues that you must address to program PM applications.
