FastUnload (Recordset function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (ah, there was three of them)
m (minor word change)
 
(19 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{Template:Recordset:FastUnload subtitle}}
{{Template:Recordset:FastUnload subtitle}}
This [[Notation conventions for methods#Callable functions|callable]] method performs synchronous or asynchronous [[Fast/Unload|unloads]] of the records in the <var>Recordset</var> method object using the <var class="product">[[Fast/Unload SOUL Interface]]</var>.


This [[Notation conventions for methods#Callable methods|callable]] method performs synchronous or asynchronous
This method is only available to customers that are also licensed for
unloads using the <var class="product">[[Fast/Unload User Language Interface]]</var>
the <var class="product">Fast/Unload SOUL Interface</var>.
of the record set data in the method object.


This method is only available to customers that are also licensed for
The <var>FastUnload</var> function also requires at least one <var class="product">Fast/Unload</var> task to be
the <var class="product">Fast/Unload User Language Interface</var>,
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.
and it is only available in <var class="product">Sirius Mods</var> version 6.7 and later.


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 <var class="product">Fast/Unload Reference Manual</var>.
==Syntax==
==Syntax==
{{Template:Recordset:FastUnload syntax}}
{{Template:Recordset:FastUnload syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%result</th>
<tr><th>%number</th>
<td>A numeric value, as follows: <ul> <li>For asynchronous requests, the request number. Request numbers are assigned serially, starting at 1. <li>For synchronous requests, the return code from <var class="product">Fast/Unload</var>.
<td>A numeric value, as follows:  
If the request is cancelled because the timeout period (<var>MaxTime</var> parameter, or FUNMAXT system parameter) is exceeded, the return code is 32. </ul>
<ul>  
</td></tr>
<li>For asynchronous requests, the request number. Request numbers are assigned serially, starting at 1.  
<tr><th>%rs</th>
 
<li>For synchronous requests, the [[Fast/Unload program return codes|return code]] from <var class="product">Fast/Unload</var>.
If the request is cancelled because the timeout period (<var>MaxTime</var> parameter, or <var>[[FUNMAXT parameter|FUNMAXT]]</var> system parameter) is exceeded, the return code is 32.  
</ul></td></tr>
 
<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>
 
<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.
<tr><th><var>Input</var></th>
</td></tr>
<td>A <var>Stringlist</var> object that contains the <var class="product">Fast/Unload</var> FUEL program for the unload, or a string that contains the DD name of the dataset which contains the FUEL program.
<tr><th><b>Output=</b>output</th>
<td>A <var>Stringlist</var> object that is to receive the unloaded data, or a string that contains the DD name that is to receive the unloaded data. <var>Output</var> is the allowed name for the parameter.
This is a [[Notation conventions for methods#Named parameters|name allowed]] parameter.</td></tr>
 
<tr><th><var>Output</var></th>
<td>A <var>Stringlist</var> object that is to receive the unloaded data, or a string that contains the DD name that is to receive the unloaded data.
If the request is asynchronous, and this parameter is a <var>Stringlist</var> object, the request is cancelled.
If the request is asynchronous, and this parameter is a <var>Stringlist</var> object, the request is cancelled.
</td></tr>
<tr><th><b>Report=</b>report</th>
This is a name allowed parameter.</td></tr>
<td>A <var>Stringlist</var> object that is to receive the <var class="product">Fast/Unload</var> report, or a string containing the DD name that is to receive the report. <var>Report</var> is the allowed name for the parameter.
 
<tr><th><var>Report</var></th>
<td>A <var>Stringlist</var> object that is to receive the <var class="product">Fast/Unload</var> report, or a string containing the DD name that is to receive the report.
If the request is asynchronous, and this parameter is a <var>Stringlist</var> object, the request is cancelled.
If the request is asynchronous, and this parameter is a <var>Stringlist</var> object, the request is cancelled.
This is an optional parameter. If it is not specified, the report goes to FUNAUDIT; if there is no FUNAUDIT, the report is simply discarded.
</td></tr>
This is an optional, name allowed, parameter. If it is not specified, the report goes to FUNAUDIT; if there is no FUNAUDIT, the report goes to the <var class="product">Model 204</var> audit trail.</td></tr>
<tr><th><b>Parameters=</b>parms</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 allowed name for the parameter.
<tr><th><var>Parameters</var></th>
This is an optional parameter; if it is not specified, no parameters are passed to <var class="product">Fast/Unload</var>.
<td>A string that contains the parameters that are to be passed to <var class="product">Fast/Unload</var>.
</td></tr>
This is an optional, name allowed, parameter; if it is not specified, no parameters are passed to <var class="product">Fast/Unload</var>.</td></tr>
<tr><th><b>AllMessages=</b>bool</th>
 
<td>A [[Enumerations#Using_Boolean_enumerations|"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>[[Enumerations#Using_Boolean_enumerations|Boolean]]</var> value. If <var>True</var>, all messages are sent to the <var class="product">Fast/Unload</var> report destination specified by the <var>Report</var> argument. Informational messages ordinarily suppressed by the <var class="product">Fast/Unload User Language Interface</var> are included by this setting.
</td></tr>
<p>
<tr><th><b>Asynch=</b>bool</th>
This is an optional, [[Notation conventions for methods#Named parameters|name required]], parameter, and it defaults to <var>False</var>. That is, many informational messages are suppressed from the report output by default.</p></td></tr>
<td>A [[Enumerations#Using_Boolean_enumerations|"Boolean Enumeration"]] value: <ul> <li>If <var>True</var>, the request is to be run asynchronously: the method should return immediately, returning a request number, rather than waiting for the unload to complete. If <var>Asynch</var> is set to <var>True</var>, neither the <var>Output</var> nor <var>Report</var> parameters can be <var>Stringlist</var> objects. <li>If <var>False</var>, the <var>FastUnload</var> method does not return until the unload is completed, if no errors are detected. In such a case, the return code from the method is the return code from <var class="product">Fast/Unload</var>. </ul>
 
<var>Asynch</var> is the required name for the parameter. The parameter itself is an optional parameter, and it defaults to <var>False</var>.
<tr id="asynch"><th><var>Asynch</var></th>
</td></tr>
<td>A <var>Boolean</var> value:  
<tr><th><b>Notify=</b>bool</th>
<ul>  
<td>A [[Enumerations#Using_Boolean_enumerations|"Boolean Enumeration"]] value: <ul> <li>If <var>True</var>, the user that initiated the request should be notified at its completion with a <var class="product">Model 204</var> message, if the request is asynchronous (Asynch=True). <li>If <var>False</var>, the initiating user will not be notified at the completion of the request. </ul>
<li>If <var>True</var>, the request is to be run asynchronously: the method should return immediately, returning a request number, rather than waiting for the unload to complete. If <var>Asynch</var> is set to <var>True</var>, neither the <var>Output</var> nor <var>Report</var> parameters can be <var>Stringlist</var> objects.  
<var>Notify</var> is the required name for the parameter. The parameter itself is an optional parameter, and it defaults to <var>False</var>.
<li>If <var>False</var>, the <var>FastUnload</var> method does not return until the unload is completed, if no errors are detected. In such a case, the return code from the method is the return code from <var class="product">Fast/Unload</var>.  
</td></tr>
</ul>
<tr><th><b>MaxTime=</b>sec</th>
This is an optional, name required, parameter, and it defaults to <var>False</var>.
 
<p class="note"><b>Note:</b> <code>Asynch=True</code> specifies that the Fast/Unload request is run completely in the background. The <var>[[FastUnloadTask (Recordset function)|FastUnloadTask]]</var> method, on the other hand, runs a Fast/Unload request asynchronously with the SOUL request that invokes it, but the SOUL request will rendezvous with the Fast/Unload request, retrieving each output record in turn.</p></td></tr>
 
<tr><th><var>Notify</var></th>
<td>A <var>Boolean</var> value:  
<ul>  
<li>If <var>True</var>, the user that initiated the request should be notified at its completion with a <var class="product">Model 204</var> message, if the request is asynchronous (Asynch=True).  
<li>If <var>False</var>, the initiating user will not be notified at the completion of the request.  
</ul>
This is an optional, name required, 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>).
<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.
<p>
<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 <var class="product">Fast/Unload Reference Manual</var>.<br>
A value of 0 for <var>MaxTime</var> means that the request will never timeout.</p>
'''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.
This is an optional, name required, parameter, and it defaults to the setting of the <var>FUNMAXT</var> system parameter.
 
'''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.</td></tr>
</td></tr></table>
</table>


==Usage notes==
==Usage notes==
<ul>
<ul>
<li>Any errors in the method parameter list (''%rs'', above), or
<li>Any errors in the method parameter list, or any environmental errors that
any environmental errors that
would prevent the request from being run, result in the request being cancelled.
would prevent the request from being run, result in the request being
cancelled.
</ul>
</ul>


==Example==
==Example==
In the following example, the <var>FastUnload</var> method uses <var class="product">Fast/Unload</var> to do a PAI unload
In the following example, the <var>FastUnload</var> method uses <var class="product">Fast/Unload</var> to do a PAI unload
to a <var>Stringlist</var> of all the records in file <code>sirFiled</code>,
to a <var>Stringlist</var> of all the records in file <code>SIRFILED</code>,
and then it displays the <var>Stringlist</var>:
and then it displays the <var>Stringlist</var>:
<p class="code"> b
<p class="code">b
%rs      is object recordSet in file sirFiled


%rs      is object recordSet in file sirFiled
%listi  is object stringList
%listo  is object stringList
%rc    is float


%listi  is object stringList
find records to %rs
%listo  is object stringList
end find


%rc    is float
%listi = new
text to %listi
  FOR EACH RECORD
      PUT '*'
      OUTPUT
      PAI
  END FOR
end text


find records to %rs
%listo = new
end find
%rc = %rs:fastUnload(%listi, %listo, parameters='NEBUFF=10')
%listo:print
end
</p>


%listi = new
==See also==
text to %listi
<ul>
    FOR EACH RECORD
<li>The <var class="product">[[Fast/Unload]]</var> wiki pages.
      PUT '*'
<li>The <var>[[FastUnloadTask (Recordset function)|FastUnloadTask]]</var> function, which allows SOUL processing of the Fast/Unload output as it is created.
      OUTPUT
</ul>
      PAI
    END FOR
end text


%listo = new
{{Template:Recordset:FastUnload footer}}
 
%rc = %rs:fastUnload(%listi, %listo, parameters='NEBUFF=10')
%listo:print


end
[[Category:Fast/Unload SOUL Interface]]
</p>
==See also==
{{Template:Recordset:FastUnload footer}}

Latest revision as of 00:33, 14 October 2016

Unload Recordset using Fast/Unload User Language Interface (Recordset class)

[Requires Fast/Unload Soul Interface]

This callable method performs synchronous or asynchronous unloads of the records in the Recordset method object using the Fast/Unload SOUL Interface.

This method is only available to customers that are also licensed for the Fast/Unload SOUL Interface.

The FastUnload function also requires at least one Fast/Unload 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

[%number =] recordset:FastUnload( [Input=] input, [Output=] output, - [[Report=] report], [[Parameters=] string], - [AllMessages= boolean], [Asynch= boolean], - [Notify= boolean], [MaxTime= number])

Syntax terms

%number A numeric value, as follows:
  • For asynchronous requests, the request number. Request numbers are assigned serially, starting at 1.
  • For synchronous requests, the return code from Fast/Unload. If the request is cancelled because the timeout period (MaxTime parameter, or FUNMAXT system parameter) is exceeded, the return code is 32.
recordset A reference to an instance of a Recordset object.
Input A Stringlist object that contains the Fast/Unload FUEL program for the unload, or a string that contains the DD name of the dataset which contains the FUEL program. This is a name allowed parameter.
Output A Stringlist object that is to receive the unloaded data, or a string that contains the DD name that is to receive the unloaded data.

If the request is asynchronous, and this parameter is a Stringlist object, the request is cancelled.

This is a name allowed parameter.
Report A Stringlist object that is to receive the Fast/Unload report, or a string containing the DD name that is to receive the report.

If the request is asynchronous, and this parameter is a Stringlist object, the request is cancelled.

This is an optional, name allowed, parameter. If it is not specified, the report goes to FUNAUDIT; if there is no FUNAUDIT, the report goes to the Model 204 audit trail.
Parameters A string that contains the parameters that are to be passed to Fast/Unload. This is an optional, name allowed, parameter; if it is not specified, no parameters are passed to Fast/Unload.
AllMessages A Boolean value. If True, all messages are sent to the Fast/Unload report destination specified by the Report argument. Informational messages ordinarily suppressed by the Fast/Unload User Language Interface are included by this setting.

This is an optional, name required, parameter, and it defaults to False. That is, many informational messages are suppressed from the report output by default.

Asynch A Boolean value:
  • If True, the request is to be run asynchronously: the method should return immediately, returning a request number, rather than waiting for the unload to complete. If Asynch is set to True, neither the Output nor Report parameters can be Stringlist objects.
  • If False, the FastUnload method does not return until the unload is completed, if no errors are detected. In such a case, the return code from the method is the return code from Fast/Unload.

This is an optional, name required, parameter, and it defaults to False.

Note: Asynch=True specifies that the Fast/Unload request is run completely in the background. The FastUnloadTask method, on the other hand, runs a Fast/Unload request asynchronously with the SOUL request that invokes it, but the SOUL request will rendezvous with the Fast/Unload request, retrieving each output record in turn.

Notify A Boolean value:
  • If True, the user that initiated the request should be notified at its completion with a Model 204 message, if the request is asynchronous (Asynch=True).
  • If False, the initiating user will not be notified at the completion of the request.
This is an optional, name required, 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.

This is an optional, name required, parameter, and it defaults to the setting of the FUNMAXT system parameter.

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.

Usage notes

  • Any errors in the method parameter list, or any environmental errors that would prevent the request from being run, result in the request being cancelled.

Example

In the following example, the FastUnload method uses Fast/Unload to do a PAI unload to a Stringlist of all the records in file SIRFILED, and then it displays the Stringlist:

b %rs is object recordSet in file sirFiled %listi is object stringList %listo is object stringList %rc is float find records to %rs end find %listi = new text to %listi FOR EACH RECORD PUT '*' OUTPUT PAI END FOR end text %listo = new %rc = %rs:fastUnload(%listi, %listo, parameters='NEBUFF=10') %listo:print end

See also

  • The Fast/Unload wiki pages.
  • The FastUnloadTask function, which allows SOUL processing of the Fast/Unload output as it is created.
Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=FastUnload_(Recordset_function)&oldid=94302"