NAME
          irPostEventC, irPostEventQ, irPostEvent - post an event to
          an application or channel

     SYNOPSIS
          #include <irapi.h>

          int irPostEventC (int channel_nbr, const void *mbuf, int
          len);

          int irPostEventQ (ir_key_t q_key, const void *mbuf, int
          len);

          int irPostEvent (const void *mbuf, int len);

     DESCRIPTION
          The irPostEventC and irPostEventQ functions allow processes
          to communicate with each other by generating events on the
          indicated channel_nbr or q_key.  mbuf is a pointer to a mes-
          sage buffer to be sent to the target channel or queue.

          mbuf must be a user allocated structure of the following
          form:

              struct msgBuf {
                  struct mbhdr header;
                  char udata[VARSIZE];
              } msgBuf;

              struct msgBuf *mbuf;

          struct mbhdr is defined in mesg.h
          (which is included by irapi.h) as follows:
              struct mbhdr {
                  long mtype;
                  short irType;
                  short irWhoTo;
                  long irChan;
                  long mchan;
                  short morig;
                  short mcont;
                  unsigned short mseqno;
              };

          Applications using irPostEventQ and irPostEventC are not
          required to set any of the elements in the mbhdr structure.
          irWhoTo, irChan, irType and morig are always set by IRAPI
          with these functions.  Applications may use the remaining
          fields for their own purposes.

          irPostEvent requires that the application set irWhoTo and
          irChan directly.  irPostEvent sets irType and morig
          internally.  Applications may use the remaining fields for
          their own purposes.  Applications should set irWhoTo to the
          Qkey of the destination or to IRD_IRAPI if the event is
          channel based.  irChan should be set to the channel number
          if the message is intended for a channel or IRD_INVALID if
          the message is intended for a queue.

          The IRE_EXTERNAL event is generated on the target channel or
          queue. See IrEVENTS(4IRAPI) for a description of the event
          structure and possible events.  The event structure element
          event_text points to a copy of the mbuf.  The receiving pro-
          cess should copy the contents of event_text to a private
          buffer if needed between calls to irWait(3IRAPI) since its
          contents are not preserved.

          The event structure sets the cid to the channel_id of the
          receiving channel if the event is generated via irPostEventC
          or is channel based.  Otherwise, cid is set to IRD_INVALID.

     EVENT
          The IRAPI library does not return any event to the applica-
          tion as a result of calling irPostEventC, irPostEventQ or
          irPostEvent.

          An IRE_EXTERNAL event occurs for the receiving process own-
          ing the channel or the queue.

     RETURN VALUE
          IRR_OK is returned if the request is successful.

          IRR_FAIL is returned if an error occurs.

     ERROR
          irError is set as follows if an error occurs:

          IRER_SYSERROR if a system or driver call failure occurs
          (check irSysError for additional information)

          IRER_INVALID if either channel_nbr or q_key is invalid or if
          the mbhdr structure elements irWhoTo or irChan are invalid

     EXAMPLE
          These functions can be used by a pair of applications to
          perform asynchronous operations.  Process A is a multi-
          threaded IRAPI application.  Process B is a database server
          process.  Process A may, on behalf of some caller, request a
          database transaction via irPostEventQ to the process B mes-
          sage queue. Process A is now free to service other channel's
          needs and eventually calls irWait(3IRAPI).  The details of
          the database transaction may be contained in the message
          text (struct msgBuf *)(event.event_text)->udata . Process B,
          waiting in irWait(3IRAPI), receives an IRE_EXTERNAL event.
          The event is processed and the results of the database tran-
          saction are transmitted to process A via some irPostEvent
          function.

          Processes A and B identify their queue keys when
          irRegister(3IRAPI) is called.  Process A identifies the
          queue key of process B via irGetQKey(3IRAPI).  Process B
          identifies process A's queue key when it receives an
          IRE_EXTERNAL event from process A and examines the morig
          element of the message buffer header.

     SEE ALSO
          irRegister(3IRAPI), irGetQKey(3IRAPI) and IrEVENTS(4IRAPI).

     VERSION
          This is version 11/25/02 of this man page.