New Page 0

Understanding data triggers in APRO

One of the most powerful features of Async Professional is data triggers. Using these can make writing such programs as automated fax and file servers dramatically easier. The trade-off (there's always at least one) is that they can be a bit difficult to understand and implement. Once you master data triggers, however, the door is opened to greatly simplified yet powerful asynchronous programming.

Keep these important data triggers issues in mind and you should be able to get your programs up and running easier and faster.

Getting the Basics
A complete discussion of data triggers would be overly complex. Here, we'll go over the basics of adding and using a data trigger in a program. You may notice that what's here doesn't exactly match what's in our manual. Rather than depending on you finding a note in the latest README file, we're using the Tech Tip to let you know about a rather significant change to what you may have understood about data triggers.

The idea behind data triggers in Async Professional is to allow you to watch for a given set of one or more characters in the incoming data. You can set one or set several. For example, you could use data triggers to automatically log into a computer to look for words such as 'Password', 'User Name', etc.

You add a trigger for 'Password' with only one line of code:

Trigger1 := ApdComport1.AddDataTrigger('PASSWORD', False);

In this case, we're telling APRO to let us know when the string 'Password' has been received and that the match is not case-sensitive. The value of the assigned trigger is stored in Trigger1. It may not be absolutely necessary to store the value but, if we had several data triggers, it would be used to determine which data trigger had been received.

To know when the trigger has been received, you add an OnTriggerData event handler, e.g.,

procedure TExTrigTest.ApdComPort1TriggerData
  (CP: TObject; TriggerHandle: Word);
begin
  if (TriggerHandle = Trigger1) then
    Label1.Caption := 
      'Trigger Received'; 
end;

Of course, you'd do something more practical with your event handler but this illustrates the point. Take a look at the EXHOST or EXAUTO examples to see a more realistic use of data triggers.

One thing missing that's very important is an OnTriggerAvail event handler. This allows the APRO dispatcher to hand off the data that's been received from Windows. You should create an OnTriggerAvail event handler that gets called when data is available. It's in this event handler that you should actually read the data from the input buffer.

When does the event fire and what data has been received?
This is where we'll part company with the existing documentation that says that when the OnTriggerData event fires, all characters up to - but not including those in the data trigger - have been passed on via the OnTriggerAvail event. In the case of our 'Password,' that would mean that all characters up to but not including 'P' had been received. Next, the OnTriggerData would fire, followed immediately by an OnTriggerAvail where the first eight characters would be 'Password' along, maybe with some other characters. Although this is the typical behavior for APRO, it is not the guaranteed behavior.

In reality, the OnTriggerAvail events fire with no regard to the data trigger. That means, in our example, that you may have 'Password' as the first characters, the last characters, or be embedded somewhere in the middle of those characters available in the OnTriggerAvail event. In fact, the two characters may come in separate events, not in just one. The OnTriggerData event says only that 'Password' has been received at some recent time.

So far this applies to data triggers longer than one character. If, instead, the trigger had been a carriage return (#13), the behavior would be as first described and in line with previous documentation. It also applies to longer data triggers when the other side pauses after sending the trigger, such as a host sending 'Password', meaning the data triggers are perfect for such tasks as log-in scripts.

In those cases where the data trigger is longer than one character and the data flow is continuous, or nearly so, then you have more work to do. If you have control over the characters being sent, you can add a unique ending character to the data trigger. When the OnTriggerData event fires because of this unique character, you can set a flag that tells the OnTriggerAvail event to look for the character the next time it fires and keep either those before, after, or including the unique character. If you can't control the sending characters, then the OnTriggerAvail will use the flag to "know" that somewhere in the data buffer into which you're storing incoming characters is the data trigger and take action accordingly.

Since data triggers are an integral and often used feature of Async Professional, we are looking at ways to make the task of handling specified characters or strings easier and even more dependable. For example, you might be able to specify a buffer and the trigger that starts or ends the data you want and APRO will handle the rest. In the meantime, keep these important data triggers issues in mind and you should be able to get your programs up and running easier and faster.

This site is not affiliated, endorsed, or otherwise associated with the entity formerly known as TurboPower Software. The owners and maintainers of Aprozilla.com were merely meager employees of the aforementioned organization, providing this site out of the pure goodness of their collective hearts.

Last updated: July 22, 2003.