$FunLoad: Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
No edit summary
 
(34 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:$FunLoad}}
{{DISPLAYTITLE:$FunLoad}}
<span class="pageSubtitle">[[Fast/Unload]] records in <var class="product">Model 204</var> list or found set</span>
<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 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 <tt>-1</tt> error code.
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.
   
   
The <var>$FunLoad</var> function accepts six arguments and returns a numeric result.
==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>])
<ul>
<li>The first argument is 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 first argument. To unload the records in a list, specify the name of the list as the first argument.
If you have a FIND statement label and a list with the same name, <var>$FunLoad</var> will use the FIND 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 FUN1 unloads all records found in the FIND statement at label DATA, while the unload at label FUN2 unloadsthe records on list DATA:
<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>
<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
   
   
<var class="product">Model 204</var> FIND 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 (FIND WITHOUT LOCKS) may be suitable.
data: in bigfile find all records for which
. . .
end find
   
   
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 the ''Fast/Unload Reference Manual'').
fun1: %rc = $funload('DATA',...)
<li>The second argument is either the identifier of a $list or 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.
fun2: %rc = $funload('LIST DATA',..)
<li>The third argument is either the identifier of the $list that is to receive the <var class="product">Fast/Unload</var> report data or 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>
<li>The fourth argument, which 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:
<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>
<ul>
<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>
<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>An asterisk (*), indicating that the unloaded data will be processed with $FUNIMG, $FUNSKIP, and/or $FunsStr. Specifying an asterisk for this argument implies that the unload is asynchronous, whether or not the ASYNCH parameter is actually specified.
<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.
<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>  
Prior to <var class="product">Sirius Mods</var> Version 6.5, multiple output data sets are not supported by the <var class="product">Fast/Unload User Language Interface</var>.
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>
This fourth argument must be the DDname of the destination file for the single output stream specified or implied in the FUEL program. <var>$FunLoad</var> will validate the existence and attempt to obtain an exclusive enqueue on the output data set.
</ul>
<p>  
As of <var class="product">Sirius Mods</var> Version 6.5, processing of this argument depends on the <var class="product">Fast/Unload</var> version.:
Processing of this argument depends on the <var class="product">Fast/Unload</var> version: </p>
<ul>
<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 for <var class="product">Sirius Mods</var> prior to Version Version 6.5..
<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.
 
</ul>
<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>
   
   
</ul>
<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>
   
   
<li>The fifth argument is 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>
==Return codes and error messages==
and can, in addition, contain the parameters ASYNCH, ALLMSG and NOTIFY. The description of parameters in the ''Fast/Unload Reference Manual'' shows the default parameter values, showing any differences when invoked via the <var class="product">Fast/Unload User Language Interface</var>.
These are the return codes:
<li>The sixth argument is 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 User Language request is '''not''' cancelled in such a case, but, for synchronous requests, the <var>$FunLoad</var> returns a 32. This is an optional argument and, if not specified, defaults to the FUNMAXT system parameter setting.
<p class="code"> -1 - <var class="product">Fast/Unload</var> PST not available
   
-2 - Input/report/output DDname in use
An explicit or default value of 0 means that there will be no time limit placed on the request. This argument is only available in <var class="product">Sirius Mods</var> Version 6.7 and later. Before that, no time limits were placed on any <var>$FunLoad</var> requests.
  -3 - Ran out of CCATEMP or free storage
   
  -4 - Input/report/output DDname not found
Note that 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.
  -5 - Required parameter not specified
</ul>
-11 - Invalid found set specified
   
-12 - Invalid input/report/output descriptor specified
==Syntax==
-13 - Conflicting parameters
<p class="syntax"><section begin="syntax" /> %RESULT = $FunLoad(found_set, funin, funprint, funout, -
        [parms], [timelimit])
<section end="syntax" /></p>
<p class="caption">$FunLoad Function
</p>
</p>
<p class="caption">%RESULT is set to the 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.</p>
   
   
==Error Codes==
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.
<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>
<p class="caption">$FunLoad Error Codes
</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 User Language request is cancelled with an error message indicating the missing capability. If any missing capabilities which 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 VIEW ERRORS 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.
   
   
Under <var class="product">Sirius Mods</var> Version 6.7 and later, if the X'01' bit is set in the system FUNPARM parameter, the request will be cancelled if a <var>$FunLoad</var> is issued in the middle of an updating transaction. Whether or not FUNPARM 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 FUNTSKN 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>.
To make it easier to diagnose problems where <var class="product">Fast/Unload User Language Interface</var> is involved, under <var class="product">Sirius Mods</var> Version 6.7 and later, 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 User Language Interface</var>.
The message when the requests are started look like:
The message when the requests are started look like:
<p class="code"> MSIR.0890: Asynchronous request 2 made by $FunLoad
<p class="code">MSIR.0890: Asynchronous request 2 made by $FunLoad
</p>
</p>
   
   
And the message when the requests are completed look like:
And the message when the requests are completed look like:
<p class="code"> MSIR.0891: Asynchronous request 2 completed, RC = 0
<p class="code">MSIR.0891: Asynchronous request 2 completed, RC = 0
</p>
</p>
 
