PreviousIntrinsic Data Exception Handling FrameworksNext"

Chapter 29: Callback Frameworks

You need to understand Callbacks in order to use the Collection classes, the GUI classes and the ExceptionManager. This chapter shows you how to create Callback instances, and how you can use them in your own applications.

29.1 Overview

An instance of the Callback class contains an object and the name of a method. When you send the message "invoke" to the Callback, it sends a message to the object it contains, invoking the named method.

A Callback instance is like a pointer to a block of code. It enables you to pass a block of code to a class or object method for later execution. For example, to implement an exception handling method, you create a Callback containing the method and pass the Callback to the ExceptionHandler.

29.2 Using Callbacks

There are two stages to using Callbacks:

When you are using Callbacks with Class Library objects, you only need to know how to create the Callback instance. The instance is then passed to the Class Library object, which invokes it when needed. However, you might want to use Callbacks in the classes you write, so this chapter also shows you how can invoke a Callback.

29.2.1 Creating a Callback

To create a Callback object, send the "new" message to the Callback class. You must supply the object which implements the method you want written into the Callback, and the message name to invoke the method.

Terminate the message name with a null byte (x"00). The Callback "new" method looks for a null to find the end of the message name. You can add a null-byte to a literal very easily with the new syntax shown below:

 01 wsLiteral         pic x(16) z"null-terminated". 
 *> equivalent to     pic x(16) "null-terminated" & X"00". 

You can create a Callback as shown below:

 invoke Callback "new" using anObject z"aMethod"
                             [p1] [p2] [p3] [p4] [p5] [p6]
                       returning aCallback

where the parameters are:

anObject contains the object handle to the class or instance object containing the method you want in the Callback.
aCallback an object reference to the Callback created.
[p1]...[p6] are up to six optional parameters for the method. These are passed to the method every time it is invoked. All parameters must be declared as usage object reference.

29.2.2 Invoking a Callback

You don't need to know how to invoke Callbacks in order to use them with the objects in the supplied Class Library, but you may want to use them in classes of your own. To execute the method stored in a Callback, send the message "invoke" to the Callback instance. You can also pass up to three parameters along with the "invoke" message. These will be passed to your Callback method following any parameters specified when the Callback was created (see the section Creating a Callback).

 invoke aCallback "invoke" [using p1 [p2] [p3] ]
                       [returning result]

If the method in a Callback returns a parameter, you must include a returning clause on the invoke to the Callback, with a parameter of matching size.

Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousIntrinsic Data Exception Handling FrameworksNext"