(Page 1 of 1 in this chapter)

Chapter 2

Migration from ME/2/X

2.1 Introduction
2.2 Channel Management
2.2.1 Programming Models
2.2.2 ME/2/X Channels and CTA Contexts
2.2.3 Communicating Between Contexts
2.2.4 Handling Events
2.2.5 Monitoring Status and Tracing
2.3 Line Management
2.3.1 Getting a Line
2.3.2 Detecting Line Hang-Up
2.3.3 Handling Multiple Lines
2.3.4 Controlling Loop Start Lines
2.4 Trunk Management
2.4.1 ADI Service Call Control
2.4.2 Starting Trunk Control Protocols
2.4.3 Handling Incoming Calls
2.4.4 Handling Outbound Calls
2.4.5 Entering Conversation States
2.4.6 Hanging Up the Call
2.4.7 Equating ME/2/X and CT Access Functions and Events
2.4.8 Equating ME/2/X TCPs with CT Access TCPs
2.5 Parameter Management
2.5.1 CT Access Parameters
2.5.2 Equating ME/2/X and CT Access Functions
2.6 VOX File Functions
2.6.1 Establishing the Current Message and Current Position
2.6.2 Setting the Insert Mode
2.6.3 Seeking Past Message Boundary
2.6.4 Accessing Non-Existent Messages
2.7 Voice Functions
2.7.1 Playing and Recording Memory
2.7.2 Playing and Recording Flat Files
2.7.3 Playing and Recording Lists
2.8 Prompt Builder
2.9 Digit Collection
2.9.1 Digit Queue
2.10 Tone Detection and Generation
2.11 DTMF Detection
2.12 Timer
2.13 Error Handling
2.14 Other Differences
2.14.1 Local Phone Functions
2.14.2 Stop Function
2.14.3 Status Monitor Functions
2.14.4 Board Numbers
2.14.5 Database Management Functions
2.14.6 Time Stamped Events
2.15 Table of Function Equivalents

2.1 Introduction

If you are migrating from an existing ME/2/X application, you may be able to directly substitute CT Access functions for ME/2/X functions, subject to considerations for each of the following:

For a list of the ME/2/X functions and the equivalent CT Access functions, refer to Section 2.15.

Note: It is important that you read Chapters 2, 3, and 5 of the CT Access Developer's Reference Manual prior to reading this chapter. The developer's manual contains concepts and terms that are essential to understanding the CT Access terminology in this chapter.

2.2 Channel Management

The ME/2/X Channel functions manage voice channels, events, and a status monitor.

Considerations for migrating are:

2.2.1 Programming Models

The ME/2/X programming model requires a separate process for each line. If you plan to follow the same programming model in CT Access, each process will have one CTA context and one CT Access event queue.

A CTA context organizes services and accompanying resources around a single processing context. A CTA context usually represents an application instance controlling a single telephone call. Some contexts are not associated with a call; an application performing voice conversions does not require a telephone line.

A service in CT Access provides a group of telephony functions. Services are opened on a CTA context and maintain their context information for each CTA context. Opening a service with hardware (e.g., AG resource board), gives you physical access (similar to a line in ME/2/X).

A CT Access event queue is the communication path from the service to the application. The service generates events indicating certain conditions or state changes. The application retrieves the events from the event queue. In ME/2/X, the queue is implicit to the process and only one line can be opened on it.

An event queue with a CTA context is equivalent to a channel in ME/2/X.

Refer to the CT Access Developer's Reference Manual for more information on CTA contexts, services, and event queues.

CT Access can support programming models to suit most application requirements. Both single-threaded and multi-threaded operating systems are supported.

Refer to Chapter 3 in the CT Access Developer's Reference Manual for examples of different programming models.

2.2.2 ME/2/X Channels and CTA Contexts

Before a line can be requested or any other functions can be used in ME/2/X, the application must request a channel with Me2RequestChannel.

As shown in Figure 1, a channel in ME/2/X is equivalent to a CT Access event queue with a single CTA context.

Figure 1. An ME/2/X Channel Versus a CT Access Context



Use ctaCreateQueue to create an event queue. This function attaches service managers (available libraries) to a CT Access queue.



Use ctaCreateContext to create a CTA context which returns a CTA context handle.



When the application requests a channel in ME/2/X, it supplies a name to the Channel Manager. ctaCreateContext also takes an application name.






2.2.3	 Communicating Between Contexts





In ME/2/X, you can send messages across channels using Me2SendEvent. Similar to Me2SendEvent, ctaQueueEvent can be used to send events to other contexts. However, ctaQueueEvent requires that destination contexts be in the same application process. Therefore, if you create application contexts in their own threads within a single process, you can accomplish a similar model. If you follow the ME/2/X one-port-per-process, you will not be able to send events between contexts in CT Access.






