Fast/Unload customer-written assembler function packages - Revision history

Tom: /* Function statement must follow OPEN, not precede it */

2015-06-15T14:20:34Z

Function statement must follow OPEN, not precede it

← Older revision		Revision as of 14:20, 15 June 2015
Line 762:		Line 762:
	If the <code>TEXT</code> file created in the preceding step is on an accessed		If the <code>TEXT</code> file created in the preceding step is on an accessed
	CMS minidisk, you can use the following <code>FUNIN</code> file:		CMS minidisk, you can use the following <code>FUNIN</code> file:
	<p class="code"><nowiki>~~FUNCTIONS UFUN~~		<p class="code"><nowiki>
	OPEN PEOPLE		OPEN PEOPLE
			FUNCTIONS UFUN
	FOR EACH RECORD		FOR EACH RECORD
	%PALINDROME = #RVRSTR(NAME)		%PALINDROME = #RVRSTR(NAME)

Tom: /* functions statement must follow OPEN, not precede it */

2015-06-15T14:19:42Z

functions statement must follow OPEN, not precede it

← Older revision		Revision as of 14:19, 15 June 2015
Line 736:		Line 736:
	//FUNCPKG DD DISP=SHR,DSN=USER.FUNCPKG Custom package		//FUNCPKG DD DISP=SHR,DSN=USER.FUNCPKG Custom package
	//FUNIN DD *		//FUNIN DD *
			OPEN PEOPLE
	FUNCTIONS IN FUNCPKG LOCFUNCS		FUNCTIONS IN FUNCPKG LOCFUNCS
	~~OPEN PEOPLE~~
	FOR EACH RECORD		FOR EACH RECORD
	%PALINDROME = #RVRSTR(NAME)		%PALINDROME = #RVRSTR(NAME)

JAL: add template

2015-03-11T19:46:15Z

add template

