$FunsStr

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

<section begin="syntax" />%STRING = $FunsStr(req_num, start, len) <section end="syntax" />

%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

• Fast/Unload User Language Interface