All names and types are converted to upper-case and all white space and non-printing characters in
them are ignored. Thus “ William Lupton ” is regarded as “WILLIAMLUPTON”. An upper limit of 16
characters is imposed on both names and types (the limit applies to the length after the removal of
white space and non-printing characters).
Provided there is only one writer to a noticeboard and the standard get and put routines are used, the routines will guarantee that consistent data is read from the noticeboard. A writer will never have to wait but a reader will retry potentially until a timeout occurs.
A (deliberate) restriction of the noticeboard system is that a noticeboard is static in structure.
Its structure must be defined before any values are put into it and once the definition is
complete no more items can be created. There are a set of routines called NBS_DEFINE_* and
NBS_*_DEFINITION which allow definition of noticeboard contents, saving definitions to and restoring
them from file (the initial state of a noticeboard is that all items have zero length values).
Only once the definition phase is complete can the NBS_PUT_* and NBS_GET_* routines be
used.
The initial reason for this was efficiency. However it is not in fact particularly difficult to allow new
items to created on the fly without compromising efficiency and this restriction should be seen more
as a way of preventing the noticeboard routines from being used for purposes for which they were not
designed and for which better tools (such as HDS) exist. Note that this “static” restriction refers only to
the creation of items in the noticeboard. It is always possible to change item shapes and
values.
When saving a noticeboard to disc, the programmer has a choice as to whether to save only the
definition or else the definition plus the data. If only the definition is saved then each time that the
definition is restored all items will revert to having zero lengths. However if the data is saved as
well the NBS_RESTORE_NOTICEBOARD routine can be used to restore both the definition and
the data, and a subsequent call to NBS_SAVE_NOTICEBOARD will update the disc file so that
the next time that the noticeboard is restored it will be in the same state as when it was
saved.
The NBS routines have been implemented to make them easy to use from Fortran, and for this reason
all character strings are passed as standard Fortran character arguments (address of VMS descriptor on
VMS, character pointer with trailing hidden length argument on most other architectures) and all other
parameters are passed by reference.
The routines are actually written in C and it would be unreasonable and wasteful to force C
programmers to build descriptors just so that they could be decoded back to the same C strings that
they started off as. For this reason, every NBS routine (except a few which handle character strings) has
an associated NBC routine which passes all character parameters as C zero-terminated strings, all input
scalar parameters by value and all other parameters by reference. See the source of the
demonstration programs described in Appendix C for examples of the use of this C-callable
version.
NBS V2.4 was the first version of NBS to be fully portable to UNIX – V2.2 onwards was written portably
but had several deficiencies and bugs. The shared memory services of UNIX System V are sufficiently
close to the VMS global section system services to require only a small amount of conditionally
compiled code in the low-level “create section” and “map section” routines. There are
however two limitations which may affect users planning to use the software on UNIX
platforms.
UNIX does not permit a process to have a shared memory
segment mapped more than once the process’s address space. NBS has been written to take
account of this and will always return the same address in a request to map a noticeboard
once it is mapped the first time. It does however keep a reference count, and will not
unmap a noticeboard until this drops to zero.
UNIX is a four byte integer. NBS therefore hashes the user supplied name into this integer.
The algorithm for doing this is much improved in V2.5.5 but it is still not proof against
different names mapping on to the same key value.All the NBS routines use ADAM modified status conventions in that they will do nothing if status is
not NBS__OK (0) on entry. They can all optionally be called as functions, in which case the
function value is the same as the returned status value. In all cases where an NBS routine is the
source of the error, an error report will be made using the error and message reporting
service.
These routines use the terminology “item” to refer to either a structured noticeboard object (ie, one
with no values but possibly having lower-level objects) or to a primitive noticeboard object
(ie, one with a shape and with values). The terms “item identifier”, “identifier” or “ID”
refer to “handles” (cf HDS locators) which allow access to all information pertaining to
an item. As far as callers are concerned these are just integers. As far as the noticeboard
system is concerned they are pointers to data structures called “item_descriptor”s. In the
routine specifications they are regarded as integers. A zero ID is always an invalid ID and
all routines will detect an attempt to use a zero ID. Similarly all routines that return ID’s
will return zero ID’s on failure. Note that there is a danger of an access violation if true
garbage ID’s are passed. This is unlikely to happen, because of the use of the modified status
convention.