OUBBEV ( empty, nevent, events, nperev, nents, ents, enttyp, usflds, ifail )
============================================================================

  Output full bulletin board information.

Receives:
  KI_cod_logical           *empty          --- true if bulletin board is to
                                           --- be emptied after being output

Returns:
 <KI_int_nitems>           *nevent         --- no of recorded events
 <KI_tag_list_int>         *events         --- recorded event tokens
 <KI_tag_list_int>         *nperev         --- no of entities at each event
 <KI_int_nitems>           *nents          --- total no of entities recorded
 <KI_tag_list_tag>         *ents           --- entities recorded
 <KI_tag_list_int>         *enttyp         --- entity types
 <KI_tag_list_int>         *usflds         --- entity user fields
  KI_cod_error             *ifail          --- error code

Specific errors:
  KI_bulletinb_is_off       cannot read bulletin board when it is off

Description:
  Outputs bulletin board information on events occurring to entities since
  the bulletin board was last emptied.  Depending on the value
  of 'empty', optionally empties the bulletin board after reading it.

  The bulletin board data is returned as a list of events and associated with
  each event there are the tags and types of the entities involved, the
  number of entities involved and optionally the user-field of each entity.

  Whether user-field data is returned depends on the setting of the
  user-field option in SEBBCO. When user-field data is not returned, the
  list 'usflds' is returned as the NULTAG.

  The list 'events' contains 'nevent' tokens from the sequence BBEV00.  The
  list 'nperev' contains 'nevent' integers which specify the number of
  entities involved in an event.  The event and number per event are in
  corresponding positions in the lists 'events' and 'nperev'.

  The list 'ents' contain 'nents' tags.  These are the tags of the entities
  which have been recorded on the bulletin board. The list 'enttyp' contains
  'nents' tokens from the sequences TYTO00, TYGE00 and TYAD00. The token
  returned in the 'enttyp' list is the type of entity in the corresponding
  position in the 'ents' list.

  The postion of the entities corresponding to the event in entry number "n"
  of the 'events' list can be found by summing the first "n-1" entries of the
  'nperev' list and adding 1.  The value in the "n"th entry of the 'nperev'
  list is the number of entities involved in the event in entry number "n"
  of the 'events' list.

  The list 'usflds' contains "'nents' * ufd_size" integers where ufd_size is
  the user-field size as set by STAMOD. The user-field of the entry number
  "n" in the 'ents' list can be found in entries "(n-1)*ufd_size+1" to
  "n*ufd_size" inclusive.


  The events merge, split, copy and transfer (types BBEVME, BBEVSP, BBEVCO
  and BBEVTR respectively) all have more than one entity associated with them.
  These are in the order:

    o Merge    - first entity is the entity which is dominant and remains
                 other entities are those which were deleted as part of the
                 operation
    o Split    - first entity is the entity which was originally split
                 other entities are those which were created as part of the
                 operation
    o Copy     - first entity is the new entity
                 other entity is the entity of which the previous is a copy
    o Transfer - first entity is the entity transferred
                 other entity is the entity which was previously its owner


  Two records of the bulletin board may be merged into one under certain
  circumstances.  These are that the events are both of the types
  create (BBEVCR), delete (BBEVDE), change (BBEVCH), transform (BBEVTF),
  transfer (BBEVTR) or attribute change (BBEVAC) and that the events
  are consecutive (that is, no other event has happened to the entity prior
  to the second event and after the first event).

                |                  Second event
   First event  | Created  Changed  Transformed  Deleted  Transferred  Att Ch
   -------------+------------------------------------------------------------
                |
     Created    |   (1)    Created   Created       (2)      Created    Created
                |
     Changed    |   (1)    Changed     (3)       Deleted      (3)        (3)
                |
   Transformed  |   (1)      (3)    Transformed  Deleted      (3)        (3)
                |
     Deleted    |   (1)      (1)       (1)         (1)        (1)        (1)
                |
    Transferred |   (1)      (3)       (3)       Deleted   Transferred   (3)
                |
     Att Ch     |   (1)      (3)       (3)       Deleted      (3)       Att Ch

      where:
                  (1) this case cannot occur.
                  (2) the entity will be removed from the bulletin board
                      entirely.
                  (3) both events will be bulletined.

  All entries made since the bulletin board was last emptied will be checked
  in this way.