3 Examples of Using the NBS Routines

This section takes the form of a tutorial. Starting with a listing of a noticeboard contents, we present the calls necessary to define that noticeboard, to put the required values into it and for another process to access those values.

Suppose that we wish to create and access a simple noticeboard. We will use as an example a subset of the noticeboard that is maintained by the AUTOFIB control software. The notation used is the same as that used by the NBTRACE (Trace Noticeboard) program (see Section C.1) — each structure entry is of the form:

and each primitive entry is of the form:

with appropriately indented entries. The shape information is shown only if the maximum number of dimensions (maxd) is greater than zero. The three slash-separated numbers are actual number of bytes, maximum number of bytes and modified count.

The result of running NBTRACE on this noticeboard might be:

• Type and shape have no significance to the NBS routines — the type is just a character string and the shape is just a list of numbers. In the above, HDS primitive type conventions have been used and this allows a sensible representation of values. Remember though that it is the NBTRACE program that is making use of the type information, not the NBS routines.
• The initial state of an item is that the actual number of bytes and the modified count are both zero. CURRENT_STATUS above is in its initial state.
• It is possible to give an item a shape during the definition phase so an item can initially have a non-scalar shape.
• The noticeboard modified count is incremented just after updating any item in the noticeboard. An “update” may be an update of an item’s value, its shape or its size.
• An item’s modified count is incremented just before updating an item and just afterwards. Thus if it is odd then an item is in the process of being updated, and the number of completed updates is MODIFIED / 2. An “update” may be an update of either an item’s value or its shape.
• You can use the NBS_GET_UPDATED routine to determine whether a noticeboard or a specific item has been updated since the last call to NBS_GET_UPDATED.

3.1 Defining the Noticeboard Contents

The following Fortran-like calls will define the contents of the above noticeboard and save the definition in a disc file.

Begin the noticeboard definition.

Define the primitive item CURRENT_CONFIG. This is a character string of maximum length 132 bytes. We choose to regard it as a scalar.

Define the primitive item CURRENT_STATUS. This is a 1D array of 72 64 byte records.

Define the structured item FIBRE_PARAMETERS. Structured items cannot have shapes or values.

Define the lower-level primitive item TRANS_MATRIX. This is a 2D array of 2 x 2 integers.

End the definition, writing to file AUTOFIB.NBD.

• All of the routines used during the definition phase are called NBS_*_DEFINITION
  or NBS_DEFINE_*.

3.2 Creating the Noticeboard

Having defined the noticeboard contents, the actual noticeboard must be created. There are three ways of doing this, depending on whether the definition is being read from a file, the definition plus data is being read from a file (this is illustrated in Section 3.7), or the noticeboard is being created in memory.

Restore the noticeboard definition from a file and create the noticeboard …

…or, instead of issuing the above NBS_END_DEFINITION call, issue this one.

• Regardless of which method is used, the situation is the same after either of these calls. The former would normally be used if the noticeboard definition had been compiled earlier by another program and the latter would be used if the noticeboard had just been defined and if no noticeboard definition file was required.
• The noticeboard now exists and is owned by this process. All items in it have an actual size of zero and a modified count of zero.

3.3 Finding the Noticeboard

Any process that wants to use a noticeboard must map it. This is done in precisely the same way by both the noticeboard owner and any other processes wishing to use it.

Map (find) the noticeboard.

• This is the first NBS routine that a non-owner need call.
• It does no harm to make multiple calls to this routine, but each call will map the noticeboard into a new part of virtual memory (on VMS only — the UNIX version will return the same virtual memory address) and will return a different ID.
• This TOPID is not the same as the TOPSID returned by the NBS_BEGIN_DEFINITION routine. Static identifiers are used only during the definition phase and we are no longer in this phase.

3.4 Putting Values into the Noticeboard

We can now put values into primitive items.

Get the IDs for all the items we want to write to.

Put values to some of them.

