Chapter 17: Callback Frameworks

This chapter shows you how to create Callback instances, and how you can use them in your own applications.

All the code shown in this chapter uses the Micro Focus alternatives to the ISO 2002 syntax.

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.

The Base Class Library also contains a class called EntryCallback which enables you to create a Callback to any COBOL entry point. You can use an EntryCallback with Class Library objects anywhere you can use a Callback, enabling you to use Class Library functionality like collection iterators with procedural COBOL code. All the rules for using Callbacks apply equally to EntryCallbacks.

Using Callbacks

There are two stages to using Callbacks:

Creating a Callback instance
Invoking a Callback instance

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.

Creating a Callback

To create a Callback object, send the "new" message to the Callback class. You must supply the object that 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 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.

Invoking a Callback

You do not 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.