View source for Workplace Shell and DSOM: Together at Last

''by [[Eric Osmann]]''

Now that OS/2 Warp Version 3 has hit the main stream, you can take advantage of some of its powerful features. One such feature is Distributed SOM (DSOM), which provides a framework that lets application programs access objects across address spaces. That is, application programs can access objects in other processes, even on different machines. Both the location and implementation of an object are hidden from a client; the client accesses the object (using method calls) in the same manner regardless of its location.

What does this mean to you? You now can call Workplace Shell methods from other processes. Before OS/2 Warp and DSOM, this was not possible. Every Workplace Shell program needed to be registered with the shell, and therefore, run within the Workplace Shell's process. DSOM removes this limitation and allows you to rise to new heights.

OS/2 Warp implements a Workplace Shell DSOM server that is hidden under the covers. When activated, it lets you manipulate the Workplace Shell indirectly through your non-Workplace Shell applications running in their own process.

A Workplace Shell DSOM client application is packaged differently from a conventional Workplace Shell application. Previous versions of OS/2 required that developers package their application in a DLL and register that DLL with the Workplace Shell. In our DSOM environment, this is no longer the case. Developers simply can create a DSOM client executable (.EXE), ensure that the Workplace Shell DSOM server is active, and run their Workplace Shell application as normal. The need to register with the Workplace Shell is gone! 

==To Serve or Not to Serve==
Before any DSOM client application can be run with the Workplace Shell DSOM server, you must first ensure that the server is active. You can do this using one of three methods:

You can use a brute-force method. This requires that you add SET WPDSERVERSTART=ON to your CONFIG.SYS file, therefore, activating the Workplace Shell DSOM server whenever you start the system.

You can activate the server on demand or as required. To do this, use the WPDSINIT utility, which is supplied with OS/2 Warp. This utility allows you to start, stop, and query the Workplace Shell DSOM server at any time.

You can have your Workplace Shell client application query whether or not the DSOM daemon and the Workplace Shell DSOM Server are active. If they are not active, the application simply starts them. The following sample code demonstrates using four new OS/2 Warp APIs to ensure that the DSOM daemon and the Workplace Shell DSOM server are active before attempting to execute any DSOM or Workplace Shell methods.
<PRE>
#define INCL_WINWORKPLACE
#include <os2.h>

...

enum { STOP, START };
APIRET     apiRtnCd;
BOOL       fDaemonUp;
BOOL       fServerUp;

...

