View source for $FunLoad

{{DISPLAYTITLE:$FunLoad}}
<span class="pageSubtitle">Fast/Unload records in Model 204 list or found set</span>

<p class="warn"><b>Note: </b>Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $Funload function is the <var>[[FastUnload (Recordset function)|FastUnload]]</var> function in the <var>Recordset</var> class</p>
 
This function requests an unload of the data in a <var class="product">Model 204</var> list or found set using <var class="product">[[Fast/Unload]]</var>. If <var class="product">Fast/Unload</var> is not installed at your site, this function returns a <code>-1</code> error code.

<var>$FunLoad</var> accepts six arguments, as explained below.
 
==Syntax==
<p class="syntax"><span class="term">%result</span> = <span class="literal">$FunLoad</span>(<span class="term">found_set</span>, <span class="term">funin</span>, <span class="term">funprint</span>, <span class="term">funout</span>, [<span class="term">parms</span>], [<span class="term">timelimit</span>])
</p>

<table>
<tr><th>%result</th>
<td>This numeric variable is set to the [[#Return codes and error messages|return code]] from Fast Unload, to the positive request number for asynchronous requests, or to a negative number if <var class="product">Fast/Unload</var> is unable to process the request.</td></tr>

<tr><th>found_set</th>
<td>A string that identifies a found set or a list. This is a required parameter. If you want to unload records in a found set created with a FIND statement, pass the label of the found set as the <var class="term">found_set</var> argument. To unload the records in a list, specify the name of the list as the <var class="term">found_set</var> argument.
<p> 
If you have a <var>FIND</var> statement label and a list with the same name, <var>$FunLoad</var> will use the <var>FIND</var> statement label, unless you explicitly specify that you want to unload a list by preceding the name of the list with the word <code>LIST</code>. For example, in the following program the unload at label <code>FUN1</code> unloads all records found in the <var>FIND</var> statement at label <code>DATA</code>, while the unload at label <code>FUN2</code> unloadsthe records on list <code>DATA</code>: </p>
 
<p class="code">declare list data in bigfile
 
data: in bigfile find all records for which
 . . .
end find
 
fun1: %rc = $funload('DATA',...)
fun2: %rc = $funload('LIST DATA',..)
</p> 
<p> 
<var class="product">Model 204</var> <var>FIND</var> statement record locking protects the record sets you are unloading. For jobs where data consistency is critical, reorganizing a file, for example, this record locking is essential. For jobs that can tolerate some inconsistent data, like certain report creation, unlocked record sets (<var>FIND WITHOUT LOCKS</var>) may be suitable. </p>
<p> 
You cannot unload records that are not in a found set or a list. For example, you cannot unload a sorted record set (although you can use sorted output in the FUEL program that <var>$FunLoad</var> runs, as described in [[Fast/Unload Extraction Language (FUEL)]]). </p></td></tr>

<tr><th>funin</th>
<td>The identifier of a [[$lists|$list]], or it is the DDname of an input program. This argument corresponds to FUNIN in batch mode <var class="product">Fast/Unload</var>. This is a required parameter. </td></tr>

<tr><th>funprint</th>
<td>The identifier of the $list that is to receive the <var class="product">Fast/Unload</var> report data, or it is the DDname of a file that is to receive the <var class="product">Fast/Unload</var> report data. Note that if you specify the ASYNCH parameter, you cannot specify a $list identifier for this argument. This argument corresponds to FUNPRINT in batch mode <var class="product">Fast/Unload</var>.
<p>
If this parameter is not specified, all report data will go to the <var class="product">Fast/Unload</var> audit trail. </p></td></tr>

<tr><th>funout</th>
<td>Corresponds to FUNOUT in batch mode <var class="product">Fast/Unload</var>; specifies the destination for the output data. This argument is required, and it may be one of the following:
<ul> 
<li>A %variable that identifies the $list that is to receive the unloaded data. If you use a $list for output, you are allowed only one output stream in the FUEL program you are invoking. The $list you specify will be the sole output destination, and any destination names specified in the FUEL program are ignored.</li>

<li>An asterisk (<tt>*</tt>), indicating that the unloaded data will be processed with <var>$FunImg</var>, <var>$FunSkip</var>, and/or <var>$FunsStr</var>. Specifying an asterisk for the <var class="term">funout</var> argument implies that the unload is asynchronous, whether or not the ASYNCH parameter is actually specified. </li>

<li>A string (eight characters at most), which indicates that the output data is to be sent to the one or more data sets specified in the FUEL program.
<p> 
Formerly, multiple output data sets were not supported by the <var class="product">[[Fast/Unload SOUL Interface]]</var>, and this <var class="term">funout</var> argument had to be the DDname of the destination file for the single output stream specified or implied in the FUEL program. <var>$FunLoad</var> validated the existence and attempted to obtain an exclusive enqueue on the output data set. </p></li>
</ul>
<p> 
Processing of this argument depends on the <var class="product">Fast/Unload</var> version: </p> 
<ul>
<li>For <var class="product">Fast/Unload</var> versions prior to 4.2, only a single output stream is supported, and processing is as described above. </li>

<li>For <var class="product">Fast/Unload</var> 4.2 and higher, multiple output data sets are supported, and this argument string serves as a placeholder only, indicating that the output data is to be sent to the one or more data sets specified in the FUEL program. <var class="product">Fast/Unload</var> will validate the existence and attempt to obtain an exclusive enqueue on all output data sets specified or implied in the FUEL program. </li>
</ul></td></tr>
 
<tr><th>parms</th>
<td>A string that specifies the <var class="product">Fast/Unload</var> parameters. This string can contain any of the parameters allowed on the PARM option on the EXEC card for batch mode <var class="product">Fast/Unload</var>
and can, in addition, contain the parameters ASYNCH, ALLMSG and NOTIFY. The description of parameters in [[Fast/Unload program parameters]] shows the default parameter values, showing any differences when invoked via the <var class="product">Fast/Unload SOUL Interface</var>. </td></tr>

<tr><th>timelimit</th>
<td>A number indicating the maximum amount of time in seconds that the request is to be allowed to complete. If the <var>$FunLoad</var> request does not complete within this time, the <var>$FunLoad</var> request is immediately cancelled. The SOUL request is <strong>not</strong> cancelled in such a case, but, for synchronous requests, <var>$FunLoad</var> returns a 32. This is an optional argument and, if not specified, defaults to the <var>FUNMAXT</var> system parameter setting.
<p> 
An explicit or default value of 0 means that there will be no time limit placed on the request. </p>
<p class="note"> 
<b>Note:</b> The time limit includes the time waiting for the request to actually be run by a <var class="product">Fast/Unload</var> task, so a request could time out because of other long-running requests tying up the <var class="product">Fast/Unload</var> tasks. </p></td></tr>
</table>
 
==Return codes and error messages==
These are the return codes:
<p class="code"> -1 - <var class="product">Fast/Unload</var> PST not available
 -2 - Input/report/output DDname in use
 -3 - Ran out of CCATEMP or free storage
 -4 - Input/report/output DDname not found
 -5 - Required parameter not specified
-11 - Invalid found set specified
-12 - Invalid input/report/output descriptor specified
-13 - Conflicting parameters
</p>
 
In addition to the above error codes, if <var>$FunLoad</var> discovers that a required capability is not supported by the version of <var class="product">Fast/Unload</var> in use, the SOUL request is cancelled with an error message indicating the missing capability. If any missing capabilities that would prevent successful <var>$FunLoad</var> operation are discovered during <var class="product">Model 204</var> initialization, an operator warning is issued and saved in the <code>VIEW ERRORS</code> table, so that corrective action may be taken in advance.
 
If the X'01' bit is set in the system <var>FUNPARM</var> parameter, the request is cancelled if a <var>$FunLoad</var> is issued in the middle of an updating transaction. Whether or not <var>FUNPARM</var> X'01' is set, it is generally best to avoid <var>$FunLoad</var> calls in the middle of an updating transaction, since <var>$FunLoad</var> calls can take a long time to run, even if the specific <var>$FunLoad</var> request is relatively small. This is so because all <var>$FunLoad</var> requests share the same <var>FUNTSKN</var> subtasks, and if these are tied up with relatively long-running requests, all other requests must wait for access to a <var class="product">Fast/Unload</var> task.
 
To make it easier to diagnose problems where <var class="product">Fast/Unload SOUL Interface</var> is involved, messages are also sent to the <var class="product">Model 204</var> journal/audit trail at each <var class="product">Fast/Unload</var> request made and at each completed by the <var class="product">Fast/Unload SOUL Interface</var>.
The message when the requests are started look like:
<p class="code">MSIR.0890: Asynchronous request 2 made by $FunLoad
</p>
 
And the message when the requests are completed look like:
<p class="code">MSIR.0891: Asynchronous request 2 completed, RC = 0
</p>

==Examples==
In the following example, the <var class="product">Fast/Unload</var> input data is in DDname <code>FUNIN</code>, the report is to go to DDname <code>FUNPRINT</code>, and the data is to be unloaded to DDname <code>FUNOUT</code>.
<p class="code">begin
find1: find all records in comics for which
   name = 'SIMPSON'
end find
 
%rc = $funload('FIND1', 'FUNIN', 'FUNPRINT', 'FUNOUT', 'NOBUFF=6')
 
if %rc ne 0 then
   print 'Error performing Fast/Unload... RC =' and %rc
end if 
end
</p> 
 
In the following example, we dynamically build the unload input program, have the report data simply go to the <var class="product">Fast/Unload</var>
audit trail, and have the data unloaded to a $list.
<p class="code">begin
%list1 = $listNew
%list2 = $listNew
 
%rc = $listAdd( %list1, 'FOR EACH RECORD' )
%rc = $listAdd( %list1, ' PUT &apos;'*&apos;&apos;' )
%rc = $listAdd( %list1, ' OUTPUT' )
%rc = $listAdd( %list1, ' PAI' )
%rc = $listAdd( %list1, 'END FOR' )
 
find1: in clowns find all records for which
  trademark = 'PRATFALL'
end find
 
%rc = $funload( 'FIND1', %list1, , %list2) 
 . . .  
end
</p>
 
In the following example, the input FUEL program is contained in procedure <code>UNLOAD1</code> in the <var class="product">Model 204</var> procedure file called <code>FUELPROC</code>. The data is processed with <var>$FunImg</var> calls (not shown).
 
<p class="code">begin 
declare list hoho in bigfile
 . . .  
%replist = $listNew
%records = 'LIST HOHO'
 
%inlist = $listNew
 
%rc = $procOpn('UNLOAD1','FUELPROC')
%rc = $procDat(%inlist)
 
%options = 'NEBUFF=4,NBBUFF=2,UPPER,ALLMSG'
%rc = $funload( %records, %inlist, , '*', %options ) 
 . . .  
end
</p>
 
The following is an example of an asynchronous unload request. The input program is in DDname <code>FUNIN</code>, the report data is to go to the <var class="product">Fast/Unload</var>
audit trail, and the data is to be dumped to DDname <code>OUTFILE</code>.
 
<p class="code">begin 
findx: in movies find all records for which
   director = 'HITCHCOCK'
end find
 
%options = 'ASYNCH ALLMSG NOBUFF=8'
 
%rc = $funload( 'FINDX', 'FUNIN', , 'OUTFILE', %OPTIONS )
 
if %rc > 0 then
   print 'Fast/Unload request accepted,' and 'request number =' with %rc
else
   Print 'Fast/Unload request rejected,' and 'error code =' and %rc
end if  
end
</p>
 
==Products authorizing {{PAGENAMEE}}== 
<ul class="smallAndTightList">
<li>[[Fast/Unload SOUL Interface]] </li>
</ul>
 
[[Category:$Functions|$FunLoad]]
[[Category:Fast/Unload SOUL Interface]]