$Buffer Used: Difference between revisions
Jump to navigation
Jump to search
No edit summary |
No edit summary |
||
| (14 intermediate revisions by 4 users not shown) | |||
| 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> | ||
<p>The $ | Where:</b> | ||
<p> | |||
The <var>$Buffer_Used</var> function returns the following values:</p> | |||
<table> | <table> | ||
<tr class="head"> | <tr class="head"> | ||
| Line 12: | Line 14: | ||
<th>Value returned is...</th> | <th>Value returned is...</th> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>Universal Buffer is not in use or MQ/204 is not linked in.</td> | <td>Universal Buffer is not in use or [[MQ/204_overview|MQ/204]] is not linked in.</td> | ||
<td align="right">-1</td> | <td align="right">-1</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td> | <td>After a <code>[[Images#MODIFY_BUFFER_statement|MODIFY BUFFER CLEAR]]</code></td> | ||
<td align="right">0</td> | <td align="right">0</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>At the start of a request running in an APSY subsystem with AUTOCOMMIT=NO</td> | <td>At the start of a request running in an [[Application_Subsystem_development|APSY]] subsystem with <code>AUTOCOMMIT=NO</code></td> | ||
<td>Same as the value at the end of the previous request, or 0, if this is the first request.</td> | <td>Same as the value at the end of the previous request, or 0, if this is the first request.</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>After an MQGET</td> | <td>After an <var>[[MQ/204_and_SOUL_statements#MQGET_statement|MQGET]]</var></td> | ||
<td>Number of bytes of the message. </td> | <td>Number of bytes of the message. </td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>After an MQGET that returned a truncated message or failed</td> | <td>After an <var>MQGET</var> that returned a truncated message or failed</td> | ||
<td>Less than the actual message length.</td> | <td>Less than the actual message length.</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>After a successful MQGET, but data was truncated when copying into the target %variable or image truncated</td> | <td>After a successful <var>MQGET</var>, but data was truncated when copying into the target %variable or image truncated</td> | ||
<td>Greater than the length of data in the target.</td> | <td>Greater than the length of data in the target.</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>After an MQPUT/MQPUT1 %variable | <td>After an <var>[[MQ/204_and_SOUL_statements#MQPUT_statement|MQPUT]]/[[MQ/204_and_SOUL_statements#MQPUT1_statement|MQPUT1]]</var> <i>%variable</i>/<i>image</i> </td> | ||
<td>Number of bytes copied into the BUFFER area.</td> | <td>Number of bytes copied into the <var>[[MQ/204_and_SOUL_statements#Universal_Buffer_statements|BUFFER]]</var> area.</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>After an MQPUT/MQPUT1 BUFFER</td> | <td>After an <code>MQPUT/MQPUT1 BUFFER</code></td> | ||
<td>Unchanged.</td> | <td>Unchanged.</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>After WRITE IMAGE ON BUFFER</td> | <td>After <code>[[Images#WRITE_IMAGE_statement|WRITE IMAGE ON BUFFER]]</code></td> | ||
<td>Point written to by the WRITE IMAGE, if data was written past the previous $ | <td>Point written to by the <var>WRITE IMAGE</var>, if data was written past the previous <var>$Buffer_Used</var>: otherwise, it is unchanged.</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>After a MODIFY BUFFER NOPRESERVE</td> | <td>After a <code>MODIFY BUFFER NOPRESERVE</code></td> | ||
<td align="right">0</td> | <td align="right">0</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>After a MODIFY BUFFER PRESERVE</td> | <td>After a <code>MODIFY BUFFER PRESERVE</code></td> | ||
<td>New size of the BUFFER area, if the size was reduced, or unchanged if the size stayed the same or increased.</td> | <td>New size of the <var>BUFFER</var> area, if the size was reduced, or unchanged if the size stayed the same or increased.</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>Any other | <td>Any other SOUL or MQ/204 statement</td> | ||
<td>Unchanged.</td> | <td>Unchanged.</td> | ||
</tr> | </tr> | ||
</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 <var>BUFFER</var> area, implicitly or explicitly, only access the buffer up to the <var>$Buffer_Used</var> 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> | ||
<p>The only exception to this rule is when executing the following: </p> | Only data up to the <var>$Buffer_Used</var> position is returned to the image. If the starting position plus the length refers to data past the <var>$Buffer_Used</var> position, the full length requested is not returned, because not that much data is available.</p> | ||
<p class="code">WRITE IMAGE ON BUFFER POSITION=%pvariable | <p> | ||
MAXLEN=%lvariable | The only exception to this rule is when executing the following: </p> | ||
<p class="code">WRITE IMAGE ON BUFFER POSITION=<i>%pvariable</i> | |||
MAXLEN=<i>%lvariable</i> | |||
</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 <var>BUFFER</var> area past the <var>$Buffer_Used</var> position. The data is copied to the nominated part of the <var>BUFFER</var> area, and <var>$Buffer_Used</var> is adjusted accordingly. </p> | |||
[[Category:SOUL $functions]] | [[Category:SOUL $functions]] | ||
Latest revision as of 12:48, 15 January 2018
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.