$Buffer Used

Function

Returns how much of the Universal Buffer currently contains data.

Syntax

$Buffer_Used

Where:

The $Buffer_Used function returns the following values:

If...	Value returned is...
Universal Buffer is not in use or MQ/204 is not linked in.	-1
After a MODIFY BUFFER CLEAR	0
At the start of a request running in an APSY subsystem with AUTOCOMMIT=NO	Same as the value at the end of the previous request, or 0, if this is the first request.
After an MQGET	Number of bytes of the message.
After an MQGET that returned a truncated message or failed	Less than the actual message length.
After a successful MQGET, but data was truncated when copying into the target %variable or image truncated	Greater than the length of data in the target.
After an MQPUT/MQPUT1 %variable/image	Number of bytes copied into the BUFFER area.
After an MQPUT/MQPUT1 BUFFER	Unchanged.
After WRITE IMAGE ON BUFFER	Point written to by the WRITE IMAGE, if data was written past the previous $Buffer_Used: otherwise, it is unchanged.
After a MODIFY BUFFER NOPRESERVE	0
After a MODIFY BUFFER PRESERVE	New size of the BUFFER area, if the size was reduced, or unchanged if the size stayed the same or increased.
Any other SOUL or MQ/204 statement	Unchanged.

Examples

Most operations that access the BUFFER area, implicitly or explicitly, only access the buffer up to the $Buffer_Used point. For example, when executing:

READ IMAGE FROM BUFFER POSITION=%pvariable MAXLEN=%lvariable

Only data up to the $Buffer_Used position is returned to the image. If the starting position plus the length refers to data past the $Buffer_Used position, the full length requested is not returned, because not that much data is available.

The only exception to this rule is when executing the following:

WRITE IMAGE ON BUFFER POSITION=%pvariable MAXLEN=%lvariable

The starting position plus the length can refer to the part of the BUFFER area past the $Buffer_Used position. The data is copied to the nominated part of the BUFFER area, and $Buffer_Used is adjusted accordingly.