Release 10.1A: OpenEdge Development:
Progress 4GL Handbook

> ## Subscribing to an event

> Since a procedure has to subscribe to an event before anything happens when another procedure publishes it, you’ll look at the `SUBSCRIBE` statement first. Here is its syntax:

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

> By default, a `SUBSCRIBE` statement registers the request on behalf of the external procedure that contains the `SUBSCRIBE` statement. The value of the procedure handle is the built-in Progress handle `THIS-PROCEDURE`. For the subscriber to receive the event, it must be running at the time the event occurs, so normally this means that you should only include a `SUBSCRIBE` statement in a procedure that is run persistent.

> You can, however, create a service procedure that subscribes other procedures to events. In that case, you can include the `PROCEDURE` `subscriber-handle` phrase and the `SUBSCRIBE` is done on behalf of that other procedure handle.

> The `event-name-expr` is a string expression holding the name of the event to publish. This is a standard Progress name of the same type as an internal procedure name. The default action when the event is published is to run an internal procedure in the subscriber with the same name as the event.

> When you subscribe to an event, you can either subscribe to it in a specific running procedure handle that is available, or you can use the `ANYWHERE` keyword to indicate that you want to be notified when this event occurs anywhere in your session. If you specify the `IN` `publisher-handle` phrase, then the publisher must be a procedure that is already running and that remains running until it publishes the event. There is no way to subscribe to events that are published by procedures in other OpenEdge sessions.

> One common practice is to subscribe to events that are published by the procedure that started the subscriber. The handle of that procedure is available in the `SOURCE-PROCEDURE` handle. An example in the "PUBLISH/SUBSCRIBE example" section shows you how this works.

> A procedure can also subscribe to events in the `SESSION` handle. Other procedures can then publish events from the `SESSION` handle, thus using it as a kind of central coordinating point for events.

> If the name of the internal procedure you want to run in response to the event must be different from the event name itself, then you include the `RUN-PROCEDURE` `local-internal-procedure` phrase in the `SUBSCRIBE` statement. You must implement the internal procedure in the subscriber (or one of its super procedures, if any).

> If it is possible that the `subscriber-handle` or `publisher-handle` might not be valid at the time the statement is executed, you can include the `NO-ERROR` phrase to suppress any error messages that would result from this. In this case, the `SUBSCRIBE` has no effect, and the `ERROR-STATUS` handle holds a status and message describing the error.

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095