op_ev_valid()
Abstract
Determines if an event handle is valid (refers to an event that exists).
Syntax
op_ev_valid (evhandle)
| Argument | Type | Description |
|---|---|---|
evhandle |
Evhandle |
event handle that may identify an event [An event handle can be obtained from several KPs in this package—such as op_ev_current(), op_ev_seek_time(), and op_ev_next()—and others such as op_intrpt_schedule_self().]. |
Return Type
Boolean
Boolean indicating if the specified event handle is valid or invalid.
An Evhandle is invalid, and thus this KP returns OPC_FALSE, if it was set to an invalid state to indicate an error in a KP that returns an Evhandle; or if it refers to an event that has already completed or been canceled; or if it is an improperly initialized user variable.
Example
/* Obtain the currently executing event (it must be at this module, */
/* since this module woke up.) and the one after it. */
this_event = op_ev_current ();
next_event = op_ev_next_local (this_event);
/* Loop through all of the events scheduled for this module */
/* and cancel any that are retransmission timers. */
while (op_ev_valid (next_event))
{
if ((op_ev_type (next_event) == OPC_INTRPT_SELF) &&
(op_ev_code (next_event) == RETRANS_TIMER))
{
retrans_timer = next_event;
next_event = op_ev_next_local (retrans_timer);
op_ev_cancel (retrans_timer);
}
else
/* Obtain the next event; if there are no more events, op_ev_next_local () */
/* will return an invalid event handle and the loop will terminate. */
next_event = op_ev_next_local (next_event);
}
Details
Evhandles that refer to events that are currently executing or are scheduled to occur are valid. Stale Evhandles, those that refer to events that have already transpired, are invalid. Empty Evhandles, those that are returned from KPs such as op_ev_next() when there is no such event, are invalid.
Purpose
Provides a mechanism to determine if an Evhandle is valid before it is used as an argument to an Event Package KP. When searching for a particular event or kind of event, using this KP provides good indication when to stop looping through the events using KPs such as op_ev_next(). Also, this KP may be used to test that certain KPs are successful when they return, because most KPs that return event handles set up empty event handles to indicate failure.
Errors
- Program Abort: Segmentation violation. (due to a malformed event handle)
Reference
- Use the KP op_ev_type() to determine the type of the event
- Use the KP op_ev_time() to determine the time of the event
- Use the KP op_ev_pending() to determine if the event is pending