OMstatus_check

Synopsis

int OMstatus_check(
int percent_done,
const char *mod_name,
int *interrupt);

Description

OMstatus_check performs two functions:

• updates the current status information (percent done and module name)

• optionally returns an interrupt flag that indicates if this object has been interrupted

This function should only be called from within the callback function of a method. In order for this function to work, you should have enabled status display for your method by setting the status property to 1. In V, you can do this with:

module my_module {
omethod update<status=1> = "my_module_update";
};

There is some overhead for calling this routine. You should try to avoid calling it more than is necessary, roughly a few times per second of execution.

If your module is not contained in a single function, you may sometimes want to bracket lower level operations that are used by several different higher level operations and thus cannot accurately predict what range of execution time they will occupy. You can use the routines OMpush_status_range and OMpop_status_range to perform this function.

Arguments

percent_done

This integer sets the percent done flag in the scheduler. This is a number between 0 and 100 that indicates roughly what percentage of the current method's work has been completed so far. This value is displayed to the user through a status bar. Setting this to a 0 value prevents flag from being updated.

mod_name

This string specifies the module name or other information that is displayed with the status information. You can use it to display a short one-line message about what operation is currently proceeding. If this value is passed as NULL, this field is not updated.

interrupt

When this value is returned as 1, it indicates that the user has attempted to interrupt the current operation. Your method should then take whatever steps are necessary to abort the current operation and return as soon as possible. If you are not going to honor this flag, you should pass a NULL value for this parameter as there is some overhead for calling this routine.

Example

This example shows how you might place the OMstatus_check call into a loop inside of a module's update method:

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 */
}
// insert the body of the loop here
}

Returned value

A status code. See Return Status .