$FunsStr: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
m (UL Interface becomes SOUL Interface)
 
(15 intermediate revisions by 4 users not shown)
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 ''[[Fast/Unload]]'' request into a string.  
<var>$FunsStr</var> retrieves data from an active <var class="product">[[Fast/Unload]]</var> request into a string.  


The $FunsStr function accepts three arguments and returns a string result.
The <var>$FunsStr</var> function accepts three arguments and returns a string result.
 
<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 second argument is the column number in the current ''[[Fast/Unload]]'' 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 ''[[Fast/Unload]]'' record.
</ul>


==Syntax==
==Syntax==
<p class="syntax"><section begin="syntax" />%STRING = $FunsStr(req_num, start, len)
<p class="syntax"><span class="term">%string</span> = <span class="literal">$FunsStr</span>(<span class="term">req_num</span>, <span class="term">start</span>, <span class="term">len</span>)
<section end="syntax" /></p>
<p class="caption">$FunsStr Function
</p>
</p>
<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.  
<table>
<tr><th>%string</th>
<td>A string variable set to the contents of the current <var class="product">Fast/Unload</var> record for the request, or to a null if there is some error.</td></tr>
 
<tr><th>req_num</th>
<td>The request identifier returned by <var>$FunLoad</var> for the request from which data is to be retrieved. This is a required argument. </td></tr>
 
<tr><th>start</th>
<td>The column number in the current <var class="product">Fast/Unload</var> record from which data is to be retrieved. </td></tr>
 
<tr><th>len</th>
<td>The maximum number of bytes of data to be retrieved from the current <var class="product">Fast/Unload</var> record.</td></tr>
</table>


$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.  
==Usage notes==
If <var class="product">Fast/Unload</var> has not unloaded any records yet, <var>$FunsStr</var> will wait for the first record. Each invocation of <var>$FunsStr</var> (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 <var class="product">Fast/Unload</var> record pointer to the next record, <var>[[$FunSkip]]</var> or <var>[[$FunImg]]</var> must be used. If there are no more records left from <var class="product">Fast/Unload</var>, <var>$FunsStr</var> will return a null. In this case, <var>$FunSkip</var> or <var>$FunImg</var> should be called to obtain the <var class="product">Fast/Unload</var> return code and clean up after the request.  


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.
<var>$FunsStr</var> calls can be mixed with <var>$FunSkip</var> and <var>$FunImg</var> calls for the same request. In addition, multiple unloads can be performed simultaneously, and <var>$FunsStr</var> calls for the different requests can be mixed in freely.
<p class="code"> %REQ = $FunLoad('DATA', , , '*')
 
IF %REQ LE 0 THEN
==Example==
STOP
In the following example, the first 20 bytes of each unloaded record is assigned to <var class="term">%var1</var>, the second 20 bytes to <var class="term">%var2</var>, and this data is processed with subroutine <code>PROCESS</code>.
END IF
<p class="code">%req = $FunLoad('DATA', , , '*')
If %req Le 0 Then
  Stop
End If
   
   
%RC = 1
%rc = 1
REPEAT WHILE %RC > 0
Repeat While %rc > 0
%VAR1 = $FunsStr( %REQ, 1, 20)
%var1 = $FunsStr(%req, 1, 20)
%VAR2 = $FunsStr( %REQ, 21, 20)
%var2 = $FunsStr(%req, 21, 20)
IF %VAR1 EQ '' THEN
If %var1 Eq &apos;&apos; Then
CALL PROCESS( %VAR1, %VAR2)
  Call Process( %var1, %var2)
END IF
End If
%RC = $FunSkip
%rc = $FunSkip
END REPEAT
End Repeat
</p>
</p>


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, <var class="term">%var1</var> and <var class="term">%var2</var> are truncated as appropriate. If a record were only 20 bytes long, <var class="term">%var1</var> would be 20 bytes and <var class="term">%var2</var> would be null. If a record were 60 bytes long, both <var class="term">%var1</var> and <var class="term">%var2</var> would be 20 bytes long. If a record were 10 bytes long, <var class="term">%var1</var> would be 10 bytes long and <var class="term">%var2</var> 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.
Note that after the last record is processed, <var>$FunsStr</var> always returns a null. At that point, <var>$FunSkip</var> should still be called once to obtain the <var class="product">Fast/Unload</var> return code and clean up after the request.


<h2>Products authorizing {{PAGENAMEE}}</h2><ul class="smallAndTightList">
==Products authorizing {{PAGENAMEE}}==
<li>[[Fast/Unload User Language Interface]]
<ul>
<li>[[Fast/Unload SOUL Interface]]</li>
</ul>
</ul>
<p>
</p>


[[Category:$Functions|$FunsStr]]
[[Category:$Functions|$FunsStr]]
[[Category:Fast/Unload User Language Interface]]
[[Category:Fast/Unload SOUL Interface]]

Latest revision as of 20:31, 16 March 2015

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.

Products authorizing $FunsStr

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=$FunsStr&oldid=76567"