OS/2 Shareware BBS: 10 Tools/10-Tools.zip/objfac.zip/SYNAPTEC.INF

OS/2 Help File | 1994-03-05 | 15KB | 422 lines

ΓòÉΓòÉΓòÉ 1. Introduction ΓòÉΓòÉΓòÉ

Welcome to The Object Factory, the first SOM development tool!

The Object Factory empowers novice and expert SOM developers with a full GUI
development environment.  The Object Factory is designed to improve the
productivity of all SOM developers.

Novice SOM developers will be aided in their development through a unique GUI
interface with comprehensive error checking and on-line help to aid in
developing SOM classes.

Expert developers will be able to implement classes many times quicker through
drag-drop class inheritance and double-click overrides of all parent methods!

Even a SOM guru will benefit from the inclusion of undocumented SOM classes and
methods!

So make more room on your desk by removing those SOM manuals and enjoy SOM
development with The Object Factory!


ΓòÉΓòÉΓòÉ 2. Requirements ΓòÉΓòÉΓòÉ

The Object Factory will run on OS/2 2.0 and higher.

Class definition files (*.SC extensions) are required for all SOM classes in
the class tree.  If you have the SOM 1.0 compiler from the OS/2 2.0 Developer's
Toolkit, you already have these.

If you ONLY have the SOM 2.0 compiler, these files were not shipped by IBM.
IBM only included 3 class definitions with the SOM 2.0 compiler -- SOMObject,
SOMClass, and SOMClassMgr.

If you only have SOM 2.0, you will only be able to successfully subclass
SOMObject, SOMClass, and SOMClassMgr until you purchase the Developer's
Toolkit.

The Object Factory is compatible with both SOM 1.0 and 2.0, although some of
the advanced features of SOM 2.0 are not currently supported, such as multiple
inheritance.  ALL known features of SOM 1.0 are supported in this version.

A version of The Object Factory with FULL SOM 2.0 support is underway and will
be available soon!


ΓòÉΓòÉΓòÉ 3. Getting Started ΓòÉΓòÉΓòÉ

After installation, 2 new templates were created in your system template
folder.  These templates form the tools used in developing with The Object
Factory -- a class tree and a class development notebook.

The class tree will be used as a repository for all SOM classes plus ALL newly
developed classes which you create.

The class development notebook contains ALL information pertaining to a
particular class which you develop.

Copy these templates anywhere you wish by holding CTRL while dragging a
template to its new location.


ΓòÉΓòÉΓòÉ 4. The Class Tree ΓòÉΓòÉΓòÉ

The class tree is a repository of all SOM classes plus any classes defined by
you.


ΓòÉΓòÉΓòÉ 4.1. Creating a Class Tree ΓòÉΓòÉΓòÉ

The class tree template is used to create new instances of class trees.  To do
this, drag a tree from the template to a location on your desktop.

You may create as many class trees as you wish simply by dragging a new
template on to the desktop, or any other work area you might have.


ΓòÉΓòÉΓòÉ 4.2. Working with a Class Tree ΓòÉΓòÉΓòÉ

To use a class tree, drag class development notebooks to a position within the
tree.  The class on which you drop your new class becomes the parent class of
the dropped object.

If you need to move a class notebook from one parent to another,  just drag the
notebook to the desired parent.  You can move class notebooks from parent to
parent as much as you like.

When moving a compiled class to a new parent, remember that previously
overridden methods may possibly not be inherited from the new parent!

Information about SOM classes may be accessed by double-clicking on the SOM
class about which you would like help.  Use this information to select the most
appropriate parent for your new class.


ΓòÉΓòÉΓòÉ 4.3. Working with Multiple Class Trees ΓòÉΓòÉΓòÉ

You are not bound to a single class tree -- you may wish to have a tree for
each development project.  You are free to create as many trees as you desire.

New classes are not restricted to a particular class tree.  Classes may be
moved or copied among various class trees.

By copying new classes, you may wish to reserve 1 class tree to act as a global
class repository and use other trees for local projects.


ΓòÉΓòÉΓòÉ 4.4. Modifying the Appearance and Window Behavior ΓòÉΓòÉΓòÉ

The appearance and window behavior of a particular class tree may be modified
via the "Settings" notebook.

The settings notebook pages operate exactly as they do for other system
objects.


ΓòÉΓòÉΓòÉ 4.5. Deleting a Class Tree ΓòÉΓòÉΓòÉ

Prior to deleting a class tree, the tree should be scanned to ensure NO new
classes which you wish to keep are inside.  Move classes you wish to keep to
another class tree.

To delete a class tree, select "Delete" from the class tree's system menu.

If you choose to delete a class tree, a confirmation box will appear to remind
you to remove new classes you wish to keep and allow you to abort the delete.


ΓòÉΓòÉΓòÉ 5. The Class Notebook ΓòÉΓòÉΓòÉ

The class notebook is where you develop your new class.  All information
pertaining to your new class is contained within the class notebook.


