OS/2 Shareware BBS: 10 Tools/10-Tools.zip/rmxbeta.zip/rmx/rmx.doc

Text File | 1994-09-06 | 19KB | 492 lines

Remote Execution for OS2 - RMX-OS2
**********************************
Before you even look at this, please be aware that the RMX-package is
not finished yet. This release cannot even be considered being beta.
You will, however, (I hope) be able to verify what RMX-OS2 is, and
perhaps give me some assistance in getting it finished. You'll need a
network that supports remote named pipes.

As I don't want to get into trouble with any lawyers, I suppose I had
better put this here:

BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.

If there is anything at all you are wondering about, please don't
hesitate to send me mail:

    [e-mail]



What is remote execution?
=========================
The applications in the Windows and OS2 operating systems must run on
the machine where you want their output to appear. It is not possible
to run the application in one computer and "redirect" its output to
another. Even if you have a file server, this is still the case. The
application is only _stored_ on the file-server, when you run the
application it runs on your local machine.

Now, why would you want to have remote execution? Well, you could have
one really powerful machine - say a Pentium - where people run their
applications and then use cheaper computers, say 486SXs, as
intelligent terminals. And as every X-user knows, being able to run an
application on different computer than where the output is displayed
simply _is_ a useful feature.

Providing remote execution as an add-on is what the RMX package is all
about.



How does RMX work
=================
OS2 is built around dynamic link libraries. Only the very core of OS2
is in the files - e.g. OS2KRNL - found in the root directory of the
boot drive. The rest, including Presentation Manager and Workplace
Shell, are all DLLs. Most functions a PM-program uses for producing
output are collected into a few DLLs. If these DLLs are replaced with
equivalent DLLs it is possible to "move" the execution of a function
to another computer.

Technically it would be possible to replace the original DLLs of OS/2
itself, in which case each and every OS2-program could be executed
remotely without any extra hazzle involved, but the amount of work
needed for doing that would be somewhat overwhelming. Eventually I may
do that, however.

In order to make an application use the DLLs of RMX, the application
needs to be marked. Marking an application essentially means that it
is patched so that it, instead of using e.g. PMWIN.DLL, will use
RXWIN.DLL. Patching like this is perfectly safe but as the tool does
not yet allow you to "depatch" the application, I suggest you first
make a copy of the original file which you then patch.

Even if an application is patched, the application need not be run
remotely and most of RMX need not be present. Only the DLLs whose
name start with RX must be available. When run locally they simply
pass all calls directly through to the real PM-DLLs. In practice this
causes no overhead at all. For those familiar with programming, the
penalty is only the cost of one additional function call.

The same terminology is used in RMX as in X. I.e. the computer where
the output of the application is displayed is called the
display-server or simply server. The applications uses the the
services of the server and are hence called clients. The computer
where the clients run is called a CPU-server.



Files
=====
When you unzip the rmx.zip, you'll get the following directory and
file structure.

.\rmx\bin\pmserver.exe
.\rmx\bin\pmengine.exe
.\rmx\bin\rmxmark.exe
.\rmx\bin\rmxstrtr.exe
.\rmx\bin\rmxstart.exe
.\rmx\demo\...
.\rmx\dll\rxctls.dll
.\rmx\dll\rxlpmgr.dll
.\rmx\dll\rxgpi.dll
.\rmx\dll\rxshapi.dll
.\rmx\dll\rxwin.dll
.\rmx\dll\rmxpipe.dll
.\rmx\dll\rmxctls.dll
.\rmx\dll\rmxlpmgr.dll
.\rmx\dll\rmxgpi.dll
.\rmx\dll\rmxshapi.dll
.\rmx\dll\rmxwin.dll
.\rmx\dll\rmxos2b.dll
.\rmx\dll\rmxos2g.dll
.\rmx\dll\rmxos2c.dll
.\rmx\dll\rmxos2s.dll
.\rmx\doc\rmx.doc

The following files are needed on the display-server:
    pmserver.exe pmengine.exe rmxstart.exe rmxos2b.dll,
    rmxos2g.dll rmxos2s.dll rmxpipe.dll

