PK_BB_output_events

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 (>= 0)
int           **const events,       --- events to which entities
                                    --- belong (optional)
PK_ENTITY_t   **const entities,     --- entities (optional)
PK_BB_event_t **const event_types,  --- event types (optional)
PK_CLASS_t    **const classes,      --- classes of entities (optional)
int           **const user_fields   --- user fields (optional)
)


This function outputs the events stored in the bulletin board


Specific Errors:
    PK_ERROR_bb_is_off        (MILD) 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 entities 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'.

See also Output of bulletin board information for more information.