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. They are also different from the class events described in the Class Events Reference.

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.

Examples

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.

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.

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.

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

Notes

See also

Publish( ) event method, PUBLISHED-EVENTS attribute, SUBSCRIBE statement, UNSUBSCRIBE statement