2.2.4	 Handling Events





In ME/2/X, events are controlled with two separate functions. Me2WaitEvent waits for a specified amount of time for an event to appear on the event queue. Me2GetEvent gets an event from the event queue.



CT Access provides a single function (ctaWaitEvent) which waits for an event and retrieves the event.



To facilitate the application waiting on events from non-CT Access devices, CT Access also provides functions to allow the application to wait/sleep and call ctaWaitEvent as necessary. Refer to the CT Access Developer's Reference Manual for more information.


 



Figure 2.	 Event Handling in ME/2/X and in CT Access






2.2.5	 Monitoring Status and Tracing





When the application requests a channel in ME/2/X, it supplies a name to the Channel Manager. This information is included in all status events which are generated by this channel, allowing a generic status monitor or call statistics monitor to report which applications are in use without actually knowing anything about them (e.g., the spv utility). In addition, ME/2/X has a low level event trace utility called Me2Trace.



In CT Access, the name is supplied to ctaCreateContext.



In CT Access, tracing is enabled in ctaInitialize. There are two tracing functions.





 





 Function



 Description




 ctaLogTrace



 Allows you to log errors, warnings, or informational messages to the CT Access trace log.




 ctaSetTraceLevel



 Sets the trace mask for a service on the specified CTA context.


















Currently, the only access to trace information is via the CT Access daemon process (ctdaemon). Refer to the CT Access Developer's Reference Manual for more information.






2.3	 Line Management





The ME/2/X Line manager manages physical lines, logical lines and line groups, and performs line arbitration. Line arbitration is automatically choosing from a group of lines the next line for an incoming call or the next line for an outgoing call.


Note:  ME/2 has line groups and line arbitration. ME/X does not have these features.


In ME/2/X, lines are identified by a number. The logical line number in ME/2/X corresponds to an MVIP address specified in the AG configuration file.


 



Additional considerations for migrating are:






2.3.1	 Getting a Line





There are two approaches for obtaining a line in ME/2/X. One is line arbitration (ME/2 only) and the other is directly specifying a line number.



There is no line arbitration in CT Access. Therefore, there is no equivalent function for Me2RequestLine. You must specify the exact line address. To get a line in CT Access, specify the board, stream, and timeslot of DSP resources connected to a line interface.



To obtain a loop start line in ME/2/X, use Me2GrabLine, which implicitly starts the loop start protocol. For other line interfaces, Me2GrabTrunkLine is used. Me2GrabTrunkLine is followed by Me2TrunkStart to initiate the protocol.



CT Access does not distinguish loop-start from other protocols. The actual line is acquired when opening the ADI service with ctaOpenServices and the protocol is started with adiStartProtocol.


 



Figure 3.	 Obtaining a Line in ME/2/X and in CT Access




Me2GetLine gives you the current line number for the channel. In CT Access, adiGetContextInfo gives you the current MVIP address.






2.3.2	 Detecting Line Hangup





To monitor for call hang-up, the ME/2/X loop detector detects loop current events (LPCURON, LPCUROFF). In CT Access, the loop start protocol generates a disconnect event (ADIEVN_CALL_DISCONNECTED). Loop start is built into ME/2/X. However, in CT Access, loop start is just another telephony protocol and has no special interface.


Note:  In ME/2/X, trunk manager protocols report disconnect with a LPCUROFF event. Refer to Section 2.4 for more details.





2.3.3	 Handling Multiple Lines





Me2KeepAlive allows a line to be released without hanging up the call. This allows another application to open the line and continue processing the call. CT Access does not have an equivalent function. However, CT Access does allow you to have multiple lines handled by one application. CT Access allows multiple threads and lets you pass control among the threads.



Grabbing and releasing an ME/2/X line is equivalent to opening and closing the ADI service in CT Access. Refer to the opening services (ctaOpenServices) information in the CT Access Developer's Reference Manual.






2.3.4	 Controlling Loop Start Lines





In ME/2/X, Me2SetLineMode, Me2Call, Me2Dial, and Me2CallProgress, along with loop current and ring events, are used to control loop start lines. In ME/2/X, loop start lines do not require the trunk manager.



In CT Access, you control loop start lines using a loop start protocol. Loop start is just another trunk protocol with exactly the same interface as other protocols.






2.4	 Trunk Management





The ME/2/X Trunk Manager contains functions that manage protocols from an application. Protocols are implemented as Trunk Control Programs (TCPs) executing on the board. Protocols include wink start (for DID/DNIS trunks) and MFC-R2 (for E1 trunks), but are not used for loop start lines.



Additional considerations for migrating are:






2.4.1	 ADI Service Call Control





