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
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 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, the
other (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 or change the
numbering of the placeholders. Valid examples are as follows:
EGL0049E = Tried to assign {0} to {1} and failed.
EGL0049E = {1} = {0} : Overflow on assignment.
The program terminates if the file that is identified in the vgj.messages.file property
cannot be opened.
Note that for system messages generated for COBOL, the first placeholder
is {1} rather than {0}.
Other details are available in Java language
documentation:
- For details on how messages are processed and on what content
is valid, see the documentation for the Java class
java.text.MessageFormat.
- For details on 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,
ensure that your project's Java Resources
folder is selected.
- In the File name field, type a name for
the properties file, ending in .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 you want 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. See ../../com.ibm.egl.messages.doc/topics/rjavrun0001.html.
- 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 system message ID EGL0049E, 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:
- If you want to localize messages into other languages, create
additional properties files for those languages:
- Create new properties files for each language you want to provide,
adding 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, without changing
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.