Fast/Unload standard functions: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (add 4.6 new option to #Words)
 
(18 intermediate revisions by 3 users not shown)
Line 1: Line 1:
<!-- Page name: Fast/Unload standard functions-->
{{DISPLAYTITLE:Fast/Unload standard #functions}}
{{DISPLAYTITLE:Fast/Unload standard #functions}}
This wiki page lists the #functions provided with <var class="product">Fast/Unload</var>.
This wiki page lists the #functions provided with <var class="product">Fast/Unload</var>.
Line 84: Line 83:
</ol>
</ol>


<div id="funerr"></div>
==<b id="funerr"></b>Run-time errors during standard #function calls==
==Run-time errors during standard #function calls==
<!--Caution: <div> above-->
The default approach for handling errors in calls to standard
The default approach for handling errors in calls to standard
<nowiki>#functions</nowiki> is strict:
<nowiki>#functions</nowiki> is strict:
Line 145: Line 141:
missing required arguments or too many arguments, because such checking is done at compile time.
missing required arguments or too many arguments, because such checking is done at compile time.
   
   
<div id="abdump"></div>
==<b id="abdump"></b>#ABDUMP: End Fast/Unload with ABEND and dump==
==#ABDUMP: End Fast/Unload with ABEND and dump==
<!--Caution: <div> above-->
The <var>#ABDUMP</var> function accepts a numeric argument, and it causes the
The <var>#ABDUMP</var> function accepts a numeric argument, and it causes the
<var class="product">Fast/Unload</var> job to terminate with user abend code equal to that argument,
<var class="product">Fast/Unload</var> job to terminate with user abend code equal to that argument,
Line 163: Line 156:
</table>
</table>
<p>
<p>
For example, the following fragment abends the job
<b>Examples</b>
</p>
<p>
The following fragment abends the job
when the input record number is 12345:
when the input record number is 12345:
</p>
</p>
Line 180: Line 176:
This #function is new in <var class="product">Fast/Unload</var> version 4.1.
This #function is new in <var class="product">Fast/Unload</var> version 4.1.
   
   
<div id="conc"></div>
==<b id="conc"></b>#CONCAT: Concatenate strings==  
==#CONCAT: Concatenate strings==
<!--Caution: <div> above-->
The <var>#CONCAT</var> function accepts two or more arguments,
The <var>#CONCAT</var> function accepts two or more arguments,
and it returns a string value that is the concatenation of all of its
and it returns a string value that is the concatenation of all of its
Line 203: Line 196:
<td>Concatenation of inputs.</td></tr>
<td>Concatenation of inputs.</td></tr>
</table>
</table>
 
<p>
For example, the following fragment prints the line
<b>Examples</b>
<code>Bugs Bunny</code> on the FUNPRINT data set:
</p>
The following fragment prints the line <code>Bugs Bunny</code> on the FUNPRINT data set:
<p class="code"><nowiki>%RABBIT = #CONCAT('Bugs', ' ', 'Bunny')
<p class="code"><nowiki>%RABBIT = #CONCAT('Bugs', ' ', 'Bunny')
REPORT %RABBIT
REPORT %RABBIT
Line 231: Line 225:
</ul>
</ul>
   
   
<div id="concatt"></div>
 
==#CONCAT_TRUNC: Concatenate strings, allowing truncation==
==<b id="concatt"></b>#CONCAT_TRUNC: Concatenate strings, allowing truncation==
<!--Caution: <div> above-->
The <var>#CONCAT_TRUNC</var> function accepts an optional output argument
The <var>#CONCAT_TRUNC</var> function accepts an optional output argument
and two or more string arguments,
and two or more string arguments,
Line 262: Line 254:
<td>Concatenation of <var class="term">stra</var>, <var class="term">strb</var>, ..., or the first 255 bytes of that concatenation, if it exceeds 255.</td></tr>
<td>Concatenation of <var class="term">stra</var>, <var class="term">strb</var>, ..., or the first 255 bytes of that concatenation, if it exceeds 255.</td></tr>
</table>
</table>
 
<p>
For example, the following fragment
<b>Examples</b>
</p>
The following fragment:
<p class="code"><nowiki>%FOO = #CONCAT_TRUNC(%LEN, 'Hello,', ' ', 'World!')   
<p class="code"><nowiki>%FOO = #CONCAT_TRUNC(%LEN, 'Hello,', ' ', 'World!')   
REPORT %FOO AND 'length is' AND %LEN
REPORT %FOO AND 'length is' AND %LEN
Line 288: Line 282:
if the total length of the input strings is greater than 255. </li>
if the total length of the input strings is greater than 255. </li>
</ul>
</ul>
This #function is new in <var class="product">Fast/Unload</var> version 4.0.


==#C2X: Convert character string to hex representation==
==#C2X: Convert character string to hex representation==
Line 305: Line 297:
<tr><th>%hex</th><td>String containing hex digits.</td></tr>
<tr><th>%hex</th><td>String containing hex digits.</td></tr>
</table>
</table>
 
<p>
For example, the code fragment
<b>Examples</b>
</p>
This code fragment would produce <code>X'C1C2818283'</code>:
<p class="code"><nowiki>%JUNK = #C2X('ABabc')
<p class="code"><nowiki>%JUNK = #C2X('ABabc')
REPORT 'X''' WITH %JUNK WITH ''''
REPORT 'X''' WITH %JUNK WITH ''''
</nowiki></p>
</nowiki></p>
would produce <code>X'C1C2818283'</code>, while
<p>
<p class="code"><nowiki>%JUNK = #C2X(' 1 ')
This code fragment would would produce <code>X'40F140'</code>:
<p class="code">%JUNK = #C2X(' 1 ')
REPORT 'X''' WITH %JUNK WITH ''''
REPORT 'X''' WITH %JUNK WITH ''''
</nowiki></p>
</p>
would produce <code>X'40F140'</code>.


The <var class="product">Fast/Unload</var> run is cancelled with a return
The <var class="product">Fast/Unload</var> run is cancelled with a return
code of 8 when:
code of 8 if:
<ul>
<ul>
<li>Length of <var class="term">str</var> exceeds 127. </li>
<li>Length of <var class="term">str</var> exceeds 127. </li>
</ul>
</ul>
<p><b>Notes</b></p>
<p>
<b>Notes</b></p>
<ul>
<ul>
<li>The inverse of this #function is <var>#X2C</var>. </li>
<li>The inverse of this #function is <var>#X2C</var>. </li>
Line 350: Line 345:
<td>Datetime string with indicated format.</td></tr>
<td>Datetime string with indicated format.</td></tr>
</table>
</table>
 
<p>
For example, the following fragment stores the current date
<b>Examples</b>
</p>
The following fragment stores the current date
in the last occurrence of the <code>REORG_DATE</code> field:
in the last occurrence of the <code>REORG_DATE</code> field:
<p class="code">ADD REORG_DATE = #DATE()
<p class="code">ADD REORG_DATE = #DATE()
Line 416: Line 413:
<td>Set to <var class="term">dat</var> plus <var class="term">n</var> days.</td></tr>
<td>Set to <var class="term">dat</var> plus <var class="term">n</var> days.</td></tr>
</table>
</table>
 
<p>
For example, the following fragment prints the date one week after
<b>Examples</b>
</p>
The following fragment prints the date one week after
the run date on the FUNPRINT dataset:
the run date on the FUNPRINT dataset:
<p class="code">%X = #DATE('DAY Month, YYYY')
<p class="code">%X = #DATE('DAY Month, YYYY')
Line 452: Line 451:
parameters are used instead. </li>
parameters are used instead. </li>


<li>The SOUL <var>[[$Sir_Datechg]]</var> function
<li>The SOUL <var>[[$Sir_DateChg]]</var> function
provides a <var>CENTSPAN</var> argument in the same fashion as <var>#DATECHG</var>. </li>
provides a <var>CENTSPAN</var> argument in the same fashion as <var>#DATECHG</var>. </li>
</ul>
</ul>
Line 484: Line 483:
<td>Set to 1 if <var class="term">dat</var> matches <var class="term">fmt</var>, 0 otherwise.</td></tr>
<td>Set to 1 if <var class="term">dat</var> matches <var class="term">fmt</var>, 0 otherwise.</td></tr>
</table>
</table>
 
<p>
For example, the following fragment prints the string <code>Bad</code>
<b>Examples</b>
</p>
The following fragment prints the string <code>Bad</code>
on the FUNPRINT dataset:
on the FUNPRINT dataset:
<p class="code">%X = #DATECHK('DAY Month, YYYY', '30 February, 1997')
<p class="code">%X = #DATECHK('DAY Month, YYYY', '30 February, 1997')
Line 551: Line 552:
<td>Set to the value of <var class="term">dat</var>, converted to output format.</td></tr>
<td>Set to the value of <var class="term">dat</var>, converted to output format.</td></tr>
</table>
</table>
 
<p>
For example, this prints the string <code>19970101</code>
<b>Examples</b>
on the FUNPRINT dataset:
</p>
This prints the string <code>19970101</code> on the FUNPRINT dataset:
<p class="code">%X = #DATECNV('YYMMDD', 'YYYYMMDD', '970101', 1950)
<p class="code">%X = #DATECNV('YYMMDD', 'YYYYMMDD', '970101', 1950)
REPORT %X
REPORT %X
Line 620: Line 622:
<td>Set to the number of days obtained by subtracting the second date from the first date, ignoring any time components of both dates.</td></tr>
<td>Set to the number of days obtained by subtracting the second date from the first date, ignoring any time components of both dates.</td></tr>
</table>
</table>
 
<p>
For example, the following fragment prints the string <code>7 days</code>
<b>Examples</b>
</p>
The following fragment prints the string <code>7 days</code>
on the FUNPRINT dataset:
on the FUNPRINT dataset:
<p class="code">%X = #DATEDIF('YYMMDD', '970308', , '970301')
<p class="code">%X = #DATEDIF('YYMMDD', '970308', , '970301')
Line 678: Line 682:
<tr><th>%tst</th><td>Set to 1 if <i>fmt</i> is a valid format string, else set to 0.</td></tr>
<tr><th>%tst</th><td>Set to 1 if <i>fmt</i> is a valid format string, else set to 0.</td></tr>
</table>
</table>
 
<p>
For example, the following fragment prints the string <code>Good</code>
<b>Examples</b>
</p>
The following fragment prints the string <code>Good</code>
on the FUNPRINT dataset:
on the FUNPRINT dataset:
<p class="code"><nowiki>%X = #DATEFMT('CYYDDDHHMISSXXX')
<p class="code"><nowiki>%X = #DATEFMT('CYYDDDHHMISSXXX')
Line 722: Line 728:
<td>Set to the number of <code>seconds*300</code> since <code>1 Jan 1900 12:00 AM</code> that corresponds to the datetime value of <var class="term">dat</var>.</td></tr>
<td>Set to the number of <code>seconds*300</code> since <code>1 Jan 1900 12:00 AM</code> that corresponds to the datetime value of <var class="term">dat</var>.</td></tr>
</table>
</table>
 
<p>
For example, the following fragment prints the value <code>BEFORE</code>
<b>Examples</b>
</p>
The following fragment prints the value <code>BEFORE</code>
on the FUNPRINT dataset:
on the FUNPRINT dataset:
<p class="code"><nowiki>IF #DATE2N('121494', 'MMDDYY') < -
<p class="code"><nowiki>IF #DATE2N('121494', 'MMDDYY') < -
Line 789: Line 797:
<td>Set to the number of days since <code>1 Jan 1900 12:00 AM</code> that corresponds to the datetime value of <var class="term">dat</var>.</td></tr>
<td>Set to the number of days since <code>1 Jan 1900 12:00 AM</code> that corresponds to the datetime value of <var class="term">dat</var>.</td></tr>
</table>
</table>
 
<p>
For example, the following fragment prints the value <code>BEFORE</code>
<b>Examples</b>
</p>
The following fragment prints the value <code>BEFORE</code>
on the FUNPRINT dataset:
on the FUNPRINT dataset:
<p class="code">IF #DATE2ND('121494', 'MMDDYY') < #DATE2ND('040195', 'MMDDYY') THEN
<p class="code">IF #DATE2ND('121494', 'MMDDYY') < #DATE2ND('040195', 'MMDDYY') THEN
Line 851: Line 861:
<td>Set to the number of milliseconds since <code>1 Jan 1900 12:00 AM</code> that corresponds to the datetime value of <var class="term">dat</var>.</td></tr>
<td>Set to the number of milliseconds since <code>1 Jan 1900 12:00 AM</code> that corresponds to the datetime value of <var class="term">dat</var>.</td></tr>
</table>
</table>
 
<p>
For example, the following fragment prints the value <code>BEFORE</code>
<b>Examples</b>
</p>
The following fragment prints the value <code>BEFORE</code>
on the FUNPRINT dataset:
on the FUNPRINT dataset:
<p class="code"><nowiki>IF #DATE2NM('121494', 'MMDDYY') < #DATE2NM('040195', 'MMDDYY') THEN
<p class="code"><nowiki>IF #DATE2NM('121494', 'MMDDYY') < #DATE2NM('040195', 'MMDDYY') THEN
Line 921: Line 933:
<td>Set to the number of seconds since <code>1 Jan 1900 12:00 AM</code> that corresponds to the datetime value of <var class="term">dat</var>.</td></tr>
<td>Set to the number of seconds since <code>1 Jan 1900 12:00 AM</code> that corresponds to the datetime value of <var class="term">dat</var>.</td></tr>
</table>
</table>
 
<p>
For example, the following fragment prints the value <code>BEFORE</code>
<b>Examples</b>
</p>
The following fragment prints the value <code>BEFORE</code>
on the FUNPRINT dataset:
on the FUNPRINT dataset:
<p class="code">IF #DATE2NS('121494', 'MMDDYY') < #DATE2NS('040195', 'MMDDYY') THEN
<p class="code">IF #DATE2NS('121494', 'MMDDYY') < #DATE2NS('040195', 'MMDDYY') THEN
Line 964: Line 978:
</ul>
</ul>
   
   
<div id="#deblnk"></div>
==<b id="#deblnk"></b>#DEBLANK: Remove leading and trailing blanks from substring==
==#DEBLANK: Remove leading and trailing blanks from substring==
<!--Caution: <div> above-->
The <var>#DEBLANK</var> function extracts a substring (starting at <var class="term">pos</var> for length <var class="term">len</var>) and returns it, with leading and trailing blanks removed. It requires a string to be deblanked.
The <var>#DEBLANK</var> function extracts a substring (starting at <var class="term">pos</var> for length <var class="term">len</var>) and returns it, with leading and trailing blanks removed. It requires a string to be deblanked.
It accepts an optional starting position within the string to be deblanked, and an optional length.
It accepts an optional starting position within the string to be deblanked, and an optional length.
Line 986: Line 997:
<td>Set to the substring within <var class="term">str</var>, starting at <var class="term">pos</var> for length <var class="term">len</var>; leading and trailing blanks are then removed from this substring. Intermediate blanks within the substring are not affected.</td></tr>
<td>Set to the substring within <var class="term">str</var>, starting at <var class="term">pos</var> for length <var class="term">len</var>; leading and trailing blanks are then removed from this substring. Intermediate blanks within the substring are not affected.</td></tr>
</table>
</table>
 
<p>
Examples:
<b>Examples</b>
</p>
<p class="code"><nowiki>#DEBLANK(' ABC ')        returns  'ABC'
<p class="code"><nowiki>#DEBLANK(' ABC ')        returns  'ABC'
#DEBLANK(' ABC ', 1, 2)  returns  'A'
#DEBLANK(' ABC ', 1, 2)  returns  'A'
Line 1,003: Line 1,015:
<ul>
<ul>
<li>This #function is similar to the <var>#STRIP</var> function ([[##strip|#STRIP: Remove leading and/or trailing copies of pad character]]). </li>
<li>This #function is similar to the <var>#STRIP</var> function ([[##strip|#STRIP: Remove leading and/or trailing copies of pad character]]). </li>
<li>This #function is new in <var class="product">Fast/Unload</var> version 4.0. </li>
</ul>
</ul>
This #function is new in <var class="product">Fast/Unload</var> version 4.0.


==#DELWORD: Remove blank-delimited words from string==
==#DELWORD: Remove blank-delimited words from string==
Line 1,029: Line 1,041:


<tr><th>%out</th>
<tr><th>%out</th>
<td>Set to <var class="term">str</var> with the substring removed which starts with the first character of word number <var class="term">word</var> and ends with the last blank character before word number <var class="term">word+count</var>.</td></tr>
<td>Set to <var class="term">str</var> with the substring removed which starts with the first character of word number <var class="term">word</var> and ends with the last blank character before word number <code><i>word+count</i></code>.</td></tr>
</table>
</table>
 
<p>
Examples:
<b>Examples</b>
<p class="code"><nowiki>#DELWORD('A B C', 1)      returns  ''
</p>
<ol>
<li><p class="code"><nowiki>#DELWORD('A B C', 1)      returns  ''
#DELWORD('A B C', 2)      returns  'A '
#DELWORD('A B C', 2)      returns  'A '
#DELWORD(' A B  C ', 3)  returns  ' A B  '
#DELWORD(' A B  C ', 3)  returns  ' A B  '
Line 1,041: Line 1,055:
#DELWORD('A B C', 1, 4)  returns  ''
#DELWORD('A B C', 1, 4)  returns  ''
#DELWORD('A B C', 2, 2)  returns  'A '
#DELWORD('A B C', 2, 2)  returns  'A '
</nowiki></p>
</nowiki></p><br/></li>
 
<li><p class="code">%X = 'Friends and Romans. Lend me your ears. I bury Brutus.'
%Y = #DELWORD(%X, 2, 1, '.')
PUT %Y
OUTPUT
</p>
 
The result of the above fragment is:
<p class="output">Friends and Romans. I bury Brutus.
</p></li>
</ol>


<p>
<b>Notes</b>
</p>
The <var class="product">Fast/Unload</var> run is cancelled with a return
The <var class="product">Fast/Unload</var> run is cancelled with a return
code of 8 if:
code of 8 if:
Line 1,074: Line 1,102:
<td>Set to the word position, within <var class="term">haystack</var>, of the first word of a sequence of words that matches the sequence in <var class="term">words</var>. If <var class="term">words</var> is not found, <var class="term">%pos</var> is set to 0.</td></tr>
<td>Set to the word position, within <var class="term">haystack</var>, of the first word of a sequence of words that matches the sequence in <var class="term">words</var>. If <var class="term">words</var> is not found, <var class="term">%pos</var> is set to 0.</td></tr>
</table>
</table>
 
<p>
Examples:
<b>Examples</b>
</p>
<p class="code"><nowiki>#FIND('A B C', 'B')          returns  2
<p class="code"><nowiki>#FIND('A B C', 'B')          returns  2
#FIND('A B C', 'D')          returns  0
#FIND('A B C', 'D')          returns  0
Line 1,098: Line 1,127:
</ul>
</ul>


This #function is new in <var class="product">Fast/Unload</var> version 4.0.
==<b id="flt8"></b>#FLOAT8: Get 8-byte float, padding 4-byte input with 0==
<div id="flt8"></div>
==#FLOAT8: Get 8-byte float, padding 4-byte input with 0==
<!--Caution: <div> above-->
 
The <var>#FLOAT8</var> function accepts a numeric argument, and it returns the
The <var>#FLOAT8</var> function accepts a numeric argument, and it returns the
value of the argument as an 8-byte floating point value.
value of the argument as an 8-byte floating point value.
Line 1,186: Line 1,210:
<td>Set to starting position of first occurrence of <var class="term">needle</var> within <var class="term">haystack</var>, with search starting at <var class="term">pos</var>, else 0 if not found or if either string length is zero.</td></tr>
<td>Set to starting position of first occurrence of <var class="term">needle</var> within <var class="term">haystack</var>, with search starting at <var class="term">pos</var>, else 0 if not found or if either string length is zero.</td></tr>
</table>
</table>
 
<p>
Examples:
<b>Examples</b>
</p>
<p class="code"><nowiki>#INDEX('123xy', '23')    returns  2
<p class="code"><nowiki>#INDEX('123xy', '23')    returns  2
#INDEX('123xy', '45')    returns  0
#INDEX('123xy', '45')    returns  0
Line 1,205: Line 1,230:
</ul>
</ul>
   
   
<div id="#left"></div>
==<b id="#left"></b>#LEFT: Initial substring, followed by pad characters to specified length==
==#LEFT: Initial substring, followed by pad characters to specified length==
<!--Caution: <div> above-->
The <var>#LEFT</var> function returns a padded initial substring from a source string.
The <var>#LEFT</var> function returns a padded initial substring from a source string.
It expects a source string argument and a numeric length of the output string.
It expects a source string argument and a numeric length of the output string.
Line 1,242: Line 1,264:
</ul></td></tr>
</ul></td></tr>
</table>
</table>
For example:
<p>
<b>Examples</b>
</p>
<p class="code"><nowiki>#LEFT('ABC', 1)      returns  A'
<p class="code"><nowiki>#LEFT('ABC', 1)      returns  A'
#LEFT('ABC', 3)      returns  'ABC'
#LEFT('ABC', 3)      returns  'ABC'
Line 1,262: Line 1,286:
</ul>
</ul>


This #function is new in <var class="product">Fast/Unload</var> version 4.0.
==<b id="#len"></b>#LEN: Length of string==
<div id="#len"></div>
==#LEN: Length of string==
<!--Caution: <div> above-->
The <var>#LEN</var> function returns the length of a string, in number of bytes.
The <var>#LEN</var> function returns the length of a string, in number of bytes.
It expects a required string argument and returns a numeric result.
It expects a required string argument and returns a numeric result.
Line 1,280: Line 1,299:
<td>Set to length of <var class="var">str</var>.</td></tr>
<td>Set to length of <var class="var">str</var>.</td></tr>
</table>
</table>
 
<p>
For example, the following fragment prints the string <code>Length: 13</code>
<b>Examples</b>
</p>
The following fragment prints the string <code>Length: 13</code>
on the FUNPRINT dataset:
on the FUNPRINT dataset:
<p class="code"><nowiki>%X = #LEN('Hello, world!')
<p class="code"><nowiki>%X = #LEN('Hello, world!')
Line 1,288: Line 1,309:


This #function has no cancelling conditions.
This #function has no cancelling conditions.
==#LOWCASE: Change uppercase letters of string to lowercase==
==#LOWCASE: Change uppercase letters of string to lowercase==
The <var>#LOWCASE</var> function returns a copy of the input string, with all uppercase
The <var>#LOWCASE</var> function returns a copy of the input string, with all uppercase
Line 1,302: Line 1,324:
<td>Copy of <var class="term">str</var>, with all uppercase EBCDIC letters changed to their lowercase EBCDIC equivalents.</td></tr>
<td>Copy of <var class="term">str</var>, with all uppercase EBCDIC letters changed to their lowercase EBCDIC equivalents.</td></tr>
</table>
</table>
For example:
<p>
<b>Examples</b>
</p>
<p class="code"><nowiki>#LOWCASE('?abc')    returns  '?abc'
<p class="code"><nowiki>#LOWCASE('?abc')    returns  '?abc'
#LOWCASE('?ABC')    returns  '?abc'
#LOWCASE('?ABC')    returns  '?abc'
#LOWCASE('')        returns  ''
#LOWCASE('')        returns  ''
</nowiki></p>
</nowiki></p>
 
<p>
<b>Notes</b>
</p>
This #function has no cancelling conditions.
This #function has no cancelling conditions.
This #function is new in <var class="product">Fast/Unload</var> version 4.0.


==#ND2DATE: Convert number of days to datetime string==
==#ND2DATE: Convert number of days to datetime string==
Line 1,324: Line 1,348:
<table>
<table>
<tr><th>datn</th>
<tr><th>datn</th>
<td>Numeric datetime value expressed as the number of days since <code>1 Jan 1900 12:00 AM</code>. This argument may not have the <var>MISSING</var> value.</td></tr>
<td>Numeric datetime value expressed as the number of days since <code>1 Jan 1900 12:00 AM</code>. This argument may not have the <var>[[Fast/Unload Extraction Language (FUEL)#%Variables|MISSING]]</var> value.</td></tr>


<tr><th>fmt</th>
<tr><th>fmt</th>
Line 1,335: Line 1,359:
<td>Set to datetime string value, in format specified by <var class="term">fmt</var>, corresponding to <var class="term">datn</var>.</td></tr>
<td>Set to datetime string value, in format specified by <var class="term">fmt</var>, corresponding to <var class="term">datn</var>.</td></tr>
</table>
</table>
 
<p>
For example, the following fragment prints the string <code>07/31/84</code>
<b>Examples</b>
</p>
The following fragment prints the string <code>07/31/84</code>
on the FUNPRINT dataset:
on the FUNPRINT dataset:
<p class="code"><nowiki>%X = #DATE2ND('8407301230', 'YYMMDDHHMI')
<p class="code"><nowiki>%X = #DATE2ND('8407301230', 'YYMMDDHHMI')
Line 1,391: Line 1,417:
<td>Set to datetime string value, in format specified by <var class="term">fmt</var>, corresponding to <var class="term">datn</var>.</td></tr>
<td>Set to datetime string value, in format specified by <var class="term">fmt</var>, corresponding to <var class="term">datn</var>.</td></tr>
</table>
</table>
 
<p>
For example, the following fragment prints the string <code>07/31/84</code>
<b>Examples</b>
</p>
The following fragment prints the string <code>07/31/84</code>
on the FUNPRINT dataset:
on the FUNPRINT dataset:
<p class="code"><nowiki>%X = #DATE2NM('8407301230', 'YYMMDDHHMI')
<p class="code"><nowiki>%X = #DATE2NM('8407301230', 'YYMMDDHHMI')
Line 1,435: Line 1,463:
<table>
<table>
<tr><th>datn</th>
<tr><th>datn</th>
<td>Numeric datetime value expressed as the number of seconds since <code>1 Jan 1900 12:00 AM</code>. This argument may not have the <var>MISSING</var> value.</td></tr>
<td>Numeric datetime value expressed as the number of seconds since <code>1 Jan 1900 12:00 AM</code>. This argument may not have the <var>[[Fast/Unload Extraction Language (FUEL)#%Variables|MISSING]]</var> value.</td></tr>


<tr><th>fmt</th>
<tr><th>fmt</th>
Line 1,446: Line 1,474:
<td>Set to datetime string value, in format specified by <var class="term">fmt</var>, corresponding to <var class="term">datn</var>.</td></tr>
<td>Set to datetime string value, in format specified by <var class="term">fmt</var>, corresponding to <var class="term">datn</var>.</td></tr>
</table>
</table>
 
<p>
For example, the following fragment prints the string <code>07/31/84</code>
<b>Examples</b>
</p>
The following fragment prints the string <code>07/31/84</code>
on the FUNPRINT dataset:
on the FUNPRINT dataset:
<p class="code"><nowiki>%X = #DATE2NS('8407301230', 'YYMMDDHHMI')
<p class="code"><nowiki>%X = #DATE2NS('8407301230', 'YYMMDDHHMI')
Line 1,479: Line 1,509:
</ul>
</ul>
   
   
<div id="num2str"></div>
==<b id="num2str"></b>#NUM2STR: Convert number to string with decimal point==
==#NUM2STR: Convert number to string with decimal point==
<!--Caution: <div> above-->
The <var>#NUM2STR</var> function converts a number to a string with an integer part,
The <var>#NUM2STR</var> function converts a number to a string with an integer part,
followed by an optional decimal point and decimal fraction digits, with
followed by an optional decimal point and decimal fraction digits, with
Line 1,569: Line 1,596:
As these rules indicate, <var class="term">%intlen</var>, if supplied, allows the <var class="product">Fast/Unload</var> program to continue when the first argument is non-numeric or the integer part is truncated in the result. If either of these conditions occur and <var class="term">%intlen</var> is omitted, the <var class="product">Fast/Unload</var> program is cancelled.</p> </td></tr>
As these rules indicate, <var class="term">%intlen</var>, if supplied, allows the <var class="product">Fast/Unload</var> program to continue when the first argument is non-numeric or the integer part is truncated in the result. If either of these conditions occur and <var class="term">%intlen</var> is omitted, the <var class="product">Fast/Unload</var> program is cancelled.</p> </td></tr>
</table>
</table>
 
<p>
Examples:
<b>Examples</b>
</p>
<p class="code"><nowiki>%N_HUMAN = 6 * 1000 * 1000 * 1000
<p class="code"><nowiki>%N_HUMAN = 6 * 1000 * 1000 * 1000
#NUM2STR(%N_HUMAN) -> "6000000000"
#NUM2STR(%N_HUMAN) -> "6000000000"
Line 1,644: Line 1,672:
without rounding, but <var>#NUM2STR</var> offers rounding of dropped low-order digits.</p>
without rounding, but <var>#NUM2STR</var> offers rounding of dropped low-order digits.</p>
</blockquote>
</blockquote>
This #function is new in <var class="product">Fast/Unload</var> version 4.0.


==#N2DATE: Convert number of seconds*300 to datetime string==
==#N2DATE: Convert number of seconds*300 to datetime string==
Line 1,659: Line 1,685:
<table>
<table>
<tr><th>datn</th>
<tr><th>datn</th>
<td>Numeric datetime value expressed as 300 times the number of seconds since <code>1 Jan 1900 12:00 AM</code>. This argument may not have the <var>MISSING</var> value.</td></tr>
<td>Numeric datetime value expressed as 300 times the number of seconds since <code>1 Jan 1900 12:00 AM</code>. This argument may not have the <var>[[Fast/Unload Extraction Language (FUEL)#%Variables|MISSING]]</var> value.</td></tr>


<tr><th>fmt</th>
<tr><th>fmt</th>
Line 1,670: Line 1,696:
<td>Set to datetime string value, in format specified by <var class="term">fmt</var>, corresponding to <var class="term">datn</var>.</td></tr>
<td>Set to datetime string value, in format specified by <var class="term">fmt</var>, corresponding to <var class="term">datn</var>.</td></tr>
</table>
</table>
 
<p>
For example, the following fragment prints the string <code>07/31/84</code>
<b>Examples</b>
</p>
The following fragment prints the string <code>07/31/84</code>
on the FUNPRINT dataset:
on the FUNPRINT dataset:
<p class="code">%X = #DATE2N('8407301230', 'YYMMDDHHMI')
<p class="code">%X = #DATE2N('8407301230', 'YYMMDDHHMI')
Line 1,702: Line 1,730:
</ul>
</ul>
   
   
<div id="#oneof"></div>
==<b id="#oneof"></b>#ONEOF: See if string is in delimited list of strings==
==#ONEOF: See if string is in delimited list of strings==
<!--Caution: <div> above-->
The <var>#ONEOF</var> function determines whether a string is found
The <var>#ONEOF</var> function determines whether a string is found
in a delimited list of strings.
in a delimited list of strings.
Line 1,730: Line 1,755:


<p>
<p>
Examples:
<b>Examples</b>
</p>
</p>
<p class="code"><nowiki>#ONEOF('HOW', 'HOW NOW', ' ')  returns  1
<p class="code"><nowiki>#ONEOF('HOW', 'HOW NOW', ' ')  returns  1
Line 1,767: Line 1,792:
entity has one of several values (see [[Fast/Unload Extraction Language (FUEL)#sel|SELECT entity]]). </li>
entity has one of several values (see [[Fast/Unload Extraction Language (FUEL)#sel|SELECT entity]]). </li>
</ul>
</ul>
<p>
This #function is new in <var class="product">Fast/Unload</var> version 4.0.
==<b id="#pad"></b>#PAD: Final substring, preceded by pad characters to specified length==
</p>
<div id="#pad"></div>
==#PAD: Final substring, preceded by pad characters to specified length==
<!--Caution: <div> above-->
The <var>#PAD</var> function returns a padded final substring from a source string.
The <var>#PAD</var> function returns a padded final substring from a source string.
It expects a source string argument and a numeric length of the output string.
It expects a source string argument and a numeric length of the output string. It accepts an optional pad character.
It accepts an optional pad character.
<var>#PAD</var> returns the string that ends at the last position
<var>#PAD</var> returns the string that ends at the last position
of the source string and is of the specified output length.
of the source string and is of the specified output length.
If the output length is less than or equal to the length of the source string,
If the output length is less than or equal to the length of the source string,
the last <var class="term">length</var> characters of the source are returned.
the last <var class="term">length</var> characters of the source are returned.
Otherwise, the source string is padded to the output length by preceding it
Otherwise, the source string is padded to the output length by preceding it with sufficient copies of the pad character.
with sufficient copies of the pad character.
<p class="syntax"><span class="term">%out</span> = #PAD(<span class="term">str, pad, len</span>)
<p class="syntax"><span class="term">%out</span> = #PAD(<span class="term">str, pad, len</span>)
</p>
</p>
Line 1,808: Line 1,825:
</ul></td></tr>
</ul></td></tr>
</table>
</table>
For example:
<p>
<b>Examples</b>
</p>
<p class="code"><nowiki>#PAD('ABC', , 0)        returns  ''
<p class="code"><nowiki>#PAD('ABC', , 0)        returns  ''
#PAD('ABC', , 1)        returns  'C'
#PAD('ABC', , 1)        returns  'C'
Line 1,830: Line 1,849:
the arguments ([[##right|#RIGHT: Final substring, preceded by pad characters to specified length]]). </li>
the arguments ([[##right|#RIGHT: Final substring, preceded by pad characters to specified length]]). </li>
</ul>
</ul>
<p>
This #function is new in <var class="product">Fast/Unload</var> version 4.0.
</p>
<div id="#padr"></div>
==#PADR: Initial substring, followed by pad characters to specified length==
<!--Caution: <div> above-->
   
   
==<b id="#padr"></b>#PADR: Initial substring, followed by pad characters to specified length==
The <var>#PADR</var> function returns a padded initial substring from a source string.
The <var>#PADR</var> function returns a padded initial substring from a source string.
It expects a source string argument and a numeric length of the output string.
It expects a source string argument and a numeric length of the output string.
Line 1,872: Line 1,885:
</ul></td></tr>
</ul></td></tr>
</table>
</table>
For example:
<p>
<b>Examples</b>
</p>
<p class="code"><nowiki>#PADR('ABC', , 1)    returns  'A'
<p class="code"><nowiki>#PADR('ABC', , 1)    returns  'A'
#PADR('ABC', , 3)    returns  'ABC'
#PADR('ABC', , 3)    returns  'ABC'
Line 1,892: Line 1,907:
the arguments ([[##left|#LEFT: Initial substring, followed by pad characters to specified length]]). </li>
the arguments ([[##left|#LEFT: Initial substring, followed by pad characters to specified length]]). </li>
</ul>
</ul>
==#QUOTE: Wrap string in quote character, and double embedded quotes==
This function returns the input string with a quote character added before
and after the input, and with any quote characters within the input replaced
by two copies of the quote character.
<p class="syntax"><span class="term">%quoted</span> = #QUOTE(<span class="term">string</span>, <span class="term">char</span>)
</p>
<p>Where:</p>
<table>
<tr><th>%quoted</th>
<td>The input string wrapped in quotes with embedded quotes doubled. It may be a long string (that is, it may exceed 255 bytes in length).</td></tr>
<tr><th>string</th>
<td>The input string to be quoted. It may be a long string (that is, it may exceed 255 bytes in length).</td></tr>
<tr><th>char</th>
<td>The quote character. It must be a string of length one.</td></tr>
</table>
<p>
<b>Example</b></p>
<p class="code">%S = 'Don&apos;'t stop'
%L = #LEN(%S)
PUT %L
PUT ' '
PUT %S
OUTPUT
%Q = #QUOTE(%S, &apos;&apos;&apos;')
%L = #LEN(%Q)
PUT %L
PUT ' '
PUT %Q
OUTPUT
</p>
The output from the above FUEL fragment is:
<p class="output">10 Don't stop
13 'Don&apos;'t stop'
</p>
<p>
<p>
This #function is new in <var class="product">Fast/Unload</var> version 4.0.
This #function is new in <var class="product">Fast/Unload</var> version 4.6.
</p>
</p>


Line 1,910: Line 1,963:
<td>Copy of <var class="term">str</var>, with all the last input byte first, followed by the next to last input byte, etc.</td></tr>
<td>Copy of <var class="term">str</var>, with all the last input byte first, followed by the next to last input byte, etc.</td></tr>
</table>
</table>
For example:
<p>
<b>Examples</b>
</p>
<p class="code"><nowiki>#REVERSE('abc')    returns  'cba'
<p class="code"><nowiki>#REVERSE('abc')    returns  'cba'
</nowiki></p>
</nowiki></p>
Line 1,916: Line 1,971:
This #function has no cancelling conditions.
This #function has no cancelling conditions.
</p>
</p>
<p>
 
This #function is new in <var class="product">Fast/Unload</var> version 4.0.
==<b id="#right"></b>#RIGHT: Final substring, preceded by pad characters to specified length==
</p>
<div id="#right"></div>
==#RIGHT: Final substring, preceded by pad characters to specified length==
<!--Caution: <div> above-->
The <var>#RIGHT</var> function returns a padded final substring from a source
The <var>#RIGHT</var> function returns a padded final substring from a source
string. It expects a source string argument and a numeric length of the output string.
string. It expects a source string argument and a numeric length of the output string.
Line 1,931: Line 1,980:
If the output length is less than or equal to the length of the source string,
If the output length is less than or equal to the length of the source string,
the last <var class="term">length</var> characters of the source are returned.
the last <var class="term">length</var> characters of the source are returned.
Otherwise, the source string is padded to the output length by preceding it
Otherwise, the source string is padded to the output length by preceding it with sufficient copies of the pad character. </p>
with sufficient copies of the pad character. </p>
<p class="syntax"><span class="term">%out</span> = #RIGHT(<span class="term">str, len, pad</span>)
<p class="syntax"><span class="term">%out</span> = #RIGHT(<span class="term">str, len, pad</span>)
</p>
</p>
Line 1,957: Line 2,005:
</ul></td></tr>
</ul></td></tr>
</table>
</table>
For example:
<p>
<b>Examples</b>
</p>
<p class="code"><nowiki>#RIGHT('ABC', 0)        returns  ''
<p class="code"><nowiki>#RIGHT('ABC', 0)        returns  ''
#RIGHT('ABC', 1)        returns  'C'
#RIGHT('ABC', 1)        returns  'C'
Line 1,965: Line 2,015:
</nowiki></p>
</nowiki></p>
<p>
<p>
The <var class="product">Fast/Unload</var> run is cancelled with a return
<b>Notes</b></p>
code of 8 when:</p>
<ul>
<li>The <var class="product">Fast/Unload</var> run is cancelled with a return
code of 8 if:
<ul>
<ul>
<li><var class="term">len</var> not numeric, or less than 0. </li>
<li><var class="term">len</var> not numeric, or less than 0. </li>
<li><var class="term">pad</var> supplied, and length not 1. </li>
<li><var class="term">pad</var> supplied, and length not 1. </li>
</ul></li>
<li><var>#RIGHT</var> is the same as the <var>#PAD</var> function, except for the order of
the arguments (see [[##pad|#PAD: Final substring, preceded by pad characters to specified length]]). </li>
</ul>
</ul>


==#SHADIGEST: SHA-1 digest ("hash") of string==
This function returns the 20-byte (always) binary string that is the
SHA-1 digest of the argument.
<p class="syntax"><span class="term">%hashval</span> = #SHADIGEST(<span class="term">string</span>)
</p>
<p>
Where:</p>
<table>
<tr><th>%hashval</th>
<td>A %variable to receive the SHA-1 digest of the argument string.</td></tr>
<tr><th>string</th>
<td>The input string to be hashed. This may be a long string (that is, it may exceed 255 bytes in length).</td></tr>
</table>
<p>
<b>Example</b></p>
The 20-byte SHA-1 hash of a string is typically expressed as a 40-digit hex value.
In the following example,
the output string from <var>#SHADIGEST</var> is converted to hex using the
<var>#C2X</var> function:
<p class="code">%HSH = #SHADIGEST('this is a simple test')
%XHSH = #C2X(%HSH)
PUT %XHSH
OUTPUT
</p>
The result is:
<p class="output">BC38AA2D6769639946806616C14AF0C69477AABE
</p>
<p>
<p>
<b>Notes</b></p>
<b>Notes</b></p>
<ul>
<ul>
<li>This is the same as the <var>#PAD</var> function, except for the order of
<li>SHA (Secure Hash Algorithm) is a set of cryptographic hashing functions, and
the arguments (see [[##pad|#PAD: Final substring, preceded by pad characters to specified length]]). </li>
<var>#SHADIGEST</var> provides <code>SHA-1</code>, the most commonly used. A complete explanation of SHA hashing can easily be found on the internet. </li>
 
<li>This FUEL #function operates the same as the SOUL <var>[[SHAdigest (String function)|SHAdigest]]</var> method. </li>
 
<li>This #function is new in <var class="product">Fast/Unload</var> version 4.6.</li>
</ul>
</ul>
<p>
This #function is new in <var class="product">Fast/Unload</var> version 4.0.
</p>


==#SNDX: Create SOUNDEX code for string==
==#SNDX: Create SOUNDEX code for string==
Line 1,997: Line 2,083:
</table>
</table>
<p>
<p>
For example, the following fragment will build values for
<b>Examples</b>
</p>
Tthe following fragment will build values for
an <var>INVISIBLE KEY</var> field which is the <var>$Sndx</var> value of the field <code>NAME</code>:
an <var>INVISIBLE KEY</var> field which is the <var>$Sndx</var> value of the field <code>NAME</code>:
</p>
</p>
Line 2,012: Line 2,100:
</p>
</p>
   
   
<div id="#strip"></div>
==<b id="#strip"></b>#STRIP: Remove leading and/or trailing copies of pad character==
==#STRIP: Remove leading and/or trailing copies of pad character==
<!--Caution: <div> above-->
The <var>#STRIP</var> function removes leading, trailing, or both, copies of a pad
The <var>#STRIP</var> function removes leading, trailing, or both, copies of a pad
character from a string. It requires a string to be stripped.
character from a string. It accepts an optional specification of which characters to strip (Leading, Trailing, or Both).
It accepts an optional specification of which characters to strip (Leading, Trailing, or Both).
It also lets you designate a <var>#STRIP</var> first-argument value to be nullified.
It accepts an optional pad character argument, specifying the character to be stripped.
<p class="syntax"><span class="term">%out</span> = #STRIP(<span class="term">str</span>, [B|L|N|P|T], [<span class="term">pad</span>], [<span class="term">nullval</span>])
<p class="syntax"><span class="term">%out</span> = #STRIP(<span class="term">str</span>, B|L|T, <span class="term">pad</span>)
</p>
</p>
Where:
Where:
<table>
<table>
<tr><th>%out</th>
<td>Set to a copy of <var class="term">str</var>, with leading, trailing, or both copies of <var class="term">pad</var> removed.</td></tr>
<tr><th>str</th>
<tr><th>str</th>
<td>String to be stripped; required.</td></tr>
<td>String to be stripped; required.</td></tr>


<tr><th>B|L|T</th>
<tr><th><var>B</var>|<var>L</var>|<var>N</var>|<var>P</var>|<var>T</var></th>
<td>Optional indicator of the type of strip: <ul>
<td>Optional indicator of the type of strip; defaults to <var>B</var>:  
<li>'B...' (any string beginning with uppercase <code>B</code>): to strip <b>B</b>oth leading and trailing pad characters. </li>
<table class="thJustBold">
<li>'L...' (any string beginning with uppercase <code>L</code>): to strip <b>L</b>eading pad characters only. </li>
<tr class="head"><th>Any string beginning with...</th><th>Action</th></tr>  
<li>'T...' (any string beginning with uppercase <code>T</code>): to strip <b>T</b>railing pad characters only. </li>
 
</ul>  
<tr><th>'B...' (uppercase <code>B</code>)</th>
<td>Strips <b>B</b>oth leading and trailing pad characters. </td></tr>
 
<tr><th>'L...' (uppercase <code>L</code>)</th>
<td>Strips <b>L</b>eading pad characters only. </td></tr>
 
<tr><th>'N...' (uppercase <code>N</code>)</th>
<td>Strips <b>N</b>either leading characters nor trailing characters.  This can be useful if you <b>only</b> want to use <var>#STRIP</var> to replace <var class="term">nullval</var> with the null string.</td></tr>
 
<tr><th>'P...' (uppercase <code>P</code>)</th>
<td>Strips all but one leading <b>P</b>ad character from consecutive leading <var class="term">pad</var> characters. </td></tr>
 
<tr><th>'T...' (uppercase <code>T</code>)</th>
<td>Strips <b>T</b>railing pad characters only. </td></tr>
</table>  
<p>
<p>
Defaults to <var>B</var>.
The <var>N</var> and <var>P</var> options are available as of version 7.7 of <var class="product">Fast/Unload</var>. </p></td></tr>
</p> </td></tr>
 
<tr><th>pad</th>
<td>The character to be stripped; optional. Blank is the default.</td></tr>


<tr><th>%out</th>
<tr><th>nullval</th>
<td>Set to a copy of <var class="term">str</var>, with leading, trailing, or both, as specified, copies of <var class="term">pad</var> removed.</td></tr>
<td>The <var class="term">str</var> value to be output as a null; optional. If the value of <var class="term">str</var> is equal to the value of <var class="term">nullval</var>, <var>#STRIP</var> returns a null string for <var class="term">str</var>.
<p>
Available as of version 7.7 of <var class="product">Fast/Unload</var>, you might use <var class="term">nullval</var> for fields that have a "placeholder value" or "default value" that is not actual data.</p></td></tr>
</table>
</table>
<p>Examples:
<p><b>Examples</b>
</p>
</p>
<p class="code"><nowiki>#STRIP('  ABC  ')         returns  'ABC'
<p class="code"><nowiki>#STRIP('  ABC  ')               returns  'ABC'
#STRIP('  ABC  ', 'L')     returns  'ABC  '
#STRIP('  ABC  ', 'L')         returns  'ABC  '
#STRIP('  ABC  ', 'T')     returns  '  ABC'
#STRIP('  ABC  ', 'T')         returns  '  ABC'
#STRIP('000123', 'L', '0') returns  '123'
 
#STRIP('000123', 'L', '0')     returns  '123'
#STRIP('000123', 'P', '0')      returns  '123'
 
#STRIP('000000', 'L', '0')      returns  ''
#STRIP('000000', 'P', '0')      returns  '0'
 
#STRIP('_123',  'P',    , '_') returns  '_123'
#STRIP('_',      'P',    , '_') returns  ''
#STRIP('__',    'P',    , '_') returns  '__'
 
#STRIP(' _',    'P',    , '_') returns  '_'
#STRIP(' _',    'N',    , '_') returns  ' _'
#STRIP('_',      'P',    , '_') returns  ''
#STRIP('_',      'N',    , '_') returns  ''
</nowiki></p>
</nowiki></p>
<p>
<p>
Line 2,051: Line 2,170:
code of 8 when:</p>
code of 8 when:</p>
<ul>
<ul>
<li><var>B|L|T</var> does not begin with either uppercase <code>B</code>, uppercase <code>L</code>, or uppercase <code>T</code>. </li>
<li><var>B|L|N|P|T</var> does not begin with uppercase <code>B</code>, <code>L</code>, <code>N</code>, <code>P</code>, or uppercase <code>T</code>. </li>


<li><var class="term">pad</var> specified and length is not 1. </li>
<li><var class="term">pad</var> specified and length is not 1. </li>
Line 2,060: Line 2,179:
<li>This #function is similar to the <var>#DEBLANK</var> function ([[##deblnk|#DEBLANK: Remove leading and trailing blanks from substring]]). </li>
<li>This #function is similar to the <var>#DEBLANK</var> function ([[##deblnk|#DEBLANK: Remove leading and trailing blanks from substring]]). </li>
</ul>
</ul>
<p>
 
This #function is new in <var class="product">Fast/Unload</var> version 4.0.
==<b id="#substr"></b>#SUBSTR: Substring==
</p>
<div id="#substr"></div>
==#SUBSTR: Substring==
<!--Caution: <div> above-->
The <var>#SUBSTR</var> function returns a substring from within a source string.
The <var>#SUBSTR</var> function returns a substring from within a source string.
It expects a source string argument and a numeric byte position within the source string.
It expects a source string argument and a numeric byte position within the source string.
Line 2,090: Line 2,203:
<td>Substring from <var class="term">str</var> starting at position <var class="term">pos</var> with length that is the minimum of <var class="term">len</var> and <code>#LEN(<i>str</i>)+1-<i>pos</i></code>.</td></tr>
<td>Substring from <var class="term">str</var> starting at position <var class="term">pos</var> with length that is the minimum of <var class="term">len</var> and <code>#LEN(<i>str</i>)+1-<i>pos</i></code>.</td></tr>
</table>
</table>
For example, you might want to get the "right-hand half" of a string
<p>
<b>Examples</b>
</p>
You might want to get the "right-hand half" of a string
(it will be to the right of the middle character if the string
(it will be to the right of the middle character if the string
length is odd):
length is odd):
Line 2,139: Line 2,255:
<td>Set to datetime string with current date and time, using <var class="term">fmt</var>.</td></tr>
<td>Set to datetime string with current date and time, using <var class="term">fmt</var>.</td></tr>
</table>
</table>
For example, the following fragment stores the current time
<p>
<b>Examples</b>
</p>
The following fragment stores the current time
in the last occurrence of the <code>REORG_TIME</code> field:
in the last occurrence of the <code>REORG_TIME</code> field:
<p class="code">ADD REORG_TIME = #TIME()
<p class="code">ADD REORG_TIME = #TIME()
Line 2,191: Line 2,310:
<td>Copy of <var class="term">str</var>, with all characters which are contained in the input table translated to the corresponding characters in the output table.</td></tr>
<td>Copy of <var class="term">str</var>, with all characters which are contained in the input table translated to the corresponding characters in the output table.</td></tr>
</table>
</table>
For example:
<p>
<b>Examples</b>
</p>
<p class="code"><nowiki>#TRANSLATE('ab', 'x', 'b')    returns  .ax.
<p class="code"><nowiki>#TRANSLATE('ab', 'x', 'b')    returns  .ax.
#TRANSLATE('ab', , '', 'z')  returns  .ab.
#TRANSLATE('ab', , '', 'z')  returns  .ab.
Line 2,223: Line 2,344:
</nowiki></p> </li>
</nowiki></p> </li>
</ul>
</ul>
<p>
This #function is new in <var class="product">Fast/Unload</var> version 4.0.
</p>


==#UPCASE: Change lowercase letters of string to uppercase==
==#UPCASE: Change lowercase letters of string to uppercase==
Line 2,241: Line 2,359:
<td>Copy of <var class="term">str</var>, with all lowercase EBCDIC letters changed to their uppercase EBCDIC equivalents.</td></tr>
<td>Copy of <var class="term">str</var>, with all lowercase EBCDIC letters changed to their uppercase EBCDIC equivalents.</td></tr>
</table>
</table>
For example:
<p>
<b>Examples</b>
</p>
<p class="code"><nowiki>#UPCASE('?abc')    returns  '?ABC'
<p class="code"><nowiki>#UPCASE('?abc')    returns  '?ABC'
#UPCASE('?ABC')    returns  '?ABC'
#UPCASE('?ABC')    returns  '?ABC'
#UPCASE('')        returns  ''
#UPCASE('')        returns  ''
</nowiki></p>
</nowiki></p>
<p>
<b>Notes</b>
</p>
<p>This #function has no cancelling conditions.
<p>This #function has no cancelling conditions.
</p>
<p>This #function is new in <var class="product">Fast/Unload</var> version 4.0.
</p>
</p>


Line 2,302: Line 2,423:
</table>
</table>
<p>
<p>
Examples:
<b>Examples</b>
</p>
</p>
<p class="code"><nowiki>#VERPOS('SIRIUS', 'ETANOISHRDLU')  returns    0
<p class="code"><nowiki>#VERPOS('SIRIUS', 'ETANOISHRDLU')  returns    0
Line 2,351: Line 2,472:
<var class="term">search</var> are in <var class="term">target</var>" if <var class="term">search</var> is null, whether or not <var class="term">target</var> is null. </li>
<var class="term">search</var> are in <var class="term">target</var>" if <var class="term">search</var> is null, whether or not <var class="term">target</var> is null. </li>
</ul>
</ul>
</ul>
==#VIEW204: Value of Model 204 parameter==
The <var>#VIEW204</var> function returns the value of the designated [[List of Model 204 parameters|Model 204 parameter]].
<p class="syntax"><span class="term">%out</span> = #VIEW204(<span class="term">param</span>)
</p>
Where:
<table>
<tr><th>param</th>
<td>String containing the name of the parameter; required.</td></tr>
</table>
<p>
The <var class="product">Fast/Unload</var> run is cancelled with a return code of 8 if the argument is not the name of a <var class="product">Model&nbsp;204</var> parameter.
</p>
<p>
<b>Notes</b></p>
<ul>
<li>This #function is new in <var class="product">Fast/Unload</var> version 7.7.</li>
</ul>
</ul>


Line 2,376: Line 2,518:
</table>
</table>
<p>
<p>
Examples:
<b>Examples</b>
</p>
</p>
<p class="code"><nowiki>#WORD('A B C', 1)       returns  'A'
<p class="code"><nowiki>#WORD('A B C', 1)                     returns  'A'
#WORD('A B C', 2)       returns  'B'
#WORD('A B C', 2)                     returns  'B'
#WORD('A B C', 3)       returns  'C'
#WORD('A B C', 3)                     returns  'C'
#WORD('A B C', 4)       returns  ''
#WORD('A B C', 4)                     returns  ''
#WORD('    ', 1)       returns  ''
#WORD('    ', 1)                     returns  ''
#WORD('The answer: Rosebud', 2, ':')  returns  'Rosebud'
</nowiki></p>
</nowiki></p>
<p>
<p>
Line 2,396: Line 2,539:
delimiter character argument, and its "<i>word</i>" argument is the third argument. </li>
delimiter character argument, and its "<i>word</i>" argument is the third argument. </li>
</ul>
</ul>
<p>
This #function is new in <var class="product">Fast/Unload</var> version 4.0.
</p>


==#WORDS: Count number of blank-delimited word in string==
==#WORDS: Count number of blank-delimited word in string==
Line 2,420: Line 2,560:
</table>
</table>
<p>
<p>
Examples:
<b>Examples</b>
</p>
</p>
<p class="code"><nowiki>#WORDS('A B C')                      returns  3
<p class="code"><nowiki>#WORDS('A B C')                      returns  3
Line 2,436: Line 2,576:
delimiter character argument. </li>
delimiter character argument. </li>
</ul>
</ul>
<p>
This #function is new in <var class="product">Fast/Unload</var> version 4.0.
</p>


==#X2C: Convert hex representation to character string==
==#X2C: Convert hex representation to character string==
Line 2,451: Line 2,588:
<table>
<table>
<tr><th>hex</th>
<tr><th>hex</th>
<td>String to convert; contains only the characters <code>0-9</code> and <code>A-F</code>.</td></tr>
<td>String to convert; must contain only the characters <code>0-9</code> and <code>A-F</code>. <p>
The <var class="product">Fast/Unload</var> run is cancelled with a return
code of 8 if <var class="term">hex</var> contains a non-hexadecimal digit character.
</p></td></tr>


<tr><th>%str</th>
<tr><th>%str</th>
<td>Set to the string of bytes represented by <var class="term">hex</var>.</td></tr>
<td>Set to the string of bytes represented by <var class="term">hex</var>.</td></tr>
</table>
</table>
For example, in
<p>
<b>Examples</b></p>
This statement sets <code>%JUNK</code> to the string <code>123</code> (EBCDIC X'F1F2F3'):
<p class="code">%JUNK = #X2C('F1F2F3')
<p class="code">%JUNK = #X2C('F1F2F3')
</p>
</p>
<code>%JUNK</code> would be set to the string <code>123</code> (EBCDIC X'F1F2F3'), and in
 
This statement sets <code>%JUNK</code> to EBCDIC X'0102', which is a non-displayable string:
<p class="code"><nowiki>%JUNK = #X2C('102')
<p class="code"><nowiki>%JUNK = #X2C('102')
</nowiki></p>
</nowiki></p>
<code>%JUNK</code> would be set to EBCDIC X'0102' which is a non-displayable string.
 
<p>
The <var class="product">Fast/Unload</var> run is cancelled with a return
code of 8 when:
</p>
<ul>
<li>Non-hexadecimal digit character in <var class="term">hex</var>. </li>
</ul>
<p>
<p>
<b>Notes</b></p>
<b>Notes</b></p>
Line 2,475: Line 2,611:
<li>The inverse of this #function is <var>[[#C2X: Convert character string to hex representation|#C2X]]</var>. </li>
<li>The inverse of this #function is <var>[[#C2X: Convert character string to hex representation|#C2X]]</var>. </li>


<li>If the number of characters of <var class="term">hex</var> is odd, a leading
<li>If the number of characters of <var class="term">hex</var> is odd, a leading character 0 is added for the conversion.
character 0 is added for the conversion.
The SOUL <var>[[$X2C]]</var> function requires an even number of characters in <var class="term">hex</var>. </li>
The SOUL <var>[[$X2C]]</var> function requires an even number of characters in <var class="term">hex</var>. </li>


Line 2,485: Line 2,620:


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

Latest revision as of 19:28, 26 January 2017

This wiki page lists the #functions provided with Fast/Unload. #Functions can be used as the expression in an assignment statement, as described in Assignment statement. Each #function is presented here with a brief phrase denoting its use, a short explanation, the form and types of its arguments and result (or "output value"), one or more examples, any error conditions, and special notes.

In some instances the behavior of a #function is compared to the behavior of a corresponding SOUL $function.

FUEL also contains program entities called "special variables" that might be initially mistaken for #functions. Similar to #functions in appearance and syntax, special variables are described in Special variables.

#Function argument types and evaluation

The arguments to a #function are FUEL entities, and their number and type varies with the #function. The maximum number of arguments in a $function call is 31 (the comma maximum is 30).

The types of the arguments, and some other items important in specifying how to use a #function, are as follows:

required argument If an argument to a #function is required, you must code an entity for it in the call. If you do not code an entity, a compilation error message will be issued and the unload is not performed.
optional argument If an argument to a #function is optional, you need not code an entity for it in the call. If you provide any arguments following it, then a comma must be used to indicate the missing argument; for example:

%P = #VERPOS(%S, %C, , 3)

The third argument, which is optional, has not been coded above.
omitted argument A particular #function may treat an omitted argument differently than a supplied argument that has the "MISSING" value or which has the null string value.
input argument If an argument to a #function is an input argument, you can specify any form of entity for the argument. The #function cannot change the value of an input argument.
argument with "MISSING" value If an argument has the MISSING value (a %variable or a field), the #function algorithm can detect this, although, except as noted, for all arguments of the standard #functions, this is the same as: passing the null string for a string argument, or passing zero for a numeric argument.

Since the numeric value of MISSING is zero, the MISSING value is not allowed for an argument that may not be zero. Also, the MISSING value is not allowed for some other #function arguments, such as the CENTSPAN argument and the first argument in the #Nx2DATE family (for example, #ND2DATE).

#function result The value of an expression that is a #function call is called the #function result. See the evaluation process below for an explanation of how this is set.
output argument In addition to the result, a #function can set additional values. This is provided by output arguments. If you supply an output argument, you must supply a %variable (leading minus sign is not allowed); if you supply an argument which is not a %variable, a compilation error message is issued and the unload will not execute.

The evaluation process, described below, explains how the value of an output argument is modified.

Note: Unless otherwise indicated:

  • All arguments shown in this documentation are required and are input arguments.
  • All input strings of the standard #functions are treated as non-DBCS, and all output strings have type of non-DBCS.

The process of evaluation of a #function call uses "call by copy/result" semantics, that is:

  1. The value of each argument entity is copied to a distinct intermediate variable which the #function can access (this is true of both input and output arguments in the current version, but in terms of the details of #function evaluation, what is important is that output arguments are copied).
  2. The value of the result is set to MISSING.
  3. During the execution of the #function, the argument values (input or output) can be accessed and output arguments can be modified, in the intermediate variables. The result can be modified or accessed by the #function; this is done directly in the %variable to which the #function result is assigned.
  4. After termination of the #function, the value of each intermediate variable corresponding to an output argument is copied to the %variable coded as the output argument.

Run-time errors during standard #function calls

The default approach for handling errors in calls to standard #functions is strict:

  • Fast/Unload treats most errors that the programmer can reasonably avoid as serious and terminates the run, if you have not provided for checking of the error.
  • At termination, Fast/Unload issues a message describing the nature of the error, the input program line number being executed and, if the error occurred during the execution of a #function, a dump of the current value of each #function argument.

Fast/Unload provides an optional output "return code" argument for some #functions. You can test the value set in this argument for errors in the value of the other arguments. Various non-zero values for the return code argument indicate error conditions; unless otherwise indicated, when one of these is set, the #function result is set to the MISSING value. If you omit the return code argument and there is an error in the value of an argument, the program is cancelled.

For example, since ONE WEEK isn't numeric, the following fragment:

%NEW_DT = #DATECHG('MM/DD/YY', '01/01/96', 'ONE WEEK',, %TST) IF %TST NE 0 THEN REPORT 'Error incrementing date:' AND %TST END IF

sets %NEW_DT to the MISSING value and produces the following line on the FUNPRINT data set:

Error incrementing date: 12

The following fragment:

%NEW_DT = #DATECHG('MM/DD/YY', '01/01/96', 'ONE WEEK')

causes Fast/Unload to immediately terminate, issuing an error message that a value is non-numeric, as shown in the following sample from FUNPRINT:

FUNL0053 Unload started. FUNL0116 Value is non-numeric or is out of range in line 203; Fast/Unload cancelled. FUNL0127 Fast/Unload cancelled unloading input record number 0 in file PROCFILE. FUNL0130 Fast/Unload cancelled during execution of line 203. FUNL0128 3 argument positions passed to #function; values : FUNL0129 01=MM/DD/YY. FUNL0129 02=01/01/96. FUNL0129 03=ONE WEEK.

Each #function description in this wiki page has a figure showing the error conditions for the #function and, if there is a "return code" argument, the non-zero values for it. Notice that, in general, there are no run-time errors for missing required arguments or too many arguments, because such checking is done at compile time.

#ABDUMP: End Fast/Unload with ABEND and dump

The #ABDUMP function accepts a numeric argument, and it causes the Fast/Unload job to terminate with user abend code equal to that argument, producing a dump.

%junk = #ABDUMP(ccode)

Where:

ccode Condition code for user ABEND; optional, defaults to 0.
%junk This #function does not return a value, but the FUEL syntax requires a place to store the #function result.

Examples

The following fragment abends the job when the input record number is 12345:

IF #RECIN EQ 12345 %FOO = #ABDUMP(99) END IF

Notes

  • The purpose of this #function is to assist in problem diagnosis. Technical Support will direct you if ever it needs to be used.

This #function is new in Fast/Unload version 4.1.

#CONCAT: Concatenate strings

The #CONCAT function accepts two or more arguments, and it returns a string value that is the concatenation of all of its arguments.

%out = #CONCAT(stra, strb ...)

Where:

stra First input string (required).
strb Second input string (required).
... Additional input strings (optional). For versions of Fast/Unload prior to 4.3, total length of all input strings may not exceed 255.
%out Concatenation of inputs.

Examples

The following fragment prints the line Bugs Bunny on the FUNPRINT data set:

%RABBIT = #CONCAT('Bugs', ' ', 'Bunny') REPORT %RABBIT

The Fast/Unload run is cancelled with a return code of 8 when:

  • Total length of input strings exceeds 255 and Fast/Unload version is less than 4.3.
  • Argument missing (see "Notes" below).

Notes

  • If the nth argument is present, where n is greater than 1, then the n-1st argument must be also be present. That is, the following results in a run-time error, because the third argument is absent:

    %X = #CONCAT(%A, %B, , %D)

  • See #CONCAT_TRUNC: Concatenate strings, allowing truncation if your version of Fast/Unload is earlier than 4.3 and if you cannot ensure that the total length of the #CONCAT input strings is less than 256.


#CONCAT_TRUNC: Concatenate strings, allowing truncation

The #CONCAT_TRUNC function accepts an optional output argument and two or more string arguments, and it returns a string value that is the concatenation of the string arguments, to a maximum of 255 bytes. It allows the total length of the string arguments to exceed 255, and it returns the total length of those arguments as the absolute value of the output argument, setting it to a negative value if the length exceeds 255.

%out = #CONCAT_TRUNC(%lenrc, stra, strb ...)

Where:

%lenrc Optional %variable, set to total length of stra, strb, ..., or to the negative of that length, if it exceeds 255.
stra First input string (required).
strb Second input string (required).
... Additional input strings (optional).
%out Concatenation of stra, strb, ..., or the first 255 bytes of that concatenation, if it exceeds 255.

Examples

The following fragment:

%FOO = #CONCAT_TRUNC(%LEN, 'Hello,', ' ', 'World!') REPORT %FOO AND 'length is' AND %LEN

prints the following line on the FUNPRINT dataset:

Hello, World! length is 13

The Fast/Unload run is cancelled with a return code of 8 when:

  • Argument missing (see "Notes" below).

Notes

  • If the nth argument is present, where n is greater than 2, then the n-1st argument must be also be present. That is, the following will result in a run-time error, because the fourth argument is absent:

    %X = #CONCAT_TRUNC(%L, %A, %B, , %D)

  • See #CONCAT: Concatenate strings if you want Fast/Unload to terminate if the total length of the input strings is greater than 255.

#C2X: Convert character string to hex representation

The #C2X function expects one required argument, and it returns a string containing the hexadecimal representation of the value in the argument string. Each byte position of the input string is converted to two characters in the result string, using only the characters 0-9 and A-F.

%hex = #C2X(str)

Where:

strString to convert. Must be 127 bytes or less.
%hexString containing hex digits.

Examples

This code fragment would produce X'C1C2818283':

%JUNK = #C2X('ABabc') REPORT 'X''' WITH %JUNK WITH ''''

This code fragment would would produce X'40F140':

%JUNK = #C2X(' 1 ') REPORT 'X WITH %JUNK WITH '

The Fast/Unload run is cancelled with a return code of 8 if:

  • Length of str exceeds 127.

Notes

  • The inverse of this #function is #X2C.
  • The SOUL $C2X function allows a maximum input length of 126, and an error causes the null string to be returned.
  • The $IHexA function ignores any input characters after the first 127.

#DATE: Current date and/or time

The #DATE function accepts an optional datetime format argument and an optional output return code argument and returns the current date and time in the specified (or defaulted) format.

%dat = #DATE(fmt, %rc)

Where:

fmt Optional format for returned date, default is YYYY-MM-DD.
%rc Optional output return code variable.
%dat Datetime string with indicated format.

Examples

The following fragment stores the current date in the last occurrence of the REORG_DATE field:

ADD REORG_DATE = #DATE()

Errors

The possible non-zero values of %rc, or terminating conditions, are shown below (see the discussion in Run-time errors during standard #function calls):

4 fmt is not a valid datetime format.

In the event of a run-time error:

  • If you specified a %rc in your #function call, it is set to the number above that corresponds to the error, and %dat is set to MISSING.
  • If %rc is absent, Fast/Unload is cancelled with return code 8.

Notes

  • The only difference between #TIME and #DATE is the default value for fmt.
  • The default format returned by the SOUL $Date and $Sir_Date functions is YY–MM–DD; the default format returned by #DATE is YYYY–MM–DD.
  • Datetime formats explains valid datetime formats.

#DATECHG: Add some days to datetime

The #DATECHG function adds a specified number of days to an input datetime, returning the incremented datetime. It requires a datetime format argument, a datetime value, and a signed number of days. It accepts an optional CENTSPAN value for interpreting datetimes with two-digit years. The incremented datetime is returned in the same format as the input datetime. An optional output return code argument allows the FUEL program to intercept error conditions.

%odat = #DATECHG(fmt, dat, n, span, %rc)

Where:

fmt Format of dat and %odat.
dat Datetime string.
n Number of days to add to dat.
span Optional CENTSPAN value.
%rc Return code variable (optional, output).
%odat Set to dat plus n days.

Examples

The following fragment prints the date one week after the run date on the FUNPRINT dataset:

%X = #DATE('DAY Month, YYYY') %X = #DATECHG('DAY Month, YYYY', %X, 7) REPORT %X

Errors

The possible non-zero values of %rc, or terminating conditions, are shown below (see the discussion in Run-time errors during standard #function calls):

4 fmt is not a valid datetime format.
8 dat does not match fmt or result date out of range.
12 n is not a number or span is invalid.

In the event of a run-time error:

  • If you specified a %rc in your #function call, it is set to the number above that corresponds to the error, and %odat is set to MISSING.
  • If %rc is absent, Fast/Unload is cancelled with return code 8.

Notes

  • Datetime formats explains valid datetime formats and valid dates.
  • The SOUL $DateChg function does not provide a call-level argument for interpreting two-digit years, the thread-level CENTSPLT/DEFCENT parameters are used instead.
  • The SOUL $Sir_DateChg function provides a CENTSPAN argument in the same fashion as #DATECHG.

#DATECHK: Check if datetime matches format

The #DATECHK function verifies that a specific datetime value is valid for a given datetime format. It requires a datetime format argument and a datetime value. It accepts an optional CENTSPAN value for interpreting datetimes with two-digit years. An optional output return code argument allows the FUEL program to intercept error conditions. The #DATECHK function returns 1 if all arguments are valid and consistent, else 0 if all arguments are valid except for the date.

%tst = #DATECHK(fmt, dat, span, %rc)

Where:

fmt Datetime format string for dat.
dat Datetime string to be validated against fmt.
span Optional CENTSPAN value.
%rc Return code variable (optional, output).
%tst Set to 1 if dat matches fmt, 0 otherwise.

Examples

The following fragment prints the string Bad on the FUNPRINT dataset:

%X = #DATECHK('DAY Month, YYYY', '30 February, 1997') IF %X = 1 THEN REPORT 'Good' ELSE REPORT 'Bad' END IF

Non-zero values of %rc, or terminating conditions, are shown in the following figure (see the discussion in Run-time errors during standard #function calls).

4 Fmt is not a valid datetime format.
12 span is an invalid CENTSPAN value.

Notes

  • Datetime formats explains valid datetime formats and valid dates.
  • The SOUL $DateChk function does not provide a call-level argument for interpreting two-digit years, the thread-level CENTSPLT/DEFCENT parameters are used instead.
  • The SOUL $Sir_DateChk function provides a CENTSPAN argument in the same fashion as #DATECHK.

#DATECNV: Convert datetime to different format

The #DATECNV function converts a datetime value from one datetime format to another datetime format. It requires an input datetime value, a corresponding input datetime format string, and an output datetime format string. It accepts an optional CENTSPAN value for interpreting datetimes with two-digit years. An optional output return code argument allows the FUEL program to intercept error conditions. The #DATECNV function returns the input datetime value in the format specified by the output datetime format string.

%odat = #DATECNV(infmt, outfmt, dat, span, %rc)

Where:

infmt Datetime format string for dat.
outfmt Datetime format string for %odat.
dat Input datetime string.
span Optional CENTSPAN value.
%rc Return code variable (optional, output).
%odat Set to the value of dat, converted to output format.

Examples

This prints the string 19970101 on the FUNPRINT dataset:

%X = #DATECNV('YYMMDD', 'YYYYMMDD', '970101', 1950) REPORT %X

Errors

The possible non-zero values of %rc, or terminating conditions, are shown below (see the discussion in Run-time errors during standard #function calls):

4 infmt or outfmt is not a valid datetime format.
8 dat does not match infmt.
12 span is an invalid CENTSPAN value.
16 Converted datetime value out of range for %outfmt.

In the event of a run-time error:

  • If you specified a %rc in your #function call, it is set to the number above that corresponds to the error, and %odat is set to MISSING.
  • If %rc is absent, Fast/Unload is cancelled with return code 8.

Notes

#DATEDIF: Difference between two dates

The #DATEDIF function subtracts a second date from a first date and returns the difference in days, ignoring time portions for both dates. It requires a first datetime format string, a first datetime value, and a second datetime value. It accepts an optional second datetime format string and an optional CENTSPAN value for interpreting datetimes with two-digit years. An optional output return code argument allows the FUEL program to intercept error conditions.

%dif = #DATEDIF(fmta, data, fmtb, datb, span, %rc)

Where:

fmta Datetime format string for data.
data First datetime string.
fmtb Optional second datetime format string for datb. Default is to use fmta.
datb Second datetime string.
span Optional CENTSPAN value.
%rc Return code variable (optional, output).
%dif Set to the number of days obtained by subtracting the second date from the first date, ignoring any time components of both dates.

Examples

The following fragment prints the string 7 days on the FUNPRINT dataset:

%X = #DATEDIF('YYMMDD', '970308', , '970301') REPORT %X AND 'days'

Errors

The possible non-zero values of %rc, or terminating conditions, are shown below (see the discussion in Run-time errors during standard #function calls):

4 fmta or fmtb is not a valid datetime format.
8 data does not match fmta, or datb does not match fmtb.
12 span is an invalid CENTSPAN value.

In the event of a run-time error:

  • If you specified a %rc in your #function call, it is set to the number above that corresponds to the error, and %dif is set to MISSING.
  • If %rc is absent, Fast/Unload is cancelled with return code 8.

Notes

  • Time is ignored in the subtraction.
  • In the example above, even though the input dates have two-digit years, there is no need for a span argument, since the dates are in the same year.
  • As in the SOUL $DATEDIF function, the single span argument is used for both dates. If it is necessary to get the difference between two dates which both have two-digit years and are in different 100-year windows, you must first use #DATECNV to convert one of them to some four-digit year format.
  • Datetime formats explains valid datetime formats and valid dates.

#DATEFMT: Validate datetime format string

The #DATEFMT function is used to validate a datetime format string. It requires a datetime format string. It returns a value of 1 if the datetime format string is valid, else it returns a value of 0.

%tst = #DATEFMT(fmt)

Where:

fmtDatetime format string to be validated.
%tstSet to 1 if fmt is a valid format string, else set to 0.

Examples

The following fragment prints the string Good on the FUNPRINT dataset:

%X = #DATEFMT('CYYDDDHHMISSXXX') IF %X = 1 THEN REPORT 'Good' ELSE REPORT 'Bad' END IF

This #function has no terminating conditions.

Notes

#DATE2N: Convert datetime string to number of seconds*300

The #DATE2N function converts a datetime value in a string format into a numeric form that is the corresponding number of seconds*300 since January 1, 1900. It requires a datetime value string and a corresponding datetime format string. It accepts an optional CENTSPAN value for interpreting datetimes with two-digit years. An optional output return code argument allows the FUEL program to intercept error conditions.

%num = #DATE2N(dat, fmt, span, %rc)

Where:

dat Datetime value string.
fmt Datetime format string for dat.
span Optional CENTSPAN value.
%rc Return code variable (optional, output).
%num Set to the number of seconds*300 since 1 Jan 1900 12:00 AM that corresponds to the datetime value of dat.

Examples

The following fragment prints the value BEFORE on the FUNPRINT dataset:

IF #DATE2N('121494', 'MMDDYY') < - #DATE2N('040195', 'MMDDYY') THEN REPORT 'BEFORE' END IF

Errors

The possible non-zero values of %rc, or terminating conditions, are shown below (see the discussion in Run-time errors during standard #function calls):

4 fmt is not a valid datetime format.
8 dat does not match fmt or result date out of range.
12 span is an invalid CENTSPAN value.

In the event of a run-time error:

  • If you specified a %rc in your #function call, it is set to the number above that corresponds to the error, and %num is set to MISSING.
  • If %rc is absent, Fast/Unload is cancelled with return code 8.

Notes

  • Values returned by #DATE2N often exceed the range that can be represented in a 4-byte integer, so you should probably avoid storing the value in a BINARY or FLOAT4 field.
  • Dates prior to 1 January 1900 will return a negative number.
  • The inverse of this #function is #N2DATE.
  • Datetime formats explains valid datetime formats and valid dates.

#DATE2ND: Convert datetime string to number of days

The #DATE2ND function converts a datetime value in a string format into a numeric form that is the corresponding number of days since January 1, 1900. It requires a datetime value string and a corresponding datetime format string. It accepts an optional CENTSPAN value for interpreting datetimes with two-digit years. An optional output return code argument allows the FUEL program to intercept error conditions.

%num = #DATE2ND(dat, fmt, span, %rc)

Where:

dat Datetime value string.
fmt Datetime format string for dat.
span Optional CENTSPAN value.
%rc Return code variable (optional, output).
%num Set to the number of days since 1 Jan 1900 12:00 AM that corresponds to the datetime value of dat.

Examples

The following fragment prints the value BEFORE on the FUNPRINT dataset:

IF #DATE2ND('121494', 'MMDDYY') < #DATE2ND('040195', 'MMDDYY') THEN REPORT 'BEFORE' END IF

Errors

The possible non-zero values of %rc, or terminating conditions, are shown below (see the discussion in Run-time errors during standard #function calls):

4 fmt is not a valid datetime format.
8 dat does not match fmt or result date out of range.
12 span is an invalid CENTSPAN value.

In the event of a run-time error:

  • If you specified a %rc in your #function call, it is set to the number above that corresponds to the error, and %num is set to MISSING.
  • If %rc is absent, Fast/Unload is cancelled with return code 8.

Notes

  • Dates prior to 1 January 1900 will return a negative number.
  • The inverse of this #function is #ND2DATE.
  • Datetime formats explains valid datetime formats and valid dates.

#DATE2NM: Convert datetime string to number of milliseconds

The #DATE2NM function converts a datetime value in a string format into a numeric form that is the corresponding number of milliseconds since January 1, 1900. It requires a datetime value string and a corresponding datetime format string. It accepts an optional CENTSPAN value for interpreting datetimes with two-digit years. An optional output return code argument allows the FUEL program to intercept error conditions.

%num = #DATE2NM(dat, fmt, span, %rc)

Where:

dat Datetime value string.
fmt Datetime format string for dat.
span Optional CENTSPAN value.
%rc Return code variable (optional, output).
%num Set to the number of milliseconds since 1 Jan 1900 12:00 AM that corresponds to the datetime value of dat.

Examples

The following fragment prints the value BEFORE on the FUNPRINT dataset:

IF #DATE2NM('121494', 'MMDDYY') < #DATE2NM('040195', 'MMDDYY') THEN REPORT 'BEFORE' END IF

Errors

The possible non-zero values of %rc, or terminating conditions, are shown below (see the discussion in Run-time errors during standard #function calls):

4 fmt is not a valid datetime format.
8 dat does not match fmt or result date out of range.
12 span is an invalid CENTSPAN value.

In the event of a run-time error:

  • If you specified a %rc in your #function call, it is set to the number above that corresponds to the error, and %num is set to MISSING.
  • If %rc is absent, Fast/Unload is cancelled with return code 8.

Notes

  • Values returned by #DATE2NM will often exceed the range that can be represented in a 4-byte integer, so you should probably avoid storing the value in a BINARY or FLOAT4 field.
  • Dates prior to 1 January 1900 will return a negative number.
  • The inverse of this #function is #NM2DATE.
  • Datetime formats explains valid datetime formats and valid dates.

#DATE2NS: Convert datetime string to number of seconds

The #DATE2NS function converts a datetime value in a string format into a numeric form that is the corresponding number of seconds since January 1, 1900. It requires a datetime value string and a corresponding datetime format string. It accepts an optional CENTSPAN value for interpreting datetimes with two-digit years. An optional output return code argument allows the FUEL program to intercept error conditions.

%num = #DATE2NS(dat, fmt, span, %rc)

Where:

dat Datetime value string.
fmt Datetime format string for dat.
span Optional CENTSPAN value.
%rc Return code variable (optional, output).
%num Set to the number of seconds since 1 Jan 1900 12:00 AM that corresponds to the datetime value of dat.

Examples

The following fragment prints the value BEFORE on the FUNPRINT dataset:

IF #DATE2NS('121494', 'MMDDYY') < #DATE2NS('040195', 'MMDDYY') THEN REPORT 'BEFORE' END IF

Errors

The possible non-zero values of %rc, or terminating conditions, are shown below (see the discussion in Run-time errors during standard #function calls):

4 fmt is not a valid datetime format.
8 dat does not match fmt or result date out of range.
12 span is an invalid CENTSPAN value.

In the event of a run-time error:

  • If you specified a %rc in your #function call, it is set to the number above that corresponds to the error, and %num is set to MISSING.
  • If %rc is absent, Fast/Unload is cancelled with return code 8.

Notes

  • Values returned by #DATE2NS will often exceed the range that can be represented in a 4-byte integer, so you should probably avoid storing the value in a BINARY or FLOAT4 field.
  • Dates prior to 1 January 1900 will return a negative number.
  • The inverse of this #function is #NS2DATE.
  • Datetime formats explains valid datetime formats and valid dates.

#DEBLANK: Remove leading and trailing blanks from substring

The #DEBLANK function extracts a substring (starting at pos for length len) and returns it, with leading and trailing blanks removed. It requires a string to be deblanked. It accepts an optional starting position within the string to be deblanked, and an optional length.

%out = #DEBLANK(str, pos, len)

Where:

str String to be deblanked; required.
pos Optional position within str to start deblanking. Must be numeric greater than or equal to 1, default is 1.
len Optional length, starting at pos of string to deblank. Must be numeric greater than or equal to 0, default is the remainder of the input string.
%out Set to the substring within str, starting at pos for length len; leading and trailing blanks are then removed from this substring. Intermediate blanks within the substring are not affected.

Examples

#DEBLANK(' ABC ') returns 'ABC' #DEBLANK(' ABC ', 1, 2) returns 'A' #DEBLANK(' A BC ', 2, 4) returns 'A B'

The Fast/Unload run is cancelled with a return code of 8 if:

  • pos is not numeric, or less than 1.
  • len is not numeric, or less than 0.

Notes

#DELWORD: Remove blank-delimited words from string

The #DELWORD function removes one or more words from a string. It requires an input string and a word number within the string. It accepts an optional number of words to delete, and as of version 4.6, an optional character delimiter to replace the default blank delimiter for separating words.

%out = #DELWORD(str, word, [count], [delimiter])

Where:

str String containing words to be deleted; required.
word Number of first word within str to remove; required. Must be numeric greater than or equal to 1.
count Optional count of words to remove. Must be numeric greater than or equal to 0, and the default is the remainder of words in the input string.
delimiter Optional one-character delimiter to separate words within str. The default delimiter is a blank.

This argument is available as of version 4.6 of Fast/Unload.

%out Set to str with the substring removed which starts with the first character of word number word and ends with the last blank character before word number word+count.

Examples

  1. #DELWORD('A B C', 1) returns '' #DELWORD('A B C', 2) returns 'A ' #DELWORD(' A B C ', 3) returns ' A B ' #DELWORD('A B C', 4) returns 'A B C' #DELWORD(' ', 1) returns ' ' #DELWORD('A B C', 1, 1) returns 'B C' #DELWORD('A B C', 1, 4) returns '' #DELWORD('A B C', 2, 2) returns 'A '


  2. %X = 'Friends and Romans. Lend me your ears. I bury Brutus.' %Y = #DELWORD(%X, 2, 1, '.') PUT %Y OUTPUT

    The result of the above fragment is:

    Friends and Romans. I bury Brutus.

Notes

The Fast/Unload run is cancelled with a return code of 8 if:

  • word is not numeric, or less than 1.
  • count is not numeric, or less than 0.

This #function is new in Fast/Unload version 4.0.

#FIND: Word position of one word sequence within another

The #FIND function determines the word position, within a string of blank-delimited words, of one or more blank-delimited words. It requires an input string to search within and an input sequence of words to search for.

%pos = #FIND(haystack, words)

Where:

haystack String containing words to be searched within; required.
words String containing one or more blank-delimited words to find; required.
%pos Set to the word position, within haystack, of the first word of a sequence of words that matches the sequence in words. If words is not found, %pos is set to 0.

Examples

#FIND('A B C', 'B') returns 2 #FIND('A B C', 'D') returns 0 #FIND('A B C', 'A B') returns 1 #FIND(' ', ' ') returns 0 #FIND('A B', 'A B C') returns 0 #FIND('B B B A', 'B B A') returns 2 #FIND('A A B', ' A B ') returns 2 #FIND(' A A B ', 'A B') returns 2

This #function has no cancelling conditions.

Notes

  • Multiple blanks in both input arguments are ignored.
  • This #function is similar to the #ONEOF function (#ONEOF: See if string is in delimited list of strings). Note, however, that both #FIND and #ONEOF are inferior to the SELECT statement, when the only purpose is to test whether an entity has one of several values (see SELECT entity).

#FLOAT8: Get 8-byte float, padding 4-byte input with 0

The #FLOAT8 function accepts a numeric argument, and it returns the value of the argument as an 8-byte floating point value. If the argument is a 4-byte floating point value, then the conversion is done by appending binary zeroes; otherwise, it is done by the normal FUEL conversion to an 8-byte floating point value.

%out = #FLOAT8(in)

Where:

%out Set to 8-byte floating point value of input argument.
in Numeric input value.

Notes

  • See Fast/Unload floating point arithmetic and numeric conversion for a specification of conversions to floating point values.
  • Numeric operations in FUEL and in SOUL are based on decimal, not binary, interpretation of floating point values, so this #function is seldom used.

    However, #FLOAT8 may be useful in unusual situations, in particular to perform a file reorganization that expands a FLOAT LEN 4 field to a FLOAT LEN 8 field, using the "raw" floating point conversion (such as can be done in a structured file reorganization using the X'0080' mode bit in FLOD).

    For example, if field FLT is defined in the input as FLOAT LEN 4, and you want to convert it to a FLOAT LEN 8 or FLOAT LEN 16 in a UAI/LAI file reorganization in such a way that the new field's values consist of the old ones with binary zeros added, you can use the following:

    OPEN PRODFILE UAI FOR EACH RECORD FOR I FROM 1 TO FLT(#) CHANGE FLT(I) = #FLOAT8(FLT(I)) END FOR UNLOAD END FOR

    In this example, if the input value of FLT is 411028F6, which is the closest 4-byte floating point value to the decimal value 1.01, it is converted on output to 411028F600000000, which SOUL will display as 1.01000022888184 (demonstrating that #FLOAT8 is only to be used in special circumstances).

    A "normal" UAI/LAI conversion of 411028F6. to a FLOAT LEN 8 field would be to the hexadecimal value 411028F5C28F5C28, which SOUL will display as 1.01.

This #function is new in Fast/Unload version 4.3.

#INDEX: Position of second string within first

The #INDEX function locates the first occurrence, if any, of a search string (needle) within a searched string (haystack). It requires a string to be searched and accepts an optional string to locate. It accepts an optional starting position within the string to be searched. #INDEX returns either the starting position within the searched string of the first occurrence of the string to be located (starting at the specified position), or 0.

%opos = #INDEX(haystack, needle, pos)

Where:

haystack String to be searched; required.
needle String to be located, may be omitted.
pos Optional starting position within haystack for search. Must be numeric greater than or equal to 1, default is 1.
%opos Set to starting position of first occurrence of needle within haystack, with search starting at pos, else 0 if not found or if either string length is zero.

Examples

#INDEX('123xy', '23') returns 2 #INDEX('123xy', '45') returns 0 #INDEX('12312', '12', 2) returns 4 #INDEX('123xy', '23', 3) returns 0

The Fast/Unload run is cancelled with a return code of 8 when:

  • pos is not numeric, or less than 1.

Notes

  • If needle or haystack is the null string, 0 is returned.

#LEFT: Initial substring, followed by pad characters to specified length

The #LEFT function returns a padded initial substring from a source string. It expects a source string argument and a numeric length of the output string. It accepts an optional pad character. #LEFT returns the string that begins at the first position of the source string and is of the specified output length. If the output length is less than or equal to the length of the source string, the first length characters of the source are returned. Otherwise, the source string is padded to the output length by following it with sufficient copies of the pad character.

%out = #LEFT(str, len, pad)

Where:

str Source string.
len Length of the output string. Must be numeric and greater than or equal to 0.
pad Optional pad character. Default is blank. If supplied, must be a string of length 1.
%out If len is greater then #LEN(str):
  • All of str, followed by len - #LEN(str) copies of the pad character

Otherwise:

  • Substring from str starting at position 1 with length len

Examples

#LEFT('ABC', 1) returns A' #LEFT('ABC', 3) returns 'ABC' #LEFT('ABC', 4) returns 'ABC ' #LEFT(4.6, 4, 0) returns '4.60'

The Fast/Unload run is cancelled with a return code of 8 if:

  • len not numeric, or less than 0.
  • pad supplied, and length not 1.

Notes

#LEN: Length of string

The #LEN function returns the length of a string, in number of bytes. It expects a required string argument and returns a numeric result.

%len = #LEN(str)

Where:

str String whose length you want to know. For Fast/Unload version 4.3 and later. str may be longer than 255 bytes.
%len Set to length of str.

Examples

The following fragment prints the string Length: 13 on the FUNPRINT dataset:

%X = #LEN('Hello, world!') REPORT 'Length:' AND %X

This #function has no cancelling conditions.

#LOWCASE: Change uppercase letters of string to lowercase

The #LOWCASE function returns a copy of the input string, with all uppercase EBCDIC letters changed to the corresponding lowercase letters. It expects a source string argument.

%out = #LOWCASE(str)

Where:

str Source string, required.
%out Copy of str, with all uppercase EBCDIC letters changed to their lowercase EBCDIC equivalents.

Examples

#LOWCASE('?abc') returns '?abc' #LOWCASE('?ABC') returns '?abc' #LOWCASE('') returns ''

Notes

This #function has no cancelling conditions.

#ND2DATE: Convert number of days to datetime string

The #ND2DATE function converts a numeric datetime value expressed as the number of days since January 1, 1900 into a datetime string value according to a specified datetime format string. It requires a datetime numeric value and a datetime format string. An optional output return code argument allows the FUEL program to intercept error conditions.

%dat = #ND2DATE(datn, fmt, %rc)

Where:

datn Numeric datetime value expressed as the number of days since 1 Jan 1900 12:00 AM. This argument may not have the MISSING value.
fmt Datetime format string to use for creating %dat.
%rc Return code (optional, output)
%dat Set to datetime string value, in format specified by fmt, corresponding to datn.

Examples

The following fragment prints the string 07/31/84 on the FUNPRINT dataset:

%X = #DATE2ND('8407301230', 'YYMMDDHHMI') %X = %X + 1 /* Add 1 day %X = #ND2DATE(%X, 'MM/DD/YY') REPORT %X

Errors

The possible non-zero values of %rc, or terminating conditions, are shown below (see the discussion in Run-time errors during standard #function calls):

4 fmt is not a valid datetime format.
8 datn is out of range for fmt.

In the event of a run-time error:

  • If you specified a %rc in your #function call, it is set to the number above that corresponds to the error, and %dat is set to MISSING.
  • If %rc is absent, Fast/Unload is cancelled with return code 8.

Notes

#NM2DATE: Convert number of milliseconds to datetime string

The #NM2DATE function converts a numeric datetime value expressed as the number of milliseconds since January 1, 1900 into a datetime string value according to a specified datetime format string. It requires a datetime numeric value and a datetime format string. An optional output return code argument allows the FUEL program to intercept error conditions.

%dat = #NM2DATE(datn, fmt, %rc)

Where:

datn Numeric datetime value expressed as the number of milliseconds since 1 Jan 1900 12:00 AM. This argument may not have the MISSING value.
fmt Datetime format string to use for creating %dat.
%rc Return code (optional, output)
%dat Set to datetime string value, in format specified by fmt, corresponding to datn.

Examples

The following fragment prints the string 07/31/84 on the FUNPRINT dataset:

%X = #DATE2NM('8407301230', 'YYMMDDHHMI') %X = %X + 1000 * 60 * 60 * 15 /* Add 15 hours %X = #NM2DATE(%X, 'MM/DD/YY') REPORT %X

Errors

The possible non-zero values of %rc, or terminating conditions, are shown below (see the discussion in Run-time errors during standard #function calls):

4 fmt is not a valid datetime format.
8 datn is out of range for fmt.

In the event of a run-time error:

  • If you specified a %rc in your #function call, it is set to the number above that corresponds to the error, and %dat is set to MISSING.
  • If %rc is absent, Fast/Unload is cancelled with return code 8.

Notes

#NS2DATE: Convert number of seconds to datetime string

The #NS2DATE function converts a numeric datetime value expressed as the number of seconds since January 1, 1900 into a datetime string value according to a specified datetime format string. It requires a datetime numeric value and a datetime format string. An optional output return code argument allows the FUEL program to intercept error conditions.

%dat = #NS2DATE(datn, fmt, %rc)

Where:

datn Numeric datetime value expressed as the number of seconds since 1 Jan 1900 12:00 AM. This argument may not have the MISSING value.
fmt Datetime format string to use for creating %dat.
%rc Return code (optional, output)
%dat Set to datetime string value, in format specified by fmt, corresponding to datn.

Examples

The following fragment prints the string 07/31/84 on the FUNPRINT dataset:

%X = #DATE2NS('8407301230', 'YYMMDDHHMI') %X = %X + 60 * 60 * 15 /* Add 15 hours %X = #NS2DATE(%X, 'MM/DD/YY') REPORT %X

Errors

The possible non-zero values of %rc, or terminating conditions, are shown below (see the discussion in Run-time errors during standard #function calls):

4 fmt is not a valid datetime format.
8 datn is out of range for fmt.

In the event of a run-time error:

  • If you specified a %rc in your #function call, it is set to the number above that corresponds to the error, and %dat is set to MISSING.
  • If %rc is absent, Fast/Unload is cancelled with return code 8.

Notes

#NUM2STR: Convert number to string with decimal point

The #NUM2STR function converts a number to a string with an integer part, followed by an optional decimal point and decimal fraction digits, with control over the number of integer and fraction digits, padding, and rounding. It requires a numeric value. Optional arguments specify the width of the resulting integer digits area, the width of the resulting fraction digits area, rounding vs. truncation and fixed width vs. variable/minimal width integer area, and the leading pad character for the integer digits area.

The final optional argument is an output argument whose absolute value is set to the number of integer characters (after leading zeroes are stripped) in the number, plus 1 if the number is negative. Specifying this argument allows the Fast/Unload program to continue if the first argument cannot be represented by the result, either as a result of truncation of the high-order integer digits, or because the first argument cannot be converted to a number.

%str = #NUM2STR(num, [intw], [fracw], [opt], [pad], [%intlen])

Where:

num Input number to be converted.
intw Number of characters used to express the integer portion and leading minus sign, if any, of num.

Optional, must be 0 or more if specified. If omitted, only the characters needed are used to represent the integer part: a leading minus sign, if num is negative, is followed by the integer portion with leading zeroes stripped (except if the integer portion is zero, a single digit 0 is used).

If the fourth argument (opt) contains the letter V, intw is the minimal width used for the integer part, and the number of characters needed is used if that exceeds intw.

fracw Number of digits used to express the fraction portion of num. Optional, must be 0 or more if specified. If this argument is omitted:
  • only the characters needed are used to represent the fraction part
  • if the fraction part is 0, no decimal point occurs in the result
  • if the fraction part is not 0, trailing zeroes are removed
%opt One or two characters, optional, with one choice from either of the following two pairs:
  • R (round) or T (trunc)
    R Round up the final digit of the result, if the most significant discarded fraction digit is 5 or more. This is the default.
    T Final digit of result unaffected by any discarded fraction digits.

    This character has no meaning if argument three (fracw) is omitted, since in that case no fraction digits are discarded.

  • F (fixed width) or V (variable width)
    F The integer portion of the result is fixed width. That is, as many characters are used for the integer (and leading minus sign) as the value of argument two (intw). This is the default.
    V The integer portion of the result is variable/minimal width. That is, if w characters are needed for the integer (and leading minus sign) with leading zeroes removed, then w characters are used for the integer if w is greater than intw; intw characters are used otherwise.

    This character has no meaning if argument two (intw) is omitted, since in that case exactly the characters needed for the integer are used.

pad The leading pad character used to fill the integer portion to the width specified by argument two (intw). Optional, must be one character, defaults to blank. If the pad character is blank, a leading minus sign follows any blank pad characters; otherwise a leading minus sign precedes any pad characters.
%intlen Set to the value len, where the absolute value of len is the number of characters needed for the integer part of the first argument (num), with any leading zeroes stripped (or one zero if the integer part is zero), including one additional character if num is negative.

If %intlen is returned with a negative value, it indicates truncation of the integer part of num. This truncation occurs if all of the following conditions hold:

  • Argument two (intw) is specified.
  • The absolute value of len is greater than intw.
  • intw greater than 0, or num less than 0, or num greater than or equal to 1.
  • Argument four (opt) does not contain the letter V.

If num cannot be converted to a number, then len is returned as zero, and the result (value of %str) of #NUM2STR is the MISSING value.

Otherwise, len is positive.

As these rules indicate, %intlen, if supplied, allows the Fast/Unload program to continue when the first argument is non-numeric or the integer part is truncated in the result. If either of these conditions occur and %intlen is omitted, the Fast/Unload program is cancelled.

Examples

%N_HUMAN = 6 * 1000 * 1000 * 1000 #NUM2STR(%N_HUMAN) -> "6000000000"

%PI = 3.14159265 #NUM2STR(%PI) -> "3.14159265" #NUM2STR(%PI, , 3) -> "3.142" #NUM2STR(%PI, , 3, 'T') -> "3.141"

%PCT7_5 = 7.5/100 #NUM2STR(%PCT7_5) -> "0.075" #NUM2STR(%PCT7_5, , 4) -> "0.0750" #NUM2STR(%PCT7_5, 0, , , '*', %W) -> ".075" with ... %W = 1 #NUM2STR(%PCT7_5, 2, , , '*', %W) -> "*0.075" with ... %W = 1

%NEGP7_5 = - %PCT7_5 #NUM2STR(%NEGP7_5) -> "-0.075" #NUM2STR(%NEGP7_5, 1, , , '*') -> "-.075" #NUM2STR(%NEGP7_5, 2, , , '*') -> "-0.075" #NUM2STR(%NEGP7_5, 3, , , '*') -> "-*0.075" #NUM2STR(%NEGP7_5, 3, , , ' ') -> " -0.075"

%TBIL = 6.025 %VISA = 18.5 #NUM2STR(%TBIL, 1, 3, , '0') -> "6.025" #NUM2STR(%VISA, 1, 3, , '0', %W) -> "8.500" with ... %W = -2 #NUM2STR(%VISA, 1, 3, 'V', '0', %W) -> "18.500" with ... %W = 2

%BAD = 'PIZZA' #NUM2STR(%BAD, , , , , %W) -> MISSING value with ... %W = 0

Errors

The possible non-zero values of %intlen, or terminating conditions, are shown below (see the discussion in Run-time errors during standard #function calls):

-N N is the length required for the integer part of num, and n is greater than intw and opt does not contain the letter V.
0 num can not be converted to a numeric value (%str is set to MISSING).
** Negative or non-numeric value for intw or fracw (this error always cancels Fast/Unload, regardless of the presence of %intlen).
** Invalid character in opt (this error always cancels Fast/Unload, regardless of the presence of %intlen).
** Length of pad not 1 (this error always cancels Fast/Unload, regardless of the presence of %intlen).

In the event of a run-time error:

  • If you specified a %intlen in your #function call, it is set to the return code above that corresponds to the error.
  • If %intlen is absent, Fast/Unload is cancelled with return code 8.

Note: If you are creating a string to place in the Fast/Unload output file, you can also use the PUT with the AS STRING or AS DECIMAL clauses (see PUT).

One difference between #NUM2STR and PUT AS STRING or PUT AS DECIMAL is that all conversion of fractional values to fixed width output formats in the PUT statement causes low order fraction digits to be dropped without rounding, but #NUM2STR offers rounding of dropped low-order digits.

#N2DATE: Convert number of seconds*300 to datetime string

The #N2DATE function converts a numeric datetime value expressed as the number of seconds*300 since January 1, 1900 into a datetime string value according to a specified datetime format string. It requires a datetime numeric value and a datetime format string. An optional output return code argument allows the FUEL program to intercept error conditions.

%dat = #N2DATE(datn, fmt, %rc)

Where:

datn Numeric datetime value expressed as 300 times the number of seconds since 1 Jan 1900 12:00 AM. This argument may not have the MISSING value.
fmt Datetime format string to use for creating %dat.
%rc Return code (optional, output)
%dat Set to datetime string value, in format specified by fmt, corresponding to datn.

Examples

The following fragment prints the string 07/31/84 on the FUNPRINT dataset:

%X = #DATE2N('8407301230', 'YYMMDDHHMI') %X = %X + 300 * 60 * 60 * 15 /* Add 15 hours %X = #N2DATE(%X, 'MM/DD/YY') REPORT %X

Errors

The possible non-zero values of %rc, or terminating conditions, are shown below (see the discussion in Run-time errors during standard #function calls):

4 fmt is not a valid datetime format.
8 datn is out of range for fmt.

In the event of a run-time error:

  • If you specified a %rc in your #function call, it is set to the number above that corresponds to the error, and %dat is set to MISSING.
  • If %rc is absent, Fast/Unload is cancelled with return code 8.

Notes

#ONEOF: See if string is in delimited list of strings

The #ONEOF function determines whether a string is found in a delimited list of strings. It requires an input string to search for and a delimited list of strings to search within. It accepts an optional delimiter character, which is used to separate the strings in the list.

%test = #ONEOF(str, list, delim)

Where:

str String to find; required.
list String containing words to be searched within; required.
delim Character used to separate strings in list; optional. Default is semicolon (;).
%test Set to 1 if str is one of the strings in list, delimited by delim. Otherwise, %test is set to 0.

Examples

#ONEOF('HOW', 'HOW NOW', ' ') returns 1 #ONEOF('NOW', 'HOW;NOW') returns 1 #ONEOF('ABC', 'ABC') returns 1 #ONEOF('', 'HOW;;NOW') returns 1 #ONEOF('', ';HOW;NOW') returns 1 #ONEOF('', 'HOW;NOW;') returns 1 #ONEOF('', 'HOW;NOW') returns 0 #ONEOF('NO', 'HOW;NOW') returns 0 #ONEOF('HOW;NOW', 'HOW;NOW') returns 0 #ONEOF('', '') returns 0

The Fast/Unload run is cancelled with a return code of 8 when:

  • delim supplied, and length not 1.

Notes

  • If argument 1 str) contains delim, 0 is returned.
  • If argument 2 (list) is the null string, 0 is returned.
  • If argument 1 (str) is the null string, 1 is returned if, and only if, there is a leading, trailing, or two adjacent copies of, delim.
  • This #function is similar to the #FIND function (#FIND: Word position of one word sequence within another). Note, however, that both #FIND and #ONEOF are inferior to the SELECT statement, when the only purpose is to test whether an entity has one of several values (see SELECT entity).

#PAD: Final substring, preceded by pad characters to specified length

The #PAD function returns a padded final substring from a source string. It expects a source string argument and a numeric length of the output string. It accepts an optional pad character. #PAD returns the string that ends at the last position of the source string and is of the specified output length. If the output length is less than or equal to the length of the source string, the last length characters of the source are returned. Otherwise, the source string is padded to the output length by preceding it with sufficient copies of the pad character.

%out = #PAD(str, pad, len)

Where:

str Source string.
pad Optional pad character. Default is blank. If supplied, must be a string of length 1.
len Length of the output string. Must be numeric and greater than or equal to 0.
%out If len is greater then #LEN(str):
  • len-#LEN(str) copies of the pad character, followed by all of str

Otherwise:

  • substring from str starting at position #LEN(str)-len+1 with length len

Examples

#PAD('ABC', , 0) returns '' #PAD('ABC', , 1) returns 'C' #PAD('ABC', , 3) returns 'ABC' #PAD('ABC', , 4) returns ' ABC' #PAD(456, 0, 4) returns '0456'

The Fast/Unload run is cancelled with a return code of 8 when:

  • len not numeric, or less than 0.
  • pad supplied, and length not 1.

Notes

#PADR: Initial substring, followed by pad characters to specified length

The #PADR function returns a padded initial substring from a source string. It expects a source string argument and a numeric length of the output string. It accepts an optional pad character. #PADR returns the string that begins at the first position of the source string and is of the specified output length. If the output length is less than or equal to the length of the source string, the first length characters of the source are returned. Otherwise, the source string is padded to the output length by following it with sufficient copies of the pad character.

%out = #PADR(str, pad, len)

Where:

str Source string.
pad Optional pad character. Default is blank. If supplied, must be a string of length 1.
len Length of the output string. Must be numeric and greater than or equal to 0.
%out If len is greater then #LEN(str):
  • all of str, followed by len-#LEN(str) copies of the pad character

Otherwise:

  • substring from str starting at position 1 with length len

Examples

#PADR('ABC', , 1) returns 'A' #PADR('ABC', , 3) returns 'ABC' #PADR('ABC', , 4) returns 'ABC ' #PADR(4.6, 0, 4) returns '4.60'

The Fast/Unload run is cancelled with a return code of 8 when:

  • len not numeric, or less than 0.
  • pad supplied, and length not 1.

Notes

#QUOTE: Wrap string in quote character, and double embedded quotes

This function returns the input string with a quote character added before and after the input, and with any quote characters within the input replaced by two copies of the quote character.

%quoted = #QUOTE(string, char)

Where:

%quoted The input string wrapped in quotes with embedded quotes doubled. It may be a long string (that is, it may exceed 255 bytes in length).
string The input string to be quoted. It may be a long string (that is, it may exceed 255 bytes in length).
char The quote character. It must be a string of length one.

Example

%S = 'Don''t stop' %L = #LEN(%S) PUT %L PUT ' ' PUT %S OUTPUT %Q = #QUOTE(%S, '''') %L = #LEN(%Q) PUT %L PUT ' ' PUT %Q OUTPUT

The output from the above FUEL fragment is:

10 Don't stop 13 'Don''t stop'

This #function is new in Fast/Unload version 4.6.

#REVERSE: Get reverse of string

The #REVERSE function returns a copy of the input string, with the order of the bytes reversed. It expects a source string argument.

%out = #REVERSE(str)

Where:

str Source string; required.
%out Copy of str, with all the last input byte first, followed by the next to last input byte, etc.

Examples

#REVERSE('abc') returns 'cba'

This #function has no cancelling conditions.

#RIGHT: Final substring, preceded by pad characters to specified length

The #RIGHT function returns a padded final substring from a source string. It expects a source string argument and a numeric length of the output string. It accepts an optional pad character.

#RIGHT returns the string that ends at the last position of the source string and is of the specified output length. If the output length is less than or equal to the length of the source string, the last length characters of the source are returned. Otherwise, the source string is padded to the output length by preceding it with sufficient copies of the pad character.

%out = #RIGHT(str, len, pad)

Where:

str Source string.
len Length of the output string.
pad Optional pad character. Default is blank. If supplied, must be a string of length 1. Must be numeric and greater than zero.
%out If len is greater then #LEN(str):
  • len-#LEN(str) copies of the pad character, followed by all of str

Otherwise:

  • substring from str starting at position #LEN(str)-len+1 with length len

Examples

#RIGHT('ABC', 0) returns '' #RIGHT('ABC', 1) returns 'C' #RIGHT('ABC', 3) returns 'ABC' #RIGHT('ABC', 4) returns ' ABC' #RIGHT(456, 4, 0) returns '0456'

Notes

#SHADIGEST: SHA-1 digest ("hash") of string

This function returns the 20-byte (always) binary string that is the SHA-1 digest of the argument.

%hashval = #SHADIGEST(string)

Where:

%hashval A %variable to receive the SHA-1 digest of the argument string.
string The input string to be hashed. This may be a long string (that is, it may exceed 255 bytes in length).

Example

The 20-byte SHA-1 hash of a string is typically expressed as a 40-digit hex value. In the following example, the output string from #SHADIGEST is converted to hex using the #C2X function:

%HSH = #SHADIGEST('this is a simple test') %XHSH = #C2X(%HSH) PUT %XHSH OUTPUT

The result is:

BC38AA2D6769639946806616C14AF0C69477AABE

Notes

  • SHA (Secure Hash Algorithm) is a set of cryptographic hashing functions, and #SHADIGEST provides SHA-1, the most commonly used. A complete explanation of SHA hashing can easily be found on the internet.
  • This FUEL #function operates the same as the SOUL SHAdigest method.
  • This #function is new in Fast/Unload version 4.6.

#SNDX: Create SOUNDEX code for string

The #SNDX function calculates a SOUNDEX code for a string, producing the same result as the Model 204 $Sndx function. It expects a single argument and returns the SOUNDEX code for the string value of the argument.

%out = #SNDX(str)

Where:

str String, presumed to contain a name.
%out Set to the SOUNDEX code corresponding to str.

Examples

Tthe following fragment will build values for an INVISIBLE KEY field which is the $Sndx value of the field NAME:

UAI OINDEX FOR EACH RECORD FOR I FROM 1 TO NAME(#) ADD NAME_SNDX = #SNDX(NAME(I)) END FOR UNLOAD END FOR

This #function has no cancelling conditions.

#STRIP: Remove leading and/or trailing copies of pad character

The #STRIP function removes leading, trailing, or both, copies of a pad character from a string. It accepts an optional specification of which characters to strip (Leading, Trailing, or Both). It also lets you designate a #STRIP first-argument value to be nullified.

%out = #STRIP(str, [B|L|N|P|T], [pad], [nullval])

Where:

%out Set to a copy of str, with leading, trailing, or both copies of pad removed.
str String to be stripped; required.
B|L|N|P|T Optional indicator of the type of strip; defaults to B:
Any string beginning with...Action
'B...' (uppercase B) Strips Both leading and trailing pad characters.
'L...' (uppercase L) Strips Leading pad characters only.
'N...' (uppercase N) Strips Neither leading characters nor trailing characters. This can be useful if you only want to use #STRIP to replace nullval with the null string.
'P...' (uppercase P) Strips all but one leading Pad character from consecutive leading pad characters.
'T...' (uppercase T) Strips Trailing pad characters only.

The N and P options are available as of version 7.7 of Fast/Unload.

pad The character to be stripped; optional. Blank is the default.
nullval The str value to be output as a null; optional. If the value of str is equal to the value of nullval, #STRIP returns a null string for str.

Available as of version 7.7 of Fast/Unload, you might use nullval for fields that have a "placeholder value" or "default value" that is not actual data.

Examples

#STRIP(' ABC ') returns 'ABC' #STRIP(' ABC ', 'L') returns 'ABC ' #STRIP(' ABC ', 'T') returns ' ABC' #STRIP('000123', 'L', '0') returns '123' #STRIP('000123', 'P', '0') returns '123' #STRIP('000000', 'L', '0') returns '' #STRIP('000000', 'P', '0') returns '0' #STRIP('_123', 'P', , '_') returns '_123' #STRIP('_', 'P', , '_') returns '' #STRIP('__', 'P', , '_') returns '__' #STRIP(' _', 'P', , '_') returns '_' #STRIP(' _', 'N', , '_') returns ' _' #STRIP('_', 'P', , '_') returns '' #STRIP('_', 'N', , '_') returns ''

The Fast/Unload run is cancelled with a return code of 8 when:

  • B|L|N|P|T does not begin with uppercase B, L, N, P, or uppercase T.
  • pad specified and length is not 1.

Notes

#SUBSTR: Substring

The #SUBSTR function returns a substring from within a source string. It expects a source string argument and a numeric byte position within the source string. It accepts an optional numeric maximum length of the output substring. #SUBSTR returns the string that begins at the indicated position of the source string and ends either at the end of the source string or when the supplied maximum length has been reached.

%out = #SUBSTR(str, pos, len)

Where:

str Source string. For Fast/Unload version 4.3 and later. str may be longer than 255 bytes.
pos Beginning position within the source string for the desired substring. Must be numeric and greater than or equal to 1.
len Optional maximum length of substring; default is 255. Must be numeric and greater than or equal to 0.
%out Substring from str starting at position pos with length that is the minimum of len and #LEN(str)+1-pos.

Examples

You might want to get the "right-hand half" of a string (it will be to the right of the middle character if the string length is odd):

%LEN = #LEN(%STR) %RIGHT = %LEN / 2 + 1 /* See note below %RIGHT = #SUBSTR(%STR, %RIGHT)

The Fast/Unload run is cancelled with a return code of 8 when:

  • pos not numeric, or less than 1.
  • len not numeric, or less than 0.

Notes

#TIME: Current time and/or date

The #TIME function returns the current date and time in a datetime string. It accepts an optional datetime format string, with a default that returns just time information. An optional output return code argument allows the FUEL program to intercept error conditions.

%tim = #TIME(fmt, %rc)

Where:

fmt Optional datetime format string for %tim. Defaults to HH:MI:SS.
%rc Return code (optional, output).
%tim Set to datetime string with current date and time, using fmt.

Examples

The following fragment stores the current time in the last occurrence of the REORG_TIME field:

ADD REORG_TIME = #TIME()

Errors

The possible non-zero values of %rc, or terminating conditions, are shown below (see the discussion in Run-time errors during standard #function calls):

4 fmt is not a valid datetime format.

In the event of a run-time error:

  • If you specified a %rc in your #function call, it is set to the number above that corresponds to the error, and %tim is set to MISSING.
  • If %rc is absent, Fast/Unload is cancelled with return code 8.

Notes

  • The only difference between #TIME and #DATE is the default value for fmt.
  • Datetime formats explains valid datetime formats.

#TRANSLATE: Change characters of string using from/to pairings

The #TRANSLATE function returns a copy of the input string, with all characters which are contained in the input table translated to the corresponding characters in the output table. It expects a source string argument, and at least one of three optional string arguments. It accepts optional output table, input table, and pad character (used to extend the output table if it is shorter than the input table).

%out = #TRANSLATE(str, tbl_out, tbl_in, pad)

Where:

str Source string; required.
tbl_out String of "to" characters (optional). Default is null string. Trailing pad characters are added to this string, if needed, so that its length is equal to the length of tbl_in.
tbl_in String of "from" characters, optional. Defaults to 256 characters consisting of all byte values, in order, that is, X'00010203...FCFDFEFF'.
pad Pad character for tbl_out (optional, must be length 1). Default blank.
%out Copy of str, with all characters which are contained in the input table translated to the corresponding characters in the output table.

Examples

#TRANSLATE('ab', 'x', 'b') returns .ax. #TRANSLATE('ab', , '', 'z') returns .ab. #TRANSLATE('ab', , , 'z') returns .zz. #TRANSLATE('ab', 'AB', , 'z') returns .zz. #TRANSLATE('ab', '', , 'z') returns .zz.

The Fast/Unload run is cancelled with a return code of 8 when:

  • Only str argument supplied.
  • pad supplied, and length not 1.

Notes

  • As a consequence of the default rules, if neither tbl_out nor tbl_in are supplied, %out is set to as many copies of pad as #LEN(str).
  • If a character occurs more than once in tbl_in, all instances of it after the first are ignored.
  • As noted, the default tbl_in is a 256 byte string. It is not possible to specify such a value in Fast/Unload. If you want to specify a translation for all 256 characters, you can do the following:

    %TBL_OUT = ... /* A 255 byte value %TBL_FF = ... /* Value that X'FF' translates to %OUT = #TRANSLATE(%STR, %TBL_OUT, , %TBL_FF)

#UPCASE: Change lowercase letters of string to uppercase

The #UPCASE function returns a copy of the input string, with all lowercase EBCDIC letters changed to the corresponding uppercase letters. It expects a source string argument.

%out = #UPCASE(str)

Where:

str Source string; required.
%out Copy of str, with all lowercase EBCDIC letters changed to their uppercase EBCDIC equivalents.

Examples

#UPCASE('?abc') returns '?ABC' #UPCASE('?ABC') returns '?ABC' #UPCASE('') returns ''

Notes

This #function has no cancelling conditions.

#VERPOS: Position in string of character not in or in list

The #VERPOS function scans a search string from an optional starting position and then finds either of these:

  • The first character that is Not in a list of target characters.
  • The first character that Matches a character in a list of target characters.

The function expects a string argument that is searched and a string comprising the target characters. It accepts an optional argument indicating the type of search to perform and an optional position at which to start the search. #VERPOS returns the starting position of the identified character, or 0 as follows:

  • For the Not matched (default) search, returns the position in the search string of the first character not in the target string, or 0 if all characters in the search string are in the target string.
  • For the Matched search, returns the position in the search string of the first character which is in the target string, or 0 if no characters in the search string are in the target string.

%opos = #VERPOS(search, target, NorM, pos)

Where:

search String to be searched.
target String containing set of target characters.
NorM Optional indicator of the type of search being formed:
  • N... (any string beginning with uppercase N): to find position of first character of search not present in target.
  • M... (any string beginning with uppercase M): to find position of first character of search present in target.

Defaults to N.

pos Optional position within search to begin scanning. Must be a positive numeric value, default is 1.
%opos Set to position of first character in search that is not in (N) or that is in (M) target, at or after the position identified by pos.

Examples

#VERPOS('SIRIUS', 'ETANOISHRDLU') returns 0 #VERPOS('HOMER', 'MRH') returns 2 #VERPOS('HOMER', 'MRH', 'M') returns 1 #VERPOS('PLATO', 'AEIOU', , 3) returns 4 #VERPOS('FRED', '', 'N', 2) returns 2 #VERPOS('BETTY', '', , 'M', 3) returns 0 #VERPOS('WILMA', 'AEIOU', 'M', 3) returns 5

The Fast/Unload run is cancelled with a return code of 8 when:

  • NorM does not begin with either uppercase N or uppercase M.
  • pos not numeric, or less than 1.

Notes

  • If search is null, #VERPOS returns 0, as long as the other arguments are not in error. If pos is greater than #LEN(search), #VERPOS returns 0.
  • If search is non-null and target is null, #VERPOS returns 0 if NorM starts with M. Otherwise #VERPOS returns pos.
  • The function that performs this service is usually called "verify", but #VERPOS is used to distinguish it from the SOUL $Verify function:
    • $Verify has only a "Boolean" (0 or 1) return; #VERPOS returns a position or 0 to indicate search "failed."
    • $Verify only has a "nomatch" type of search.
    • $Verify does not have a pos argument.
    • $Verify returns 0 if there is a character in search that is not in target. #VERPOS(Nomatch) returns 0 if there is no such character.
    • $Verify returns "some character in search is not in target" (0) if search is null and target is not null. #VERPOS returns "all characters in search are in target" if search is null, whether or not target is null.

#VIEW204: Value of Model 204 parameter

The #VIEW204 function returns the value of the designated Model 204 parameter.

%out = #VIEW204(param)

Where:

param String containing the name of the parameter; required.

The Fast/Unload run is cancelled with a return code of 8 if the argument is not the name of a Model 204 parameter.

Notes

  • This #function is new in Fast/Unload version 7.7.

#WORD: Return nth blank-delimited word from string

The #WORD function returns the designated delimited word within a string. It requires an input string and a word number within the string. As of version 4.6, it accepts an optional character delimiter to replace the default blank delimiter for separating words.

%out = #WORD(str, word, [delimiter])

Where:

str String containing blank-delimited words; required.
word Number of word within str to return; required. Must be numeric greater than or equal to 1.
delimiter Optional one-character delimiter to separate words within str. The default delimiter is a blank.

This argument is available as of version 4.6 of Fast/Unload.

%out Set to the wordth blank-delimited word within str. If word is greater than the number of words in str, the null string is returned.

Examples

#WORD('A B C', 1) returns 'A' #WORD('A B C', 2) returns 'B' #WORD('A B C', 3) returns 'C' #WORD('A B C', 4) returns '' #WORD(' ', 1) returns '' #WORD('The answer: Rosebud', 2, ':') returns 'Rosebud'

The Fast/Unload run is cancelled with a return code of 8 if:

  • word is not numeric, or less than 1.

Notes

  • The SOUL $Word function also has an optional delimiter character argument, and its "word" argument is the third argument.

#WORDS: Count number of blank-delimited word in string

The #WORDS function returns the number of delimited words in a string. It requires an input string. As of version 4.6, it accepts an optional character delimiter to replace the default blank delimiter for separating words.

%count = #WORDS(str, [delimiter])

Where:

str String containing delimited words; required.
delimiter Optional one-character delimiter to separate words within str. The default delimiter is a blank.

This argument is available as of version 4.6 of Fast/Unload.

%count Set to number of words within str.

Examples

#WORDS('A B C') returns 3 #WORDS('ABC') returns 1 #WORDS(' ') returns 0 #WORDS('The answer: Rosebud', ':') returns 2

This #function has no cancelling conditions.

Notes

  • The SOUL $Words function also has an optional delimiter character argument.

#X2C: Convert hex representation to character string

The #X2C function converts a string of hexadecimal characters (the digits 0-9 and the letters A-F) to the corresponding byte string. Each two characters in the input string become one character in the result string, with a leading 0 added to input strings of odd length.

%str = #X2C(hex)

Where:

hex String to convert; must contain only the characters 0-9 and A-F.

The Fast/Unload run is cancelled with a return code of 8 if hex contains a non-hexadecimal digit character.

%str Set to the string of bytes represented by hex.

Examples

This statement sets %JUNK to the string 123 (EBCDIC X'F1F2F3'):

%JUNK = #X2C('F1F2F3')

This statement sets %JUNK to EBCDIC X'0102', which is a non-displayable string:

%JUNK = #X2C('102')

Notes

  • The inverse of this #function is #C2X.
  • If the number of characters of hex is odd, a leading character 0 is added for the conversion. The SOUL $X2C function requires an even number of characters in hex.
  • The $X2C function returns the null string if hex has an error.
  • The SOUL $IHexA function converts any non-hex characters in hex to 0.

See also