The ME/2/X Trunk Manager equates to the call control functionality of the ADI service. Refer to the CT Access Developer's Reference Manual for more information.



ME/2/X makes a special consideration for non-loop start lines and calls them trunk lines.



The ME/2/X functions Me2GrabTrunkLine and Me2TrunkStart are the equivalent in CT Access of opening an ADI service on a CTA context (ctaOpenServices) and starting a protocol (adiStartProtocol).



Both ME/2/X and the ADI service use TCPs which are downloaded to the board and are specified as TCP files in the AG configuration file. ME/2/X Trunk Manager TCPs perform call set-up for either inbound or outbound calls and then exit. ADI TCPs run at all times. ADI also supports two way trunks.



The following are examples of ADI TCPs:






2.4.2	 Starting  Trunk Control Protocols





In ME/2/X, the trunk control program is started with Me2TrunkStart and is acknowledged with the TRUNKBEG event. The equivalent in CT Access is adiStartProtocol and is acknowledged with the event ADIEVEN_STARTPROTOCOL_DONE and the event value of CTA_REASON_FINISHED.



Each network protocol is coded in a Trunk Control Program (TCP). The protocol selected must have been downloaded at system initialization time. The agmon program downloads all TCPs specified in the AG configuration file.


 






2.4.3	 Handling Incoming Calls





Depending on the protocol, address information may be supplied with an incoming call in the form of DTMF/MF/pulsed digits.



In ME/2/X, the incoming digits are received as individual digit events after seizure and appear on the digit queue. All digits are in the queue by the time the TRUNKCALLRECD event is received. After receiving TRUNKCALLRECD, call Me2TrunkAnswer or Me2TrunkTone to answer or reject the call.



In CT Access, the application calls adiGetCallStatus to obtain any incoming digits after receiving the ADIEVN_INCOMING_CALL event. After receiving ADIEVN_INCOMING_CALL, the application calls adiAnswerCall or adiRejectCall. By default, there are no individual digit events during call setup. 






2.4.4	 Handling Outbound Calls





In ME/2/X, Me2TrunkDial dials an outgoing call. The protocol stops as soon as the dialing is finished. Use Me2CallProgress to monitor for voice and tones. In CT Access, adiPlaceCall automatically dials and performs call progress analysis.






2.4.5	 Entering Conversation States





When you enter the conversation state in ME/2/X, you receive TRUNKDONE and the protocol is no longer active.



In CT Access, you receive ADIEVN_CALL_CONNECTED and the protocol continues to be active.






2.4.6	 Hanging Up the Call





In ME/2/X, if the remote party hangs up first, ME/2/X delivers the LPCUROFF event. In CT Access, you receive the ADIEVN_CALL_DISCONNECTED event.



When the application wants to hang up in ME/2/X, the application restarts the protocol (Me2TrunkStart) which results in a hang-up.



In CT Access, the protocol is always running. When you want to hang up, call adiReleaseCall. The ADIEVN_CALL_RELEASED event indicates that both sides have hung up.






2.4.7	 Equating ME/2/X  and CT Access Functions and Events





The following table presents the major functionality performed by trunk management and the functions you use in ME/2/X and the equivalent functions in CT Access. The ME/2/X functions are shown for both the trunk manager and for loop-start.





 





 Functionality



 ME/2/X Trunk Manager Function



 ME/2/X Using Loop Start



 CT Access Function




 Obtain a line and start a protocol



 Me2GrabTrunkLine*
and
Me2TrunkStart



 Me2GrabLine*



 ctaOpenServices and adiStartProtocol




 Place a call



 Me2TrunkDial
and
Me2CallProgress



 Me2Call, or
Me2Dial and Me2CallProgress



 adiPlaceCall




 Answer an inbound call



 Me2TrunkAnswer**



 Me2SetLineMode (PICKUP mode)



 adiAnswerCall




 Reject an inbound call



 Me2TrunkTone



 (do not PICKUP)



 adiRejectCall




 Terminate a call



 Me2TrunkStart



 Me2SetLineMode (HANGUP mode)



 adiReleaseCall




 Start a different protocol



 Me2TrunkLoad



 NA



 adiStopProtocol and adiStartProtocol
















 *  In ME/2, Me2RequestLine may be used.


 **  Me2TrunkAnswer plays a timed interval of ringing and then answers the call. In adiAnswerCall, the number of rings before answering is specified.


 





