WebSpeed
Developer’s Guide


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 5–2 lists these functions.

Table 5–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:

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

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:

<HTML> 
<BODY> 
<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"> 
</P> 
</FORM> 
</BODY> 
</HTML>  

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


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