$FunImg: Difference between revisions
Jump to navigation
Jump to search
m (1 revision) |
m (misc cleanup) |
||
| (19 intermediate revisions by 4 users not shown) | |||
| Line 2: | Line 2: | ||
<span class="pageSubtitle">Retrieve data from active Fast/Unload request into image</span> | <span class="pageSubtitle">Retrieve data from active Fast/Unload request into image</span> | ||
This retrieves data from an active | This retrieves data from an active <var class="product">[[Fast/Unload]]</var> request into an image. | ||
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 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. | ||
The second argument is the image item to which data is to be returned. Data is returned starting at that image item and continuing to the end of the image or until no more <var class="product">Fast/Unload</var> data is available in the current record. | |||
==Syntax== | ==Syntax== | ||
<p class="syntax">< | <p class="syntax"><span class="term">%result</span> = <span class="literal">$FunImg</span>(<span class="term">req_num</span>, <span class="term">image_item</span>) | ||
< | |||
</ | |||
< | |||
< | |||
</ | |||
</p> | </p> | ||
If | <p> | ||
<var class="term">%result</var> is set to either of these: </p> | |||
<ul> | |||
<li>The number of bytes returned </li> | |||
<li>An error code if no data was returned: | |||
<p class="code"> >0 - Number of bytes in unloaded record | |||
0 — <var class="product">Fast/Unload</var> completed with return code 0; no more data | |||
-1 — Request not found | |||
-2 — Invalid image item | |||
<-2 — <var class="product">Fast/Unload</var> completed with non-zero return code, and value returned | |||
is negative of return code; no more data </p></li> | |||
</ul> | |||
==Usage notes== | |||
<ul> | |||
<li>If <var class="product">Fast/Unload</var> has not unloaded any records yet, <var>$FunImg</var> waits for the first record. Each invocation of <var>$FunImg</var> skips over the record processed, so the next invocation retrieves the next unloaded record. </li> | |||
$FunImg | <li><var>$FunImg</var> calls can be mixed with <var>[[$FunSkip]]</var> and <var>[[$FunsStr]]</var> calls for the same request. In addition, multiple unloads can be performed simultaneously with <var>$FunImg</var> calls for the different requests mixed freely. </li> | ||
</ul> | |||
==Example== | |||
<p class="code"> | This fragment starts an unload request and then returns the first record into image <code>IMAGE</code>, starting at item <code>ITEM</code> in the image: | ||
<p class="code">%req = $FunLoad('DATA', , , '*') | |||
If %req le 0 then | |||
Stop | |||
End if | |||
%rc = $FunImg( %req, %image:ITEM ) | |||
</p> | </p> | ||
If the record is shorter than the rest of the image (starting at <code>ITEM</code>), then only as much data as is in the <var class="product">Fast/Unload</var> record is used to overlay the image. All other data in the image is left unchanged. If the record is longer than the rest of the image, the record is truncated before overlaying the image. In all cases, when <var class="term">%rc</var> is positive, it contains the length of the original <var class="product">Fast/Unload</var> record.<p> | |||
==Products authorizing {{PAGENAMEE}}== | |||
<ul class="smallAndTightList"> | <ul class="smallAndTightList"> | ||
<li>[[Fast/Unload | <li>[[Fast/Unload SOUL Interface]] | ||
</ul> | </ul> | ||
[[Category:$Functions|$FunImg]] | [[Category:$Functions|$FunImg]] | ||
[[Category:Fast/Unload | [[Category:Fast/Unload SOUL Interface]] | ||
Latest revision as of 19:47, 16 March 2015
Retrieve data from active Fast/Unload request into image
This retrieves data from an active Fast/Unload request into an image.
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 image item to which data is to be returned. Data is returned starting at that image item and continuing to the end of the image or until no more Fast/Unload data is available in the current record.
Syntax
%result = $FunImg(req_num, image_item)
%result is set to either of these:
- The number of bytes returned
- An error code if no data was returned:
>0 - Number of bytes in unloaded record 0 — Fast/Unload completed with return code 0; no more data -1 — Request not found -2 — Invalid image item <-2 — Fast/Unload completed with non-zero return code, and value returned is negative of return code; no more data
Usage notes
- If Fast/Unload has not unloaded any records yet, $FunImg waits for the first record. Each invocation of $FunImg skips over the record processed, so the next invocation retrieves the next unloaded record.
- $FunImg calls can be mixed with $FunSkip and $FunsStr calls for the same request. In addition, multiple unloads can be performed simultaneously with $FunImg calls for the different requests mixed freely.
Example
This fragment starts an unload request and then returns the first record into image IMAGE, starting at item ITEM in the image:
%req = $FunLoad('DATA', , , '*') If %req le 0 then Stop End if %rc = $FunImg( %req, %image:ITEM )
If the record is shorter than the rest of the image (starting at ITEM), then only as much data as is in the Fast/Unload record is used to overlay the image. All other data in the image is left unchanged. If the record is longer than the rest of the image, the record is truncated before overlaying the image. In all cases, when %rc is positive, it contains the length of the original Fast/Unload record.