WAIT-FOR statement (ABL only)

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.

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).

See also

DISABLE statement, ENABLE statement, ON statement, Trigger phrase, WAIT-FOR statement (.NET and ABL), Widget phrase