HomePowerBuilderAppeon Documentation Center

Yield

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
NEXT

In 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
Prev  Up  Next
Year  Home  Zoom