The following table compares the events in ME/2/X, without and with the trunk manager, to the events in CT Access.





 





 ME/2/X Event Without Trunk Manager



 ME/2/X Event With Trunk Manager



 CT Access Event




 LPCUROFF



 LPCUROFF



 ADIEVN_CALL_DISCONNECTED




 None



 LPCURON



 ADIEVN_CALL_CONNECTED




 None



 TRUNKBEG



 ADIEVN_STARTPROTOCOL_DONE or ADIEVN_CALL_RELEASED




 None



 TRUNKCALLRECD



 ADIEVN_INCOMING_CALL




 None



 TRUNKDONE



 ADIEVN_CALL_CONNECTED




 None



 TRUNKENDOFDIAL



 ADIEVN_CALL_PROCEEDING




 None



 TRUNKFAIL



 ADIEVN_STARTPROTOCOL_DONE (reason is equal to error code)




 None



 TRUNKHANGUP



 ADIEVN_CALL_DISCONNECTED or ADIEVN_CALL_RELEASED




 None



 TRUNKNODIGITS



 ADIEVN_OUT_OF_SERVICE, (no digits)




 None



 TRUNKPARTIALDIAL



 ADIEVN_OUT_OF_SERVICE, (trunk partial dial)




 None



 TRUNKPERMANENT



 ADIEVN_OUT_OF_SERVICE, (permanent seizure)




 RINGBEG (1st)



 TRUNKSEIZED



 ADIEVN_SEIZURE_DETECTED




 RINGEND



 None



 No equivalent.




 None



 TRUNKSTOP



 ADIEVN_STOPPROTOCOL_DONE




 None



 TRUNKSTUCKSENDER



 ADIEVN_OUT_OF_SERVICE, (remote blocking)




 None



 TRUNKTIMEOUT



 ADIEVN_REJECTING_CALL




 None



 TRUNKWINKTIMEOUT



 ADIEVN_CALL_DISCONNECTED (no wink)





















2.4.8	 Equating ME/2/X TCPs with CT Access TCPs





The following table compares the TCPs for AG boards in ME/2/X and in CT Access:





 





 ME/2/X TCP



 ME/2/X Description



 CT Access TCP




 VBX



 AG-8 or ATI loop-start for USA



 lps0




 VBXxxx



 WTI-8 loop-start for country xxx



 lps2, 3, 4*




 VBXOPSFX



 Off Premises Station (OPS) FXO mode



 lps8




 VBXOPSSA



 Off Premises Station (OPS) SAO mode



 lps9




 TCPDID



 Wink-start (or immediate start) DTMF inbound



 did0, wnk0, wnk1 **




 TCPOGT



 Wink-start (or immediate start) DTMF outbound



 ogt0, wnk0, wnk1 **




 TCPMFI



 Wink-start (or immediate start) MF inbound



 did0, wnk0, wnk1 **




 TCPMFO



 Wink-start (or immediate start) MF outbound



 ogt0, wnk0, wnk1 **




 TCPFGD



 Feature Group D inbound



 fdi0




 R2_IN



 MF Compelled R2 signalling inbound (generic)



 mfc0***




 R2_OUT



 MF Compelled R2 signalling outbound (generic)



 mfc0***




 R2xxxIN



 MF Compelled R2 signalling inbound (for country xxx)



 mfc0***




 R2xxxOUT



 MF Compelled R2 signalling outbound (for country XXX)



 mfc0***
















 *  Refer to the WTI-8 Hardware Reference Manual..


 **  wnk0 is a bi-directional wink-start protocol encompassing both incoming and outgoing calls.


 ***  Consult the AG-E1 MFC-R2 documentation.


 








2.5	 Parameter Management





The ME/2/X Parameter Manager manages system and user-defined parameters. Parameters are variables which define system specific information and runtime information.



In ME/2/X, parameters are found in .prm files. A .prm file is a binary file that defines a parameter to the system. ME/2/X also supports user-defined parameters.



Parameters are organized in categories. The full name of a parameter is the category name, a period, and the parameter name.



Parameters can be changed with a user profile (.pro files) or via function calls.



Additional considerations for migrating are:






2.5.1	 CT Access Parameters





In CT Access, the characteristics for services can be altered by modifying associated parameters. Refer to the CT Access Developer's Reference Manual for an explanation of services.



Parameters are grouped together in C language structures called parameter structures. Each parameter structure has default values that are sufficient for most configurations. The parameters can be modified to enable/disable features and to adapt the service for special configurations.



CT Access stores and retrieves the values of named parameters and structures for any service. All services providing the same functionality have the same standard parameters. Services providing the same functionality but implemented on different hardware may have unique extension parameters.



CT Access uses either application process local memory or system shared memory to store the system default parameters of services as specified in ctaInitialize. If shared memory is being used, the CT Access parameter daemon must be running.



Each service has two sets of parameters: a system default copy and a CTA context copy. When CT Access is initialized with the specified service, the service descriptors and values are created and stored. These are the system default values.



