Understanding the Message controller option

When you want to display messages in your Web pages, you need to configure a message resource in the iSeries Web Tools Run-time Configuration wizard. You also need to define an output parameter as a message controller in the Web Interaction wizard.

Message handling option in the iSeries Web Tools Run-time Configuration wizard

The message resource can be configured on the second page of the iSeries Web Tools Run-time Configuration wizard.

Use this option to:

  1. Specify the message file used for message handling in the Message resource field. This file is a properties file unless you check Use iSeries message file. The properties file must be created in the JavaSources folder, or in a folder within the Java Resources folder. Selecting Browse allows you to browse the JavaSources folder for the properties file.

    If you check Use iSeries message file, it indicates that the message resource is an iSeries message file. Selecting Browse allows you to browse a remote host for the message file. For an iSeries message file, *LIBL and *CURLIB are supported.

    If only the message file name is specified, it is qualified as *LIBL.

  2. Select Use iSeries message file if the message file you specified in the Message resource field is an iSeries message file.

Message controller option in the Web Interaction wizard

The Message Control Specification window opens when you select true for the Message Controller property for any output parameter on either the Design the Result Form page or the Map and Link the Output Parameters to the Output Fields pages in the Web Interaction wizard. This output parameter is designated as the message controller parameter.

Use this window to map values returned by the message controller parameter to message IDs and to specify the Web component that displays the message.

  1. Use the Parameter Value field to specify a value that is mapped to a message ID. You can edit your entries in this field. There are also two special values that you can select:
    • *OTHER - all other values not specified here.
    • *BLANK - white spaces. This value is only enabled if the message controller parameter type is non-numeric.

    To return multiple values, the message controller parameter must be defined as an array.

    If the message controller parameter is of type character, it can be used to return substitution text for substitution variables in the message. The substitution text is separated from the message ID by a space. Spaces in the substitution text are discarded unless they are enclosed in quotes. For example, if the value returned by the program is
    MSG0001 John " D o e "
    the message ID is MSG0001, the first substitution text is John, and the second substitution text is D o e. To specify the quote character in the substitution text, encode it twice. For example, if the value returned by the program is
    MSG0002 ab""c...
    the substitution text is ab"c....

    If the message resource specified in the iSeries Web Tools Run-time Configuration wizard is an iSeries message file, a maximum of 1024 bytes of substitution text can be supplied. Each substitution text must be correctly formatted. For example, a 4-byte substitution variable must be formatted as "   a". That is, all 4 bytes must be supplied.

    If the message resource specified in the iSeries Web Tools Run-time Configuration wizard is a properties file, you encode substitution variables in the message using the format {n}, where n denotes the substitution number from 0 to 3. That is, up to 4 substitution variable are allowed. Following is an example of the format of a message:
    MSG0001=My first name is {0}. My last name is {1}.
  2. Use the Message ID field to specify the message ID for the message that is to be displayed. You can edit your entries in this field. There are also three special values that you can select:
    • *NONE - there is no message mapped to the parameter value.
    • *PARM - the parameter value is used as the message ID.
    • *SELECT - you are prompted to select an iSeries message.

      This option appears if an iSeries message file is selected in the Run-time Configuration wizard.

  3. Use the Web Component field to specify the Web components that are used to display messages. The Web components that you can use for this purpose are Combo Box, Label, Selection Box, or Text Area. These Web components cannot be mapped to any input or output parameters. You cannot edit this field.
    • *DEFAULT - the message is not displayed in a Web component. The message is converted to a Struts message. If the Struts version of the Web project is less than 1.1, the message is converted to Struts ActionError objects. Otherwise, Struts ActionMessage objects are created. To display the messages, you need to add the appropriate Struts tags to your JSP files. If the JSP files are generated by the Web Interaction wizard, these tags are also generated for you. The tags generated depend on the Struts version of the Web project. If the Struts version is less than 1.1, this is generated:
      <html:errors/> 
      Otherwise, this is generated:
      <html:messages id="msg" message="true">
      <bean:write name="msg"/><br>
      </html:messages>
  4. Select New to add a parameter value, message ID, and Web component to be associated to the message controller parameter.
  5. Use Remove to remove a definition specified for the message controller parameter.
  6. Use the Move up and Move down buttons to rearrange the order of the definitions specified for the message controller parameter.