FastUnloadTask (Recordset function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
No edit summary
 
(14 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{Template:Recordset:FastUnloadTask subtitle}}
{{Template:Recordset:FastUnloadTask subtitle}}
This method performs unloads using <var class="product">[[Fast/Unload]]</var> where
This method performs unloads using <var class="product">[[Fast/Unload]]</var> where
the <var class="product">[[Fast/Unload]]</var> output is processed programmatically as it is received.
the <var class="product">Fast/Unload</var> output is [[#See also|processed programmatically]] as it is received.


The <var>FastUnloadTask</var> approach has this advantage over the <var>FastUnload</var> method
The <var>FastUnloadTask</var> approach has this advantage over the <var>[[FastUnload (Recordset function)|FastUnload]]</var> method which has a <var>Stringlist</var>
with a <var>Stringlist</var>
output: it avoids potentially large quantities of data from being
output: it avoids potentially large quantities of data from being
moved to and from CCATEMP.
moved to and from CCATEMP.
Its disadvantage is that, since User Language processing is likely to be
Its disadvantage is that, since <var class="product">SOUL</var> processing is likely to be
slower than <var class="product">[[Fast/Unload]]</var> processing, using <var>FastUnloadTask</var> is likely to tie
slower than <var class="product">Fast/Unload</var> processing, using <var>FastUnloadTask</var> is likely to tie
up a <var class="product">[[Fast/Unload]]</var> task much longer than using <var>FastUnload</var>, which sends its output to
up a <var class="product">Fast/Unload</var> task much longer than using <var>FastUnload</var>, which sends its output to a <var>Stringlist</var>.
a <var>Stringlist</var>.
 
<p class="note"><b>Note:</b> The <code>[[FastUnload (Recordset function)#asynch|Asynch=True]]</code> argument of the <var>FastUnload</var> method provides for complete background execution of a Fast/Unload request.</p>


<var>FastUnloadTask</var> returns a <var>[[FastUnloadTask class|FastUnloadTask]]</var> object
<var>FastUnloadTask</var> returns a <var>[[FastUnloadTask class|FastUnloadTask]]</var> object
that can be used to retrieve output from <var class="product">[[Fast/Unload]]</var>.
that can be used to retrieve output from <var class="product">Fast/Unload</var>.


The <var>FastUnloadTask</var> function is only available to customers licensed for the
The <var>FastUnloadTask</var> function is only available to customers licensed for the
<var class="product">Fast/Unload User Language Interface</var>.
<var class="product">[[Fast/Unload SOUL Interface]]</var>.
 
The <var>FastUnloadTask</var> function also requires at least one <var>FastUnload</var> task to be available in the Online in which it is running, which means that the
<var>[[FUNTSKN parameter|FUNTSKN]]</var> system parameter must be set to 1 or higher.


The <var>FastUnload</var> function also requires at least one <var>FastUnload</var> task to be
available in the Online in which it is running, which means that the
FUNTSKN system parameter must be set to 1 or higher.
For more information about <var class="product">Fast/Unload User Language Interface</var> environmental considerations, see the &amp;amp;FUNR..
==Syntax==
==Syntax==
{{Template:Recordset:FastUnloadTask syntax}}
{{Template:Recordset:FastUnloadTask syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%funtask</th>
<tr><th>%fastUnloadTask</th>
<td>A reference to an instance of a <var>FastUnloadTask</var> object.
<td>A reference to an instance of a <var>FastUnloadTask</var> object.</td></tr>
</td></tr>
 
<tr><th>%rs</th>
<tr><th>recordset</th>
<td>A reference to an instance of a <var>Recordset</var> object.
<td>A reference to an instance of a <var>Recordset</var> object.</td></tr>
</td></tr>
 
<tr><th><b>Input=</b>inlist</th>
<tr><th><var>Input</var></th>
<td>A <var>Stringlist</var> object that contains the <var class="product">[[Fast/Unload]]</var> FUEL program for the unload. <var>Input</var> is the [[Notation conventions for methods#Named parameters|allowed name]] for the parameter.
<td>A <var>Stringlist</var> object that contains the <var class="product">Fast/Unload</var> FUEL program for the unload. <var>Input</var> is the [[Notation conventions for methods#Named parameters|allowed name]] for the parameter.</td></tr>
</td></tr>
 
<tr><th><b>Parameters=</b>parms</th>
<tr><th><var>Parameters</var></th>
<td>A string that contains the parameters that are to be passed to <var class="product">[[Fast/Unload]]</var>. <var>Parameters</var> is the [[Notation conventions for methods#Named parameters|allowed name]] for the parameter.
<td>A string that contains the parameters that are to be passed to <var class="product">Fast/Unload</var>. <var>Parameters</var> is the allowed name for the parameter.
This is an optional parameter; if it is not specified, no parameters are passed to <var class="product">[[Fast/Unload]]</var>.
<p>
</td></tr>
This is an optional parameter; if it is not specified, no parameters are passed to <var class="product">Fast/Unload</var>.</p></td></tr>
<tr><th><b>AllMessages=</b>bool</th>
 
<td>A Boolean enumeration, providing functionality similar to the <var>$Funload</var> ALLMSG parameter: if <var>True</var>, all messages that would go in the <var class="product">[[Fast/Unload]]</var> report are sent to the report dataset, report <var>Stringlist</var>, or FUNAUDIT. Informational messages ordinarily suppressed by <var class="product">Fast/Unload User Language Interface</var> are included by this setting.
<tr><th><var>AllMessages</var></th>
<var>AllMessages</var> is the [[Notation conventions for methods#Named parameters|required name]] for the parameter. The parameter itself is an optional parameter, and it defaults to <var>False</var>. That is, many informational messages are suppressed from the report output.
<td>A <var>[[Boolean enumeration]]</var>, providing functionality similar to the <var>$Funload</var> <var>ALLMSG</var> parameter: if <var>True</var>, all messages that would go in the <var class="product">Fast/Unload</var> report are sent to the report dataset, report <var>Stringlist</var>, or FUNAUDIT. Informational messages ordinarily suppressed by <var class="product">Fast/Unload SOUL Interface</var> are included by this setting.
</td></tr>
<p>
<tr><th><b>ReportToStringlist=</b>bool</th>
<var>AllMessages</var> is the [[Notation conventions for methods#Named parameters|required name]] for the parameter. The parameter itself is an optional parameter, and it defaults to <var>False</var>. That is, many informational messages are suppressed from the report output.</p></td></tr>
<td>A Boolean enumeration value: <ul> <li>If <var>True</var>, the report data from <var class="product">[[Fast/Unload]]</var> will be retrieved via the <var>[[Report (FastUnloadTask function)|Report]]</var> method on the <var>FastUnloadTask</var> object returned by this method. <li>If <var>False</var>, the report data is sent to FUNAUDIT, if present, by default. </ul>
 
<code>ReportToStringlist</code> is the [[Notation conventions for methods#Named parameters|required name]] for the parameter. The parameter itself is an optional parameter, and it defaults to <var>False</var>.
<tr><th><var>ReportToStringlist</var></th>
</td></tr>
<td>A <var>Boolean</var> <var>enumeration</var> value:  
<tr><th><b>MaxTime=</b>sec</th>
<ul>  
<td>A numeric value that indicates the maximum number of seconds after initiation of the request that the request is given to complete. If the request has not even started running in a <var class="product">[[Fast/Unload]]</var> task, or if the task is running, but hasn't completed after the timeout period, the request is cancelled (resulting in a return code 32 from <var class="product">[[Fast/Unload]]</var>).
<li>If <var>True</var>, the report data from <var class="product">Fast/Unload</var> will be retrieved via the <var>[[Report (FastUnloadTask function)|Report]]</var> method on the <var>FastUnloadTask</var> object returned by this method.  
 
<li>If <var>False</var>, the report data is sent to FUNAUDIT, if present, by default.  
</ul>
<var>ReportToStringlist</var> is the required name for the parameter. The parameter itself is an optional parameter, and it defaults to <var>False</var>.</td></tr>
 
<tr><th><var>MaxTime</var></th>
<td>A numeric value that indicates the maximum number of seconds after initiation of the request that the request is given to complete. If the request has not even started running in a <var class="product">Fast/Unload</var> task, or if the task is running, but hasn't completed after the timeout period, the request is cancelled (resulting in a return code 32 from <var class="product">Fast/Unload</var>).
A value of 0 for <var>MaxTime</var> means that the request will never timeout.
A value of 0 for <var>MaxTime</var> means that the request will never timeout.
<var>MaxTime</var> is the [[Notation conventions for methods#Named parameters|required name]] for the parameter. The parameter itself is an optional parameter, and it defaults to the setting of the FUNMAXT system parameter. FUNMAXT is described in the &amp;amp;FUNR.. '''Note:''' A request can timeout through no fault of its own if all the <var class="product">[[Fast/Unload]]</var> tasks are taken up by other long-running requests.
<p>
<var>MaxTime</var> is the required name for the parameter. The parameter itself is an optional parameter, and it defaults to the setting of the <var>[[FUNMAXT parameter|FUNMAXT]]</var> system parameter. <var>FUNMAXT</var> is also described in the [[Fast/Unload SOUL Interface#FUNMAXT|FUNMAXT]] section of the [[Fast/Unload SOUL Interface]] page. </p>
<p class="note">
'''Note:''' A request can timeout through no fault of its own if all the <var class="product">Fast/Unload</var> tasks are taken up by other long-running requests.</p></td></tr>
</table>
 
==Examples==
See the [[FastUnloadTask class#FastUnloadTask example|examples for the <var>FastUnloadTask</var> class]].


</td></tr></table>
==See also==
==See also==
<ul>
<li>The <var class="product">[[Fast/Unload]]</var> wiki pages.
</ul>
The following functions provide interaction with the task created by <var>FastUnloadTask</var>:
<ul>
<li><var>[[GetNextRecord (FastUnloadTask function)|GetNextRecord]]</var>: retrieve the <var class="product">Fast/Unload</var> task's output, one record at a time
<li><var>[[Report (FastUnloadTask function)|Report]]</var>: retrieve the <var class="product">Fast/Unload</var> task's report into a <var>Stringlist</var>, after the task is done
<li><var>[[ReturnCode (FastUnloadTask function)|ReturnCode]]</var>: retrieve the <var class="product">Fast/Unload</var> task's return code, after the task is done
<li><var>[[State (FastUnloadTask function)|State]]</var>: retrieve the state of the <var class="product">Fast/Unload</var> task
</ul>
{{Template:Recordset:FastUnloadTask footer}}
{{Template:Recordset:FastUnloadTask footer}}
[[Category:Fast/Unload SOUL Interface]]

Latest revision as of 16:13, 13 October 2016

Initiate asynch Recordset unload using Fast/Unload User Language Interface (Recordset class)

[Requires Fast/Unload Soul Interface]

This method performs unloads using Fast/Unload where the Fast/Unload output is processed programmatically as it is received.

The FastUnloadTask approach has this advantage over the FastUnload method which has a Stringlist output: it avoids potentially large quantities of data from being moved to and from CCATEMP. Its disadvantage is that, since SOUL processing is likely to be slower than Fast/Unload processing, using FastUnloadTask is likely to tie up a Fast/Unload task much longer than using FastUnload, which sends its output to a Stringlist.

Note: The Asynch=True argument of the FastUnload method provides for complete background execution of a Fast/Unload request.

FastUnloadTask returns a FastUnloadTask object that can be used to retrieve output from Fast/Unload.

The FastUnloadTask function is only available to customers licensed for the Fast/Unload SOUL Interface.

The FastUnloadTask function also requires at least one FastUnload task to be available in the Online in which it is running, which means that the FUNTSKN system parameter must be set to 1 or higher.

Syntax

%fastUnloadTask = recordset:FastUnloadTask( [Input=] input, - [[Parameters=] string], - [AllMessages= boolean], - [ReportToStringlist= boolean], - [MaxTime= number])

Syntax terms

%fastUnloadTask A reference to an instance of a FastUnloadTask object.
recordset A reference to an instance of a Recordset object.
Input A Stringlist object that contains the Fast/Unload FUEL program for the unload. Input is the allowed name for the parameter.
Parameters A string that contains the parameters that are to be passed to Fast/Unload. Parameters is the allowed name for the parameter.

This is an optional parameter; if it is not specified, no parameters are passed to Fast/Unload.

AllMessages A Boolean enumeration, providing functionality similar to the $Funload ALLMSG parameter: if True, all messages that would go in the Fast/Unload report are sent to the report dataset, report Stringlist, or FUNAUDIT. Informational messages ordinarily suppressed by Fast/Unload SOUL Interface are included by this setting.

AllMessages is the required name for the parameter. The parameter itself is an optional parameter, and it defaults to False. That is, many informational messages are suppressed from the report output.

ReportToStringlist A Boolean enumeration value:
  • If True, the report data from Fast/Unload will be retrieved via the Report method on the FastUnloadTask object returned by this method.
  • If False, the report data is sent to FUNAUDIT, if present, by default.
ReportToStringlist is the required name for the parameter. The parameter itself is an optional parameter, and it defaults to False.
MaxTime A numeric value that indicates the maximum number of seconds after initiation of the request that the request is given to complete. If the request has not even started running in a Fast/Unload task, or if the task is running, but hasn't completed after the timeout period, the request is cancelled (resulting in a return code 32 from Fast/Unload).

A value of 0 for MaxTime means that the request will never timeout.

MaxTime is the required name for the parameter. The parameter itself is an optional parameter, and it defaults to the setting of the FUNMAXT system parameter. FUNMAXT is also described in the FUNMAXT section of the Fast/Unload SOUL Interface page.

Note: A request can timeout through no fault of its own if all the Fast/Unload tasks are taken up by other long-running requests.

Examples

See the examples for the FastUnloadTask class.

See also

The following functions provide interaction with the task created by FastUnloadTask:

  • GetNextRecord: retrieve the Fast/Unload task's output, one record at a time
  • Report: retrieve the Fast/Unload task's report into a Stringlist, after the task is done
  • ReturnCode: retrieve the Fast/Unload task's return code, after the task is done
  • State: retrieve the state of the Fast/Unload task