==Examples==
==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
   
   
In the following example, the <var class="product">Fast/Unload</var> input data is in DDname FUNIN, the report is to go to DDname FUNPRINT and the data is to be unloaded to DDname FUNOUT.
%rc = $funload('FIND1', 'FUNIN', 'FUNPRINT', 'FUNOUT', 'NOBUFF=6')
<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>
   
   
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>
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.
audit trail, and have the data unloaded to a $list.
<p class="code"> begin
<p class="code">begin
%list1 = $listNew
%list2 = $listNew
   
   
%list1 = $listNew
%rc = $listAdd( %list1, 'FOR EACH RECORD' )
%list2 = $listNew
%rc = $listAdd( %list1, ' PUT &apos;'*&apos;&apos;' )
%rc = $listAdd( %list1, ' OUTPUT' )
%rc = $listAdd( %list1, ' PAI' )
%rc = $listAdd( %list1, 'END FOR' )
   
   
%rc = $listAdd( %list1, 'FOR EACH RECORD' )
find1: in clowns find all records for which
%rc = $listAdd( %list1, ' PUT ''*''' )
  trademark = 'PRATFALL'
%rc = $listAdd( %list1, ' OUTPUT' )
end find
%rc = $listAdd( %list1, ' PAI' )
%rc = $listAdd( %list1, 'END FOR' )
   
   
find1: in clowns find all records for which
%rc = $funload( 'FIND1', %list1, , %list2)  
trademark = 'PRATFALL'
  . . .   
end find
end
%rc = $funload( 'FIND1', %list1, , %list2)
   
. . . . . . . . . .
   
end
</p>
</p>
   
   
In the following example, the input FUEL program is contained in procedure 'UNLOAD1' in the <var class="product">Model 204</var> procedure file called 'FUELPROC'. The data is processed with $FunImg calls (not shown).
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
<p class="code">begin  
declare list hoho in bigfile
. . . 
%replist = $listNew
%records = 'LIST HOHO'
   
   
declare list hoho in bigfile
%inlist = $listNew
   
   
. . . . . . . . . .
%rc = $procOpn('UNLOAD1','FUELPROC')
%rc = $procDat(%inlist)
   
   
%replist = $listNew
%options = 'NEBUFF=4,NBBUFF=2,UPPER,ALLMSG'
%records = 'LIST HOHO'
%rc = $funload( %records, %inlist, , '*', %options )  
  . . .   
%inlist = $listNew
end
%rc = $procOpn('UNLOAD1','FUELPROC')
%rc = $procDat(%inlist)
%options = 'NEBUFF=4,NBBUFF=2,UPPER,ALLMSG'
%rc = $funload( %records, %inlist, , '*', %options )
   
. . . . . . . . . .
   
end
</p>
</p>
   
   
The following is an example of an asynchronous unload request. The input program is in DDname FUNIN, the report data is to go to the <var class="product">Fast/Unload</var>
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 OUTFILE.
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
<p class="code">begin
director = 'HITCHCOCK'
findx: in movies find all records for which
end find
  director = 'HITCHCOCK'
end find
   
   
%options = 'ASYNCH ALLMSG NOBUFF=8'
%options = 'ASYNCH ALLMSG NOBUFF=8'
   
   
%rc = $funload( 'FINDX', 'FUNIN', , 'OUTFILE', %OPTIONS )
%rc = $funload( 'FINDX', 'FUNIN', , 'OUTFILE', %OPTIONS )
   
   
if %rc > 0 then
if %rc > 0 then
print 'Fast/Unload request accepted,' and -
  print 'Fast/Unload request accepted,' and 'request number =' with %rc
'request number =' with %rc
else
else
  Print 'Fast/Unload request rejected,' and 'error code =' and %rc
Print 'Fast/Unload request rejected,' and -
end if   
'error code =' and %rc
end
end if
   
end
</p>
</p>
   
   
==Products authorizing {{PAGENAMEE}}==
<ul class="smallAndTightList">
<ul class="smallAndTightList">
<li>[[Fast/Unload User Language Interface]]
<li>[[Fast/Unload SOUL Interface]] </li>
</ul>
</ul>
<p class="caption">Products authorizing $FunLoad
</p>
   
   
[[Category:$Functions|$FunLoad]]
[[Category:$Functions|$FunLoad]]
[[Category:Fast/Unload User Language Interface]]
[[Category:Fast/Unload SOUL Interface]]

Latest revision as of 02:32, 28 February 2020

Fast/Unload records in Model 204 list or found set

Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $Funload function is the FastUnload function in the Recordset class

This function requests an unload of the data in a Model 204 list or found set using Fast/Unload. If Fast/Unload is not installed at your site, this function returns a -1 error code.

$FunLoad accepts six arguments, as explained below.

Syntax

%result = $FunLoad(found_set, funin, funprint, funout, [parms], [timelimit])

%result This numeric variable is set to the return code from Fast Unload, to the positive request number for asynchronous requests, or to a negative number if Fast/Unload is unable to process the request.
found_set 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 found_set argument. To unload the records in a list, specify the name of the list as the found_set argument.

If you have a FIND statement label and a list with the same name, $FunLoad will use the FIND statement label, unless you explicitly specify that you want to unload a list by preceding the name of the list with the word LIST. For example, in the following program the unload at label FUN1 unloads all records found in the FIND statement at label DATA, while the unload at label FUN2 unloadsthe records on list DATA:

declare list data in bigfile data: in bigfile find all records for which . . . end find fun1: %rc = $funload('DATA',...) fun2: %rc = $funload('LIST DATA',..)

Model 204 FIND 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 (FIND WITHOUT LOCKS) may be suitable.

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 $FunLoad runs, as described in Fast/Unload Extraction Language (FUEL)).

