14

SUN/77.8

Starlink Project
Starlink User Note 77.8

D.J. Allan

11 September 1995

NBS
The Noticeboard System

Version 2.5.5

Programmer’s Manual


Abstract

This document describes Version 2.5.5 of the Noticeboard System. It is aimed at programmers interested in or intending to use the system and contains all information necessary to use it.

Contents

1 Introduction
2 General Description
 2.1 Names and Types
 2.2 Data Consistency
 2.3 Static Definition
 2.4 Saving to Disc
 2.5 C-callable Version
 2.6 Portability to UNIX
 2.7 Status Conventions
 2.8 Terminology
3 Examples of Using the NBS Routines
 3.1 Defining the Noticeboard Contents
 3.2 Creating the Noticeboard
 3.3 Finding the Noticeboard
 3.4 Putting Values into the Noticeboard
 3.5 Getting values from the Noticeboard
 3.6 Finding out about Items
 3.7 Saving and Restoring of Values
 3.8 Losing Noticeboards
4 Compiling and Linking Applications
 4.1 Compiling
 4.2 Linking on VMS
 4.3 Linking on UNIX
5 NBS Routines Listed by Category
 5.1 NBS_TUNE — Routines used to alter global noticeboard system parameters
 5.2 NBS_DEFINITION — Routines used to define the noticeboard structure
 5.3 NBS_FIND — Routines that find noticeboards and items within noticeboards
 5.4 NBS_LOSE — Routines that lose noticeboards and items within noticeboards
 5.5 NBS_PUT — Routines that write information to a noticeboard
 5.6 NBS_GET — Routines that read information from a noticeboard
6 Routine Timings
7 Omissions and Future Plans
 7.1 New Features
 7.2 Bug Fixes
A Description of Individual NBS Routines
NBS_TUNE–Alter the value of a global parameter
NBS_TUNE_NOTICEBOARD – Alter the value of a noticeboard-specific global parameter
NBS_BEGIN_DEFINITION – Begin definition of the contents of a noticeboard and return a static identifier to the top level of the noticeboard
NBS_DEFINE_STRUCTURE – Define a new entry for a structured item within another structured item and return a static identifier to the new item
NBS_DEFINE_PRIMITIVE – Define a new entry for a primitive item within another structured item and return a static identifier to the new item
NBS_DEFINE_SHAPE – Define an initial shape for a primitive item
NBS_END_DEFINITION – End the definition of a noticeboard and then create the noticeboard, save the definition in a file, or save the definition plus data in a file
NBS_RESTORE_DEFINITION – Restore a noticeboard definition from file and create the noticeboard
NBS_RESTORE_NOTICEBOARD – Restore a noticeboard definition and data from file and create the noticeboard
NBS_SAVE_NOTICEBOARD – Save a noticeboard to its noticeboard definition file
NBS_FIND_NOTICEBOARD – Find a named noticeboard and return an identifier to it
NBS_FIND_ITEM – Find an item with a specified name contained in a structure associated with a specified identifier and return the located item’s ID
NBS_FIND_NTH_ITEM – Find the Nth item contained in a structure associated with a specified identifier and return the located item’s ID
NBS_LOSE_NOTICEBOARD – Unmap a specified noticeboard
NBS_LOSE_ITEM – Declare an intention never again to use a specified item
NBS_PUT_VALUE – Put a byte array into a slice of a primitive item associated with a specified identifier
NBS_PUT_CVALUE – Put a character string into a slice of a primitive item associated with a specified identifier
NBS_PUT_SHAPE – Put a new shape to a primitive item associated with a specified identifier
NBS_PUT_SIZE – Put a new size to a primitive item associated with a specified identifier
NBS_INC_MODIFIED – Increment the noticeboard modified count or an item modified count depending on whether this is a structured or primitive item
NBS_PUT_TRIGGER – Specify a routine to be called whenever a primitive item is updated
NBS_GET_VALUE – Get a byte array from a slice of a primitive item associated with the specified identifier
NBS_GET_CVALUE – Get a character string from a slice of a primitive item associated with the specified identifier
NBS_GET_SHAPE – Get the shape of a primitive item associated with the specified identifier
NBS_GET_MODIFIED – Get the noticeboard modified count or an item modified count depending on whether this is a structured or primitive item
NBS_GET_MODIFIED_POINTER – Get a pointer to the noticeboard modified count or an item modified count depending on whether this is a structured or primitive item
NBS_GET_UPDATED – Determine whether a primitive item or the noticeboard has been updated since the noticeboard was found or this routine was last called
NBS_GET_POINTER – Return a pointer to the first byte of the data of a primitive item associated with the specified identifier
NBS_GET_NAME – Get the name of an item associated with the specified identifier
NBS_GET_TYPE – Get the type of an item associated with the specified identifier
NBS_GET_SIZE – Get the maximum and actual sizes of a primitive item associated with the specified identifier
NBS_GET_PRIMITIVE – Determine whether or not an item is primitive
NBS_GET_PARENT – Get the identifier of an item’s parent structure
NBS_GET_CHILDREN – Get the number of children of a structured item
NBS_GET_INFO – Get general non-character information on a given noticeboard
NBS_GET_CINFO – Get general character information on a given noticeboard

B NBS Error Codes
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