All Frameworks Class Hierarchy This Framework Indexes Previous Next

System class CATMsgCatalog

Usage: you must use this class as is. You should never derive it.

public class CATMsgCatalog

Message catalog class.
Role: Processing a message catalog file. A message catalog file contains parameterized messages (see CATMsg ). A message is a parameterized alphanumerical string which can be used for any alphanumerical item of information, a warning, a help or error message, and whenever you need to display any text in a dialog window, such a the caption on a push button.
NLS (National Langage Support) is supported but, in the same way, a message catalog file should only contain strings which must be translated into other languages: otherwise, resource catalog files should be used (see CATRscCatalog ).
A message catalog is built from a file that contains messages identified by a key. A message can be parameterized ie contains parameters you value at run-time. A parameter begins with /p or /P in the message text.
The following are examples of messages:

 Message1 = "This is a simple 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.";

A message catalog file posess the .CATNls suffix and is retrieved from the folders specified by the CATMsgCatalogPath variable. The localized version of the message catalog is searched first. If it does not exist, the english version is taken.
Regarding the localized version, the language taken is the UI language. The UI language is determined the following way:

the Tools\Customize\Options\"User Interface Language" combo is read.
in the case where this combo is set to the "Environment language" value (default), the thread language locale is taken (see, on Windows, the "Settings for the current user" frame of the "General" tab of the "Regional Options" panel of the Control Panel and, on Unix, the window locale)
in the case where this combo is set to an explicit language, the given language is taken

Example: Suppose

we are on Windows
the environment is Japanese
the Tools\Customize\Options\"User Interface Language" combo is set to "Environment language (default)"

then, if the CATMsgCatalogPath variable is valued the following way:

   CATMsgCatalogPath=C:\PersonalFolder;C:\Program Files\Dassault Systemes\B14

CATIA will search the message catalog file into the following paths:

   1 - C:\PersonalFolder\Japanese
   2 - C:\PersonalFolder
   3 - C:\Program Files\Dassault Systemes\B14\Japanese
   4 - C:\Program Files\Dassault Systemes\B14

The character set for the message key characters is the following:

within the A - Z range
within the a - z range
within the 0 - 9 range
PERIOD (.), SPACING UNDERSCORE (_), LEFT SQUARE BRACKET ([) and RIGHT SQUARE BRACKET (]) characters

Constructor and Destructor Index

o CATMsgCatalog(): Constructs a message catalog.
o CATMsgCatalog(CATMsgCatalog&): Copy constructor.
o ~CATMsgCatalog()

Method Index

o BuildEnglishMessage(CATString&,CATString&,CATUnicodeString*,int,CATUnicodeString&): Computes an english alphanumeric message string.
o BuildMessage(CATString&,CATString&,CATUnicodeString*,int,CATUnicodeString&,CATString*): Computes an alphanumeric message string from an identified parameterized message of the catalog, given specified parameters values.
o GetCatalogKeys(CATListValCATString*): Get the message catalog keys.
o GetCatalogMsg(CATString&,CATString*): Returns a message from the message catalog.
o GetError(): Returns the first syntax error found.
o LoadMsgCatalog(CATString&,char*,CATString*): Loads a message catalog.
o SubstituteCatalogMsg(CATString&,CATMsg&): Substitutes a message into an internalized message catalog.
o operator =(CATMsgCatalog&): Assignment operator.

Constructor and Destructor

o CATMsgCatalog

public CATMsgCatalog(

)

Constructs a message catalog.

o CATMsgCatalog

public CATMsgCatalog( const CATMsgCatalog& iMsgCatalog)

Copy constructor.
Caution: This method should rarely be used, in most cases the use of CATMsgCatalog.BuildMessage is enough.

Parameters:

iMsgCatalog: The message catalog to copy

o ~CATMsgCatalog

public ~CATMsgCatalog(

)

Methods

o BuildEnglishMessage

public static const CATUnicodeString BuildEnglishMessage(	const CATString&	`iCatalogName`,
	const CATString&	`iMessageKey`,
	CATUnicodeString*	`iMsgParameters`	`= NULL`,
	int	`iParamNb`	`= 0`,
	const CATUnicodeString&	`iDefaultMsg`	`=(char *)NULL` )

Computes an english alphanumeric message string.
Role: Does the same thing as CATMsgCatalog.BuildMessage , except that it takes the english version and not the UI language version. Caution: This method should rarely be used, in most cases the use of CATMsgCatalog.BuildMessage is enough.

Parameters:

iCatalogName: Name of the catalog containing the message
iMessageKey: Key of the message to be retrieved
iMsgParameters: Array giving to the method possible parameter values which the method will integrate into the parameterized message.
iParamNb: Parameter value count
iDefaultMsg: Message to be used if a problem occured while accessing the message catalog file or the key.

Returns:

The built message. If the execution gives the iDefaultMsg return value, debug the message catalog file using CATMsgCatalog.GetError , which may return:

Line %d Unexpected EOF !
Line %d = expected, and '%d' found
Line %d \" expected, and '%d' found
Line %d Expected , or ; not found
File %s.CATNls has not read access
File %s.CATNls not found
Error while reading file : %s.CATNls

