getMessage()

The sysLib.getMessage() system function returns a message from one of several possible sources.

The function retrieves a message from one of the following sources:
  • The file that is referenced in the Java™ runtime setting vgj.messages.file.
  • The list of EGL error messages.
  • The list of Informix® error messages.

You can specify inserts for inclusion in the message. The function typically retrieves a custom error message.

The vgj.messages.file setting references a base file name, which you can extend if you have multiple files for different languages and locations. For example, the setting might look like this:
vgj.messages.file = files/messages/errorMessages
In the simplest case, you have a single file in the files/messages folder named errorMessages.properties. If you need national language support, add an underscore and a two-letter language code to the base name, such as errorMessages_fr.properties.
For a file that is customized for a specific locale, you can add another underscore and a two-letter country code. For example, if your application was designed for Canada, you might have two custom error message files:
  • errorMessages_fr_CA.properties
  • errorMessages_en_CA.properties

For information about setting Java™ runtime properties such as vgj.messages.file, see Overview of Java runtime properties. For a more complete description of the way messages are formatted, see your Java™ API docs for the class java.text.MessageFormat.

You can also use sysLib.getMessage() to look up EGL error messages. For example, the key "EGL0001I" returns the message "The error occurred in {0}." In addition, EGL queries the Informix® JDBC driver for an Informix® message under the following circumstances:
  • No message with the specified key is found in the file specified in vgj.messages.file.
  • No EGL message is found with the specified key.
  • The program was generated with the dbms build descriptor option set to INFORMIX.
  • The key contains digits only.

Language codes follow the ISO 639-2 standard, and country codes follow the ISO 3166 standard. For more information, see the related reference links at the end of this topic.

The following syntax shows the format of the entries in the messages file:
key = message

key is a unique string that identifies the message. The message can contain integers within braces to indicate points where you can make substitutions. Start the integers with 0 and increment in order; these integers provide indexes into an array of substitution strings. See the examples later in this topic.

If you use multiple language versions, the key identifiers must be the same across all versions of the file.

Syntax

  sysLib.getMessage(
    key STRING in
    [, insertArray STRING[] in])
  returns (result STRING)
key
Input can be any variable or expression that is assignment compatible with the STRING type. This parameter provides the key into the messages file that is used at run time. If the key is blank, all messages in the file are concatenated.
insertArray
An array of type STRING. Each element contains an insert for inclusion in the message being retrieved.
In the message text, the substitution symbol is an integer that is surrounded by braces, as in this example from a messages file:
  VGJ0216E = {0} is not a valid date mask for {1}.

The first element in insertArray is assigned to the placeholder numbered 0, the second element is assigned to the placeholder numbered 1, and so forth.

result
The result can be assigned to any variable that is assignment compatible with the STRING type. The function returns a null string if key is not found.

Example

The following example is an entry from the message file errorMessages_en_US.properties:

badname = The name you entered, {0}, is not valid.
The following section of code uses this message
  userName STRING = getUserName();  // ask for input
  rc = validateUserName(userName);
  if (rc < 0)
    SysLib.setError( SysLib.getMessage( "badname", [ userName ] ) );
  end

Compatibility

Table 1. Compatibility considerations for getMessage()
Platform Issue
COBOL generation The sysLib.getMessage() function is not supported
JavaScript™ generation The sysLib.getMessage() function is not supported