// Check if the DSOM daemon active.
// If not, we need to start it before we can continue.
fDaemonUp = WinIsSOMDDReady();
if( !fDaemonUp )
{
   apiRtnCd = WinRestartSOMDD( START );
   if( apiRtnCd )
   {
      somPrintf( "Unable to start the DSOM dameon, rc=%ld\n, apiRtnCd );
      exit( apiRtnCd );
   }
}

// Check if the Workplace Shell DSOM server is up and running,
// If not, we need to start it before we can continue.
fServerUp = WinIsWPDServerReady();
if( !fServerUp )
{
   apiRtnCd = WinRestartWPDServer( START );
   if( apiRtnCd )
   {
      somPrintf( "Unable to start the DSOM server, rc=%ld\n, apiRtnCd );
      exit( apiRtnCd );
   }
}
</PRE>
Note: The absolute minimum is that you start the DSOM daemon. After you start the DSOM daemon, if a client application is run and the server is not already active, the DSOM Implementation Repository automatically starts the Workplace Shell DSOM server. 

==Now What?==
Writing a Workplace Shell DSOM client application requires a little up-front housekeeping. First, you must set up the local DSOM environment and register it with the DSOM daemon as a client program. The following lines of code shows how to do this.
<PRE>
#include <somd.h>
#include <somtcnst.h>

...

Environment *ev;

...

ev = SOM_CreateLocalEnvironment();
SOMD_Init( ev );
</PRE>
Now you must do a little housekeeping for your Workplace Shell environment. Merge the Workplace Shell Class Manager with the SOM Class Manager. The following lines of code will take care of this:
<PRE>
#include <wpclsmgr.h>
WPClassManager *vWPClassManagerObject;

...

vWPClassManagerObject = WPClassManagerNew();
_somMergeInto( SOMClassMgrObject, vWPClassManagerObject );
</PRE>
Moving on to more exciting things, you must initialize all of the Workplace Shell classes that you plan to use, as well as all of the classes that you are a descendant of. For each class, the corresponding <classname>NewClass call must be made. At a minimum, you must include WPObject when working with any Workplace Shell methods.
<PRE>
#include <wpobject.h>
#include <wpabs.h>
#include <wppgm.h>
#include <wpfolder.h>
#include <wpdesk.h>

...

WPObjectNewClass( 1, 1 );
WPAbstractNewClass( 1, 1 );
WPProgramNewClass( 1, 1 );
WPFolderNewClass( 1, 1 );
WPDesktopNewClass( 1, 1 );
</PRE>
To invoke method calls on other processes, such as the case with using Workplace Shell methods, query the handle to the Workplace Shell DSOM server. This is so that when you invoke a Workplace Shell method, the method will actually get dispatched and executed on the Workplace Shell process. The Workplace Shell DSOM Server defaults to wpdServer. You can use the following DSOM method call to query it.
 SOMClass *Server;
 Server = _somdFindServerByName( SOMD_ObjectMgr, ev, "wpdServer" );

==Let's Do It==
Now, we can start calling Workplace Shell methods. To demonstrate, the following sample code queries for a handle to the Workplace Shell desktop, and then creates a new folder with a program object. Notice that the method calls are invoked in the same fashion as conventional non-DSOM Workplace Shell applications, requiring no special consideration.
<PRE>
M_WPFolder *clsFolder;
SOMObject  *objFolder;
SOMObject  *objProgram;
SOMObject  *objDesktop;

...

clsFolder  = _somdGetClassObj( Server, ev, "WPFolder" );
objDesktop = _wpclsQueryFolder( clsFolder, "<WP_DESKTOP>", TRUE );
if( objDesktop )
{
   // Create a WPFolder object on the desktop.
   somPrintf( "Creating a opened WPFolder object on desktop: " );
   objFolder = _wpclsNew( clsFolder, "WoW Folder",
                         "OPEN=ICON;ALWAYSSORT=YES",
                         objDesktop, TRUE );
   somPrintf( "%s\n", objFolder ? "Succeeded" : "\aFailed" );

   // Create a WPProgram object in folder.
   if( objFolder )
   {
      somPrintf( "Creating a WPProgram object in folder: " );
      objProgram = _wpclsNew( _somdGetClassObj( Server, ev, "WPProgram" ),
                              "My Config File",
                              "EXENAME=C:\\OS2\\E.EXE;PARAMETERS=C:\\CONFIG.SYS",
                              objFolder, TRUE );
      somPrintf( "%s\n", objProgram ? "Succeeded" : "\aFailed" );

      //  Let's open our WPProgram object.
      _wpOpen( objProgram, NULLHANDLE, OPEN_DEFAULT, 0L );
   }
}
</PRE>
Wasn't that easy? Now that we are done using the Workplace Shell DSOM server, we need to release our resource, de-register ourselves from the DSOM daemon, and destroy our local DSOM environment.

 _somdReleaseObject( SOMD_ObjectMgr, ev, Server );
 SOMD_Uninit( ev );
 SOM_DestroyLocalEnvironment( ev );

==Experience the Power==
This article covered all of the basic parts to creating a Workplace Shell client DSOM application. As you can see, writing a Workplace Shell DSOM client application is a breeze under OS/2 Warp Version 3.

With OS/2 Warp and SOMObjects Workgroup Enabler for OS/2 Version 2 (purchased separately), your programs are no longer restricted to your machine. After you install the SOMObjects Workgroup Enabler with OS/2 Warp, you can run your Workplace Shell DSOM client applications from any machine connected over a network.

Unleashed in OS/2 Warp is the power and flexibility that every developer has been long awaiting. Check out the sample programs on your accompanying Developer Connection for OS/2 CD-ROM (in the "Source Code from The Developer Connection News" category); experience the power! 

[[Category:SOM Articles]]