Customizing EGL system runtime messages for Java™

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:
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, ensure that your project's Java™ Resources folder is selected.
6. 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.
7. Click Finish. The new file is created and opens in the editor.
To add customized messages to the messages file:
1. 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 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 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.
3. 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:
- 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, 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, follow these steps:
  1. In the Project Explorer view, double-click the project's J2EE deployment descriptor. 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.
- Set the vgj.messages.file property in the file rununit.properties 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 file rununit.properties, follow these steps:
  1. Open the file rununit.properties 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.
If you want to localize messages into other languages, create additional properties files for those languages:
1. 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.
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, without changing 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.
Generate any EGL file in the project.