$Buffer_Used

From m204wiki
Revision as of 12:43, 15 January 2018 by DCameron (talk | contribs)
Jump to navigation Jump to search

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.