PUBLISH statement

Causes an ABL named event to occur.

Note: ABL named events are completely different from the key function, mouse, widget, and direct manipulation events 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


PUBLISH `event-name` [ FROM `publisher-handle` ] [ ( `parameter` [ , `parameter` ] ... ) ]

event-name

A quoted character string or character expression representing the name of a named event. If you use a quoted character string, ABL adds event-name to the PUBLISHED-EVENTS attribute’s list of events.

FROM publisher-handle

A procedure or handle representing the procedure or widget to which ABL attributes the named event.

The FROM option lets a procedure publish an event on behalf of another procedure or widget. For example, if you want procedure A to publish a named event on behalf of procedure B, set publisher-handle to the procedure handle of B.

If the FROM option does not appear, ABL attributes the event to THIS-PROCEDURE, the procedure that contains the PUBLISH statement.

Note: If the FROM option does not appear and the PUBLISH statement occurs in a nonpersistent procedure that does not publicize its handle, potential subscribers have no way of knowing the handle’s value, and can subscribe to the event only by using the SUBSCRIBE statement’s ANYWHERE option.

( parameter [ , parameter ] ... )

The parameters, if any, of the named event.

As in the RUN statement, you must supply a value for each INPUT and INPUT-OUTPUT parameter and a variable for each OUTPUT parameter.

Also, if a named event has one or more parameters, the PUBLISH statement and each subscriber’s local internal procedure (which the SUBSCRIBE statement names and which the AVM runs when the named event occurs) must specify identical signatures-where signature means the number of parameters and the data type and mode (INPUT, etc.) for each.

Note: When the named event occurs and the AVM runs each subscriber’s local internal procedure, if the signature of a local internal procedure does not match the signature in the PUBLISH statement, the AVM reports a run-time error. Since the PUBLISH statement runs with an implicit NO-ERROR, errors are stored in the ERROR-STATUS handle.

The parameter syntax is identical to that of the RUN statement. For its specification, see the Parameter passing syntax reference entry.

Example

The following example consists of four procedure files: a driver, a publisher, and two subscribers. The driver, r-nedrvr.p, runs the publisher and the two subscribers persistently, then subscribes to the event NewCustomer on behalf of the second subscriber.

r-nedrivr.p
/* r-nedrvr.p / DEFINE VARIABLE hPub AS HANDLE NO-UNDO. DEFINE VARIABLE hSub1 AS HANDLE NO-UNDO. DEFINE VARIABLE hSub2 AS HANDLE NO-UNDO. DEFINE BUTTON bNewCust LABEL "New Customer". DEFINE BUTTON bQuit LABEL "Quit". RUN r-nepub.p PERSISTENT SET hPub. RUN r-nesub1.p PERSISTENT SET hSub1 (hPub). RUN r-nesub2.p PERSISTENT SET hSub2. / Subscribe to event NewCustomer on behalf of subscriber 2 */ SUBSCRIBE PROCEDURE hSub2 TO "NewCustomer" IN hPub. FORM bNewCust bQuit WITH FRAME x. ENABLE ALL WITH FRAME x. ON CHOOSE OF bNewCust RUN NewCust in hPub. WAIT-FOR CHOOSE OF bQuit OR WINDOW-CLOSE OF CURRENT-WINDOW.

r-nedrivr.p

/* r-nedrvr.p  */ 
DEFINE VARIABLE hPub  AS HANDLE NO-UNDO. 
DEFINE VARIABLE hSub1 AS HANDLE NO-UNDO. 
DEFINE VARIABLE hSub2 AS HANDLE NO-UNDO. 
DEFINE BUTTON bNewCust LABEL "New Customer". 
DEFINE BUTTON bQuit    LABEL "Quit". 
RUN r-nepub.p  PERSISTENT SET hPub. 
RUN r-nesub1.p PERSISTENT SET hSub1 (hPub). 
RUN r-nesub2.p PERSISTENT SET hSub2. 
/* Subscribe to event NewCustomer on behalf of subscriber 2 */ 
SUBSCRIBE PROCEDURE hSub2 TO "NewCustomer" IN hPub. 
FORM bNewCust bQuit WITH FRAME x. 
ENABLE ALL WITH FRAME x. 
ON CHOOSE OF bNewCust RUN NewCust in hPub. 
WAIT-FOR CHOOSE OF bQuit OR WINDOW-CLOSE OF CURRENT-WINDOW.

