Triggering API

E.2 Trigger Structure

The host tools allow users to enter specific information and commands, which the tools then download to the target. Data is usually entered in the GUI window, but it can be entered at the command line as well. The GUI displays and allows entering of the following information (see Figure E-2):

Show trigger information.

Activate triggering.

Create and delete triggers.

Enable and disable triggers.

Choose the event, context, and/or object which will activate a trigger.

Define a conditional expression to refine the circumstances which will activate the trigger (optional).

Define the actions related to the trigger (optional) such as:

call a user function (the function parameters must be given)

start or stop logging

Provide the ID of another trigger to be chained to the current one (optional).

Figure E-2: Triggering Window and Trigger Maintenance Dialog Box

Once it receives this information, the target is responsible for triggering and performs the following actions:

Organizes the data received from the host in a trigger list.

Manages the trigger list.

Activates and deactivates event triggering.

Performs the actions requested by the host (such as disabling, enabling, or deleting triggers).

Interacts with WindView and the event points.

The target saves the information coming from the host in a trigger structure. The target is also responsible for setting the flag to activate triggering when necessary. When this flag is set, the event can be detected by the regular WindView instrumentation, by e( ), or through trgEvent( ). Once the event occurs, the ACTION_IS_SET variable is checked to see whether WindView or triggering is active.

If triggering is active, the list of triggers is checked to see if any is related to that event. If one is found, the specified action is performed. Otherwise execution continues.

The triggering structure is defined as follows:

typedef struct trigger 
    { 
    OBJ_CORE          objCore;       /* trigger object core */ 
    event_t           eventId;       /* event type */ 
    UINT16            status;        /* status of the trigger, */ 
                                      /* i.e. enabled, disabled, etc */ 
    BOOL              disable;       /* check if trigger needs to be */ 
                                       /* disabled after use */ 
    int               contextType;   /* type of context where */ 
                                      /* event occurs */ 
    UINT32            contextId;     /* id of context where */ 
                                      /* event occurs */ 
    OBJ_ID            objId;         /* object type */ 
    struct trigger    *chain;        /* pointer to chained trigger */ 
    struct trigger    *next;         /* ptr to next trigger in list */ 
    int               conditional;   /* check if a condition is set */ 
    int               condType;      /* check the expression */ 
                                      /* type (var/fn) */ 
    void *            condEx1;       /* ptr to conditional expression */ 
    int               condOp;        /* conditional operator */ 
                                      */ (==, !=, ...) */ 
    int               condEx2;       /* second operand (constant) */ 
    int               actionType;    /* type of action (none, fn, lib) */ 
    FUNCPTR           actionFunc;    /* pointer to the action */ 
    int               actionArg;     /* argument passed to the action */ 
    BOOL              actionDef;     /* defer the action */ 
    } TRIGGER;

The following macros are also defined:

Representing the status of the trigger:

#define TRG_ENABLE 1 
#define TRG_DISABLE 0

Defining whether the condition is a variable or a function:

#define TRIGGER_COND_FUNC       0 
#define TRIGGER_COND_VAR        1 
#define TRIGGER_COND_LIB        2

E.2 Trigger Structure

Figure E-2: Triggering Window and Trigger Maintenance Dialog Box