This WAIT-FOR statement instructs the AVM to
stop executing the current block until a specific ABL event occurs.
The AVM continues to respond to all other incoming events and execute
any associated triggers or event procedures while in this wait state.
Note: ABL supports a separate version of the WAIT-FOR
statement (
.NET WAIT-FOR) that blocks for .NET,
as well as ABL, events. For more information, see the
WAIT-FOR statement (.NET and ABL) reference entry.
Syntax
WAIT-FOR event-list OF widget-list
[ OR event-list OF widget-list ] ...
[ FOCUS widget ]
[ PAUSE n ]
|
WAIT-FOR "WEB-NOTIFY" OF DEFAULT-WINDOW
[ PAUSE n ]
[ EXCLUSIVE-WEB-USER ]
|
-
event-list
-
A space or comma-separated list of user-interface events
and other ABL events to wait for.
An event can be any event
described in the Handle-based Object Events Reference.
-
widget-list
-
A space- or comma-separated list of widgets with which the event
is associated. For more information on referencing widgets, see
the Widget phrase reference entry.
- FOCUS widget
-
Specifies the widget that initially receives input focus
when the WAIT-FOR statement is executed. The value widget must
be a valid reference to a widget (a widget name or handle) that
is currently displayed and enabled.
- PAUSE n
-
Specifies a time-out interval for the WAIT-FOR statement.
The value n can be any numeric expression, including
a fractional value. You can choose a whole or a fractional value
for the time-out interval. If the time-out period you specify is
a fractional value, the value is rounded to the nearest whole millisecond.
If a period of n seconds elapses between events,
the WAIT-FOR automatically terminates.
Examples
This
procedure defines two buttons, defines triggers for them, and enables them.
The procedure then waits for the user to close the current window.
The initial focus is placed on the button labeled MORE. The user
can then choose buttons continuously until closing the window or
exiting with the END-ERROR key.
r-wait.p
DEFINE BUTTON more-button LABEL "MORE".
DEFINE BUTTON next-button LABEL "NEXT".
FORM Customer.CustNum Customer.Name more-button next-button
WITH FRAME brief.
FORM Customer EXCEPT Customer.CustNum Customer.Name
WITH FRAME full.
ON CHOOSE OF more-button
DISPLAY Customer EXCEPT Customer.CustNum Customer.Name WITH FRAME full.
ON CHOOSE OF next-button DO:
HIDE FRAME full.
FIND NEXT Customer NO-LOCK NO-ERROR.
IF AVAILABLE Customer THEN
DISPLAY Customer.CustNum Customer.Name WITH FRAME brief.
END.
FIND FIRST Customer NO-LOCK.
DISPLAY Customer.CustNum Customer.Name WITH FRAME brief.
ENABLE more-button next-button WITH FRAME brief.
WAIT-FOR WINDOW-CLOSE OF CURRENT-WINDOW FOCUS more-button.
|
If the user closes the current window then execution
continues after the WAIT-FOR statement. In this case, the procedure
ends because there are no more statements.
The following procedure
uses the PAUSE option of the WAIT-FOR statement so that you automatically
jump ahead to the next record if the user does not perform any action
within three seconds after the customer information is displayed:
r-waitpn.p
DEFINE VARIABLE jump-ahead AS LOGICAL NO-UNDO INITIAL TRUE.
DEFINE BUTTON more-button LABEL "MORE".
DEFINE BUTTON next-button LABEL "NEXT".
FORM Customer.CustNum Customer.Name more-button next-button
WITH FRAME brief.
FORM Customer EXCEPT Customer.CustNum Customer.Name
WITH FRAME full.
ON CHOOSE OF more-button DO:
DISPLAY Customer EXCEPT Customer.CustNum Customer.Name WITH FRAME full.
jump-ahead = FALSE.
END.
ON CHOOSE OF next-button DO:
jump-ahead = TRUE.
END.
ON WINDOW-CLOSE OF CURRENT-WINDOW DO:
QUIT.
END.
ENABLE more-button next-button WITH FRAME brief.
DO WHILE TRUE:
IF jump-ahead THEN
RUN next-cust.
WAIT-FOR WINDOW-CLOSE OF CURRENT-WINDOW OR CHOOSE OF next-button
FOCUS more-button PAUSE 3.
END.
PROCEDURE next-cust:
HIDE FRAME full.
FIND NEXT Customer NO-ERROR.
IF AVAILABLE Customer THEN
DISPLAY Customer.CustNum Customer.Name WITH FRAME brief.
END.
|
In this example, the code for finding the next
Customer has been moved to an internal procedure. The WAIT-FOR statement
has been placed inside a DO loop. The loop iterates when the user
chooses the NEXT button or three seconds elapse. (If the user closes
the window, the QUIT statement is executed and the loop does not
iterate.) On each iteration, if the variable jump-ahead is TRUE, then
the next-cust procedure is run to find and display the next Customer.
If the user chooses the MORE button for a Customer, jump-ahead is
set to FALSE. This prevents the procedure from automatically jumping
ahead to the next Customer. Instead, the user can spend time examining
the data. To move ahead to the next Customer, the user must explicitly
choose the NEXT button. At that point, jump-ahead is reset to TRUE.
Notes
- Any
widget associated with an event must be enabled before you wait
on it.
- In general, do not use an UPDATE statement in an application
that executes a WAIT-FOR statement. One exception is updating fields
in a dialog box.
- In general, if you nest two WAIT-FOR statements in a single
ABL application (where the nested WAIT-FOR executes in a trigger),
you must ensure that your application satisfies the nested WAIT-FOR
first. The event that satisfies the outer WAIT-FOR statement should
be the terminating event for your application.
- In general, when a modal dialog box is active, the event-list can
reference only events supported by the active dialog box and the
widgets it contains. There are two exceptions:
- You can specify
an event on a procedure handle as long as widget-list specifies
only a single procedure handle.
- You can specify the PROCEDURE-COMPLETE event on an asynchronous
request handle.
- In batch mode (running with the -b startup parameter),
the WAIT-FOR statement supports only the following events:
- PROCEDURE-COMPLETE
- READ-RESPONSE
- CONNECT
- Developer events (U1 to U10, and CLOSE)
- The PROCEDURE-COMPLETE event occurs for an asynchronous request
handle when the current ABL session receives the response message
from the AppServer that executed the request. When the WAIT-FOR
statement executes, it processes any PROCEDURE-COMPLETE event that
has occurred but has not yet been processed.
- PROCEDURE-COMPLETE events from a single AppServer connection
are processed in the order that the associated asynchronous requests were
originally generated. To ensure that all pending PROCEDURE-COMPLETE
events are handled by a single WAIT-FOR statement, specify a single
PROCEDURE-COMPLETE event for the last asynchronous request handle
generated before the WAIT-FOR statement.
- To process a PROCEDURE-COMPLETE event for a particular asynchronous
request handle, the AVM:
- Decrements the ASYNC-REQUEST-COUNT
attribute for the server referenced by SERVER attribute for the
asynchronous request handle.
- Decrements the ASYNC-REQUEST-COUNT attribute for a persistent
procedure, if the PERSISTENT-PROCEDURE attribute of the asynchronous
request handle refers to a valid persistent procedure.
- Sets the COMPLETE attribute for the asynchronous request handle
to TRUE.
- Sets the STOP, QUIT, and ERROR attributes for the asynchronous
request handle appropriately as indicated by the response message
from the AppServer.
- Sets the return value for the RETURN-VALUE function, if a return
value was returned by the AppServer.
- Stores any error information returned from the AppServer in the
ERROR-STATUS system handle.
- Attempts to execute the event procedure specified by the EVENT-PROCEDURE
and the EVENT-PROCEDURE-CONTEXT attributes for the asynchronous
request handle, if EVENT-PROCEDURE is not the empty string ("").
- Sets each INPUT parameter for the event procedure to the Unknown value (?) or,
if the parameter is a TEMP-TABLE, the TEMP-TABLE remains unchanged,
if the response message indicates that the remote request finished
with a STOP, ERROR, or QUIT condition.
- Sets the INPUT parameter values for the event procedure to the OUTPUT
and INPUT-OUTPUT parameter values returned by the remote procedure,
if the response message indicates that the remote request completed
successfully.
- Displays an error message, if a specified event procedure fails
to execute for any reason.
- Raises any unhandled STOP condition, ERROR condition, or QUIT
condition in the context of the WAIT-FOR statement, if the event
procedure completes execution with that condition.
- These are possible causes for failing to execute the event procedure
for a PROCEDURE-COMPLETE event. All of these failures raise a STOP condition
in the context of the WAIT-FOR statement:
- The procedure handle
referenced by the EVENT-PROCEDURE-CONTEXT attribute is no longer
valid.
- The internal procedure specified by the EVENT-PROCEDURE attribute
cannot be found.
- The parameters to the internal procedure specified by the EVENT-PROCEDURE
attribute are not all INPUT parameters.
- The parameter signature of the internal procedure specified
by the EVENT-PROCEDURE attribute does not match the output parameters
returned in the response message for the asynchronous request.
- For SpeedScript, the WAIT-FOR statement instructs WebSpeed to stop
executing the current block until the WEB-NOTIFY event occurs. The
WEB-NOTIFY event is intended for internal use only, it does not apply
to SpeedScript programming.
- In the context of the .NET blocking method, System.Windows.Forms.Application:Run( ),
if you directly or indirectly execute this WAIT-FOR statement while
displaying a non-modal ABL window, in certain contexts (such as within
a user-defined function or non-VOID method) this
statement execution raises the STOP condition. For more information
on the .NET Application:Run( ), method,
see the reference entry for the WAIT-FOR statement (.NET and ABL).