SUBSCRIBE statement

Creates a subscription to an ABL named event.

Syntax

SUBSCRIBE [ PROCEDURE subscriber-handle] [ TO ] event-name 
  { IN publisher-handle | ANYWHERE }
  [ RUN-PROCEDURE local-internal-procedure ] [ NO-ERROR ]

PROCEDURE subscriber-handle

A procedure or handle representing the subscriber.

The PROCEDURE option lets one procedure create a subscription on behalf of another. For example, if you want procedure A to create 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 creates a subscription on behalf of THIS-PROCEDURE, the procedure that contains the SUBSCRIBE statement.

TO event-name

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

IN publisher-handle

Subscribes to the named events published by publisher-handle.

If publisher-handle is not a valid procedure or widget handle at the time the SUBSCRIBE statement executes, the AVM reports a run-time error unless you specify the NO-ERROR option.

ANYWHERE

Subscribes to named events published within the ABL session, regardless of the publisher.

RUN-PROCEDURE local-internal-procedure

A quoted string or character expression representing the name of an internal procedure that resides within the subscribing program. The AVM runs local-internal-procedure when the named event occurs.

If the RUN-PROCEDURE option does not appear, when the named event occurs, the AVM runs an internal procedure with the same name as the named event.

Note: The RUN-PROCEDURE option lets you create a subscription when the event name and the procedure name do not match, or when you must subscribe to two different events that have the same name.

When the named event occurs, the AVM RUNs each subscriber's local internal procedure, passing the parameters, if any, The order in which the AVM notifies subscribers is undefined. The AVM always performs this RUN with an implicit NO-ERROR, and logs errors to the ERROR-STATUS system handle.

NO-ERROR

The NO-ERROR option is used to prevent the statement from raising ERROR and displaying error messages.

Example

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

Notes

• Within the local internal procedure, you can get a handle to the publisher of the named event by using the SOURCE-PROCEDURE system handle. For more information on the SOURCE-PROCEDURE system handle, see the reference entry.
• If the AVM detects a redundant SUBSCRIBE statement—that is, a SUBSCRIBE statement with the same event name, and either the same publisher handle or the same ANYWHERE option—the AVM does not report an error.
• If event-name is a string containing spaces or is otherwise not a standard ABL name, use one of the following techniques:
  • Use the RUN-PROCEDURE option to assign the local internal procedure a more conventional name.
  • When you define local-internal-procedure, put its name in quotes, as in the following example:

    PROCEDURE "spaced event":

See also

NO-ERROR option, PUBLISH statement, PUBLISHED-EVENTS attribute, Subscribe( ) event method, UNSUBSCRIBE statement