Clarion Community Help

YIELD

YIELD temporarily gives control to Windows to allow other concurrently executing Windows applications to process events they need to handle (except those events that would post messages back to the program containing the YIELD statement, or events that would change focus to the other application).

YIELD is used to ensure that long batch processing in a Clarion application does not completely “lock out” other applications from completing their tasks. This is known as “cooperative multi-tasking” and ensures that your Windows programs peacefully co-exist with any other Windows applications.

Within your Clarion application, YIELD only allows control to pass to EVENT:Timer events in other execution threads. This allows you to code a “background” procedure in its own execution thread using the TIMER attribute to perform some long batch processing without requiring the user to wait until the task is complete before continuing with other work in the application. This is an industry-standard Windows method of doing background processing within an application.

The example code on the next page demonstrates both approaches to performing batch processing: making the user wait for the process to complete, and processing in the background. Only the WaitForProcess procedure requires the YIELD statement, because it takes full control of the program. Background processing using EVENT:Timer does not need a YIELD statement, since the ACCEPT loop automatically performs cooperative multi-tasking with other Windows applications.

Example:

StartProcess PROCEDURE

Win  WINDOW('Choose a Batch Process'),MDI

    BUTTON('Full Control'),USE(?FullControl)

    BUTTON('Background'),USE(?Background)

    BUTTON('Close'),USE(?Close)

   END

CODE

OPEN(Win)

ACCEPT

 CASE ACCEPTED()

 OF ?FullControl

  DISABLE(FIRSTFIELD(),LASTFIELD())   !Disable all buttons

  WaitForProcess                      !and call the batch process procedure

  ENABLE(FIRSTFIELD(),LASTFIELD())    !Enable buttons when batch is complete

 OF ?Background

  START(BackgroundProcess)            !Start new execution thread for the process

 OF ?Close

  BREAK

 END

END

WaitForProcess PROCEDURE               !Full control Batch process

CODE

SETCURSOR(CURSOR:Wait)                !Alert user to batch in progress

SET(File)                             !Set up a batch process

LOOP

 NEXT(File)

 IF ERRORCODE() THEN BREAK END

 !Perform some batch processing code

YIELD                                !Yield to other applications and EVENT:Timer

END

SETCURSOR                             !Restore mouse cursor

BackgroundProcess  PROCEDURE           !Background processing batch process

Win  WINDOW('Batch Processing…'),TIMER(1),MDI

     BUTTON('Cancel'),STD(STD:Close)

    END

CODE

OPEN(Win)

SET(File)                             !Set up a batch process

ACCEPT

 CASE EVENT()

 OF EVENT:CloseWindow

  BREAK

 OF EVENT:Timer                       !Process records whenever the timer allows it

  LOOP 3 TIMES

   NEXT(File)

   IF ERRORCODE()

    POST(EVENT:CloseWindow)

    BREAK

   END

   !Perform some batch processing code

  END

 END

END

See Also:

ACCEPT

TIMER