ctaCreateQueue

Creates an event queue and returns a queue handle.

Prototype

DWORD ctaCreateQueue ( char *mgrlist[], unsigned nmgrs, CTAQUEUEHD *ctaqueuehd)

Argument	Description
mgrlist	Pointer to a list of service managers to attach to the queue. The name of each service manager must match one of the names specified with ctaInitialize.
nmgrs	Number of service managers in mgrlist.
ctaqueuehd	Pointer to a returned queue handle.

Return values

Return value	Description
SUCCESS
CTAERR_ALREADY_DEFINED	There is a duplicate service manager in mgrlist.
CTAERR_BAD_ARGUMENT	Invalid ctaqueuehd is NULL.
CTAERR_NOT_FOUND	One or more of the service managers in mgrlist is not found.
CTAERR_NOT_INITIALIZED	Natural Access is not initialized. Call ctaInitialize first.
CTAERR_DRIVER_OPEN_FAILED	The ADI service driver open failed.

A service-manager-specific error, such as:

Return value	Description
CTAERR_DRIVER_OPEN_FAILED	The ADI service driver open failed.

Events

None.

Details

This function creates an event queue. It returns a handle (ctaqueuehandle) that is used to reference the queue. When the application creates a context, the context is associated with this queue.

If mgrlist is NULL, then all service managers registered with ctaInitialize are attached to the queue.

Use ctaWaitEvent to retrieve events. After creating the event queue, applications that are managing wait objects must set the CTA_NOTIFY_UPDATE_WAITOBJS flag in the ctaflags field of the CTA_INIT_PARMS structure in ctaInitialize. Call ctaQueryWaitObjects after calling ctaCreateQueue.

Refer to Creating event queues for more information.

Note: When running on a local or remote server, the cta.cfg file must contain a list of all service and service manager pairs that are expected to be used by any and all applications. Failure to do so will result in CTAERR_NOT_FOUND errors during your call to ctaOpenServices or ctaInitialize.

Example

DEMOCONTEXT *Cxarray[100];
/* Setup a queue and multiple contexts for a state machine demo. */
void DemoSetup(CTAQUEUEHD *ctaqueuehd)
{
  unsigned   i;
  char      *mgrlist[] = { "ADIMGR", "VCEMGR", "SWIMGR" };

/* Create the Natural Access application queue and attach specified managers */
  ctaCreateQueue( mgrlist,
                  sizeof(mgrlist)/sizeof(mgrlist[0]),
                  ctaqueuehd);

  for (i=0; i < 100; i++)
  {
      char cxname[12];
      DEMOCONTEXT *cx = (DEMOCONTEXT *) malloc ( sizeof(DEMOCONTEXT) );

      cx->line       = i;
      cx->ctaqueuehd = *ctaqueuehd;

      /* Context name will be printed in all trace records for this context */
      sprintf( cxname, "DEMOCX%04d", i );
      /* Create context with index of demo context as userid */
      ctaCreateContext( cx->ctaqueuehd, i, cxname, &(cx->ctahd) );

      Cxarray[i] = cx;
  }
}