SendEvent

SendEvent is a built-in function that sends a specified event to the project's event history. The event can include a comment and up to ten custom fields for other data.

Syntax

SendEvent(strEvent,optNumFlag,optStrComment,optCustom1,…,optCustom10)

strEvent

The event message or description.

optNumFlag

A numeric flag that indicates whether to associate a comment with the event. Any non-zero value is considered TRUE.

This parameter is optional; if no value is specified, the default value is 0 (FALSE).

optStrComment

The text of the comment to be associated with the event.

This parameter is optional. If no value is specified, the resulting behavior varies depending on where the function is called:

If the function is called by a background task, such as Math or Scheduler, on the server station, a dialog box is displayed on that station in order to get the comment text. The dialog box is displayed by the project runtime software itself, regardless of whether the local Viewer module is also running on the station.

The function is executed synchronously, however, which means the background task is suspended while it waits for the execution to be completed, and the execution is completed only after the event — including the comment, if any — is saved in the event log. If no one is watching the station, or if the station is running "headless" (without a display or with the display turned off), the background task might be suspended indefinitely and the project's overall runtime performance might be severely affected while the function waits for the comment text.

Therefore, we recommend that you do not use this function in any background task unless you either specify a value for this parameter or omit the comment entirely (see optNumFlag above).

If the function is called by a project screen on a Thin Client, a dialog box is displayed by that Thin Client in order to get the comment text. It is expected that the current user at the client station will promptly respond to the dialog box, but even if they do not, only the project screen that called the function will be suspended while the function waits for the comment text. The project's overall runtime performance should not be affected.

optCustom1 … optCustom10

Custom data that will be included with the event. You can specify any type of data (num, str, etc.) for each field. The number of custom fields is set in the Options tab of the project settings.

Note: This feature is not supported in projects that are configured to run on the Embedded target platform. For more information, see About target platforms, product types, and target systems.

Return value

This function returns one of the following possible values:

Notes

In order to use this function in your project, you must enable the Event Logger and then select the Custom Messages option. For more information, see Events.

Examples

Send the event message to the event history:

SendEvent("Valve Open")

Send the event message concatenated with a tag value:

SendEvent("Valve Open Tank No. " + SelectedTank)

Prompt the user for a comment to associate with the event:

SendEvent("Valve Open Tank No. " + SelectedTank,1)

Associate a comment with the event, but use a tag value instead of a user comment:

SendEvent("Valve Open Tank No. " + SelectedTank,1,ValveOpenComment)

Prompt for a user comment, and then also include custom data:

SendEvent("Valve Open Tank No. " + SelectedTank,1,,Tank[SelectedTank].Temperature,Tank[SelectedTank].Level,Tank[SelectedTank].Pressure)

Note: The examples above show how the addition operator (+) can be used to concatenate strings and tag values, but it can be used this way only in a Built-in Language interface (for example, a Math worksheet). In a VBScript interface (e.g. a Script worksheet), you must use the ampersand (&) instead.