# 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.

#### See also

ctaAttachContext, ctaDestroyContext, ctaOpenServices

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