And the following on the CPU-server:
    rxctls.dll rxlpmgr.dll rxgpi.dll rxshapi.dll rxwin.dll
    rmxctls.dll rmxlpmgr.dll rmxgpi.dll rmxshapi.dll rmxwin.dll
    rmxos2b.dll rmxos2g.dll rmxos2c.dll rmxpipe.dll

The DLLs have to be in a directory that is included in the LIBPATH.
You can of course move all RMX-DLLs to one of the directories that are
in the LIBPATH already, but I'd suggest adding the RMX DLL directory to
the LIBPATH instead.

The RMX-directory need not be in the root, it can be moved anywhere.

In the following each file of RMX is descibed:

pmserver.exe & pmengine.exe
---------------------------
Pmserver must be running on the display-server if remote execution is
to be used. It simply sits there, idle most of the time, waiting for
remote clients to initiate a connection. When a client connects, the
pmserver starts a pmengine that provides services for that client. So,
for each client there will a separate pmengine.

The pmengines look and feel exactly as the clients that are running on
the CPU-server.

You have to specify the engine using the environment variable
RMXENGINE. E.g.:

      [C:\]set RMXENGINE=C:\RMX\BIN\pmengine.exe
      [C:\]start pmserver

In general you need not worry about these applications, just start the
pmserver.


rmxmark.exe
-----------
This application marks an application for remote execution. Without
any flags, rmxmark marks the application if it is convinced the remote
execution of the application will succeed. Remote execution will
succeed provided the application only uses PM-DLLs rmxmark knows
about, and the application is a true 32-bit executable. 32-bit
applications that use the 16-bit interface of PM-DLLs cannot be
marked. But as rmxmark complains about any 16-bit functions and not
only the ones related to PM, remote execution may still succeed.

If rmxmark refuses to mark an application it can always be forced to
do that by starting it with the flag -f. Whether remote execution
really will work can only be found out by testing.

There is no technical reason for not supporting 16-bit DLLs. I only
thought it would be a waste of time and effort to support them.
However, I've noticed that quite a few applications use the
VIO-functions so I may add support for them. Unless of course IBM
chooses to provide 32-bit character I/O-functions.

Of the programs delivered with OS/2 only a fairly small number can be
marked. Mainly because most of them are 16-bit programs. The ones that
can be marked are:

    c:\os2\e.exe
    c:\os2\pulse.exe
    c:\os2\apps\jigsaw.exe

Unfortunately, atleast for the moment, jigsaw.exe causes a protection
violation when you attempt to open a file. I'm pretty certain the
reason is that it has such a small stack.


rmxstrtr.exe & rmxstart.exe
---------------------------
These files are used for starting applications on the CPU-server from
the display-server. These programs are actually not part of RMX, they
are only provided for convenience. They are also named-pipe specific
so they won't be usable under RMXTCPIP (which is not here yet).

Anyway, first start rmxstrtr on the CPU-server. It's a deamon
application so it can very well be detached. However, it does write
some information about what it's doing to the stdout, so you might
want to start it in a command prompt window. When started, it sits
idle while waiting for requests to start applications.

Rmxstart.exe is then used to start applications on the CPU-server from
the display-server. Suppose the name of the CPU-server is \\CPU_SERVER
and the name of the display-server is \\MY_DISPLAY and you want to
start the application mine.exe. Then you just issue:

    [C:\]rmxstart \\CPU_SERVER mine.exe \\MY_DISPLAY

As a result of the the rmxstrtr on \\CPU_SERVER will attempt to start
mine.exe, whose output will be redirected to \\MY_DISPLAY.

A few things to keep in mind:

    (1) The application will be started with the same environment
        as rmxstrtr.exe has. So make sure the PATH is ok when it
        is started.
    (2) Rmxstrtr makes no attempt to verify that the application
        can be executed remotely. So, if the application has
        not been marked, it will appear on the CPU-server and not
        on the display-server.
    (3) The trick of having "." in the LIBPATH won't work properly
        as the current directory, when the applications are started,
        is always the directory from which rmxstrtr was started.
    (4) You can use an absolute path in the application name.


