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.