1 chuck 1.1 <!doctype html public "-//w3c//dtd html 4.0 transitional//en">
2 <html>
3 <head>
4 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
5 mday 1.1.2.2 <meta name="GENERATOR" content="Mozilla/4.76 [en] (X11; U; Linux 2.4.2-2 i686) [Netscape]">
|
6 chuck 1.1 </head>
7 <body text="#000000" bgcolor="#FFFFFF" link="#0000EF" vlink="#55188A" alink="#FF0000">
8
9 <center><font size=+4>Globalization HOWTO</font>
10 <p>Release: Pegasus 2.3
11 <p>Author: Chuck Carmack (carmack@us.ibm.com)
|
12 mday 1.1.2.2 <p>July 28, 2003</center>
|
13 chuck 1.1
14 <p><br>
15 <h2>
16 1.0 Introduction</h2>
17
18 <p><br>As part of the Pegasus 2.3 release, functions were added for globalization
19 support. Globalization involves two major aspects: internationalization
20 and localization.
21 <br>
22 <p>Internationalization is the process of writing a program that is locale-neutral.
23 In other words, the program should be able to run in any locale without
24 change. There are several categories in a locale, including the language
25 of message strings, date format, time format, etc. For release 2.3,
26 the Pegasus server is concerned with the language of the message strings
27 it returns to its clients.
28 <br>
29 <p>To support internationalization, a program is designed to do the following:
30 <br>
31 <blockquote>
32 <li>
33 Support character sets that can represent customer data in any language.
34 chuck 1.1 Typically, the program supports some variation of Unicode for internal
35 data. There is usually some conversion between the supported character
36 sets for external data, and the internal character set. Since Unicode
37 covers all characters, and usually has converters on the platform, it is
38 a good choice for the 'normalized' internal character set.
39 The most 'interoperable' solution for external data is to support UTF-8
40 (eg. network and file system data). The internal data is usually
41 UTF-16 (or UCS-2, but that is deprecated).</li>
42
43 <br>
44 <li>
45 Extract locale-sensitive resources, such as message strings, from the code
46 to external resource files. Typically, the resources are loaded based
47 on the locale requested by the end-user, and returned to the end-user for
48 display.</li>
49 </blockquote>
50
51 <p><br>Localization is the process of customizing a software product to
52 support particular locales. For example, a product that is internationalized
53 might want to only localize for certain countries. This would mean
54 that the localized resources (eg. message files) would only be translated
55 chuck 1.1 and shipped for the countries that the product supports. Since the
56 code for the product is locale-neutral, it will be easy to drop in new
57 translations as more countries are supported.
58 <br>
59 <p>The Pegasus 2.3 release added support for globalization. At a
60 high-level, the following additions were made to Pegasus 2.3:
61 <br>
62 <ul>
63 <li>
64 Support UTF-8 for external data.</li>
65
66 <br>
67 <ul>
68 <li>
69 The CIM-XML documents contained in the HTTP messages</li>
70
71 <li>
72 Repository files and MOF files (<b>TODO</b> - remove MOF files if
73 we can't get this into 2.3)</li>
74 </ul>
75
76 chuck 1.1 <li>
77 Support UTF-16 for internal data.</li>
78
79 <br>
80 <li>
81 Extract the hardcoded messages from the Pegasus code into message files.
82 An API was added to load messages from the message files.</li>
83
84 <br>
85 <li>
86 APIs were added for clients to associate a language with the CIM objects
87 they are sending to Pegasus. Also, APIs were added for clients to
88 determine the language of the error message or CIM object that Pegasus
89 returns.</li>
90
91 <br>
92 <li>
93 APIs were added for providers to determine the language of CIM objects
94 sent by the client. Also, APIs were added for providers to associate
95 a language with the CIM object, or error message, they return to the client.</li>
96 </ul>
97 chuck 1.1
98 <p><br>Please refer to PEPs 56 and 58 for details about the globalization
|
99 mday 1.1.2.2 design in Pegasus 2.3.
|
100 chuck 1.1 <br>
101 <p>This document provides a HOWTO guide to be used by developers to globalize
102 code that is being added to Pegasus. The audience for this document
103 are:
104 <br>
105 <ul>
106 <li>
107 Provider developers - both CMPI and C++</li>
108
109 <li>
110 Client developers</li>
111
112 <li>
113 Pegasus developers</li>
114 </ul>
115
116 <p><br>The quickest way to approach this document is to read the General
117 section, and then the developer section that relates to what you are doing.
118 <br>
119 <h2>
120 2.0 General</h2>
121 chuck 1.1
122 <h3>
123 2.1 Unicode Support</h3>
124
125 <p><br>Pegasus 2.3 supports Unicode throughout the processing of requests.
126 External data to Pegasus is encoded in UTF-8. Internal data is encoded
127 in UTF-16.
128 <br>
129 <p>External data includes the CIM-XML messages passed over the network,
130 the repository files, and the MOF files. For the CIM-XML messages,
131 Pegasus follows section 4.8 of the <a href="http://www.dmtf.org/standards/documents/WBEM/DSP200.html">CIM-HTTP
132 specification</a> Specifically, Pegasus supports the
133 "utf-8" setting for the charset parameter of the Content-Type header and
134 the XML encoding attribute. If no charset is specified, the 7-bit
135 ASCII is assumed. The Pegasus MOF compiler supports UTF-8 encoding
136 in the MOF files. (<b>TODO</b> - remove this statement if this is
137 not in 2.3)
138 <br>
139 <p>The internal support of UTF-16 is encapsulated in the Pegasus String
140 class. This class has been updated to contain UTF-16 characters.
141 Specifically, the Char16 objects inside the String contain UTF-16 characters.
142 chuck 1.1 Note: a UTF-16 surrogate pair is contained in two consecutive Char16 objects.
143 To keep backwards compatibilty, the methods on the String class have not
144 changed. New methods have been added as needed. The following
145 describes this in more detail:
146 <ul>
147 <li>
148 The Pegasus 2.2 methods that take a char *, or return char *, are unchanged.
149 Code written to Pegasus 2.2 may have expected to store 8-bit ASCII (ISO-8859-1)
150 characters into String. These methods will convert the input to UTF-16
151 from 8-bit ASCII. (This is simple because UTF-16 is a superset of
152 8-bit ASCII - simply need to prepend '\0' to each char). The Pegasus
153 2.2 methods that return char data will attempt to convert from the UTF-16
154 internal representation to 8-bit ASCII. Characters that cannot be
155 converted will be replaced with a substitution character.</li>
156
157 <br>
158 <li>
159 All methods that take or return Char16 data are unchanged. The String
160 class now supports UTF-16 data in Char16, although surrogate pairs will
161 require two consecutive Char16 objects. The String class does NO
162 checking for unmatched surrogate pairs.</li>
163 chuck 1.1
164 <br>
165 <li>
166 New methods have been added to take and return UTF-8 data. The String
167 class will convert between UTF-8 and the UTF-16 internal representation
168 as needed. These new methods will use char * parameters, but will
169 be clearly labelled as UTF-8 methods.</li>
170
171 <br> </ul>
172 PROGRAMMING NOTE: Putting EBCDIC data into the String class is dangerous.
173 The String class is designed for UTF-16, which is a superset of 8-bit ASCII.
174 Any String object containing EBCDIC data will not work if it is used by
175 Pegasus to read or write data from external sources, such as the network
176 or repository files. In other words, any String containing EBCDIC
177 data should not leave the code using it.
178 <br>
179 <br>
180 <h3>
181 2.2 Localization Support</h3>
182
183 <h4>
184 chuck 1.1 2.2.1 Language Headers</h4>
185
186 <p><br>Pegasus 2.3 supports clients and providers that wish to localize.
187 There are two areas to be localized: <a href="http://www.dmtf.org/standards/documents/WBEM/DSP201.html#SecERROR">ERROR</a>
188 elements in the CIM-XML; and <a href="http://www.dmtf.org/standards/documents/WBEM/DSP201.html#SecObjectDefinitionElements">Object
189 Definition</a> elements in the CIM-XML. Clients can request
190 the server to return error messages and CIM objects in a set of languages
191 of their choosing. Clients can also tag a language to the CIM objects
192 they are sending to the server. Providers and the server can return
193 error messages and CIM objects that are tagged with one of languages
194 requested by the client.
195 <br>
196 <p>The localization design is based on section 4.8 of the <a href="http://www.dmtf.org/standards/documents/WBEM/DSP200.html">CIM-HTTP
197 specification</a> , which refers to <a href="http://www.ietf.org/rfc/rfc2616.txt?number=2616">RFC
198 2616</a>. The method used to tag a language to the CIM-XML is through
199 the Accept-Language and Content-Language HTTP headers. These headers
200 are basically lists of language tags. An HTTP request can contain
201 an Accept-Language header, which indicates the list of preferred languages
202 that the client wants in the response. This list can be prioritized
203 by using the quality numbers. An HTTP request or response can contain
204 a Content-Language header, which indicates the language(s) of the content
205 chuck 1.1 in the message. In the Pegasus case, this would be the CIM-XML.
206 Note that the Content-Language header is a list of language tags.
207 This allows the content of an HTTP message to contain more than one translation.
208 However, in the Pegasus case, there is only one CIM-XML document in the
209 HTTP message, and thus one translation.
210 <br>
211 <p>CIM clients may use the Accept-Language HTTP header to specify the languages
212 they wish to be returned in the CIM response message. CIM clients
213 may also use the Content-Language header to tag the language of any CIM
214 objects they are sending to the server in the CIM request message.
215 The server, and providers, should attempt to return error messages and
216 CIM objects in one of the accept languages requested by the client.
217 The server and providers should set the Content-Language header in the
218 CIM response message to indicate which of the requested languages they
219 are returning.
220 <br>
221 <p>NOTE: Localization support was not added for the MOF files and
222 repository in Pegasus 2.3. The #pragma locale, #pragma instancelocale,
223 and translatable qualifier flavor are not supported in the Pegasus 2.3
224 MOF compiler. From the client perspective, classes, qualifiers, and
|
225 mday 1.1.2.2 instances stored in the repository are not tagged with a language.
|
226 chuck 1.1 The Accept-Language and Content-Language headers will be ignored for repository
227 operations. However, since the repository will support UTF-8,
228 characters for any language may be stored there.
229 <br>
230 <p>NOTE: Since the Content-Language header applies to the entire
231 HTTP message, it applies to the entire CIM-XML document. This includes
232 all the objects in the document, including enumerated objects, and all
233 the values in the objects. This is a limitation that will remain
234 until the CIM standard has been updated to support language tags tied to
235 individual CIM values. From the client perspective, it is possible
236 for Pegasus to send a CIM response with NO Content-Language, even if the
237 client had sent Accept-Language. This can happen if Pegasus
238 does not know the language of the response. An example is a request
239 that was sent to a Pegasus 2.2 provider. Another example is an enumerated
240 response where each provider returned a different language. Please
241 refer to PEP58 for details on these provider scenarios.
242 <br>
243 <p>Pegasus 2.3 has added classes for the localization support. There
244 are new classes called AcceptLanguages and ContentLanguages that encapsulate
245 the Accept-Language and Content-Language headers, respectively. These
246 classes are basically containers of AcceptLanguageElement and ContentLanguageElement,
247 chuck 1.1 where a language element represents one language tag. The AcceptLanguages
248 class will keep the AcceptLanguageElement's prioritized based on quality,
249 according to RFC 2616.
250 <br>
251 <p>AcceptLanguages and ContentLanguages are the objects used by code throughout
252 the request/response processing, from the client to the server to the providers
253 and back. The server handles the creation of these objects from the
254 HTTP headers. Code at each point in the process will have access
255 to these objects.
256 <br>
257 <p>Please refer to the following files for details on the new Pegasus classes.
258 <br>
259 <ul>
260 <li>
261 pegasus/src/Pegasus/Common/AcceptLanguages.h</li>
262
263 <li>
264 pegasus/src/Pegasus/Common/AcceptLanguageElement.h</li>
265
266 <li>
267 pegasus/src/Pegasus/Common/ContentLanguages.h</li>
268 chuck 1.1
269 <li>
270 pegasus/src/Pegasus/Common/ContentLanguageElement.h</li>
271
272 <li>
273 pegasus/src/Pegasus/Common/LanguageElementContainer.h</li>
274
275 <li>
276 pegasus/src/Pegasus/Common/LanguageElement.h</li>
277 </ul>
278
279 <p><br>See the sections below for details on how to write clients and providers
280 to use these classes.
281 <br>
282 <br>
283 <h4>
|
284 mday 1.1.2.2 2.2.2 Message Bundles</h4>
|
285 chuck 1.1
286 <p><br>One of the goals of globalization for Pegasus 2.3 is the extraction
|
287 mday 1.1.2.2 of hardcoded messages into translated message files, loading translated
288 messages from those files, and returning those messages to the client.
289 The topics to be discussed here are: how to create message files,
290 how to compile message files, and how to load messages into Pegasus.
|
291 chuck 1.1 <br>
292 <p>At the time of writing, the message loading function in Pegasus 2.3
293 used the International Components for Unicode (<a href="http://oss.software.ibm.com/icu">ICU)</a>
294 libraries. This is expected to be the future direction for Pegasus.
295 <a href="http://oss.software.ibm.com/icu">ICU
296 </a>uses
297 a resource bundle format for their message files. In order
298 to load the messages, ICU requires that the resource bundles are compiled
299 into a binary form (.res file) using their genrb tool.
300 <br>
|
301 mday 1.1.2.2 <p>Platform Maintainers Note: Please refer to PEP 58 for information
302 about how to build Pegasus to use the ICU libraries.
303 <br>
|
304 chuck 1.1 <p>The documentation for ICU resource bundles is in the <a href="http://oss.software.ibm.com/icu/userguide/ResourceManagement.html">Resource
305 Management</a> section of the <a href="http://oss.software.ibm.com/icu/userguide/">ICU
306 User Guide</a> . This section will tell you how to
|
307 mday 1.1.2.2 <br>create and organize your resource bundles for different languages.
|
308 chuck 1.1 Note: your resource bundles should be organized in a tree structure
309 similiar to the one shown in the Resource Management section, including
|
310 mday 1.1.2.2 the empty bundles in the tree. It is recommended that you ship a
311 root resource bundle to be used as the fallback in case the client requests
312 a language that you are not supporting.
|
313 chuck 1.1 <br>
314 <p>NOTE: Pegasus 2.3 only supports simple string resources in the
315 ICU resource bundles. String resources may only be loaded by key.
316 Tables, arrays, and other complex resource types, are not supported.
317 <br>
|
318 mday 1.1.2.2 <p>In order to compile your resource bundles, support has been added to
319 the Pegasus make files to run genrb. A new make target, "messages",
320 has been added that will call genrb and put the compiled bundles (.res)
321 in a directory of your choosing. An example of ICU resource bundles
322 and the make files to compile them are located in:
323 <br>
324 <ul>
325 <li>
326 pegasus/src/Providers/sample/LocalizedProvider/Makefile (just causes the
327 make to recurse to the msg sub-directory)</li>
328
329 <li>
330 pegasus/src/Providers/sample/LocalizedProvider/msg/Makefile (compiles the
331 bundles in the msg/ directory)</li>
332
333 <li>
334 pegasus/src/Providers/sample/LocalizedProvider/msg/*.txt (the resource
335 bundles to compile, using the recommended ICU language tree structure)</li>
336 </ul>
337
338 <p><br>NOTE: At the time of writing, only the Linux make files have
339 mday 1.1.2.2 been updated to compile ICU resource bundles.
340 <br>
341 <p>It is important to place the compiled resource bundles in a directory
342 where your code can find them . The make files above compile the
343 resource bundles into $PEGASUS_HOME/msg/provider/localizedProvider.
344 The code that loads these messages uses the MessageLoader class (next section)
345 to load messages from this directory.
346 <br>
347 <br>
348 <h4>
349 2.2.3 Message Loading</h4>
350
351 <p><br>Code that needs to load a message in Pegasus does not call ICU directly.
|
352 chuck 1.1 Two message loading classes were added for Pegasus 2.3: MessageLoader
353 and MessageLoaderParms. These classes are abstractions designed to
|
354 mday 1.1.2.2 hide of the actual loader used (but note that at the time of writing, only
355 ICU is supported). The MessageLoader is used to load a message
356 using a list of preferrred languages. The parameters to MessageLoader
357 are encapsulated in a MessageLoaderParms object.
358 <br>
359 <p>The MessageLoader is the place where the Accept-Language header, Content-Language
360 header, and the ICU resource bundles, join up. The MessageLoader
361 class is designed to receive an AcceptLanguages object, and a set of parameters
362 indicating the bundle base-name and message ID to use. The AcceptLanguages
363 object contains the list of requested languages sent by the client.
364 The MessageLoader searches for the message in the set of bundles named
365 with the base-name, using the AcceptLanguages for the list of specific
366 translated bundles to search. The MessageLoader returns the message
367 that it found, along with a ContentLanguages object indicating the language
368 of the message. The ContentLanguages object should be used to indicate
369 the language of the response sent back to the client.
|
370 chuck 1.1 <br>
371 <p>The MessageLoaderParms object contains the parameters to load the message.
372 There are many parameters, but many can be allowed to default. Here
373 is a description of the parameters:
374 <br>
375 <br>
376 <table BORDER COLS=3 WIDTH="100%" NOSAVE >
377 <tr>
378 <td>String msg_id; </td>
379
380 <td>Input.
381 <br>Required.</td>
382
383 <td>Message ID of the message to load from the resource bundle.
384 This is the key that ICU will use to load the message.</td>
385 </tr>
386
387 <tr>
388 <td>String default_msg;</td>
389
390 <td>Input.
391 chuck 1.1 <br>Required</td>
392
|
393 mday 1.1.2.2 <td>Message to return if the no message can be loaded for msg_id from any
|
394 chuck 1.1 resource bundle. Note: The args parameters below are substituted
395 into this string.
396 <br>Note: For the args into this string, use the Pegasus '$'
397 form, as described in pegasus/src/Pegasus/Common/Formatter.h. Don't
398 use the ICU substitution format for the default message string.</td>
399 </tr>
400
401 <tr>
402 <td>String msg_src_path; </td>
403
404 <td>Input.
405 <br>Optional
406 <br>Default: $PEGASUS_HOME/msg/pegasus/pegasusServer</td>
407
408 <td>Path to the root resource bundle file which contains the msg_id.
|
409 mday 1.1.2.2 <br>Note: Only specify the path down to the bundle base-name. Do
410 not append a language tag, such as "_root" or "_en". Do not append
411 a file extension.
412 <br>Note: relative paths start at $PEGASUS_HOME/msg.
413 <br>Note: defaults to the bundle containing the Pegasus server messages.</td>
|
414 chuck 1.1 </tr>
415
416 <tr>
417 <td>AcceptLanguages acceptlanguages;</td>
418
419 <td>Input.
420 <br>Optional
421 <br>Default: AcceptLanguages::EMPTY</td>
422
423 <td>Contains the list of preferred languages, in priority order.
424 This is combined with msg_src_path to determine which resource bundles
|
425 mday 1.1.2.2 to search for for the msg_id. If not empty, overrides useThreadLocale
|
426 chuck 1.1 and useProcessLocale.</td>
427 </tr>
428
429 <tr>
430 <td>ContentLanguages contentlanguages;</td>
431
432 <td>Output</td>
433
434 <td>Contains the language that MessageLoader found for the msg_id. </td>
435 </tr>
436
437 <tr>
438 <td>Boolean useProcessLocale;</td>
439
440 <td>Input
441 <br>Optional
442 <br>Default = false</td>
443
444 <td>If true, MessageLoader will use the default locale of the process.
445 If true, overrides useThreadLocale.</td>
446 </tr>
447 chuck 1.1
448 <tr>
449 <td>Boolean useThreadLocale;</td>
450
451 <td>Input
452 <br>Optional
453 <br>Default = <font color="#FF0000">true</font></td>
454
|
455 mday 1.1.2.2 <td>If true, MessageLoader will use the AcceptLanguages set by Pegasus
456 into the caller's Thread. See the Note below for details. </td>
|
457 chuck 1.1 </tr>
458
459 <tr>
460 <td>Boolean useICUfallback</td>
461
462 <td>Input
463 <br>Optional
464 <br>Default = false</td>
465
466 <td>If true, use ICU's fallback mechnism to search more general resource
467 bundles if the msg_id cannot be found. Note: the recommended setting
468 is false if you are using an AcceptLanguages from a CIM client. The
469 Accept-Languages HTTP header from the client contains the fallback specifications.</td>
470 </tr>
471
472 <tr>
473 <td>Formatter::Arg arg0;
474 <br> Formatter::Arg arg1;
475 <br> Formatter::Arg arg2;
476 <br> Formatter::Arg arg3;
477 <br> Formatter::Arg arg4;
478 chuck 1.1 <br> Formatter::Arg arg5;
479 <br> Formatter::Arg arg6;
480 <br> Formatter::Arg arg7;
481 <br> Formatter::Arg arg8;
482 <br> Formatter::Arg arg9;</td>
483
484 <td>Input
485 <br>Optional
486 <br>Default: Formatter::Arg( ) // empty arg</td>
487
488 <td>These are the substitution variables, using the Pegasus Formatter::Arg
489 class.</td>
490 </tr>
491 </table>
492
|
493 mday 1.1.2.2 <p>Notes:
494 <br>
495 <p>The "useThreadLocale" parameter defaults to true. This flag indicates
496 to use the AcceptLanguages object set by Pegasus into the Pegasus Thread
497 in which the caller's code is running. This AcceptLanguages object
498 reflects the languages requested by the client. This is useful for
499 code that may not have access to the AcceptLanguages from the client.
500 Pegasus sets this AcceptLanguages object into the Thread of providers and
501 internal Pegasus code. For this reason, it is recommended that provider
502 and internal Pegasus code use the "useThreadLocale" flag instead of explicity
503 passing in an AcceptLanguages object. See the Provider Developer
504 and Pegasus Developer sections for details.
505 <br>
506 <p>The "useProcessLocale" flag can be used to tell MessageLoader to use
507 the default locale of the process, as determined by ICU. This is
508 useful for situations where the caller is not localizing for a client request.
509 The caller may itself be a client (eg. cimconfig), or may need to log messages
510 to the system log in the locale of the Pegasus server process. See
511 the CLI Messages and Logger Messages sections below.
512 <br>
513 <p>"Master switch"
514 mday 1.1.2.2 <br>The MessageLoader class has a public static Boolean variable called
515 _useProcessLocale that may be used to override all the AcceptLanguages
516 and useThreadLocale settings in the MessageLoaderParms objects passed in.
517 This is useful for CLI code (eg cimconfig) that needs to localize its messages
518 based on the locale of its process, which refects the locale set by the
519 user running the CLI (eg. $LANG on Unix). The CLI code may call Pegasus
520 APIs that are coded to use the Thread's AcceptLanguages, which will not
521 be set in this case. The _useProcessLocale static variable tells
522 the MessageLoader to ignore the AcceptLanguages, useThreadLocale, and useProcessLocale
523 settings in MessageLoaderParms that it gets. The MessageLoader will
524 use the default process locale, as determined by ICU, in this case.
525 <br>
526 <p><i>Important Note:</i> The MessageLoader defaults to <i>not </i>use
527 the "fallback" mechanism described in the ICU Resource Management section.
528 This is because the Accept-Language header itself describes the fallback
529 that the client wants. However, the MessageLoader does "fallback"
530 to the root resource bundle if none of the languages in AcceptLanguages
531 can be found. If the root resource bundle cannot be found, then the
532 default_msg is returned. The "useICUFallback" flag can be set to
533 have MessageLoader use ICU fallback on all message load attempts.
534 However, usage of this flag for client requests may lead to incorrect results.
535 mday 1.1.2.2 For example, a client sets Accept-Language to french, german, and spanish,
536 in that order, but there is no french resource bundle. A call to
537 MessageLoader with useICUfallback == true would cause the root resource
538 bundle string to be returned on the attempt to load from the french bundle.
539 But the client requested german to be the fallback after french.
540 <br>
|
541 chuck 1.1 <p>Please refer to the following files for details on the new Pegasus classes.
542 <br>
543 <ul>
544 <li>
545 pegasus/src/Pegasus/Common/MessageLoader.h</li>
546 </ul>
547
548 <h4>
|
549 mday 1.1.2.2 2.2.4 Message Loading Example</h4>
550
551 <p><br>The following example shows how a message may be loaded using the
552 classes described above. Note: this a generic example. Each
553 of the developer sections below have 'real-life' examples that are better
554 suited to each type of code.
|
555 chuck 1.1 <p>// Build an AcceptLanguages with some language elements
556 <br>AcceptLanguages acceptLangs;
557 <br>acceptLangs.add(AcceptLanguageElement("fr", 0.5));
558 <br>acceptLangs.add(AcceptLanguageElement("de", 0.8));
559 <br>acceptLangs.add(AcceptLanguageElement("es", 0.4));
560 <p>// Construct a MessageLoaderParms
561 <br>MessageLoaderParms parms("msgID", "default message");
562 <br>parms. msg_src_path = "/my_msg_dir/my_bundle";
563 <br>parms.acceptlanguages = acceptLangs;
564 <p>// Note: If you have args, set them into MessageLoaderParms
565 <p>// Load the localized String
566 <br>String localizedMsg = MessageLoader::getMessage(parms);
567 <br>
568 <br>
569 <h4>
570 2.2.4 Message Writing Guidelines</h4>
571
572 <p><br>Here are some basic rules for writing messages:
573 <br>
574 <ul>
575 <li>
576 chuck 1.1 If you want to claim that you are globalized, no hardcoded messages!</li>
577
578 <li>
579 Avoid combining messages in the code from other messages. When you
580 do this you are assuming that you know the grammar for every language.</li>
581
582 <li>
583 String substitutions into messages are generally untranslated, ie. not
584 loaded from the resource bundle. Example: a file name.</li>
585
586 <li>
587 Avoid jargon, humour, and cultural idioms. Use full sentences.
588 Have your messages reviewed by your globalization team. Your messages
589 need to make sense to the translators, and ultimately the customer.</li>
590
591 <li>
592 <b>TODO </b>- find a good message writing guide to link to</li>
593 </ul>
594
|
595 mday 1.1.2.2 <h4>
596 2.2.5 Localized Exceptions</h4>
597
598 <p><br>The base Exception class, and derived classes, have been updated
599 to support localization. Constructors have been added that take a
600 MessageLoaderParms object. These constructors will use the MessageLoaderParms
601 object to call the MessageLoader to load the localized exception message.
602 The localized message is saved in the Exception. The ContentLanguages
603 object returned by MessageLoader is also saved in the Exception.
604 This indicates the language of the message. The ContentLanguages
605 object is used later to set the Content-Language header in the HTTP message
606 to the client.
607 <br>
608 <p>The old Exception constructors that take a String will remain.
609 These should be used in cases where the code throwing the exception is
610 not localized, or the String is not localized (for example, a file name).
611 Also, there are several exceptions in Pegasus where the String parameter
612 is meant to be a non-localized substitution in a localized message owned
613 by the Exception (see InternalException.h, ClassNotResolved for an example).
614 The old constructors for these have been kept.
615 <br>
616 mday 1.1.2.2 <br>
|
617 chuck 1.1 <h2>
618 3.0 Provider Developers</h2>
619
620 <h3>
621 3.1 Design Issues</h3>
622
623 <p><br>Providers that wish to globalize should consider the following in
624 their design:
625 <br>
626 <ul>
627 <li>
628 Are there localized string properties that need to be supported?
629 If so, then the client will use Accept-Language to request specific languages
630 for these properties. If the properties are read-only, use MessageLoader
631 to load the localized strings for the properties.</li>
632
633 <li>
634 If you have a localized read/write string property, then the client will
635 use Content-Language to set the property with an associated language.
636 The client will expect to be able to retrieve the property in that same
637 language later (using Accept-Language).</li>
638 chuck 1.1
639 <li>
640 Note: only the string property types in CIM are candidates for localization.
641 The other types, including datetime, are locale-neutral.</li>
642
643 <li>
644 Are there error messages that need to returned to the client in different
645 languages? The client will use Accept-Language to request specific
646 languages for the error messages.</li>
647
648 <li>
649 What resource bundle translations, if any, will be shipped with the provider?</li>
650
651 <li>
652 Do any codepage conversions need to be done between the UTF-16 characters
653 in the String objects and the codepage of data stored on the system?
654 This is a concern for EBCDIC platforms. All EBCDIC data needs to
655 be converted to at least 7-bit ASCII before it is passed into the String
656 object.</li>
657 </ul>
658
659 chuck 1.1 <p><br>To help providers handle the situations described above, Pegasus
660 2.3 will pass the Accept-Language received from the client to the provider.
661 The provider should load strings from its resource bundle based on the
662 client's Accept-Language. The client's Accept-Language is passed
663 to the provider in two ways:
664 <br>
665 <ul>
666 <li>
667 Pegasus will set the Accept-Language from the client into the thread in
668 which the provider is running. By using the useThreadLocale setting
669 in MessageLoaderParms, providers can easily load strings using the client's
670 requested Accept-Language. The provider does not need to know what
671 the Accept-Language is. This is the recommended method to load messages
672 based on the client's request.</li>
673
674 <br>
675 <li>
676 The OperationContext will contain an AcceptLanguages object that has the
677 Accept-Language requested by the client. The provider can use this
678 AcceptLanguages object to load strings with MessageLoader.</li>
679 </ul>
680 chuck 1.1
681 <p><br>The OperationContext will also contain a ContentLanguages object
682 that is set from the Content-Language in the client request. This
683 is the language of the CIM objects being passed to the provider on that
684 request. A localized provider should store the content language along
685 with the data from the CIM objects. This will allow the client to
686 use Accept-Language later to retreive the data in that language.
687 <br>
688 <p>The provider should indicate the language of CIM objects it is returning
689 by calling setLanguage( ) on the ResponseHandler. This will be used
690 to set the Content-Language in the CIM response message sent back to the
691 client. If setLanguage( ) is not called, then no Content-Language
692 will be returned to the client. setLanguage( ) should only be called
693 once per response.
694 <br>
695 <h3>
696 3.2 Sample Code</h3>
697
698 <p><br>The following sample code shows a localized getInstance( ) where
699 the instance returned is localized based on the Accept-Language of the
700 client request. Note that this example also throws a localized exception.
701 chuck 1.1 <br>
702 <p>void LocalizedProvider::getInstance(
703 <br> const OperationContext & context,
704 <br> const CIMObjectPath & instanceReference,
705 <br> const Boolean includeQualifiers,
706 <br> const Boolean includeClassOrigin,
707 <br> const CIMPropertyList & propertyList,
708 <br> InstanceResponseHandler & handler)
709 <br>{
710 <br> // convert a potential fully qualified reference
711 into a local reference
712 <br> // (class name and keys only).
713 <br> CIMObjectPath localReference = CIMObjectPath(
714 <br> String(),
715 <br> String(),
716 <br> instanceReference.getClassName(),
717 <br> instanceReference.getKeyBindings());
718 <p> // begin processing the request
719 <br> handler.processing();
720 <p> // Find the instance to be returned.
721 <br> Uint32 i;
722 chuck 1.1 <br> Uint32 n = _instances.size();
723 <br> for (i = 0; i < n; i++)
724 <br> {
725 <br> if(localReference
726 == _instanceNames[i])
727 <br> {
728 <br>
729 // We found the instance to return
730 <p>
731 // Build the parameters for loading the localized string property.
732 <br>
733 // We are going to let the message loader parameters default to use the
734 <br>
735 // AcceptLanguages that Pegasus set into our thread.
736 <br>
737 // (this equals the AcceptLanguages requested by the client)
738 <br>
739 // Note: This parms object could be constructed once and
740 <br>
741 // reused.
742 <br>
743 chuck 1.1 MessageLoaderParms parms("myMsgID", "myDefaultString");
744 <br>
745 parms.msg_src_path = "/myprovider/msg/myResourceBundle";
746 <p>
747 // Load the string for the localized property from the resource bundle
748 <br>
749 String localizedString = MessageLoader::getMessage(parms);
750 <p>
751 // Remove the old property from the instance to be returned
752 <br>
753 Uint32 index = instances[i].findProperty("myProperty");
754 <br>
755 if (index != PEG_NOT_FOUND)
756 <br>
757 {
758 <br>
759 _instances[i].removeProperty(index);
760 <br>
761 }
762 <p>
763 // Add the localized string property to the instance
764 chuck 1.1 <br>
765 instances[i].addProperty(CIMProperty("myProperty", localizedString));
766 <p>
767 // The MessageLoader set the contentlanguages member
768 <br>
769 // of parms to the language that it found for the message.
770 <br>
771 ContentLanguages rtnLangs = parms.contentlanguages;
772 <p>
773 // We need to tag the instance we are returning with the
774 <br>
775 // the content language.
776 <br>
777 handler.setLanguages(rtnLangs);
778 <p>
779 // deliver requested instance
780 <br>
781 handler.deliver(_instances[i]);
782 <p>
783 break;
784 <br>
785 chuck 1.1 } // end if
786 <br> }
787 // end for
788 <p> // throw an exception if
789 the instance wasn't found
790 <br> if (i == n)
791 <br> {
792 <br>
793 // Build the parameters for loading the localized error message.
794 <br>
795 // We are going to let the message loader parameters default to use the
796 <br>
797 // AcceptLanguages that Pegasus set into our thread.
798 <br>
799 // (this equals the AcceptLanguages requested by the client)
800 <br>
801 // Note: This parms object could be constructed once and
802 <br>
803 // reused.
804 <br>
805 MessageLoaderParms errParms("myErrorMsgID", "myErrorDefaultString");
806 chuck 1.1 <br>
807 errParms.msg_src_path = "/myprovider/msg/myResourceBundle";
808 <p>
809 // Note: the exception calls MessageLoader::getMessage( )
810 <br>
811 // Note: no need to call handler.setLanguages( ) in this case
812 <br>
813 throw CIMObjectNotFoundException(errParms);
814 <br> }
815 <br>
816 <p> // complete processing the
817 request
818 <br> handler.complete();
819 <br>}
820 <br>
821 <p>NOTE: A sample provider has been written that fully demonstates the
822 design issues described above. This provider is located at:
823 <br>
824 <ul>
825 <li>
826 pegasus/src/Providers/sample/LocalizedProvider/</li>
827 chuck 1.1 </ul>
828
829 <p><br>This sample provider also demonstrates how some of the special issues
830 can be handled. The special issues are caused by having a read/only
831 localized property and a read/write localized property. What happens
832 if the client sets the read/write property with a Content-Language that
833 is not one of the supported languages for the read/only property?
834 This provider allows the client to set any language into the read/write
835 property, and get that property back in the same language. This becomes
836 an issue when the client does a getInstance( ) later, because the Content-Language
837 on the returned instance applies to all the properties. A related
838 issue is what to return for Content-Language when the client does enumerateInstances,
839 but the instances have different languages. Recall that Content-Language
840 applies to the entire response (a limitation in the CIM specification).
841 <br>
842 <p>NOTE: Indication Providers have other special considerations for
843 language support. Please refer to PEP58.
844 <br>
845 <p>NOTE: The CMPI interface has been updated for language support.
846 Please refer to the CMPI documentation for details.
847 <br>
848 chuck 1.1 <p>NOTE: SPECIAL ISSUES FOR OS/400 PROVIDERS:
849 <ul>
850 <li>
851 Convert between UTF-16 in the String objects and EBCDIC system data as
852 needed. The converters in Pegasus/Common/OS400ConvertChar.h may be
853 used to convert between EBCDIC CCSID 37 and ASCII CCSID 819 (a subset of
854 UTF-16).</li>
855
856 <li>
857 The Pegasus program, and all bound service programs, will run in
858 a UTF-8 locale even though the job CCSID is 37. The C-runtime library
859 (printf, fopen, isalpha, strcmp, etc) will expect UTF-8, or at least 7-bit
860 ASCII, characters.</li>
861
862 <li>
863 Consideration should be given to the codepage for the compiled string literals.
864 Use #pragma convert as needed. But, remember that the C-runtime will
865 expect UTF-8.</li>
866
867 <li>
868 For more details, refer to "Unicode support" in chapter 3 of the <u>ILE
869 chuck 1.1 C/C++ for iSeries Run-Time Functions, Version 5</u> publication for V5R3
870 (SC41-5607-02). The Pegasus string literals will be compiled with
871 the UTF-8 compile switch described in this section. OS/400 provider
872 developers should strongly consider using the same compile switch for their
873 string literals. This would allow the literals to match the UTF-8
874 encoding expected by the C-runtime.</li>
875 </ul>
876
877 <h2>
878 4. 0 Client Developers</h2>
879
880 <p><br>Methods have been added to CIMClient to set the Accept-Language
881 and Content-Language on the request, and retrieve Content-Language on the
|
882 mday 1.1.2.2 response. The language tags in the Accept-Language header must meet
883 the ISO-639 and ISO-3166 standards.
|
884 chuck 1.1 <br>
885 <p>Please refer to
886 <br>
887 <ul>
888 <li>
889 pegasus/src/Pegasus/Client/CIMClient.h</li>
890
891 <br> </ul>
892 for the new methods on CIMClient.
893 <br>
894 <p>Here is a code fragment that uses the new methods on CIMClient
895 <p> //
896 <br> // Get a localized instance in French
897 <br> //
898 <p> // Language priority is martian, pig-latin, and french.
899 We should
900 <br> // get french back, even though its the lowest priority
901 <br> AcceptLanguages acceptLangs;
902 <br> acceptLangs.add(AcceptLanguageElement("x-martian"));
903 <br> acceptLangs.add(AcceptLanguageElement("fr", 0.1));
904 <br> acceptLangs.add(AcceptLanguageElement("x-pig-latin", 0.4));
905 chuck 1.1 <p> // Set the requested languages into the CIMClient
906 <br> client.setRequestAcceptLanguages(acceptLangs);
907 <p> // Get the instance
908 <br> CIMInstance instance = client.getInstance(
909 <br> NAMESPACE,
910 <br> cimNInstances[0].buildPath(sampleClass),
911 <br> localOnly,
912 <br> includeQualifiers,
913 <br> includeClassOrigin);
914 <p> // Get the string property that should be french
915 <br> String returnedString;
916 <br> instance.getProperty (
917 <br> instance.findProperty("myProp")).
918 <br>
919 getValue().
920 <br>
921 get(returnedString);
922 <p> // Check that we got back french
923 <br> ContentLanguages CL_FR("fr");
924 <br> String expectedFRString = "oui";
925 <br> PEGASUS_ASSERT(CL_FR == client.getResponseContentLanguages());
926 chuck 1.1 <br> PEGASUS_ASSERT(expectedFRString == returnedString);
927 <p> //
928 <br> // Create an instance in French
929 <br> //
930 <p> String oui = "Oui";
931 <br> CIMInstance frInstance(CLASSNAME);
932 <br> frInstance.addProperty(CIMProperty(
933 <br>
934 CIMName("myProp"),
935 <br>
936 oui));
937 <p> CIMObjectPath frInstanceName = frInstance.buildPath(sampleClass);
938 <p> client.setRequestContentLanguages(CL_FR);
939 <p> client.createInstance(NAMESPACE, frInstance);
940 <br>
941 <br>
942 <br>
943 <p>Also, refer to
944 <ul>
945 <li>
946 pegasus/src/Clients/g11ntest/</li>
947 chuck 1.1 </ul>
948 for more examples of a client that uses Accept-Language and Content-Language.
949 <br>
950 <p>NOTE: Consideration should be given for converting the UTF-16
951 characters in the String objects passed over the CIMClient interface to
952 a platform codepage. This is especially needed for EBCDIC platforms.
953 See the Provider developer section for details of the EBCDIC considerations.
954 <br>
|
955 mday 1.1.2.2 <br>
956 <h3>
957 4.1 Default Process Locale</h3>
958
959 <p><br>A method has been added to CIMClient to set the Accept-Language
960 for the requests based on the default locale of the process, as determined
961 by ICU. If ICU is installed on the client system then CIMClient will
962 set the Accept-Language from the default ICU process locale. If ICU
963 is not installed then the caller is required to set an AcceptLanguages
964 into CIMClient that meets the ISO-639 and IS0-3166 standards. Note:
965 this is useful for local clients, such as the Pegasus CLIs, where ICU would
966 be installed on both the client and server sides.
967 <br>
|
968 chuck 1.1 <br>
969 <h2>
970 5. 0 Pegasus Developers</h2>
971
972 <p><br>The design for Pegasus releases beyond 2.3 is to avoid using hardcoded
973 messages. All new messages should be loaded from a Pegasus resource
974 bundle. This section describes the process to follow if you are creating
975 a new message. The process depends on where you are in the code.
976 <br>
977 <br>
978 <h3>
979 <b>5.1 Pegasus Resource Bundles</b></h3>
980
981 <p><br>Place any new Pegasus messages into one of the following resource
982 bundles:
983 <br>
984 <ul>
985 <li>
|
986 mday 1.1.2.2 pegasus/src/Pegasus/msg/Server/pegasusServer_*.txt for server and
987 MOF compiler (cimmof, cimmofl) messages</li>
|
988 chuck 1.1
989 <li>
|
990 mday 1.1.2.2 pegasus/src/Pegasus/msg/CLI/pegasusCLI_*.txt for all CLI messages (except
991 the MOF compiler)</li>
|
992 chuck 1.1 </ul>
|
993 mday 1.1.2.2
994 <p><br>The make messages target will compile these resource bundles.
995 <p>Note: As described above, the resource bundle path in MessageLoaderParms
|
996 chuck 1.1 defaults to the server resource bundle. For CLI messages, you will
997 need to specify the bundle for your CLI.
998 <br>
999 <h3>
1000 5.2 Server Messages</h3>
1001
1002 <p><br>For messages returned from one of the services in the Pegasus server
1003 (eg. CIMOperationRequestDispatcher, or ProviderManagerService), the goal
1004 is to make it easy for any code in the call chain to throw an exception
1005 with a localized error string. The code throwing the exception will
1006 not need to know the Accept-Language that the client requested. To
1007 understand how this works, some design points need to described:
1008 <br>
1009 <p><b>Server Design Points:</b>
1010 <br>
1011 <p>The CIMMessage object has been expanded to include an AcceptLanguages
1012 object and a ContentLanguages object. For CIMRequestMessage, these
1013 objects contain the Accept-Language and Content-Language headers that were
1014 built from the client request. For CIMResponseMessage, the ContentLanguages
1015 object is used to build the Content-Language header associated with the
1016 CIM <i>objects </i>in the response message. The AcceptLanguages object
1017 chuck 1.1 in the CIMResponseMessage is ignored.
1018 <br>
1019 <p>The localization of the cimException object in the CIMResponseMessage
1020 is handled separately from the CIM objects. The message string in
1021 the cimException object is assumed to have been localized by the time it
1022 is built into the XML. For this reason, the localization of the exception
1023 is the responsibility of the code throwing the exception. (The goal
1024 of the design is to make that easy - see below). The ContentLanguages
1025 object in the CIMResponseMessage has NO relation to this exception.
1026 The cimException object keeps its own localization information once it
1027 is created.
1028 <br>
1029 <p>To enable exceptions to be localized, the ability was added to set a
1030 global language for all the code running from a Pegasus Thread object.
1031 The top level code for a Thread can set a global AcceptLanguages object
|
1032 mday 1.1.2.2 that can be accessed by all the low-level functions that it calls.
1033 This will allow an exception thrown by the low-level function to be localized
1034 based on this global AcceptLanguages object. Note: This applies
1035 only to Threads that are managed by a ThreadPool.
|
1036 chuck 1.1 <br>
1037 <p>Each service in the request path of the Pegasus server sets the AcceptLanguages
1038 into its Thread from the AcceptLanguages in the CIMRequestMessage object
1039 that it dequeues. This sets the global langauge for all the functions
1040 in the same thread that are called below handleEnqueue. <i>If you
1041 are writing a new service that processes requests, or discover a request
1042 service that was missed, please do this. </i> The CIMOperationRequestDispatcher
1043 service is an example.
1044 <br>
1045 <p><b>How to Throw a Localized Exception from Server code:</b>
1046 <br>
1047 <p>With all that background, here is how code running in a Pegasus service
1048 can throw a localized exception:
1049 <br>This example assumes that the top-level code in the service had set
|
1050 mday 1.1.2.2 the global thread AcceptLanguages beforehand. As described above,
1051 every service in Pegasus should do that. The code here may be buried
1052 several layers deep in the call chain, but does not need to know the AcceptLanguage
1053 of the current client request.
|
1054 chuck 1.1 <p>// First, construct a MessageLoaderParms
1055 <br>//
1056 <br>// Notes:
1057 <br>// 1) The errorMessageID must be in the Pegasus server resource
1058 bundle.
1059 <br>// 2) The default message is the old "hardcoded" message.
1060 <br>// 3) The MessageLoaderParms will default to use the Pegasus
1061 server resource bundle
|
1062 mday 1.1.2.2 <br>// 4) The MessageLoaderParms will default to use the AcceptLanguages
1063 set into the current Thread. Don't change this!
|
1064 chuck 1.1 <br>// 5) You might need to set the arguments for the message into
1065 the MessageLoaderParms
1066 <br>MessageLoaderParms parms("errorMessageID", "default message");
1067 <p>// Second, throw the Exception
1068 <br>// Note: this applies to all the derived classes from Exception, including
1069 the CIMException's
1070 <br>throw new Exception(parms);
1071 <br>
1072 <p>NOTE: If you are throwing an Exception with un-localized data,
1073 use the constructor that takes a String. An example of this would
1074 be an Exception where you are passing in a file name. Most of the
1075 "non-CIM" exceptions defined in Exception.h and InternalException.h take
1076 un-localized data.
1077 <br>
|
1078 mday 1.1.2.2 <p><b>The Exception Macros</b>
1079 <br>
1080 <p>There are many spots in the server code that use the PEGASUS_CIM_EXCEPTION
1081 macro to throw a TraceableCIMException. The use of this macro in
1082 the code like the following example presented a design problem:
1083 <p>....
1084 <br>} catch (Exception & e)
1085 <br>{
1086 <br> throw PEGASUS_CIM_EXCEPTION(CIM_ERR_FAILED, e.getMessage());
1087 <br>}
1088 <br>
1089 <p>This type of code would have lost the ContentLanguages saved in "e",
1090 so that the Content-Language would not be set in HTTP response to the client.
1091 <br>
1092 <p>For Pegasus 2.3, these types of macro calls can stay. The TraceableCIMException
1093 constructed by the macro will "re-localize". That is, the "CIM" part
1094 of the message (the part based on the error code) will be localized at
1095 throw time, and the ContentLanguages re-established. A key is to
1096 avoid a "language mismatch" problem between the CIM part of the message
1097 and the extra part of the message. The design point here is that
1098 all internal exceptions thrown by Pegasus code are localized using the
1099 mday 1.1.2.2 global AcceptLanguages of the Thread...see above.
1100 <br>
1101 <p>In the future, it will be safer and more maintainable to use of the
1102 new "localized" flavors of the macro. For example:
1103 <br>
1104 <p>When the message from a caught Exception needs to be become the
1105 extra message in a thrown CIMException:
1106 <p>....
1107 <br>} catch (Exception & e)
1108 <br>{
1109 <br> throw PEGASUS_CIM_EXCEPTION_LANG(e.getContentLanguages(
1110 ),
1111 <br>
1112 CIM_ERR_FAILED,
1113 <br>
1114 e.getMessage( ));
1115 <br>}
1116 <br>
1117 <p>This guarantees that the ContentLanguages in "e" is copied to the newly
1118 created TraceableCIMException.
1119 <br>
1120 mday 1.1.2.2 <p>In the case where the extra message for the CIMException is determined
1121 by the throwing code:
1122 <br>
1123 <p>throw PEGASUS_CIM_EXCEPTION_L(CIM_ERR_FAILED,
1124 <br>
1125 MessageLoaderParms("Repository.CIMRepository.COMPACT_FAILED", "compact
1126 failed"));
1127 <br>
1128 <p>(example from CIMRepository.cpp)
1129 <br>This uses a MessageLoaderParms object to localize the extra message
1130 in the newly created TraceableCIMException.
|
1131 chuck 1.1 <br>
1132 <h3>
1133 5.2 Logger Messages</h3>
1134
1135 <p><br>New methods have been added to Logger to take a message ID of a
1136 message to be loaded from the Pegasus server resource bundle. The
|
1137 mday 1.1.2.2 caller is only required to pass in the message ID, the old "hardcoded"
|
1138 chuck 1.1 message, and the args. The Logger will use MessageLoader to load
1139 the message in the locale of the Pegasus server <i>process</i>, using the
|
1140 mday 1.1.2.2 hardcoded message as the default string. Please refer to pegasus/src/Pegasus/Logger.h.
1141 <p>Note: Messages sent to the "logs", whether the system logs or
1142 the Pegasus log file, are converted to UTF-8 before being sent.
|
1143 chuck 1.1 <br>
1144 <h3>
1145 5.3 CLI Messages</h3>
1146
|
1147 mday 1.1.2.2 <p><br>The goal for messages returned by the Pegasus CLIs is to localize
1148 in the locale of the user running the CLI. This should be automatic
1149 -- the user should not be required to tell the CLI what the locale is.
1150 For the CLIs that are CIM clients (cimconfing, cimprovider) there are two
1151 sets of messages to localize -- messages generated in the CLI process
1152 itself, and messages returned from the Pegasus server . For CLIs
1153 that are directly linked into Pegasus (cimmofl), all the messages are generated
1154 in the CLI's process, but the CLI may call Pegasus APIs that are coded
1155 to localize based on a client's requested languages.
1156 <br>
1157 <p>Code in the client side of the client/server CLIs (eg. cimconfig, cimmof),
1158 or in directly linked CLIs (cimmofl), should use the _useProcessLocale
1159 "master switch" described in the Message Loading section. This will
1160 cause all messages, including exceptions thrown by Pegasus APIs,
1161 to be loaded in the locale based on the environment in which the program
1162 is running. This locale can be set by the user before running the
1163 program.
1164 <br>
1165 <p>Code in the client side of the client/server CLIs need to send an Accept-Language
1166 to the Pegasus server that reflects the default locale of the CLI's process.
1167 See the Client Developer section for details.
|
1168 chuck 1.1 <br>
|
1169 mday 1.1.2.2 <p>An example of these considerations can be seen in the source code for
1170 cimconfig.
|
1171 chuck 1.1 <br>
1172 <p>
1173 <hr>
1174 <p><i>Copyright (c) 2003 BMC Software; Hewlett-Packard Development Company,
1175 L.P.; IBM Corp.; The Open Group</i>
1176 <p><i>Permission is hereby granted, free of charge, to any person obtaining
1177 a copy of this software and associated documentation files (the "Software"),
1178 to deal in the Software without restriction, including without limitation
1179 the rights to use, copy, modify, merge, publish, distribute, sublicense,
1180 and/or sell copies of the Software, and to permit persons to whom the Software
1181 is furnished to do so, subject to the following conditions:</i>
1182 <p><i>THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED
1183 IN ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS
1184 PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
1185 INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
1186 FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS
1187 OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
1188 WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT
1189 OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
1190 SOFTWARE.</i>
1191 <br>
1192 chuck 1.1 <br>
1193 </body>
1194 </html>
|
Return to
Globalization_HOWTO.htm
CVS log
Up to [Pegasus] / pegasus / doc