rxwin.dll rxgpi.dll rxshapi.dll rxctls.dll rxlpmgr.dll
------------------------------------------------------
These DLLs replace replace pmwin.dll, pmgpi.dll, pmshapi.dll,
pmctls.dll and helpmgr.dll respectively. If the application is run
locally - i.e. run and displayed on the same machine - they "route"
all function calls directly to the correspnding PM-DLLs. If the
application is run remotely they route all function calls to
corresponding RMX-DLLs.


rmxwin.dll rmxgpi.dll rmxshapi.dll rmxctls.dll rmxlpmgr.dll
-----------------------------------------------------------
These DLLs redirect all function calls to the appropriate pmengine on
the display-server.


rmxpipe.dll
-----------
The actual transfer of bytes from a client to an engine is outside
RMX. The byte transfer is handled by a DLL that is loaded during
startup. The specification of that DLL - what functions it must
contain and what they should do - is public and available to anyone
interested (mail me if you are). Hence, it is basically quite trivial
to provide support for different networks and/or media.

The default implementation of the communications DLL is rmxpipe, which
uses named pipes. I hope I or somebody else will soon write a DLL for
TCP/IP. The DLL to be used _must_ be specified before any applications
or pmserver are started.

    [C:\]set RMXCOMMS=rmxpipe
    [C:\]start pmserver

The same DLL must of course be used in both the CPU-server and the
display-server.



Installation
============
The following procedure should give you a working environment. Here I
have assumed RMX has been installed in drive C:.

Both-computers
--------------
1) [C:\]unzip rmx.zip

2) Add C:\RMX\DLL; to the LIBPATH in config.sys.

3) Add the following lines to config.sys:

   set RMXENGINE=C:\RMX\BIN\pmengine.exe
   set RMXCOMMS=rmxpipe

4) Reboot

CPU-server
----------
[C:\]net share ipc$ (or whatever you have to do to enable remote named pipes)

[C:\]cd \rmx\demo

[C:\RMX\DEMO]copy C:\OS2\APPS\pulse.exe .

[C:\RMX\DEMO]..\bin\rmxmark pulse.exe

[C:\RMX\DEMO]..\bin\rmxstrtr


Display-server
--------------
[C:\]net share ipc$ (or whatever you have to do to enable remote named pipes)

[C:\]cd \rmx\bin

[C:\RMX\BIN]start pmserver.exe

[C:\RMX\BIN]rmxstart \\CPU_SERVER pulse.exe \\MY_DISPLAY

Pulse.exe running on \\CPU_SERVER should now appear on \\MY_DISPLAY.
You should of course replace \\CPU_SERVER and \\MY_DISPLAY with
whatever names your computers have.

The \RMX\DEMO directory contains original shareware programs that I've
been using while testing RMX. Simply unzip those programs and mark the
executables and use them. Not all of them work perfectly, start with
mine and tetris. Pmps allows you to monitor and kill applications on
another computer.



Starting remote applications
============================
The normal way to start a remote execution is through rmxstrtr and
rmxstart. However, there is another way.

Before starting a client application set RMXDISPLAY to the computer
where you want your application to appear. E.g.:

    [C:\]set RMXDISPLAY=\\MY_DISPLAY
    [C:\]start mine.exe

Now the application will appear on the computer \\MY_DISPLAY instead
of in the local computer. If RMXDISPLAY is not defined, the
application will run locally. This is essentially what rmxstrtr.exe
does when it starts an application. Rmxstart.exe tells it what
RMXDISPLAY should be, rmxstrtr sets it to that and starts the
application.

Doing it manually is of course possible only if you have the two
computers next to each other or if you have other way of logging on to
the CPU-server, e.g. telnet over TCP/IP.

NOTE: If you manually start an application from a command prompt you
      _have_ to use "start". Otherwise PM (not OS/2 itself) will freeze.

      The reason is, I believe, that as the application is a
      PM-application, the Presentation Manager expects it to create a
      message queue and start receiving messages. As the calls for
      doing that are redirected to the display-server, they will never
      be made on the CPU-server with the effect of PM freezing up.

      When the application is terminated (from the dislay-server) PM
      starts working again.



Performance
===========
Please be prepared that he applications will run very slowly. I have
debugging code all over the place and I havn't done any optimizations
at all. Optimizing the DLLs and the executables won't have too much
impact, but optimizing the message traffic between the client and the
engine will significantly improve the performance. However, I don't
intend to do much optimization before I'm satisfied with the
functionality.



