When an error occurs at Java™ run
time, an EGL system message is displayed by default. You can specify
a customized message for each of those system messages or for a subset
of messages.
The customized messages are stored in a properties file that you
identify in the vgj.messages.file Java runtime property. This property
is set with the userMessageFile build descriptor
option. For more information about the format of a Java properties file, see Program properties file.
When a message is required, EGL first searches the properties file
that is specified in vgj.messages.file.
EGL compares the message ID of the required message to the IDs of
the messages in the properties file. If EGL finds a message in the
properties file with a matching ID, it uses that message. If there
is no message in the properties file with a matching ID, EGL uses
the default system message. You can also use the sysLib.getMessage system
function to return a message from the properties file that is specified
in vgj.messages.file.
In many cases, a system message includes placeholders for the message
inserts that EGL retrieves at run time. For example, if your code
submits an invalid date mask to a system function, the message has
two placeholders: one (placeholder 0) for the date mask itself and
one (placeholder 1) for the name of the system function. In properties-file
format, the entry for the default message is as follows:
EGL0049E = Overflow when assigning {0} to {1}.
You can change the wording of the message to include all or some
of the placeholders in any order, but you cannot add placeholders.
Valid examples are as follows:
EGL0049E = Tried to assign {0} to {1} and failed.
EGL0049E = {1} = {0} : Overflow on assignment.
If the file that is identified in the vgj.messages.file property
cannot be opened, the program ends.
Other details are available in Java language
documentation:
- For details about how messages are processed and about what content
is valid, see the documentation for the Java class
java.text.MessageFormat.
- For details about handling characters that cannot be directly
represented in the ISO 8859-1 character encoding, which is always
used in properties files, see the documentation for the Java class java.util.Properties.
Creating a customized message file
You can
create a properties file that contains customized messages that are
shown when errors occur at Java run
time. These messages replace the default system messages.
- To create a properties file for the customized messages:
- In the Project Explorer view, right-click the Java
Resources folder of your EGL project.
- Click .
- In the New window, expand General and click File.
- Click Next.
- In the Enter or select the parent folder field,
make sure that the Java Resources
folder of your project is selected.
- In the File name field, type a name for
the properties file; end the name with .properties.
An example of a valid file name is messages.properties.
- Click Finish. The new file is created and
opens in the editor.
- To add customized messages to the messages file:
- Find the message ID of the system message to replace or create
a new message ID if you are adding a new message.
The documentation
contains information about the system messages, their message IDs,
and any placeholders in the message. For more information, see "EGL Java runtime error codes."
- Add a line to the messages file in the following format:
messageID = customMessage
- messageID
- The ID of the system message.
- customMessage
- The custom message to display in place of the system message,
including any placeholders in the message.
For example, the following properties file line
replaces the EGL0049E system message ID, which by default is Overflow
when assigning {0} to {1}.:
EGL0049E = Tried to assign {0} to {1} and failed.
In
this example, the code strings {0} and {1} are
placeholders for message inserts that EGL retrieves at run time. These
placeholders are optional in your customized message.
- When you are finished adding messages, save and close the messages
file.
- Set the genProperties build descriptor
option to GLOBAL or PROGRAM.
- Using one of the following methods, specify the messages file:
- To localize messages into other languages, create additional properties
files for those languages:
- Create new properties files for each language to provide, and
add a locale suffix to the new files to represent their language.
For example, if your original properties file was named messages.properties,
a file with messages in German might be named messages_de.properties.
For more information on locales, see Locales for resource bundles.
- In each new file, repeat the message IDs that you used in the
first properties file.
- In the new files, translate the text of the message; do not change
the message ID.
- Set the application to use the specified language by either generating
with the targetNLS build descriptor option
to the name of the language or by setting the language with the sysLib.setLocale() system
function.
- Generate any EGL file in the project.