Setting up the Natural Access environment

Before you can call functions from the ADI library, the application must initialize Natural Access and open the ADI service. Application setup for Natural Access consists of the following steps:

1. Initialize Natural Access for the process.

2. Create event queues and contexts.

3. Open services on each context.

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

1. Initialize the Natural Access application.

2. Create event queues.

3. Attach the application to the existing context.

Initializing Natural Access

Initialize Natural Access by calling ctaInitialize and specifying the service and service manager names. Service managers are dynamic link libraries (DLLs) in Windows and shared libraries in UNIX.  Only the services initialized in the call to ctaInitialize can be opened by the application.

Use one of the following service managers in your call to 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 managers to attach to each queue. The ADI service manager is ADIMGR (or QDIMGR). When you attach a service manager to a queue, you make that service manager available to the queue.

Create a context by calling ctaCreateContext and providing the queue handle (ctaqueuehd) that was returned from ctaCreateQueue. All events for services on the context are received in the specified event queue. ctaCreateContext returns a context handle (ctahd), which the application supplies when invoking ADI 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

Open services on a context by calling ctaOpenServices. When opening the ADI service, specify a context, a specific board, a timeslot, and a mode. The parameter structure CTA_MVIP_ADDR contains the following fields: board, bus, stream, timeslot, and mode. For all boards, bus and stream can be 0.

The board field specifies the board number you want to use. Refer to the system configuration file for the board keyword identifying each board in the system. See the NMS OAM System User's Manual for more information.

The timeslot and mode fields are used to calculate which timeslots to allocate to the service. The timeslot specifies the base timeslot, and the mode dictates how many timeslots are allocated.

The mode field can be one of the following values:

Use the demonstration program ctatest to verify that the ADI service is properly installed. Refer to the Natural Access Developer's Reference Manual for more information about ctatest.

When you open the ADI service, specify a DSP address. A DSP address is specified as a timeslot. Bus and stream fields are 0 (zero). The following table shows valid timeslot values for AG and CG Series boards:

When the ADI 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 ADI service and passes any event generated back to the calling function.

Using the ADI service in driver-only mode

To access only the board driver, use the special board argument ADI_AG_DRIVER_ONLY in place of a real board number in the CTA_MVIP_ADDR structure. This argument permits the application to use a virtual port. The application can use the following functions on a context in driver-only mode, since they do not require physical board resources:

• adiGetBoardInfo

• adiGetBoardSlots

• adiGetBoardSlots32

• adiGetTimeStamp

• adiGetEEPromData

Note: All other functions that take a context handle (ctahd) require board-level resources.

Linking with the ADI service

The ADI service contains two components, the ADI service interface and the ADI service implementation. When building a Natural Access application that uses the ADI service, link to adiapi.lib (under UNIX, libadiapi.so).

For existing applications, modify the make files to link with adiapi.lib (libadiapi.so). Since earlier applications using the ADI service linked to adimgr.lib (under UNIX, libadimgr.so), it is included only for backward compatibility.

See the Natural Access Service Writer's Manual for more details about service implementation.