Release 10.1A: OpenEdge Application Server:
Developing WebSpeed Applications

> ## Message handling

> A number of WebSpeed API functions facilitate message queuing and output. They interact with a message queue that allows you to organize messages into named groups. Table 3–2 lists these functions.

> Table 3–2: Message API functions
> Function | Return type | Description
> --- | --- | ---
>     available-messages
>     LOGICAL
> | Returns `TRUE` if there are any messages queued for a specified group or for all groups.
>     get-messages
>     CHARACTER
> | Returns any messages queued for a specified group or for all groups. Optionally deletes the messages from the queue.
>     get-message-groups
>     CHARACTER
> | Returns a comma-separated list of groups for which there are queued messages.
>     output-messages
>     INTEGER
> | Outputs messages to the Web that have been queued by queue-message and returns the number of messages output. Includes options to format the output and to specify a specific group of messages or all messages.
>     queue-message
>     INTEGER
> | Queues a message for later output by output-messages and returns the message number in the queue. Optionally associates the message with a specified group.

> The definitions for these functions reside in `install-path``/src/web/method/message.i`.

> ##### Generating messages directly

> In embedded SpeedScript and SpeedScript-generating Web objects, where the program code explicitly controls the HTML output, you can call the message API function directly. For most applications you only need to use output-messages and queue-messages. These API functions call the other message API functions.

> ##### Generating messages with a custom tag

> For HTML-mapping Web objects, WebSpeed provides a custom tag (`<!--WSMSG -->`) in `tagmap.dat` to output messages at strategic points in a mapped HTML file. Generally, you invoke the queue-message function to append a message to the message queue. If you want a certain group of messages to be output to the Web, you can insert the `<!--WSMSG -->` tag for that group of messages at any point in the HTML file.

> This custom tag takes two optional attributes:

> - `NAME` — The name of the message group or "all" for all messages in the queue.

> - `VALUE` — The heading to appear prior to the messages output for the specified group.

> Using the custom tag with no attributes defaults to `TYPE="application messages"` and `NAME="all"`.

> The following HTML example contains two `<!--WSMSG -->` tags, one for messages in a `CustNum` group and one for messages in a `CustName` group. When the HTML-mapping Web object invokes the output-fields event procedure, the messages for each respective group are output in the Web page at the specified point, as shown in this code:

>     <FORM ACTION="custnum.w" METHOD="post">
>     <P>
>     <!--WSMSG NAME="CustNum" VALUE="Customer Number Errors" -->
>     <HR>
>     Enter Customer Number:
>     <INPUT TYPE="text" NAME="Customer_Number"> <BR>
>     <INPUT TYPE="submit" NAME="SUBMIT"> <BR>
>     <HR>
>     <!--WSMSG NAME="CustName" VALUE="Customer Name Errors" -->
>     Customer Name:
>     <INPUT TYPE="text" NAME="Customer_Name"> <BR>
>     Customer Phone:
>     <INPUT TYPE="text" NAME="Customer_Phone">

> The tagmap utility procedure `install-path``/src/web/support/webmsg.p` contains the default `web.outpu`t control handler to output the HTML for this custom tag.

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095