Security
========
Adding remote execution as an add-on has implications on the security.
When pmserver is running, anybody can initate a connection with the
computer and e.g. start a hidden application that monitors keystrokes.
Currently there are no security features in RMX but I have a
specification ready that allows third-parties to implement whatever
security features are felt necessary. I assume the security-issue will
not be particularily important as long as RMX is not finished product,
but if somebody is interested in that specification, let me know and
I'll send it to you.



Debugging
=========
During execution of programs there will be crashes. Occasionally RMX
is able to gracefully handle protection violations and alike and
prevent the application from being terminated. However, problems like
this are always logged to the file rmx.log. If the environment
variable RMXDIR is specified, RMX attempts to create the logfile in
that directory. Otherwise it creates it in the root-directory.

If you experience problems, please check that file on both the
CPU-server and the display-server as it might contain an explanation.

If there is nothing useful there then set RMXDEBUG to 1, 2 or 3 (there
is not much difference between them currently, but eventually there
will be) and restart the application.

    [C:\]set RMXDEBUG=3
    [C:\]start mine.exe

This will cause a LOT of information to be written to rmx.log. Do
whatever you have to do in order to get the problem to appear and then
mail the contents of the log-file to me. Preferably the log-files from
both the CPU-server and the display-server. You need of course to stop
the pmserver, set RMXDEBUG and restart it for the logging to start.

Don't have RMXDEBUG set all the time, as it really makes the
applications crawl.

If you can do so (you have written it, it is shareware or you trust
me), please send the entire executable that is causing trouble to me,
along with a description that allows me to regenerate the problem. The
executable need not contain any debug info, nor do I need any source.



Known big misfeatures
=====================
The help doesn't work at in applications.

I havn't reverse engineered the default file-open dialog box yet.
Therefore when you run e.g. e.exe remotely the files shown in the
listboxes when you choose [File]->[Open] are the files on the
display-server and not the files on the CPU-server. A workaround is to
have same network drives visible on both machines. With Lan Server
this would be:

    CPU-server
    [C:\]net share c=c:\
    [C:\]net use x: \\CPU_SERVER\C

    display-server
    [C:\]net use x: \\CPU_SERVER\C

This way if you choose a file from X: it will be the same one both the
CPU-server and the display-server. I will provide a transparent
replacement for the default dialog boxes so that there will be no need
for having the same directory visible on both computers.

If the client-application is terminated in an uncontrolled fashion,
the pmengine may fail to detect that and not die. In that case it'll
be around until the display-server is booted. However, you'll get the
PID of the engine using pstat and then you can kill it with some
kill-utility.



Future
======
Currently my main effort is directed towards getting all functionality
of the five supported DLLs implemented. Only then will I start
improving the performance.

If there is an application you really would like to use remotely, but
cannot because it uses some DLL that RMX does not support let me know
and I'll see what I can do. In principle the creation of a replacement
DLL is fairly trivial as I have developed a C++ class framework for
doing that, but I really would like to get the current DLLs working
perfectly before jumping on to the next ones.

However, don't hold your breath while waiting for upgrades, bug-fixes
etc. as I'm developing RMX only in my sparetime. If things get busy at
work I may not be able to work on this for a longer period of time. Of
course, if you really like RMX, you can always buy it from me and
continue developing it yourself or aliternatively pay me enough to be
able to work fulltime on it;-)

And finally a little bit of vapour-ware:-)

If and when OS/2 is available on PowerPC I hope to be able to provide
an RMX implementation that would allow applications running natively
on a PowerPC computer to display their output on an Intel-computer and
vice versa.

The concept for providing remote execution is in no way OS/2 specific.
Most of the code is portable and providing remote execution for Window
NT or Chicago should not be too big a task. When I have enough space
to install them, I will check how much work it would mean.

Again, if you have any question or statement - e.g. that this document is
incomprehensible - please send mail to

    [e-mail]

Cheers,
    Johan


BTW: I've developed RMX as part of my Master's Thesis which I'm about
     to finish right now. If you are interested in it, let me know and
     I'll mail it to you when it's ready.