ZEVENT_RCVR (3X)

NAME

zevent_rcvr - Set up a program ZLU to receive ZCOM alarms and events

SYNOPSIS

#include           <zcom/zcomsys.h>
#include           <zcom/zcomcall.h> /* if compiled with ANSI C (recommended) */
 
int zevent_rcvr (rzap, action, eclass, einfop)
 
zaddr_type         *rzap;
int                action;
uint32             eclass;
Zclinfo_type       *einfop;

DESCRIPTION

Routine zevent_rcvr is used to set up a program to receive ZCOM alarm and system event messages. When this routine is called, it causes the ZCOM subsystem to queue the indicated type(s) of events or alarms on the program queue specified by the rzap parameter. The event type is specified through the eclass parameter. The application program can read the event and/or alarm messages by issuing a zread call using the program ZLU specified in the rzap parameter. There is a limit on the number of programs that can request reception of each source of ZCOM event messages (e.g. status event of different target nodes are considered different sources). The limit is set to ZcMAX_SHARED_RCVRS, currently, 64.

If the action parameter is ZcDELETE, then the receiver linkage is deleted. That is, events and alarms of the indicated type (eclass) will no longer be delivered to that receiver ZLU.

The libraries libzcom_c.a and libpthread.a must be linked into the calling program by giving the options "-lzcom_c -lpthread" to cc(1) or ld(1).

Threads Considerations

This routine may be called from multi-threaded application using the POSIX (1003.1c) kernel threads API package. This routine has the following characteristics when called by a multi-threaded application:

cancellation point	Thread cancellation can occur when a thread calls this routine.
async-cancel unsafe	The calling thread's cancelability type must be PTHREAD_CANCEL_DEFERRED if cancellation is enabled.
async-signal unsafe	It cannot be called from a signal handler.
fork unsafe	It cannot be called by a child process after fork(2) but before exec(2).

PARAMETERS

rzap	ZCOM address of the receiver program (required).
action	Type of action to perform (required). ZcDELETE_EVENT - Remove the linkage for the indicated event classes. That is, those event classes will no longer be delivered to the program queue specified by the rzap parameter. Events that have already been queued prior to this call are not deleted. ZcADD_EVENT - Incrementally add the event classes indicated by the eclass parameter to the list of events delivered to the program (specified by the rzap parameter). ZcREPLACE_EVENT - Atomically replace any previously specified event classes with new event classes specified by the eclass and einfop parameters.
eclass	ZCOM Subsystem event class (type of event). Note that each event class is a single bit that can be OR'd together to specify multiple event classes in a single zevent_rcvr call. ZcNODE_STATUS - Deliver an event when a Node or any link to a Node changes status. See the ZCOM Programmer's reference manual for a detailed discussion of node status events. ZcDYN_CONFIG - Deliver dynamic reconfiguration completion events. These types of events are generated by the zconfig routine after an application or protocol driver has dynamically changed the ZCOM configuration. ZcALL_EVENTS - Deliver all classes of ZCOM alarms and events.
einfop	This data structure contains any event class specific information needed to carry out the action specified. Some of this information is optional, some of it is required (depending on the action and eclass values). The fields in this data structure are listed below with their dependent class types given in parenthesis. src_node (ZcNODE_STATUS) - This is the node that should be used to detect the node status changes. It can be the local or a remote node. This field is required when ZcNODE_STATUS is specified in the eclass parameter. target_node (ZcNODE_STATUS) - This is the node that should be monitored. If the src_node detects a change in the status of the target_node or the link between the src_node and target_nodes, an event message will be generated. If target_node is assigned the value ZcALL_NODES, then all nodes (from the src_node's perspective) will be monitored. This field is required when ZcNODE_STATUS is specified in the eclass parameter.

NOTES

When an Application program issues a zread call, it can differentiate the type of information it is receiving by looking at the type of the message. ZCOM Event messages will return a message type of 5 (ZCOM_MSTYPE_LSEM) for a local system event, and a message type of 13 (ZCOM_MSTYPE_RSEM) for a remote system event. The difference between local and remote event messages is where the event was generated. Local event messages were generated locally and remote event messages were generated at a remote node. The content of the message will contain additional information about the event.

The 'C' structure for a ZCOM Event Message is shown below:

/*--- ZCOM Event Messsage Type ---*/
 
typedef structuint8     setype;            /* Event type. */
uint8     seflag;            /* Event flags (reserved for now). */
uint16    senode;            /* Node where event was generated. */
uint32    setime;            /* Event time (Epoc time). */
union 
      {
      struct {                     /* Node Status change Event data. */
           uint16  node_num;       /* Node whose state has changed. */
           int8    nstat;          /* Node state change indicator. */
           int8    spare;          /* Reserved for future use. */
           int8    hstat[ZCOM_NHOST];   /* Link state change indicator */
           } node;
      struct {                     /* Dynamic Reconfiguration Event data. */
           uint32  cfg_class;           /* User supplied config class
                                   /*   (1-999 reserved for use by ZCOM) */
 
           uint32  cfg_info1;           /* User supplied class specific info. */
           } recfg; 
      } sedata;                    /* Event class specific data. */
} zevent_type;

For the field setype there are two defined event types:

ZCOM_SETYPE_NODE	- Node Status Change Event.
ZCOM_SETYPE_RECONFIG	- Reconfiguration Complete Event.

See the ZCOM Programmer's Reference Manual for a detailed description of the fields in this data structure.

RETURN VALUE

Routine zevent_rcvr returns 0 if successful. Otherwise, a non-zero error code is returned. See /opt/acc/include/zcom/zcomsys.h for the list of ZCOM error codes and their meanings.

EXAMPLE

#include <zcom/zcomsys.h>
#include <zcom/zcomcall.h>
 
int           ierr;
zaddr_type    rzap;
int           action;
uin32         eclass;
Zclinfo_type  cinfo;if (ierr = zevent_rcvr (&rzap, action, eclass, &cinfo)) {
 /* error return code */
}
else {
          /* good return code */
}

FILES

/opt/acc/include/zcom/zcomsys.h	ZCOM system general include file, containing data types, data structures, constants, error codes, masks, etc. Note that this must be the first include file before any other ZCOM include files.
/opt/acc/include/zcom/zcomcall.h	ZCOM routine function prototypes (requires ANSI C compilation).