NAME
          irInitGroup - initialize a channel and obtain channel id
          from an equipment group

     SYNOPSIS
          #include <irapi.h>

          int irInitGroup (int equip_grp, channel_id *cid_ptr, int
          return_mode, int tag);

     DESCRIPTION
          The irInitGroup function initializes a channel in equipment
          group equip_grp.

          Except upon failure, this function sets *cid_ptr to the
          channel_id that is to be used by most of the other functions
          when referencing the channel.

          return_mode indicates how the caller of the function expects
          channel allocation to be handled.  Allocation of channels
          behaves much like the allocation of other resources.  The
          behavior determined by return_mode is summarized as follows:

          IRD_BLOCKFOREVER
                         Indicates irInitGroup should return
                         IRR_PENDING if the channel cannot be immedi-
                         ately allocated.  When IRR_PENDING is
                         returned, the calling application should be
                         prepared to deal with a subsequent
                         IRE_CHAN_GRANT event.

          Any positive integer N
                         Indicates irInitGroup should return
                         IRR_PENDING if the channel cannot be immedi-
                         ately allocated.  When IRR_PENDING is
                         returned, the calling application should be
                         prepared to deal with a subsequent
                         IRE_CHAN_GRANT event or a subsequent
                         IRE_CHAN_DENY event after N milliseconds.

          tag is returned to the application with the subsequent
          IRE_CHAN_GRANT or IRE_CHAN_DENY event.

          irInitGroup selects as negotiable channels in equip_grp only
          if they are currently owned by the default owner (usually
          the Application Dispatch process).  The library determines
          the state of the channel and releases it to the requesting
          application if the channel is not busy.

          If no negotiable channels are found, the first channel in
          equip_grp freed by some process is allocated to the reques-
          ter.
          Channels are allocated to requesters on a first-come-first-
          served basis.  Channel requests made via irInit(3IRAPI) have
          priority over those made via irInitGroup.

          The equipment group equip_group can be any of the adminis-
          terable equipment groups 0 to 31, or one of the two follow-
          ing abstract equipment groups.  IRD_REAL_CHANS represents
          any of the real channels in the system and IRD_VIRTUAL_CHANS
          represents any of the virtual channels in the system.

     EVENT
          The IRE_CHAN_GRANT event occurs if the return value is
          IRR_PENDING.

          The IRE_CHAN_DENY event occurs if a channel from equip_grp
          cannot be granted within the time specified in the
          return_mode argument.  The application should discontinue
          use of the channel_id after receiving the IRE_CHAN_DENY
          event.

     RETURN VALUE
          IRR_PENDING is returned if a channel from equip_grp has not
          yet been released by the prior application.  The *cid_ptr is
          valid, but no other functions may be called until the
          IRE_CHAN_GRANT event is received.  This event indicates a
          state change from IRS_INIT_PENDING to IRS_IDLE.

          IRR_FAIL is returned if an error occurs.

     ERROR
          irError is set as follows if an error occurs:

          IRER_INVALID if equip_grp specifies an invalid equipment
          group, return_mode is invalid, or cid_ptr is NULL

          IRER_NOREGISTER if the process has not previously called
          irRegister(3IRAPI)

          IRER_RESOURCEBUSY if return_mode is IRD_IMMEDIATE and there
          is no channel immediately available

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

     EXAMPLE
          The following examples shows how to initialize a group.
          Note the use of "&" before the cid argument to irInitGroup
          in the following example:

              int equip_grp;
              channel_id cid;
              int retval;
              int tag;

                 ...

              retval = irInitGroup(equip_grp, &cid, IRD_BLOCKFOREVER, tag);
              switch (retval) {
                  case IRR_FAIL:
                       <report failure as appropriate>
                       break;
                  case IRR_PENDING:
                       <wait for IRE_CHAN_GRANT or IRE_CHAN_DENY event>
                       break;
              }

                 ...

     SEE ALSO
          irDeinit(3IRAPI), irReturn(3IRAPI), irInit(3IRAPI),
          IrPARAMETERS(4IRAPI), IrEVENTS(4IRAPI).

     CAVEAT
          Note that it is possible to configure a system where incom-
          ing and outgoing calls occur over the same set of ports.  In
          this situation, an application can get a pseudo-glare condi-
          tion:  an outbound application has acquired a channel, but
          has not yet initiated an outbound call.  In this interval, a
          new call can enter the system.  The ``right'' behavior for
          an application is release the channel and allow the incoming
          call to proceed.  The application should irExec(3IRAPI) the
          default owner on the channel, which is AD by default.  The
          default owner is responsible for dispatching a new applica-
          tion.  Alternatively, applications can use
          irInitCall(3IRAPI)  and  irInitCallGroup(3IRAPI) to manage
          glare conditions automatically.

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