Asynchronous methods

One of the advanced features of ActiveAG is that it makes asynchronous forms of all time-consuming methods available to your program. As used here, asynchronous should be understood to mean non-blocking. That is, an asynchronous method is one that starts and returns control to your program before it completes the operation it will perform. When the method finally completes, your program is notified by an AsyncCmdDone event.

Asynchronous methods are made possible by ActiveAG’s multi-threaded architecture. That is, ActiveAG is internally multi-threaded. If your program uses asynchronous methods, this explanation of how they work is recommended reading. This explanation applies to all asynchronous methods in ActiveAG.

When your program uses an Async method, ActiveAG passes that request on to its worker thread. This allows it to return control to your program immediately. The worker thread then proceeds to process the command in exactly the same manner as the synchronous form of the method would have been processed. When the worker thread completes the operation, ActiveAG fires the AsyncCmdDone event to your program with this information:

CmdCode as a short integer. This will be one of the Asynchronous completion constants described in the ActiveAG constants topic.

LineNumber as a short integer. This indicates which line (or ActiveAG instance) the asynchronous method was invoked for. While this information is redundant for Visual Basic programmers, it is necessary for using ActiveAG with C++ tools.

Status as a long integer. This value will be one of the status codes described in the ActiveAG Status codes topic.

Finally, a return string as a BSTR. This string is only used when the method used was the GetTouchTonesAsync method. In this case, it contains any touch-tones that were collected by the method. For all other methods, this will be an empty (NULL) string.

In your program’s AsyncCmdDone event handler, you can use a case statement on the line number, or the command code, or both. In all cases, though, your program should check the value of the Status to determine if an error occurred in the asynchronous method.

What are asynchronous methods used for? In general, they allow your program to perform more than one task in a single thread of execution. For example, if your application has a graphical interface, using asynchronous method calls will allow the user interface to remain responsive while the program is controlling the telelphone line.

As another example, you may want to do a database look-up while playing an ‘infomercial’ or a background message to a caller. This can be done using the PlayVoiceAsync method . Invoke this method in your program and then proceed to do your database operation. When your program receives the AsyncCmdDone event for the PlayVoiceAsync method, it can either a) continue if it’s ready or b) re-start PlayVoiceAsync if it’s not ready to continue.

Another possible use of asynchronous methods is to write a state machine application that can handle multiple ports (telephone lines) in a single process. This will require that your application instantiate an array of ActiveAG instances, but this is easily done in almost any language.

State machine programming is more complex than simple sequential programming -- but it is an extremely efficient way to implement a multi-port process and it uses fewer system resources than other methods (port per process or port per thread). At Group W Systems, we have demonstrated a 48 port Visual Basic process (built with ActiveAG) running in a stress test, so the ability to handle a large volume of telephony events is not a question.

The ActiveAG Methods topic shows a complete list of all methods, including the asynchronous ones. The names of all asynchronous methods end with the characters ‘Async’.