graPHIGS Programming Interface: Subroutine Reference

The graPHIGS Programming Interface : Subroutine Reference

GPEVHN - Define Event Handling Subroutine

GPEVHN (event-handler, anchor)

Purpose

Use GPEVHN to specify the address of an application-defined event handling procedure.

If the specified application event handler routine address is not zero, 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 environment independent.

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 data

Application 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 integer

Major code of the event.

class -- fullword integer

Event class of the event.

minor -- fullword integer

Minor code of the event.

length -- fullword integer

Length of event data in bytes.

data -- variable length data

Event data. For the format of event data see The graPHIGS Programming Interface: Technical Reference

sflag -- fullword integer

Status flag. Flags representing the event queue status. The following bits are set:

bit 0-28

Reserved, is set to 0.

bit 29

Event queue space flag (1=NO_MORE_SPACE_AVAILABLE,0=SPACE_AVAILABLE )

bit 30

Event queue overflow flag (1=ALREADY_OVERFLOWED, 0=NOT_OVERFLOWED_YET ) When this bit is 1, bit 29 is always 1.

bit 31

More simultaneous event flag (1=MORE_SIMULTANEOUS_EVENT,0=NO_MORE_SIMULTANEOUS_EVENT )

rflag -- fullword integer

Return flag. Flags specifying required operations. The following bits should be set:

bit 0-30

Reserved, should be set to 0.

bit 31

Discard flag (1=SHOULD_BE_DISCARDED,0=SHOULD_BE_ENQUEUED ) 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.

Parameters

event-handler -- specified by user, fullword integer

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.

Error Codes

None

Related Subroutines

None

RCP code

201338117 (X'0C002D05')