funin The identifier of a $list, or it is the DDname of an input program. This argument corresponds to FUNIN in batch mode Fast/Unload. This is a required parameter.
funprint The identifier of the $list that is to receive the Fast/Unload report data, or it is the DDname of a file that is to receive the Fast/Unload 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 Fast/Unload.

If this parameter is not specified, all report data will go to the Fast/Unload audit trail.

funout Corresponds to FUNOUT in batch mode Fast/Unload; specifies the destination for the output data. This argument is required, and it may be one of the following:
  • 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.
  • An asterisk (*), indicating that the unloaded data will be processed with $FunImg, $FunSkip, and/or $FunsStr. Specifying an asterisk for the funout argument implies that the unload is asynchronous, whether or not the ASYNCH parameter is actually specified.
  • 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.

    Formerly, multiple output data sets were not supported by the Fast/Unload SOUL Interface, and this funout argument had to be the DDname of the destination file for the single output stream specified or implied in the FUEL program. $FunLoad validated the existence and attempted to obtain an exclusive enqueue on the output data set.

Processing of this argument depends on the Fast/Unload version:

  • For Fast/Unload versions prior to 4.2, only a single output stream is supported, and processing is as described above.
  • For Fast/Unload 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. Fast/Unload will validate the existence and attempt to obtain an exclusive enqueue on all output data sets specified or implied in the FUEL program.
parms A string that specifies the Fast/Unload parameters. This string can contain any of the parameters allowed on the PARM option on the EXEC card for batch mode Fast/Unload 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 Fast/Unload SOUL Interface.
timelimit A number indicating the maximum amount of time in seconds that the request is to be allowed to complete. If the $FunLoad request does not complete within this time, the $FunLoad request is immediately cancelled. The SOUL request is not cancelled in such a case, but, for synchronous requests, $FunLoad returns a 32. This is an optional argument and, if not specified, defaults to the FUNMAXT system parameter setting.

An explicit or default value of 0 means that there will be no time limit placed on the request.

Note: The time limit includes the time waiting for the request to actually be run by a Fast/Unload task, so a request could time out because of other long-running requests tying up the Fast/Unload tasks.

Return codes and error messages

These are the return codes:

-1 - Fast/Unload 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

In addition to the above error codes, if $FunLoad discovers that a required capability is not supported by the version of Fast/Unload in use, the SOUL request is cancelled with an error message indicating the missing capability. If any missing capabilities that would prevent successful $FunLoad operation are discovered during Model 204 initialization, an operator warning is issued and saved in the VIEW ERRORS table, so that corrective action may be taken in advance.

If the X'01' bit is set in the system FUNPARM parameter, the request is cancelled if a $FunLoad is issued in the middle of an updating transaction. Whether or not FUNPARM X'01' is set, it is generally best to avoid $FunLoad calls in the middle of an updating transaction, since $FunLoad calls can take a long time to run, even if the specific $FunLoad request is relatively small. This is so because all $FunLoad requests share the same FUNTSKN subtasks, and if these are tied up with relatively long-running requests, all other requests must wait for access to a Fast/Unload task.

To make it easier to diagnose problems where Fast/Unload SOUL Interface is involved, messages are also sent to the Model 204 journal/audit trail at each Fast/Unload request made and at each completed by the Fast/Unload SOUL Interface. The message when the requests are started look like:

MSIR.0890: Asynchronous request 2 made by $FunLoad

And the message when the requests are completed look like:

MSIR.0891: Asynchronous request 2 completed, RC = 0

Examples

In the following example, the Fast/Unload input data is in DDname FUNIN, the report is to go to DDname FUNPRINT, and the data is to be unloaded to DDname FUNOUT.

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

In the following example, we dynamically build the unload input program, have the report data simply go to the Fast/Unload audit trail, and have the data unloaded to a $list.

begin %list1 = $listNew %list2 = $listNew %rc = $listAdd( %list1, 'FOR EACH RECORD' ) %rc = $listAdd( %list1, ' PUT ''*''' ) %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

In the following example, the input FUEL program is contained in procedure UNLOAD1 in the Model 204 procedure file called FUELPROC. The data is processed with $FunImg calls (not shown).

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

The following is an example of an asynchronous unload request. The input program is in DDname FUNIN, the report data is to go to the Fast/Unload audit trail, and the data is to be dumped to DDname OUTFILE.

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

Products authorizing $FunLoad