Customizing runtime messages

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:

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.

  1. To create a properties file for the customized messages:
    1. In the Project Explorer view, right-click the Java Resources folder of your EGL project.
    2. Click New > Other.
    3. In the New window, expand General and click File.
    4. Click Next.
    5. In the Enter or select the parent folder field, make sure that the Java Resources folder of your project is selected.
    6. 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.
    7. Click Finish. The new file is created and opens in the editor.
  2. To add customized messages to the messages file:
    1. 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."

    2. 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.

    3. When you are finished adding messages, save and close the messages file.
  3. Set the genProperties build descriptor option to GLOBAL or PROGRAM.
  4. Using one of the following methods, specify the messages file:
    • Set the userMessageFile build descriptor option to specify name of the messages file without the .properties extension. For example, if the messages file is named messages.properties, set the userMessageFile build descriptor option to messages.

      The userMessageFile build descriptor option sets the vgj.messages.file Java runtime property, which is the runtime property that specifies the message file. This method applies to any type of EGL project.

    • Set the vgj.messages.file Java runtime property in the J2EE deployment descriptor (not the EGL deployment descriptor) to specify the name of the messages file. This method applies only to projects used within the J2EE framework. To set the vgj.messages.file runtime property in the J2EE deployment descriptor:
      1. In the Project Explorer view, double-click the J2EE deployment descriptor of the project. The deployment descriptor opens in the deployment descriptor editor.
      2. Click the Variables tab.
      3. Under Environment Variables, click Add. The Add Environment Entry window opens.
      4. In the Name field, type vgj.messages.file.
      5. In the Type field, select String.
      6. In the Value field, type the name of the messages file without the .properties extension. For example, if the messages file is named messages.properties, type messages.
      7. Click Finish.
    • To specify the name of the messages file, set the vgj.messages.file property in the rununit.properties file. This method applies only to projects that are used within the J2EE framework. To set the vgj.messages.file runtime property in the file rununit.properties file:
      1. Open the rununit.properties file in the Java Resources folder. This file is created the first time that you generate a file with the genProperties property set to GLOBAL. If you generate with genProperties set to PROGRAM, the properties file is named pgmNameOrAlias.properties and is located in the Java package of the generated program.
      2. In the properties file, add the following code:
        vgj.messages.file = messageFileName
      3. Replace messageFileName with the name of the name of the messages file without the .properties extension. For example, if the messages file is named messages.properties, type vgj.messages.file = messages.
      4. Save and close the properties file.
  5. To localize messages into other languages, create additional properties files for those languages:
    1. 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.
    2. In each new file, repeat the message IDs that you used in the first properties file.
    3. In the new files, translate the text of the message; do not change the message ID.
    4. 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.
  6. Generate any EGL file in the project.

Feedback