ctaCreateContextEx

Creates a shared context, sets the context sharing mode, and returns a context handle (ctahd).

Prototype

DWORD ctaCreateContextEx ( CTAQUEUEHD ctaqueuehd, unsigned userid, char *descriptor, CTAHD *ctahd, char flags)

Argument	Description
ctaqueuehd	Handle returned by ctaCreateQueue.
userid	User-specified value repeated in all events returned for this context.
descriptor	Pointer to a string containing a service object descriptor or user-defined context name.
ctahd	Pointer to a returned context handle.
flags	Indicates the context sharing mode.

If CTA_CONTEXT_DECLARED_ACCESS is specified, the context is created in Declared Access mode. If the flag is not specified, the context is created in Common Access mode.

If CTA_CONTEXT_PERSISTENT is specified, the returned context is only destroyed if the last application calls ctaDestroyContext. Use this parameter to enable an application to reattach to a shared service mode context.

Return values

Return value	Description
SUCCESS
CTAERR_BAD_NAME	Specified descriptor is in use.
CTAERR_INCOMPATIBLE_SERVICES	On the server on which the context is created, at least one of the available services conflicts with the same service that is open on another server. A client application can use only one instance of a service at a time.
CTAERR_INVALID_CTAQUEUEHD
CTAERR_NOT_IMPLEMENTED	This function can not be used to create an in-process context. It can be used only to create contexts on local or remote instances of Natural Access Server.
CTAERR_NOT_INITIALIZED	Natural Access is not initialized. Call ctaInitialize first.
CTAERR_SVR_COMM	Server communication error.

Events

None.

Details

Applications use this function to create a shared context on a local or remote server and associate a userid and descriptor with it. The userid is returned in all events for this context. Both the userid and the descriptor also appear in trace records. The context name part of the descriptor is limited to 11 characters (not including a null terminator), and can be used by other applications to attach to the context.

After creating a context, you can open services on it, manage context parameters, and attach other contexts to it.

The following shared access modes are supported for contexts:

Access mode	Restricted
Common	Any service instances open on the context are immediately accessible through any contexts attached to it.
Declared	To access any service instances open on the context, each process using the shared context must open that service (with ctaOpenServices) on the context.

Note: This function can be used only by applications using local or remote instances of Natural Access Server (ctdaemon).

Refer to Sharing contexts for more information.

Example

typedef struct
{
    unsigned   line;
    unsigned   ag_board;
    unsigned   mvip_stream;
    unsigned   mvip_slot;
    CTAQUEUEHD ctaqueuehd;
    CTAHD      ctahd;
    VCEHD      demovh;
    SWIHD      demoswihd;
} DEMOCONTEXT ;

/* Create a Natural Access queue and a context on the default server */
void DemoCreateContext(unsigned line, DEMOCONTEXT *cx)
{
    char cxname[12];

    cx->line = line;

    /* Context name will be printed in all trace records
     * for this context
     */
    sprintf(cxname, "DEMOCX%04d", cx->line);

    /* Create queue and attach all service managers   */
    ctaCreateQueue( NULL, 0, &(cx->ctaqueuehd) );

    /* Create context named "cxname" in restricted
     * access mode
     */
    ctaCreateContextEx( cx->ctaqueuehd, line, cxname, & cx->ctahd,
                   CTA_CONTEXT_DECLARED_ACCESS );
}