The OS/2 Workplace Shell introduces many powerful capabilities surfaced in objects that are manipulated on the OS/2 Desktop. Several different object `types' are visible on the desktop, including folders, programs, data files, printers, and palettes. Each object type stores properties using a number of different formats, and most cannot be shared between different OS/2 systems. For example, many of OS/2's objects cannot be copied to floppy disks or to network drives, where they could be shared by a community of users.

Object Desktop provides a powerful new Workplace Shell data type called an Object Package, which is designed to capture object properties as they are stored inside the Workplace Shell, and to allow users to transport objects and properties between OS/2 systems.

An object package is a new type of Workplace Shell container which can store any object type. Any object type that can be viewed in the Workplace Shell can be stored inside a package, including program objects, shadow objects, data files, folders, and printer. All object properties are stored with the objects in the package, including customized icons, folder background changes, and view types. The object package is a convenient way to back up your desktop and share files with other users. System administrators who need to set up multiple, standard desktops can use object packages to clone desktops quickly. The Class Editor provides an interface for replacing or editing classes. You can even generate standard reports, such as INI.RC files, REXX scripts, and hierarchical reports, directly from a package file.

To create an object package:

1. Open the Object Desktop folder and drag a copy of the Object Package template to your desktop.

2. Drag objects from Workplace Shell folders to the new package.

Package It!

That's it! The resulting package is a self-contained file which can be restored on any OS/2 desktop that has Object Desktop installed. You can ship the package on disk, over the network, or through the Internet.

Backing Up Your Desktop

To package all objects on your desktop, choose Store Desktop from the Object Package pop-up menu.

To view the contents of a package, simply double-click the package object. The Tree pane displays the contents of the package. The Editor pane displays the title, class, object and parent IDs, icon data, and setup strings associated with the object that is currently highlighted on the Tree pane.

You can edit data on the Contents pane simply by typing in any of the fields. For example, you may want to tweak the setup strings before copying the package to multiple workstations. To save your changes, choose File, Save. If you forget to save changes, a dialog will prompt you when you try to close the package window.

To remove a file from the package, highlight the file on the Tree pane and then choose Edit, Remove.

Workplace Shell Setup Strings

Each Workplace Shell object is created with a setup string describing the object properties. These properties are generally listed as KEY=VALUE pairs, separated by semicolon characters. The Object Package Editor lists the Workplace Shell setup strings for each object stored in the package file. You can change the properties of each object in the package.

It is beyond the scope of this manual to list all of the Workplace Shell setup strings available for each Workplace Shell class. There are many references on this subject. One excellent reference for OS/2 Warp Workplace Shell setup strings is OS/2 Warp Uncensored, Peter G. Magid, et. al., (The IBM Press), published by IDC Books Worldwide, Inc (ISBN 1-56884-474-3).

Reviewing the Package Contents

Editing Package Contents

The Object Package Workplace Shell class uses several strategies for obtaining setup string data for each Workplace Shell object contained in an object package. These object setup strings are recorded in an efficient form and are forward compatible with new objects as they appear on the market.

An object package is a special data file that contains object properties of stored objects in a hierarchical proprietary object store (object database). Do not attempt to edit an object package using any other tool besides the Package Editor described earlier; the data in a package is not in a readable or manageable form when opened outside the Package Editor.

Object packages contain information that is used to reconstruct objects in their original form, including customized icons, data file content, folder background data, folder presentation data, program object paths, program object types, specialized printer driver data, and much more. Each object contained in an object package contains a number of small chunks of data which each contain a description of how the object should be reconstructed. The data storage is very efficient; for example, icon and data file contents are stored in a compressed form.

To minimize the amount of stored data, Object Desktop uses several storage strategies to avoid duplicating default data such as program object icons, which are identical to the original icons of the executable file. Another mechanism used to minimize storage overhead is to link to Workplace Shell class default data, such as help panels and default folder views, whenever possible.

In addition to objects, a Workplace Shell class database is stored in an object package. The database is used to restore class registrations and class replacements when an object is restored to a different system.

The Package Editor described earlier in this chapter displays each set of object properties listed in the Setup editor window. Each property that is editable is listed with a descriptive name, such as ICONVIEW=ICON,FLOWED. Note that no setup string data is stored inside an object package file; the object properties are only presented as setup strings inside the Package Editor, and of course to the Workplace Shell when the object is recreated. In the ICONVIEW= example, only six bytes are needed to store this folder setting.

Restoring a Package

The process of transferring the objects in a package to a desktop is called restoring a package. For example, if a colleague packaged an application and data files from his desktop and shipped the disk to you, need to restore the package to your desktop in order to use the application and view the data files.

You can restore all objects in a package at once or restore objects individually.

To restore all objects at once:

1. Choose Restore Contents from the package pop-up menu.

To restore individual objects:

1. Double-click the package to open it.

2. On the Tree pane, highlight the object you wish to restore.

3. Choose Action, Restore Selected Object.

Restoring Objects That Already Exist

When restoring an object from an object package, the object may already exist on your system with a similar title in the destination folder, or with the same global object identifier (OBJECTID). When this situation occurs, a dialog similar to the following one is displayed.

On this dialog, choose how objects should be restored by clicking one of the following buttons.

Skip.

Completely skips restoring the specified object, but continues processing objects in the package. If the object is a folder, a dialog will ask if you want to restore the folder's contents.

Create.

Creates a new object in the same folder location as the current existing object, using the same title and object settings. This duplicate function can be used to testing how object packages work.

Update.

Copies the settings from the object stored in the package to the existing object.

Replace.

Deletes the existing object on the system before restoring the object in the package.

Stop.

Skips the current object and stops processing any remaining objects in the object package.

Choosing Skip, Create, Update or Replace will make it the default action when the dialog is displayed again. To skip the dialog for all subsequent object restoration collisions that occur and just perform the action indicated by the selected button, unmark the Continue prompting checkbox .

Workplace Shell Classes and Package Restoration

Each Workplace Shell object is managed by an OS/2 System Object Model (SOM) class which is responsible for providing the behavior of the object as it is seen on the OS/2 Desktop. Each of these classes is registered with the Workplace Shell, which maintains a list of classes that are called upon to provide the entire Workplace Shell Desktop. Each class is invoked by the Workplace Shell via a class name and files containing executable code that provides the class behavior resides in one or dynamic link libraries (DLLs).

In order to restore objects contained in an object package, Object Desktop must interrogate the Workplace Shell class "database" and ensure that each class required to create the contained objects is registered and active in the system. If you attempt to restore an object with a class that is not registered, Object Desktop will first attempt to locate the Workplace Shell class DLLs that were originally used to create the object package, to re-register the Workplace Shell class.

If this process is not successful in registering the class, the Class Registration Advisor dialog will prompt you for information about where the class DLLs are stored on your system.

Workplace Shell Class Registration

The Class Registration Advisor dialog prompts you to specify where the DLL for the Workplace Shell class of the object (or objects) being restored resides. On this dialog, you may choose to register the DLL with the full path or with a "stripped" path which may require an update to the system CONFIG.SYS file. In either case, Object Desktop knows how to immediately register the Workplace Shell class without requiring a system reboot. However, there are instances where a system reboot may be required after registering a Workplace Shell class replacement.

Note on CONFIG.SYS Changes: The Class Registration Advisor dialog provides two mechanisms for registering classes: one with a fully qualified file path for the DLL, and one without the full path. Since both of these mechanisms result in the class being registered, you may wonder why a choice is provided.

Stardock Systems recommends using the registration of Workplace Shell DLLs without fully qualified paths, which may require updates to the OS/2 LIBPATH statement. To enable this option, choose Without module path (update LIBPATH). There are several reasons for this recommendation:

1. Registering a class with the full path results in immediate class availability. Most applications perform class registrations this way, since it does not require a reboot step to create objects on the desktop that correspond to the new class.

Object Desktop is the first product that does not require this type of class registration. All class registrations are immediate if the DLL the class is registered for does not depend on any other DLLs in the system that are not located on the OS/2 CONFIG.SYS LIBPATH statement.

2. Fully qualified paths aggravate a Workplace Shell defect which was fixed with IBM OS/2 Warp FixPak 17 or higher. This defect involves an internal limitation of 4096 bytes of class registration data in the OS/2 Workplace Shell. Because of this problem, registering a large number of OS/2 Workplace Shell classes with fully qualified DLL names can cause system problems that limit further registration of Workplace Shell classes.

3. Registering classes without the fully qualified DLL names provides flexibility in systems management, as directories which contain application code can be moved or renamed along with a change to the OS/2 LIBPATH statement without disturbing objects on the OS/2 Desktop.

The OS/2 CONFIG.SYS and LIBPATH Statement

The CONFIG.SYS file found in the root directory of the OS/2 boot partition contains a statement called the LIBPATH. This statement lists directories which contain Dynamic Link Libraries (DLLs). This directory is searched when application or object code is demand-loaded by the system. Workplace Shell objects are essentially DLLs, and hence the LIBPATH statement may need to be updated in order to enable use of some Workplace Shell classes.

Workplace Shell Class Replacement

The Workplace Shell contains an advanced object-oriented capability called class replacement. This feature allows an application developer to add functionality to objects that are already exist on a system, such as Folders and Program objects. A good example of class replacement is the Enhanced Folder provided by Object Desktop.

The class replacement mechanism is not immediate, however. Class replacement requires the Workplace Shell to be restarted once a replacement is made. The best way to restart the Workplace Shell is to simply reboot or shutdown your computer.

Since an object package is designed to capture all the data for a set of objects, the number and type of class replacements that were present when the package was created is recorded in the package file itself. When an object is restored on a computer that does not have the same class replacements, an attempt is made to register the Workplace Shell classes present on the original system, and to perform the same class replacements. In this case, the object package restoration process will inform you that class replacements were made and the system should be restarted.

Restoring An Object Package Containing a Workplace Shell Desktop

This section describes how to restore the contents of an object package when you have destroyed and reset the contents of your Workplace Shell Desktop using the MAKEINI procedure described in the OS/2 User Guide, or after you have reinstalled OS/2.

A classic chicken/egg problem occurs when the Workplace Shell class for the object package is not registered for the object package that you are trying to restore. You want to invoke the context menu of the package file containing your desktop so you can choose Restore Contents, but since the Workplace Shell has not been told what an object package is, the original object package files appear and behave like normal data files (But remember, don't edit them!).

Object Desktop contains a utility to circumvent this problem, called OBJDINST.EXE. To restore an object package when the Workplace Shell class is not registered, run the following command from an OS/2 Window:

OBJDINST.EXE RESTORE [Package File Path]

You may specify the name of the package file to restore. Ensure that the package file you are trying to restore contains a Desktop archive (created using the Store Desktop command on the Object Package context menu).

The OBJDINST utility registers the Object Package Workplace Shell class. If the class cannot be registered automatically, an opportunity is given to browse your system disks for the original Object Desktop Object Package DLL file, called OBJDOPKG.DLL.

Generating Reports

To generate an INI.RC file, REXX script, or ASCII report, choose Generate from the package pop-up menu and then choose a file type. If the package is open, choose Action, Generate. You will be asked to specify the name and location of the output file.

To open the package Settings notebook, choose Settings from the package pop-up menu. If the package is open, choose File, Settings from the menubar.

On the Storage Options page, you can choose whether to save custom icons that are used for objects stored in the package. If you unmark the Save Custom Icons checkbox, standard icons will be used.

Assign Object IDs.

To assign new object IDs using object titles while the objects are being stored in a package, mark the checkbox. Object IDs are optional for objects, but are necessary for communicating with objects from applications such as REXX.

On the Restore Options page, decide what to do when an object to be restored from a package already exists on the target system. Select a default action by clicking a radio button:

Skip. Does not restore the object.

Create Another. Restores the object by creating a new object. Does not overwrite an object that already exists.

Update. Updates the settings for the object that already exists using the settings stored in the object package.

Replace. Replaces the object that already exists.

Prompt for Decision.

To display a confirmation dialog before performing the selected default action, mark the checkbox beside Prompt for Decision. To automatically perform the default action, unmark the checkbox.

Selecting Package Settings

Auto-extract.

To automatically restore objects when you double-click them, mark the checkbox.

Verify Program Object Paths

Mark this checkbox to check that program object executable paths are reachable when restoring program objects. If a program object is restored with a path (setup string EXENAME=) that does not exist on the destination system, a dialog will appear, allowing this setting to be changed.

Generate Restoration Report

Mark this checkbox to display a dialog after restoring objects, displaying summary information on objects restored, class registrations, class replacements, and any errors encountered restoration.

Restoration Report

A restoration report can be generated after restoring objects from an object package. Summary information is detailed on the progress of the object restorations, including class registration activity, objects created, skipped, updated, or replaced, and object errors logged.

The summary report can be logged to a file, which will appear in the root of the OS/2 boot drive as the file \PKGREPRT.LOG. Alternatively, you may save the log content to another file.

Using the Class Editor

You can edit or replace a class using the Object Desktop Class Editor, which is available from the Object Inspector and the Object Package.

To open the Class Editor, choose Open, Class Editor View from a package's context menu.

When you highlight a class name on the list displayed on the left side of the dialog, information about the class is displayed in the Class Name, Module Name, Location fields.

To remove a class, highlight it on the list and then click the Remove button.

To replace a class:

1 Highlight the replacement class.

2 Mark the checkbox beside Replaces Class.

3 In the Replaces Class field, enter the class name that is being replaced.

To add a new class:

1. Click the Add button.

2. Enter the name of the new class, then click the Add button.

3. Complete the Class Register Advisor screen and then click the Register button. Please refer to the Workplace Shell Class Registration section in this chapter for details.