C Demonstration Programs

 C.1 NBTRACE — Trace Noticeboard Contents
 C.2 TIME — Time Noticeboard Operations
 C.3 EXERCISE — Exercise Noticeboard Routines
 C.4 WORDS — Generate Tree-structured Noticeboard

Several demonstration programs are shipped with the system and are described here (it is assumed that the symbol “program” has been set up to run the program program). All of these programs are written in C.

C.1 NBTRACE — Trace Noticeboard Contents

NBTRACE lists the contents of a noticeboard definition file or of an active noticeboard.

The name of the definition file (assumed extension .NBD) or of a noticeboard item can be given as a command line parameter and will be prompted for if it is not given. The program first attempts to find the noticeboard and if that fails (because the noticeboard doesn’t exist) it attempts to restore the noticeboard from the definition file. Then it locates the specified item and lists it and all items below it. VMS-style wild cards can be used. Thus

  $ nbtrace gct.ifl.enq*

might result in the following

  Noticeboard data not restored because it was not saved
  STRUC    IFL (140)
    _CHAR    ENQ_DEV_DESCR   (0/132/0)
    _CHAR    ENQ_DEV_TYPE    (0/132/0)
    _CHAR    ENQ_VER_DATE    (0/132/0)
    _CHAR    ENQ_VER_NUM     (0/132/0)


  $ nbtrace gct.fits.*.x

is a useful trick to suppress listing of lower level items (on the assumption that none of them are called X).

  Noticeboard data not restored because it was not saved
  STRUC   FITS (15)
    DRT_STRUCT   RUN (3)

When no item name is given, general information about the noticeboard’s size and owner is given, as in

  $ nbtrace words
  Software version   = 5 (5)
  Size of section    = 1080 (438)
  Size of definition = 1080 (438)
  Noticeboard owner  = 2959 (b8f)
  Modified count     = 0 (0)
    WORD     BROWN   (0/0/0)
    WORD     DOG     (0/0/0)
    WORD     FOX     (0/0/0)
    WORD     JUMPS   (0/0/0)
    WORD     LAZY    (0/0/0)
    WORD     OVER    (0/0/0)
    WORD     QUICK   (0/0/0)
    WORD     THE     (0/0/0)
    WORD     THE     (0/0/0)

C.2 TIME — Time Noticeboard Operations

TIME times various noticeboard operations. It produced the timings listed in Section 6.

The user chooses how many items the noticeboard should contain, which item should be used for timing NBS_FIND_ITEM, how many iterations to perform and the values of the INCREMENT_MODIFY and CHECK_MODIFY flags. The program produces a report in TIME.LIS. For example:

  Noticeboard system timing program at Thu Mar 31 17:49:00 1988
  Number of iterations   = 10000
  Number of items        = 100
  Item used for searches = 100
  Increment modify flag  = 1
  Check modify flag      = 1
  Test 0, define, save and find noticeboard
         cpu microseconds = 2330000
  Test 1, scalar assignment
         cpu microseconds per iteration = 3
  Test 2, put scalar
         cpu microseconds per iteration = 124
  Test 3, get scalar
         cpu microseconds per iteration = 90

C.3 EXERCISE — Exercise Noticeboard Routines

EXERCISE calls all NBS routines and triggers all reasonable errors. It produces a report in EXERCISE.LIS in which any unexpected results have an asterisk in the first column. The total error count is reported at the bottom and this should always be zero. If it is non-zero there could be a resource-related problem (or even a bug in the NBS routines). For example:

  Noticeboard system exercise program at Thu Mar 31 10:28:55 1988
  nbs_tune max_defn_size: ok
  nbs_tune of doesnt_exist: illegal parameter / item name
  NBS_DEFINE_* errors
  nbs_define_structure: not currently defining noticeboard contents
  nbs_get_primitive: NIL item ID
  nbs_get_parent: NIL item ID
  nbs_get_children: NIL item ID
  nbs_get_children: item is primitive
  nbs_get_info: NIL item ID
  nbs_get_info: illegal parameter / item name
  Error count = 0

C.4 WORDS — Generate Tree-structured Noticeboard

WORDS generates a tree-structured noticeboard with one item for each word found in a file provided by the user. The user also specifies a “cluster size”, which is a measure of how deep the tree is (the tree has about log 2(cluster size) levels). Once the noticeboard has been created the user can type in words and is told whether they appeared in the file. Exit with ^Z. The example given for NBTRACE is of a noticeboard created using WORDS.