Class Definition File

Each of these sections is described in more detail below, using examples from the password-protected folder class described earlier in this chapter.

Include Section

Since all system object model classes have a parent, it is necessary to know the name of the parent class and the location of its interface definition. The include section specifies the location of the interface definition file for the parent. In the folder example, only a single line is included:

#
# Include the class definition file for the parent class
#
include <wpfolder.sc>

Since the folder example is simply a specialized form of the WPFolder class, it uses this class as its parent and inherits much of its behavior from the WPFolder class. The include section therefore specifies the interface definition for the WPFolder class. A full list of Workplace Shell classes and their definition files can be found in the IBM OS/2 Version 2.0 Presentation Manager Reference.

Note that the comments that start with a "#" are discarded by the SOM Precompiler; hence the comment in the example above will not be seen in the SOM Precompiler-generated files.

Class Section

This section provides basic information about the new class, specifying its name and various attributes. The password folder example has the following class section entry:

#
#   Define the new class
#
class: PWFolder,
       file stem = pwfolder,
       external prefix = pwFolder_,
       class prefix = pwFoldercls_,
       major version = 1,
       minor version = 1,
       local;
-- PWFolder is a Password-protected folder.
-- Its derived as follows:
--        SOMOject
--          - WPObject
--             - WPFileSystem
--                - WPFolder
--                   - PWFolder

All class definition files must contain a class section. Certain statements within the class section are mandatory, while others are optional.

The first item in the class section is a name:

class: PWFolder,

All classes must have a name.

The file stem specifies the file name to be used by the SOM Precompiler for the generated files. For example, if the file stem statement reads:

file stem = myfile

then the .DEF file generated by the SOM Precompiler would be called myfile.def.

The external prefix specifies a prefix to be used by the SOM Precompiler on all function names. Hence if an external prefix of "pwFolder_" is specified and a method is named "SetInfo", the function name generated by the SOM Precompiler would be "pwFolder_SetInfo".

The SOM Precompiler normally generates a macro for all methods defined by the class, such that the method is referenced in the source code by its defined name, preceded by an underscore character. For example, the method pwFolder_SetInfo described above would be referenced simply as _SetInfo. This helps make the source code more readable and avoids the need for the programmer to type the full name when editing the code.

The class prefix is similar to the external prefix, except that it is used specifically for functions that are class methods. The differences between class methods and instance methods are discussed in Methods (Class Methods).

The major version and minor version are used to ensure that the bindings are at the right level for the class implementation code.

The local option is used to specify that binding files should be linked locally. In " C" programming terms, this means that the following source code is generated:

   #include "wpfolder.h"

If the global option is used, the resulting source code would be as follows:

#include <wpfolder.h>

The last part of the class section is for comments. Using "--" as the comment style causes a comment block to be passed through to the interface definition (.SC) file.

Parent Class Section

The parent class section specifies the parent of the new class. All classes must have this section. The parent class section for the password-protected folder example appears as follows:

#
# Parent class
#
parent: WPFolder;

Release Order Section

This section allows the programmer to specify the sequence in which the methods and public data will be released. Since this sequence is maintained by the SOM Precompiler, other programs using this class will not need to be recompiled every time something new is added to the class.

The password-protected folder example has only one public method in addition to those already defined by its ancestor classes. This method is seen in the release section as follows:

#
# Specify the release order of new methods
#
release order: LockFolder;

Since other public methods are defined by the parent class or by its ancestors, the programmer creating an object class need not define these methods in the class definition file. Hence the programmer need not be aware of the existing methods in the parent class, unless they require modification for use by the new class. This is in accordance with the object-oriented concept of encapsulation.

Metaclass Section

For the password-protected folder example (and in most other cases) an explicit metaclass is not required. The concept of metaclasses is discussed in Metaclasses. Readers desiring more knowledge of programming using metaclasses should refer to the IBM SOM Programming Reference.

Passthru Section

This section allows the programmer to define blocks of C source code that are passed through to any of the files generated by the SOM Precompiler. Each passthru block is distinguished by an identifier, the syntax of which is as follows:

   passthru: <language>.<suffix>

The password-protected folder example has two passthru sections. The first passthru is "C.h", which passes the code block to the C binding file pwfolder.h. This block of code defines a DebugBox macro, which can be used anywhere in the code for the new class.

#
# Passthru a debug message box to the .ih file
# (for inclusion in the .c file)
#
passthru: C.h, after;

#define DebugBox(Title, Text) WinMessageBox(HWND_DESKTOP,
                                            HWND_DESKTOP,
                                            (PSZ)Text,
                                            (PSZ)Title,
                                            0,
                                            MB_OK |
                                            MB_INFORMATION)

endpassthru;

The second passthru block is "C.ph"; this passes the code block to the C binding file pwfolder.ph. This block is used to define a data structure that is accessed by the private methods _GetInfo and _SetInfo, and is used to pass information to and from the dialog procedure that prompts the user for the folder password.

#
# Passthru private definitions to the .ph file
# (for inclusion in the .c file)
#
passthru: C.ph;

typedef struct _PWF_INFO {
                         CHAR   szPassword[20&rbk.;
                         CHAR   szCurrentPassword[20];
                         CHAR   szUserid[20];
                         } PWF_INFO;
typedef PWF_INFO *PPWF_INFO;

endpassthru;

Data Section

This section lists the instance variables used by the class. In the password-protected folder example, three variables are defined as follows:

#
# Define instance data for the class
#
data:
CHAR szPassword[20];
--  This is the password that locks the folder
CHAR szCurrentPassword[20];
--  This is the password the user has entered to be
--  checked against the lock password
CHAR szUserid[20];
--  The userid data is here for future expansion

Note that the szUserid instance variable is not used in the version discussed in this document, since the current example assumes only a single workstation user. However, it is feasible for user identification to be obtained at startup, and held by the system for authentication against a password to determine whether access is permitted.

Methods Section

The last section in the class definition file contains a list of all the methods to be defined by the object class. ANSI C function-prototype syntax is used to define each method. When coding these definitions, it is recommended that the methods be divided into the following parts:

The following section shows two methods taken from the folder example's class definition file.

This first method will be used in the password dialog to take a copy of the object's instance data and place it in a structure that the dialog code may access.

#
# Define new methods
#
methods:

BOOL QueryInfo(PPWF_INFO pPWFolderInfo), private;
--
-- METHOD:   QueryInfo                                   PRIVATE
--
-- PURPOSE:  Copy the PWFolder instance data into
--           the PWF_INFO structure that pPWFolderInfo
--           points to.
--

The second example shows an overridden method. This method originates in the WPObject class, which is a base class. It is used to set up the password string when the folder object is created.

#
# Specify methods being overridden
#

override wpSetup;
--
-- OVERRIDE: wpSetup                                     PUBLIC
--
-- PURPOSE:  Here we can set the folder password
--           to that passed in from the object
--           create command.
--

More detailed information on class definition files and the OIDL is given in the IBM SOM Programming Reference.