ArborX

event

Longname: event   Open the Documentation Legend
Released: 5.00 
Created: 5.00 
See also: automac

Summary
 The event macro is only useful in 3B2OCX where communication between 3B2 and the enclosing application is required.
Example extract

You can pass your own events from 3B2 using the event macro:

 event 555 1024

Syntax (5.00)
event event_number:n event_param:n
event_number:n User defined event number. 3B2 issues a number of events automatically i.e. for each page printed or formatted (see api.txt in the OCX install directory).
event_param:n A parameter of the event sent to and used by the OCX wrapper application to action whatever it may be configured to do. This number can be generated by a number of means in 3B2 including, but not exclusively, getvars, script variables or expressions.

There are two main reason for 3B2 to issue an event to the enclosing application:

4  Messages: can be sent via events (although the second parameter can only be of type long not a string) so you might send an event to the enclosing application to, for example, fill a 3B2 variable with a certain value or read a predefined string from 3B2 using the OCX api calls GetText for example.
When using user defined events like the example, you need to make sure that these do not clash with 3B2's predefined events, from api.txt:

AdventEvent(long identifier, long lParam)

This event passes two long variables the first value is the event identifier and the second is some associated value.

Currently (version 8) 3B2 uses the following event identifiers:

0xFFFFFFFF

mem : This event sends the amount of memory 3B2 is using (Note: only sent from DEBUG version).

256

User clicked on a protected field at 'pos' in the current stream.

257

OnOff : Dialogue box notification.

258

handle : Current stream notification.

259

page : High-level formatting page 'page' (tformat).

260

page : Printing page 'page' (tprint).

261

page : Low-level formatting page 'page' (trf, tpgoto, tfreeze, tformat, tprint etc.)

Example

This advanced example is executed by the templates autoexec. v21812 is the script line number, v1818 is the script name. Each time one of them change, 3b2 increase the variables (respectively) _AX_P_ and _AX_S_ and sends the comment event 600 or 601 with the variable value as parameter.

 automac 1,"v21812",0,"(^_AX_P_++):(event 601,^_AX_P_^)",2; 1
 2,"v1818",0,"(^_AX_S_++):(event 600,^_AX_S_^)",2 2

Adventtest.exe (the sample wrapper program delivered with 3B2 ocx builds) displays the event number and the event parameter it receives from 3b2 (eg. event 600,1 would show 600 in the first field and 1 in the second, at the bottom left of the window).

However, up to its version 2.3, it does not display the number of received events in any manner, so the only way to see, on screen, consecutive events with identical numbers, is to change their parameters. Hence the slightly unusual sample seen here.
For further information see also:

Perl3B2::event (a way to send events from perl scripts as Perl3B2::macro(event X, Y) is no longer stable).

api.txt - ships with the OCX version.

ACS documentation, ACS relies heavily on events for logs (Advent3B2::ACS perl package).

Document created on 08-Feb-2003 (revision 1)