[ Previous | Next | Contents | Glossary | Home | Search ]
The graPHIGS Programming Interface : Subroutine Reference

GPEVHN - Define Event Handling Subroutine

GPEVHN (event-handler, anchor)


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.


    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


    Related Subroutines


    RCP code

    201338117 (X'0C002D05')

    [ Previous | Next | Contents | Glossary | Home | Search ]