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.