$Buffer Used: Difference between revisions

From m204wiki
Jump to navigation Jump to search
No edit summary
No edit summary
 
(11 intermediate revisions by 2 users not shown)
Line 5: Line 5:
<p class="code">$Buffer_Used
<p class="code">$Buffer_Used
</p>
</p>
<b>Where</b>
<b>
<p>The $Buffer_Used function returns the following values:</p>
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>After a MODIFY BUFFER CLEAR</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 or image </td>
<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 $Buffer_Used: otherwise, it is unchanged.</td>
<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 User Language or MQ/204 statement</td>
<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 $Buffer_Used point. For example, when executing:</p>
<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 $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>
<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 $Buffer_Used position. The data is copied to the nominated part of the BUFFER area, and $Buffer_Used is adjusted accordingly. </p>
<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.