setError()

The sysLib.setError() system function associates a message with one of several possible containers.
The following containers are available to sysLib.setError():
The location where the message is placed may vary:

The message is displayed when the related Web page is displayed.

If a validation function invokes sysLib.setError(), the Web page is redisplayed automatically when the function ends.

The first of the three signatures shown for the function in "Syntax" is available in JSF handlers or in VGWebTransaction programs, while the second and third are available only for JSF handlers:

You can associate multiple messages with a field or with the JSF handler. The messages are lost if the JSF handler runs a forward statement, or if the VGWebTransaction program runs a transfer or show statement.

You can use sysLib.setError() in the function specified in the onPostRenderFunction property of the JSF Handler, but not in the functions specified in the onPostRenderFunction or onConstructionFunction properties.

Syntax

  sysLib.setError(
    fieldInError anyPageVariable in,
    msgKey STRING in
    [, msgInsert STRING in])
  sysLib.setError(
    this enumerationThis in,
    msgKey STRING in
    {, msgInsert STRING in})
  sysLib.setError(msgText STRING in)
fieldInError
If sysLib.setError() is issued from a JSF handler, fieldInError is a variable in the JSF handler that is bound to a component on the Web page.

If sysLib.setError is issued from a VGWebTransaction program, fieldInError is a field in the VGUI record that is specified in the show or converse statement, or in the inputUIRecord for the program.

this
Refers to the JSF handler that issues the sysLib.setError() call. In this case, the message is not specific to a field, but is associated with the JSF handler itself. For details on this, see The "this" keyword.
msgKey
Input can be any variable or expression that is assignment compatible with the STRING type (see Assignment compatibility in EGL). The msgKey provides the key into the message resource bundle or properties file used at run time. If the key is blank, the message is a concatenation of all messages.
msgInsert
Input can be any variable or expression that is assignment compatible with the STRING type (see Assignment compatibility in EGL). msgInsert is inserted into the output message. The substitution symbol in the message text is an integer surrounded by braces, as in this example:
  Invalid file name {0}
Only a single msgInsert string is permitted with sysLib.setError(), unlike sysLib.getMessage(), which takes an array of inserts.
msgText
Input can be any variable or expression that is assignment compatible with the STRING type (see Assignment compatibility in EGL). This is the text of a message that is associated with the Web page.

Example

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

badname = The name you entered, {0}, is not valid.
The following example shows that message in use:
  userName STRING = getUserName();  // ask for input
  rc = validateUserName(userName);
  if (rc < 0)
    SysLib.setError( SysLib.getMessage( "badname", [ userName ] ) );
  end

Compatibility considerations

Table 1. Compatibility considerations
Platform Issue
Java generation The function sysLib.setError() is not supported in a service.
JavaScript generation The function sysLib.setError() is not supported.

Feedback