KCMS CMM Developer's Guide

Chapter 8 `KcsStatus` Extension

Every API function returns a KcsStatusId to inform the application when it has executed successfully or, if it has not, why it has failed. If a function successfully executes, it returns the status code KCS_SUCCESS. If the application's user cancels a function before its completion, the function returns the status code KCS_OPERATION_CANCELLED. API calls can also return warning messages. See the SDK manual KCMS Application Developer's Guide for more details.

The KcsStatus extension returns a status message string. Provide a maximum of two functions depending upon whether or not you want custom errors and warnings in your software.

extern

long KcsDLOpenStatCount; char * findErrDesc(KcsStatus statId); char *

findWarningDesc(KcsStatus statId);

findErrDesc()() creates an instance of the function connecting the custom error codes with your string descriptions.

findWarningDesc()() creates an instance of the function connecting the custom warning codes with your string descriptions.

You can add your own findErrDesc()() and findWarningDesc()() functions and provide a header file with your own error and warning numbers and strings. Use custom status codes in your software and identify them with an OwnerId value so that your dynamically loadable status module is used for messages rather than the KCMS default messages. The OwnerId is a long that you set in your loadable module to identify your error and warning messages.

Example

Use these on-line files as a reference for this example:

/opt/SUNWddk/kcms/src/kcssolmsg.cp /opt/SUNWddk/kcms/src/kcssolmsg.h

The following is an excerpt from the kcssolmsg.cc file. Use it as a template when extending the KcsStatus class.

Example 8-1 `KcsStatus` Class Example

... char *

findErrDesc(KcsStatusId statId) { #ifndef KCSSOLMSG_STRINGS #define

KCSSOLMSG_STRINGS 	setlocale (LC_MESSAGES,"");

	bindtextdomain("kcssolmsg.strings","/usr/lib/locale");

#endif 	switch (statId) 	{ 		case KCS_SOLARIS_FILE_NOT_FOUND:

			return(dgettext("kcssolmsg_strings","Could not find

Solaris file type \  					profile")); 		case KCS_X11_WINDOW_PROF_ERROR:

			return(dgettext("kcssolmsg_strings","Error in X11 window

profile")); ...

Header File

In addition to the two functions, findErrDesc()() and findWarningDesc()(), you need to provide a header file to incorporate status messages into your code. The header file should contain the following:

#define

<identifier> <status

number>

This define links a status identifier (for example, KCS_SOLARIS_FILE_NAME_NULL) with a hexadecimal status identification number (for example, 0x4203). You can assign numbers to your own status numbers that are not used by the KCMS library and only in the following specified ranges:

Warning range: 0x1007 - 0x3ffe
Error range: 0x4122 - 0x6ffe

The header file should also contain your OwnerID (for example, SolMsgOwner) by which these messages are distinguished from the KCMS default messages.

The setId() function is one of the KcsStatus class methods.

status->setId(KCS_SOLARIS_FILE_NOT_FOUND,

SolMsgOwner);

It sets an ID (OwnerID) that tells the KcsStatus class function, getDescription()(), that it is not a KCMS library error and to search the OWconfig file for a dynamically loadable module containing the matching error descriptions.

This example also contains code that prepares the message strings for language localization. You must setlocale(3C) and bindtextdomain(3I) once, so choose a unique define with which to ifdef these functions. Also choose a message file name for the message extraction script, xgettext(3I), in the makefile.

Localizing Messages

Note that the message strings are arguments in the dgettext(3I) function that marks these strings for inclusion in the kcssolmsg_strings.po file upon running xgettext()() on this code file.

These are very terse notes on what the application or library should contain and what you should run to create a file of messages ready to be translated into the local language.

See setlocale(3C), bindtextdomain(3I), gettext(3I), dgettext(3I),and msgfmt(1) for information on internationalization and localization.

Application Module

The application, or library module must include the following code:

#include

<locale.h> #include <libintl.h>

setlocale("LC_MESSAGES",

"<language>");

bindtestdomain("string_file_name","directory");

dgettext("string_file_name",

"message");

where

language is one of the language locale directories in /usr/lib/locale

directory is the location of the installed translated message file, string_file_name

message is the message string to translate

Developer

As the CMM developer, you must do the following tasks to create a file of messages to translate into the local language:

Use the -lintl linker option when building.
Run xgettext on files using the dgettext() function.
Edit the resulting .po file to translate the messages into the appropriate language.
Run msgfmt on the .po file to create a .mo file.
Move the .mo file to the appropriate directory, such as /usr/openwin/lib/locale/<language>/LC_MESSAGES.

The application should then pick up the translated messages.

Chapter 8 KcsStatus Extension