ΓòÉΓòÉΓòÉ 5.1. Creating a Class Notebook ΓòÉΓòÉΓòÉ

The class notebook template is used to create new instances of class notebooks.
Simply drag a notebook from the template to a location of your choosing and you
have just created a new class notebook.

Until you place a notebook in a class tree,  you do not have a notebook which
can be compiled.

You may create as many class notebooks as you desire.


ΓòÉΓòÉΓòÉ 5.2. Working with a Class Notebook ΓòÉΓòÉΓòÉ

Double-click on a class notebook to access the information associated with the
class.

If this is a new class and you have dropped it in the class tree, some of the
fields will be automatically filled in for you.  For instance, the parent and
inherited methods are known and subsequently filled in for you.

Fill in the required sections of the notebook, plus any of the optional
sections you desire your class to have.  Each page of the notebook has
comprehensive help available.

When you are ready to compile the class, select "Compile" from the notebook's
system menu.  Any compilation errors will be displayed.

If the class compiles correctly, you are ready to modify the emitted stub file
and implement the class.


ΓòÉΓòÉΓòÉ 5.3. Deleting a Class Notebook ΓòÉΓòÉΓòÉ

To delete a class notebook, select "Delete" from the class notebook's system
menu.

If you have system delete confirmations turned on, a confirmation box will
appear to allow you to abort the delete.

Deleting a class notebook will not delete any emitted files which were created
by the notebook.


ΓòÉΓòÉΓòÉ 6. SOM Development Hints ΓòÉΓòÉΓòÉ

SOM development can be frustrating due to the lack of published information.
We have included for you solutions to some of the common pitfalls associated
with implementing new SOM classes.


ΓòÉΓòÉΓòÉ 6.1. Instance and Class Methods ΓòÉΓòÉΓòÉ

Within the emitted C/C++ file created by SOM, the ordering of instance and
class methods is important.  Normally, instance methods appear at the top of
the file and class methods appear at the bottom of the file.

Also, the macro SOM_CurrentClass must be defined as SOMMeta between the two
sections.

The following code shows how the file should look if you overrode the wpSetup
and wpclsQueryTitle methods:

SOM_Scope BOOL  SOMLINK SOMNtbk_wpSetup(SOMNotebook *somSelf, PSZ pszSetupString)
{
return (parent_wpSetup(somSelf,pszSetupString));
}

#undef SOM_CurrentClass
#define SOM_CurrentClass SOMMeta

SOM_Scope PSZ   SOMLINK SOMNtbkcls_wpclsQueryTitle(M_SOMNotebook *somSelf)
{
return (parent_wpclsQueryTitle(somSelf));
}

If you later override or add new instance methods, they must appear above the
SOM_CurrentClass definition.

SOM 1.0 always appends to the bottom of the file, so you must move instance
methods above the SOM_CurrentClass definition!

SOM 2.0 correctly places methods, but forgets to add the definition of
SOM_CurrentClass to the file!.  If you are using SOM 2.0, you should add the
definition of SOM_CurrentClass in the correct position in the emitted C/C++
file yourself!!


ΓòÉΓòÉΓòÉ 6.2. Compiler Settings ΓòÉΓòÉΓòÉ

To implement your SOM class as a WPS object, you must create a DLL.  To do
this, set your C compiler to generate an OS/2 multithreaded DLL.

Also, SOM uses the STANDARD calling convention, not "C".  Set your compiler's
calling convention to STANDARD when compiling SOM DLL's.


ΓòÉΓòÉΓòÉ 6.3. Borland C++ V1.0 ΓòÉΓòÉΓòÉ

In order to correctly initialize your DLL, you must add the following line to
the top of your emitted C/C++ file:

extern int _multidll = 0;

This global variable is documented in the README file shipped with Borland C++.

If you are using SOM 2.0 with Borland C++, examine the README shipped with SOM
2.0 VERY closely.  You will find a requirement that SOMLINK must be defined as
_syscall.

Instead of defining SOMLINK on the SOM command line as README suggests, it is
easier to change SOMLINK in file "\SOM\INCLUDE\SOMLTYPE.H" to "_syscall".


ΓòÉΓòÉΓòÉ 6.4. Variable Name Lengths ΓòÉΓòÉΓòÉ

SOM generates extremely long variable names within its binding files.  This can
cause compilation errors if you have your C compiler's identifier lengths set
too short.  The default for some C compilers is 32 characters.

We suggest setting your C compiler's identifier lengths to at least 100
characters to satisfy the SOM bindings.


ΓòÉΓòÉΓòÉ 6.5. Include files ΓòÉΓòÉΓòÉ

You should add the following lines to either the top of your emitted C/C++ file
or the PASSTHRU *.IH page in the class notebook.

#define INCL_WIN
#define INCL_DOS
#define INCL_WINWORKPLACE
#define INCL_WPCLASS
#include <os2.h>

These lines satisfy requirements imposed by the SOM binding files.


