Runtime Derivation Coding Requirements

This section describes what you need to do in the code of each of your CMM derivatives so that the derivative can be executed at runtime.

Runtime Derivation Code Examples

For code examples showing how to use the wrapper functions and entry points described in the sections below, see the chapter describing that derived class. The chapters are:

• Chapter 4, KcsIO Derivative "

• Chapter 5, KcsProfile Derivative "

• Chapter 6, KcsProfileFormat Derivative "

• Chapter 7, KcsXform Derivative "

In addition, see the sample programs in /opt/SUNWddk/kcms/src. The directory contains brief sample programs that illustrate all the coding requirements described in this section.

Wrapper Functions

To allocate an object at runtime, you use wrapper functions. Wrapper functions are implemented in C and perform a C++-to-C conversion. The allocation routines return a pointer to the base class object that indicates to the C++ compiler what is returned, but not the definitions. As in typical C, you can reference symbols in a sharable library because the functions are defined as extern C {}().

These functions are written in C++ and call new()() (or its equivalent alternative). Since the shareable object code has all of the header information from the base class, the derivative is constructed properly and has the same structure as statically-linked code.

External Entry Points

You need to provide the KCMS framework with an external entry point to load each of your derivatives as an executable. The symbols are loaded and the derivative is called by the framework to access your derivative's functionality.

The types of entry points for a runtime derivative are:

• mandatory

• optional

• base-class specific

In the paragraphs that follow, XXXX refers to the base class identifier from which it is being derived. XXXX can only have the following values:

• IO

• Prof

• Pfm

• Xfrm

• Stat

Mandatory

For each runtime derivative, you must supply a C-based variable and an external entry point. Respectively, these are:

• KcsDLOpen()XXXXCount()()

• KcsCreate()XXXX()()

The KcsDLOpenStatusCount()()variable is the only requirement for extending the KcsStatus class.

KcsDLOpen()XXXXCount()()

extern

long

KcsDLOpen()XXXXCount();

KcsDLOpen()XXXXCount()()is the number of times the shareable object was opened. It is equivalent to the number of times the shareable object is being shared. The CMM should not set this variable. It is controlled by the KCMS framework.

KcsCreate()XXXX()()

KcsXXXX

*KcsCreateXXXX(KcsStatus *,

XXXX creation

args);

KcsCreate()XXXX()() is one of possibly many creation entry points. This entry point maps directly to the static create()XXXX()() methods of the base class from which it is being derived. The arguments following KcsStatus * are specific to the base class and are described in the appropriate class chapter. See the chapters describing the KcsIO, KcsProfile, KcsProfileFormat, and KcsXform classes (Chapter 4, KcsIO Derivative through Chapter 7, KcsXform Derivative , respectively). The CMM must support all declared create()XXXX()() methods; otherwise, applications receive CMM errors from calls to load()().

Optional

Runtime derivatives can supply the following external entry points:

• KcsInit()XXXX()()

• KcsCleanup()XXXX()()

It is highly recommended that you use the KcsInit()XXXX()() entry point to verify the version of the versions so that your CMM can use the profile data properly.

KcsInit()XXXX()()

KcsStatus

KcsInit()XXXX(long libMajor,

long libMinor,  		long *myMajor, long

*myMinor);

If you supply the KcsInit()XXXX()()entry point, the KCMS framework calls it when the shareable object is loaded for the first time. This initializes and derives private allocations before any creation method is called. KcsInit()XXXX()() checks for minor version numbering. See "Configuration Requirements" for more information.

KcsCleanup()XXXX()()

KcsStatus

KcsCleanup()XXXX()();

If you supply the KcsCleanup()XXXX()()entry point, the KCMS framework calls it when the shareable object is unloaded for the last time (when KcsDLOpen()XXXXCount = 0()). This cleans up shareable objects when they are no longer needed.

Base-Class Specific

Each base class also provides additional necessary and optional entry points. See the chapters describing the KcsIO, KcsProfile, KcsProfileFormat, and KcsXform classes (Chapter 4, KcsIO Derivative through Chapter 7, KcsXform Derivative , respectively), for detailed explanations.

Instantiation

You instantiate KCMS framework objects or any runtime derivations of that object with the following methods:

• createXXXX()()

• attach()()

• new()()

create()XXXX()()

You allocate an object with the create()XXXX()() method. This method combines sharing of the object with runtime derivative support. With chunk set-based objects, this function searches for a match through allocated objects. If it finds a match, it attaches to that object and returns its address. If it does not find a match or the object is not chunk set based, it searches for a match through objects in the runtime-loadable object files.

To maximize the runtime nature of the KCMS framework, it is recommended that you use the create()XXXX()() method whenever possible within your CMM derivative. It enables derivatives statically linked into an application or included directly in the KCMS framework's shared object libraries (such as, libkcs) to use the correct and latest version of your CMM derivative.

Note that the KcsStatus class extension is an exception to this recommendation. It passes back a status string rather than a pointer to a derivative, and only two C functions are written.

attach()()

You use the attach()() method to share an object. If an object already exists, it can be shared in memory with this method. You can share the object with other users of that object. Any changes in the object are applied to objects that share it. If you share an object, make sure that object does not change while your derivative is attached to it.

new()()

To get a new object of a specified type or a KCMS framework derivative, you use the new()() method. This allows a runtime derivative to actually override a built-in type after it has been released.

Initialization and Cleanup

The KcsLoadable class loads a runtime derivative's binaries when a create()() method is used. It generates the shared object's configuration file keywords based on class, derivative, and version identifiers. It retrieves the module name and loads the library. See "Creating OWconfig File Entries" for further information.

The KcsLoadable class then locates the KcsDLOpen()XXXXCount() variable. If KcsDLOpen()XXXXCount = 0, it locates and loads the KcsInit()XXXX()() entry point and, if available, calls it. Then the KcsCreate()XXXX()() entry point is located and loaded. If everything is successful, the KcsCreate()XXXX()()entry point is called.

When the last of a specific derivative type is deallocated and the KcsCleanup()XXXX()() entry point is available, it is located, loaded, and called.