Setting up Natural Access applications

To set up a Natural Access application:

1. Initialize the Natural Access application.

2. Create event queues.

3. Create contexts.

4. Open services on each context.

To set up a second Natural Access application that will share a context with the first application:

1. Initialize the Natural Access application.

2. Create event queues.

3. Attach to the existing context that the applications will share.

For more information about Natural Access functions, refer to the Alphabetical function reference in this manual.

Initializing Natural Access applications

Use ctaInitialize to initialize Natural Access applications. When you initialize Natural Access applications, you can

• Register the services that are available to the application.

• Specify the parameter management strategy.

• Enable or disable tracing.

• Enable or disable the wait object notification event when the internal wait object list has changed.

Registering services

You can register services in one of the following ways:

• Invoke ctaInitialize and specify the service and service manager names of all the services you plan to use. The application can use only the services specified in the call to ctaInitialize.

• Invoke ctaInitialize, pass NULL for svcname, and pass a user-defined Natural Access configuration file name. cta.cfg is the default configuration file name if a file name is not specified. ctaInitialize looks in the [ctasys] header section of the configuration file for the list of service and service manager names.

Creating event queues

Applications can create one or more event queues by calling ctaCreateQueue. Specify the service managers to attach to each queue (if this is different than the defaults specified in the cta.cfg file). When you attach or bind a service manager to a queue, you make the service manager available to the queue. After the services are opened, the events generated by the managed services go to the attached queue.

An event queue handle (ctaqueuehd), returned from the ctaCreateQueue function, addresses the event queue. You supply the handle to retrieve events from the queue when calling ctaWaitEvent.

Applications can invoke ctaCreateQueue multiple times within a single process. Each invocation returns a unique queue handle.

After creating the event queue, Natural Access knows which services are available to the event queue (specified by the service managers). You can now create contexts on the event queue.

Creating contexts

To create contexts, call ctaCreateContext (or ctaCreateContextEx for shared contexts) and provide the queue handle (ctaqueuehd) that ctaCreateQueue returned. All events for services on the context are received in the specified event queue. ctaCreateContext returns a context handle (ctahd), which the application uses when invoking Natural Access functions. Events communicated back to the application are also associated with the context.

When creating a context, an application can specify a context name. The context name must be unique to the server on which it is created.

Optionally, you can supply a user-defined value (userid) when opening the context. Natural Access never interprets this value. The value is echoed back to the application in the event structure when events are delivered. It can be used (instead of the ctahd) to correlate the context with an application-specific data structure.

Setting the default Natural Access server

When creating a context, you can specify on which server it is created. If you do not specify a server, the context is created on a default Natural Access Server. To set the default server, edit the Natural Access configuration file (cta.cfg) as follows:

1. Set the DefaultServer keyword in the application section of the cta.cfg to one of the following locations:

DefaultServer = inproc | localhost | server_name

Note: If an existing application uses a configuration file that sets the CTAmode statement, CTAmode = 0 or CTAmode = 2 are interpreted as if the DefaultServer statement was set to inproc. CTAmode = 1 is interpreted as a setting of localhost.

2. Save the changes.

Supplying context object descriptors

Specify a context descriptor when creating a context and performing tracing. Each context is associated with a Natural Access Server (ctdaemon).

A context descriptor defines each context by associating a context name and the address of the server on which the context is created. To implement shared contexts, specify the context descriptor (descriptor) as a parameter when invoking ctaCreateContext or ctaCreateContextEx.

The following examples describe some of the valid descriptors:

• A context with a context name of ctx001 created in the process address space has the following context descriptor:

cta://inproc/ctx001

• A context created on a local server with a context name of line1 has the following context descriptor:

cta://localhost/line1

• A context with a context name of demo created on the remote server host.nmss.com has the following context descriptor:

cta://host.nmss.com/demo

Note: If a server address is not specified in the context descriptor, the context is created on the default server as specified in the cta.cfg file.

Refer to ctaGetObjDescriptor for more information on object descriptors.

Managing parameters

Natural Access manages parameters for services on a context basis. The context maintains a copy of the parameters for all services managed by the dispatcher and specified in the call to ctaInitialize. Parameters can be modified for a service not yet opened by ctaOpenServices as long as this service was registered in the call to ctaInitialize. This feature gives applications the flexibility to open and close services without affecting context parameter values. Refer to Opening services for more information.