Events and the event calendar
If the custom logic that you need to install does not fit into one of the user-installable rules discussed in Section 2.3., you can write a function for your own event. You may also need to access the event calendar or schedule an event from your custom rule. An example where you might want to do this is periodic inventory valuation.
Events are calls to functions that occur at scheduled times. Events are scheduled by adding them to an event list. Two event lists, also called event calendars, are used by the Scheduler to store events. These event lists are defined as follows:
- standard - This list contains standard and custom events in the order in which they are scheduled to occur. You can schedule your custom events on this list.
- internal - This list contains events which happen immediately. All of the events on this list are processed before any event on the standard list is processed.
The following special system functions can be used to schedule events and to manipulate event lists in other ways.
| Function | Description |
|---|---|
| cschd0 | Schedule a zero-time system event (on the internal list). |
| csched | Schedule a timed system event (on the standard list). |
| cselep | Search the event lists for an entity. |
| cselfv | Search the event list for the first entity scheduled for a given function. |
| cselnv | Search the event list for the next entity scheduled for a given function. |
| csepea | Get the scheduled event address for an entity. |
| csepet | Get the scheduled event time for an entity. |
| csnew | Get a pointer to a new entity of specified size. |
| CSNEW | Get a pointer to a new entity of specified size. (The difference between CSNEW and csnew is discussed in Section 3.4.2). |
| csterm | Terminate an entity pointer. |
| uccschd0 | Schedule a zero-time user event (on the internal list). |
| uccsched | Schedule a timed user event (on the standard list). |
You should not use the standard list functions described in Section 3.4 to manipulate event lists because event lists contain many different types of entities and their ordering is more complex than other lists.
Your custom event function must accept only one argument, a pointer to a CSENTITY. A CSENTITY must be allocated using function csnew, but the contents of the entity can be anything you like. For example, your custom event function should have the form:
void evntfun(CSENTITY *)
{
/* Tailored event logic. */
}
and could be scheduled to occur one hour from the current Scheduler time with a call to the function uccsched:
uccsched(ep, "EVNTFUN", 1.0);
You must schedule the first occurrence of your custom event from ucini2 or from some custom functions that you have written. You can schedule subsequent events from the event function itself or from custom functions you have written.