setError()

The sysLib.setError() system function associates a message with one of several possible containers.

The following containers are available to sysLib.setError():

a field in a JSF handler
a field in a VGUIRecord
the JSF handler itself

The location where the message is placed may vary:

If a JSF handler invokes the function, the message is placed at the location of a message or messages tag in the JSP.
If a VGWebTransaction program invokes the function, the message is placed at the location of the associated field in the JSP.

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
JavaScript™ generation	The function sysLib.setError() is not supported
JSF Handler	Inserts for messages in a msgTable type DataTable are supported; the first insert is {0}.
Web transactions	Inserts for messages in a msgTable type DataTable are supported; the first insert is {1}.