IMessageText

The IMessageText class loads message text from a message file. When the Open Class Library detects an error condition and prepares to throw an exception, the library creates an object of this class if it is using customized message text. You can use the message text provided by this class to construct an object of a class derived from IException.

You can override the name of the default message file by setting the environment variable ICLUI_MSGFILE to the name of the preferred message file.

AIX Considerations

The IMessageText object searches for the message file using the NLSPATH environment setting.

OS/2 Considerations

The IMessageText object searches for the message file as follows: Typically, message files have the extension .MSG.


IMessageText - Member Functions and Data by Group

Constructors & Destructor

You can construct, destruct, copy, and assign objects of this class.


[view class]
~IMessageText
public:
~IMessageText()
Destructs this message text object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IMessageText
Constructs a message text object.


Overload 1
public:
IMessageText(const IMessageText& text)

You can construct objects of this class using the Open Class Library-provided copy constructor.

text
The error message text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IMessageText( unsigned long messageId, const char* messageFileName = IMessageText::messageFile ( ), const char* textInsert1 = 0, const char* textInsert2 = 0, const char* textInsert3 = 0, const char* textInsert4 = 0, const char* textInsert5 = 0, const char* textInsert6 = 0, const char* textInsert7 = 0, const char* textInsert8 = 0, const char* textInsert9 = 0 )

You can construct objects of this class using this constructor, allowing you to retrieve a message from a file and, optionally, insert additional text strings within the retrieved message.

You can specify that the object insert the text strings through substitution symbols within the message. For example:

The application cannot find the file, %1, at the specified path, %2.
Using this constructor, you can replace the substitution symbols by supplying the file name and path name via textInsert1 and textInsert2 respectively. Notice the substitution symbol number (%1) matches the parameter number (textInsert1).


Attention: You must use the numbers in sequence. For example, you cannot use %1, %2, and %5 in a message, skipping %3 and %4. Instead, you must use %1, %2, and %3. You must specify the substitution symbols sequentially and the text insertion parameters' numbers must match their respective substitution symbol.

messageId
The message ID.
messageFileName
The name of the message file to retrieve the message from. The message file name must include the file extension.

If you specify 0, the message text is in a message segment bound to the .EXE. The IMessageText object loads the message from the application. Otherwise, the library searches for the message text in the specified message file.
Note: If the Open Class Library cannot load the text from the message file, this constructor first tries to load from the Open Class Library internal message table (in C locale) and if this still fails, it uses the following default text: "Unable to load text from message file." In either case, a call to successful() returns 0.

textInsert1 through textInsert9
A text string you insert into the message. Optional.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Assignment

Assigns one message text object to another


[view class]
operator =
public:
IMessageText& operator =(const IMessageText& text)
Assigns antoher message object to this object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Message File Support

Use these members to get or set the message file name.


[view class]
messageFile
public:
static char* messageFile()
Returns a pointer to the message file name used to extract the message text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setMessageFile
public:
static void setMessageFile(const char* msgFileName)
Sets a new message file from which the message text will be extracted. Since only one message file can be active at a time, the Open Class Library message text will also be loaded from the new message file.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Text Operations

Use these members to obtain the text from the object and to set the default text for the object.


[view class]
operator const char *
public:
operator const char *() const
Returns the message text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setDefaultText
public:
IMessageText& setDefaultText(const char* text)
Sets the default message text to the specified text string. The text is set only if the constructor cannot load the text for the specified message ID.


Note: The default text is: "Unable to load text from message file."

text
The new default text string.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
successful
public:
int successful() const
Indicates whether the message extraction was successful.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
text
public:
const char* text() const
Returns the message text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IMessageText - Inherited Member Functions and Data

Inherited Public Functions

Inherited Public Data

Inherited Protected Functions

Inherited Protected Data