next up previous 372
Next: NBS_PUT_CVALUE - Put a character string into a slice of a primitive item associated with a specified identifier
Up: Description of Individual NBS Routines
Previous: 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

Description:
Check that the ID is not NIL and that it pertains to a primitive item.
Check that the caller owns the noticeboard (or WORLD_WRITE is TRUE).
Check that the offset into the data is not negative.
Check that the item is large enough to accept all of the supplied values.
Increment the item's modified count.
Update the item size (maintain a high-water mark).
Copy the values to the noticeboard.
Increment the item's modified count again.
Increment the noticeboard modified count.

The item and noticeboard modified counts will not be incremented if INCREMENT_MODIFY is FALSE.

Note that this routine only alters the specified number of bytes starting at the specified offset -- all bytes are initially zero and bytes above and below those that are being altered will not be affected. The actual size of the item will be adjusted upwards if the new data extends past the previous end of the data but the size of the item cannot be decreased by this routine. To alter the size of an item, use the NBS_PUT_SIZE routine.


Invocation:
(Int) = NBS_PUT_VALUE (ID,OFFSET,NBYTES,BYTE_ARRAY,STATUS)

Arguments:

ID = INTEGER (Given)
Identifier of the item which the value is to be put.
OFFSET = INTEGER (Given)
Byte offset into item data.
NBYTES = INTEGER (Given)
Number of bytes to put.
BYTES = BYTE(*) (Given)
Bytes to be put.
STATUS = INTEGER (Given and returned)
The global status. Possible return values are,

NBS__NILID   		 NIL ID 

NBS__NOTPRIMITIVE Item is not primitive
NBS__NOTOWNER Caller does not own the noticeboard
NBS__BADOFFSET Negative offset specified
NBS__TOOMANYBYTES Not room to put all the data

Notes:
In versions prior to {V2.4.0} this routine could be used to write character strings on the VAX using the %REF() mechanism to pass the character data. A new routine, NBS_PUT_CVALUE, has been provided to remove the need for %REF and make the method portable.


next up previous 372
Next: NBS_PUT_CVALUE - Put a character string into a slice of a primitive item associated with a specified identifier
Up: Description of Individual NBS Routines
Previous: NBS_LOSE_ITEM - Declare an intention never again to use a specified item

NBS The Noticeboard System
Starlink User Note 77
D.J. Allan
11 September 1995
E-mail:ussc@star.rl.ac.uk