When a service is opened on a CTA context, the parameter default values are copied to a CTA context copy. The CTA context copy of the parameters may then be modified to define CTA context characteristics.



Refer to the CT Access Developer's Reference Manual for detailed information about the parameter functions. If a valid CTA context handle is passed to the function, the CTA context copy of the parameters are retrieved or modified. If the CTA context passed is NULL_CTAHD, the system default values are retrieved or modified.



In addition to the named parameter interface, each function in CT Access optionally takes a data structure to override the parameters.






2.5.2	 Equating ME/2/X and CT Access Functions





Me2ParmByName gets or sets the value of a parameter using the parameter name to identify the parameter. In CT Access, this function has been separated into two functions - ctaGetParmByName and ctaSetParmByName.



Me2ParmByNum gets or sets the value of a single parameter by specifying the integer category number and integer parameter number. In CT Access, ctaGetParms gets parameters for a specified parameter structure but CT Access does not have a function for getting or setting parameter values by number.


 






2.6	 VOX File Functions





If you are migrating from an existing ME/2/X application, you may be able to directly substitute CT Access Voice Message service (vce) functions for ME/2/X Voice Manager (Me2Vox) functions, subject to these considerations:




For a list of the ME/2/X functions and the equivalent CT Access functions, refer to Section 2.6.1.






2.6.1	 Establishing the Current Message and Current Position





In ME/2/X, each open file has a current message and current position.



CT Access only exposes one current message (or list) and current position for a CTA context. Many functions implicitly reference this current message and do not take a voice file handle. This will not be a problem if your application performs editing or positioning operations on one file at a time. If managing multiple files at one time, you need to maintain the current message and the current position in the application context.



For example, although Me2VoxPlayFrm requires a voice handle, you can replace this with vcePlay, which does not take a voice handle, as long as the file being played was the most recently referenced.



To operate on the current message of a specific voice file, call vceSetCurrentMessage and vceSetPosition to make the voice file's current message be the current message in the Voice Message service context.



The following table lists ME/2/X functions that operate on the current message in a VOX file and shows the corresponding CT Access function that operates on the current message in the context: 





 ME/2/X Function



 CT Access Function




 Me2VoxCopyFrm



 No equivalent.




 Me2VoxGetCurFrm



 vceGetContextInfo




 Me2VoxEraseFrm



 vceErase




 Me2VoxGetCurMsg



 vceGetContextInfo




 Me2VoxGetFrames



 vceRead




 Me2VoxMarkFrm



 No equivalent.




 Me2VoxMsgSize (message = 0)



 vceGetCurrentSize




 Me2VoxMsgSize (message !=0)



 vceGetMessageSize*




 Me2VoxPlayFrm



 vcePlay




 Me2VoxPutFrames



 vceWrite




 Me2VoxRecordFrm



 vceRecord




 Me2VoxSeekFrm



 vceSetPosition




 Me2VoxSetCurMsg



 vceSetCurrentMessage




 Me2VoxSetCurMsgLst



 vceSetCurrentList















 * Unlike Me2VoxMsgSize, vceGetMessageSize does not affect the current message.






2.6.2	 Setting the Insert Mode





ME/2/X always records or writes in insert mode.



In CT Access, set the insertmode argument of vceRecord and vceWrite to VCE_INSERT.






2.6.3	 Seeking Past Message Boundary





Me2VoxSeekFrm returns ME2_VOX_FRM_NOT_FOUND when attempting to seek beyond the end or beginning of a message. The CT Access function vceSetPosition returns SUCCESS. Both Me2VoxSeekFrm and vceSetPosition set the position to the message boundary (end or beginning) in this situation. To know the relative position from the boundary in CT Access, you need to know the message size (vceGetMessageSize) and the current position (vceSetPosition).






2.6.4	 Accessing Nonexistent Messages





In ME/2/X, when you attempt to access a message that does not exist, the ME2_VOX_MSG_NOT_FOUND error is returned.



In CT Access, a nonexistent or erased message has a size of zero (0), but the message number is still valid. This applies to setting the current message, copying messages, erasing messages, getting message size, and playing.



Me2VoxSetCurMsg returns ME2_VOX_MSG_NOT_FOUND if the specified message does not exist. The CT Access function vceSetCurrentMessage returns SUCCESS. In both cases, the specified message becomes the current message.



If knowing that a message does not exist is important to your application (ME2_VOX_MSG_NOT_FOUND), call vceGetMessageSize and interpret a return size of zero (0) as the same.


Note:  In ME/2/X, message 0 is invalid. In CT Access, all voice files can contain a message 0.

 






2.7	 Voice Functions





ME/2/X voice functions such as Me2VoxPlayMsg, Me2VoxPlayMsgList, Me2VoxRecordMsg, etc. have equivalent functions in CT Access. Refer to Section 2.15.



