(Page 1 of 1 in this chapter)

Chapter 3

Migration from AG Access

: 3.1 Introduction
: 3.2 AG Access Functions Replaced in CT Access
: 3.3 Ports/Drivers versus Queues/Contexts
: 3.4 Event Retrieval
: 3.5 Passing Events Between Threads
: 3.6 ADI Service Opened in Driver Only Mode
: 3.7 Parameter Management
: 3.8 Voice Message Service
: 3.9 Header Files
: 3.10 Library Files

3.1 Introduction

If you are migrating from an existing AG Access application, you may be able to directly substitute CT Access functions for AG Access functions, subject to these considerations: AG Access functions replaced in CT Access Ports and drivers versus queues and contexts Event retrieval Passing events between threads ADI service opened in driver only mode Parameter Management Voice Message service Header files Note: It is important that you read Chapters 2, 3, and the ADI chapters of the CT Access Developer's Reference Manual prior to reading this AG Access chapter. The developer's manual contains concepts and terms that are essential to understanding the CT Access terminology in this chapter.

3.2 AG Access Functions Replaced in CT Access

The following AG Access functions are replaced in CT Access:

If you use...

Replace With...

adiCloseDriver

See Section 3.3.

adiClosePort

See Section 3.3.

adiConfigParm

ctaSetParmByName

adiFetchAndProcess

ctaWaitEvent (See Section 3.4.)

adiGetErrorText

ctaGetText

adiGetEventText

ctaGetText

adiGetParmByName

ctaGetParmByName

adiGetParmInfo

ctaGetParmInfo

adiGetParms

ctaGetParms

adiGetVersion

ctaGetVersion

adiOpenDriver

See Section 3.3.

adiOpenPort

See Section 3.3.

adiSendAGMessage

None.

adiGetAGMessage

None.

adiLoopBackEvent

ctaQueueEvent

adiRetractAGBuffer

None.
Refer to the CT Access Developer's Reference Manual for more information about the CT Access functions.

If you use...	Replace With...
adiCloseDriver	See Section 3.3.
adiClosePort	See Section 3.3.
adiConfigParm	ctaSetParmByName
adiFetchAndProcess	ctaWaitEvent (See Section 3.4.)
adiGetErrorText	ctaGetText
adiGetEventText	ctaGetText
adiGetParmByName	ctaGetParmByName
adiGetParmInfo	ctaGetParmInfo
adiGetParms	ctaGetParms
adiGetVersion	ctaGetVersion
adiOpenDriver	See Section 3.3.
adiOpenPort	See Section 3.3.
adiSendAGMessage	None.
adiGetAGMessage	None.
adiLoopBackEvent	ctaQueueEvent
adiRetractAGBuffer	None.

3.3 Ports/Drivers versus Queues/Contexts

In CT Access, the AG Access concepts of ports and drivers are replaced with CTA contexts and queues.
In AG Access, you first open the AG driver with adiOpenDriver, which returns two handles; a MUX_HANDLE to sleep on waiting for the driver to request servicing, and a driver handle for adiFetchAndProcess to actually pull events from the driver into AG Access.
In CT Access, you first create a queue with ctaCreateQueue, which returns a CTAQUEUEHD. If the ADI service is part of your application space (see ctaInitialize), then the equivalent of adiOpenDriver will happen inside of CT Access. The CTAQUEUEHD is passed to ctaWaitEvent to wait for, and retrieve, events. This is similar to adiFetchAndProcess.
In AG Access, ports are represented by the context handle, CTAHD. Prior to AG Access 1.2, this datatype was called PORTHD. CTAHD represents both an application processing context and an AG port (processing resources). As shown in Figure 5, the application gets a port using adiOpenPort. In CT Access, this is achieved in two steps: creating the context (ctaCreateContext) and attaching processing resources (ctaOpenServices). To obtain the equivalent of an AG Access port, the ADI service should be specified as an argument to ctaOpenServices.

Figure 5. Obtaining a Context Handle

3.4 Event Retrieval

AG Access retrieves board events from the AG driver when the application invokes adiFetchAndProcess, and optionally returns an event to the application. adiFetchAndProcess should be called after the application is awoken while sleeping on the MUX_HANDLE returned from adiOpenDriver. If the board event is consumed by the library, an event value of zero (0) is returned.
In CT Access, there are two models for retrieving events. In the first model, the two steps of sleeping and fetching are taken care of by ctaWaitEvent. To retrieve events, call ctaWaitEvent with the CTAQUEUEHD, and event structure to fill, and a timeout value. If no events are waiting, the function blocks for the specified timeout waiting for an event to appear. If one does not, CTAEVN_WAIT_TIMEOUT event is returned in the event structure.
In the second model, sleeping occurs outside of CT Access. CT Access allows you to integrate application-specific wait objects with CT Access wait objects. The following functions allow you to establish whether wait objects will be managed by your application or managed by CT Access:

Function

Description

ctaQueryWaitObjects

Returns an operating system specific array of wait objects that CT Access is managing internally. This function is used when the application manages wait objects.

ctaRegisterWaitObject

Allows the application to register a wait object with CT Access. This function is used when CT Access manages wait objects.