ΓòÉΓòÉΓòÉ 6.6. DLL Definition File ΓòÉΓòÉΓòÉ

The emitted DEF file produced by SOM may be incorrect if you are compiling
using prepended underscores to access your C run-time libraries.  For example,
given the following DEF file:

; This file was generated by the SOM Compiler.
;  FileName: ClssNote.def.
;  Generated using:
;    SOM Precompiler spc: 1.22
;    SOM Emitter emitdef: 1.13
LIBRARY ClassNote INITINSTANCE
DESCRIPTION 'ClassNotebook Class Library'
PROTMODE
DATA MULTIPLE NONSHARED LOADONCALL
EXPORTS
  MyClassNameCClassData
  MyClassNameClassData
  MyClassNameNewClass
  M_MyClassNameCClassData
  M_MyClassNameClassData
  M_MyClassNameNewClass

If you are compiling with prepended underscores turned ON, change the DEF file
to:

; This file was generated by the SOM Compiler.
;  FileName: ClssNote.def.
;  Generated using:
;    SOM Precompiler spc: 1.22
;    SOM Emitter emitdef: 1.13
LIBRARY ClassNote INITINSTANCE
DESCRIPTION 'ClassNotebook Class Library'
PROTMODE
DATA MULTIPLE NONSHARED LOADONCALL
EXPORTS
  _MyClassNameCClassData
  _MyClassNameClassData
  MyClassNameNewClass
  _M_MyClassNameCClassData
  _M_MyClassNameClassData
  M_MyClassNameNewClass


ΓòÉΓòÉΓòÉ 6.7. Linking ΓòÉΓòÉΓòÉ

During the linking of your class objects using your C compiler, you may receive
errors.  Depending on which version of OS2.LIB you have, some classes will not
link correctly.  These problems are not due to The Object Factory.

For example, the OS2.LIB shipped with Borland's C++ V1.0 is missing references
for 16 SOM classes.  OS2386.LIB, on the other hand, is only missing 5.

The Object Factory was designed totally against the SOM class definition files.
This is why the WPJob class appears as "JO" -- IBM's documentation does not
match the class definition file.

If you have any compile or link errors, please be sure to check your OS2.LIB
version and your compiler's INCLUDE path.


ΓòÉΓòÉΓòÉ 7. Backup Procedures ΓòÉΓòÉΓòÉ

The Object Factory was created using SOM and is now part of your operating
system.  As such, it is important that you periodically save copies of your
desktop.

Failure to backup your desktop WILL result in the loss of information contained
in your class trees and class notebooks.

Follow the normal backup procedures for your desktop contained in your OS/2
documentation.  At a minimum, you should issue a BACKUP command on all your
desktop directories AND save copies of OS2.INI and OS2SYS.INI.

The above instructions are not meant to be complete nor entirely accurate for
your machine.  Read your OS/2 documentation for precise instructions on
saving/restoring your desktop information.


ΓòÉΓòÉΓòÉ 8. Product Registration ΓòÉΓòÉΓòÉ

If you would like to receive information on future products from Synaptec,
please print the next page, fill in the requested information, and return via
mail.


ΓòÉΓòÉΓòÉ 8.1. Registration Card ΓòÉΓòÉΓòÉ

                               The Object Factory
                                Registration Card


Name    ____________________________________
Company ____________________________________
Address ____________________________________
City    ____________________________________
State   ____________________________________
Zip     ____________________________________
Phone   ____________________________________
FAX     ____________________________________

Please mail your completed registration card to:

                                 Synaptec, Inc.
                             5085 Forest View Trail
                             Douglasville, GA 30135


ΓòÉΓòÉΓòÉ 9. Contacting Synaptec ΓòÉΓòÉΓòÉ

We at Synaptec hope that this tool makes your SOM development easier and
enjoyable.

We appreciate your business and pledge to provide any assistance you may need
in using The Object Factory.

If you need assistance in using The Object Factory, or experience problems, you
can contact Synaptec at:


                             [phone]  9-5 EST


We will assist you as efficiently as possible.

Due to the complexity of SOM development, we ask that all questions be directly
related to usage of The Object Factory -- we cannot answer questions concerning
implementing your classes.


ΓòÉΓòÉΓòÉ 10. Legalities ΓòÉΓòÉΓòÉ

This section contains trademark and copyright information.


ΓòÉΓòÉΓòÉ 10.1. Trademarks ΓòÉΓòÉΓòÉ

"The Object Factory" and "Synaptec" are trademarks of Synaptec, Inc.

"Borland" and "Borland C++ V1.0" are registered trademarks of Borland
International, Inc.

"IBM", "OS/2", "SOM", "Workplace Shell", and "Developer's Toolkit" are all
registered trademarks of International Business Machines Corporation.


ΓòÉΓòÉΓòÉ 10.2. Copyright ΓòÉΓòÉΓòÉ

Copyright 1994, Synaptec, Inc.  All rights reserved.