• Normally one would get IDs for the items of interest just after finding the noticeboard. Finding an item involves a search and is relatively slow, whereas putting and getting a value is very fast.
• The second parameter to NBS_PUT_VALUE and NBS_PUT_CVALUE is a byte offset. You can use non-zero offsets to put a slice of the data associated with an item. The current size of an item’s data is the high-water mark of all PUTs. You can use NBS_PUT_SIZE explicitly to set the size of an item’s data.
• Because the NBS routines don’t use the type information, it is necessary to pass all values by reference. In Fortran this is the default passing mechanism for all variables except for character strings, hence the routine NBS_PUT_CVALUE to handle this case.
• However, on VMS only the %REF function enables the user to pass the actual character pointer to NBS_PUT_VALUE, and supply the length of the character string (or indeed, any other number) as the maximum number of bytes to be read.
• The noticeboard is now in the same state as in the listing at the start of this section. If another process ran NBTRACE at this stage, it would get precisely the same output.

3.5 Getting values from the Noticeboard

Values can be accessed either by copying to and from the user’s buffer or else directly to and from the noticeboard. Both methods are illustrated here.

Get current value of MATRIX. We expect the actual number of bytes to be at least 16.

Again, reading character strings is slightly different,

Alternatively get a pointer to the actual data in the noticeboard.

• The second parameter to NBS_GET_VALUE and NBS_GET_CVALUE is a byte offset. You can use non-zero offsets to get a slice of the data associated with an item.
• The length of the string passed into NBS_GET_CVALUE serves the same purpose as the third argument to NBS_GET_VALUE — ie. it limits the amount of data that can be read.
• It is not an NBS error if an item contains fewer bytes than are being asked for.
• When accessing data directly via pointer, no checks are possible and the modified count is not (and could not be) accessed.

3.6 Finding out about Items

There is a complete set of enquiry routines that allow programs that know nothing about a noticeboard to navigate through it. NBTRACE is just such a program. A few of these routines are illustrated here.

• Higher-level routines may wish to check consistency between shape, size and type. For example, in the above we expect ACTBYTES to be 4 (the number of bytes per pixel) times the product of the dimensions.

3.7 Saving and Restoring of Values

It is possible to save and restore the noticeboard data as well as just the definition by using a different option when ending the noticeboard definition.

End the definition, writing it and the noticeboard data to file AUTOFIB.NBD.

Restore the noticeboard definition plus data from a file and create the noticeboard.

Map (find) the noticeboard.

Get the ID for an item we want to write to and put its value.

Save the noticeboard to disc.

• NBS_RESTORE_NOTICEBOARD can be used to restore from a file that contains only a definition as well as from a file that contains a definition plus data. However if a file does not contain data the NBS__DATANOTSAVED warning status is returned — this indicates that the noticeboard has been created but that it is in its initial state.
• NBS_RESTORE_DEFINITION cannot be used to restore from a file that contains data in addition to a definition. In cases where both sorts of file are to be accessed, use NBS_RESTORE_NOTICEBOARD.
• The implementation of NBS_SAVE_NOTICEBOARD is inefficient in that the entire definition plus data is copied to disc. Under operating systems that support the mapping of files into virtual memory it could be implemented using an “update section” call.
• NBS_SAVE_NOTICEBOARD does not create a new version of the noticeboard definition file; it always overwrites the data in the file from which it was restored.

3.8 Losing Noticeboards

Noticeboards can be explicitly lost (unmapped). Often you will not need to worry about this and will be happy to allow them to be unmapped on image exit. Sometimes, however, you may require explicit control. Note though that a noticeboard is not actually deleted until the last process unmaps it.

Find a noticeboard and an item within it.

Lose the item and the noticeboard.

Alternatively, if you like living dangerously, try this.

• FIND and LOSE calls are normally paired. If the CHECK flag is given, you can only lose items and noticeboards for which all derived IDs have already been lost.
• If you know that there is no chance that any of a noticeboard’s or item’s derived IDs will be used, you can specify the FORCE flag. This allows the item or noticeboard to be lost regardless of whether any derived IDs are still in use.