ctaUnregisterWaitObject

Allows the application to unregister a previously registered wait object. This function is used when CT Access manages wait objects.
Refer to the CT Access Developer's Reference Manual for more information about wait objects in CT Access.
Figure 6 shows how events are retrieved in AG Access and in CT Access. Figure 6. Event Retrieval in AG Access and in CT Access

Function	Description
ctaQueryWaitObjects	Returns an operating system specific array of wait objects that CT Access is managing internally. This function is used when the application manages wait objects.
ctaRegisterWaitObject	Allows the application to register a wait object with CT Access. This function is used when CT Access manages wait objects.
ctaUnregisterWaitObject	Allows the application to unregister a previously registered wait object. This function is used when CT Access manages wait objects.

3.5 Passing Events Between Threads

To pass events between different threads, adiLoopBackEvent is replaced with ctaQueueEvent. ctaQueueEvent is called with an event structure and sends the event to the queue associated with the CTA context in the event structure.

3.6 ADI Service Opened in Driver-Only Mode

There are some functions that do not require board resources. If you need to use these functions and do not have a CT Access context with board resources, you can create a context and attach the service in the driver-only mode.
When calling ctaOpenServices, the board field in the CTA_MVIP_ADDR parameter structure should be set to ADI_AG_DRIVER_ONLY. In this mode, you are not specifying a channel on an AG board. You are only communicating with the driver.
These functions include adiGetBoardInfo, adiGetBoardSlots, adiGetEEPromData, and adiGetTimeStamp. These functions may also be used on contexts with board resources.

3.7 Parameter Management

CT Access provides an extra level of parameter management that must be taken into consideration when migrating from AG Access. CT Access provides per- context parameters in addition to global default parameters. As with AG Access, global default parameters are either stored in each process (process global defaults) or are shared among processes in a system (system global defaults) if the daemon is running.
Since AG Access does not have the concept of per-context parameters, the values retrieved by calls to parameter functions (adiGetParms, adiGetParmByName, adiConfigParm) always reflect the process or system global default values. If a value is changed in the addaemon, all applications that were started after the daemon will reference the modified parameter value the next time a parameter function is called.
In CT Access, if a value is changed in the ctdaemon, CTA contexts created before the value was changed will not have the new parameter value. All calls to parameter functions (ctaGetParms, ctaGetParmByName, ctaSetParmByName) referencing the CTA context handle will return the context parameter values that were copied when the context was created, including any changes that were made on the context parameters by ctaSetParmByName. To update the values to reflect the current global default parameters, ctaRefreshParms must be called. This restores any per-context values that were modified after context creation.
In CT Access, when NULL is passed to an API function in place of a parameter structure, the values used by the function will be those stored in the context. AG Access API functions, on the other hand, retrieve the parameter values from the process or system global defaults. To retrieve or modify per context parameters in CT Access, pass a valid CTA context handle to the parameter management functions. To retrieve or modify global default parameters, pass NULL_CTAHD to these functions. In AG Access, there are no context parameters. Parameter functions always retrieve or modify process or system global defaults.
The advantage of having per context parameters is that each context within the same process can have a different parameter profile and will behave differently based on these parameters. It is not necessary to retrieve and modify every API parameter structure or to create separate processes with different parameter values loaded in order to achieve modification of call processing behavior on a per context basis.
In CT Access, the choice of which global defaults to use is made when calling ctaInitialize. Set the parmflags field in the CTA_INIT_PARMS structure to CTA_PARM_MGMT_SHARED to use system global defaults or to 0 to use process global defaults. If system global defaults is chosen and the ctdaemon is not running, an error will be returned. In contrast, AG Access automatically uses system global defaults if the addaemon is running or process global defaults if it is not.

3.8 Voice Message Service

The most convenient way to program play and record functions in applications is using the Voice Message service since it provides disk management with the player/recorder functionality. To use the Voice Message service with the ADI service playing/recording functions, open both services on the same CTA context.
For more information on the CT Access Voice Message service, refer to the CT Access Developer's Reference Manual.
When using the Voice Message service, you do not call the ADI playing/recording functions directly. The Voice Message service will call the functions when needed.
If you want to create an application using your own disk management functions, you may call the ADI functions directly.
adiPlayAsync, adiRecordAsync, adiSubmitPlayBuffer, and adiSubmitRecordBuffer do not have any corresponding Voice Message service functions but are supported in CT Access.

3.9 Header Files

AG Access applications include adi.h which also includes adidef.h.
CT Access applications include ctadef.h, which also includes ctaerr.h. When using the ADI service, the application also includes adidef.h.

3.10 Library Files

AG Access applications link with adi.lib (Windows NT) or libadi.so (UNIX).
CT Access applications using the ADI service link with cta.lib and adiapi.lib (Windows NT) or libcta.so and libadiapi.so (UNIX).
When installing AG Access, both adi and adimgr versions of the library are installed. If you inadvertently link the ADI service when building a CT Access application, the link will succeed. However, runtime errors will occur. For example, adiStartProtocol will return ADIERR_INVALID_QUEUEID.

(Page 1 of 1 in this chapter)

tech_support@nmss.com