Address Book -- Workplace Shell Sample (Open Watcom Port)

Port of IBM's 1993 WPS "Address Book" sample from SOM 1.0 .SC format to modern SOM IDL, built with Open Watcom on ArcaOS.

What it does

A simple address book containing person objects with names, addresses, and phone numbers. Demonstrates WPS folder subclassing, custom views, the SOM observer pattern, and restrictive containment.

Class	Inherits from	Purpose
ShrAddressBook	ShrFolder ??? WPFolder	Address book with a custom alphabetically-tabbed "Indexed View"
ShrPerson	WPAbstract	Person record with an "Info" settings page
ShrFolder	WPFolder	Intermediate folder with content-add/remove hooks
ShrList	SOMObject	Ordered list (utility)
ShrNotifier	SOMObject	Observer-pattern notification (keeps views synced with models)

All five classes live in a single DLL (share.dll).

Project layout

  idl\       SOM IDL interface definitions (5 classes)
  h\         SOM bindings (.ih/.h) + project headers
  src\       C implementations, resource scripts, module definitions
  doc\       Original IBM documentation (README.TXT, WPS-PGM.TXT)
  release\   Build output (DLL, EXE, import libs, map files)

Prerequisites

1. Open Watcom installed; WATCOM environment variable set.
2. SOM toolkit headers at C:\os2tk45\som\include (or override SOMINC).
3. OS/2 toolkit headers at C:\os2tk45\h (or override WPSINC).
4. SOM compiler SC.EXE from the toolkit (not Watcom's) ??? needed once to generate bindings. genbind.cmd locates it automatically.
5. ArcaOS / OS/2 to run the build (wmake, wcc386, wlink, wrc, implib).

Build

1. Generate SOM bindings (once)

Run from the project directory on the OS/2 side:

genbind

This invokes the SOM compiler on all five .idl files and writes the .ih / .h bindings into h\. You only need to do this once; the bindings are checked in and rarely change.

2. Build the DLL and EXE

mk

This runs wmake and captures all output to release\wmake.log.

Build products in release\:

File	Description
share.dll	All 5 WPS classes
shrinst.exe	Installation helper (optional)
som.lib	SOM import library (built from C:\OS2\DLL\som.dll)
pmwp.lib	PMWP import library (built from ordinal definitions)

3. Register and run

register

Registers ShrAddressBook and ShrPerson with the WPS and creates an "Address Book" icon on the desktop. Open it and select "Create person".

Note: on some ArcaOS versions SysRegisterObjectClass returns 0 even on success. If register reports failure but no popuplog errors, the registration may have actually succeeded ??? the ground truth is whether SysCreateObject places the icon on the desktop.

Changes in this release

IDL modernization

• Converted all five classes from SOM 1.0 .SC format to standard SOM IDL.
• dllname = "share.dll" in all IDL implementation sections.
• pmstddlg.h included in the C passthru section of shrfoldr.idl.

Build system (Open Watcom)

• Makefile.wat: SYSTEM OS2V2_DLL, -bd for DLL objects, -wcd=1177 for toolkit header warnings, wrc with -i= paths.
• Import libraries: som.lib built directly from C:\OS2\DLL\som.dll via implib (the toolkit's somtk.lib silently drops PMWP-family entries); pmwp.lib built from src\pmwp.def with ordinal imports (PMWP exports by ordinal only).
• genbind.cmd: locates SOM SC.EXE excluding Watcom's; uses sh.exe for stderr capture when available.
• mk.cmd: captures full build output to release\wmake.log.

C source porting

• Added explicit SOMInitModule in src\share.c (modern sc does not generate it) ??? calls ShrListNewClass ??? ShrNotifierNewClass ??? ShrFolderNewClass ??? ShrAddressBookNewClass ??? ShrPersonNewClass.
• Replaced IBM C Set/2 _DLL_InitTerm / _CRT_init pattern with lazy initialization via ShrEnsureDllInit() (Open Watcom has no _CRT_init).
• Added diagnostic ShrLog() calls in SOMInitModule for bring-up.
• #pragma linkage(..., system) for all SOM method overrides.

Resource compilation

• wrc invoked with -i=$(HDIR) -i=$(SOMINC) -i=$(WPSINC) so share.h (which includes <som.h>) resolves correctly.

Troubleshooting

"Registering class failed" / no icon on desktop

1. Check C:\POPUPLOG.OS2 for crash entries mentioning share.dll.
2. Check release\wmake.log for build errors.
3. If the DLL was never loaded (no popuplog entry), the import table may reference DLLs not on LIBPATH ??? verify with lx_export.py or lx_exp.py on the built DLL.

Registration succeeds but SysCreateObject fails

The class registered but the WPS could not instantiate it. Common causes:

• Missing parent class (pmwp.dll not loaded).
• SOMInitModule did not run (check C:\sominit.log).
• Instance data size mismatch between IDL and C implementation.

Build errors

• Unresolved symbols: ensure genbind was run and h\ has all .ih and .h files for the five classes.
• wrc errors on <som.h>: ensure SOMINC points to the SOM include directory.
• sc "not found": run genbind from the OS/2 side, not the Windows host.

License

BSD 3 Clauses see LICENSE.

Links

• https://github.com/OS2World/DEV-SAMPLES-WPS-AddressBook