Description
Yields control to other graphic objects, including objects that are not PowerBuilder objects. Yield checks the message queue and if there are messages in the queue, it pulls them from the queue.
Syntax
Yield ( )
Return value
Boolean.
Returns true if it pulls messages from the message queue and false if there are no messages.
Usage
Include Yield within a loop so that other processes can happen. For example, use Yield to allow end users to interrupt a loop. By yielding control, you allow the user time to click on a cancel button in another window. Then code in the loop can check whether a global variable's status has changed. You can also use Yield in a loop in which you are waiting for something to finish so that other processing can take place, in either your or some other application.
Using other applications while retrieving data
Although the user cannot do other activities in a PowerBuilder application while retrieving data, you can allow them to use other applications on their system. Put Yield in the RetrieveRow event so that other applications can run during the retrieval.
Of course, Yield will make your PowerBuilder application run slower because processing time will be shared with other applications.
Examples
In this example, some code is processing a long task. A second window includes a button that the user can click to interrupt the loop by setting a shared boolean variable sb_interrupt. When the user clicks the button, its Clicked script sets sb_interrupt, shown here:
sb_interrupt = TRUE
The script that is doing the processing checks the shared variable sb_interrupt and interrupts the processing if it is true. The Yield function allows a break in the processing so the user has the opportunity to click the button:
integer n
// sb_interrupt is a shared variable.
sb_interrupt = FALSE
FOR n = 1 to 3000
Yield()
IF sb_interrupt THEN // var set in other script
MessageBox("Debug","Interrupted!")
sb_interrupt = FALSE
EXIT
ELSE
... // Some processing
END IF
NEXTIn this example, this script doing some processing runs in one window while users interact with controls in a second window. Without Yield, users could click in the second window, but they would not see focus change or their actions processed until the loop completed:
integer n FOR n = 1 to 3000 Yield() ... // Some processing NEXT
In this example, a script wants to open a DDE channel with Lotus Notes, whose executable name is stored in the variable mailprogram. If the program is not running, the script starts it and loops, waiting until the program's startup is finished and it can establish a DDE channel. The loop includes Yield, so that the computer can spend time actually starting the other program:
time starttime
long hndl
SetPointer(HourGlass!)
//Try to establish a handle; SendMail is the topic.
hndl = OpenChannel("Notes","SendMail")
//If the program is not running, start it
IF hndl < 1 then
Run(mailprogram, Minimized!)
starttime = Now()
// Wait up to 2 minutes for Notes to load
// and the user to log on.
DO
//Yield control occasionally.
Yield()
//Is Notes active yet?
hndl = OpenChannel("Notes","SendMail")
// If Notes is active.
IF hndl > 0 THEN EXIT
LOOP Until SecondsAfter(StartTime,Now()) > 120
// If 2 minutes pass without opening a channel
IF hndl < 1 THEN
MessageBox("Error", &
"Can't start Notes.", StopSign!)
SetPointer(Arrow!)
RETURN
END IF
END IF