$FunsStr
Retrieve data from active Fast/Unload request into string
$FunsStr retrieves data from an active Fast/Unload request into a string.
The $FunsStr function accepts three arguments and returns a string result.
Syntax
%string = $FunsStr(req_num, start, len)
| %string | A string variable set to the contents of the current Fast/Unload record for the request, or to a null if there is some error. |
|---|---|
| req_num | The request identifier returned by $FunLoad for the request from which data is to be retrieved. This is a required argument. |
| start | The column number in the current Fast/Unload record from which data is to be retrieved. |
| len | The maximum number of bytes of data to be retrieved from the current Fast/Unload record. |
Usage notes
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 calls 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.
Example
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.