UNSUBSCRIBE statement

Cancels a subscription to an ABL named event. Specifically, the UNSUBSCRIBE statement cancels one or more subscriptions to one or more named events.

Note: ABL named events are completely different from the key function, mouse, widget, and direct manipulation events, which are described in the "Handle-based Object Events Reference" section. They are also different from the class events described in the "Class Events Reference" section.

Syntax


UNSUBSCRIBE [ PROCEDURE `subscriber-handle` ] [ TO ] { `event-name` \| ALL } [ IN `publisher-handle` ]

PROCEDURE subscriber-handle

A procedure handle representing the subscriber to a named event.

The PROCEDURE option lets one procedure cancel a subscription on behalf of another. For example, if you want procedure A to cancel a subscription on behalf of procedure B, set subscriber-handle to the procedure handle of B.

If the PROCEDURE option does not appear, the AVM assumes that the subscriber is THIS-PROCEDURE, the procedure that contains the UNSUBSCRIBE statement.

event-name

A quoted string or character expression representing the name of a named event.

ALL

Cancels all subscriptions.

IN publisher-handle

A procedure handle representing the publisher of a named event.

If the IN option appears, the AVM cancels subscriptions to named events published by publisher-handle-specifically, either all subscriptions (if the ALL option appears), or only subscriptions to event-name (if event-name appears).

If the IN option does not appear, the AVM cancels subscriptions regardless of the publisher-specifically, either all subscriptions (if the ALL option appears), or only subscriptions to event-name (if event-name appears).

Example

For an example, see the reference entry for the PUBLISH statement.

Notes

When the AVM executes an UNSUBSCRIBE statement, it cancels a subscription when it finds a match. A match means that the SUBSCRIBE and UNSUBSCRIBE event names match, and that one of the following is true:

The subscription was created using SUBSCRIBE IN, cancelled using UNSUBSCRIBE IN, and the publisher and subscriber handles in the SUBSCRIBE and UNSUBSCRIBE statements match.

The subscription was created using SUBSCRIBE ANYWHERE, and cancelled using UNSUBSCRIBE without the IN option.

The AVM executes the UNSUBSCRIBE statement with an implicit NO-ERROR option. That is, if the AVM cannot find a match, it does not report an error. To find out what errors, if any, occurred, use the ERROR-STATUS system handle.

If you create a subscription using SUBSCRIBE ANYWHERE, you cannot cancel the subscription using UNSUBSCRIBE IN.