The publisher, r-nepub.p, publishes the event NewCustomer:

r-nepub.p
/* r-nepub.p / PROCEDURE NewCust: DEFINE VARIABLE name AS CHARACTER NO-UNDO INITIAL "Sam". / Let subscriber know new customer */ PUBLISH "NewCustomer" (INPUT name). END PROCEDURE.

The first subscriber, nesub1.p, subscribes to the event NewCustomer:

r-nesub1.p
/* r-nesub1.p */ DEFINE INPUT PARAMETER hPub AS HANDLE NO-UNDO. SUBSCRIBE TO "NewCustomer" IN hPub. PROCEDURE NewCustomer: DEFINE INPUT PARAMETER name AS CHARACTER NO-UNDO. MESSAGE "Subscriber 1 received event NewCustomer concerning" name VIEW-AS ALERT-BOX. END.

r-nesub1.p

/* r-nesub1.p */ 
DEFINE INPUT PARAMETER hPub AS HANDLE NO-UNDO. 
SUBSCRIBE TO "NewCustomer" IN hPub. 
PROCEDURE NewCustomer: 
  DEFINE INPUT PARAMETER name AS CHARACTER NO-UNDO. 
  MESSAGE "Subscriber 1 received event NewCustomer concerning" name 
    VIEW-AS ALERT-BOX. 
END.

The second subscriber, nesub2.p, already subscribed to the event NewCustomer, cancels all subscriptions:

r-nesub2.p
/* r-nesub2.p / PROCEDURE NewCustomer: DEFINE INPUT PARAMETER name AS CHARACTER NO-UNDO. MESSAGE "Subscriber 2 received event NewCustomer concerning" name VIEW-AS ALERT-BOX. / This subscriber receives the first event, then removes itself */ UNSUBSCRIBE TO ALL. END.

r-nesub2.p

/* r-nesub2.p */ 
PROCEDURE NewCustomer: 
  DEFINE INPUT PARAMETER name AS CHARACTER NO-UNDO. 
  MESSAGE "Subscriber 2 received event NewCustomer concerning" name 
    VIEW-AS ALERT-BOX. 
  /* This subscriber receives the first event, then removes itself */ 
  UNSUBSCRIBE TO ALL. 
END.

To start the example, run the driver, r-nedrvr.p.

Notes

If a named event has multiple subscribers, the order in which the AVM notifies subscribers is undefined.

INPUT-OUTPUT parameters can accumulate values from a set of subscribers. When a subscriber receives an INPUT-OUTPUT parameter, it has the value that the previous subscriber set it to. When the publisher receives an INPUT-OUTPUT parameter, it has the value that the last subscriber set it to.

If a named event with multiple subscribers has OUTPUT parameters, each time a subscriber sets an OUTPUT parameter, the AVM overwrites the previous value. For this reason, Progress Software Corporation recommends that you use OUTPUT parameters with named events only when there is a single subscriber.

If a named event has multiple subscribers and several subscribers specify a RETURN statement with a return value, the RETURN-VALUE function evaluates to the return value set by the last subscriber.

The AVM executes the PUBLISH statement with an implicit NO-ERROR option. To find out if any errors occurred, and if so, which ones, use the ERROR-STATUS system handle.

If publisher-handle is a handle, the value of SOURCE-PROCEDURE in each of the subscribers’ internal procedures will be the handle of the procedure that created the widget.