In addition to VOX file functions, the ME/2/X Voice Manager contains functions to play and record memory and flat files.



Considerations for migrating are:






2.7.1	 Playing and Recording Memory





In ME/2/X, Me2PlayMemory plays a voice message from a memory buffer.



Me2RecordMemory records to a memory buffer.



In CT Access, use vceOpenMemory to assign a voice handle to a memory block. Use vcePlayMessage to start playing the message.



Use vceRecordMessage to record to the memory buffer.






2.7.2	 Playing and Recording Flat Files





In ME/2/X, flat (non-formatted, no header) files are opened with a system open function. The file handle returned can be used with Me2RecordList and Me2PlayList.



In CT Access, flat files are opened with vceOpenFile and the returned voice handle can be used with all voice functions.


 






2.7.3	 Playing and Recording Lists





In ME/2/X, you construct a list that contains open file handles and/or memory addresses. You then pass it to Me2PlayList or Me2RecordList.



In CT Access, you obtain a voice handle for each file and memory address. You then need to construct a list with vceSetCurrentList and then call either vcePlay or vceRecord.



Figure 4 shows the functions used in ME/2/X and in CT Access for playing VOX, memory, and flat files.


 



Figure 4.	 Playing and Recording Files in ME/2/X and in CT Access



Note:  CT Access also plays wave files.





2.8	 Prompt Builder





The ME/2/X Prompt Manager allows an application to announce dates, times, numbers and monetary amounts. A text string containing variable data such as 11/30/96, is passed to the Prompt Manager (Me2PromptBuild) which then builds a list of messages to be spoken from a standard message library.



CT Access contains equivalent prompt management (Prompt Builder) functions for converting text strings to message lists (vceBuildPromptList). The output list of message numbers is passed to vcePlayList.


 






2.9	 Digit Collection





The Me/2/X Me2GetTTS function and the ADI service function adiCollectDigits in CT Access are similar digit collection functions. However, these two functions have differences.



In ME/2/X, the list of touch tones to accept and terminate on are specified in ASCII (me2channel.tt_okay_list and me2channel.tt_done_list). In the ADI service, they are specified in the validDTMFs field and the terminators field in the ADI_COLLECT_PARMS structure.



The asynchronous result of the digit collection in ME/2/X is returned via a previously provided function argument. In the ADI service, it is the value field of the event.



The following table presents the ME/2/X result values and their equivalent CT Access event reason codes:





 





 ME/2 Result Value



 CT Access Event Reason




 Any digit (in the terminating list)



 CTA_REASON_DIGIT




 T



 CTA_REASON_TIMEOUT




 S



 CTA_REASON_STOPPED




 M (maximum digits received)



 CTA_REASON_FINISHED




 E



 CTAERR_xxxxxxx


















Refer to Appendix C in the CT Access Developer's Reference Manual for a description of the CT Access reason codes.


 






2.9.1	 Digit Queue





 Me2GetTTC gets the oldest touchtone (DTMF) in the touchtone queue and optionally removes the digit from the queue.



The CT Access ADI service provides you with three functions:





 





 CT Access Function



 Description




 adiGetDigit



 Gets a single DTMF digit character from the front of the internal digit queue. The oldest digit is removed from the queue.




 adiPeekDigit



 Reads a single DTMF digit character from the front of the internal digit queue without removing it.




 adiFlushDigitQueue



 Discards (flushes) all digits in the internal digit queue. The digit queue is automatically flushed when the call is released.


















The internal digit queue in the ADI service is equivalent to the touch tone queue in ME/2/X.






2.10	 Tone Detection and Generation





ME/2/X has Me2StartToneDetector for AG boards. The equivalent function in CT Access is adiStartToneDetector which allows you to individually run up to three tone detectors at the same time.



The equivalents of Me2Beep and Me2TTone in CT Access are adiStartTones and adiStartDTMF.



In CT Access, you can also automatically send a beep when starting a record function.


 






2.11	 DTMF Detection





In ME/2/X, the only way to turn off the DTMF detector is to use the internal function Me2OvlyMosEnv to change to a new speech environment level. The detector is not parameterized. This is typically not used by applications.



CT Access has functions for starting and stopping the DTMF detector (adiStartDTMFDetector and adiStopDTMFDetector). You can also control parameters of the detector such as sensitivity.






2.12	 Timer





Me2Delay starts an asynchronous timer on the board in ME/2/X. The delay time is specified in 1/100 seconds. At any point during the delay, Me2Stop can be called to abort the function. While the ME/2/X timer is running, no other asynchronous function can be called.



