═══ 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 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: (404) 942-8699 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.