U_WAIT

Wait for a user response

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
xcall U_WAIT([D_BELL|D_NOBELL], [D_ALERT|D_ERROR])

Arguments

D_BELL | NOBELL

(optional) Ring the terminal bell (default) or don’t ring the terminal bell. (n)

D_ALERT | D_ERROR

(optional) Do alert processing (default) or do error processing. (n)

Discussion

U_WAIT displays a message in a window and waits for a user response. The waiting is either alert‑style (D_ALERT) or error‑style (D_ERROR). The primary difference between the two styles is how you want the message to be acknowledged.

An alert state is a normal part of processing a given function. For example, it could be a completion message after some lengthy processing has completed. Alert‑style processing displays a message (“Press return to continue” by default) and waits for the user to press return (enter).

An error state is an exception condition. It does not occur unless an invalid status exists. In this case, you want the user to read the displayed message and then correct the error condition (entry of invalid data, for example). You don’t want a simple return (enter) to terminate the error state because users often enter data at the terminal before it has actually been requested (referred to as “type‑ahead”). If the user receives an error condition with type‑ahead pending, the first return in the type‑ahead data would inadvertently terminate the error condition. The data in any additional type‑ahead would then be entered where the error originally occurred, either causing another error or entering valid but incorrect data.

For this reason, error‑style processing purges all type‑ahead data before displaying an error message. By default, this message is “Press ^G to continue” on UNIX and OpenVMS and “Press return to continue” on Windows. It then waits for a response. On UNIX and OpenVMS, the terminal bell rings each time an incorrect continuation character is entered. (The terminal bell will not ring if g_beep is set to false. See g_beep.)

U_WAIT on Windows

In traditional Synergy, U_WAIT creates a Windows‑style message box that contains the alert or error message, an icon, and an OK button. The icon is an information icon (i) if you pass D_ALERT, or an exclamation point (!) if you pass D_ERROR.

In Synergy .NET, Toolkit uses a cell‑based‑style message box if g_netnativemsgbox (in tools.def) is set to false, which is the default. If g_netnativemsgbox is set to true, Toolkit uses a native Windows message box.

U_WAIT cannot time out on Windows, and the g_beep setting has no effect (see g_beep).

U_WAIT on UNIX and OpenVMS

On UNIX and OpenVMS, U_WAIT looks for an existing wait window called u_wait_msg. If it can’t find this window, it looks in the window library opened on g_utlib. If it can’t find u_wait_msg in the library (or a window library is not defined), U_WAIT creates a one‑line window of that name and places it three lines above the bottom of the screen body. The wait message will be displayed in this window.

If you create your own u_wait_msg window, you can control the window’s vertical placement, but not the horizontal placement. Toolkit recognizes a vertical placement setting for this window but ignores a horizontal placement setting.

You can redefine the continuation key code and the continuation message for both the error and alert states by changing the contents of g_wt_err_key, g_wt_err_msg, g_wt_alrt_key, and g_wt_alrt_msg, respectively, in the tkctl.def file.

If a time‑out occurs, g_select is set to true and g_entnam is set to the entry name specified in tkctl.def for g_time_entry. By default, g_time_entry is defined as “O_TIMEOUT”.

Examples

The first example displays a message in an alert state but does not ring the terminal bell. The second example displays a message in an error state; it will ring the terminal bell.

xcall u_wait(D_NOBELL, D_ALERT)
xcall u_wait(D_ERROR)