$Buffer Used: Difference between revisions
m (minor cleanup) |
No edit summary |
||
| (10 intermediate revisions by the same user not shown) | |||
| Line 16: | Line 16: | ||
<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 <code>MODIFY BUFFER CLEAR</code></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 <code>AUTOCOMMIT=NO</code></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 <var>MQGET</var></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> | ||
| Line 46: | Line 46: | ||
<tr> | <tr> | ||
<td>After an <var>MQPUT/MQPUT1</var> <i>%variable</i>/<i>image</i> </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 <var>BUFFER</var> area.</td> | <td>Number of bytes copied into the <var>[[MQ/204_and_SOUL_statements#Universal_Buffer_statements|BUFFER]]</var> area.</td> | ||
</tr> | </tr> | ||
| Line 56: | Line 56: | ||
<tr> | <tr> | ||
<td>After <code>WRITE IMAGE ON BUFFER</code></td> | <td>After <code>[[Images#WRITE_IMAGE_statement|WRITE IMAGE ON BUFFER]]</code></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> | <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> | ||
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.