Setting up the Natural Access environment

Before you can call functions from the CDI library, set up the Natural Access environment. Follow these steps:

• Initialize Natural Access

• Create event queues and contexts, and attach the contexts to an event queue

• Open services, including the CDI service, on each context.

Initializing Natural Access

Register services in the call to ctaInitialize by specifying the service and service manager names. Only the services initialized with ctaInitialize can be opened by the application. Service managers are dynamic link libraries (DLLs) in Windows.

Use CDIMGR, the CX board family service manager, in the call to ctaInitialize. Refer to the Natural Access Developer's Reference Manual for more information about using ctaInitialize.

Creating event queues and contexts

After initializing Natural Access, create the event queues and contexts. Create one or more event queues by calling ctaCreateQueue and specifying the service manager to attach to each queue. The CDI service manager is CDIMGR. When you attach or bind a service manager to an event queue, you make that service manager available to the event queue.

To create a context, call ctaCreateContext and provide the queue handle (ctaqueuehd) returned from ctaCreateQueue. All events for services on the context are received in the specified event queue.

ctaCreateContext returns a context handle (ctahd). The context handle is supplied by the application when invoking CDI service functions. Events communicated back to the application are also associated with the context.

Refer to the Natural Access Developer's Reference Manual for details on the programming models created by the use of contexts and event queues.

Opening services

To open services on a context, call ctaOpenServices. When opening a service on a context, you must specify information about the service and the service manager, and which resources to attach to the context.

The following table shows how to fill in this information to start CDI on a context:

Receiving CDI service events

When the CDI service manager is attached to an event queue, it opens the board driver and associates the muxable wait object returned by the driver open command with the event queue. When this wait object is signaled on receipt of events from the board, ctaWaitEvent processes the events through the CDI service and passes any event generated back to the calling function.

Events arrive in the form of the standard CTA event data structure (defined in ctadef.h):

typedef struct CTA_EVENT
{
    DWORD    id;                /* Event code (and source service ID)    */
    CTAHD    ctahd;             /* Natural Access context handle         */
    DWORD    timestamp;         /* Timestamp                             */
    DWORD    userid;            /* User ID (defined by ctaCreateContext) */
    DWORD    size;              /* Size of buffer if buffer != NULL      */
    void     *buffer;           /* Buffer pointer                        */
    DWORD    value;             /* Event status or event-specific data   */
    DWORD    objHd;             /* Service client side object handle     */
} CTA_EVENT;

This structure informs the application which event occurred on which context and includes additional information specific to the event.

The CTA_EVENT structure contains the following fields:

Linking with the CDI service

When building a Natural Access application that uses the CDI service, compile the program with cdidef.h and link to the cdiapi library (cdiapi.lib for Windows, libcdiapi.so for UNIX).

Refer to the Natural Access Developer's Reference Manual for more information about service implementation.