[ Previous |
The graPHIGS Programming Interface : Subroutine Reference
GPEVHN - Define Event Handling Subroutine
Use GPEVHN to specify the address of an
If the specified application event handler routine address is not
the graPHIGS API gives control to the routine for each event
received by the shell from any connecting nucleus.
When the routine address is zero, the graPHIGS API performs
event handling without calling any application defined event handler.
The application event handler defined by this subroutine
is invoked from the graPHIGS API event handling routine
running in a special run time environment.
The environment depends on the operating system on which
the graPHIGS API shell is running and on the communication mechanism
used to communicate with each nucleus.
If two graPHIGS API nuclei are connected to the graPHIGS API shell
and communication methods for these nuclei are different, the
application event handler may be invoked in two different environments.
Therefore, the application event handler:
Must be written in a programming language which is
Must follow the standard linkage convention of the operating
system on which the graPHIGS API shell is running.
Must not issue any graPHIGS API subroutine call.
Should not issue nor invoke
any system subroutine which may
require the normal run time environment.
Must return to the graPHIGS API event handler.
For the details of event class, major/minor codes and
event data, see The graPHIGS Programming Interface: Technical Reference
When the application event handler is invoked, it receives the
following parameters by the "call by reference mechanism" via
the operating system's standard linkage convention.
The application event handler
should never modify any parameter other than the return flag:
anchor -- variable dataApplication anchor.
This is the second parameter of the GPEVHN subroutine.
Anchor is a user defined data area that the graPHIGS API passes
to your event handler.
The parameter is passed without any checking or modification.
major -- fullword integerMajor code of the event.
class -- fullword integerEvent class of the event.
minor -- fullword integerMinor code of the event.
length -- fullword integerLength of event data in bytes.
data -- variable length dataEvent data.
For the format of event data see The graPHIGS Programming Interface: Technical Reference
sflag -- fullword integerStatus flag.
Flags representing the event queue status.
The following bits are set:
bit 0-28Reserved, is set to 0.
bit 29Event queue space flag
bit 30Event queue overflow flag
When this bit is 1, bit 29 is always 1.
bit 31More simultaneous event flag
rflag -- fullword integerReturn flag.
Flags specifying required operations.
The following bits should be set:
bit 0-30Reserved, should be set to 0.
bit 31Discard flag
Even if the application specifies 0 for this bit, the event
is discarded when there is no more space available, that is, when
bit 29 of the status flag is 1.
If this situation occurs in the process of simultaneous events,
it also causes deletion of all events within the simultaneous event
group and the event queue enters an overflow state.
Note that in the case of queue overflow the
deletion of a set of simultaneous
events includes deletion of events already
reported to the application event handler.
event-handler -- specified by user,
Address of the application event handler routine
or a fullword integer of 0.
anchor -- specified by user, variable data
Parameter to be passed back to the application event handler.
Anchor is for user defined data.
[ Previous |