Core AVS/Express and the Object Manager

Adding status and interrupt controls

This chapter describes how to use the status and interrupt facility to display status information to the user and allow the user to interrupt an application.

This chapter discusses:

6.1 Introduction

The status and interrupt facilility enables you to monitor and control the execution of your application.

6.1.1 Status information

Status information includes:

You can control how the module name and the percent completion fields are displayed to the user by customizing the user interface of the control panel.

In order for the system to show status information for a method that you write, you must:

While the method is executing, you can also change the current module field to display a text message to the user about what operation is proceeding.

6.1.2 Interrupt capabilities

Interrupt capabilities include

Interrupt capabilities apply only to methods that are interruptable. A method is by default interruptable. A method can declare, through an object property, that it is not interruptable.

You control the user interface for interrupt information, whether a module is interruptable, and when and how a module reacts to an interrupt request.

6.2 Scheduler object

Underpinning the status and interrupt facility is a special object called Scheduler, located immediately under Root in the object hierarchy.

Scheduler contains four external-use subobjects:

An application interacts with Scheduler through user-interface connections to the subobjects. For example, if you want to display the current module to the user, you typically connect a UItext widget to Scheduler.current_mod.

See Section 6.3, Connecting a user interface to Scheduler  [page 6-6].

Scheduler.disable, an int object, indicates whether the user has requested a disable. 0 means no; nonzero means yes. You typically connect a UItoggle widget to Schedule.disable.


Scheduler.interrupt, an int object, indicates whether the user has requested an interrupt. 0 means no; nonzero means yes. When interrupt is set, AVS/Express also sets disable. You typically connect a UIdynamic_toggle to Schedule.interrupt.


Scheduler.percent_done, an int object, indicates the module's percent completion. You typically connect a UIfield widget to percent_done.

You are responsible for maintaining percent_done, which you typically do from a module's method. You set percent_done with a call to OMstatus_check. You can control the minimum and maximum range displayed with calls to OMpush_status_range and OMpop_status_range.

See Section 6.5, Setting and querying information from a function  [page 6-9].

Scheduler.current_mod, a string, indicates the current module. If a method has status information enabled, AVS/Express sets current_mod to the method's name when the method is about to be invoked. You typically connect a UItext widget to Schedule.current_mod.

A function can set current_mod with a call to OMstatus_check. This enables the function to display arbitrary text and to change this text as the method proceeds.

6.3 Connecting a user interface to Scheduler

6.3.1 To use the standard interface

AVS/Express supplies a standard user interface for displaying the information in Scheduler as part of the SingleWindowApp and MultiWindowApp DataViewers. This appears below the Module panel and consists of simple User Interface widgets attached to the percent_done, current_mode, interrupt, and disable fields.

Note that you can also access a control panel interface to Scheduler from the control menu on a ModuleStack.

6.3.2 To build your own interface

You can build your own interface to Scheduler.

1. Build the user interface, consisting of appropriate widgets for the Scheduler subobjects you want to display.
Scheduler subobject
Widget you typically use
UItoggle or perhaps UIdynamic_toggle
UIslider or UIfield

2. Connect each widget's value, label, or set subobject to the appropriate subobject in Scheduler. You cannot draw a connection line, as Scheduler does not appear in the Network Editor. Instead, you enter a connection in the widget subobject's value box. For example, to refer to Scheduler.interrrupt, you enter the connection operator (=>) followed by Scheduler.interrrupt.

6.3.3 UIdynamic_toggle

Generally, a widget has no special execution priority. When the user interacts with a widget, the Object Manager executes the widget's update method only after it has handled other methods already in the queue.

UIdynamic_toggle is like UItoggle, but with the added feature that the Object Manager executes its update method immediately. This is particularly useful for the widget connected to Scheduler.interrupt. When the user selects the interrupt toggle, you want Scheduler.interrupt updated immediately. An executing module's function can then query Scheduler.interrupt (by calling OMstatus_check) and take the appropriate action.

CAUTION: Use UIdynamic_toggle cautiously. It works here because it is connected to Scheduler.interrupt (and possibly Scheduler.disable), and access to these Scheduler subobjects is controlled.
Note: You can customize any widget to achieve the same affect by adding to the widget a subobject of type UImake_dyn_wind, then connecting its handle subobject to the widget's handle subobject. dyn_wind stands for dynamic window. For a model of this, see UIdynamic_toggle. Use this capability cautiously.

6.4 Declaring a module's behavior

A module's update method declares, through object properties, whether the Object Manager should display status information for the module and whether the module is interruptable.

6.4.1 To enable or disable status information

By default, a method does not display status information. To enable status information, set the method's status property to 1. Use the Properties Editor on the method object.

6.4.2 To enable or disable interruptability

By default, a method can be interrupted and disabled. To allow a method to continue to execute even when the system is disabled, set the interruptable property to 0 on the method object. You might want to do this for User Interface objects so that they continue to provide feedback despite the system being disabled.

6.5 Setting and querying information from a function

A method can make OM calls to set and query scheduler information.

6.5.1 To access Scheduler information

A method can set Scheduler.percent_done, Scheduler.current_mod, and query Scheduler.interrupt by calling OMstatus_check.

For details, see Section 1.104, OMstatus_check  [page 1-197]

6.5.2 To set a range for percent done

A function can normalize percent_done, one of the arguments specified in a call to OMstatus_check, by indicating, in advance, a percent range.

For example, you specify a percent range of 0 to 20. You then call OMstatus_check and specify 25 for percent_done. The Object Manager normalizes percent_done to 5 (that is, 25 percent of 20).

You can push, and subsequently pop, multiple percent ranges onto a stack maintained by the Object Manager. When normalizing, the Object Manager uses the top range in the stack.

This feature is useful when the work of an update function is split among several other functions that the update function calls. The update function sets the percent ranges for the other functions. See the example, below.

To push a range onto the stack

Call OMpush_status_range.

To pop a range from the stack

Call OMpop_status_range.

For details, see Section 1.87, OMpush_status_range and OMpop_status_range  [page 1-168]

6.5.3 Example module code

get_random_values(int arr[], int size)
int i, stop;
for (i = 0; i < size; i++) {
if (!(i & 0xff)) { /* do only every so often... */
(void) OMstatus_check(i * 100 / size, NULL, &stop);
if (stop) return(0); /* user interrupted us */
arr[i] = random();
update_me(OMobj_id obj_id, OMevent_mask mask, int seq_num)
int arr1[1000], arr2[500];
int stat;

stat = get_random_values(arr1,1000);
if (stat != 1) return(0); /* interrupted */

stat = get_random_values(arr2,500);
if (stat != 1) return(0);

... set the values in arr1 and arr2 into objects...