o BuildMessage

public static const CATUnicodeString BuildMessage(	const CATString&	`iCatalogName`,
	const CATString&	`iMessageKey`,
	CATUnicodeString*	`iMsgParameters`	`= NULL`,
	int	`iParamNb`	`= 0`,
	const CATUnicodeString&	`iDefaultMsg`	`=(char *)NULL`,
	CATString*	`iLanguage`	`= NULL`)

Computes an alphanumeric message string from an identified parameterized message of the catalog, given specified parameters values.
Role: Computes a alphanumeric string from a message from a message catalog using the catalog name, the message key, the message parameters and (if needed) a default NLS message.

Regarding messages, for most use, the GetResourceValueFromKey method of the CATDialog class will be sufficient. We remind you also that Dialog Engine Acquisition Agents support messages without having to use any message service, just using the file and key name convention rules.

Anyway, sometimes (for combo values for example), you may need to access to the messages from soft. You will then use this service.

The use of this service is as follows: call it at any moment you want during execution. You do not have to store the computed message for a future re-use. Effectively, this service is encapsulated. It takes into account the following things:

If the catalog is not loaded, it does it (this enables the calling code not to bother about the loading: it lets the managing of it to this service, the message catalog will be present into the memory only once, whatever the count of softwares using it.
Otherwise, from the input message catalog identifier (iCatalogName parameter, see below), the method find in its own data the message catalog pointer, among the other message catalog already loaded, through a method that has its performances optimized: a hashtable. This technology ensures there isn't any performance problem.

The only need for an application to factorize a given message the first time it computes it (storing it for future uses), would be to make an optimized management of exceptions that would occur during the message catalog loading: the purpose beeing to mention the message catalog syntax errors only once. Such applications needs seldom occur.

Parameters:

iCatalogName

Name of the catalog containing the message, without the .CATNls suffix

iMessageKey

Key of the message to be retrieved

iMsgParameters

Array giving to the method possible parameter values which the method will integrate into the parameterized message. The parameter value count should correspond to the message parameter highest index (this is not exactly the parameter count: the software authorizes parameter indices that are not consecutive, which would distinguish the message parameters highest index from the parameter count). If the input parameter value count is not sufficient, a default behaviour is foreseen: "?" characters are introduced into the computed output resource string. NULL default value coresponds to no parameter values.

iParamNb

Parameter value count

iDefaultMsg

Message to be used if a problem occured while accessing the message catalog file or the key. You may, for example, put in this message an information about an access problem. We suggest you to deliver a valid value to this parameter, so that, if an error occurs, a valid return value be delivered by the service.

iLanguage

Language in which the message must be taken:

English
French
German
Italian
Japanese
Korean
Simplified_Chinese

NULL default value coresponds to the UI language (see above).

Returns:

The built message. If the execution gives the iDefaultMsg return value, debug the message catalog file using CATMsgCatalog.GetError , which may return:

Line %d Unexpected EOF !
Line %d = expected, and '%d' found
Line %d \" expected, and '%d' found
Line %d Expected , or ; not found
File %s.CATNls has not read access
File %s.CATNls not found
Error while reading file : %s.CATNls

o GetCatalogKeys

public int GetCatalogKeys( CATListValCATString* oKey =NULL)

Get the message catalog keys.

Parameters:

oKey: The key list.
Lifecycle rules deviation: the caller must allocate the object and manage so that, in input, the oKey size be equal to zero.

Returns:

The message catalog key count.
Legal values: 0 if an error occured, or Other otherwise.
If the execution gives a 0 value, debug the message catalog file using CATMsgCatalog.GetError , which may return:

Line %d Unexpected EOF !
Line %d = expected, and '%d' found
Line %d \" expected, and '%d' found
Line %d Expected , or ; not found
File %s.CATNls has not read access
File %s.CATNls not found
Error while reading file : %s.CATNls

o GetCatalogMsg

public const CATMsg GetCatalogMsg(	const CATString&	`iMessageKey`,
	CATString*	`iLanguage`	`= NULL`)

Returns a message from the message catalog.
Role: Returns a message from a message catalog using the message key.
Caution: This method should rarely be used, in most cases the use of CATMsgCatalog.BuildMessage is enough.

Parameters:

iMessageKey

Key of the message to be returned

iLanguage

Language in which the message must be taken:

English
French
German
Italian
Japanese
Korean
Simplified_Chinese

NULL default value coresponds to the UI language (see above).

Returns:

The returned parameterized message. If an error occured the return value is an empty string. If the execution gives an empty string, debug the message catalog file using CATMsgCatalog.GetError , which may return:

Line %d Unexpected EOF !
Line %d = expected, and '%d' found
Line %d \" expected, and '%d' found
Line %d Expected , or ; not found
File %s.CATNls has not read access
File %s.CATNls not found
Error while reading file : %s.CATNls

o GetError

public const CATString GetError(

)

Returns the first syntax error found.
Role: Returns the first syntax error found after a call to CATMsgCatalog.BuildMessage or CATMsgCatalog.LoadMsgCatalog .
CAUTION: Although this method is not static, the CATString returned does not depend from the CATMsgCatalog instance used.
See CATMsgCatalog.BuildMessage and CATMsgCatalog.LoadMsgCatalog .

Returns:

Error message. It may be:

File %s.CATNls has not read access
File %s.CATNls not found
Error while reading file : %s.CATNls
Line %d Unexpected EOF !
Line %d = expected, and '%d' found
Line %d \" expected, and '%d' found
Line %d Expected , or ; not found
GetCatalogMsg() called with a bad key format : '%d' can't be used in a key
Key %s not defined.

o LoadMsgCatalog

public int LoadMsgCatalog(	const CATString&	`iCatalogMessageName`,
	const char*	`iPath`	`= NULL`,
	CATString*	`iLanguage`	`= NULL`)

Loads a message catalog.
Role: Loads a message catalog by means of its name and (if desired) of a path.
Caution: This method should rarely be used, in most cases the use of CATMsgCatalog.BuildMessage is enough.

Parameters:

iCatalogMessageName

Name of the message catalog file, without the .CATNls suffix

iPath

Absolute path where the catalog message must be searched for.
The localized version of the message catalog is searched first. If it does not exist, the english version is taken.
Example: In a japanese Windows environment, if the iPath variable is valued the following way:

      iPath="C:\PersonalFolder;C:\Program Files\Dassault Systemes\B14"

then, CATIA search the message catalog file into the following paths:

      1 - C:\PersonalFolder\Japanese
      2 - C:\PersonalFolder
      3 - C:\Program Files\Dassault Systemes\B14\Japanese
      4 - C:\Program Files\Dassault Systemes\B14

Caution: This parameter should always be given a null value. Actually, the english version of a message catalog file should always be located at:

    %CATInstallPath%\resources\msgcatalog

Otherwise, the message catalog will not be taken into account by the following tools:

translation tools
test message catalog generation tools
the installation dialog regarding the language of the user interface files which must be installed

Consequently, a non-null value for iPath has no meaning.

iLanguage

Language in which the message must be taken:

English
French
German
Italian
Japanese
Korean
Simplified_Chinese

NULL default value coresponds to the UI language (see above).

Returns:

Legal values: 0: False if an error occured, or 1 if the execution succeeded.
If the execution gives 0, debug the message catalog file using CATMsgCatalog.GetError , which may return:

Line %d Unexpected EOF !
Line %d = expected, and '%d' found
Line %d \" expected, and '%d' found
Line %d Expected , or ; not found
File %s.CATNls has not read access
File %s.CATNls not found
Error while reading file : %s.CATNls

o SubstituteCatalogMsg

public int SubstituteCatalogMsg(	const CATString&	`iMessageKey`,
	const CATMsg&	`iReplacingMessage`)

Substitutes a message into an internalized message catalog.
Role: Substitutes a message into an internalized message catalog using the message key. This enable to use messages known only during execution into a CATStateCommand.

Example:
The MyApplicativeCommand.CATNls file contains:

     MyApplicativeCommand.MessageSink="fake message";

The MyApplicativeCommand::BuildGraph method will contain:

     CATDialogState* MyState = NULL;
     CATMsgCatalog ApplicativeCommandCatalogMessage;
     CATString MessageKey = "MessageSink";
     CATUnicodeString StringOfTheMessageKnownDuringExecution = "message obtained during execution";
     ApplicativeCommandCatalogMessage.LoadMsgCatalog("MyApplicativeCommand");
     CATMsg MessageKnownDuringExecution(StringOfTheMessageKnownDuringExecution);
     ApplicativeCommandCatalogMessage.SubstituteCatalogMsg("MyApplicativeCommand.MessageSink", MessageKnownDuringExecution);
     MyState = AddDialogState(MessageKey);

Parameters:

iMessageKey: Key of the message to substitute
iReplacingMessage: The new message which must replace the current one

Returns:

Legal values: 0: False if the substitution didn't succeed, or Other: True otherwise.
If the execution gives a 0 value, debug the message catalog file using CATMsgCatalog.GetError , which may return:

Line %d Unexpected EOF !
Line %d = expected, and '%d' found
Line %d \" expected, and '%d' found
Line %d Expected , or ; not found
File %s.CATNls has not read access
File %s.CATNls not found
Error while reading file : %s.CATNls

o operator =

public CATMsgCatalog & operator =( const CATMsgCatalog& iMsgCatalog)

Assignment operator.
Caution: This method should rarely be used, in most cases the use of CATMsgCatalog.BuildMessage is enough.

Parameters:

iMsgCatalog: Message catalog of the right part of the equality

Returns:

Message catalog of the left part of the equality

This object is included in the file: CATMsgCatalog.h
If needed, your Imakefile.mk should include the module: JS0GROUP

System writeClassCharacteristic(); class CATMsgCatalog

Constructor and Destructor Index

Method Index

Constructor and Destructor

Methods

System class CATMsgCatalog