In CT Access, adiStartTimer starts a timer on the board. Time is specified in milliseconds. This function supports one application timer per context. This on-board timer has 10 ms resolution. The application can stop the timer by calling adiStopTimer. The timer may be reset or restarted with an additional call to adiStartTimer. When the timer is restarted, previous timer definitions are discarded and the timer begins with the new parameters. While adiStartTimer is running, other functions can be called.


Note:  Unlike most other CT Access asynchronous functions, the timer function is not stopped automatically when a call is released.





2.13	 Error Handling





Me2GetError obtains the operating system error which caused an ME/2/X function to fail. It does not have a direct CT Access function equivalent.



However, CT Access provides you with two similar functions. adiGetContextInfo returns information about the current state of a specified context. vceGetContextInfo returns information about the current or most recent play or record operation on a CTA context.






2.14	 Other Differences





This section contains a short description of other differences between ME/2/X and CT Access that you must consider when migrating from an existing ME/2/X application.






2.14.1	 Local Phone Functions





CT Access does not support VBX boards. Currently, there are no AG boards with local handsets. Therefore, there are no equivalent functions in CT Access for the local phone functions.






2.14.2	 Stop Function





ME/2/X has a single stop function (Me2Stop) that stops whatever is running because only one asynchronous function can be run at one time.



CT Access provides separate stop functions for each asynchronous function. All asynchronous functions automatically stop when a call is released. The only exception to this is adiStartTimer.






2.14.3	 Status Monitor Functions





There are no status monitor functions (such as Me2GetMonEvent) in CT Access.






2.14.4	 Board Numbers





Me2GetMaxAGBoardNo retrieves the highest AG board number of all initialized AG boards in the system. In CT Access, call adiGetBoardInfo in a loop to probe the number of boards in your system.






2.14.5	 Database Management Functions





There are no database functions in CT Access. You should obtain another dBase III compatible library.






2.14.6	 Time Stamped Events





In ME/2/X, time stamped events were available as a special only (not in the standard product). In CT Access, all events have a timestamp in them.






2.15	 Table of Function Equivalents





