Before using the information, and the product it supports, be sure to read the general information under Appendix A, "Notices".

The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law. INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. 

This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time.

It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country.

Requests for technical information about IBM products should be made to your IBM reseller or IBM marketing representative.

(c) Copyright International Business Machines Corporation 1996. All rights reserved.

Note to U.S. Government users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.

Overview

 This guide covers two basic topics, setting up a basic development environment and using the PartMeister tool to kickstart your development effort.

OpenDoc Overview

 OpenDoc is an exciting set of technologies that provide new ways of approaching application development, including the ability to apply object-oriented development techniques very effectively. One of the most important aspects of these technologies for software developers is the immediate introduction to object oriented techniques as the natural way of producing OpenDoc components; inheritence and polymorphism are not left to the developer to fit in, they are simply part of the development process.

As a cross-platform specification built on an open infrastructure, OpenDoc has been adopted as the distributed document component common facility by the OMG. The OpenDoc specifications are maintained by an independent standards organization, Component Integration Labratories (CI-Labs). CI-Labs also licences the technologies for other organizations to implement. OpenDoc has been, or is being, implemented on Mac OS, OS/2 Warp, Windows NT and 95, AIX and Linux. More platforms are expected.

PartMeister Overview

 The goal of PartMeister is to make creating OpenDoc components simple. This allows developers to focus on implementing interesting function, instead of figuring out where to start and reinventing the wheel over and over.

Exciting, object-oriented, open, easy - let's get started !

Pre-release notification

 This version of PartMeister and accompanying documention are beta level. As long as this notice is here, consider the information contained within the document to be useful but preliminary in nature. It should also be assumed that the templates supplied with PartMeister may change and therefore you may be required to change and/or recompile code produced based on this code at a later date.

Package Information

 PartMeister is currently available for OS/2 and Windows (32-bit). PartMeister for AIX will be available later. The base classes are portable between OS/2 and Windows, however the table framework is currently only on OS/2. The code may be compiled with the following compilers:

IBM VisualAge C++ for OS/2 3.0

IBM VisualAge C++ for Windows 3.5

Future editions of the base classes and templates will support other platforms, and additional compiler support will be added as those editions are delivered.

The generated source code can be edited with any editor.

Installation

 PartMeister is shipped as part of the OpenDoc developers kit and independently. If you are installing a version received from a source other than with a toolkit, then use the installation program that accompanies the product. The accompanying README file contains the installation instructions.

If you are installing PartMeister independent of the toolkit, you should direct the install program to replace the version installed by the toolkit install. The installation program will not create a program icon. This is not a problem if you replace the toolkit version, since the original icon will work. If you do not have a program icon, or create a new one, set the working directory to be the same as the install directory in the program settings.

Recommended Development Workstation Setup

 In determining the settings required for the PartMeister tool, it became obvious that there are some good guidelines to follow in setting up a development workstation for creating OpenDoc parts. This section defines a good setup for developers to follow based on my experience and in preparation for cross-platform development.

Two primary directory trees are used, one for base parts and the other for derived parts. Base parts are those that will be derived from, and generally apply to a group of derived parts. The base parts and frameworks shipped with this package are examples of parts that would be kept in the base parts directory.

The advantages to using a base parts directory include easier management of parts (the base parts may be on a network drive that is shared by a development group), and knowledge that changes to parts in the base part directory must be made with the knowledge that their are derived parts that depend on them. This directory also provides a location for the public files directory that all shared files will be stored in. Developers should expect that most base parts will have PartMeister templates associated with them, to create new derived parts.

The derived parts directory is where PartMeister will generate files to, and will be the primary working directory tree that the developer will work in.

It is suggested that upon the setup of the base parts directory, the public files shipped with the OpenDoc toolkit be copied into this directory. This provides a single directory for all shared files to be accessed from, instead of separate directories to be maintained in make files. The public files are located in the following directories:

On OS/2, in TOOLKIT\BETA\SAMPLES\OPENDOC\PUBUTILS

On Windows (June 96 beta), in ODBETA1\SAMPLES\PUBLIC

PartMeister makes this assumption of the development environment when generating make files for parts. If you have a different setup, you may modify the generated files or the templates to reflect the differences.

Using PartMeister; First time usage

 When you start PartMeister for the first time, you will need to configure a few things. Select the Settings menu item on the Part menu to display the settings page.

The first page 'Copyright' provides entry fields to indicate the information that should be placed in the header area of all generated source files. The name will be placed on an author line, the company name and years will be used in a standard copyright notice. Note that multi-year copyright can be signified by specifying the first year followed by a hyphen followed by the last year (ie. 1994-1996).

The second page, Directories, specifies the directories in which the files will be generated (Output) and which will be used in the make file generation. The following are descriptions of usage:

Runtime	where the OpenDoc runtime is installed, including the BIN subdirectory (ie C:\OPENDOC\BIN). This is used in the makefile as the target directory for the DLL to be copied to on successful building of the part.
Public	this is a common directory for all files that are shared by parts including IDL, header and library files. All parts that may be derived from should place there common files in this directory. If you follow the recommended setup, this directory will be the subdirectory 'public' in the base parts directory.
Output	the directory into which files are generated is a subdirectory of this directory. The subdirectory name is specified by the 'short name' on the Part page. If you followed the recommended setup, this directory will be the derived parts directory.

The changes take effect immediately, you do NOT have to exit the program and restart it.

Creating a Part

 The first page on the PartMeister notebook is the Template page. A selection of templates is available, and as each is selected a text description of the generated code is displayed. PartMeister generates derived parts, so the selection of a template is also a selection of the part that will be used as the part for the generated part. Select the template which is most appropriate to the task that you wish the new part to perform.

