Sun and OracleChannel SunHow to BuyLog In한국어

KCMS CMM Developer's Guide
검색에만이 책은
검색 도움말
Contained Within
Find More Documentation
Featured Support Resources
 PDF로 이 문서 다운로드

KcsStatus Extension

8

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.
Code 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), msgfmt(1), and the Solaris 2.4 Developer's Guide to Internationalization for detailed 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:
  1. Use the -lintl linker option when building.

  2. Run xgettext on files using the dgettext function.

  3. Edit the resulting .po file to translate the messages into the appropriate language.

  4. Run msgfmt on the .po file to create a .mo file.

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