PK_ERROR_code_t       PK_BB_output_events
(
--- received arguments ---
PK_BB_t               bb,           --- not used
PK_LOGICAL_t          empty,        --- whether to empty bulletin board

--- returned arguments ---
int            *const n_entities,   --- number of entities
int           **const events,       --- events to which entities belong
PK_ENTITY_t   **const entities,     --- entities
PK_BB_event_t **const event_types,  --- event types
PK_CLASS_t    **const classes,      --- classes of entities
int           **const user_fields   --- user fields
)


This function outputs the events stored in the bulletin board


Specific Errors:
    PK_ERROR_bb_is_off             can not output events when bb is off


The received argument bb is not used.

The events recorded in the bulletin board since it was last empty are returned.
If empty is set to PK_LOGICAL_true, then all of these events are removed
from the bulletin board.

Events are returned in four parallel arrays of the same size n_entities
( user_fields is discussed below).  Each event involves one or more
entities.  All entites involved in an event are adjacent in the entities
array.  Each event is assigned an integer identifier, and these identifiers
are returned in the events array.  The event types are returned in the
event_types array (see documentation for PK_BB_event_t) and the classes
of the entities in classes.

For example: if a point is created and copied and the bulletin board has been
set to record these events then it would contain two events as follows:

    events    entities       event_types           classes

      0         249       PK_BB_event_create_c  PK_CLASS_point
      1         250       PK_BB_event_copy_c    PK_CLASS_point
      1         249       PK_BB_event_copy_c    PK_CLASS_point

event 0 is the creation of point 249 and event 1 is the copying of point
249 to point 250.

The events: PK_BB_event_merge_c, PK_BB_event_split_c, PK_BB_event_copy_c
and PK_BB_event_transfer_c all have more than one entity involved.  These
are in the order:

  PK_BB_event_merge_c:
      the first entity is the surviving entity and subsequent entities
      are those which were deleted in the event.

  PK_BB_event_split_c:
      the first entity is the entity which was split and subsequent entities
      are those which were created in this event.

  PK_BB_event_copy_c:
      the first entity is the newly created entity and the second entity is
      the original which was copied.

  PK_BB_event_transfer_c:
      the first entity is the entity whose ownership has been transferred
      and the second entity is the former owner.

If the current status of the bulletin board is PK_BB_status_user_field_c
then the user fields will be returned in the array user_fields.  The length
of user fields per entity is set in PK_SESSION_start_o_t and it can be
found by calling PK_SESSION_ask_user_field_len.  If the length of user fields
is u then the length of user_fields is u * n_entities.  Each u entries in
user_fields is asociated with an entity from entities.