3D PLM Enterprise Architecture

Middleware Abstraction

Managing Character Strings

Creating and using character strings and messages

Use Case

Abstract

This article shows how to create and use character strings and how to retrieve messages in message catalog.

What You Will Learn With This Use Case
The CAASysCharStrings Use Case
Step-by-Step
In Short
References

What You Will Learn With This Use Case

This use case is intended to show you how to create and use character strings, and messages stored in message catalogs and in resources catalog.

[Top]

The CAASysCharStrings Case

CAASysCharStrings is a use case of the CAASystem.edu framework that illustrates the System framework capabilities.

[Top]

What Does CAASysCharStrings Do

This use case creates and uses character strings.

[Top]

How to Launch CAASysCharStrings

To launch CAASysCharStrings, you will need to set up the build time environment, then compile CAASysCharStrings along with its prerequisites, set up the run time environment, and then execute the use case [1].

[Top]

Where to Find the CAASysCharStrings Code

The CAASysCharStrings use case is made of a several classes located in the CAASysCharStrings.m module of the CAASystem.edu framework:

Windows	`InstallRootDirectory\CAASystem.edu\CAASysCharStrings.m\`
Unix	`InstallRootDirectory/CAASystem.edu/CAASysCharStrings.m/`

wherwe InstallRootDirectory is the directory where the CAA CD-ROM is installed.

[Top]

Step-by-Step

The character string capabilities are shown using five steps:

#	Step
1	Retrieve a Simple Message in a Message Catalog
2	Retrieve a Parameterized Message in a Message Catalog
3	Retrieve a Simple Value in a Resource Catalog
4	Message Catalog Files Format
5	Create a CATUnicodeString from a wchar_t
6	Convert a CATUnicodeString to UTF8 and to STEP
7	Convert CATUnicodeString to numerals and the reverse

[Top]

Retrieving a Simple Message in a Message Catalog

...
  CATString ExampleMsgCatalogName("CAASysCharStrings");
  CATString ExampleMsgCatalogKey("CAASystemCharacterStrings.MessageWithoutParameter");
  CATUnicodeString ExampleBuiltMessage;
  ExampleBuiltMessage = CATMsgCatalog::BuildMessage(ExampleMsgCatalogName,
                                                    ExampleMsgCatalogKey);
...

A message catalog contains strings to display which must be translated into languages. A message catalog should only contain strings which must be translated into other languages, otherwise, resource catalogs should be used.

The two CATString instances created are the message catalog name and the key of the message to search for in the catalog respectively. The static BuildMessage method retrieves the message as a CATUnicodeString instance that can be used, for example, for display in a dialog box.

[Top]

Retrieving a Parameterized Message in a Message Catalog

...
  CATString MsgCatalogName("CAASysCharStrings");
  CATString MsgCatalogKey("CAASystemCharacterStrings.MessageWithTwoParameters");

  CATUnicodeString DefaultMessage = 
     "A problem occurred while loading the CAASysCharStrings.CATNls file";

  int ParametersCount = 2;
  CATUnicodeString Parameters[2];
  Parameters[0] = "First Param";
  Parameters[1] = "Second Param";

  CATUnicodeString BuiltMessage;
  BuiltMessage = CATMsgCatalog::BuildMessage(MsgCatalogName,
                                             MsgCatalogKey,
                                             Parameters,
                                             ParametersCount,
                                             DefaultMessage);
...

The two CATString instances created are the message catalog name and the key of the message to search for in the catalog respectively. A default message is created to be issued if the message catalog loading fails. Two parameters are created in the Parameters array. To be merged with the message extracted from the catalog, they must be CATUnicodeString instances. The static BuildMessage method retrieves the message as a CATUnicodeString instance and puts the parameters at the place reserved for them in the message, the first parameter in the array being placed at the first parameter location in the message, and so on. Then the message can be used, for example, for display in a dialog box.

[Top]

Retrieving a Simple Value in a Resource Catalog

...
  CATString ExampleRscCatalogName("CAAAfrGeneralWksAddinHeader");
  CATString ExampleRscCatalogKey("CAAAfrGeneralWksAddinHeader.CAAAfrSearchHdr.Icon.Normal");
  CATString ExampleBuiltResourceValue;("CAAAfrGeneralWksAddinHeader.CAAAfrSearchHdr.Icon.Normal");

  CATRscCatalog::BuildResource(ExampleRscCatalogName,ExampleRscCatalogKey,ExampleBuiltResourceValue);
...

Resource Catalogs must be used for all non hard-coded strings which must not be translated into other languages.

[Top]

Message Catalog Files Format

The message catalog files (.CATNls) contain a list of messages. They are clear-text files, encoded in the following code pages:

English, German, French, Italian, Portuguese, Spanish, Danish, Swedish, Dutch, Finnish, Icelandic, Norwegian: ISO 8859-1
Polish, Czech : ISO 8859-2
Russian : ISO 8859-5
Greek : ISO 8859-7
Hebrew: ISO 8859-8
Turkish: ISO 8859-9
Japanese :IBM 943
Korean : EUC KR
Simplified_Chinese : EUC CN
Traditional_Chinese : EUC TW

They may be edited, for example:

on Windows using Wordpad
on Unix using vi

On Windows, they are located in the directory intel_a\resources\msgcatalog.

A message catalog file contains several messages. When a message may take several lines, it is possible to enter it in several parts (compound message). Thus, the
message will be more readable. Each message has the following syntax:

Message ::= SpacesOrComment* Key SpacesOrComment* <EQUALS SIGN>
SpacesOrComment* MessagePart
( <COMMA> SpacesOrComment* MessagePart )* SpacesOrComment* <SEMICOLON>

Key ::= [a-z A-Z 0-9 . _]+

MessagePart ::= <QUOTATION MARK>
                       ( EffectiveCharacter | ControlCharacter |
                       FormalParameter | SlashExpression )*
                       <QUOTATION MARK>

EffectiveCharacter ::= <character encoded in the supported code page (see above),
except control characters,
the SOLIDUS character (slash) and the REVERSE SOLIDUS character>

FormalParameter ::= ( <LATIN CAPITAL LETTER P> | <LATIN SMALL LETTER P> ) [0-9]*

SlashExpression ::= ( <SOLIDUS (slash)> <any character except LATIN CAPITAL LETTER P and
                           LATIN SMALL LETTER P> ) |
                           ( <SOLIDUS> <SOLIDUS>
                           ( <LATIN CAPITAL LETTER P> | <LATIN SMALL LETTER P> ) )

SpacesOrComment ::= SpaceCharacter* |
( <SOLIDUS (slash)> <SOLIDUS (slash)> <any character except '\n' and '\0'>* <'\n'> )

SpaceCharacter ::= <SPACE> | <CARRIAGE RETURN> | <LINE FEED> | <CHARACTER TABULATION > |
<LINE TABULATION>

Note: Regarding the ControlCharacter entity, if it is valued to <REVERSE SOLIDUS><QUOTATION MARK> , then, in the effective displayed message, it will have been converted to <QUOTATION MARK>. <REVERSE SOLIDUS><LATIN SMALL LETTER N>, <REVERSE SOLIDUS><LATIN SMALL LETTER T> . . . are converted the same way.

Note: Regarding the SlashExpression entity, if it is valued to <SOLIDUS><SOLIDUS><LATIN CAPITAL LETTER P> , then, in the effective displayed message, it will have been converted to <SOLIDUS><LATIN CAPITAL LETTER P> . <SOLIDUS><SOLIDUS><LATIN SMALL LETTER P> is converted the same way.

Caution: regarding a EffectiveCharacter entity, if it does not correspond to an effective code in the corresponding code page (ISO 8859-1 for an english message catalog file, IBM 932 for a japanese message catalog file . . .), the parsing of the message catalog file will fail.

Caution: Each key must be present only once in a given file .

Examples:

Message1 = "This is a simple english message.";
Message2 = "This message includes the parameter /P1 that is valued by your application at run-time.";
Message3 = "This is a", "compound ", "message.";
Message4 = "You can use control characters such as \t or \n in your messages.";

[Top]

Creating a CATUnicodeString from a wchar_t

...
  wchar_t* CLanguageUnicodeString = L"Unicode string";
  int CharacterCount = wcslen(CLanguageUnicodeString);

  CATUC2Bytes *UnicodeCharacters = new CATUC2Bytes[CharacterCount];
  for (int i=0; i<=CharacterCount; i++) 
     UnicodeCharacters[i] = CLanguageUnicodeString[i];

  CATUnicodeString UnicodeString;
  UnicodeString.BuildFromUCChar(UnicodeCharacters, CharacterCount);
  delete UnicodeCharacters;
...

A wchar_t string is created and its length is retrieved thanks to the wcslen function. Then a CATUC2Bytes table is instantiated with the string length as size, and filled in with the wchar_t string. The CATUC2Bytes class represents the Unicode character encode using two bytes, and its assignment operator converts wchar_t to CATUC2Bytes instances. Then a CATUnicodeString instance is created using the CATUC2Bytes table, thanks to the BuildFromUCChar method..

[Top]

Converting a CATUnicodeString to UTF8 and to STEP

...
  CATUnicodeString StringToConvert = "String";
  char *UTF8String = new char[4+6*(StringToConvert.GetLengthInChar())];
  size_t UTF8StringByteCount;
  StringToConvert.ConvertToUTF8(UTF8String, &UTF8StringByteCount);
  ... // Display UTF8String

  char *STEPString = new char[50];
  StringToConvert.ConvertToSTEP(STEPString);
  cout << "STEP String = " << STEPString << endl;
  delete STEPString;
...

A CATUnicodeString instance is converted as an array of characters expressed using the UTF8 Unicode format thanks to the ConvertToUTF8 method. The array size takes the maximum possible size of the character string, whose actual length is returned in UTF8StringByteCount. Then the ConvertToSTEP method converts the same string to the character string format used by the STEP standard.

[Top]

Converting CATUnicodeString to Numerals and the Reverse

...
  StringToConvert = "1250";
  int OutputInteger;
  int IsConversionOK = StringToConvert.ConvertToNum(&OutputInteger);
  StringToConvert = "1250.12";
  double OutputReal;
  IsConversionOK = StringToConvert.ConvertToNum(&OutputReal);

  int InputInteger = 253;
  CATUnicodeString StringToFill;
  int FillingWasOK = StringToFill.ConvertNumToString(InputInteger);
  double InputReal = 253.57;
  FillingWasOK = StringToFill.ConvertNumToString(InputReal);
...

The ConvertToNum method converts a CATUnicodeString instance into an integer or a double. conversely, the ConvertNumToString method converts an integer or a double into a CATUnicodeString instance. The conversion succeeds if the returned integer is different from 0.

[Top]

In Short

This use case shows how to create and use character strings and how to retrieve messages from message catalogs.

[Top]

References

[1]	Building and Launching a CAA V5 Use Case
[Top]

History

Version: 1 [Mar 2000]	Document created
[Top]