← Older revision		Revision as of 19:46, 11 March 2015
Line 773:		Line 773:

	==See also==		==See also==
	[[Fast/Unload ~~overview#WIKFUN$$topics\|Fast/Unload topics]]~~		{{Template:Fast/Unload topic list}}

JAL: more conversion cleanup

2015-02-23T20:33:17Z

more conversion cleanup

Show changes

JAL at 18:08, 23 January 2015

2015-01-23T18:08:54Z

← Older revision		Revision as of 18:08, 23 January 2015
Line 1:		Line 1:
			{{DISPLAYTITLE:Fast/Unload customer-written assembler #function packages}}
	<!-- Page name: Fast/Unload customer-written assembler function packages-->		<!-- Page name: Fast/Unload customer-written assembler function packages-->
	~~{{DISPLAYTITLE:Fast/Unload customer-written assembler #function packages}}~~

	You can extend the set of #functions available at your site by writing		You can extend the set of #functions available at your site by writing
	one or more collections of them and making them available to FUEL.		one or more collections of them and making them available to FUEL.

JAL: # in page title

2015-01-23T18:08:02Z

# in page title

← Older revision		Revision as of 18:08, 23 January 2015
Line 1:		Line 1:
	<!-- Page name: Fast/Unload customer-written assembler function packages-->		<!-- Page name: Fast/Unload customer-written assembler function packages-->
	~~<p><~~/p>		{{DISPLAYTITLE:Fast/Unload customer-written assembler #function packages}}

	You can extend the set of #functions available at your site by writing		You can extend the set of #functions available at your site by writing
	one or more collections of them and making them available to FUEL.		one or more collections of them and making them available to FUEL.
Line 16:		Line 17:
	not even need to reassemble your #functions.		not even need to reassemble your #functions.
	</ul>		</ul>

	==Members of SIRIUS.OBJLIB used in coding #functions==		==Members of SIRIUS.OBJLIB used in coding #functions==
	<p></p>		<p></p>
Line 21:		Line 23:
	distribution tape to assist you in developing #functions.		distribution tape to assist you in developing #functions.
	They are described in this section.		They are described in this section.

	===Run-time interface symbols: FUNCEQU COPY===		===Run-time interface symbols: FUNCEQU COPY===
	~~<p></p>~~
	This COPY member should be made available in a MACLIB to assemble any		This COPY member should be made available in a MACLIB to assemble any
	<nowiki>#functions</nowiki> you write.		<nowiki>#functions</nowiki> you write.

DmeWiccan: Automatically generated page update

2015-01-15T19:40:15Z

Automatically generated page update

← Older revision		Revision as of 19:40, 15 January 2015
Line 1:		Line 1:
	~~{{DISPLAYTITLE:Fast/Unload customer-written assembler #function packages}}~~
	<!-- Page name: Fast/Unload customer-written assembler function packages-->		<!-- Page name: Fast/Unload customer-written assembler function packages-->
	<p></p>		<p></p>

JAL: change page title display

2015-01-14T15:14:40Z

change page title display

← Older revision		Revision as of 15:14, 14 January 2015
Line 1:		Line 1:
	{{DISPLAYTITLE:Fast/Unload customer-written assembler #function ~~package~~}}		{{DISPLAYTITLE:Fast/Unload customer-written assembler #function packages}}
	<!-- Page name: Fast/Unload customer-written assembler function packages-->		<!-- Page name: Fast/Unload customer-written assembler function packages-->
	<p></p>		<p></p>

JAL: change page title display

2015-01-14T15:09:59Z

change page title display

← Older revision		Revision as of 15:09, 14 January 2015
Line 1:		Line 1:
			{{DISPLAYTITLE:Fast/Unload customer-written assembler #function package}}
	<!-- Page name: Fast/Unload customer-written assembler function packages-->		<!-- Page name: Fast/Unload customer-written assembler function packages-->
	<p></p>		<p></p>

DmeWiccan: Automatically generated page update

2015-01-14T00:49:18Z

Automatically generated page update

New page

You can extend the set of #functions available at your site by writing
one or more collections of them and making them available to FUEL.
The items enabling you to do this are:
<ul>
<li>The FUNCTIONS statement has been added to FUEL to identify the
location of #functions you have written.
<li>An efficient, easy-to-use interface has been designed for matching
a #function name to the code implementing that #function.
<li>An efficient, easy-to-use interface has been designed for performing
common operations needed by #functions, such as obtaining the value of
arguments and setting the result value and output arguments.
<li>The interfaces have been designed with compatibility in mind;
with new releases of <var class="product">Fast/Unload</var> you will
not even need to reassemble your #functions.
</ul>
==Members of SIRIUS.OBJLIB used in coding #functions==

Some assembler language source files are included in your <var class="product">Fast/Unload</var>
distribution tape to assist you in developing #functions.
They are described in this section.
===Run-time interface symbols: FUNCEQU COPY===

This COPY member should be made available in a MACLIB to assemble any
<nowiki>#functions</nowiki> you write.
The symbols defined in it consist of the values you can pass to
the <var class="product">Fast/Unload</var> #function service routine, for the various
services being requested.
The only value defined in this COPY member which will change is
the symbol FUNQX, which will increase when additional services are
added to the interface.

Note: Prior to the release of version 4.0 of <var class="product">Fast/Unload</var>, one of the symbols,
FUNQAFS, was incorrectly defined.
Be sure you are using the corrected FUNCEQU COPY, which contains the
following assembler statement:
<nowiki>FUNQAFS EQU 11 Assign float to arg...
</nowiki>
===Example #function package: UFUN ASSEMBLE===

This ASSEMBLE program contains the package-searching code, along with
one sample #function available in the package.
You can modify this program to write a #function package, using your
own #function names in the table.

Since future versions of <var class="product">Fast/Unload</var> may contain new standard #functions,
you should choose a naming convention for your #functions which is not
likely to overlap the standard #functions.
==Compiler call to package to locate #function==

When a #function call
is compiled in a FUEL program, if the #function name is not one of
the standard <var class="product">Fast/Unload</var> #functions,
all #function packages
are dynamically loaded and called, in the order specified, until the
<nowiki>#function</nowiki> name is in the package.

The registers passed to the #function package are:
<table>
<tr><th>R1</th><td>The address of a byte, which contains the length of the <nowiki>#function</nowiki> name, followed by the #function name, blank padded to 255 bytes.</td></tr>
<tr><th>R6</th><td>The address of a 4096 byte work area which is passed to all <nowiki>#function</nowiki> packages and to all #functions. This area is initally all binary zeroes and is aligned on a doubleword boundary. <var class="product">Fast/Unload</var> does not modify this area.</td></tr>
<tr><th>R13</th><td>The address of a 4096 byte work area which is passed only to this #function package and to all #functions within this package. This area is initially all binary zeroes and is aligned on a doubleword boundary. <var class="product">Fast/Unload</var> does not modify this area.</td></tr>
<tr><th>R14</th><td>The return address.</td></tr>
<tr><th>R15</th><td>The entry point of the #function package.</td></tr>
</table>

The registers returned by the #function package are:
<table>
<tr><th>R0</th><td>Must contain 0.</td></tr>
<tr><th>R1</th><td>One of the following two cases: <ul>
<li>0 to indicate the #function is not part of the package.
<li>A positive number, which is the entry point of the #function. </ul></td></tr>
<tr><th>R2</th><td>A bit mask, to indicate which arguments are required. For example, X'A0000000' indicates the first and third arguments are required (a rather strange example).</td></tr>
<tr><th>R3</th><td>A bit mask, to indicate which arguments, if specified, must be %variables (i.e., available as output). For example, X'30000000' indicates the third and fourth arguments are output arguments.</td></tr>
<tr><th>R4</th><td>Maximum number of arguments the #function can accept.</td></tr>
<tr><th>R5-R15</th><td>Need not be restored, can contain any value.</td></tr>
</table>
==Run-time invocation of #function==

This section describes the registers passed to a #function
(none need be returned by the #function),
and the services that <var class="product">Fast/Unload</var> makes available for use by a #function.

The registers passed to a #function are:
<table>
<tr><th>R5</th><td>The address of a service routine to retrieve from or assign to the #function arguments or perform other services. See the description of the interface to the service routine, presented next in this section.</td></tr>
<tr><th>R6</th><td>The address of a 4096 byte work area which is passed to all <nowiki>#function</nowiki> packages and all to #functions. <var class="product">Fast/Unload</var> does not modify this area.</td></tr>
<tr><th>R13</th><td>The address of a 4096 byte work area which is passed only to a given #function package and to all <nowiki>#functions</nowiki> which were resolved by a call to that package. <var class="product">Fast/Unload</var> does not modify this area.</td></tr>
<tr><th>R14</th><td>The return address.</td></tr>
<tr><th>R15</th><td>The entry point of the #function.</td></tr>
</table>

The argument values can be returned by the service routine;
various values (FUNQ2xxx) are used for different types.

There is no information returned from a #function in the registers.
No registers need be restored; they can contain any value.
The result value and output arguments
of a #function are set by
passing various values
(FUNQ2xxx) to the service routine.

The service routine which is passed to a #function in register R5 is
used to retrieve the value of or perform assignment into the #function
arguments or result, issue error messages, terminate <var class="product">Fast/Unload</var>, and
manage memory.

The registers at entry to the service routine are described below;
individual services have some exceptions, which are explained in the
description of the services in this section.
<table>
<tr><th>R0</th><td>Unless specified otherwise, the argument number for the service. Argument number 0 designates the #function result.</td></tr>
<tr><th>R1</th><td>A code indicating the service required (symbols for this code are defined in FUNCQEU COPY).</td></tr>
<tr><th>R2</th><td>As described for individual service descriptions in this section.</td></tr>
<tr><th>F0</th><td>(Floating point register 0); as described for individual service descriptions in this section.</td></tr>
<tr><th>R14</th><td>The return address.</td></tr>
</table>

The registers on return from
the service routine are
explained in the
description of the services in this section.
For all services, the registers on return from the service routine are:
<table>
<tr><th>R0-R2</th><td>Unless specified for an individual service, unpredictable.</td></tr>
<tr><th>R3-R14</th><td>Unchanged from values at entry.</td></tr>
<tr><th>R15</th><td>Usually a return code; if not specified by the service routine description, unpredictable.</td></tr>
</table>
===Get information about #function argument(s)===

This service obtains the number of arguments to the
<nowiki>#function</nowiki> and optionally the type (omitted/present,
MISSING value or not, and output or not)
of a specified argument.



This service is most often invoked for #functions which
have a variable number of arguments (such as #CONCAT).
For a different usage
example, it can be invoked as follows to see if a particular
argument is an output argument (although the function package
makes sure that if an argument is declared as output, any
function call using that argument is a %variable):
<nowiki> LA R0,xxx Get info about arg xxx
LA R1,FUNQAI Get service number
BALR R14,R5 Call service
LTR R15,R15 Is arg an output arg?
BP ... No, handle condition
</nowiki>

Special input registers for this service are:
<table>
<tr><th>R0</th><td>Argument number (0 means don't get single arg info).</td></tr>
</table>

Output registers for this service are:
<table>
<tr><th>R0</th><td>Number of arguments (including omitted arguments after a comma) (i.e., 0 if no args, else 1 + number of commas). :lp.Following output registers only apply if this service is called with R0 > 0:</td></tr>
<tr><th>R1</th><td>0: Argument has a value. 4: Argument is not present. 8: Argument is present but value is MISSING.</td></tr>
<tr><th>R15</th><td>0: Argument is an output arg; assignment will be OK. 4: Argument is not present. 8: Argument present but not an output arg.</td></tr>
</table>
===Get string value of argument===

This pair of services obtains the string
value of a specified argument.
The strict service (FUNQ2SS) will terminate if the argument is
omitted.
The conditional service (FUNQ2SC) will allow all argument cases.
Either service will reflect exception argument cases
by a return code in register R15 and a zero length in register R0.

For example, they can be invoked as follows:
<nowiki> LA R0,xxx Get value of arg xxx
LA R1,FUNQ2SS Service number: omitted CANCEL
BALR R14,R5 Call service
* Omit following two lines if null for MISSING is OK:
CH R15,=H'8' Is value MISSING?
BE ... Yes, handle condition
LTR R15,R0 Is string zero-length?
BZ ... Yes, handle condition
BCTR R15,0 No, get length - 1
EX R15,MVCA MVC xx(0,R13),0(R1) Copy to work area
</nowiki>
or
<nowiki> LA R0,xxx Get value of arg xxx
LA R1,FUNQ2SC Get service number - allow errors
BALR R14,R5 Call service
CH R15,=H'4' Is arg present?
BE ... No, handle condition
LTR R15,R0 Is string zero-length?
BZ ... Yes, handle condition
BCTR R15,0 No, get length - 1
EX R15,MVCA MVC xx(0,R13),0(R1) Copy to work area
* Omit following two lines if no DBCS data handled:
LTR R2,R2 Is string DBCS?
BC ... Handle condition
</nowiki>

These services have no special input registers.

Output registers for these services are:
<table>
<tr><th>R0</th><td>Length of string value (0 if omitted or MISSING value).</td></tr>
<tr><th>R1</th><td>Address of string value.</td></tr>
<tr><th>R2</th><td> 0: Not a DBCS string or not DBCS run > 0: Mixed DBCS string < 0: Pure DBCS string</td></tr>
<tr><th>R15</th><td>0: Argument contains string value. 4: Argument is not present. 8: Argument present but value is MISSING.</td></tr>
</table>
===Get float value of argument===

This pair of services obtains the 8 byte floating point
value of a specified argument.
The strict service (FUNQ2FS) will terminate if the argument is
omitted, has a non-numeric value, or has a
value too large in absolute value to store in
an eight byte floating point number (insignificant
fractions will be truncated without
error).
The conditional service (FUNQ2FC) will allow all argument cases.
Either service will reflect exception argument cases
by a return code in register R15 and a zero in float register F0.

For example, they can be invoked as follows:

<nowiki> LA R0,xxx Get value of arg xxx
LA R1,FUNQ2FS Service num: omit/non-num CANCEL
BALR R14,R5 Call service
* Omit following two lines if zero for MISSING is OK:
CH R15,=H'8' Is value MISSING?
BE ... Yes, handle condition
STD F0,xxx(,R13) Save value in work area
</nowiki>

or
<nowiki> LA R0,xxx Get value of arg xxx
LA R1,FUNQ2FC Get service number - allow errors
BALR R14,R5 Call service
B *+4(R15) Handle conditions
B OK Handle success
B ... Handle arg omitted
B ... Handle MISSING value
B ... Handle conversion error
OK STD F0,xxx(,R13) Save value in work area
</nowiki>

These services have no special input registers.

Output registers for these services are:
<table>
<tr><th>F0</th><td>Float value (0 if omitted/unconvertible).</td></tr>
<tr><th>R15</th><td> 0: Argument contains float value. 4: Argument is not present. 8: Argument present but value is MISSING. 12: Argument value can't be converted to float.</td></tr>
</table>
===Get fixed value of argument===

This pair of services obtains the 4 byte binary integer
value of a specified argument.
The strict service (FUNQ2BS) will terminate if the argument is
omitted, has a non-numeric value, or has a
value too large (positive) or too small (negative) to store in
a four byte signed binary number (fractions will be truncated without
error).
The conditional service (FUNQ2FC) will allow all argument cases.
Either service will reflect exception argument cases
by a return code in register R15 and a zero in register R1.

For example, they can be invoked as follows:

<nowiki> LA R0,xxx Get value of arg xxx
LA R1,FUNQ2BS Service num: omit/non-num CANCEL
BALR R14,R5 Call service
* Omit following two lines if zero for MISSING is OK:
CH R15,=H'8' Is value MISSING?
BE ... Yes, handle condition
ST R1,xxx(,R13) Save value in work area
</nowiki>

or
<nowiki> LA R0,xxx Get value of arg xxx
LA R1,FUNQ2BC Get service number - allow errors
BALR R14,R5 Call service
B *+4(R15) Handle conditions
B OK Handle success
B ... Handle arg omitted
B ... Handle MISSING value
B ... Handle conversion error
OK ST R1,xxx(,R13) Save value in work area
</nowiki>

These services have no special input registers.

Output registers for these services are:
<table>
<tr><th>R1</th><td>Binary value (0 if omitted/unconvertible).</td></tr>
<tr><th>R15</th><td> 0: Argument contains integer value (maybe truncated). 4: Argument is not present. 8: Argument present but value is MISSING. 12: Argument value can't be converted to fullword int.</td></tr>
</table>
===Assign string value to argument===

This pair of services sets the
value of a specified argument to a specified byte string.
The strict service (FUNQASS) will terminate if the argument is
omitted or is not an output argument.
The conditional service (FUNQASC) will reflect these errors
by a return code in register R15.


They are invoked as follows:
<nowiki> LA R0,xxx Set value of arg xxx
LA R1,FUNQASS Get service number - errors CANCEL
LA R2,... Address of string to assign
set R3,... Length of string to assign
* Omit following line if no DBCS data handled:
set R4,... Indicate DBCS string type
BALR R14,R5 Call service
</nowiki>

or
<nowiki> LA R0,xxx Set value of arg xxx
LA R1,FUNQASC Get service number - allow errors
LA R2,... Address of string to assign
LA R3,... Length of string to assign
* Omit following line if no DBCS data handled:
set R4,... Indicate DBCS string type
BALR R14,R5 Call service
CH R15,=H'4' Is arg present/output?
BC ... Handle condition
</nowiki>

Special input registers for these services are:
<table>
<tr><th>R2</th><td>Address of value to assign.</td></tr>
<tr><th>R3</th><td>Length of value to assign (must be < 256).</td></tr>
<tr><th>R4</th><td>If a DBCS run: 0: Not a DBCS string > 0: Mixed DBCS string < 0: Pure DBCS string</td></tr>
</table>

Output registers for these services are:
<table>
<tr><th>R15</th><td>0: Assignment successful. 4: Assignment failed: arg omitted. 8: Assignment failed: arg is not output.</td></tr>
</table>

For FUNQASS, since the non-0 cases for R15 cause the
<var class="product">Fast/Unload</var> program to be terminated, if the service returns then R15 will
be 0.
===Assign float value to argument===

This pair of services sets the
value of a specified argument to a specified 8 byte floating point value.
The strict service (FUNQAFS) will terminate if the argument is
omitted or is not an output argument.
The conditional service (FUNQAFC) will reflect these errors
by a return code in register R15.


They are invoked as follows:
<nowiki> LA R0,xxx Set value of arg xxx
LA R1,FUNQAFS Get service number - errors CANCEL
LD F0,... Value to assign
BALR R14,R5 Call service
</nowiki>

or
<nowiki> LA R0,xxx Set value of arg xxx
LA R1,FUNQAFC Get service number - allow errors
LD F0,... Value to assign
BALR R14,R5 Call service
CH R15,=H'4' Is arg present/output?
BC ... Handle condition
</nowiki>

Special input registers for these services are:
<table>
<tr><th>F0</th><td> Value to assign.</td></tr>
</table>

Output registers for these services are:
<table>
<tr><th>R15</th><td>0: Assignment successful. 4: Assignment failed: arg omitted. 8: Assignment failed: arg is not output.</td></tr>
</table>

For FUNQAFS, since the non-0 cases for R15 cause the
<var class="product">Fast/Unload</var> program to be terminated, if the service returns then R15 will
be 0.

Note: Prior to the release of version 4.0 of <var class="product">Fast/Unload</var>,
FUNQAFS was incorrectly defined.
Be sure you are using the corrected FUNCEQU COPY, which contains the
following assembler statement:
<nowiki>FUNQAFS EQU 11 Assign float to arg...
</nowiki>
===Assign fixed value to argument===

This pair of services sets the
value of a specified argument to a specified 4 byte binary integer value.
The strict service (FUNQABS) will terminate if the argument is
omitted or is not an output argument.
The conditional service (FUNQABC) will reflect these errors
by a return code in register R15.


They are invoked as follows:
<nowiki> LA R0,xxx Set value of arg xxx
LA R1,FUNQABS Get service number - errors CANCEL
L R2,... Value to assign
BALR R14,R5 Call service
</nowiki>

or
<nowiki> LA R0,xxx Set value of arg xxx
LA R1,FUNQABC Get service number - allow errors
L R2,... Value to assign
BALR R14,R5 Call service
CH R15,=H'4' Is arg present/output?
BC ... Handle condition
</nowiki>

Special input registers for these services are:
<table>
<tr><th>R2</th><td> Value to assign.</td></tr>
</table>

Output registers for these services are:
<table>
<tr><th>R15</th><td>0: Assignment successful. 4: Assignment failed: arg omitted. 8: Assignment failed: arg is not output.</td></tr>
</table>

For FUNQABS, since the non-0 cases for R15 cause the
<var class="product">Fast/Unload</var> program to be terminated, if the service returns then R15 will
be 0.
===Allocate storage===

This pair of services allocates dynamic storage, above (FUNQGMA) or
below (FUNQGMB) the 16 meg line, respectively.


They are invoked as follows:
<nowiki> LA R0,... Length of storage to allocate
LA R2,=C'... Label for storage
LA R1,FUNQGMB Get service number - below 16 MB
BALR R14,R5 Call service
</nowiki>

or
<nowiki> LA R0,... Length of storage to allocate
LA R2,=C'... Label for storage
LA R1,FUNQGMA Get service number - above 16 MB
BALR R14,R5 Call service
</nowiki>

Special input registers for these services are:
<table>
<tr><th>R0</th><td>Length of storage in bytes.</td></tr>
<tr><th>R2</th><td>Address of 8 character eyecatcher for storage.</td></tr>
</table>

Output registers for these services are:
<table>
<tr><th>R1</th><td>Address of storage allocated.</td></tr>
</table>

If the storage is
not available, the FUEL program is terminated (i.e.,
the service does not return).
===Release storage===

This service releases a block of storage which was
previously allocated (partial blocks may not be released).


It is invoked as follows:
<nowiki> LR R0,... Address of storage to release
LA R1,FUNQFM Get service number
BALR R14,R5 Call service
</nowiki>

Special input registers for this service are:
<table>
<tr><th>R0</th><td>Address of storage to release.</td></tr>
</table>

This service has no output registers.
===Issue an error message and/or set return code===

This service issues the FUNL0111 message, with the specified
text, and/or changes the <var class="product">Fast/Unload</var> program return code.


The FUNQMSG service is invoked in a variety of ways.
To issue a message without changing the current return code:
<nowiki> LA R0,MSG Address of message text
LA R1,FUNQMSG Get service number
LA R2,L'MSG Length of message text
SLR R3,R3 Indicate no change to return code
BALR R14,R5 Call service
</nowiki>

To issue a message and ensure that the return code is
set at least as large as a supplied value:
<nowiki> LA R0,MSG Address of message text
LA R1,FUNQMSG Get service number
LA R2,L'MSG Length of message text
LA R3,value Set minimum return code
BALR R14,R5 Call service
ST R15,xxx(,RD) Save prior value of return code
</nowiki>

To ensure that the return code is set at least as large as a
supplied value, without printing a message:
<nowiki> LA R1,FUNQMSG Get service number
SLR R2,R2 Indicate no message text
BCTR R2,0 Optionally suppress FUNL0111
LA R3,value Set minimum return code
BALR R14,R5 Call service
ST R15,xxx(,RD) Save prior value of return code
</nowiki>

To force return code to specific value, without regard to
previous value, with or without printing a message:
<nowiki> LA R1,FUNQMSG Get service number
IF ... Message desired
LA R0,MSG Address of message text
LA R2,L'MSG Length of message text
ELSE , No message
SLR R2,R2 No message text, but FUNL0111
BCTR R2,0 Eliminate FUNL0111 header as well
ENDIF ,
LH R3,=H'-1' Change return code in any case
LA R4,value Set new return code
BALR R14,R5 Call service
ST R15,xxx(,RD) Save prior value of return code
</nowiki>

Special input registers for this service are:
<table>
<tr><th>R0</th><td>Address of message.</td></tr>
<tr><th>R2</th><td>Length of message; if less than 0, message not issued. Must be less than 256. Trailing blanks preserved.</td></tr>
<tr><th>R3</th><td> 0: do not change return code. > 0: change return code to this value if it is less than that value. < 0: change return code to value in R4, regardless.</td></tr>
<tr><th>R4</th><td>New return code, if R3 less than 0.</td></tr>
</table>

Output registers for this service are:
<table>
<tr><th>R15</th><td>Prior value of return code.</td></tr>
</table>
===Terminate Fast/Unload., optionally set return code===

This service terminates <var class="product">Fast/Unload</var>, and optionally
changes the <var class="product">Fast/Unload</var> program return code.


The FUNQTRM service is invoked in a variety of ways.
To terminate the current run without changing the return code:
<nowiki> LA R1,FUNQTRM Get service number
SLR R3,R3 Indicate no change to return code
BALR R14,R5 Call service
</nowiki>

To terminate the current run and ensure that the return code
is at least as high as a provided number:
<nowiki> LA R1,FUNQTRM Get service number
LA R3,value Set minimum return code
BALR R14,R5 Call service
</nowiki>

To terminate the current run and set the return code to a given
value without regard to its previous value:
<nowiki> LA R1,FUNQTRM Get service number
LH R3,=H'-1' Change return code in any case
LA R4,value Set return code
BALR R14,R5 Call service
</nowiki>

Special input registers for this service are:
<table>
<tr><th>R0</th><td>Unused.</td></tr>
<tr><th>R3</th><td> 0: do not change return code. > 0: change return code to value in R3 if it is less than that value. < 0: change return code to value in R4, regardless.</td></tr>
<tr><th>R4</th><td>New return code, if R3 less than 0.</td></tr>
</table>

This service does not return.
==Example - z/OS==
This example demonstrates use of the sample #function package contained
on the distribution tape, in the z/OS environment.
===Installing a #function package===

This step consists of assembling and link-editing a #function package.
<nowiki>//ASMLINK EXEC ASMCL
//ASM.SYSIN DD DISP=SHR,DSN=SIRIUS.LIB(UFUN) Sample package
//ASM.SYSLIB DD DISP=SHR,DSN=SIRIUS.LIB FUNCEQU macro
//LINK.SYSLMOD DD DISP=(NEW,CATLG),DSN=USER.FUNCPKG
//LINK.SYSIN DD *
NAME LOCFUNCS(R)
/*
</nowiki>
===Using a #function package===

Shown here are the changes to the <var class="product">Fast/Unload</var> JCL and FUEL needed
to use a #function package.
<nowiki>//FUNLOAD EXEC PGM=FUNLOAD
//... Normal JCL
//FUNCPKG DD DISP=SHR,DSN=USER.FUNCPKG Custom package
//FUNIN DD *
FUNCTIONS IN FUNCPKG LOCFUNCS
OPEN PEOPLE
FOR EACH RECORD
%PALINDROME = #RVRSTR(NAME)
%PALINDROME = #CONCAT(NAME, %PALINDROME)
PUT %PALINDROME
OUTPUT
END FOR
</nowiki>
==Example - CMS==
This example demonstrates use of the sample #function package contained
on the distribution tape, in the CMS environment.
===Installing a #function package===

This step consists of assembling a #function package.
<nowiki>* Create a macro library with FUNCEQU:
MACLIB GEN FUNLOAD FUNCEQU
* Assemble the package:
GLOBAL MACLIB FUNCEQU
HASM UFUN
</nowiki>
===Using a #function package===

If the TEXT file created in the preceding step is on an accessed
CMS minidisk, you can use the following FUNIN file:
<nowiki>FUNCTIONS UFUN
OPEN PEOPLE
FOR EACH RECORD
%PALINDROME = #RVRSTR(NAME)
%PALINDROME = #CONCAT(NAME, %PALINDROME)
PUT %PALINDROME
OUTPUT
END FOR
</nowiki>
==See also==
[[Fast/Unload overview#WIKFUN$$topics|Fast/Unload topics]]