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

Description:

      Check that the ID is not NIL and that it pertains to a primitive item. 

Check that the offset into the data is not negative.
Repeat
{
Read the modified count for this item.
Copy as many bytes as there is room for in the user's buffer from the noticeboard starting
at the specified offset and return the actual number of bytes in the item.
Read the modified count for this item once more.
}
Until time out or the two modified counts are equal and even
(which means that the values were not updated whilst they were being read).

If CHECK_MODIFY is FALSE, the item's modified count is not checked at all and a timeout cannot occur.

If the specified offset is greater than the current size of the item's data, no error status will be returned and no data will be copied, but the returned number of bytes (ACTBYTES) will be less than the offset (OFFSET) and this case should always be checked for.


Invocation:
(Int) = NBS_GET_VALUE (ID,OFFSET,MAXBYTES,BYTE_ARRAY,ACTBYTES,STATUS)

Arguments:

ID = INTEGER (Given)
Identifier of the item from which thew value is to be got.
OFFSET = INTEGER (Given)
Byte offset into item data.
MAXBYTES = INTEGER (Given)
Size in bytes of the user's buffer.
BYTE_ARRAY = BYTE(*) (Returned)
User's buffer into which bytes will be got.
ACTBYTES = INTEGER (Returned)
Actual number of values associated with the item. This may be greater than OFFSET + MAXBYTES but no more than MAXBYTES bytes will be copied into the user's buffer.
STATUS = INTEGER (Given and returned)
The global status. Possible return values are,

NBS__NILID   		 NIL ID 

NBS__NOTPRIMITIVE Item is not primitive
NBS__BADOFFSET Negative offset specified
NBS__TIMEOUT Timeout awaiting valid data



next up previous 372
Next: NBS_GET_CVALUE - Get a character string from a slice of a primitive item associated with the specified identifier
Up: Description of Individual NBS Routines
Previous: NBS_PUT_TRIGGER - Specify a routine to be called whenever a primitive item is updated

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