KCMS Calibrator Tool Loadable Interface Guide

Chapter 3 OWconfig Database

In This Chapter

To provide for maximum flexibility in adding software modules, your module is dynamically loaded as a shared object at run time. The list of loadable objects (modules) is maintained in a system configuration database file called OWconfig.

By default, Calibrator Tool reads OWconfig from the /usr/openwin/server/etc directory. If it does not find the OWconfig file or the modules in it that it is looking for, it reads the OWconfig file from /etc/openwin/server/etc.

This chapter explains how to create, insert, and remove OWconfig file entries for calibration modules. The chapter also describes how the server uses the information in OWconfig entries to locate a dynamically loadable module.

Note -

OWconfig is a database for various dynamically loadable objects. It not only can contain entries for calibration but also can include entries for other extensions and X Window System modules. The guidelines in this chapter pertain specifically to modules that interact with Calibrator Tool.

OWconfig Entry

Example 3-1 shows an OWconfig text file entry for a fictitious dynamically loadable calibration module.

Example 3-1 `OWconfig` File Entry

package="SUNWkcsmy" 
class="KCMS_CALIBRATE" name="mydriver"
     kcmsCalDeviceType="monitor"
    kcmsCalLoadableModule="kcmscSUNWmydriver.so.1";

Table 3-1 describes the meaning of each attribute=value pair in the OWconfig file entry.

Table 3-1 Calibration Module Attributes and Meanings


Attribute=	Meaning
package=	This value is a unique name for your `OWconfig` entries.
class=	This value string is always KCMS_CALIBRATE, which uniquely identifies the class of loadable modules that interact with Calibrator Tool.
name=	This value is the name of the loadable module. It uniquely identifies the instance of the class object in the `OWconfig` file and must be different for each loadable module. This name string will appear in the Calibrator Tool Calibrator:Devices window. (See Figure 2-2 in Chapter 2, Calibrating A Monitor.)
kcmsCalDeviceType=	This value is accessed when the end user chooses a particular device type to calibrate. It identifies the type of the device and is used to create a list of loadable modules for this device. The names of all the modules of the specified device type are displayed in the Calibrator:Devices window. (See Figure 2-1 in Chapter 2, Calibrating A Monitor.) There can be several device type entries. Each is uniquely identified by the name= value.
kcmsCalLoadableModule=	This value is the name of the shared object that will be loaded when the end user clicks on Load. It has all the information necessary to start its own application to measure the device data. The module is expected to be installed in the `/usr/openwin/etc/devhandlers/` directory.

Updating the `OWconfig` File

Before your module can be loaded, you need to update the OWconfig file by inserting an entry for your module. To do this, you use the interactive OWconfig_calibrate program provided with the SDK.

To update the OWconfig file, you must be root. If you are not root or the /etc/openwin/server/etc path does not exist, the following error is generated:

OWconfile file not created/updated.
Check that you are root and /etc/openwin/server/etc exists.

Start the OWconfig_calibrate program as follows:

example% su
example# ./OWconfig_calibrate

Inserting An Entry

The following is an example of how to insert a calibrator module configuration entry into the OWconfig file. Sample user responses are enclosed in brackets ([]).

Example 3-2 Inserting A Calibrator Module Entry

ATTENTION: You must be root to update the OWconfig file.

Are you inserting an OWconfig entry? y/n

[y]

You will be asked to supply a name, a device type, and 
a kcsLoadableModule to create an entry such as the
following:  name = 'mydriver'
        kcmsCalDeviceType = 'monitor'
        kcmscCalLoadableModule = 'kcmscSUNWmydriver.so.1'
Please see the KCMS Calibrator Tool LOadable Interface Guide for 
information


The class for this entry will always be KCMS_CALIBRATE 
Enter the unique name of the device  

[mydriver]  

Enter the device type  - normally monitor  

[monitor]  

Enter the name of your dynamically loadable module.  

[kcmsSUNWmydriver.so.1]  

This is your OWconfig entry.  OK? y/n  

class = KCMS_CALIBRATE  name = mydriver 
kmcsCalDeviceType = monitor
kmcsCalLoadableModule = kcmsSUNWmydriver.so.1 
y  

Do you have more entries to create? y/n 
n

The OWconfig_calibrate program above appends the entry to the OWconfig file.

Try inserting the entry shown in the above example using the procedure outlined below:

Run the OWconfig_calibrate program. Be sure you are root.

See "Updating the OWconfig File".

Insert the user responses shown in Example 3-2.

Check for the entry at the end of the OWconfig file.

The new configuration entry is appended to the /usr/openwin/server/etc/OWconfig file. For local machine use only, the /etc/openwin/server/etc/OWconfig file is updated. If you inserted the entry with the user responses in Example 3-2, the entry appears in OWconfig as shown below.

Example 3-3 OWconfig Entry For Calibrator Loadable Module
```
class="KCMS_CALIBRATE" name="mydriver"     kcmsCalDeviceType="monitor"    
kcmsCalLoadableModule="kcmsSUNWmydriver.so.1";
```

Removing Entries

The following is an example of how to remove a configuration entry from the OWconfig file. Sample user responses are enclosed in brackets ([]).

Example 3-4 Removing A Calibrator Module Entry

ATTENTION: You must be root to update the OWconfig file.  

Are you inserting an OWconfig entry? y/n
[n] 
To remove an OWconfig entry:  

Enter the unique name for your driver for removal 
from the OWconfig file.  

[mydriver]  

This is the OWconfig entry to remove.  OK? y/n  

class = KCMS_CALIBRATE  name = mydriver 
[y]  

Do you have

more entries to remove? y/n 
[n]

The OWconfig_calibrate program removes the last entry in the OWconfig file.

Try removing the entry you inserted following Example 3-4. Use the procedure outlined below:

Run the OWconfig_calibrate program again. Be sure you are root.

See "Updating the OWconfig File".

Fill in the user responses shown in Example 3-4.

Check the OWconfig file.

The entry should no longer appear at the end of the file.

Locating and Opening the Module

Calibrator Tool supplies the OWconfig values as arguments to the OWconfig library routines. Using the values, the OWconfig routines find and dynamically open the loadable module. Then, using dlsym(3DL), they execute the module functions.