Work Place Shell Programming - Part 1

Written by Chris Palchak

Purpose
The purpose of this series of articles is to teach the reader how to integrate an application with the OS/2 Work Place Shell. As this writer always looks for ways to avoid using API calls, the settings pages are written in C++ using the IBM Visual Age for C++ compiler and Open Class Library. Hopefully, those readers who are unfamiliar with C++ will be inspired to learn the language once they see the brevity of the settings page programs.

Overview
There are two parts to a Work Place Shell (WPS) program. The first is a System Object Model (SOM) Interface Definition Language (IDL) source file. The second part, is the code you write in C, C++, or some other supported language. This first article will show the reader how to:
 * Create the SOM IDL module,
 * Compile the IDL code,
 * Make the C++ DLL,
 * Register the new WPS class,
 * Create objects of the new class

The second article in this series will show the reader the code that needs to be added to the generated C++ program.

The third article in this series will show the reader how to access this class from another C++ program.

The fourth article in this series will cover a second WPS class.

SOM IDL
IBM's SOM is the basis for all WPS objects. To create custom WPS objects, you must use the SOM IDL. This may seem intimidating at first, but note that there are only two categories of statements in the SOM IDL:
 * 1) Attribute (or data) definition statements
 * 2) Interface (function) declaration statements

Once these statements are prepared, you simply generate stub program files and fill in the functions with your own code. For the purposes of this article, the generated stub files will be C++ programs. The following command will read a SOM IDL file and generate a stub C++ program along with the necessary header files: sc.exe -s"xc;xh;xih;def" -S128000 chfile.idl.

In this case, chfile.idl is the SOM IDL file. The class described in this file is ChartFile. This is a class that inherits from WPDataFile and contains stock quotes. This is the first of two WPS classes that will be developed over the course of these articles. The other class that will be developed is ChartFolder. ChartFolder inherits from WPFolder and is used to store ChartFile objects.

ChFile.idl listing:

The Module Definition File
The following file is generated by the SOM compiler. This file must be modified to include the custom functions declared for setting and getting ChartFile's data.

ChFile.def Listing

This is the modified module definition file. Note that there is no need to use mangled function names for this DLL because the exported functions are not really C++ class members. This file has been named Export.def so that it does not get overlaid when a new ChFile.def gets generated.

Export.def Listing

ChFile.mak Listing

Registering ChartFile
The following REXX program will register the ChartFile class:

Creating instances ChartFile
Even though the SOM compiler creates a C++ class, you can NOT use the "new" operator to create WPS objects. The following REXX program will create a ChartFile object in the Charts directory on drive d:. Alternatively, WinCreateObject can be used to create new ChartFile objects.

Deregistering ChartFile
The following REXX program will deregister the ChartFile class:

Debugging a WPS DLL
Be sure to read the following section in the Workplace Shell Programming Guide that comes with the OS/2 toolkit:
 * Using Workplace Shell Debugging Techniques

This is a subsection of the main section:
 * Debugging Workplace Shell Applications

This information is VERY useful. It shows how to bring up OS/2 with an OS/2 window instead of the WPS. It also shows how to start, stop, and, debug the WPS. Since a DLL can not be debugged directly, the programmer must debug PMSHELL.EXE (the WPS) and set a "Load" break point for the DLL in question.