summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorchuck <chuck>2003-12-01 19:57:38 +0000
committerchuck <chuck>2003-12-01 19:57:38 +0000
commitb4db368f7cb607d223801e593a36c8093416b6b2 (patch)
treea4d10c4f4d748a95ffe768c13eaa69af5c2871e6
parente3f871438214c09f17b9940672e5e7bf0b7a6f83 (diff)
downloadtog-pegasus-RELEASE_2_3_0-branch.zip
tog-pegasus-RELEASE_2_3_0-branch.tar.gz
tog-pegasus-RELEASE_2_3_0-branch.tar.xz
IBM-CC, update HOWTORELEASE_2_3_0-branch
-rw-r--r--doc/Globalization_HOWTO.htm322
1 files changed, 170 insertions, 152 deletions
diff --git a/doc/Globalization_HOWTO.htm b/doc/Globalization_HOWTO.htm
index 58fa132..653007f 100644
--- a/doc/Globalization_HOWTO.htm
+++ b/doc/Globalization_HOWTO.htm
@@ -8,12 +8,31 @@
</head>
<body text="#000000" bgcolor="#ffffff" link="#0000ef" vlink="#55188a"
alink="#ff0000">
-<center><font size="+4">Globalization HOWTO</font>
+<center>
+<p><big><big><big>Globalization HOWTO</big></big></big></p>
<p>Release: Pegasus 2.3 </p>
<p>Author: Chuck Carmack (carmack@us.ibm.com) </p>
-<p>July 28, 2003</p>
+<p>December 1, 2003</p>
</center>
<p><br>
+Change History:<br>
+</p>
+<table cellpadding="2" cellspacing="2" border="1"
+ style="text-align: left; width: 100%; margin-left: auto; margin-right: auto;">
+ <tbody>
+ <tr>
+ <td style="vertical-align: top;">01/12/03<br>
+ </td>
+ <td style="vertical-align: top;">carmack<br>
+ </td>
+ <td style="vertical-align: top;">Section 2.2.2. &nbsp;Changed how
+the package name parameter should be used. &nbsp;It should no longer be
+used as part of the table name inside the bundle.<br>
+ </td>
+ </tr>
+ </tbody>
+</table>
+<p><br>
</p>
<h2> 1.0 Introduction</h2>
<p><br>
@@ -25,8 +44,8 @@ aspects:&nbsp; internationalization and localization. <br>
locale-neutral.&nbsp; In other words, the program should be able to run
in any locale without change.&nbsp; There are several categories in a
locale, including the language of message strings, date format, time
-format, etc.&nbsp; For release 2.3, the Pegasus server is concerned
-with the language of the message strings it returns to its clients. <br>
+format, etc.&nbsp; For release 2.3, the Pegasus server is concerned with
+the language of the message strings it returns to its clients. <br>
&nbsp; </p>
<p>To support internationalization, a program is designed to do the
following: <br>
@@ -39,8 +58,8 @@ the internal character set.&nbsp; Since Unicode covers all characters,
and usually has converters on the platform, it is a good choice for the
'normalized' internal character set.&nbsp;&nbsp;&nbsp; The most
'interoperable' solution for external data is to support UTF-8 (eg.
-network and file system data).&nbsp; The internal data is usually
-UTF-16 (or UCS-2, but that is deprecated).</li>
+network and file system data).&nbsp; The internal data is usually UTF-16
+(or UCS-2, but that is deprecated).</li>
<br>
&nbsp; <li> Extract locale-sensitive resources, such as message
strings, from the code to external resource files.&nbsp; Typically, the
@@ -79,14 +98,14 @@ message files.&nbsp; An API was added to load messages from the message
files.</li>
<br>
&nbsp; <li> APIs were added for clients to associate a language with
-the CIM objects they are sending to Pegasus.&nbsp; Also, APIs were
-added for clients to determine the language of the error message or CIM
+the CIM objects they are sending to Pegasus.&nbsp; Also, APIs were added
+for clients to determine the language of the error message or CIM
object that Pegasus returns.</li>
<br>
&nbsp; <li> APIs were added for providers to determine the language of
CIM objects sent by the client.&nbsp; Also, APIs were added for
-providers to associate a language with the CIM object, or error
-message, they return to the client.</li>
+providers to associate a language with the CIM object, or error message,
+they return to the client.</li>
</ul>
<p><br>
Please refer to PEPs 56 and 58 for details about the globalization
@@ -137,23 +156,23 @@ this in more detail: </p>
<li> The Pegasus 2.2 methods that take a char *, or return char *, are
unchanged.&nbsp; Code written to Pegasus 2.2 may have expected to store
8-bit ASCII (ISO-8859-1) characters into String.&nbsp; These methods
-will convert the input to UTF-16 from 8-bit ASCII.&nbsp; (This is
-simple because UTF-16 is a superset of 8-bit ASCII - simply need to
-prepend '\0' to each char).&nbsp; The Pegasus 2.2 methods that return
-char data will attempt to convert from the UTF-16 internal
-representation to 8-bit ASCII.&nbsp; Characters that cannot be
-converted will be replaced with a substitution character.</li>
+will convert the input to UTF-16 from 8-bit ASCII.&nbsp; (This is simple
+because UTF-16 is a superset of 8-bit ASCII - simply need to prepend
+'\0' to each char).&nbsp; The Pegasus 2.2 methods that return char data
+will attempt to convert from the UTF-16 internal representation to
+8-bit ASCII.&nbsp; Characters that cannot be converted will be replaced
+with a substitution character.</li>
<br>
&nbsp; <li> All methods that take or return Char16 data are
unchanged.&nbsp; The String class now supports UTF-16 data in Char16,
although surrogate pairs will require two consecutive Char16
-objects.&nbsp; The String class does NO checking for unmatched
-surrogate pairs.</li>
+objects.&nbsp; The String class does NO checking for unmatched surrogate
+pairs.</li>
<br>
&nbsp; <li> New methods have been added to take and return UTF-8
data.&nbsp; The String class will convert between UTF-8 and the UTF-16
-internal representation as needed.&nbsp; These new methods will use
-char * parameters, but will be clearly labelled as UTF-8 methods.</li>
+internal representation as needed.&nbsp; These new methods will use char
+* parameters, but will be clearly labelled as UTF-8 methods.</li>
<br>
&nbsp;
</ul>
@@ -162,8 +181,8 @@ dangerous.&nbsp; The String class is designed for UTF-16, which is a
superset of 8-bit ASCII.&nbsp; Any String object containing EBCDIC data
will not work if it is used by Pegasus to read or write data from
external sources, such as the network or repository files.&nbsp; In
-other words, any String containing EBCDIC data should not leave the
-code using it. <br>
+other words, any String containing EBCDIC data should not leave the code
+using it. <br>
&nbsp; <br>
&nbsp;
<h3> 2.2 Localization Support</h3>
@@ -202,13 +221,13 @@ and thus one translation. <br>
&nbsp; </p>
<p>CIM clients may use the Accept-Language HTTP header to specify the
languages they wish to be returned in the CIM response message.&nbsp;
-CIM clients may also use the Content-Language header to tag the
-language of any CIM objects they are sending to the server in the CIM
-request message.&nbsp; The server, and providers, should attempt to
-return error messages and CIM objects in one of the accept languages
-requested by the client.&nbsp; The server and providers should set the
-Content-Language header in the CIM response message to indicate which
-of the requested languages they are returning. <br>
+CIM clients may also use the Content-Language header to tag the language
+of any CIM objects they are sending to the server in the CIM request
+message.&nbsp; The server, and providers, should attempt to return
+error messages and CIM objects in one of the accept languages requested
+by the client.&nbsp; The server and providers should set the
+Content-Language header in the CIM response message to indicate which of
+the requested languages they are returning. <br>
&nbsp; </p>
<p>NOTE:&nbsp; Localization support was not added for the MOF files and
repository in Pegasus 2.3.&nbsp; The #pragma locale, #pragma
@@ -217,8 +236,8 @@ the Pegasus 2.3 MOF compiler.&nbsp; From the client perspective,
classes, qualifiers, and instances stored in the repository are not
tagged with a language.&nbsp; The Accept-Language and Content-Language
headers will be ignored for repository operations.&nbsp; However, since
-the repository will support UTF-8,&nbsp; characters for any language
-may be stored there. <br>
+the repository will support UTF-8,&nbsp; characters for any language may
+be stored there. <br>
&nbsp; </p>
<p>NOTE:&nbsp; Since the Content-Language header applies to the entire
HTTP message, it applies to the entire CIM-XML document.&nbsp; This
@@ -227,11 +246,11 @@ and all the values in the objects.&nbsp; This is a limitation that will
remain until the CIM standard has been updated to support language tags
tied to individual CIM values.&nbsp; From the client perspective, it is
possible for Pegasus to send a CIM response with NO Content-Language,
-even if the client had sent Accept-Language.&nbsp;&nbsp; This can
-happen if Pegasus does not know the language of the response.&nbsp; An
-example is a request that was sent to a Pegasus 2.2 provider.&nbsp;
-Another example is an enumerated response where each provider returned
-a different language.&nbsp; Please refer to PEP58 for details on these
+even if the client had sent Accept-Language.&nbsp;&nbsp; This can happen
+if Pegasus does not know the language of the response.&nbsp; An example
+is a request that was sent to a Pegasus 2.2 provider.&nbsp; Another
+example is an enumerated response where each provider returned a
+different language.&nbsp; Please refer to PEP58 for details on these
provider scenarios. <br>
&nbsp; </p>
<p>Pegasus 2.3 has added classes for the localization support.&nbsp;
@@ -290,39 +309,42 @@ information about how to build Pegasus to use the ICU libraries. <br>
href="http://oss.software.ibm.com/icu/userguide/ResourceManagement.html">Resource
Management</a>&nbsp; section of the <a
href="http://oss.software.ibm.com/icu/userguide/">ICU User Guide</a>
-.&nbsp; This section will tell you how to <br>
-create and organize your resource bundles for different
-languages.&nbsp; Note:&nbsp; your resource bundles should be organized
-in a tree structure similiar to the one shown in the Resource
-Management section, including the empty bundles in the tree.&nbsp; It
-is recommended that you ship a root resource bundle to be used as the
-fallback in case the client requests a language that you are not
+.&nbsp; This section will tell you how to create and organize your
+resource bundles for different languages.&nbsp; Note:&nbsp; your
+resource bundles should be organized in a tree structure similiar to
+the one shown in the Resource Management section, including the empty
+bundles in the tree.&nbsp;<br>
+</p>
+<p><br>
+It is recommended that you ship a root resource bundle to be used as
+the fallback in case the client requests a language that you are not
supporting.&nbsp; The Pegasus make files are set up to automatically
create and compile a root resource bundle for you.&nbsp; For Pegasus
2.3, the make will use your "en" bundle, upper case all the messages,
and then put the uppercased messages into the root bundle.&nbsp; The
uppercasing of the messages is necessary to create a "fallback" root
-bundle that contains invariant characters across all EBCIC and
+bundle that contains invariant characters across all EBCDIC and
ASCII&nbsp;codepages. <br>
&nbsp; </p>
<p>NOTE:&nbsp; When creating your resource bundles, the name of the
-table resource should contain the package name.&nbsp;&nbsp;&nbsp; For
-example, if you have a bundle with a package name of "xyz", then the
-"en" bundle should start like this: </p>
-<p>xyz_en:table { <br>
+table resource should <span style="font-style: italic;">not</span>
+contain the package name.&nbsp;&nbsp;&nbsp; For example, if you <br>
+have a bundle with a package name of "xyz", then the "en" bundle should
+start like this: </p>
+<p><br>
+en:table { <br>
..... messages here <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-} <br>
-&nbsp; </p>
-<p><i>not</i> like this: </p>
-<p>en:table { <br>
+}</p>
+<p><i>not</i> like this:</p>
+<p>xyz_en:table { <br>
..... messages here <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-} </p>
-<p>This is different than some of the examples in the <a
- href="http://oss.software.ibm.com/icu/userguide/ResourceManagement.html">Resource
-Management</a> section, but is needed because the -p option is not used
-on genrb by the make files. <br>
+} <br>
+&nbsp; <br>
+</p>
+<p>This is needed because the package name (-p) option is used by the
+Pegasus make files on the call to genrb. <br>
&nbsp; </p>
<p>NOTE:&nbsp; Pegasus 2.3 only supports simple string resources in the
ICU resource bundles.&nbsp; String resources may only be loaded by
@@ -360,9 +382,9 @@ messages from this directory. <br>
<p><br>
Code that needs to load a message in Pegasus does not call ICU
directly.&nbsp; Two message loading classes were added for Pegasus
-2.3:&nbsp; MessageLoader and MessageLoaderParms.&nbsp; These classes
-are abstractions designed to hide of the actual loader used (but note
-that at the time of writing, only ICU is supported).&nbsp;&nbsp; The
+2.3:&nbsp; MessageLoader and MessageLoaderParms.&nbsp; These classes are
+abstractions designed to hide of the actual loader used (but note that
+at the time of writing, only ICU is supported).&nbsp;&nbsp; The
MessageLoader is used to load a message using a list of preferrred
languages.&nbsp; The parameters to MessageLoader are encapsulated in a
MessageLoaderParms object. <br>
@@ -371,15 +393,14 @@ MessageLoaderParms object. <br>
Content-Language header, and the ICU resource bundles, join up.&nbsp;
The MessageLoader class is designed to receive an AcceptLanguages
object, and a set of parameters indicating the bundle base-name and
-message ID to use.&nbsp; The AcceptLanguages object contains the list
-of requested languages sent by the client.&nbsp; The MessageLoader
-searches for the message in the set of bundles named with the
-base-name, using the AcceptLanguages for the list of specific
-translated bundles to search.&nbsp; The MessageLoader returns the
-message that it found, along with a ContentLanguages object indicating
-the language of the message.&nbsp; The ContentLanguages object should
-be used to indicate the language of the response sent back to the
-client. <br>
+message ID to use.&nbsp; The AcceptLanguages object contains the list of
+requested languages sent by the client.&nbsp; The MessageLoader
+searches for the message in the set of bundles named with the base-name,
+using the AcceptLanguages for the list of specific translated bundles
+to search.&nbsp; The MessageLoader returns the message that it found,
+along with a ContentLanguages object indicating the language of the
+message.&nbsp; The ContentLanguages object should be used to indicate
+the language of the response sent back to the client. <br>
&nbsp; </p>
<p>The MessageLoaderParms object contains the parameters to load the
message.&nbsp; There are many parameters, but many can be allowed to
@@ -411,7 +432,7 @@ Don't use the ICU substitution format for the default message string.</td>
<td>Input.&nbsp; <br>
Optional <br>
Default: $PEGASUS_HOME/msg/pegasus/pegasusServer</td>
- <td>Path to the root resource bundle file which contains the
+ <td>Path to the resource bundle file which contains the
msg_id.&nbsp; <br>
Note: Only specify the path down to the bundle base-name.&nbsp; Do not
append a language tag, such as "_root" or "_en".&nbsp; Do not append a
@@ -426,8 +447,8 @@ Optional <br>
Default: AcceptLanguages::EMPTY</td>
<td>Contains the list of preferred languages, in priority
order.&nbsp; This is combined with msg_src_path to determine which
-resource bundles to search for for the msg_id.&nbsp;&nbsp; If not
-empty, overrides useThreadLocale and useProcessLocale.</td>
+resource bundles to search for for the msg_id.&nbsp;&nbsp; If not empty,
+overrides useThreadLocale and useProcessLocale.</td>
</tr>
<tr>
<td>ContentLanguages contentlanguages;</td>
@@ -461,7 +482,8 @@ Default = false</td>
resource bundles if the msg_id cannot be found.&nbsp; Note: the
recommended setting is false if you are using an AcceptLanguages from a
CIM client.&nbsp; The Accept-Languages HTTP header from the client
-contains the fallback specifications.</td>
+contains the fallback specifications. &nbsp;Using ICU's fallback in this
+case may lead to returning a language that the client didn't ask for.</td>
</tr>
<tr>
<td>Formatter::Arg arg0; <br>
@@ -490,18 +512,18 @@ indicates to use the AcceptLanguages object set by Pegasus into the
Pegasus Thread in which the caller's code is running.&nbsp; This
AcceptLanguages object reflects the languages requested by the
client.&nbsp; This is useful for code that may not have access to the
-AcceptLanguages from the client.&nbsp; Pegasus sets this
-AcceptLanguages object into the Thread of providers and internal
-Pegasus code.&nbsp; For this reason, it is recommended that provider
-and internal Pegasus code use the "useThreadLocale" flag instead of
-explicity passing in an AcceptLanguages object.&nbsp; See the Provider
-Developer and Pegasus Developer sections for details. <br>
+AcceptLanguages from the client.&nbsp; Pegasus sets this AcceptLanguages
+object into the Thread of providers and internal Pegasus code.&nbsp;
+For this reason, it is recommended that provider and internal Pegasus
+code use the "useThreadLocale" flag instead of explicity passing in an
+AcceptLanguages object.&nbsp; See the Provider Developer and Pegasus
+Developer sections for details. <br>
&nbsp; </p>
<p>The "useProcessLocale" flag can be used to tell MessageLoader to use
the default locale of the process, as determined by ICU.&nbsp; This is
useful for situations where the caller is not localizing for a client
-request.&nbsp; The caller may itself be a client (eg. cimconfig), or
-may need to log messages to the system log in the locale of the Pegasus
+request.&nbsp; The caller may itself be a client (eg. cimconfig), or may
+need to log messages to the system log in the locale of the Pegasus
server process.&nbsp; See the CLI Messages and Logger Messages sections
below. <br>
&nbsp; </p>
@@ -523,18 +545,18 @@ default process locale, as determined by ICU, in this case. <br>
the "fallback" mechanism described in the ICU Resource Management
section.&nbsp; This is because the Accept-Language header itself
describes the fallback that the client wants.&nbsp; However, the
-MessageLoader does "fallback" to the root resource bundle if none of
-the languages in AcceptLanguages can be found.&nbsp; If the root
-resource bundle cannot be found, then the default_msg is
-returned.&nbsp; The "useICUFallback" flag can be set to have
-MessageLoader use ICU fallback on all message load attempts.&nbsp;
-However, usage of this flag for client requests may lead to incorrect
-results.&nbsp; For example, a client sets Accept-Language to french,
-german, and spanish, in that order, but there is no french resource
-bundle.&nbsp; A call to MessageLoader with useICUfallback == true would
-cause the root resource bundle string to be returned on the attempt to
-load from the french bundle.&nbsp; But the client requested german to
-be the fallback after french. <br>
+MessageLoader does "fallback" to the root resource bundle if none of the
+languages in AcceptLanguages can be found.&nbsp; If the root resource
+bundle cannot be found, then the default_msg is returned.&nbsp; The
+"useICUFallback" flag can be set to have MessageLoader use ICU fallback
+on all message load attempts.&nbsp; However, usage of this flag for
+client requests may lead to incorrect results.&nbsp; For example, a
+client sets Accept-Language to french, german, and spanish, in that
+order, but there is no french resource bundle.&nbsp; A call to
+MessageLoader with useICUfallback == true would cause the root resource
+bundle string to be returned on the attempt to load from the french
+bundle.&nbsp; But the client requested german to be the fallback after
+french. <br>
&nbsp; </p>
<p>Please refer to the following files for details on the new Pegasus
classes. <br>
@@ -569,9 +591,9 @@ Here are some basic rules for writing messages: <br>
<ul>
<li> If you want to claim that you are globalized, no hardcoded
messages!</li>
- <li> Avoid combining messages in the code from other messages.&nbsp;
-When you do this you are assuming that you know the grammar for every
-language.</li>
+ <li> Avoid creating a message in the code by combining other
+messages.&nbsp; When you do this you are assuming that you know the
+grammar for every language.</li>
<li> String substitutions into messages are generally untranslated,
ie. not loaded from the resource bundle.&nbsp;&nbsp; Example: a file
name.</li>
@@ -587,12 +609,11 @@ The base Exception class, and derived classes, have been updated to
support localization.&nbsp; Constructors have been added that take a
MessageLoaderParms object.&nbsp; These constructors will use the
MessageLoaderParms object to call the MessageLoader to load the
-localized exception message.&nbsp; The localized message is saved in
-the Exception.&nbsp; The ContentLanguages object returned by
-MessageLoader is also saved in the Exception.&nbsp; This indicates the
-language of the message.&nbsp; The ContentLanguages object is used
-later to set the Content-Language header in the HTTP message to the
-client. <br>
+localized exception message.&nbsp; The localized message is saved in the
+Exception.&nbsp; The ContentLanguages object returned by MessageLoader
+is also saved in the Exception.&nbsp; This indicates the language of
+the message.&nbsp; The ContentLanguages object is used later to set the
+Content-Language header in the HTTP message to the client. <br>
&nbsp; </p>
<p>The old Exception constructors that take a String will remain.&nbsp;
These should be used in cases where the code throwing the exception is
@@ -614,9 +635,9 @@ design: <br>
<ul>
<li> Are there localized string properties that need to be
supported?&nbsp; If so, then the client will use Accept-Language to
-request specific languages for these properties.&nbsp; If the
-properties are read-only, use MessageLoader to load the localized
-strings for the properties.</li>
+request specific languages for these properties.&nbsp; If the properties
+are read-only, use MessageLoader to load the localized strings for the
+properties.</li>
<li> If you have a localized read/write string property, then the
client will use Content-Language to set the property with an associated
language.&nbsp; The client will expect to be able to retrieve the
@@ -645,16 +666,14 @@ Accept-Language is passed to the provider in two ways: <br>
<ul>
<li> Pegasus will set the Accept-Language from the client into the
thread in which the provider is running.&nbsp; By using the
-useThreadLocale setting in MessageLoaderParms, providers can easily
-load strings using the client's requested Accept-Language.&nbsp; The
+useThreadLocale setting in MessageLoaderParms, providers can easily load
+strings using the client's requested Accept-Language.&nbsp; The
provider does not need to know what the Accept-Language is.&nbsp; This
-is the recommended method to load messages based on the client's
-request.</li>
+is the recommended method to load messages based on the client's request.</li>
<br>
&nbsp; <li> The OperationContext will contain an AcceptLanguages object
-that has the Accept-Language requested by the client.&nbsp; The
-provider can use this AcceptLanguages object to load strings with
-MessageLoader.</li>
+that has the Accept-Language requested by the client.&nbsp; The provider
+can use this AcceptLanguages object to load strings with MessageLoader.</li>
</ul>
<p><br>
The OperationContext will also contain a ContentLanguages object that
@@ -669,8 +688,8 @@ language. <br>
returning by calling setContext( ) on the ResponseHandler.&nbsp; This
will be used to set the Content-Language in the CIM response message
sent back to the client.&nbsp; If setContext( ) is not called, then no
-Content-Language will be returned to the client.&nbsp; setContext( )
-should only be called once per response. <br>
+Content-Language will be returned to the client.&nbsp; The setContext( )
+function should only be called once per response. <br>
&nbsp; </p>
<h3> 3.2 Sample Code</h3>
<p><br>
@@ -819,14 +838,14 @@ read/only localized property and a read/write localized property.&nbsp;
What happens if the client sets the read/write property with a
Content-Language that is not one of the supported languages for the
read/only property?&nbsp; This provider allows the client to set any
-language into the read/write property, and get that property back in
-the same language.&nbsp; This becomes an issue when the client does a
+language into the read/write property, and get that property back in the
+same language.&nbsp; This becomes an issue when the client does a
getInstance( ) later, because the Content-Language on the returned
-instance applies to all the properties.&nbsp; A related issue is what
-to return for Content-Language when the client does enumerateInstances,
+instance applies to all the properties.&nbsp; A related issue is what to
+return for Content-Language when the client does enumerateInstances,
but the instances have different languages.&nbsp; Recall that
-Content-Language applies to the entire response (a limitation in the
-CIM specification). <br>
+Content-Language applies to the entire response (a limitation in the CIM
+specification). <br>
&nbsp; </p>
<p>NOTE:&nbsp; Indication Providers have other special considerations
for language support.&nbsp; Please refer to&nbsp; PEP58. <br>
@@ -852,8 +871,8 @@ C/C++ for iSeries Run-Time Functions, Version 5</u> publication for V5R3
(SC41-5607-02).&nbsp; The Pegasus string literals will be compiled with
the UTF-8 compile switch described in this section.&nbsp; OS/400
provider developers should strongly consider using the same compile
-switch for their string literals.&nbsp; This would allow the literals
-to match the UTF-8 encoding expected by the C-runtime.</li>
+switch for their string literals.&nbsp; This would allow the literals to
+match the UTF-8 encoding expected by the C-runtime.</li>
</ul>
<h2> 4. 0 Client Developers</h2>
<p><br>
@@ -971,8 +990,8 @@ server and MOF compiler (cimmof, cimmofl) messages</li>
<p><br>
The make messages target will compile these resource bundles. </p>
<p>Note:&nbsp; As described above, the resource bundle path in
-MessageLoaderParms defaults to the server resource bundle.&nbsp; For
-CLI messages, you will need to specify the bundle for your CLI. <br>
+MessageLoaderParms defaults to the server resource bundle.&nbsp; For CLI
+messages, you will need to specify the bundle for your CLI. <br>
&nbsp; </p>
<h3> 5.2 Server Messages</h3>
<p><br>
@@ -990,14 +1009,14 @@ to described: <br>
AcceptLanguages object and a ContentLanguages object.&nbsp; For
CIMRequestMessage, these objects contain the Accept-Language and
Content-Language headers that were built from the client request.&nbsp;
-For CIMResponseMessage, the ContentLanguages object is used to build
-the Content-Language header associated with the CIM <i>objects </i>in
-the response message.&nbsp; The AcceptLanguages object in the
+For CIMResponseMessage, the ContentLanguages object is used to build the
+Content-Language header associated with the CIM <i>objects </i>in the
+response message.&nbsp; The AcceptLanguages object in the
CIMResponseMessage is ignored. <br>
&nbsp; </p>
<p>The localization of the cimException object in the
-CIMResponseMessage is handled separately from the CIM objects.&nbsp;
-The message string in the cimException object is assumed to have been
+CIMResponseMessage is handled separately from the CIM objects.&nbsp; The
+message string in the cimException object is assumed to have been
localized by the time it is built into the XML.&nbsp; For this reason,
the localization of the exception is the responsibility of the code
throwing the exception.&nbsp; (The goal of the design is to make that
@@ -1019,10 +1038,9 @@ that are managed by a ThreadPool. <br>
AcceptLanguages into its Thread from the AcceptLanguages in the
CIMRequestMessage object that it dequeues.&nbsp; This sets the global
langauge for all the functions in the same thread that are called below
-handleEnqueue.&nbsp; <i>If you are writing a new service that
-processes requests, or discover a request service that was missed,
-please do this.&nbsp;</i> The CIMOperationRequestDispatcher service is
-an example. <br>
+handleEnqueue.&nbsp; <i>If you are writing a new service that processes
+requests, or discover a request service that was missed, please do
+this.&nbsp;</i> The CIMOperationRequestDispatcher service is an example. <br>
&nbsp; </p>
<p><b>How to Throw a Localized Exception from Server code:</b> <br>
&nbsp; </p>
@@ -1075,14 +1093,14 @@ so that the Content-Language would not be set in HTTP response to the
client. <br>
&nbsp; </p>
<p>For Pegasus 2.3, these types of macro calls can stay.&nbsp; The
-TraceableCIMException constructed by the macro will
-"re-localize".&nbsp; That is, the "CIM" part of the message (the part
-based on the error code) will be localized at throw time, and the
-ContentLanguages re-established.&nbsp; A key is to avoid a "language
-mismatch" problem between the CIM part of the message and the extra
-part of the message.&nbsp; The design point here is that all internal
-exceptions thrown by Pegasus code are localized using the global
-AcceptLanguages of the Thread...see above. <br>
+TraceableCIMException constructed by the macro will "re-localize".&nbsp;
+That is, the "CIM" part of the message (the part based on the error
+code) will be localized at throw time, and the ContentLanguages
+re-established.&nbsp; A key is to avoid a "language mismatch" problem
+between the CIM part of the message and the extra part of the
+message.&nbsp; The design point here is that all internal exceptions
+thrown by Pegasus code are localized using the global AcceptLanguages
+of the Thread...see above. <br>
&nbsp; </p>
<p>In the future, it will be safer and more maintainable to use of
the&nbsp; new "localized" flavors of the macro.&nbsp; For example: <br>
@@ -1119,10 +1137,10 @@ the newly created TraceableCIMException. <br>
<p><br>
New methods have been added to Logger to take a message ID of a message
to be loaded from the Pegasus server resource bundle.&nbsp; The caller
-is only required to pass in the message ID, the old "hardcoded"
-message, and the args.&nbsp; The Logger will use MessageLoader to load
-the message in the locale of the Pegasus server <i>process</i>, using
-the hardcoded message as the default string.&nbsp; Please refer to
+is only required to pass in the message ID, the old "hardcoded" message,
+and the args.&nbsp; The Logger will use MessageLoader to load the
+message in the locale of the Pegasus server <i>process</i>, using the
+hardcoded message as the default string.&nbsp; Please refer to
pegasus/src/Pegasus/Logger.h. </p>
<p>Note:&nbsp; Messages sent to the "logs", whether the system logs or
the Pegasus log file, are converted to UTF-8 before being sent. <br>
@@ -1134,8 +1152,8 @@ the locale of the user running the CLI.&nbsp; This should be automatic
-- the user should not be required to tell the CLI what the locale
is.&nbsp;&nbsp; For the CLIs that are CIM clients (cimconfing,
cimprovider) there are two sets of messages to localize&nbsp; --
-messages generated in the CLI process itself, and messages returned
-from the Pegasus server .&nbsp; For CLIs that are directly linked into
+messages generated in the CLI process itself, and messages returned from
+the Pegasus server .&nbsp; For CLIs that are directly linked into
Pegasus (cimmofl), all the messages are generated in the CLI's process,
but the CLI may call Pegasus APIs that are coded to localize based on a
client's requested languages. <br>
@@ -1143,8 +1161,8 @@ client's requested languages. <br>
<p>Code in the client side of the client/server CLIs (eg. cimconfig,
cimmof), or in directly linked CLIs (cimmofl), should use the
_useProcessLocale "master switch" described in the Message Loading
-section.&nbsp; This will cause all messages, including exceptions
-thrown by Pegasus APIs,&nbsp; to be loaded in the locale based on the
+section.&nbsp; This will cause all messages, including exceptions thrown
+by Pegasus APIs,&nbsp; to be loaded in the locale based on the
environment in which the program is running.&nbsp; This locale can be
set by the user before running the program. <br>
&nbsp; </p>
@@ -1164,9 +1182,9 @@ Company, L.P.; IBM Corp.; The Open Group</i> </p>
obtaining a copy&nbsp; of this software and associated documentation
files (the "Software"), to deal in the Software without restriction,
including without limitation the rights to use, copy, modify, merge,
-publish, distribute, sublicense, and/or sell copies of the Software,
-and to permit persons to whom the Software is furnished to do so,
-subject to the following conditions:</i> </p>
+publish, distribute, sublicense, and/or sell copies of the Software, and
+to permit persons to whom the Software is furnished to do so, subject
+to the following conditions:</i> </p>
<p><i>THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE
INCLUDED IN ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE
SOFTWARE IS PROVIDED&nbsp; "AS IS", WITHOUT WARRANTY OF ANY KIND,