The following table lists the ME/2/X functions and the equivalent CT Access functions:





 





 ME/2/X Function



 CT Access Functions




 Me2AvailLines



 None. No line arbitration supported.




 Me2Beep



 adiStartTones




 Me2Call



 adiPlaceCall




 Me2CallProgress



 adiStartCallProgress




 Me2Delay



 adiStartTimer




 Me2DetectMF



 adiStartMFDetector




 Me2Dial



 adiStartDial or adiPlaceCall




 Me2FindFile



 ctaFindFile




 Me2GetAGBoardInfo



 adiGetBoardInfo




 Me2GetAGBoardType



 adiGetBoardInfo




 Me2GetAGLineInfo



 adiGetContextInfo




 Me2GetAGSerialNo



 adiGetBoardInfo




 Me2GetChannel



 None. Channel is equivalent to context handle, ctahd.




 Me2GetError



 adiGetContextInfo and vceGetContextInfo




 Me2GetErrorDescription



 None.




 Me2GetErrorName



 ctaGetText




 Me2GetEvent



 ctaWaitEvent




 Me2GetEventName



 ctaGetText




 Me2GetEventDescription



 ctaFormatEvent




 Me2GetLastMonEvent



 None.




 Me2GetLine



 adiGetContextInfo




 Me2GetLineError



 None. No line arbitration supported.




 Me2GetLineGroup



 None. No line arbitration supported.




 Me2GetLineStatus



 adiGetCallStatus and adiGetContextInfo




 Me2GetMaxAGBoardNo



 None. Refer to adiGetBoardInfo.




 Me2GetMonEvent



 None.




 Me2GetPhysLine



 None.




 Me2GetProcId



 None. Use operating system call.




 Me2GetTTC



 adiGetDigit, adiPeekDigit, adiFlushDigitQueue




 Me2GetTTS



 adiCollectDigits




 Me2GrabLine



 ctaOpenServices and adiStartProtocol




 Me2GrabTrunkLine



 ctaOpenServices and adiStartProtocol




 Me2GroupName



 None. No line arbitration supported.




 Me2GroupNum



 None. No line arbitration supported.




 Me2IsAStream



 None. CT Access Unix devices are always STREAM devices.




 Me2IsGroupMember



 None.




 Me2KeepAlive



 None.




 Me2LineListFail



 None.




 Me2LineListRestore



 None.




 Me2MaxGroup



 None. No line arbitration supported.




 Me2MaxLine



 None.




 Me2ParmByName (GETPARM)



 ctaGetParmByName




 Me2ParmByName (SETPARM)



 ctaSetParmByName




 Me2ParmByNum (GETPARM)



 ctaGetParms (structures only)




 Me2ParmByNum (SETPARM)



 None.




 Me2ParmCategoryName



 ctaGetParmInfo




 Me2ParmCategoryNum



 None.




 Me2ParmLoad



 See the Demo Library.




 Me2ParmMsg



 None.




 Me2ParmName



 ctaGetParmInfo




 Me2ParmNum



 None.




 Me2ParmSave



 None.




 Me2ParmTypeByName



 ctaGetParmInfo




 Me2ParmTypeByNum



 ctaGetParmInfo




 Me2PlayList



 vceOpenMemory, vceSetCurrentList, and vcePlay




 Me2PlayMemory



 vceOpenMemory and vcePlayMessage




 Me2PromptBuild



 vceBuildPromptList




 Me2PromptClose



 vceUnloadPromptRules




 Me2PromptLoad



 vceLoadPromptRules




 Me2RecordList



 vceRecordMessage




 Me2RecordMemory



 vceOpenMemory and vceRecordMessage




 Me2ReleaseChannel



 ctaDestroyContext




 Me2ReleaseLine



 ctaCloseServices or ctaDestroyContext




 Me2ReleaseStatMon



 None.




 Me2RequestChannel



 ctaCreateQueue and ctaCreateContext




 Me2RequestLine



 No line arbitration supported. Refer to ctaOpenServices.




 Me2RequestStatMon



 None.




 Me2SendAGCmd



 adiSendAGMessage




 Me2SendEvent



 ctaQueueEvent




 Me2SendMonEvent



 ctaLogTrace




 Me2SetAttachMode



 None. This is a VBX100 local phone function.




 Me2SetAttnMode



 None. This is a VBX100 local phone function.




 Me2SetAudioMode



 None. This is a VBX100 local phone function.




 Me2SetAudioVolume



 None. This is a VBX100 local phone function.




 Me2SetLineGroup



 None. No line arbitration supported.




 Me2SetLineMode



 adiPlaceCall, adiReleaseCall or adiAssertSignal




 Me2SetMuteMode



 None. This is a VBX100 local phone function.




 Me2SetPhysLine



 None.




 Me2SetTraceFlags



 ctaSetTraceLevel




 Me2StartToneDetector



 adiStartToneDetector




 Me2Stop



 Various. See the Stop function for the appropriate CT Access service.




 Me2StopToneDetector



 adiStopToneDetector




 Me2TelState



 adiGetCallStatus or adiQuerySignalState




 Me2TotalLines



 adiGetBoardSlots and adiGetBoardInfo




 Me2TriTone



 adiStartTones




 Me2TrunkAnswer



 adiAnswerCall




 Me2TrunkDial



 adiPlaceCall




 Me2TrunkLoad



 adiStartProtocol




 Me2TrunkStart



 adiStartProtocol and adiReleaseCall




 Me2TrunkTone



 adiRejectCall




 Me2TTone



 adiStartDTMF




 Me2VoxClose



 vceClose




 Me2VoxCopyFrm



 None.




 Me2VoxCopyMsg



 vceCopyMessage




 Me2VoxEraseFrm



 vceErase




 Me2VoxEraseMsg



 vceEraseMessage




 Me2VoxFrmEnergy



 None.




 Me2VoxGetCurFrm



 vceGetContextInfo




 Me2VoxGetCurMsg



 vceGetContextInfo




 Me2VoxGetFrames



 vceRead




 Me2VoxGetRate



 vceGetOpenInfo




 Me2VoxHighMsg



 vceGetHighMessageNumber




 Me2VoxMarkFrm



 None.




 Me2VoxMsgSize (message = 0)



 vceGetCurrentSize




 Me2VoxMsgSize (message !=0)



 vceGetMessageSize. See Section 2.6.1.




 Me2VoxOpen



 vceOpenFile




 Me2VoxPlayFrm



 vcePlay




 Me2VoxPlayLouder



 vceSetPlayGain




 Me2VoxPlayMsg



 vcePlayMessage




 Me2VoxPlayMsgList



 vcePlayList




 Me2VoxPlaySofter



 vceSetPlayGain




 Me2VoxPutFrames



 vceWrite




 Me2VoxRecordFrm



 vceRecord




 Me2VoxRecordMsg



 vceRecordMessage




 Me2VoxSeekFrm



 vceSetPosition




 Me2VoxSetCurMsg



 vceSetCurrentMessage




 Me2VoxSetCurMsgLst



 vceSetCurrrentList




 Me2VoxUniqMsg



 vceGetUniqueMessageNumber




 Me2WaitEvent



 ctaWaitEvent


























 
    (Page 1 of 1 in this chapter)




 




tech_support@nmss.com



Copyright © 1998, Natural MicroSystems, Inc.   All rights
reserved.