$FunsStr: Difference between revisions
m (→Syntax) |
No edit summary |
||
| Line 2: | Line 2: | ||
<span class="pageSubtitle">Retrieve data from active Fast/Unload request into string</span> | <span class="pageSubtitle">Retrieve data from active Fast/Unload request into string</span> | ||
This retrieves data from an active | This retrieves data from an active <i>[[Fast/Unload]]</i> 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. | ||
| Line 8: | Line 8: | ||
<ul> | <ul> | ||
<li>The first argument is the request identifier returned by <var>$FunLoad</var> 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 <var>$FunLoad</var> 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 | <li>The second argument is the column number in the current <i>[[Fast/Unload]]</i> record from which data is to be retrieved. | ||
<li>The third argument is the maximum number of bytes of data to be retrieved from the current | <li>The third argument is the maximum number of bytes of data to be retrieved from the current <i>[[Fast/Unload]]</i> record. | ||
</ul> | </ul> | ||
| Line 19: | Line 19: | ||
<p>%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> | <p>%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 | If <i>[[Fast/Unload]]</i> 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 <i>[[Fast/Unload]]</i> record pointer to the next record, [[$FunSkip]] or [[$FunImg]] must be used. If there are no more records left from <i>[[Fast/Unload]]</i>, $FunsStr will return a null. In this case, [[$FunSkip]] or [[$FunImg]] should be called to obtain the <i>[[Fast/Unload]]</i> 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. | $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. | ||
| Line 33: | Line 33: | ||
%VAR1 = $FunsStr( %REQ, 1, 20) | %VAR1 = $FunsStr( %REQ, 1, 20) | ||
%VAR2 = $FunsStr( %REQ, 21, 20) | %VAR2 = $FunsStr( %REQ, 21, 20) | ||
IF %VAR1 EQ | IF %VAR1 EQ '' THEN | ||
CALL PROCESS( %VAR1, %VAR2) | CALL PROCESS( %VAR1, %VAR2) | ||
END IF | END IF | ||
| Line 42: | 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 | 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 <i>[[Fast/Unload]]</i> return code and clean up after the request. | ||
==Products authorizing {{PAGENAMEE}}== | ==Products authorizing {{PAGENAMEE}}== | ||
Revision as of 21:36, 11 November 2014
Retrieve data from active Fast/Unload request into 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 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
%STRING = $FunsStr(req_num, start, len)
%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