The next step is to fill in the Part page, with the following:

Class name	the name of the SOM class that will be generated. This is also the part handler name.
Short name	so that files can be generated on systems with the FAT file system installed, an eight character name is required that will be used as the name of the directory into which the files are generated and as the base name for the files.
Category	a list of categories is supplied, based on the list maintained by CI-Labs. If the data type for your part does not match any of the specified categories, fill in a plain text name of your choice.
Kind	create a unique kind for your part. A common mechanism for this is to use your company name followed by a colon followed by the class name (ie IBM:MyPart).
Desktop display name	this text string will be displayed to the end user with the icon for the part. It should be a meaningful name, and may contain spaces (ie Stock Ticker).
Kind display name	user readable name that describes the part kind
Category display name	user readable name that describes the part category

The third page, Symbols, allows templates to provide additional replaceable variables. 

When the pages are filled in, select the Generate menu item from the Part menu. A few seconds later you a generation complete message will be displayed - or you will receive a message indicating that one of the fields is incorrect or empty and requires a change. Given that the source generation completes, you may open a command line window and switch to the output directory to see the generated files.

If no changes are desired, the NMAKE tool can be invoked to compile and link the new part. The resulting DLL file will be copied to the OpenDoc runtime directory.

On OS/2, switch to the OpenDoc runtime directory to register the new part. Type ODINST -cClassName -dDllName to register the part (ie ODINST -cNewPart -dnewpart). Case is important for the class name. On Windows use ODREGPRT ClassName.

You may now use the new part.

PartMeister Templates

 The value of the PartMeister tool is not limited to the flexibility of its interface, instead it is shared between the interface, templates that are used for code generation and the base classes on which the generated code builds. Thus a primary goal of the tool is to provide extensibility without requiring changes to the tool itself, allowing growth through the addition and/or improvement of templates and base classes.

To add additional templates, simply copy the .TPL file and its associated generation files to the PartMeister directory. The next time PartMeister is started, the new template will be loaded. The template file is a plain text file with the following structure:

- all lines consist of a type followed by a colon and one or more values separated by commas.

- blank lines will be ignored

- a line may be up to 1000 characters in length, values are limited to a single line

To create a new file, it is recommended that an existing file be copied and changed. The following are the types and requirements for each line.

TYPE	DESCRIPTION	EXAMPLE
ToolName	IBM PartMeister	IBM PartMeister
FileType	Template Definition File	Template Defintion File
Version	Version Release Modification	1 0 0
Template	Name to place in template list	Table
TemplateType	Code generation parser	Simple
Description	Displayed when template selected	Editable table part
ParentClass	Name of parent class	Table
ParentFileName	File name of parent class	table
Category	Default category of derived part	kODCategoryTable
Platforms	List of platforms supportedv	OS/2, Windows, MacOS, AIX
File	Generator source/target files	table.tc, $filename$.cpp
Symbol	User defined symbols, default value	initialrows, 2

All types except File and Symbol may only be used once. File and Symbol may be used multiple times, with each line requiring the type and colon at the beginning.

The templates used by PartMeister are plain text files that support replaceable values and a few simple functions that operate on the replaceable values. A replaceable value is surrounded by dollar sign ($) delimiters. A function is indicated by placing a colon (:) after the replaceable value and following it with the name of the function. This level of support is defined as a 'simple' template, and is the only level supported in this version.

Replaceable values are not case sensitive.

The following are the predefined replaceable values:

partname	name of the IDL interface (class name)
filename	file name for the new components files
parentname	IDL interface name of parent
parentfilename	file name of parent files
author	name of component author
company	company holding copyright
years	year, or years, for copyright notice
category	OpenDoc part category
kind	OpenDoc part kind
displayname	display name
kinddisplayname	kind display name
categorydisplayname	category display name
runtimepath	OpenDoc runtime directory
publicpath	public files directory
outputpath	target path for generation
toolname	Name of tool generating files
toolversion	Version number of tool generating files

The following are the predefined functions, with an example of each:

toupper	change replaceable value to upper case	$filename:toupper$
tolower	change replaceable value to lower case	$partname:tolower$

Creating an Installation Program for a Part

 When you have created a part, and are ready to distribute the part files, a Component Installation Utility is provided to assist in the installation of the DLL, IDL, source and PartMeister template files. This utility is currently only available on OS/2.

An install script file is provided by the vendor, and the name of the file is the parameter to the CINSTALL executable. The file format has two part lines, the key followed by a colon followed by a value or values. There is no order requirement for the lines, and only the Component line is a single defintion only (if it is defined more than once, the last definition will be used).

Component	text string, will be used in component area on dialog
Runtime	OpenDoc runtime directory
Public	Directory for public files (ie IDL)
PartMeister	Directory where PartMeister is installed, for template and generator files
Source	Source file name, Target directory, Target file name

The Source line has three values, with each values separated by commas. The target directory is the name of the directory that will be created under the 'source' directory specified by the user. An install script may install multiple parts using this feature (for example, see the BaseNonContainer install script).Appendix A: Notices

References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Subject to IBM's valid intellectual property or other legally protectable rights, any functionally equivalent product, program, or service may be used instead of the IBM product, program, or service. The evaluation and verification of the operation in conjunction with other products, except those expressly designated by IBM, are the responsibility of the user.

IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing
IBM Corporation
500 Columbus Avenue
Thornwood, NY 10594
U.S.A.

Licencees of this program who wish to have information about it for purposes of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact IBM Corporation, Department RM1A, 1000 N.W. 51st Street, Boca Raton, FL 33431, U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.