Programming Guide: Creating a Part with PartMeister

# Programming Guide

## Creating a Part with PartMeister

The PartMeister developer utility helps you create OpenDoc source code for parts. It automates the creation of new parts based on templates. Sample templates are provided however, since you may be changing the templates based on your needs, verify the generated source code with the OpenDoc recipes. The generated source code can be compiled with the following compilers:

  IBM VisualAge C++ for OS/2 3.0
  IBM VisualAge C++ for Windows 3.5

The generated source code can be edited with any editor.

### Settings Notebook

Select Settings on the Part menu to display the Settings notebook.

The Copyright tab provides the following fields to indicate the copyright information for the header area in your generated source files. Enter the appropriate information.

Author | Your name.
Company | The name of your company.
Years | The year or years to be used in a standard copyright notice. Note that a multiple year copyright can be used by specifying the first year followed by a hyphen followed by the last year for example, 1994-1996.

The Directory tab specifies the output directory where the files are generated which is used in the make file generation. Enter the appropriate information in the following fields.

Runtime | The target directory, used in the makefile, where the DLL is placed on a successful build of the part.
Public | The include path, used in the makefile, for the SOM compiler (sc.exe) and the C++ compiler (icc.exe). Only one path is allowed. This can be a common directory for all files that are shared by parts including IDL, header, and library files. The recommended setup is that this directory is a subdirectory `public` containing the base parts. For example, `\pmeister\public`. Base parts and frameworks are examples of parts that would be kept in the base parts directory.
Output | The `\pmeister` subdirectory where generated files are placed. For example, `\pmeister\output\mypart` where mypart is the directory name for your part. The directory name is specified by the Short name on the Part page. The recommended setup is that this directory contains the derived parts directories. You can modify the generated make files and other files to correct errors.

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

### Creating a Part

When you open PartMeister the PartMeister notebook is displayed. Once you've completed the Part Settings you are ready to create a part. See "Settings Notebook" for details on the settings.

The Template tab contains a drop-down list of templates that are available. When you select a template the description is displayed. Select the template that is most appropriate to the task you wish the new part to perform. The selected template will be used to generate your new part. For more information on PartMeister templates see "PartMeister Templates".

The Part tab contains the following fields.

Class name

The name of the SOM class that is generated. This is also the part handler name.

Note:

> Only use single byte character set (SBCS) characters in this field. If you use double-byte character set (DBCS) characters your compile will fail.

Short name

An eight character name to be used for the directory where the files are generated and for the base name of the files.

Note:

> Only use single byte character set (SBCS) characters in this field. If you use double-byte character set (DBCS) characters your compile will fail.

Desktop display name | The name of the icon that is displayed. It should be a meaningful name and may contain spaces for example, Stock Ticker.
Category | A list of categories is supplied, based on the list maintained by CI Labs. Select the category. If the data type for your part does not match any of the specified categories, fill in the name of your choice.
Category display name | The name of the category that is displayed on the screen. See "User Strings" for more information.

Kind

The name of your part kind. A common naming convention is to use your company name followed by a colon followed by the class name for example, IBM:MyPart.

Note:

> Only use single byte character set (SBCS) characters in this field. If you use double-byte character set (DBCS) characters your compile will fail.

Kind display name | The name of your part kind that is displayed on the screen. See "User Strings" for more information.

The Symbols tab contains a drop-down list of replaceable values. A description of each symbol is displayed in the Value field. You can change the description if you like by typing text in the Value field.

When the pages are completed, go to the Part Menu and select Generate. When the generation completion message is displayed, the generated files are in the output directory that you specified in the Settings notebook. If no changes are desired you can run the NMAKE tool provided by your compiler to compile and link the new part. The resulting DLL file is copied to the Runtime directory that you specified in the Settings notebook.

Note:

> You must register your part before you can use it. See "Registering a Part Handler" for information on registering part handlers.

### PartMeister Templates

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

- 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.

Table 14. Template Types and Requirements

Type | Description | Path
--- | --- | ---
ToolName | IBM PartMeister | publicpath
FileType | Template Definition File | publicpath
Version | Version Release Modification | publicpath
Template | Name to place in template list | publicpath
TemplateType | Code generation parser | publicpath
Description | Displayed when template selected | publicpath
ParentClass | Name of parent class | publicpath
ParentFileName | File name of parent class | publicpath
Category | Default category of derived part | publicpath
Platforms | List of platforms supported | publicpath
File | Generator source/target files | publicpath
Symbol | User defined symbols, default value | publicpath

All types except File and Symbol can be used only once. File and Symbol may be used multiple times, with each line requiring the type followed by a colon.

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. Replaceable values are not case sensitive.

The following are the predefined replaceable values.

Table 15. Replaceable Values

Replaceable Value | Description
--- | ---
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(s) for copyright notice
category | OpenDoc part category
categorynq | OpenDoc part category (no quotes)
kind | OpenDoc part kind
kindnq | OpenDoc part kind (no quotes)
displayname | display name
displaynamenq | display name (no quotes)
kinddisplayname | kind display name
kinddisplaynamenq | kind display name (no quotes)
categorydisplayname | category display name
categorydisplaynamenq | category display name (no quotes)
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 predefined functions, with an example of each

Table 16. Predefined Functions

Function | Description | Path
--- | --- | ---
toupper | change replaceable value to upper case | publicpath
tolower | change replaceable value to lower case | publicpath

[ Top | Previous | Next | Contents | Index | Documentation Homepage ]