$FunsStr: Difference between revisions
m (1 revision) |
mNo edit summary |
||
| Line 1: | Line 1: | ||
{{DISPLAYTITLE:$FunsStr}} | {{DISPLAYTITLE:$FunsStr}} | ||
<span class="pageSubtitle"><section begin="desc" />Retrieve data from active | <span class="pageSubtitle"><section begin="desc" />Retrieve data from active [[Fast/Unload]] request into string<section end="desc" /></span> | ||
This retrieves data from an active ''[[Fast/Unload]]'' request into a string. | This retrieves data from an active ''[[Fast/Unload]]'' request into a string. | ||
The $FunsStr function accepts three arguments and returns a string result. | The $FunsStr function accepts three arguments and returns a string result. | ||
<ul> | <ul> | ||
<li>The first argument is the request identifier returned by $FunLoad for the request from which data is to be retrieved. This is a required argument. | <li>The first argument is the request identifier returned by $FunLoad for the request from which data is to be retrieved. This is a required argument. | ||
<li>The second argument is the column number in the current ''[[Fast/Unload]]'' record from which data is to be retrieved. | <li>The second argument is the column number in the current ''[[Fast/Unload]]'' record from which data is to be retrieved. | ||
| Line 19: | Line 17: | ||
<p class="caption">$FunsStr Function | <p class="caption">$FunsStr Function | ||
</p> | </p> | ||
<p class="caption">%STRING is set to the contents of the current | <p class="caption">%STRING is set to the contents of the current [[Fast/Unload]] record for the request, or to a null if there is some error.</p> | ||
If ''[[Fast/Unload]]'' has not unloaded any records yet, $FunsStr will wait for the first record. Each invocation of $FunsStr (with the same request number) operates on the same record, so a record longer than 255 bytes long can be split into multiple strings. To adjust the ''[[Fast/Unload]]'' record pointer to the next record, [[$FunSkip]] or [[$FunImg]] must be used. If there are no more records left from ''[[Fast/Unload]]'', $FunsStr will return a null. In this case, [[$FunSkip]] or [[$FunImg]] should be called to obtain the ''[[Fast/Unload]]'' return code and clean up after the request. | |||
$FunsStr's can be mixed with [[$FunSkip]] and [[$FunImg]] calls for the same request. In addition, multiple unloads can be performed simultaneously, and $FunsStr calls for the different requests can be mixed in freely. | |||
In the following example, the first 20 bytes of each unloaded record is assigned to %VAR1, the second 20 bytes to %VAR2, and this data is processed with subroutine PROCESS. | In the following example, the first 20 bytes of each unloaded record is assigned to %VAR1, the second 20 bytes to %VAR2, and this data is processed with subroutine PROCESS. | ||
| Line 45: | Line 42: | ||
If any record is shorter than 40 bytes in the preceding example, %VAR1 and %VAR2 are truncated as appropriate. If a record were only 20 bytes long, %VAR1 would be 20 bytes and %VAR2 would be null. If a record were 60 bytes long, both %VAR1 and %VAR2 would be 20 bytes long. If a record were 10 bytes long, %VAR1 would be 10 bytes long and %VAR2 would be null. | If any record is shorter than 40 bytes in the preceding example, %VAR1 and %VAR2 are truncated as appropriate. If a record were only 20 bytes long, %VAR1 would be 20 bytes and %VAR2 would be null. If a record were 60 bytes long, both %VAR1 and %VAR2 would be 20 bytes long. If a record were 10 bytes long, %VAR1 would be 10 bytes long and %VAR2 would be null. | ||
Note that after the last record is processed, $FunsStr always returns a null. At that point, $FunSkip should still be called once to obtain the ''[[Fast/Unload]]'' return code and clean up after the request.<p> | Note that after the last record is processed, $FunsStr always returns a null. At that point, [[$FunSkip]] should still be called once to obtain the ''[[Fast/Unload]]'' return code and clean up after the request.<p> | ||
<ul class="smallAndTightList"> | |||
<li>[[Fast/Unload User Language Interface]] | |||
</ul> | </ul> | ||
<p class="caption">Products authorizing $FunsStr | <p class="caption">Products authorizing $FunsStr | ||
</p> | </p> | ||
[[Category:$Functions|$FunsStr]] | [[Category:$Functions|$FunsStr]] | ||
[[Category:Fast/Unload $functions|$FunsStr]] | |||
Revision as of 17:14, 1 February 2011
<section begin="desc" />Retrieve data from active Fast/Unload request into string<section end="desc" />
This retrieves data from an active Fast/Unload request into a string.
The $FunsStr function accepts three arguments and returns a string result.
- The first argument is the request identifier returned by $FunLoad for the request from which data is to be retrieved. This is a required argument.
- The second argument is the column number in the current Fast/Unload record from which data is to be retrieved.
- The third argument is the maximum number of bytes of data to be retrieved from the current Fast/Unload record.
Syntax
<section begin="syntax" /> %STRING = $FunsStr(req_num, start, len) <section end="syntax" />
$FunsStr Function
%STRING is set to the contents of the current Fast/Unload record for the request, or to a null if there is some error.
If Fast/Unload has not unloaded any records yet, $FunsStr will wait for the first record. Each invocation of $FunsStr (with the same request number) operates on the same record, so a record longer than 255 bytes long can be split into multiple strings. To adjust the Fast/Unload record pointer to the next record, $FunSkip or $FunImg must be used. If there are no more records left from Fast/Unload, $FunsStr will return a null. In this case, $FunSkip or $FunImg should be called to obtain the Fast/Unload return code and clean up after the request.
$FunsStr's can be mixed with $FunSkip and $FunImg calls for the same request. In addition, multiple unloads can be performed simultaneously, and $FunsStr calls for the different requests can be mixed in freely.
In the following example, the first 20 bytes of each unloaded record is assigned to %VAR1, the second 20 bytes to %VAR2, and this data is processed with subroutine PROCESS.
%REQ = $FunLoad('DATA', , , '*') IF %REQ LE 0 THEN STOP END IF %RC = 1 REPEAT WHILE %RC > 0 %VAR1 = $FunsStr( %REQ, 1, 20) %VAR2 = $FunsStr( %REQ, 21, 20) IF %VAR1 EQ THEN CALL PROCESS( %VAR1, %VAR2) END IF %RC = $FunSkip END REPEAT
If any record is shorter than 40 bytes in the preceding example, %VAR1 and %VAR2 are truncated as appropriate. If a record were only 20 bytes long, %VAR1 would be 20 bytes and %VAR2 would be null. If a record were 60 bytes long, both %VAR1 and %VAR2 would be 20 bytes long. If a record were 10 bytes long, %VAR1 would be 10 bytes long and %VAR2 would be null.
Note that after the last record is processed, $FunsStr always returns a null. At that point, $FunSkip should still be called once to obtain the Fast/Unload return code and clean up after the request.
Products authorizing $FunsStr