$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.