Release 10.1A: OpenEdge Development:
Progress 4GL Reference

> ## SUBSCRIBE statement

> Creates a subscription to a Progress named event.

> Note: Progress named events are completely different from the key function, mouse, widget, and direct manipulation events described in the "Events Reference" section. For more information on Progress named events, see OpenEdge Development: Progress 4GL Handbook .

> #### 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, Progress 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, Progress reports a run time error unless you specify the NO-ERROR option.

> `ANYWHERE`

> Subscribes to named events published within the OpenEdge 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. Progress runs `local-internal-procedure` when the named event occurs.

> If the RUN-PROCEDURE option does not appear, when the named event occurs, Progress 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, Progress RUNs each subscriber’s local internal procedure, passing the parameters, if any, The order in which Progress notifies subscribers is undefined. Progress always performs this RUN with an implicit NO-ERROR, and logs errors to the ERROR-STATUS system handle.

> `NO-ERROR`

> Tells Progress not to report a run time error if `publisher-handle` or `subscriber-handle` is not a valid procedure handle, or if Progress cannot evaluate an `event-name` expression. Errors are still generated, however, and are stored in the ERROR-STATUS handle.

> Example

> For an example, see the reference entry for the PUBLISH statement in this manual.

> #### 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 its reference entry in this book.

> - If Progress 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—Progress does not report an error.

> - If `event-name` is a string containing spaces or is otherwise not a standard Progress 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

> PUBLISH statement, PUBLISHED-EVENTS attribute, UNSUBSCRIBE statement

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