$Buffer Used: Difference between revisions
Jump to navigation
Jump to search
m (Mlarocca moved page $BUFFER USED to $Buffer Used: Lower case change) |
No edit summary |
||
| Line 1: | Line 1: | ||
{{DISPLAYTITLE:$ | {{DISPLAYTITLE:$Buffer_Used}} | ||
<b>Function</b> | <b>Function</b> | ||
<p>Returns how much of the Universal Buffer currently contains data. </p> | <p>Returns how much of the Universal Buffer currently contains data. </p> | ||
<b>Syntax</b> | <b>Syntax</b> | ||
<p class="code">$ | <p class="code">$Buffer_Used | ||
</p> | </p> | ||
<b>Where</b> | <b>Where</b> | ||
<p>The $ | <p>The $Buffer_Used function returns the following values:</p> | ||
<table> | <table> | ||
<tr class="head"> | <tr class="head"> | ||
| Line 46: | Line 46: | ||
<tr> | <tr> | ||
<td>After WRITE IMAGE ON BUFFER</td> | <td>After WRITE IMAGE ON BUFFER</td> | ||
<td>Point written to by the WRITE IMAGE, if data was written past the previous $ | <td>Point written to by the WRITE IMAGE, if data was written past the previous $Buffer_Used: otherwise, it is unchanged.</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
| Line 62: | Line 62: | ||
</table> | </table> | ||
<b>Examples</b> | <b>Examples</b> | ||
<p>Most operations that access the BUFFER area, implicitly or explicitly, only access the buffer up to the $ | <p>Most operations that access the BUFFER area, implicitly or explicitly, only access the buffer up to the $Buffer_Used point. For example, when executing:</p> | ||
<p class="code">READ IMAGE FROM BUFFER POSITION=%pvariable | <p class="code">READ IMAGE FROM BUFFER POSITION=%pvariable | ||
MAXLEN=%lvariable | MAXLEN=%lvariable | ||
</p> | </p> | ||
<p>Only data up to the $ | <p>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.</p> | ||
<p>The only exception to this rule is when executing the following: </p> | <p>The only exception to this rule is when executing the following: </p> | ||
<p class="code">WRITE IMAGE ON BUFFER POSITION=%pvariable | <p class="code">WRITE IMAGE ON BUFFER POSITION=%pvariable | ||
MAXLEN=%lvariable | MAXLEN=%lvariable | ||
</p> | </p> | ||
<p>The starting position plus the length can refer to the part of the BUFFER area past the $ | <p>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. </p> | ||
[[Category:SOUL $functions]] | [[Category:SOUL $functions]] | ||
Revision as of 13:36, 14 July 2014
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 or 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 User Language 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.