ctaCreateContext

Creates a context or a void context handle for the specified server.

Prototype

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

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.

Return values

Return value	Description
SUCCESS
CTAERR_BAD_ARGUMENT	Invalid server address
CTAERR_BAD_NAME	Specified descriptor is in use.
CTAERR_NOT_INITIALIZED	Natural Access is not initialized. Call ctaInitialize first.
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_SVR_COMM	Server communication error.

Details

ctaCreateContext creates a context and (optionally) associates a userid and a 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 must be unique to the server on which it is created.

If the descriptor does not specify a server, the function uses the default Natural Access Server (ctdaemon) specified in cta.cfg. Use ctaSetDefaultServer to override the default server.

The following table shows some examples of created contexts based on the location of Natural Access Server in relation to the application:

Location	Context example	Description
In-Process	test_context	Creates a context named test_context that is specific to the application and cannot be shared.
Local	svr_context	Creates a context named svr_context on a local server.
Remote	localhost/srv_context	Creates a context named srv_context on the local server.
Remote	test_context	Creates a context named test_context on the remote server.

When ctaqueuehd is NULL_CTAQUEUEHD, ctaCreateContext interprets descriptor as a server descriptor with a host address. If this parameter is a valid Natural Access Server descriptor, ctaCreateContext returns the void context handle containing the address of the Natural Access Server (ctdaemon) specified by descriptor. Otherwise, the CTAERR_BAD_NAME error code is returned.

The descriptor parameter specifies the server for which the void context handle is created. The void context handle refers only to the server on which the commands are executed and not to any real context object. When descriptor is the string

cta://localhost

the returned void context handle corresponds to the local server.

When descriptor is the string

cta://inproc

the returned void context handle corresponds to the process address space.

For more information on descriptors, see ctaGetObjDescriptor.

After creating a context, you can open services on it and manage context parameters. Refer to Creating contexts for more information.

Note: Use ctaCreateContextEx to create shared contexts. For more information, see Sharing contexts.

Example 1

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

/*             Creates a Natural Access context with its own queue, storing */
/*             in the context (cx) that was created by the caller.          */

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 with line number as userid*/
    ctaCreateContext( cx->ctaqueuehd, line,
                      cxname, &(cx->ctahd) );
}

Example 2

/*Creates one Natural Access context in the process server and one Natural   */
/*Access context on a local server.                                          */

void DemoCreateContext(
     unsigned userid,
     CTAQUEUHD *ctaqueuehd,
     CTAHD *ctahd_library,
     CTAHD *ctahd_server)
{
     /* Context name for in-process server */
     char cxname_lib[] = "DEMOCX0";
     /* Context name for local server  */
     char cxname_svr[] = "localhost/DEMOCX1";

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

     /* Create a Natural Access context in the process server   */
     ctaCreateContext(*ctaqueuehd, userid, cxname_lib, ctahd_library);

     /* Create a Natural Access context on local server    */
     ctaCreateContext(*ctaqueuehd, userid, cxname_svr, ctahd_server);
}

Example 3

/* Retrieves global parameter values from the remote server*/
void DemoGetParms(
     unsigned parmid,
     void *buffer,
     unsigned size)
{
     CTAHD void_ctahd;
     /* Server name descriptor  */
     char server_desc[] = "host.nmss.com:2244";

     /* Create a void context handle */
     ctaCreateContext(NULL_CTAQUEUEHD, 0, server_desc, &void_ctahd);

     /* Retrieve parameter values from host.nmss.com server*/
     ctaGetParms (void_ctahd, parmid, butter, size);
}