E.3   Triggering API

The following functions are used to manipulate the triggering structure, to detect the presence of a trigger, and to perform the action specified in the trigger definition:

Adding a Trigger to the Trigger List

TRIGGER_ID trgAdd 
    ( 
    event_t     event,        /* event type as defined in eventP.h */ 
                               /* for WindView, if given */ 
    int         status,       /* initial status (enabled/disabled) */ 
    int         contextType,  /* type of context where event occurs */ 
    UINT32      contextId,    /* ID (if any) of context where event occurs */ 
    OBJ_ID      objId,        /* object type, if given */ 
    int         conditional,  /* flag specifying if there is a condition */ 
    int         condType,     /* flag specifying if an existing condition */ 
                               /* is a variable or a function */ 
    int         * condEx1,    /* pointer to conditional expression */ 
    int         condOp,       /* operator (==, !=, <, <=, >, >=, |, &) */ 
    int         condEx2,      /* second operand (constant) */ 
    BOOL        disable,      /* flag specifying whether to disable */ 
                               /* trigger after it is hit */ 
    TRIGGER     *chain,       /* flag specifying if another trigger is */ 
                               /* associated with this one */ 
    int         actionType,   /* action type associated with trigger */ 
    FUNCPTR     actionFunc,   /* pointer to the function */ 
    BOOL        actionDef,    /* defer the action */ 
    int         actionArg     /* argument passed to function if any */ 
    ) 
    { 
        fills in the trigger struct and adds it to the trigger list; 
        returns the trigger ID 
    }

Deleting a Trigger from the Trigger List

Triggers are deleted when they are removed from the trigger list. The function trgDelete( ) also checks to see if any other triggers are still active; if none are but triggering is still active, it turns it off. Triggering introduces some overhead and should be disabled if no function is present.

STATUS trgDelete 
    ( 
    TRIGGER_ID trgId 
    ) 
    { 
        delete the trigger from the table;         turn triggering off if this was  
        the last trigger and triggering  is still on 
    }

Activating Triggering

Any time an event point is hit when triggering is active, a check for the presence of possible triggers is performed. This introduces overhead, so it is important to activate triggering only when necessary:

STATUS trgOn() 
    { 
        set evtAction to TRG_ACTION_IS_SET if not already set 
    }

Deactivating Triggering

void trgOff() 
    { 
        set evtAction to TRG_ACTION_IS_UNSET if it is on 
    }

Showing Information on Triggers

The following information is given:

If options is 1 and trgId is specified, all parameters are shown for the specified trigger. If trgId is NULL all the triggers are shown.

STATUS trgShow 
    ( 
    TRIGGER_ID trgId, 
    int        options 
    ) 
    { 
        display information on the specified trigger 
        or on all triggers 
    }

Changing Trigger Status

Once a trigger is created by trgAdd( ), its status can be set by using the trgEnable( ) function. This is the mechanism used to activate a chained trigger. A counter is also incremented to keep track of the total number of currently enabled triggers. This information is used by trgDisable( ).

STATUS trgEnable 
    ( 
    TRIGGER_ID trgId 
    ) 
    { 
        enable the trigger unless the maximum number of triggers 
        is already enabled 
    }

A trigger can be disabled by using trgDisable( ). This function also checks to see if there are any other triggers still active. This is done through the counter trgCnt. If trgCnt is 0 and triggering is still on, it calls trgOff( ).

STATUS trgDisable 
    ( 
    TRIGGER_ID trgId 
    ) 
    { 
        turn the trigger off; if this is the last active trigger,         turn triggering off. 
    }

Creating a User Event to Fire a Trigger

This routine triggers a user event. A trigger must exist and triggering must have been started with trgOn( ) or from the triggering GUI to use this routine. evtId must be in the range 40000-65535.

void trgEvent 
    ( 
    event_t evtId     /* event*/ 
    ) 
    { 
        set a user event with the specified ID 
    }