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 user-defined context name and (optionally) the address of the server on which the context is created.

ctahd

Pointer to a returned context handle.

flags

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 destroyed only 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

An invalid queue handle was passed as an argument to a function, or the queue was destroyed by another thread.

CTAERR_NOT_IMPLEMENTED

This function cannot 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.


Details

ctaCreateContextEx creates a shared context on a local or remote server and associates a userid and descriptor with it. The userid is returned in all events for this context. Both the userid and the descriptor also display 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

Description

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.

See also

ctaAttachContext

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 );
}