Fast/Unload standard functions: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (argument info from FUEL page)
 
(29 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 40: Line 39:


<tr><th nowrap>argument with "MISSING" value</th>
<tr><th nowrap>argument with "MISSING" value</th>
<td>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.  
<td>If an argument has the <var>[[Fast/Unload Extraction Language (FUEL)#%Variables|MISSING]]</var> 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.  
<p>
<p>
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 <var>CENTSPAN</var> argument and the first argument in the <var>#N<i>x</i>2DATE</var> family.</p></td></tr>
Since the numeric value of <var>MISSING</var> is zero, the <var>MISSING</var> value is not allowed for an argument that may not be zero. Also, the <var>MISSING</var> value is not allowed for some other #function arguments, such as the <var>[[Fast/Unload datetime processing considerations#CENTSPAN|CENTSPAN]]</var> argument and the first argument in the <var>#N<i>x</i>2DATE</var> family (for example, <var>[[##ND2DATE: Convert number of days to datetime string|#ND2DATE]]</var>).</p></td></tr>


<tr><th>#function result</th>
<tr><th>#function result</th>
Line 71: Line 70:
output arguments are copied). </li>
output arguments are copied). </li>


<li>The value of the result is set to "MISSING". </li>
<li>The value of the result is set to <var>MISSING</var>. </li>


<li>During the execution of the #function, the argument values (input
<li>During the execution of the #function, the argument values (input
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:
<ul>
<ul>
<li><var class="product">Fast/Unload</var> treats most errors which the programmer can reasonably
<li><var class="product">Fast/Unload</var> treats most errors that the programmer can reasonably
avoid as serious and
avoid as serious and
terminates the run, if you have not provided for checking of
terminates the run, if you have not provided for checking of
the error. </li>
the error. </li>


<li>At termination, <var class="product">Fast/Unload</var> will issue a message describing
<li>At termination, <var class="product">Fast/Unload</var> issues a message describing
the nature of the error, the input program line number being
the nature of the error, the input program line number being
executed and, if the error occurred during the execution of
executed and, if the error occurred during the execution of
a #function, a dump of the current value of each #function
a #function, a dump of the current value of each #function argument. </li>
argument. </li>
</ul>
</ul>


Line 110: Line 105:
conditions; unless otherwise indicated,
conditions; unless otherwise indicated,
when one of these is set, the #function result
when one of these is set, the #function result
is set to the MISSING value.
is set to the <var>MISSING</var> value.
If you omit the return code argument and there is an error
If you omit the return code argument and there is an error
in the value of an argument, the program is cancelled.
in the value of an argument, the program is cancelled.


For example, since 'ONE WEEK' isn't numeric, the following fragment:
For example, since <code>ONE WEEK</code> isn't numeric, the following fragment:
<p class="code"><nowiki>%NEW_DT = #DATECHG('MM/DD/YY', '01/01/96', 'ONE WEEK',, -
<p class="code"><nowiki>%NEW_DT = #DATECHG('MM/DD/YY', '01/01/96', 'ONE WEEK',, %TST)          
          %TST)
IF %TST NE 0 THEN
IF %TST NE 0 THEN
   REPORT 'Error incrementing date:' AND %TST
   REPORT 'Error incrementing date:' AND %TST
END IF
END IF
</nowiki></p>
</nowiki></p>
will set %NEW_DT to the MISSING value and
sets <code>%NEW_DT</code> to the <var>MISSING</var> value and
will produce the following line on the FUNPRINT dataset:
produces the following line on the <code>FUNPRINT</code> data set:
<p class="code"><nowiki>Error incrementing date: 12
<p class="code">Error incrementing date: 12
</nowiki></p>
</p>
while the following fragment:
The following fragment:
<p class="code"><nowiki> %NEW_DT = #DATECHG('MM/DD/YY', '01/01/96', 'ONE WEEK')
<p class="code">%NEW_DT = #DATECHG('MM/DD/YY', '01/01/96', 'ONE WEEK')
</nowiki></p>
</p>
will cause <var class="product">Fast/Unload</var> to immediately terminate,
causes <var class="product">Fast/Unload</var> to immediately terminate,
issuing an error message that a value is non-numeric, as shown in the
issuing an error message that a value is non-numeric, as shown in the
following sample from FUNPRINT:
following sample from FUNPRINT:
<p class="code"><nowiki>FUNL0053 Unload started.
<p class="output"><nowiki>FUNL0053 Unload started.
FUNL0116 Value is non-numeric or is out of range in line 203; Fast/Unload cancelled.
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.
FUNL0127 Fast/Unload cancelled unloading input record number 0 in file PROCFILE.
Line 145: Line 139:
code" argument, the non-zero values for it.
code" argument, the non-zero values for it.
Notice that, in general, there are no run-time errors for
Notice that, in general, there are no run-time errors for
missing required arguments or too many arguments;
missing required arguments or too many arguments, because such checking is done at compile time.
this is because such checking is done at compile time.
<div id="abdump"></div>
==#ABDUMP: End <var class="product">Fast/Unload</var> with ABEND and dump==
<!--Caution: <div> above-->
   
   
The #ABDUMP function accepts a numeric argument, and causes the
==<b id="abdump"></b>#ABDUMP: End Fast/Unload with ABEND and dump==
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,
producing a dump.
producing a dump.
<p class="code"><nowiki>%junk = #ABDUMP(ccode)
<p class="syntax"><span class="term">%junk</span> = #ABDUMP(<span class="term">ccode</span>)
</nowiki></p>
</p>
Where:
Where:
<table>
<table>
<tr><th>ccode</th><td>Condition code for user ABEND; optional, defaults to 0.</td></tr>
<tr><th>ccode</th>
<tr><th>%junk</th><td>This #function does not return, but the FUEL syntax requires a place to store the #function result.</td></tr>
<td>Condition code for user ABEND; optional, defaults to 0.</td></tr>
 
<tr><th>%junk</th>
<td>This #function does not return a value, but the FUEL syntax requires a place to store the #function result.</td></tr>
</table>
</table>
<p>For example, the following fragment abends the job
<p>
<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>
<p class="code"><nowiki>IF #RECIN EQ 12345
<p class="code">IF #RECIN EQ 12345
   %FOO = #ABDUMP(99)
   %FOO = #ABDUMP(99)
END IF
END IF
</nowiki></p>
</p>


<p><b>Notes</b></p>
<p>
<b>Notes</b></p>
<ul>
<ul>
<li>The purpose of this #function is to assist in problem diagnosis;
<li>The purpose of this #function is to assist in problem diagnosis.
Technical Support will direct you if ever it needs to be used. </li>
[[Contacting Rocket Software Technical Support|Technical Support]] will direct you if ever it needs to be used. </li>
</ul>
</ul>


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==
The <var>#CONCAT</var> function accepts two or more arguments,
<!--Caution: <div> above-->
and it returns a string value that is the concatenation of all of its
The #CONCAT function accepts two or more arguments
and returns a string value that is the concatenation of all of its
arguments.
arguments.
<p class="code"><nowiki>%out = #CONCAT(stra, strb ...)
<p class="syntax"><span class="term">%out</span> = #CONCAT(<span class="term">stra</span>, <span class="term">strb</span> ...)
</nowiki></p>
</p>
Where:
Where:
<table>
<table>
<tr><th>stra</th><td>First input string (required).</td></tr>
<tr><th>stra</th>
<tr><th>strb</th><td>Second input string (required).</td></tr>
<td>First input string (required).</td></tr>
<tr><th>...</th><td>Additional input strings (optional). For versions of <var class="product">Fast/Unload</var> prior to 4.3, total length of all input strings may not exceed 255.</td></tr>
<tr><th>%out</th><td>Concatenation of inputs.</td></tr>
</table>


For example, the following fragment prints the line
<tr><th>strb</th>
<code>Bugs Bunny</code> on the FUNPRINT dataset:
<td>Second input string (required).</td></tr>
<p class="code"><nowiki>%RABBIT = #CONCAT('Bugs', ' ', 'Bunny')
 
REPORT %RABBIT
<tr><th>...</th>
</nowiki></p>
<td>Additional input strings (optional). For versions of <var class="product">Fast/Unload</var> prior to 4.3, total length of all input strings may not exceed 255.</td></tr>
 
<tr><th>%out</th>
<td>Concatenation of inputs.</td></tr>
</table>
<p>
<b>Examples</b>
</p>
The following fragment prints the line <code>Bugs Bunny</code> on the FUNPRINT data set:
<p class="code"><nowiki>%RABBIT = #CONCAT('Bugs', ' ', 'Bunny')
REPORT %RABBIT
</nowiki></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
Line 210: Line 213:
<b>Notes</b></p>
<b>Notes</b></p>
<ul>
<ul>
<li>If the <i>n</i>th argument is present, where <i>n</i> is
<li>If the <var class="term">n</var>th argument is present, where <var class="term">n</var> is
greater than 1, then the <i>n-1</i>st
greater than 1, then the <var class="term">n-1</var>st
argument must be also be present.
argument must be also be present.
That is, the following will result
That is, the following results in a run-time error, because the third argument is absent:
in a run-time error, because the third argument is absent:
<p class="code"><nowiki>%X = #CONCAT(%A, %B, , %D)
<p class="code"><nowiki>%X = #CONCAT(%A, %B, , %D)
</nowiki></p> </li>
</nowiki></p> </li>
Line 220: Line 222:
<li>See [[#concatt|#CONCAT_TRUNC: Concatenate strings, allowing truncation]] if your version of <var class="product">Fast/Unload</var> is earlier than 4.3 and
<li>See [[#concatt|#CONCAT_TRUNC: Concatenate strings, allowing truncation]] if your version of <var class="product">Fast/Unload</var> is earlier than 4.3 and
if you cannot ensure that the total
if you cannot ensure that the total
length of the #CONCAT input strings is less than 256. </li>
length of the <var>#CONCAT</var> input strings is less than 256. </li>
</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
and two or more string arguments,
The #CONCAT_TRUNC function accepts an optional output argument
and it returns a string value that is the concatenation of the string
and two or more string arguments
and returns a string value that is the concatenation of the string
arguments, to a maximum of 255 bytes.
arguments, to a maximum of 255 bytes.
It allows the total length of the string
It allows the total length of the string
arguments to exceed 255, and returns the total length of
arguments to exceed 255, and it returns the total length of
those arguments as the absolute value of the output argument,
those arguments as the absolute value of the output argument,
setting it to a negative value if the length exceeds 255.
setting it to a negative value if the length exceeds 255.
<p class="code"><nowiki>%out = #CONCAT_TRUNC(%lenrc, stra, strb ...)
<p class="syntax"><span class="term">%out</span> = #CONCAT_TRUNC(<span class="term">%lenrc</span>, <span class="term">stra</span>, <span class="term">strb</span> ...)
</nowiki></p>
</p>
Where:
Where:
<table>
<table>
<tr><th>%lenrc</th><td>Optional %variable, set to total length of <i>stra</i>, <i>strb</i>, ..., or to the negative of that length, if it exceeds 255.</td></tr>
<tr><th>%lenrc</th>
<tr><th>stra</th><td>First input string (required).</td></tr>
<td>Optional %variable, set to total length of <i>stra</i>, <i>strb</i>, ..., or to the negative of that length, if it exceeds 255.</td></tr>
<tr><th>strb</th><td>Second input string (required).</td></tr>
 
<tr><th>...</th><td>Additional input strings (optional).</td></tr>
<tr><th>stra</th>
<tr><th>%out</th><td>Concatenation of <i>stra</i>, <i>strb</i>, ..., or the first 255 bytes of that concatenation, if it exceeds 255.</td></tr>
<td>First input string (required).</td></tr>
 
<tr><th>strb</th>
<td>Second input string (required).</td></tr>
 
<tr><th>...</th>
<td>Additional input strings (optional).</td></tr>
 
<tr><th>%out</th>
<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 class="code"><nowiki>%FOO = #CONCAT_TRUNC(%LEN, 'Hello,', -
</p>
  ' ', 'World!')
The following fragment:
<p class="code"><nowiki>%FOO = #CONCAT_TRUNC(%LEN, 'Hello,', ' ', 'World!')  
REPORT %FOO AND 'length is' AND %LEN
REPORT %FOO AND 'length is' AND %LEN
</nowiki></p>
</nowiki></p>
prints the following line
prints the following line on the FUNPRINT dataset:
on the FUNPRINT dataset:
<p class="code"><nowiki>Hello, World! length is 13
<p class="code"><nowiki>Hello, World! length is 13
</nowiki></p>
</nowiki></p>
Line 263: Line 272:
<p><b>Notes</b></p>
<p><b>Notes</b></p>
<ul>
<ul>
<li>If the <i>n</i>th argument is present, where <i>n</i> is
<li>If the <var class="term">n</var>th argument is present, where <var class="term">n</var> is
greater than 2, then the <i>n-1</i>st
greater than 2, then the <var class="term">n-1</var>st
argument must be also be present.
argument must be also be present.
That is, the following will result
That is, the following will result in a run-time error, because the fourth argument is absent:
in a run-time error, because the fourth argument is absent:
<p class="code"><nowiki>%X = #CONCAT_TRUNC(%L, %A, %B, , %D)
<p class="code"><nowiki>%X = #CONCAT_TRUNC(%L, %A, %B, , %D)
</nowiki></p> </li>
</nowiki></p> </li>
Line 274: 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==
The #C2X function expects one required argument and returns a
The <var>#C2X</var> function expects one required argument, and it returns a
string containing the hexadecimal representation of the value in
string containing the hexadecimal representation of the value in
the argument string.
the argument string.
Each byte position of the input string is converted to two characters
Each byte position of the input string is converted to two characters
in the result string, using only the characters <b>0</b>-<b>9</b>
in the result string, using only the characters <code>0</code>-<code>9</code>
and <b>A</b>-<b>F</b>.
and <code>A</code>-<code>F</code>.
<p class="code"><nowiki>%hex = #C2X(str)
<p class="syntax"><span class="term">%hex</span> = #C2X(<span class="term">str</span>)
</nowiki></p>
</p>
Where:
Where:
<table>
<table>
Line 291: 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 <i>str</i> 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 323: Line 332:
and returns the current date and time in the specified (or defaulted)
and returns the current date and time in the specified (or defaulted)
format.
format.
<p class="code">%dat = #DATE(fmt, %rc)
<p class="syntax"><span class="term">%dat</span> = #DATE(<span class="term">fmt</span>, <span class="term">%rc</span>)
</p>
</p>
Where:
Where:
<table>
<table>
<tr><th>fmt</th><td>Optional format for returned date, default is <code>YYYY-MM-DD</code>.</td></tr>
<tr><th>fmt</th>
<tr><th>%rc</th><td>Optional output return code variable.</td></tr>
<td>Optional format for returned date, default is <code>YYYY-MM-DD</code>.</td></tr>
<tr><th>%dat</th><td>Datetime string with indicated format.</td></tr>
 
<tr><th>%rc</th>
<td>Optional output return code variable.</td></tr>
 
<tr><th>%dat</th>
<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()
</p>
</p>
<p>
<b>Errors</b></p>
The possible non-zero values of <var class="term">%rc</var>, or terminating conditions,
are shown below (see the discussion in
[[#funerr|Run-time errors during standard #function calls]]):
<table class="thJustBold">
<tr><th>4</th>
<td><var class="term">fmt</var> is not a valid datetime format.</td></tr>
</table>
In the event of a run-time error:
<ul>
<li>If you specified a <var class="term">%rc</var> in your #function call, it is set to the number above that corresponds to the error,
and <var class="term">%dat</var> is set to <var>MISSING</var>. </li>


Non-zero values of <var class="term">%rc</var>, or terminating conditions,
<li>If <var class="term">%rc</var> is absent, <var class="product">Fast/Unload</var> is cancelled with return code 8. </li>
are shown in the following figure (see the discussion in
</ul>
[[#funerr|Run-time errors during standard #function calls]]).


<b>Errors:</b>
<p><b>Notes</b></p>
if <var class="term">%rc</var> present, set to corresponding number
and set <var class="term">%dat</var> to MISSING; if absent, cancel <var class="product">Fast/Unload</var> with return code 8.
<table>
<tr><th>4</th><td><i>fmt</i> is not a valid datetime format.</td></tr>
</table>
<p><b>Notes</b></p>
<ul>
<ul>
<li>The only difference between #TIME and #DATE is the default value
<li>The only difference between <var>#TIME</var> and <var>#DATE</var> is the default value
for <var class="term">fmt</var>. </li>
for <var class="term">fmt</var>. </li>


<li>The default format returned by the
<li>The default format returned by the
SOUL <var>[[$Date]]</var> and <var>[[$Sir_Date]]</var> functions is "YY&ndash;MM&ndash;DD";
SOUL <var>[[$Date]]</var> and <var>[[$Sir_Date]]</var> functions is <code>YY&ndash;MM&ndash;DD</code>;
the default format returned by #DATE is "YYYY&ndash;MM&ndash;DD". </li>
the default format returned by <var>#DATE</var> is <code>YYYY&ndash;MM&ndash;DD</code>. </li>


<li>[[Fast/Unload datetime processing considerations#dtfmt|Datetime formats]] explains valid datetime formats.
<li>[[Fast/Unload datetime processing considerations#dtfmt|Datetime formats]] explains valid datetime formats. </li>
</ul>
</ul>


==#DATECHG: Add some days to datetime==
==#DATECHG: Add some days to datetime==
The #DATECHG function adds a specified number of days to an input
The <var>#DATECHG</var> function adds a specified number of days to an input
datetime, returning the incremented datetime.
datetime, returning the incremented datetime.
It requires a datetime format argument, a datetime value, and a signed
It requires a datetime format argument, a datetime value, and a signed
number of days.
number of days.
It accepts an optional CENTSPAN value for interpreting datetimes with two
It accepts an optional <var>[[Fast/Unload datetime processing considerations#cspan|CENTSPAN]]</var> value for interpreting datetimes with two-digit years.
digit years.
The incremented datetime is returned in the same format as the input
The incremented datetime is returned in the same format as the input
datetime.
datetime.
Line 375: Line 395:
Where:
Where:
<table>
<table>
<tr><th>fmt</th><td>Format of <var class="term">dat</var> and <var class="term">%odat</var>.</td></tr>
<tr><th>fmt</th>
<tr><th>dat</th><td>Datetime string.</td></tr>
<td>Format of <var class="term">dat</var> and <var class="term">%odat</var>.</td></tr>
<tr><th>n</th><td>Number of days to add to <var class="term">dat</var>.</td></tr>
 
<tr><th>span</th><td>Optional <var>CENTSPAN</var> value.</td></tr>
<tr><th>dat</th>
<tr><th>%rc</th><td>Return code variable (optional, output).</td></tr>
<td>Datetime string.</td></tr>
<tr><th>%odat</th><td>Set to <var class="term">dat</var> plus <var class="term">n</var> days.</td></tr>
 
<tr><th>n</th>
<td>Number of days to add to <var class="term">dat</var>.</td></tr>
 
<tr><th>span</th>
<td>Optional <var>CENTSPAN</var> value.</td></tr>
 
<tr><th>%rc</th>
<td>Return code variable (optional, output).</td></tr>
 
<tr><th>%odat</th>
<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"><nowiki>%X = #DATE('DAY Month, YYYY')
<p class="code">%X = #DATE('DAY Month, YYYY')
%X = #DATECHG('DAY Month, YYYY', %X, 7)
%X = #DATECHG('DAY Month, YYYY', %X, 7)
REPORT %X
REPORT %X
</nowiki></p>
</p>
<p>
<b>Errors</b></p>
The possible non-zero values of <var class="term">%rc</var>, or terminating conditions,
are shown below (see the discussion in [[#funerr|Run-time errors during standard #function calls]]):
<table class="thJustBold">
<tr><th>4</th>
<td><var class="term">fmt</var> is not a valid datetime format.</td></tr>


Non-zero values of <i>%rc</i>, or terminating conditions,
<tr><th>8</th>
are shown in the following figure (see the discussion in
<td><var class="term">dat</var> does not match <var class="term">fmt</var> or result date out of range.</td></tr>
[[#funerr|Run-time errors during standard #function calls]]).


<b>Errors:</b>
<tr><th>12</th>
If <var class="term">%rc</var> present, set to corresponding number
<td><var class="term">n</var> is not a number or <var class="term">span</var> is invalid.</td></tr>
and set <var class="term">%odat</var> to MISSING. If absent, cancel <var class="product">Fast/Unload</var> with return code 8.
<table>
<tr><th>4</th><td><var class="term">fmt</var> is not a valid datetime format.</td></tr>
<tr><th>8</th><td><var class="term">dat</var> does not match <var class="term">fmt</var> or result date out of range.</td></tr>
<tr><th>12</th><td><var class="term">n</var> is not a number or <var class="term">span</var> is invalid.</td></tr>
</table>
</table>
In the event of a run-time error:
<ul>
<li>If you specified a <var class="term">%rc</var> in your #function call, it is set to the number above that corresponds to the error, and <var class="term">%odat</var> is set to <var>MISSING</var>. </li>
<li>If <var class="term">%rc</var> is absent, <var class="product">Fast/Unload</var> is cancelled with return code 8. </li>
</ul>
<p>
<p>
<b>Notes</b></p>
<b>Notes</b></p>
<ul>
<ul>
<li>[[Fast/Unload datetime processing considerations#dtfmt|Datetime formats]] explains valid datetime formats and valid dates. </li>
<li>[[Fast/Unload datetime processing considerations#dtfmt|Datetime formats]] explains valid datetime formats and valid dates. </li>
<li>[[Fast/Unload datetime processing considerations#cspan|CENTSPAN]] explains <var>CENTSPAN</var> arguments. </li>


<li>The SOUL <var>[[$DateChg]]</var> function does not provide a call-level
<li>The SOUL <var>[[$DateChg]]</var> function does not provide a call-level
argument for interpreting two-digit years, the thread-level CENTSPLT/DEFCENT
argument for interpreting two-digit years, the thread-level <var>CENTSPLT</var>/<var>DEFCENT</var>
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 CENTSPAN argument in the same fashion as #DATECHG. </li>
provides a <var>CENTSPAN</var> argument in the same fashion as <var>#DATECHG</var>. </li>
</ul>
</ul>


==#DATECHK: Check if datetime matches format==
==#DATECHK: Check if datetime matches format==
The #DATECHK function verifies that a specific datetime value is valid
The <var>#DATECHK</var> function verifies that a specific datetime value is valid
for a given datetime format.
for a given datetime format.
It requires a datetime format argument and a datetime value.
It requires a datetime format argument and a datetime value.
It accepts an optional CENTSPAN value for interpreting datetimes with two
It accepts an optional <var>[[Fast/Unload datetime processing considerations#cspan|CENTSPAN]]</var> value for interpreting datetimes with two-digit years.
digit years.
An optional output return code argument allows the FUEL program to
An optional output return code argument allows the FUEL program to
intercept error conditions.
intercept error conditions.
The #DATECHK function returns 1 if all arguments are valid and consistent,
The <var>#DATECHK</var> function returns 1 if all arguments are valid and consistent,
else 0 if all arguments are valid except for the date.
else 0 if all arguments are valid except for the date.
<p class="syntax"><span class="term">%tst</span> = #DATECHK(<span class="term">fmt, dat, span, %rc</span>)
<p class="syntax"><span class="term">%tst</span> = #DATECHK(<span class="term">fmt, dat, span, %rc</span>)
Line 447: 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 462: Line 500:
[[#funerr|Run-time errors during standard #function calls]]).
[[#funerr|Run-time errors during standard #function calls]]).


<b>Errors:</b>
<table class="thJustBold">
If <var class="term">%rc</var> present, set to corresponding number
and set <var class="term">%tst</var> to MISSING. If absent, cancel <var class="product">Fast/Unload</var> with return code 8.
<table>
<tr><th>4</th>
<tr><th>4</th>
<td><var class="term">Fmt</var> is not a valid datetime format.</td></tr>
<td><var class="term">Fmt</var> is not a valid datetime format.</td></tr>


<tr><th>12</th>
<tr><th>12</th>
<td><var class="term">span</var> is an invalid CENTSPAN value.</td></tr>
<td><var class="term">span</var> is an invalid <var>CENTSPAN</var> value.</td></tr>
</table>
</table>
<p>
<p>
Line 477: Line 511:
<ul>
<ul>
<li>[[Fast/Unload datetime processing considerations#dtfmt|Datetime formats]] explains valid datetime formats and valid dates. </li>
<li>[[Fast/Unload datetime processing considerations#dtfmt|Datetime formats]] explains valid datetime formats and valid dates. </li>
<li>[[Fast/Unload datetime processing considerations#cspan|CENTSPAN]] explains <var>CENTSPAN</var> arguments. </li>


<li>The SOUL <var>[[$DateChk]]</var> function does not provide a call-level argument
<li>The SOUL <var>[[$DateChk]]</var> function does not provide a call-level argument
Line 484: Line 516:
used instead. </li>
used instead. </li>


<li>The <var class="product">SOUL</var> <var>$Sir_DateChk</var> function provides a CENTSPAN
<li>The <var class="product">SOUL</var> <var>$Sir_DateChk</var> function provides a <var>CENTSPAN</var>
argument in the same fashion as #DATECHK.
argument in the same fashion as <var>#DATECHK</var>.
</ul>
</ul>


==#DATECNV: Convert datetime to different format==
==#DATECNV: Convert datetime to different format==
The #DATECNV function converts a datetime value from one datetime
The <var>#DATECNV</var> function converts a datetime value from one datetime
format to another datetime format.
format to another datetime format.
It requires an input datetime value, a corresponding input datetime format
It requires an input datetime value, a corresponding input datetime format
string, and an output datetime format string.
string, and an output datetime format string.
It accepts an optional CENTSPAN value for interpreting datetimes with two
It accepts an optional <var>[[Fast/Unload datetime processing considerations#cspan|CENTSPAN]]</var> value for interpreting datetimes with two-digit years.
digit years.
An optional output return code argument allows the FUEL program to
An optional output return code argument allows the FUEL program to
intercept error conditions.
intercept error conditions.
The #DATECNV function returns the input datetime value in the format specified
The <var>#DATECNV</var> function returns the input datetime value in the format specified
by the output datetime format string.
by the output datetime format string.
<p class="syntax"><span class="term">%odat</span> = #DATECNV(<span class="term">infmt, outfmt, dat, span, %rc</span>)
<p class="syntax"><span class="term">%odat</span> = #DATECNV(<span class="term">infmt, outfmt, dat, span, %rc</span>)
Line 521: 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
</p>
</p>
 
<p>
Non-zero values of <var class="term">%rc</var>, or terminating conditions,
<b>Errors</b></p>
are shown in the following figure (see the discussion in
The possible non-zero values of <var class="term">%rc</var>, or terminating conditions,
[[#funerr|Run-time errors during standard #function calls]]).
are shown below (see the discussion in [[#funerr|Run-time errors during standard #function calls]]):
 
<table class="thJustBold">
<b>Errors:</b>
If <var class="term">%rc</var> present, set to corresponding number
and set <var class="term">%odat</var> to MISSING.
If absent, cancel <var class="product">Fast/Unload</var> with return code 8.
<table>
<tr><th>4</th>
<tr><th>4</th>
<td><i>infmt</i> or <var class="term">outfmt</var> is not a valid datetime format.</td></tr>
<td><var class="term">infmt</var> or <var class="term">outfmt</var> is not a valid datetime format.</td></tr>


<tr><th>8</th>
<tr><th>8</th>
<td><i>dat</i> does not match <var class="term">infmt</var>.</td></tr>
<td><var class="term">dat</var> does not match <var class="term">infmt</var>.</td></tr>


<tr><th>12</th>
<tr><th>12</th>
<td><i>span</i> is an invalid CENTSPAN value.</td></tr>
<td><var class="term">span</var> is an invalid <var>CENTSPAN</var> value.</td></tr>


<tr><th>16</th>
<tr><th>16</th>
<td>Converted datetime value out of range for <var class="term">%outfmt</var>.</td></tr>
<td>Converted datetime value out of range for <var class="term">%outfmt</var>.</td></tr>
</table>
</table>
In the event of a run-time error:
<ul>
<li>If you specified a <var class="term">%rc</var> in your #function call, it is set to the number above that corresponds to the error, and <var class="term">%odat</var> is set to <var>MISSING</var>. </li>
<li>If <var class="term">%rc</var> is absent, <var class="product">Fast/Unload</var> is cancelled with return code 8. </li>
</ul>
<p>
<p>
<b>Notes</b></p>
<b>Notes</b></p>
<ul>
<ul>
<li>[[Fast/Unload datetime processing considerations#dtfmt|Datetime formats]] explains valid datetime formats and valid dates. </li>
<li>[[Fast/Unload datetime processing considerations#dtfmt|Datetime formats]] explains valid datetime formats and valid dates. </li>
<li>[[Fast/Unload datetime processing considerations#cspan|CENTSPAN]] explains <var>CENTSPAN</var> arguments. </li>
</ul>
</ul>


==#DATEDIF: Difference between two dates==
==#DATEDIF: Difference between two dates==
The #DATEDIF function subtracts a second date from a first date and
The <var>#DATEDIF</var> function subtracts a second date from a first date and
returns the difference in days, ignoring time portions for both dates.
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
It requires a first datetime format string, a first datetime value, and a second
datetime value.
datetime value.
It accepts an optional second datetime format string and an optional CENTSPAN
It accepts an optional second datetime format string and an optional <var>[[Fast/Unload datetime processing considerations#cspan|CENTSPAN]]</var>
value for interpreting datetimes with two digit years.
value for interpreting datetimes with two-digit years.
An optional output return code argument allows the FUEL program to
An optional output return code argument allows the FUEL program to
intercept error conditions.
intercept error conditions.
<p class="code"><nowiki>%dif = #DATEDIF(fmta, data, fmtb, datb, -
<p class="syntax"><span class="term">%dif</span> = #DATEDIF(<span class="term">fmta, data, fmtb, datb, span, %rc</span>)
                span, %rc)
</p>
</nowiki></p>
Where:
Where:
<table>
<table>
<tr><th>fmta</th><td>Datetime format string for <i>data</i>.</td></tr>
<tr><th>fmta</th>
<tr><th>data</th><td>First datetime string.</td></tr>
<td>Datetime format string for <var class="term">data</var>.</td></tr>
<tr><th>fmtb</th><td>Optional second datetime format string for <i>datb</i>. Default is to use <i>fmta</i>.</td></tr>
<tr><th>datb</th><td>Second datetime string.</td></tr>
<tr><th>span</th><td>Optional <b>CENTSPAN</b> value.</td></tr>
<tr><th>%rc</th><td>Return code variable (optional, output).</td></tr>
<tr><th>%dif</th><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>


For example, the following fragment prints the string <code>7 days</code>
<tr><th>data</th>
on the FUNPRINT dataset:
<td>First datetime string.</td></tr>
<p class="code"><nowiki>%X = #DATEDIF('YYMMDD', '970308', , '970301')
REPORT %X AND 'days'
</nowiki></p>


Non-zero values of <i>%rc</i>, or terminating conditions,
<tr><th>fmtb</th>
are shown in the following figure (see the discussion in
<td>Optional second datetime format string for <var class="term">datb</var>. Default is to use <var class="term">fmta</var>.</td></tr>
[[#funerr|Run-time errors during standard #function calls]]).


<b>Errors:</b>
<tr><th>datb</th>
if <i>%rc</i> present, set to corresponding number
<td>Second datetime string.</td></tr>
and set <i>%dif</i> to MISSING;
if absent, cancel <var class="product">Fast/Unload</var> with return code 8.
<table>
<tr><th>4</th><td><i>fmta</i> or <i>fmtb</i> is not a valid datetime format.</td></tr>
<tr><th>8</th><td><i>data</i> does not match <i>fmta</i>, or <i>datb</i> does not match <i>fmtb</i>.</td></tr>
<tr><th>12</th><td><i>span</i> is an invalid CENTSPAN value.</td></tr>
</table>
<p><b>Notes</b></p>
<ul>
<li>Time is ignored in the subtraction. </li>


<li>In the example above, even though the input dates have 2-digit years,
<tr><th>span</th>
there is no need for a <i>span</i> argument, since the dates are
<td>Optional <var>CENTSPAN</var> value.</td></tr>
in the same year. </li>


<li>As in the SOUL $DATEDIF function,
<tr><th>%rc</th>
the single <b>span</b> argument is used for
<td>Return code variable (optional, output).</td></tr>
both dates; if it is necessary to get the difference between two
dates which both have 2-digit years and are in different 100-year
windows, you must first use #DATECNV to convert one of them to some
4-digit year format. </li>


<li>[[Fast/Unload datetime processing considerations#dtfmt|Datetime formats]] explains valid datetime formats and valid dates. </li>
<tr><th>%dif</th>
 
<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>
<li>[[Fast/Unload datetime processing considerations#cspan|CENTSPAN]] explains <b>CENTSPAN</b> arguments. </li>
</table>
<p>
<b>Examples</b>
</p>
The following fragment prints the string <code>7 days</code>
on the FUNPRINT dataset:
<p class="code">%X = #DATEDIF('YYMMDD', '970308', , '970301')
REPORT %X AND 'days'
</p>
 
<p>
<b>Errors</b></p>
The possible non-zero values of <var class="term">%rc</var>, or terminating conditions,
are shown below (see the discussion in [[#funerr|Run-time errors during standard #function calls]]):
<table class="thJustBold">
<tr><th>4</th>
<td><var class="term">fmta</var> or <var class="term">fmtb</var> is not a valid datetime format.</td></tr>
 
<tr><th>8</th>
<td><var class="term">data</var> does not match <var class="term">fmta</var>, or <var class="term">datb</var> does not match <var class="term">fmtb</var>.</td></tr>
 
<tr><th>12</th>
<td><var class="term">span</var> is an invalid <var>CENTSPAN</var> value.</td></tr>
</table>
In the event of a run-time error:
<ul>
<li>If you specified a <var class="term">%rc</var> in your #function call, it is set to the number above that corresponds to the error, and <var class="term">%dif</var> is set to <var>MISSING</var>. </li>
 
<li>If <var class="term">%rc</var> is absent, <var class="product">Fast/Unload</var> is cancelled with return code 8. </li>
</ul>
<p>
<b>Notes</b></p>
<ul>
<li>Time is ignored in the subtraction. </li>
 
<li>In the example above, even though the input dates have two-digit years,
there is no need for a <var class="term">span</var> argument, since the dates are
in the same year. </li>
 
<li>As in the SOUL <var>$DATEDIF</var> function,
the single <var class="term">span</var> 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 <var>#DATECNV</var> to convert one of them to some
four-digit year format. </li>
 
<li>[[Fast/Unload datetime processing considerations#dtfmt|Datetime formats]] explains valid datetime formats and valid dates. </li>
</ul>
</ul>


==#DATEFMT: Validate datetime format string==
==#DATEFMT: Validate datetime format string==
The #DATEFMT function is used to validate a datetime format string.
The <var>#DATEFMT</var> function is used to validate a datetime format string.
It requires 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 1 if the datetime format string is valid, else
it returns a value of 0.
it returns a value of 0.
<p class="code"><nowiki>%tst = #DATEFMT(fmt)
<p class="code"><span class="term">%tst</span> = #DATEFMT(<span class="term">fmt</span>)
</nowiki></p>
</p>
Where:
Where:
<table>
<table>
Line 633: 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 651: Line 702:


==#DATE2N: Convert datetime string to number of seconds*300==
==#DATE2N: Convert datetime string to number of seconds*300==
The #DATE2N function converts a datetime value in a string format into
The <var>#DATE2N</var> function converts a datetime value in a string format into
a numeric form that is the corresponding number of seconds*300 since
a numeric form that is the corresponding number of <code>seconds*300</code> since
January 1, 1900.
January 1, 1900.
It requires a datetime value string and a corresponding datetime
It requires a datetime value string and a corresponding datetime format string.
format string.
It accepts an optional <var>[[Fast/Unload datetime processing considerations#cspan|CENTSPAN]]</var> value for interpreting datetimes with two-digit years.
It accepts an optional CENTSPAN value for interpreting datetimes with
two digit years.
An optional output return code argument allows the FUEL program to
An optional output return code argument allows the FUEL program to
intercept error conditions.
intercept error conditions.
<p class="code"><nowiki>%num = #DATE2N(dat, fmt, span, %rc)
<p class="syntax"><span class="term">%num</span> = #DATE2N(<span class="term">dat, fmt, span, %rc</span>)
</nowiki></p>
</p>
Where:
Where:
<table>
<table>
<tr><th>dat</th><td>Datetime value string.</td></tr>
<tr><th>dat</th>
<tr><th>fmt</th><td>Datetime format string for <i>dat</i>.</td></tr>
<td>Datetime value string.</td></tr>
<tr><th>span</th><td>Optional <b>CENTSPAN</b> value.</td></tr>
 
<tr><th>%rc</th><td>Return code variable (optional, output).</td></tr>
<tr><th>fmt</th>
<tr><th>%num</th><td>Set to the number of seconds*300 since 1 Jan 1900 12:00 AM that corresponds to the datetime value of <i>dat</i>.</td></tr>
<td>Datetime format string for <i>dat</i>.</td></tr>
 
<tr><th>span</th>
<td>Optional <var>CENTSPAN</var> value.</td></tr>
 
<tr><th>%rc</th>
<td>Return code variable (optional, output).</td></tr>
 
<tr><th>%num</th>
<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 678: Line 738:
END IF
END IF
</nowiki></p>
</nowiki></p>
<p>
<b>Errors</b></p>
The possible non-zero values of <var class="term">%rc</var>, or terminating conditions,
are shown below (see the discussion in [[#funerr|Run-time errors during standard #function calls]]):
<table class="thJustBold">
<tr><th>4</th>
<td><var class="term">fmt</var> is not a valid datetime format.</td></tr>


Non-zero values of <i>%rc</i>, or terminating conditions,
<tr><th>8</th>
are shown in the following figure (see the discussion in
<td><var class="term">dat</var> does not match <var class="term">fmt</var> or result date out of range.</td></tr>
[[#funerr|Run-time errors during standard #function calls]]).


<b>Errors:</b>
<tr><th>12</th>
if <i>%rc</i> present, set to corresponding number
<td><var class="term">span</var> is an invalid <var>CENTSPAN</var> value.</td></tr>
and set <i>%num</i> to MISSING;
if absent, cancel <var class="product">Fast/Unload</var> with return code 8.
<table>
<tr><th>4</th><td><i>fmt</i> is not a valid datetime format.</td></tr>
<tr><th>8</th><td><i>dat</i> does not match <i>fmt</i> or result date out of range.</td></tr>
<tr><th>12</th><td><i>span</i> is an invalid CENTSPAN value.</td></tr>
</table>
</table>
<p><b>Notes</b></p>
In the event of a run-time error:
<ul>
<ul>
<li>Values returned by #DATE2N </li>
<li>If you specified a <var class="term">%rc</var> in your #function call, it is set to the number above that corresponds to the error, and <var class="term">%num</var> is set to <var>MISSING</var>. </li>


will often exceed the range that can be represented
<li>If <var class="term">%rc</var> is absent, <var class="product">Fast/Unload</var> is cancelled with return code 8. </li>
</ul>
<p>
<b>Notes</b></p>
<ul>
<li>Values returned by <var>#DATE2N</var> often exceed the range that can be represented
in a 4-byte integer, so you should probably avoid storing the
in a 4-byte integer, so you should probably avoid storing the
value in a BINARY or FLOAT4 field. </li>
value in a <var>BINARY</var> or <var>FLOAT4</var> field. </li>


<li>Dates prior to 1 January 1900 will return a negative number. </li>
<li>Dates prior to 1 January 1900 will return a negative number. </li>


<li>The inverse of this #function is #N2DATE. </li>
<li>The inverse of this #function is <var>[[##N2DATE: Convert number of seconds*300 to datetime string|#N2DATE]]</var>. </li>


<li>[[Fast/Unload datetime processing considerations#dtfmt|Datetime formats]] explains valid datetime formats and valid dates. </li>
<li>[[Fast/Unload datetime processing considerations#dtfmt|Datetime formats]] explains valid datetime formats and valid dates. </li>
<li>[[Fast/Unload datetime processing considerations#cspan|CENTSPAN]] explains <b>CENTSPAN</b> arguments.
</ul>
</ul>


==#DATE2ND: Convert datetime string to number of days==
==#DATE2ND: Convert datetime string to number of days==
The #DATE2ND function converts a datetime value in a string format into
The <var>#DATE2ND</var> function converts a datetime value in a string format into
a numeric form that is the corresponding number of days since
a numeric form that is the corresponding number of days since January 1, 1900.
January 1, 1900.
It requires a datetime value string and a corresponding datetime format string.
It requires a datetime value string and a corresponding datetime
It accepts an optional <var>[[Fast/Unload datetime processing considerations#cspan|CENTSPAN]]</var> value for interpreting datetimes with two-digit years.
format string.
An optional output return code argument allows the FUEL program to intercept error conditions.
It accepts an optional CENTSPAN value for interpreting datetimes with
<p class="syntax"><span class="term">%num</span> = #DATE2ND(<span class="term">dat, fmt, span, %rc</span>)
two digit years.
</p>
An optional output return code argument allows the FUEL program to
intercept error conditions.
<p class="code"><nowiki>%num = #DATE2ND(dat, fmt, span, %rc)
</nowiki></p>
Where:
Where:
<table>
<table>
<tr><th>dat</th><td>Datetime value string.</td></tr>
<tr><th>dat</th>
<tr><th>fmt</th><td>Datetime format string for <i>dat</i>.</td></tr>
<td>Datetime value string.</td></tr>
<tr><th>span</th><td>Optional <b>CENTSPAN</b> value.</td></tr>
<tr><th>%rc</th><td>Return code variable (optional, output).</td></tr>
<tr><th>%num</th><td>Set to the number of days since 1 Jan 1900 12:00 AM that corresponds to the datetime value of <i>dat</i>.</td></tr>
</table>


For example, the following fragment prints the value <code>BEFORE</code>
<tr><th>fmt</th>
on the FUNPRINT dataset:
<td>Datetime format string for <var class="term">dat</var>.</td></tr>
<p class="code"><nowiki>IF #DATE2ND('121494', 'MMDDYY') < -
          #DATE2ND('040195', 'MMDDYY') THEN
  REPORT 'BEFORE'
END IF
</nowiki></p>


Non-zero values of <i>%rc</i>, or terminating conditions,
<tr><th>span</th>
are shown in the following figure (see the discussion in
<td>Optional <var>CENTSPAN</var> value.</td></tr>
[[#funerr|Run-time errors during standard #function calls]]).


<b>Errors:</b>
<tr><th>%rc</th>
if <i>%rc</i> present, set to corresponding number
<td>Return code variable (optional, output).</td></tr>
and set <i>%num</i> to MISSING;
if absent, cancel <var class="product">Fast/Unload</var> with return code 8.
<table>
<tr><th>4</th><td><i>fmt</i> is not a valid datetime format.</td></tr>
<tr><th>8</th><td><i>dat</i> does not match <i>fmt</i> or result date out of range.</td></tr>
<tr><th>12</th><td><i>span</i> is an invalid CENTSPAN value.</td></tr>
</table>
<p><b>Notes</b></p>
<ul>
<li>Dates prior to 1 January 1900 will return a negative number. </li>
<li>The inverse of this #function is #ND2DATE. </li>
<li>[[Fast/Unload datetime processing considerations#dtfmt|Datetime formats]] explains valid datetime formats and valid dates. </li>
<li>[[Fast/Unload datetime processing considerations#cspan|CENTSPAN]] explains <b>CENTSPAN</b> arguments. </li>
</ul>


==#DATE2NM: Convert datetime string to number of milliseconds==
<tr><th>%num</th>
The #DATE2NM function converts a datetime value in a string format into
<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>
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.
<p class="code"><nowiki>%num = #DATE2NM(dat, fmt, span, %rc)
</nowiki></p>
Where:
<table>
<tr><th>dat</th><td>Datetime value string.</td></tr>
<tr><th>fmt</th><td>Datetime format string for <i>dat</i>.</td></tr>
<tr><th>span</th><td>Optional <b>CENTSPAN</b> value.</td></tr>
<tr><th>%rc</th><td>Return code variable (optional, output).</td></tr>
<tr><th>%num</th><td>Set to the number of milliseconds since 1 Jan 1900 12:00 AM that corresponds to the datetime value of <i>dat</i>.</td></tr>
</table>
</table>
 
<p>
For example, the following fragment prints the value 'BEFORE'
<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') < -
<p class="code">IF #DATE2ND('121494', 'MMDDYY') < #DATE2ND('040195', 'MMDDYY') THEN
          #DATE2NM('040195', 'MMDDYY') THEN
   REPORT 'BEFORE'
   REPORT 'BEFORE'
END IF
END IF
</nowiki></p>
</p>
 
<p>
Non-zero values of <i>%rc</i>, or terminating conditions,
<b>Errors</b></p>
are shown in the following figure (see the discussion in
The possible non-zero values of <var class="term">%rc</var>, or terminating conditions,
[[#funerr|Run-time errors during standard #function calls]]).
are shown below (see the discussion in [[#funerr|Run-time errors during standard #function calls]]):
<table class="thJustBold">
<tr><th>4</th>
<td><i>fmt</i> is not a valid datetime format.</td></tr>
 
<tr><th>8</th>
<td><var class="term">dat</var> does not match <var class="term">fmt</var> or result date out of range.</td></tr>


<b>Errors:</b>
<tr><th>12</th>
if <i>%rc</i> present, set to corresponding number
<td><var class="term">span</var> is an invalid <var>CENTSPAN</var> value.</td></tr>
and set <i>%num</i> to MISSING;
if absent, cancel <var class="product">Fast/Unload</var> with return code 8.
<table>
<tr><th>4</th><td><i>fmt</i> is not a valid datetime format.</td></tr>
<tr><th>8</th><td><i>dat</i> does not match <i>fmt</i> or result date out of range.</td></tr>
<tr><th>12</th><td><i>span</i> is an invalid CENTSPAN value.</td></tr>
</table>
</table>
<p><b>Notes</b></p>
In the event of a run-time error:
<ul>
<ul>
<li>Values returned by #DATE2NM
<li>If you specified a <var class="term">%rc</var> in your #function call, it is set to the number above that corresponds to the error, and <var class="term">%num</var> is set to <var>MISSING</var>. </li>
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. </li>


<li>If <var class="term">%rc</var> is absent, <var class="product">Fast/Unload</var> is cancelled with return code 8. </li>
</ul>
<p>
<b>Notes</b></p>
<ul>
<li>Dates prior to 1 January 1900 will return a negative number. </li>
<li>Dates prior to 1 January 1900 will return a negative number. </li>


<li>The inverse of this #function is #NM2DATE. </li>
<li>The inverse of this #function is <var>[[#ND2DATE: Convert number of days to datetime string|#ND2DATE]]</var>. </li>


<li>[[Fast/Unload datetime processing considerations#dtfmt|Datetime formats]] explains valid datetime formats and valid dates. </li>
<li>[[Fast/Unload datetime processing considerations#dtfmt|Datetime formats]] explains valid datetime formats and valid dates. </li>
<li>[[Fast/Unload datetime processing considerations#cspan|CENTSPAN]] explains <b>CENTSPAN</b> arguments.
</ul>
</ul>


==#DATE2NS: Convert datetime string to number of seconds==
==#DATE2NM: Convert datetime string to number of milliseconds==
The #DATE2NS function converts a datetime value in a string format into
The <var>#DATE2NM</var> function converts a datetime value in a string format into
a numeric form that is the corresponding number of seconds since
a numeric form that is the corresponding number of milliseconds since January 1, 1900.
January 1, 1900.
It requires a datetime value string and a corresponding datetime format string.
It requires a datetime value string and a corresponding datetime
It accepts an optional <var>[[Fast/Unload datetime processing considerations#cspan|CENTSPAN]]</var> value for interpreting datetimes with two-digit years.
format string.
An optional output return code argument allows the FUEL program to intercept error conditions.
It accepts an optional CENTSPAN value for interpreting datetimes with
<p class="syntax"><span class="term">%num</span> = #DATE2NM(<span class="term">dat, fmt, span, %rc</span>)
two digit years.
</p>
An optional output return code argument allows the FUEL program to
intercept error conditions.
<p class="code"><nowiki>%num = #DATE2NS(dat, fmt, span, %rc)
</nowiki></p>
Where:
Where:
<table>
<table>
<tr><th>dat</th><td>Datetime value string.</td></tr>
<tr><th>dat</th>
<tr><th>fmt</th><td>Datetime format string for <i>dat</i>.</td></tr>
<td>Datetime value string.</td></tr>
<tr><th>span</th><td>Optional <b>CENTSPAN</b> value.</td></tr>
 
<tr><th>%rc</th><td>Return code variable (optional, output).</td></tr>
<tr><th>fmt</th>
<tr><th>%num</th><td>Set to the number of seconds since 1 Jan 1900 12:00 AM that corresponds to the datetime value of <i>dat</i>.</td></tr>
<td>Datetime format string for <var class="term">dat</var>.</td></tr>
 
<tr><th>span</th>
<td>Optional <var>CENTSPAN</var> value.</td></tr>
 
<tr><th>%rc</th>
<td>Return code variable (optional, output).</td></tr>
 
<tr><th>%num</th>
<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 'BEFORE'
<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 #DATE2NS('121494', 'MMDDYY') < -
<p class="code"><nowiki>IF #DATE2NM('121494', 'MMDDYY') < #DATE2NM('040195', 'MMDDYY') THEN
          #DATE2NS('040195', 'MMDDYY') THEN
   REPORT 'BEFORE'
   REPORT 'BEFORE'
END IF
END IF
</nowiki></p>
</nowiki></p>


Non-zero values of <i>%rc</i>, or terminating conditions,
<p>
are shown in the following figure (see the discussion in
<b>Errors</b></p>
[[#funerr|Run-time errors during standard #function calls]]).
The possible non-zero values of <var class="term">%rc</var>, or terminating conditions,
are shown below (see the discussion in [[#funerr|Run-time errors during standard #function calls]]):
<table class="thJustBold">
<tr><th>4</th>
<td><i>fmt</i> is not a valid datetime format.</td></tr>
 
<tr><th>8</th>
<td><var class="term">dat</var> does not match <var class="term">fmt</var> or result date out of range.</td></tr>


<b>Errors:</b>
<tr><th>12</th>
if <i>%rc</i> present, set to corresponding number
<td><var class="term">span</var> is an invalid <var>CENTSPAN</var> value.</td></tr>
and set <i>%num</i> to MISSING;
if absent, cancel <var class="product">Fast/Unload</var> with return code 8.
<table>
<tr><th>4</th><td><i>fmt</i> is not a valid datetime format.</td></tr>
<tr><th>8</th><td><i>dat</i> does not match <i>fmt</i> or result date out of range.</td></tr>
<tr><th>12</th><td><i>span</i> is an invalid CENTSPAN value.</td></tr>
</table>
</table>
<p><b>Notes</b></p>
In the event of a run-time error:
<ul>
<ul>
<li>Values returned by #DATE2NS
<li>If you specified a <var class="term">%rc</var> in your #function call, it is set to the number above that corresponds to the error, and <var class="term">%num</var> is set to <var>MISSING</var>. </li>
will often exceed the range that can be represented
 
in a 4-byte integer, so you should probably avoid storing the
<li>If <var class="term">%rc</var> is absent, <var class="product">Fast/Unload</var> is cancelled with return code 8. </li>
value in a BINARY or FLOAT4 field. </li>
</ul>
<p>
<b>Notes</b></p>
<ul>
<li>Values returned by <var>#DATE2NM</var>
will often exceed the range that can be represented
in a 4-byte integer, so you should probably avoid storing the
value in a <var>BINARY</var> or <var>FLOAT4</var> field. </li>


<li>Dates prior to 1 January 1900 will return a negative number. </li>
<li>Dates prior to 1 January 1900 will return a negative number. </li>


<li>The inverse of this #function is #NS2DATE. </li>
<li>The inverse of this #function is <var>[[#NM2DATE: Convert number of milliseconds to datetime string|#NM2DATE]]</var>. </li>


<li>[[Fast/Unload datetime processing considerations#dtfmt|Datetime formats]] explains valid datetime formats and valid dates. </li>
<li>[[Fast/Unload datetime processing considerations#dtfmt|Datetime formats]] explains valid datetime formats and valid dates. </li>
</ul>


<li>[[Fast/Unload datetime processing considerations#cspan|CENTSPAN]] explains <b>CENTSPAN</b> arguments.
==#DATE2NS: Convert datetime string to number of seconds==
</ul>
The <var>#DATE2NS</var> function converts a datetime value in a string format into
a numeric form that is the corresponding number of seconds since January 1, 1900.
<div id="#deblnk"></div>
It requires a datetime value string and a corresponding datetime
==#DEBLANK: Remove leading and trailing blanks from substring==
format string.
<!--Caution: <div> above-->
It accepts an optional <var>[[Fast/Unload datetime processing considerations#cspan|CENTSPAN]]</var> value for interpreting datetimes with two-digit years.
An optional output return code argument allows the FUEL program to
The #DEBLANK function extracts a substring (starting at pos for length len)
intercept error conditions.
and returns it, with leading and trailing blanks removed.
<p class="syntax"><span class="term">%num</span> = #DATE2NS(<span class="term">dat, fmt, span, %rc</span>)
It requires a string to be deblanked.
</p>
It accepts an optional starting position within the string to be
deblanked, and an optional length.
<p class="code"><nowiki>%out = #DEBLANK(str, pos, len)
</nowiki></p>
Where:
Where:
<table>
<table>
<tr><th>str</th><td>String to be deblanked; required.</td></tr>
<tr><th>dat</th>
<td>Datetime value string.</td></tr>


<tr><th>pos</th><td>Optional position within <i>str</i> to start deblanking. Must be numeric greater than or equal to 1, default is 1.</td></tr>
<tr><th>fmt</th>
<td>Datetime format string for <var class="term">dat</var>.</td></tr>


<tr><th>len</th><td>Optional length, starting at <i>pos</i> of string to deblank. Must be numeric greater than or equal to 0, default is the remainder of the input string.</td></tr>
<tr><th>span</th>
<td>Optional <var>CENTSPAN</var> value.</td></tr>
 
<tr><th>%rc</th>
<td>Return code variable (optional, output).</td></tr>


<tr><th>%out</th><td>Set to the substring within <i>str</i>, starting at <i>pos</i> for length <i>len</i>; leading and trailing blanks are then removed from this substring. Intermediate blanks within the substring are not affected.</td></tr>
<tr><th>%num</th>
<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>
<b>Examples</b>
</p>
The following fragment prints the value <code>BEFORE</code>
on the FUNPRINT dataset:
<p class="code">IF #DATE2NS('121494', 'MMDDYY') < #DATE2NS('040195', 'MMDDYY') THEN
  REPORT 'BEFORE'
END IF
</p>
<p>
<b>Errors</b></p>
The possible non-zero values of <var class="term">%rc</var>, or terminating conditions,
are shown below (see the discussion in [[#funerr|Run-time errors during standard #function calls]]):
<table class="thJustBold">
<tr><th>4</th>
<td><var class="term">fmt</var> is not a valid datetime format.</td></tr>
<tr><th>8</th>
<td><var class="term">dat</var> does not match <var class="term">fmt</var> or result date out of range.</td></tr>


Examples:
<tr><th>12</th>
<p class="code"><nowiki>#DEBLANK(' ABC ')        returns  'ABC'
<td><var class="term">span</var> is an invalid <var>CENTSPAN</var> value.</td></tr>
#DEBLANK(' ABC ', 1, 2)  returns  'A'
</table>
#DEBLANK(' A  BC ', 2, 4) returns  'A  B'
In the event of a run-time error:
</nowiki></p>
 
The <var class="product">Fast/Unload</var> run is cancelled with a return
code of 8 when:
<ul>
<ul>
<li><i>pos</i> is not numeric, or less than 1. </li>
<li>If you specified a <var class="term">%rc</var> in your #function call, it is set to the number above that corresponds to the error, and <var class="term">%num</var> is set to <var>MISSING</var>. </li>
<li><i>len</i> is not numeric, or less than 0. </li>
 
<li>If <var class="term">%rc</var> is absent, <var class="product">Fast/Unload</var> is cancelled with return code 8. </li>
</ul>
</ul>
<p><b>Notes</b></p>
<p>
<b>Notes</b></p>
<ul>
<ul>
<li>This #function is similar to the #STRIP function ([[##strip|#STRIP: Remove leading and/or trailing copies of pad character]]). </li>
<li>Values returned by <var>#DATE2NS</var>
</ul>
will often exceed the range that can be represented
in a 4-byte integer, so you should probably avoid storing the
value in a <var>BINARY</var> or <var>FLOAT4</var> field. </li>


This #function is new in <var class="product">Fast/Unload</var> version 4.0.
<li>Dates prior to 1 January 1900 will return a negative number. </li>
 
<li>The inverse of this #function is <var>[[#NS2DATE: Convert number of seconds to datetime string|#NS2DATE]]</var>. </li>


==#DELWORD: Remove blank-delimited words from string==
<li>[[Fast/Unload datetime processing considerations#dtfmt|Datetime formats]] explains valid datetime formats and valid dates. </li>
The #DELWORD function removes one or more blank-delimited words from a string.
</ul>
It requires an input string and a word number within the string.
It accepts an optional number of words to delete.
==<b id="#deblnk"></b>#DEBLANK: Remove leading and trailing blanks from substring==
<p class="code"><nowiki>%out = #DELWORD(str, word, count)
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.
</nowiki></p>
It accepts an optional starting position within the string to be deblanked, and an optional length.
<p class="syntax"><span class="term">%out</span> = #DEBLANK(<span class="term">str, pos, len</span>)
</p>
Where:
Where:
<table>
<table>
<tr><th>str</th><td>String containing words to be deleted; required.</td></tr>
<tr><th>str</th>
<tr><th>word</th><td>Number of first word within <i>str</i> to remove; required. Must be numeric greater than or equal to 1.</td></tr>
<td>String to be deblanked; required.</td></tr>
<tr><th>count</th><td>Optional count of words to remove. Must be numeric greater than or equal to 0, default is the remainder of words in the input string.</td></tr>
 
<tr><th>%out</th><td>Set to <i>str</i> with the substring removed which starts with the first character of word number <i>word</i> and ends with the last blank character before word number <i>word+count</i>.</td></tr>
<tr><th>pos</th>
<td>Optional position within <var class="term">str</var> to start deblanking. Must be numeric greater than or equal to 1, default is 1.</td></tr>
 
<tr><th>len</th>
<td>Optional length, starting at <var class="term">pos</var> of string to deblank. Must be numeric greater than or equal to 0, default is the remainder of the input string.</td></tr>
 
<tr><th>%out</th>
<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 class="code"><nowiki>#DELWORD('A B C', 1)     returns  ''
</p>
#DELWORD('A B C', 2)     returns  'A '
<p class="code"><nowiki>#DEBLANK(' ABC ')         returns  'ABC'
#DELWORD(' A B C ', 3)  returns  ' A B  '
#DEBLANK(' ABC ', 1, 2)   returns  'A'
#DELWORD('A B C', 4)     returns  'A B C'
#DEBLANK(' A  BC ', 2, 4) returns  'A  B'
#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 '
</nowiki></p>
</nowiki></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 when:
code of 8 if:
<ul>
<ul>
<li><i>word</i> is not numeric, or less than 1. </li>
<li><var class="term">pos</var> is not numeric, or less than 1. </li>
<li><i>count</i> is not numeric, or less than 0. </li>
<li><var class="term">len</var> is not numeric, or less than 0. </li>
</ul>
</ul>
<p>
<b>Notes</b></p>
<ul>
<li>This #function is similar to the <var>#STRIP</var> function ([[##strip|#STRIP: Remove leading and/or trailing copies of pad character]]). </li>


This #function is new in <var class="product">Fast/Unload</var> version 4.0.
<li>This #function is new in <var class="product">Fast/Unload</var> version 4.0. </li>
</ul>
<div id="#find"></div>
 
==#FIND: Word position of one word sequence within another==
==#DELWORD: Remove blank-delimited words from string==
<!--Caution: <div> above-->
The <var>#DELWORD</var> function removes one or more words from a string.
It requires an input string and a word number within the string.
The #FIND function determines the word position, within a string of
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.
blank-delimited words, of one or more blank-delimited words.
<p class="syntax"><span class="term">%out</span> = #DELWORD(<span class="term">str</span>, <span class="term">word</span>, [<span class="term">count</span>], [<span class="term">delimiter</span>])</p>
It requires an input string to search within and an input sequence
of words to search for.
<p class="code"><nowiki>%pos = #FIND(haystack, words)
</nowiki></p>
Where:
Where:
<table>
<table>
<tr><th>haystack</th><td>String containing words to be searched within; required.</td></tr>
<tr><th>str</th>
<tr><th>words</th><td>String containing one or more blank-delimited words to find; required.</td></tr>
<td>String containing words to be deleted; required.</td></tr>
<tr><th>%pos</th><td>Set to the word position, within <i>haystack</i>, of the first word of a sequence of words that matches the sequence in <i>words</i>. If <i>words</i> is not found, <i>%pos</i> is set to 0.</td></tr>
</table>


Examples:
<tr><th>word</th>
<p class="code"><nowiki>#FIND('A B C', 'B')          returns  2
<td>Number of first word within <var class="term">str</var> to remove; required. Must be numeric greater than or equal to 1.</td></tr>
#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
</nowiki></p>


This #function has no cancelling conditions.
<tr><th>count</th>
<p><b>Notes</b></p>
<td>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.</td></tr>
 
<tr><th>delimiter</th>
<td>Optional one-character delimiter to separate words within <var class="term">str</var>. The default delimiter is a blank.
<p>
This argument is available as of version 4.6 of <var class="product">Fast/Unload</var>. </p></td></tr>
 
<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 <code><i>word+count</i></code>.</td></tr>
</table>
<p>
<b>Examples</b>
</p>
<ol>
<li><p class="code"><nowiki>#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 '
</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
code of 8 if:
<ul>
<ul>
<li>Multiple blanks in both input arguments are ignored. </li>
<li><var class="term">word</var> is not numeric, or less than 1. </li>
 
<li><var class="term">count</var> is not numeric, or less than 0. </li>
<li>This #function is similar to the #ONEOF function ([[##oneof|#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 [[Fast/Unload Extraction Language (FUEL)#sel|SELECT entity]]). </li>
</ul>
</ul>


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.0.
   
   
<div id="flt8"></div>
<div id="#find"></div>
==#FLOAT8: Get 8-byte float, padding 4-byte input with 0==
 
==#FIND: Word position of one word sequence within another==
<!--Caution: <div> above-->
<!--Caution: <div> above-->
 
The #FLOAT8 function accepts a numeric argument, and it returns the
The <var>#FIND</var> function determines the word position, within a string of
value of the argument as an 8-byte floating point value.
blank-delimited words, of one or more blank-delimited words.
If the argument is a 4-byte floating point value, then
It requires an input string to search within and an input sequence
the conversion is done by appending binary zeroes; otherwise, it
of words to search for.
is done by the normal FUEL conversion to an 8-byte floating point value.
<p class="syntax"><span class="term">%pos</span> = #FIND(<span class="term">haystack</span>, <span class="term">words</span>)
<p class="code"><nowiki>%out = #FLOAT8(in)
</p>
</nowiki></p>
Where:
Where:
<table>
<table>
<tr><th>%out</th><td>Set to 8-byte floating point value of input argument.</td></tr>
<tr><th>haystack</th>
<tr><th>in</th><td>Numeric input value.</td></tr>
<td>String containing words to be searched within; required.</td></tr>
 
<tr><th>words</th>
<td>String containing one or more blank-delimited words to find; required.</td></tr>
 
<tr><th>%pos</th>
<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><b>Notes</b></p>
<ul>
<li>See [[Fast/Unload floating point arithmetic and numeric conversion]] for a specification of conversions to floating
point values. </li>
<li>Numeric operations in FUEL and in <var class="product">SOUL</var> are based on <b>decimal</b>,
not <b>binary</b>, interpretation of floating point values, so
this #function is seldom used.
<p>
<p>
However, #FLOAT8 may be useful in unusual situations, in particular to
<b>Examples</b>
perform a file reorganization that expands a FLOAT LEN 4 field to
</p>
a FLOAT LEN 8 field, using the "raw" floating point conversion
<p class="code"><nowiki>#FIND('A B C', 'B')          returns 2
(such as can be done in a structured file reorganization using
#FIND('A B C', 'D')          returns  0
the <code>X'0080'</code> mode bit in FLOD).</p>
#FIND('A B C', 'A B')        returns  1
<p>
#FIND('     ', ' ')          returns  0
For example, if field FLT is defined in the input as FLOAT LEN
#FIND('A B', 'A B C')       returns  0
4, and you want to convert it to a FLOAT LEN 8 or FLOAT LEN 16
#FIND('B B B A', 'B B A')   returns  2
in a UAI/LAI file reorganization in such a way that the new
#FIND('A A B', ' A  B ')   returns  2
field's values consist of the old ones with binary zeros added,
#FIND(' A  A   B  ', 'A B')  returns  2
you can use the following:</p>
<p class="code"><nowiki>  OPEN PRODFILE
  UAI
  FOR EACH RECORD
     FOR I FROM 1 TO FLT(#)
      CHANGE FLT(I) = #FLOAT8(FLT(I))
    END FOR
    UNLOAD
   END FOR
</nowiki></p>
</nowiki></p>
This #function has no cancelling conditions.
<p>
<p>
In this example, if the input value of FLT is 411028F6, which is the
<b>Notes</b></p>
closest 4-byte floating point value to the decimal value 1.01, it is
<ul>
converted on output to 411028F600000000, which <var class="product">SOUL</var> will display as
<li>Multiple blanks in both input arguments are ignored. </li>
1.01000022888184 (demonstrating that #FLOAT8 is only to be used in
 
special circumstances).</p>
<li>This #function is similar to the <var>#ONEOF</var> function ([[##oneof|#ONEOF: See if string is in delimited list of strings]]).
<p>
Note, however, that both <var>#FIND</var> and <var>#ONEOF</var> are inferior to the
A "normal"
<var>SELECT</var> statement, when the only purpose is to test whether an
UAI/LAI conversion of 411028F6 to a FLOAT LEN 8 field would be to
entity has one of several values (see [[Fast/Unload Extraction Language (FUEL)#sel|SELECT entity]]). </li>
the hexadecimal value 411028F5C28F5C28, which <var class="product">SOUL</var> will display as
1.01.</p> </li>
</ul>
</ul>


This #function is new in <var class="product">Fast/Unload</var> version 4.3.
==<b id="flt8"></b>#FLOAT8: Get 8-byte float, padding 4-byte input with 0==
The <var>#FLOAT8</var> 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.
<p class="syntax"><span class="term">%out</span> = #FLOAT8(<span class="term">in</span>)
</p>
Where:
<table>
<tr><th>%out</th>
<td>Set to 8-byte floating point value of input argument.</td></tr>
 
<tr><th>in</th>
<td>Numeric input value.</td></tr>
</table>
<p>
<b>Notes</b></p>
<ul>
<li>See [[Fast/Unload floating point arithmetic and numeric conversion]] for a specification of conversions to floating
point values. </li>
 
<li>Numeric operations in FUEL and in <var class="product">SOUL</var> are based on <i>decimal</i>, not binary, interpretation of floating point values, so
this #function is seldom used.
<p>
However, <var>#FLOAT8</var> may be useful in unusual situations, in particular to
perform a file reorganization that expands a <code>FLOAT LEN 4</code> field to
a <code>FLOAT LEN 8</code> field, using the "raw" floating point conversion
(such as can be done in a structured file reorganization using
the <code>X'0080'</code> mode bit in <var>FLOD</var>).</p>
<p>
For example, if field <code>FLT</code> is defined in the input as <code>FLOAT LEN
4</code>, and you want to convert it to a <code>FLOAT LEN 8</code> or <code>FLOAT LEN 16</code>
in a <var>UAI/LAI</var> 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:</p>
<p class="code">OPEN PRODFILE
UAI
FOR EACH RECORD
  FOR I FROM 1 TO FLT(#)
    CHANGE FLT(I) = #FLOAT8(FLT(I))
  END FOR
  UNLOAD
END FOR
</p>
<p>
In this example, if the input value of <code>FLT</code> is <code>411028F6</code>, which is the
closest 4-byte floating point value to the decimal value 1.01, it is
converted on output to <code>411028F600000000</code>, which <var class="product">SOUL</var> will display as
<code>1.01000022888184</code> (demonstrating that <var>#FLOAT8</var> is only to be used in
special circumstances).</p>
<p>
A "normal" <var>UAI/LAI</var> conversion of <code>411028F6</code>. to a <code>FLOAT LEN 8</code> field would be to
the hexadecimal value <code>411028F5C28F5C28</code>, which <var class="product">SOUL</var> will display as
<code>1.01</code>.</p> </li>
</ul>
 
This #function is new in <var class="product">Fast/Unload</var> version 4.3.


==#INDEX: Position of second string within first==
==#INDEX: Position of second string within first==
The #INDEX function locates the first occurrence, if any, of a search
The <var>#INDEX</var> function locates the first occurrence, if any, of a search
string (needle) within a searched string (haystack).
string (needle) within a searched string (haystack).
It requires a string to be searched and accepts an optional string
It requires a string to be searched and accepts an optional string to locate.
to locate.
It accepts an optional starting position within the string to be searched.
It accepts an optional starting position within the string to be
<var>#INDEX</var> returns either the starting position within the searched string
searched.
<nowiki>#INDEX</nowiki> returns either the starting position within the searched string
of the first occurrence of the string to be located (starting at the
of the first occurrence of the string to be located (starting at the
specified position), or 0.
specified position), or 0.
<p class="code"><nowiki>%opos = #INDEX(haystack, needle, pos)
<p class="syntax"><span class="term">%opos</span> = #INDEX(<span class="term">haystack, needle, pos</span>)
</nowiki></p>
</p>
Where:
Where:
<table>
<table>
<tr><th>haystack</th><td>String to be searched; required.</td></tr>
<tr><th>haystack</th>
<tr><th>needle</th><td>String to be located, may be omitted.</td></tr>
<td>String to be searched; required.</td></tr>
<tr><th>pos</th><td>Optional starting position within <i>haystack</i> for search. Must be numeric greater than or equal to 1, default is 1.</td></tr>
 
<tr><th>%opos</th><td>Set to starting position of first occurrence of <i>needle</i> within <i>haystack</i>, with search starting at <i>pos</i>, else 0 if not found or if either string length is zero.</td></tr>
<tr><th>needle</th>
</table>
<td>String to be located, may be omitted.</td></tr>


Examples:
<tr><th>pos</th>
<td>Optional starting position within <var class="term">haystack</var> for search. Must be numeric greater than or equal to 1, default is 1.</td></tr>
 
<tr><th>%opos</th>
<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>
<p>
<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,085: Line 1,222:
code of 8 when:
code of 8 when:
<ul>
<ul>
<li><i>pos</i> is not numeric, or less than 1. </li>
<li><var class="term">pos</var> is not numeric, or less than 1. </li>
</ul>
</ul>
<p><b>Notes</b></p>
<p>
<b>Notes</b></p>
<ul>
<ul>
<li>If <i>needle</i> or <i>haystack</i> is the null string, 0 is returned. </li>
<li>If <var class="term">needle</var> or <var class="term">haystack</var> is the null string, 0 is returned. </li>
</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==
The <var>#LEFT</var> function returns a padded initial substring from a source string.
<!--Caution: <div> above-->
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 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.
<nowiki>#LEFT</nowiki> returns the string that begins at the first position
<var>#LEFT</var> returns the string that begins at the first 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 first <i>length</i> characters of the source are returned.
the first <var class="term">length</var> characters of the source are returned.
Otherwise, the source string is padded to the output length by following it
Otherwise, the source string is padded to the output length by following it
with sufficient copies of the pad character.
with sufficient copies of the pad character.
<p class="code"><nowiki>%out = #LEFT(str, len, pad)
<p class="syntax"><span class="term">%out</span> = #LEFT(<span class="term">str, len, pad</span>)
</nowiki></p>
</p>
Where:
Where:
<table>
<table>
<tr><th>str</th><td>Source string.</td></tr>
<tr><th>str</th>
<tr><th>len</th><td>Length of the output string. Must be numeric >= 0.</td></tr>
<td>Source string.</td></tr>
<tr><th>pad</th><td>Optional pad character. Default is blank. If supplied, must be a string of length 1.</td></tr>
 
<tr><th>%out</th><td>If <i>len</i> is greater then #LEN(<i>str</i>):  
<tr><th>len</th>
<td>Length of the output string. Must be numeric and greater than or equal to 0.</td></tr>
 
<tr><th>pad</th>
<td>Optional pad character. Default is blank. If supplied, must be a string of length 1.</td></tr>
 
<tr><th>%out</th>
<td>If <var class="term">len</var> is greater then <code>#LEN(<i>str</i>)</code>:  
<ul>
<ul>
<li>all of <i>str</i>, followed by <i>len</i> - <nowiki>#LEN</nowiki>(<i>str</i>) copies of the pad character  </li>
<li>All of <var class="term">str</var>, followed by <code><i>len</i> - #LEN(<i>str</i>)</code> copies of the pad character  </li>
</ul>  
</ul>  
<p>Otherwise: </p>  
<p>
Otherwise: </p>  
<ul>
<ul>
<li>substring from <i>str</i> starting at position 1 with length <i>len</i> </li>
<li>Substring from <var class="term">str</var> starting at position 1 with length <var class="term">len</var> </li>
</ul></td></tr>
</ul></td></tr>
</table>
</table>
For example:
<p>
<p class="code"><nowiki>#LEFT('ABC', 1)      returns  'A'
<b>Examples</b>
</p>
<p class="code"><nowiki>#LEFT('ABC', 1)      returns  A'
#LEFT('ABC', 3)      returns  'ABC'
#LEFT('ABC', 3)      returns  'ABC'
#LEFT('ABC', 4)      returns  'ABC '
#LEFT('ABC', 4)      returns  'ABC '
Line 1,130: Line 1,274:


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><i>Len</i> not numeric, or less than 0. </li>
<li><var class="term">len</var> not numeric, or less than 0. </li>
<li><i>Pad</i> supplied, and length not 1. </li>
<li><var class="term">pad</var> supplied, and length not 1. </li>
</ul>
</ul>
<p>
<p>
<b>Notes</b></p>
<b>Notes</b></p>
<ul>
<ul>
<li>This is the same as the #PADR function, except for the order of
<li>This is the same as the <var>#PADR</var> function, except for the order of
the arguments (see [[##padr|#PADR: Initial substring, followed by pad characters to specified length]]). </li>
the arguments (see [[##padr|#PADR: Initial substring, followed by pad characters to specified length]]). </li>
</ul>
</ul>


This #function is new in <var class="product">Fast/Unload</var> version 4.0.
==<b id="#len"></b>#LEN: Length of string==
The <var>#LEN</var> function returns the length of a string, in number of bytes.
<div id="#len"></div>
==#LEN: Length of string==
<!--Caution: <div> above-->
The #LEN 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.
<p class="code"><nowiki>%len = #LEN(str)
<p class="syntax"><span class="term">%len</span> = #LEN(<span class="term">str</span>)
</nowiki></p>
</p>
Where:
Where:
<table>
<table>
<tr><th>str</th><td>String whose length you want to know. For <var class="product">Fast/Unload</var> version 4.3 and later. <i>str</i> may be longer than 255 bytes.</td></tr>
<tr><th>str</th>
<tr><th>%len</th><td>Set to length of <i>str</i>.</td></tr>
<td>String whose length you want to know. For <var class="product">Fast/Unload</var> version 4.3 and later. <var class="term">str</var> may be longer than 255 bytes.</td></tr>
 
<tr><th>%len</th>
<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,165: 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 #LOWCASE 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
EBCDIC letters changed to the corresponding lowercase letters.
EBCDIC letters changed to the corresponding lowercase letters.
It expects a source string argument.
It expects a source string argument.
<p class="code"><nowiki>%out = #LOWCASE(str)
<p class="syntax"><span class="term">%out</span> = #LOWCASE(<span class="term">str</span>)
</nowiki></p>
</p>
Where:
Where:
<table>
<table>
<tr><th>str</th><td>Source string, required.</td></tr>
<tr><th>str</th>
<tr><th>%out</th><td>Copy of <i>str</i>, with all uppercase EBCDIC letters changed to their lowercase EBCDIC equivalents.</td></tr>
<td>Source string, required.</td></tr>
 
<tr><th>%out</th>
<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==
The #ND2DATE function converts a numeric datetime value expressed as
The <var>#ND2DATE</var> function converts a numeric datetime value expressed as
the number of days since January 1, 1900 into a datetime string
the number of days since January 1, 1900 into a datetime string
value according to a specified datetime format string.
value according to a specified datetime format string.
Line 1,193: Line 1,343:
An optional output return code argument allows the FUEL program to
An optional output return code argument allows the FUEL program to
intercept error conditions.
intercept error conditions.
<p class="code"><nowiki>%dat = #ND2DATE(datn, fmt, %rc)
<p class="syntax"><span class="term">%dat</span> = #ND2DATE(<span class="term">datn, fmt, %rc</span>)
</nowiki></p>
</p>
Where:
Where:
<table>
<table>
<tr><th>datn</th><td>Numeric datetime value expressed as the number of days since 1 Jan 1900 12:00 AM. This argument may not have the MISSING value.</td></tr>
<tr><th>datn</th>
<tr><th>fmt</th><td>Datetime format string to use for creating <i>%dat</i>.</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>%rc</th><td>Return code (optional, output)</td></tr>
 
<tr><th>%dat</th><td>Set to datetime string value, in format specified by <i>fmt</i>, corresponding to <i>datn</i>.</td></tr>
<tr><th>fmt</th>
<td>Datetime format string to use for creating <var class="term">%dat</var>.</td></tr>
 
<tr><th>%rc</th>
<td>Return code (optional, output)</td></tr>
 
<tr><th>%dat</th>
<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,211: Line 1,370:
</nowiki></p>
</nowiki></p>


Non-zero values of <i>%rc</i>, or terminating conditions,
<p>
are shown in the following figure (see the discussion in
<b>Errors</b></p>
[[#funerr|Run-time errors during standard #function calls]]).
The possible non-zero values of <var class="term">%rc</var>, or terminating conditions,
are shown below (see the discussion in [[#funerr|Run-time errors during standard #function calls]]):
<table class="thJustBold">
<tr><th>4</th>
<td><var class="term">fmt</var> is not a valid datetime format.</td></tr>


<b>Errors:</b>
<tr><th>8</th>
if <i>%rc</i> present, set to corresponding number
<td><var class="term">datn</var> is out of range for <var class="term">fmt</var>.</td></tr>
and set <i>%dat</i> to MISSING;
if absent, cancel <var class="product">Fast/Unload</var> with return code 8.
<table>
<tr><th>4</th><td><i>fmt</i> is not a valid datetime format.</td></tr>
<tr><th>8</th><td><i>datn</i> is out of range for <i>fmt</i>.</td></tr>
</table>
</table>
In the event of a run-time error:
<ul>
<li>If you specified a <var class="term">%rc</var> in your #function call, it is set to the number above that corresponds to the error, and <var class="term">%dat</var> is set to <var>MISSING</var>. </li>
<li>If <var class="term">%rc</var> is absent, <var class="product">Fast/Unload</var> is cancelled with return code 8. </li>
</ul>
<p>
<p>
<b>Notes</b></p>
<b>Notes</b></p>
<ul>
<ul>
<li>The inverse of this #function is #DATE2ND. </li>
<li>The inverse of this #function is <var>[[#DATE2ND: Convert datetime string to number of days|#DATE2ND]]</var>. </li>
 
<li>[[Fast/Unload datetime processing considerations#dtfmt|Datetime formats]] explains valid datetime formats and valid dates. </li>
<li>[[Fast/Unload datetime processing considerations#dtfmt|Datetime formats]] explains valid datetime formats and valid dates. </li>
</ul>
</ul>


==#NM2DATE: Convert number of milliseconds to datetime string==
==#NM2DATE: Convert number of milliseconds to datetime string==
The #NM2DATE function converts a numeric datetime value expressed as
The <var>#NM2DATE</var> function converts a numeric datetime value expressed as
the number of milliseconds since January 1, 1900 into a datetime string
the number of milliseconds since January 1, 1900 into a datetime string
value according to a specified datetime format string.
value according to a specified datetime format string.
It requires a datetime numeric value and a 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
An optional output return code argument allows the FUEL program to intercept error conditions.
intercept error conditions.
<p class="syntax"><span class="term">%dat</span> = #NM2DATE(<span class="term">datn, fmt, %rc</span>)
<p class="code"><nowiki>%dat = #NM2DATE(datn, fmt, %rc)
</p>
</nowiki></p>
Where:
Where:
<table>
<table>
<tr><th>datn</th>
<tr><th>datn</th>
<td>Numeric datetime value expressed as the number of milliseconds since 1 Jan 1900 12:00 AM. This argument may not have the MISSING value.</td></tr>
<td>Numeric datetime value expressed as the number of milliseconds since <code>1 Jan 1900 12:00 AM</code>. This argument may not have the <var>MISSING</var> value.</td></tr>


<tr><th>fmt</th>
<tr><th>fmt</th>
<td>Datetime format string to use for creating <i>%dat</i>.</td></tr>
<td>Datetime format string to use for creating <var class="term">%dat</var>.</td></tr>


<tr><th>%rc</th>
<tr><th>%rc</th>
Line 1,252: Line 1,415:


<tr><th>%dat</th>
<tr><th>%dat</th>
<td>Set to datetime string value, in format specified by <i>fmt</i>, corresponding to <i>datn</i>.</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,263: Line 1,428:
</nowiki></p>
</nowiki></p>


Non-zero values of <i>%rc</i>, or terminating conditions,
<p>
are shown in the following figure (see the discussion in
<b>Errors</b></p>
[[#funerr|Run-time errors during standard #function calls]]).
The possible non-zero values of <var class="term">%rc</var>, or terminating conditions,
are shown below (see the discussion in [[#funerr|Run-time errors during standard #function calls]]):
<table class="thJustBold">
<tr><th>4</th>
<td><var class="term">fmt</var> is not a valid datetime format.</td></tr>


<b>Errors:</b>
<tr><th>8</th>
if <i>%rc</i> present, set to corresponding number
<td><var class="term">datn</var> is out of range for <var class="term">fmt</var>.</td></tr>
and set <i>%dat</i> to MISSING;
if absent, cancel <var class="product">Fast/Unload</var> with return code 8.
<table>
<tr><th>4</th><td><i>fmt</i> is not a valid datetime format.</td></tr>
<tr><th>8</th><td><i>datn</i> is out of range for <i>fmt</i>.</td></tr>
</table>
</table>
<p>
In the event of a run-time error:
<b>Notes</b></p>
<ul>
<li>If you specified a <var class="term">%rc</var> in your #function call, it is set to the number above that corresponds to the error, and <var class="term">%dat</var> is set to <var>MISSING</var>. </li>
 
<li>If <var class="term">%rc</var> is absent, <var class="product">Fast/Unload</var> is cancelled with return code 8. </li>
</ul>
<p>
<b>Notes</b></p>
<ul>
<ul>
<li>[[Fast/Unload datetime processing considerations#dtfmt|Datetime formats]] explains valid datetime formats and valid dates. </li>
<li>[[Fast/Unload datetime processing considerations#dtfmt|Datetime formats]] explains valid datetime formats and valid dates. </li>
Line 1,283: Line 1,452:


==#NS2DATE: Convert number of seconds to datetime string==
==#NS2DATE: Convert number of seconds to datetime string==
The #NS2DATE function converts a numeric datetime value expressed as
The <var>#NS2DATE</var> function converts a numeric datetime value expressed as
the number of seconds since January 1, 1900 into a datetime string
the number of seconds since January 1, 1900 into a datetime string
value according to a specified datetime format string.
value according to a specified datetime format string.
Line 1,289: Line 1,458:
An optional output return code argument allows the FUEL program to
An optional output return code argument allows the FUEL program to
intercept error conditions.
intercept error conditions.
<p class="code"><nowiki>%dat = #NS2DATE(datn, fmt, %rc)
<p class="syntax"><span class="term">%dat</span> = #NS2DATE(<span class="term">datn, fmt, %rc</span>)
</nowiki></p>
</p>
Where:
Where:
<table>
<table>
<tr><th>datn</th><td>Numeric datetime value expressed as the number of seconds since 1 Jan 1900 12:00 AM. This argument may not have the MISSING value.</td></tr>
<tr><th>datn</th>
<tr><th>fmt</th><td>Datetime format string to use for creating <i>%dat</i>.</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>%rc</th><td>Return code (optional, output)</td></tr>
 
<tr><th>%dat</th><td>Set to datetime string value, in format specified by <i>fmt</i>, corresponding to <i>datn</i>.</td></tr>
<tr><th>fmt</th>
<td>Datetime format string to use for creating <var class="term">%dat</var>.</td></tr>
 
<tr><th>%rc</th>
<td>Return code (optional, output)</td></tr>
 
<tr><th>%dat</th>
<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,307: Line 1,485:
</nowiki></p>
</nowiki></p>


Non-zero values of <i>%rc</i>, or terminating conditions,
<p>
are shown in the following figure (see the discussion in
<b>Errors</b></p>
[[#funerr|Run-time errors during standard #function calls]]).
The possible non-zero values of <var class="term">%rc</var>, or terminating conditions,
are shown below (see the discussion in [[#funerr|Run-time errors during standard #function calls]]):
<table class="thJustBold">
<tr><th>4</th>
<td><var class="term">fmt</var> is not a valid datetime format.</td></tr>


<b>Errors:</b>
<tr><th>8</th>
if <i>%rc</i> present, set to corresponding number
<td><var class="term">datn</var> is out of range for <var class="term">fmt</var>.</td></tr>
and set <i>%dat</i> to MISSING;
if absent, cancel <var class="product">Fast/Unload</var> with return code 8.
<table>
<tr><th>4</th><td><i>fmt</i> is not a valid datetime format.</td></tr>
<tr><th>8</th><td><i>datn</i> is out of range for <i>fmt</i>.</td></tr>
</table>
</table>
In the event of a run-time error:
<ul>
<li>If you specified a <var class="term">%rc</var> in your #function call, it is set to the number above that corresponds to the error, and <var class="term">%dat</var> is set to <var>MISSING</var>. </li>
<li>If <var class="term">%rc</var> is absent, <var class="product">Fast/Unload</var> is cancelled with return code 8. </li>
</ul>
<p>
<p>
<b>Notes</b></p>
<b>Notes</b></p>
<ul>
<ul>
<li>The inverse of this #function is #DATE2NS. </li>
<li>The inverse of this #function is <var>[[#DATE2NS: Convert datetime string to number of seconds|#DATE2NS]]</var>. </li>
<li>[[Fast/Unload datetime processing considerations#dtfmt|Datetime formats]] explains valid datetime formats and valid dates. </li>
<li>[[Fast/Unload datetime processing considerations#dtfmt|Datetime formats]] explains valid datetime formats and valid dates. </li>
</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==
The <var>#NUM2STR</var> function converts a number to a string with an integer part,
<!--Caution: <div> above-->
The #NUM2STR 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
control over the number of integer and fraction digits, padding, and
control over the number of integer and fraction digits, padding, and rounding.
rounding.
It requires a numeric value.
It requires a numeric value.
Optional arguments specify the width of the resulting integer digits
Optional arguments specify the width of the resulting integer digits
area, the width of the resulting fraction digits area,
area, the width of the resulting fraction digits area,
rounding vs. truncation and fixed width vs. variable/minimal width
rounding vs. truncation and fixed width vs. variable/minimal width integer area,
integer area,
and the leading pad character for the integer digits area.
and the leading pad character for the integer digits area.


The final optional argument is an output argument whose absolute
The final optional argument is an output argument whose absolute value is set to the
value is set to the
number of integer characters (after leading zeroes are stripped) in the
number of integer characters (after leading zeroes are stripped) in the
number, plus 1 if the number is negative.
number, plus 1 if the number is negative.
Specifying this argument
Specifying this argument allows the <var class="product">Fast/Unload</var> program to continue if the first argument cannot be represented by the result, either as a result of truncation of
allows the <var class="product">Fast/Unload</var> program to continue if the first argument
the high-order integer digits, or because the first argument cannot be converted to a number.
cannot be represented by the result, either as a result of truncation of
 
the high-order integer digits, or because the first argument can not be
<p class="syntax"><span class="term">%str</span> = #NUM2STR(<span class="term">num</span>, [<span class="term">intw</span>], [<span class="term">fracw</span>], [<span class="term">opt</span>], [<span class="term">pad</span>], [<span class="term">%intlen</span>])
converted to a number.
</p>
<p class="code"><nowiki>%str = #NUM2STR(num, intw, fracw, opt, pad, %intlen)
</nowiki></p>
Where:
Where:
<table>
<table>
<tr><th>num</th><td>Input number to be converted.</td></tr>
<tr><th>num</th>
<tr><th>intw</th><td>Number of characters used to express the integer portion and leading minus sign, if any, of <i>num</i>. 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 <i>num</i> 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).  
<td>Input number to be converted.</td></tr>
<p>If the fourth argument (<i>opt</i>) contains the letter 'V', <i>intw</i> is the minimal width used for the integer part, and the number of characters needed is used if that exceeds <i>intw</i>.</p> </td></tr>
 
<tr><th>intw</th>
<td>Number of characters used to express the integer portion and leading minus sign, if any, of <var class="term">num</var>.  
<p>
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 <var class="term">num</var> 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).</p>
<p>
If the fourth argument (<var class="term">opt</var>) contains the letter <code>V</code>, <var class="term">intw</var> is the minimal width used for the integer part, and the number of characters needed is used if that exceeds <var class="term">intw</var>.</p> </td></tr>


<tr><th>fracw</th><td>Number of digits used to express the fraction portion of <i>num</i>. Optional, must be 0 or more if specified. If this argument is omitted:  
<tr><th>fracw</th>
<td>Number of digits used to express the fraction portion of <var class="term">num</var>. Optional, must be 0 or more if specified. If this argument is omitted:  
<ul>
<ul>
<li>only the characters needed are used to represent the fraction part </li>
<li>only the characters needed are used to represent the fraction part </li>
Line 1,366: Line 1,547:
</ul></td></tr>
</ul></td></tr>


<tr><th>%opt</th><td>One or two characters, optional, with one choice from either of the following two pairs:  
<tr><th>%opt</th>
<td>One or two characters, optional, with one choice from either of the following two pairs:  
<ul>
<ul>
<li>R (round) or T (trunc)
<li>R (round) or T (trunc)
<table>
<table class="thJustBold">
<tr><th>R</th><td>Round up the final digit of the result, if the most significant discarded fraction digit is 5 or more. This is the default.</td></tr>
<tr><th>R</th>
<td>Round up the final digit of the result, if the most significant discarded fraction digit is <code>5</code> or more. This is the default.</td></tr>


<tr><th>T</th><td>Final digit of result unaffected by any discarded fraction digits.</td></tr>
<tr><th>T</th>
<td>Final digit of result unaffected by any discarded fraction digits.</td></tr>
</table>
</table>
<p>
<p>
This character has no meaning if argument three (<i>fracw</i>) is omitted, since in that case no fraction digits are discarded.</p> </li>
This character has no meaning if argument three (<var class="term">fracw</var>) is omitted, since in that case no fraction digits are discarded.</p> </li>
   
   
<li>F (fixed width) or V (variable width)
<li><var>F</var> (fixed width) or <var>V</var> (variable width)
<table>
<table class="thJustBold">
<tr><th>F</th>
<tr><th>F</th>
<td>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 (<i>intw</i>). This is the default.</td></tr>
<td>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 (<var class="term">intw</var>). This is the default.</td></tr>


<tr><th>V</th>
<tr><th>V</th>
<td>The integer portion of the result is variable/minimal width. That is, if <i>w</i> characters are needed for the integer (and leading minus sign) with leading zeroes removed, then <i>w</i> characters are used for the integer if <i>w</i>><i>intw</i>; <i>intw</i> characters are used otherwise.</td></tr>
<td>The integer portion of the result is variable/minimal width. That is, if <var class="term">w</var> characters are needed for the integer (and leading minus sign) with leading zeroes removed, then <var class="term">w</var> characters are used for the integer if <var class="term">w</var> is greater than <var class="term">intw</var>; <var class="term">intw</var> characters are used otherwise.</td></tr>
</table>
</table>
<p>
<p>
This character has no meaning if argument two (<i>intw</i>) is omitted, since in that case exactly the characters needed for the integer are used.</p> </li>  
This character has no meaning if argument two (<var class="term">intw</var>) is omitted, since in that case exactly the characters needed for the integer are used.</p> </li>  
</ul></td></tr>
</ul></td></tr>


<tr><th>pad</th><td>The leading pad character used to fill the integer portion to the width specified by argument two (<i>intw</i>). Optional, must be one character, defaults to blank. If the pad character is blank, a leading minus sign <b>follows</b> any blank pad characters; otherwise a leading minus sign <b>precedes</b> any pad characters.</td></tr>
<tr><th><i>pad</i></th>
<td>The leading pad character used to fill the integer portion to the width specified by argument two (<var class="term">intw</var>). Optional, must be one character, defaults to blank. If the pad character is blank, a leading minus sign <b>follows</b> any blank pad characters; otherwise a leading minus sign <b>precedes</b> any pad characters.</td></tr>


<tr><th>%intlen</th><td>Set to the value <i>len</i>, where the absolute value of <i>len</i> is the number of characters needed for the integer part of the first argument (<i>num</i>), with any leading zeroes stripped (or one zero if the integer part is zero), including one additional character if <i>num</i> is negative.  
<tr><th><i>%intlen</i></th>
<p>If <i>%intlen</i> is returned with a negative value, that indicates truncation of the integer part of <i>num</i>; this occurs if all of the following conditions hold:</p>   
<td>Set to the value <var class="term">len</var>, where the absolute value of <var class="term">len</var> is the number of characters needed for the integer part of the first argument (<var class="term">num</var>), with any leading zeroes stripped (or one zero if the integer part is zero), including one additional character if <var class="term">num</var> is negative.  
<p>
If <var class="term">%intlen</var> is returned with a negative value, it indicates truncation of the integer part of <var class="term">num</var>. This truncation occurs if all of the following conditions hold:</p>   
<ul>
<ul>
<li>Argument two (<i>intw</i>) is specified. </li>
<li>Argument two (<var class="term">intw</var>) is specified. </li>
<li>The absolute value of <i>len</i> is greater than <i>intw</i>. </li>
<li>The absolute value of <var class="term">len</var> is greater than <var class="term">intw</var>. </li>
<li><i>Intw</i>>0, or <i>num</i><0, or <i>num</i>>=1. </li>
 
<li>Argument four (<i>opt</i>) does not contain the letter 'V'. </li>  
<li><var class="term">intw</var> greater than 0, or <var class="term">num</var> less than 0, or <var class="term">num</var> greater than or equal to 1. </li>
 
<li>Argument four (<var class="term">opt</var>) does not contain the letter <code>V</code>. </li>  
</ul>  
</ul>  
<p>
<p>
If <i>num</i> cannot be converted to a number, then <i>len</i> is returned as zero, and the result (value of <i>%str</i>) of #NUM2STR is the MISSING value.  
If <var class="term">num</var> cannot be converted to a number, then <var class="term">len</var> is returned as zero, and the result (value of <var class="term">%str</var>) of <var>#NUM2STR</var> is the <var>MISSING</var> value. </p>
<p>
<p>
Otherwise, <i>len</i> is positive.
Otherwise, <var class="term">len</var> is positive.
</p>  
</p>  
<p>
<p>
As these rules indicate, <i>%intlen</i>, 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 <i>%intlen</i> 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,445: Line 1,635:
</nowiki></p>
</nowiki></p>


Non-zero values of <i>%intlen</i>, or terminating conditions,
<p>
are shown in the following figure (see the discussion in
<b>Errors</b></p>
[[#funerr|Run-time errors during standard #function calls]]).
The possible non-zero values of <var class="term">%intlen</var>, or terminating conditions,
are shown below (see the discussion in [[#funerr|Run-time errors during standard #function calls]]):
<table class="thJustBold">
<tr><th>-N</th>
<td><var class="term">N</var> is the length required for the integer part of <var class="term">num</var>, and <var class="term">n</var> is greater than <var class="term">intw</var> and <var class="term">opt</var> does not contain the letter <code>V</code>.</td></tr>


<b>Errors:</b>
<tr><th>0</th>
if <i>%intlen</i> present, set to corresponding number;
<td><var class="term">num</var> can not be converted to a numeric value (<var class="term">%str</var> is set to <var>MISSING</var>).</td></tr>
if absent, cancel <var class="product">Fast/Unload</var> with return code 8.
<table>
<tr><th>-N</th><td><i>N</i> is the length required for the integer part of <i>num</i>, and <i>n</i>><i>intw</i> and <i>opt</i> does not contain the letter "V".</td></tr>
<tr><th>0</th><td><i>Num</i> can not be converted to a numeric value (<i>%str</i> is set to MISSING).</td></tr>
<tr><th>**</th><td>Negative or non-numeric value for <i>intw</i> or <i>fracw</i> (this error always cancels <var class="product">Fast/Unload</var>, regardless of the presence of <b>%intlen</b>).</td></tr>
<tr><th>**</th><td>Invalid character in <i>opt</i> (this error always cancels <var class="product">Fast/Unload</var>, regardless of the presence of <b>%intlen</b>).</td></tr>
<tr><th>**</th><td>Length of <i>pad</i> not 1 (this error always cancels <var class="product">Fast/Unload</var>, regardless of the presence of <b>%intlen</b>).</td></tr>
</table>
<blockquote class="note"><b>Note:</b> If you are creating a string to place in the <var class="product">Fast/Unload</var>
output file, you can also use the PUT with the AS STRING or AS DECIMAL
clauses (see [[Fast/Unload Extraction Language (FUEL)#put|PUT]]).


One difference between #NUM2STR and PUT AS STRING or PUT AS DECIMAL
<tr><th>**</th>
is that all conversion
<td>Negative or non-numeric value for <var class="term">intw</var> or <var class="term">fracw</var> (this error always cancels <var class="product">Fast/Unload</var>, regardless of the presence of <var class="term">%intlen</var>).</td></tr>
of fractional values to fixed width output formats
 
in the PUT statement causes low order fraction digits to be dropped
<tr><th>**</th>
without rounding, but #NUM2STR offers rounding of dropped low order
<td>Invalid character in <var class="term">opt</var> (this error always cancels <var class="product">Fast/Unload</var>, regardless of the presence of <var class="term">%intlen</var>).</td></tr>
digits.
 
<tr><th>**</th>
<td>Length of <var class="term">pad</var> not 1 (this error always cancels <var class="product">Fast/Unload</var>, regardless of the presence of <var class="term">%intlen</var>).</td></tr>
</table>
In the event of a run-time error:
<ul>
<li>If you specified a <var class="term">%intlen</var> in your #function call, it is set to the return code above that corresponds to the error. </li>
 
<li>If <var class="term">%intlen</var> is absent, <var class="product">Fast/Unload</var> is cancelled with return code 8. </li>
</ul>
 
<blockquote class="note">
<p><b>Note:</b> If you are creating a string to place in the <var class="product">Fast/Unload</var>
output file, you can also use the <var>PUT</var> with the <var>AS STRING</var> or <var>AS DECIMAL</var>
clauses (see [[Fast/Unload Extraction Language (FUEL)#put|PUT]]).</p>
<p>
One difference between <var>#NUM2STR</var> and <var>PUT AS STRING</var> or <var>PUT AS DECIMAL</var>
is that all conversion of fractional values to fixed width output formats
in the <var>PUT</var> statement causes low order fraction digits to be dropped
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==
The #N2DATE function converts a numeric datetime value expressed as
The <var>#N2DATE</var> function converts a numeric datetime value expressed as
the number of seconds*300 since January 1, 1900 into a datetime string
the number of <code>seconds*300</code> since January 1, 1900 into a datetime string
value according to a specified datetime format string.
value according to a specified datetime format string.
It requires a datetime numeric value and a 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
An optional output return code argument allows the FUEL program to
intercept error conditions.
intercept error conditions.
<p class="code"><nowiki>%dat = #N2DATE(datn, fmt, %rc)
<p class="syntax"><span class="term">%dat</span> = #N2DATE(<span class="term">datn, fmt, %rc</span>)
</nowiki></p>
</p>
Where:
Where:
<table>
<table>
<tr><th>datn</th><td>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.</td></tr>
<tr><th>datn</th>
<tr><th>fmt</th><td>Datetime format string to use for creating <i>%dat</i>.</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>%rc</th><td>Return code (optional, output)</td></tr>
 
<tr><th>%dat</th><td>Set to datetime string value, in format specified by <i>fmt</i>, corresponding to <i>datn</i>.</td></tr>
<tr><th>fmt</th>
<td>Datetime format string to use for creating <var class="term">%dat</var>.</td></tr>
 
<tr><th>%rc</th>
<td>Return code (optional, output)</td></tr>
 
<tr><th>%dat</th>
<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 = #DATE2N('8407301230', 'YYMMDDHHMI')
<p class="code">%X = #DATE2N('8407301230', 'YYMMDDHHMI')
%X = %X + 300 * 60 * 60 * 15  /* Add 15 hours
%X = %X + 300 * 60 * 60 * 15  /* Add 15 hours
%X = #N2DATE(%X, 'MM/DD/YY')
%X = #N2DATE(%X, 'MM/DD/YY')
REPORT %X
REPORT %X
</nowiki></p>
</p>
<p>
<b>Errors</b></p>
The possible non-zero values of <var class="term">%rc</var>, or terminating conditions,
are shown below (see the discussion in [[#funerr|Run-time errors during standard #function calls]]):
<table class="thJustBold">
<tr><th>4</th>
<td><var class="term">fmt</var> is not a valid datetime format.</td></tr>


Non-zero values of <i>%rc</i>, or terminating conditions,
<tr><th>8</th>
are shown in the following figure (see the discussion in
<td><var class="term">datn</var> is out of range for <var class="term">fmt</var>.</td></tr>
[[#funerr|Run-time errors during standard #function calls]]).
</table>
In the event of a run-time error:
<ul>
<li>If you specified a <var class="term">%rc</var> in your #function call, it is set to the number above that corresponds to the error, and <var class="term">%dat</var> is set to <var>MISSING</var>. </li>


<b>Errors:</b>
<li>If <var class="term">%rc</var> is absent, <var class="product">Fast/Unload</var> is cancelled with return code 8. </li>
if <i>%rc</i> present, set to corresponding number
</ul>
and set <i>%dat</i> to MISSING;
<p>
if absent, cancel <var class="product">Fast/Unload</var> with return code 8.
<b>Notes</b></p>
<table>
<tr><th>4</th><td><i>fmt</i> is not a valid datetime format.</td></tr>
<tr><th>8</th><td><i>datn</i> is out of range for <i>fmt</i>.</td></tr>
</table>
<p><b>Notes</b></p>
<ul>
<ul>
<li>The inverse of this #function is #DATE2N. </li>
<li>The inverse of this #function is <var>[[#DATE2N: Convert datetime string to number of seconds*300|#DATE2N]]</var>. </li>
<li>[[Fast/Unload datetime processing considerations#dtfmt|Datetime formats]] explains valid datetime formats and valid dates. </li>
<li>[[Fast/Unload datetime processing considerations#dtfmt|Datetime formats]] explains valid datetime formats and valid dates. </li>
</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==
The <var>#ONEOF</var> function determines whether a string is found
<!--Caution: <div> above-->
The #ONEOF function determines whether a string is found
in a delimited list of strings.
in a delimited list of strings.
It requires an input string to search for and a delimited list of
It requires an input string to search for and a delimited list of
Line 1,528: Line 1,737:
It accepts an optional delimiter character, which is used to
It accepts an optional delimiter character, which is used to
separate the strings in the list.
separate the strings in the list.
<p class="code"><nowiki>%test = #ONEOF(str, list, delim)
<p class="syntax"><span class="term">%test</span> = #ONEOF(<span class="term">str, list, delim</span>)
</nowiki></p>
</p>
Where:
Where:
<table>
<table>
<tr><th>str</th><td>String to find; required.</td></tr>
<tr><th>str</th>
<tr><th>list</th><td>String containing words to be searched within; required.</td></tr>
<td>String to find; required.</td></tr>
<tr><th>delim</th><td>Character used to separate strings in <i>list</i>; optional. Default is semi-colon (<code>;</code>).</td></tr>
 
<tr><th>%test</th><td>Set to 1 if <i>str</i> is one of the strings in <i>list</i>, delimited by <i>delim</i>. Otherwise, <i>%test</i> is set to 0.</td></tr>
<tr><th>list</th>
<td>String containing words to be searched within; required.</td></tr>
 
<tr><th>delim</th>
<td>Character used to separate strings in <var class="term">list</var>; optional. Default is semicolon (<tt>;</tt>).</td></tr>
 
<tr><th>%test</th>
<td>Set to 1 if <var class="term">str</var> is one of the strings in <var class="term">list</var>, delimited by <var class="term">delim</var>. Otherwise, <var class="term">%test</var> is set to 0.</td></tr>
</table>
</table>


<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,557: Line 1,773:


<ul>
<ul>
<li><i>Delim</i> supplied, and length not 1. </li>
<li><var class="term">delim</var> supplied, and length not 1. </li>
</ul>
</ul>


<p><b>Notes</b></p>
<p>
<b>Notes</b></p>
<ul>
<ul>
<li>If argument 1 (<i>str</i>) contains <i>delim</i>, 0 is returned. </li>
<li>If argument 1 <var class="term">str</var>) contains <i>delim</i>, 0 is returned. </li>


<li>If argument 2 (<i>list</i>) is the null string, 0 is returned. </li>
<li>If argument 2 (<var class="term">list</var>) is the null string, 0 is returned. </li>


<li>If argument 1 (<i>str</i>) is the null string, 1 is returned if,
<li>If argument 1 (<var class="term">str</var>) is the null string, 1 is returned if,
and only if, there is a leading, trailing, or two adjacent copies of,
and only if, there is a leading, trailing, or two adjacent copies of,
<i>delim</i>. </li>
<var class="term">delim</var>. </li>


<li>This #function is similar to the #FIND function ([[##find|#FIND: Word position of one word sequence within another]]).
<li>This #function is similar to the <var>#FIND</var> function ([[##find|#FIND: Word position of one word sequence within another]]).
Note, however, that both #FIND and #ONEOF are inferior to the
Note, however, that both <var>#FIND</var> and <var>#ONEOF</var> are inferior to the
SELECT statement, when the only purpose is to test whether an
<var>SELECT</var> statement, when the only purpose is to test whether an
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.
</p>
   
   
<div id="#pad"></div>
==<b id="#pad"></b>#PAD: Final substring, preceded by pad characters to specified length==
==#PAD: Final substring, preceded by pad characters to specified length==
The <var>#PAD</var> function returns a padded final substring from a source string.
<!--Caution: <div> above-->
It expects a source string argument and a numeric length of the output string. It accepts an optional pad character.
<var>#PAD</var> returns the string that ends at the last position
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.
<nowiki>#PAD</nowiki> 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 <i>length</i> 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="code"><nowiki>%out = #PAD(str, pad, len)
</p>
</nowiki></p>
Where:
Where:
<table>
<table>
<tr><th>str</th><td>Source string.</td></tr>
<tr><th>str</th>
<tr><th>pad</th><td>Optional pad character. Default is blank. If supplied, must be a string of length 1.</td></tr>
<td>Source string.</td></tr>
<tr><th>len</th><td>Length of the output string. Must be numeric >= 0.</td></tr>
 
<tr><th>%out</th><td>If <i>len</i> is greater then #LEN(<i>str</i>):  
<tr><th>pad</th>
<td>Optional pad character. Default is blank. If supplied, must be a string of length 1.</td></tr>
 
<tr><th>len</th>
<td>Length of the output string. Must be numeric and greater than or equal to 0.</td></tr>
 
<tr><th>%out</th>
<td>If <var class="term">len</var> is greater then <code>#LEN(<i>str</i>)</code>:  
<ul>
<ul>
<li><i>len</i> - <nowiki>#LEN</nowiki>(<i>str</i>) copies of the pad character, followed by all of <i>str</i> </li>  
<li><code><i>len</i>-#LEN(<i>str</i>)</code> copies of the pad character, followed by all of <var class="term">str</var> </li>  
</ul>  
</ul>  
<p>Otherwise:</p>   
<p>
Otherwise:</p>   
<ul>
<ul>
<li>substring from <i>str</i> starting at position #LEN(<i>str</i>) - <i>len+1</i> with length <i>len</i> </li>
<li>substring from <var class="term">str</var> starting at position <code>#LEN(<i>str</i>)-<i>len+1</i></code> with length <var class="term">len</var> </li>
</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,621: Line 1,839:
</p>
</p>
<ul>
<ul>
<li><i>Len</i> not numeric, or less than 0. </li>
<li><var class="term">len</var> not numeric, or less than 0. </li>
<li><i>Pad</i> supplied, and length not 1. </li>
<li><var class="term">pad</var> supplied, and length not 1. </li>
</ul>
</ul>


<p><b>Notes</b></p>
<p>
<b>Notes</b></p>
<ul>
<ul>
<li>This is the same as the #RIGHT function, except for the order of
<li>This is the same as the <var>#RIGHT</var> function, except for the order of
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>
==<b id="#padr"></b>#PADR: Initial substring, followed by pad characters to specified length==
==#PADR: Initial substring, followed by pad characters to specified length==
The <var>#PADR</var> function returns a padded initial substring from a source string.
<!--Caution: <div> above-->
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 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.
<nowiki>#PADR</nowiki> returns the string that begins at the first position
<var>#PADR</var> returns the string that begins at the first 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 first <i>length</i> characters of the source are returned.
the first <var class="term">length</var> characters of the source are returned.
Otherwise, the source string is padded to the output length by following it
Otherwise, the source string is padded to the output length by following it
with sufficient copies of the pad character.
with sufficient copies of the pad character.
<p class="code"><nowiki>%out = #PADR(str, pad, len)
<p class="syntax"><span class="term">%out</span> = #PADR(<span class="term">str, pad, len</span>)
</nowiki></p>
</p>
Where:
Where:
<table>
<table>
<tr><th>str</th><td>Source string.</td></tr>
<tr><th>str</th>
<tr><th>pad</th><td>Optional pad character. Default is blank. If supplied, must be a string of length 1.</td></tr>
<td>Source string.</td></tr>
<tr><th>len</th><td>Length of the output string. Must be numeric >= 0.</td></tr>
 
<tr><th>%out</th><td>If <i>len</i> is greater then #LEN(<i>str</i>):  
<tr><th>pad</th>
<td>Optional pad character. Default is blank. If supplied, must be a string of length 1.</td></tr>
 
<tr><th>len</th>
<td>Length of the output string. Must be numeric and greater than or equal to 0.</td></tr>
 
<tr><th>%out</th>
<td>If <var class="term">len</var> is greater then <code>#LEN(<i>str</i>)</code>:  
<ul>
<ul>
<li>all of <i>str</i>, followed by <i>len</i> - <nowiki>#LEN</nowiki>(<i>str</i>) copies of the pad character  </li>
<li>all of <var class="term">str</var>, followed by <code><i>len</i>-#LEN(<i>str</i>)</code> copies of the pad character  </li>
</ul>  
</ul>  
<p>Otherwise:
<p>
Otherwise:
</p>   
</p>   
<ul>
<ul>
<li>substring from <i>str</i> starting at position 1 with length <i>len</i> </li>  
<li>substring from <var class="term">str</var> starting at position 1 with length <var class="term">len</var> </li>  
</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,675: Line 1,897:
code of 8 when:</p>
code of 8 when:</p>
<ul>
<ul>
<li><i>Len</i> not numeric, or less than 0. </li>
<li><var class="term">len</var> not numeric, or less than 0. </li>
<li><i>Pad</i> supplied, and length not 1. </li>
<li><var class="term">pad</var> supplied, and length not 1. </li>
</ul>
</ul>


<p><b>Notes</b></p>
<p>
<b>Notes</b></p>
<ul>
<ul>
<li>This is the same as the #LEFT function, except for the order of
<li>This is the same as the <var>#LEFT</var> function, except for the order of
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>
<p>
This #function is new in <var class="product">Fast/Unload</var> version 4.0.
<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>
This #function is new in <var class="product">Fast/Unload</var> version 4.6.
</p>
</p>


==#REVERSE: Get reverse of string==
==#REVERSE: Get reverse of string==
The #REVERSE function returns a copy of the input string, with the order of
The <var>#REVERSE</var> function returns a copy of the input string, with the order of
the bytes reversed.
the bytes reversed.
It expects a source string argument.
It expects a source string argument.
<p class="code"><nowiki>%out = #REVERSE(str)
<p class="syntax"><span class="term">%out</span> = #REVERSE(<span class="term">str</span>)
</nowiki></p>
</p>
Where:
Where:
<table>
<table>
<tr><th>str</th><td>Source string; required.</td></tr>
<tr><th>str</th>
<tr><th>%out</th><td>Copy of <i>str</i>, with all the last input byte first, followed by the next to last input byte, etc.</td></tr>
<td>Source string; required.</td></tr>
 
<tr><th>%out</th>
<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>
<p>This #function has no cancelling conditions.
<p>
This #function has no cancelling conditions.
</p>
</p>
<p>This #function is new in <var class="product">Fast/Unload</var> version 4.0.
 
</p>
==<b id="#right"></b>#RIGHT: Final substring, preceded by pad characters to specified length==
The <var>#RIGHT</var> function returns a padded final substring from a source
<div id="#right"></div>
string. It expects a source string argument and a numeric length of the output string.
==#RIGHT: Final substring, preceded by pad characters to specified length==
It accepts an optional pad character.  
<!--Caution: <div> above-->
<p>
<var>#RIGHT</var> returns the string that ends at the last position of the source string and is of the specified output 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.
<nowiki>#RIGHT</nowiki> 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,
If the output length is less than or equal to the length of the source string,
the last <i>length</i> 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 class="syntax"><span class="term">%out</span> = #RIGHT(<span class="term">str, len, pad</span>)
<p class="code"><nowiki>%out = #RIGHT(str, len, pad)
</p>
</nowiki></p>
Where:
Where:
<table>
<table>
<tr><th>str</th><td>Source string.</td></tr>
<tr><th>str</th>
<tr><th>len</th><td>Length of the output string.</td></tr>
<td>Source string.</td></tr>
<tr><th>pad</th><td>Optional pad character. Default is blank. If supplied, must be a string of length 1. Must be numeric >= 0.</td></tr>
 
<tr><th>%out</th><td>If <i>len</i> is greater then #LEN(<i>str</i>):  
<tr><th>len</th>
<td>Length of the output string.</td></tr>
 
<tr><th>pad</th>
<td>Optional pad character. Default is blank. If supplied, must be a string of length 1. Must be numeric and greater than zero.</td></tr>
 
<tr><th>%out</th>
<td>If <var class="term">len</var> is greater then <code>#LEN(<i>str</i>)</code>:  
<ul>
<ul>
<li><i>len</i> - <nowiki>#LEN</nowiki>(<i>str</i>) copies of the pad character, followed by all of <i>str</i> </li>
<li><code><i>len</i>-#LEN(<i>str</i>)</code> copies of the pad character, followed by all of <var class="term">str</var> </li>
</ul>  
</ul>  
<p>
<p>
Otherwise:</p>   
Otherwise:</p>   
<ul>
<ul>
<li>substring from <i>str</i> starting at position #LEN(<i>str</i>) - <i>len+1</i> with length <i>len</i> </li>  
<li>substring from <var class="term">str</var> starting at position <code>#LEN(<i>str</i>)-<i>len+1</i></code> with length <var class="term">len</var> </li>  
</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,746: 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><i>Len</i> not numeric, or less than 0. </li>
<li><var class="term">len</var> not numeric, or less than 0. </li>
<li><i>Pad</i> supplied, and length not 1. </li>
<li><var class="term">pad</var> supplied, and length not 1. </li>
</ul>
</ul></li>


<p><b>Notes</b></p>
<li><var>#RIGHT</var> is the same as the <var>#PAD</var> function, except for the order of
<ul>
<li>This is the same as the #PAD function, except for the order of
the arguments (see [[##pad|#PAD: Final substring, preceded by pad characters to specified length]]). </li>
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>
<p>
This #function is new in <var class="product">Fast/Unload</var> version 4.0.
Where:</p>
</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>
<b>Notes</b></p>
<ul>
<li>SHA (Secure Hash Algorithm) is a set of cryptographic hashing functions, and
<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>


==#SNDX: Create SOUNDEX code for string==
==#SNDX: Create SOUNDEX code for string==
The #SNDX function calculates a <b>SOUNDEX</b> code for a
The <var>#SNDX</var> function calculates a <code>SOUNDEX</code> code for a
string, producing the same result as the <var class="product">Model 204</var> $SNDX function.
string, producing the same result as the <var class="product">Model 204</var> <var>[[$Sndx]]</var> function.
It expects a single argument and returns the <b>SOUNDEX</b>
It expects a single argument and returns the SOUNDEX code for the string value of the argument.
code for the string value of the argument.
<p class="syntax"><span class="term">%out</span> = #SNDX(<span class="term">str</span>)
<p class="code"><nowiki>%out = #SNDX(str)
</p>
</nowiki></p>
Where:
Where:
<table>
<table>
<tr><th>str</th><td>String, presumed to contain a name.</td></tr>
<tr><th>str</th>
<tr><th>%out</th><td>Set to the <b>SOUNDEX</b> code corresponding to <i>str</i>.</td></tr>
<td>String, presumed to contain a name.</td></tr>
 
<tr><th>%out</th>
<td>Set to the SOUNDEX code corresponding to <var class="term">str</var>.</td></tr>
</table>
</table>
<p>For example, the following fragment will build values for
<p>
an INVISIBLE KEY field which is the $SNDX value of the
<b>Examples</b>
field NAME:
</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>:
</p>
</p>
<p class="code"><nowiki>UAI OINDEX
<p class="code"><nowiki>UAI OINDEX
Line 1,786: Line 2,096:
END FOR
END FOR
</nowiki></p>
</nowiki></p>
<p>This #function has no cancelling conditions.
<p>
This #function has no cancelling conditions.
</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==
The <var>#STRIP</var> function removes leading, trailing, or both, copies of a pad
<!--Caution: <div> above-->
character from a string. 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.
The #STRIP function removes leading, trailing, or both, copies of a pad
<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>])
character from a string.
</p>
It requires a string to be stripped.
It accepts an optional specification of which characters to strip
(Leading, Trailing, or Both).
It accepts an optional pad character argument, specifying the character
to be stripped.
<p class="code"><nowiki>%out = #STRIP(str, B|L|T, pad)
</nowiki></p>
Where:
Where:
<table>
<table>
<tr><th>str</th><td>String to be stripped; required.</td></tr>
<tr><th>%out</th>
<tr><th>B|L|T</th><td>Optional indicator of the type of strip: <ul>
<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>
<li>'B...' (any string beginning with uppercase B): to strip <b>B</b>oth leading and trailing pad characters. </li>
<li>'L...' (any string beginning with uppercase L): to strip <b>L</b>eading pad characters only. </li>
<li>'T...' (any string beginning with uppercase T): to strip <b>T</b>railing pad characters only. </li>
</ul>
<p>
Defaults to <b>B</b>.
</p> </td></tr>


<tr><th>%out</th><td>Set to a copy of <i>str</i>, with leading, trailing, or both, as specified, copies of <i>pad</i> removed.</td></tr>
<tr><th>str</th>
<td>String to be stripped; required.</td></tr>
 
<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; defaults to <var>B</var>:
<table class="thJustBold">
<tr class="head"><th>Any string beginning with...</th><th>Action</th></tr>
 
<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>
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>
 
<tr><th>pad</th>
<td>The character to be stripped; optional. Blank is the default.</td></tr>
 
<tr><th>nullval</th>
<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 1,827: Line 2,170:
code of 8 when:</p>
code of 8 when:</p>
<ul>
<ul>
<li><i>B|L|T</i> does not begin with either uppercase B, uppercase L,
<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>
or uppercase T. </li>


<li><i>Pad</i> specified and length is not 1. </li>
<li><var class="term">pad</var> specified and length is not 1. </li>
</ul>
</ul>


<p><b>Notes</b></p>
<p><b>Notes</b></p>
<ul>
<ul>
<li>This #function is similar to the #DEBLANK 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.
 
</p>
==<b id="#substr"></b>#SUBSTR: Substring==
The <var>#SUBSTR</var> function returns a substring from within a source string.
<div id="#substr"></div>
It expects a source string argument and a numeric byte position within the source string.
==#SUBSTR: Substring==
<!--Caution: <div> above-->
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.
It accepts an optional numeric maximum length of the output substring.
<nowiki>#SUBSTR</nowiki> returns the string that begins at the indicated position
<var>#SUBSTR</var> returns the string that begins at the indicated position
of the source string and ends either at the end of the source
of the source string and ends either at the end of the source
string or when the supplied maximum length has been reached.
string or when the supplied maximum length has been reached.
<p class="code"><nowiki>%out = #SUBSTR(str, pos, len)
<p class="syntax"><span class="term">%out</span> = #SUBSTR(<span class="term">str, pos, len</span>)
</nowiki></p>
</p>
Where:
Where:
<table>
<table>
<tr><th>str</th><td>Source string. For <var class="product">Fast/Unload</var> version 4.3 and later. <i>str</i> may be longer than 255 bytes.</td></tr>
<tr><th>str</th>
<tr><th>pos</th><td>Beginning position within the source string for the desired substring. Must be numeric >= 1.</td></tr>
<td>Source string. For <var class="product">Fast/Unload</var> version 4.3 and later. <var class="term">str</var> may be longer than 255 bytes.</td></tr>
<tr><th>len</th><td>Optional maximum length of substring; default is 255. Must be numeric >= 0.</td></tr>
 
<tr><th>%out</th><td>Substring from <i>str</i> starting at position <i>pos</i> with length that is the minimum of <i>len</i> and #LEN(<i>str</i>) +1 - <i>pos</i>.</td></tr>
<tr><th>pos</th>
<td>Beginning position within the source string for the desired substring. Must be numeric and greater than or equal to 1.</td></tr>
 
<tr><th>len</th>
<td>Optional maximum length of substring; default is 255. Must be numeric and greater than or equal to 0.</td></tr>
 
<tr><th>%out</th>
<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):
<p class="code"><nowiki>%LEN = #LEN(%STR)
<p class="code">%LEN = #LEN(%STR)
%RIGHT = %LEN / 2 + 1  /* See note below
%RIGHT = %LEN / 2 + 1  /* See note below
%RIGHT = #SUBSTR(%STR, %RIGHT)
%RIGHT = #SUBSTR(%STR, %RIGHT)
</nowiki></p>
</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 when:
code of 8 when:
<ul>
<ul>
<li><i>Pos</i> not numeric, or less than 1. </li>
<li><var class="term">pos</var> not numeric, or less than 1. </li>
<li><i>Len</i> not numeric, or less than 0. </li>
<li><var class="term">len</var> not numeric, or less than 0. </li>
</ul>
</ul>
<p>
<p>
<b>Notes</b></p>
<b>Notes</b></p>
<ul>
<ul>
<li>You can omit the <code>+</code>&nbsp;<code>1</code> in the "right hand half"
<li>You can omit the <code>+1</code> in the "right-hand half"
example above if you want to include
example above if you want to include
the middle character, but you must check that the string is not shorter
the middle character, but you must check that the string is not shorter
than 2 bytes.
than two bytes.
If it is shorter, omitting the <code>+</code>&nbsp;<code>1</code>
If it is shorter, omitting the <code>+1</code>
will cause your program to terminate, because <i>pos</i>
will cause your program to terminate, because <var class="term">pos</var>
must be 1 or more. </li>
must be 1 or more. </li>


<li>The maximum length of <i>%out</i> is
<li>The maximum length of <var class="term">%out</var> is
<nowiki>#LEN</nowiki>(<i>str</i>)&nbsp;-&nbsp;<i>pos</i>&nbsp;+&nbsp;1. </li>
<code>#LEN(<i>str</i>)-<i>pos</i>+1</code>. </li>


<li>To take an initial or final substring, you can also use the #functions
<li>To take an initial or final substring, you can also use the #functions
Line 1,894: Line 2,239:


==#TIME: Current time and/or date==
==#TIME: Current time and/or date==
The #TIME function returns the current date and time in a
The <var>#TIME</var> function returns the current date and time in a datetime string.
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
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.
program to intercept error conditions.
<p class="code"><nowiki>%tim = #TIME(fmt, %rc)
<p class="syntax"><span class="term">%tim</span> = #TIME(<span class="term">fmt</span>, <span class="term">%rc</span>)
</nowiki></p>
</p>
Where:
Where:
<table>
<table>
<tr><th>fmt</th><td>Optional datetime format string for <i>%tim</i>. Defaults to <b>HH:MI:SS</b>.</td></tr>
<tr><th>fmt</th>
<tr><th>%rc</th><td>Return code (optional, output).</td></tr>
<td>Optional datetime format string for <var class="term">%tim</var>. Defaults to <code>HH:MI:SS</code>.</td></tr>
<tr><th>%tim</th><td>Set to datetime string with current date and time, using <i>fmt</i>.</td></tr>
 
<tr><th>%rc</th>
<td>Return code (optional, output).</td></tr>
 
<tr><th>%tim</th>
<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>
in the last occurrence of the REORG_TIME field:
<b>Examples</b>
<p class="code"><nowiki>ADD REORG_TIME = #TIME()
</nowiki></p>
<p>Non-zero values of <i>%rc</i>, or terminating conditions,
are shown in the following figure (see the discussion in
[[#funerr|Run-time errors during standard #function calls]]).
</p>
</p>
<p><b>Errors:</b>
The following fragment stores the current time
in the last occurrence of the <code>REORG_TIME</code> field:
<p class="code">ADD REORG_TIME = #TIME()
</p>
</p>
if <i>%rc</i> present, set to corresponding number
<p>
and set <i>%tim</i> to MISSING;
<b>Errors</b></p>
if absent, cancel <var class="product">Fast/Unload</var> with return code 8.
The possible non-zero values of <var class="term">%rc</var>, or terminating conditions,
are shown below (see the discussion in [[#funerr|Run-time errors during standard #function calls]]):
<table>
<table class="thJustBold">
<tr><th>4</th><td><i>fmt</i> is not a valid datetime format.</td></tr>
<tr><th>4</th>
<td><var class="term">fmt</var> is not a valid datetime format.</td></tr>
</table>
</table>
<p><b>Notes</b></p>
In the event of a run-time error:
<ul>
<li>If you specified a <var class="term">%rc</var> in your #function call, it is set to the number above that corresponds to the error, and <var class="term">%tim</var> is set to <var>MISSING</var>. </li>
 
<li>If <var class="term">%rc</var> is absent, <var class="product">Fast/Unload</var> is cancelled with return code 8. </li>
</ul>
<p>
<b>Notes</b></p>
<ul>
<ul>
<li>The only difference between #TIME and #DATE is the default value
<li>The only difference between <var>#TIME</var> and <var>#DATE</var> is the default value
for <i>fmt</i>. </li>
for <var class="term">fmt</var>. </li>
<li>[[Fast/Unload datetime processing considerations#dtfmt|Datetime formats]] explains valid datetime formats. </li>
<li>[[Fast/Unload datetime processing considerations#dtfmt|Datetime formats]] explains valid datetime formats. </li>
</ul>
</ul>


==#TRANSLATE: Change characters of string using from/to pairings==
==#TRANSLATE: Change characters of string using from/to pairings==
The #TRANSLATE function returns a copy of the input string, with all characters
The <var>#TRANSLATE</var> function returns a copy of the input string, with all characters
which are contained in the input table translated to the corresponding characters
which are contained in the input table translated to the corresponding characters
in the output table.
in the output table.
It expects a source string argument, and at least one of 3 optional string
It expects a source string argument, and at least one of three optional string arguments.
arguments.
It accepts optional output table, input table, and pad character (used
It accepts optional
output table, input table, and pad character (used
to extend the output table if it is shorter than the input table).
to extend the output table if it is shorter than the input table).
<p class="code"><nowiki>%out = #TRANSLATE(str, tbl_out, tbl_in, pad)
<p class="syntax"><span class="term">%out</span> = #TRANSLATE(<span class="term">str, tbl_out, tbl_in, pad</span>)
</nowiki></p>
</p>
Where:
Where:
<table>
<table>
<tr><th>str</th><td>Source string; required.</td></tr>
<tr><th>str</th>
<tr><th>tbl_out</th><td>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 <i>tbl_in</i>.</td></tr>
<td>Source string; required.</td></tr>
<tr><th>tbl_in</th><td>String of "from" characters, optional. Defaults to 256 characters consisting of all byte values, in order, that is, X'00010203...FCFDFEFF'.</td></tr>
 
<tr><th>pad</th><td>Pad character for <i>tbl_out</i> (optional, must be length 1). Default blank.</td></tr>
<tr><th>tbl_out</th>
<tr><th>%out</th><td>Copy of <i>str</i>, with all characters which are contained in the input table translated to the corresponding characters in the output table.</td></tr>
<td>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 <var class="term">tbl_in</var>.</td></tr>
 
<tr><th>tbl_in</th>
<td>String of "from" characters, optional. Defaults to 256 characters consisting of all byte values, in order, that is, <code>X'00010203...FCFDFEFF'</code>.</td></tr>
 
<tr><th>pad</th>
<td>Pad character for <var class="term">tbl_out</var> (optional, must be length 1). Default blank.</td></tr>
 
<tr><th>%out</th>
<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 1,962: Line 2,323:
code of 8 when:</p>
code of 8 when:</p>
<ul>
<ul>
<li>Only <i>str</i> argument supplied. </li>
<li>Only <var class="term">str</var> argument supplied. </li>
<li><i>Pad</i> supplied, and length not 1. </li>
<li><var class="term">pad</var> supplied, and length not 1. </li>
</ul>
</ul>
<p>
<p>
<b>Notes</b></p>
<b>Notes</b></p>
<ul>
<ul>
<li>As a consequence of the default rules, if neither <i>tbl_out</i>
<li>As a consequence of the default rules, if neither <var class="term">tbl_out</var>
nor <i>tbl_in</i> are supplied, <i>%out</i> is set to
nor <var class="term">tbl_in</var> are supplied, <var class="term">%out</var> is set to
as many copies of <i>pad</i> as #LEN(<i>str</i>). </li>
as many copies of <var class="term">pad</var> as <code>#LEN(<i>str</i>)</code>. </li>


<li>If a character occurs more than once in <i>tbl_in</i>,
<li>If a character occurs more than once in <var class="term">tbl_in</var>,
all instances of it after the first are ignored. </li>
all instances of it after the first are ignored. </li>


<li>As noted, the default <i>tbl_in</i> is a <b>256</b> byte
<li>As noted, the default <var class="term">tbl_in</var> is a <code>256</code> byte
string; it is not possible to specify such a value in <var class="product">Fast/Unload</var>.
string. It is not possible to specify such a value in <var class="product">Fast/Unload</var>.
If you want to specify a translation for all 256 characters, you
If you want to specify a translation for all 256 characters, you can do the following:
can do the following:
<p class="code"><nowiki>%TBL_OUT = ...  /* A 255 byte value
<p class="code"><nowiki>%TBL_OUT = ...  /* A 255 byte value
%TBL_FF  = ...  /* Value that X'FF' translates to
%TBL_FF  = ...  /* Value that X'FF' translates to
Line 1,984: 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==
The #UPCASE function returns a copy of the input string, with all lowercase
The <var>#UPCASE</var> function returns a copy of the input string, with all lowercase
EBCDIC letters changed to the corresponding uppercase letters.
EBCDIC letters changed to the corresponding uppercase letters.
It expects a source string argument.
It expects a source string argument.
<p class="code"><nowiki>%out = #UPCASE(str)
<p class="syntax"><span class="term">%out</span> = #UPCASE(<span class="term">str</span>)
</nowiki></p>
</p>
Where:
Where:
<table>
<table>
<tr><th>str</th><td>Source string; required.</td></tr>
<tr><th>str</th>
<tr><th>%out</th><td>Copy of <i>str</i>, with all lowercase EBCDIC letters changed to their uppercase EBCDIC equivalents.</td></tr>
<td>Source string; required.</td></tr>
 
<tr><th>%out</th>
<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>


==#VERPOS: Position in string of character not in or in list==
==#VERPOS: Position in string of character not in or in list==
The #VERPOS function scans a search string from an optional starting
The <var>#VERPOS</var> function scans a search string from an optional starting
position and then finds either the first character that is <b>N</b>ot
position and then finds either of these:
in a list of target characters, or the first character that
<ul>
<b>M</b>atches a character in a list of target characters.
<li>The first character that is <b>N</b>ot in a list of target characters. </li>
It expects a string argument that is searched and a string comprising
 
the target characters.
<li>The first character that <b>M</b>atches a character in a list of target characters. </li>
It accepts an optional argument indicating the type of search to perform
</ul>
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.
and an optional position at which to start the search.
<nowiki>#VERPOS</nowiki> returns the starting position of the identified character, or
<var>#VERPOS</var> returns the starting position of the identified character, or
0 as follows:
0 as follows:
<ul>
<ul>
Line 2,030: Line 2,395:
or 0 if no characters in the search string are in the target string. </li>
or 0 if no characters in the search string are in the target string. </li>
</ul>
</ul>
<p class="code"><nowiki>%opos = #VERPOS(search, target, NorM, pos)
<p class="syntax"><span class="term">%opos</span> = #VERPOS(<span class="term">search, target, NorM, pos</span>)
</nowiki></p>
</p>
Where:
Where:
<table>
<table>
<tr><th>search</th><td>String to be searched.</td></tr>
<tr><th>search</th>
<tr><th>target</th><td>String containing set of target characters.</td></tr>
<td>String to be searched.</td></tr>
<tr><th>NorM</th><td>Optional indicator of the type of search being formed:  
 
<tr><th>target</th>
<td>String containing set of target characters.</td></tr>
 
<tr><th>NorM</th>
<td>Optional indicator of the type of search being formed:  
<ul>
<ul>
<li>'N...' (any string beginning with uppercase N): to find position of first character of <i>search</i> not present in <i>target</i>. </li>
<li><code>N...</code> (any string beginning with uppercase <code>N</code>): to find position of first character of <var class="term">search</var> not present in <var class="term">target</var>. </li>
<li>'M...' (any string beginning with uppercase M): to find position of first character of <i>search</i> present in <i>target</i>. </li>
 
<li><code>M...</code> (any string beginning with uppercase <code>M</code>): to find position of first character of <var class="term">search</var> present in <var class="term">target</var>. </li>
</ul>  
</ul>  
<p>Defaults to <b>N</b>.
<p>
Defaults to <code>N</code>.
</p> </td></tr>
</p> </td></tr>


<tr><th>pos</th><td>Optional position within <i>search</i> to begin scanning. Must be a positive numeric value, default is 1.</td></tr>
<tr><th>pos</th>
<td>Optional position within <var class="term">search</var> to begin scanning. Must be a positive numeric value, default is 1.</td></tr>


<tr><th>%opos</th><td>Set to position of first character in <i>search</i> that is not in ('N') or is in ('M') <i>target</i>, at or after the position identified by <i>pos</i>.</td></tr>
<tr><th>%opos</th>
<td>Set to position of first character in <var class="term">search</var> that is not in (<code>N</code>) or that is in (<code>M</code>) <var class="term">target</var>, at or after the position identified by <var class="term">pos</var>.</td></tr>
</table>
</table>
<p>Examples:
<p>
<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,062: Line 2,437:
code of 8 when:</p>
code of 8 when:</p>
<ul>
<ul>
<li><i>NorM</i> does not begin with either uppercase N or uppercase M. </li>
<li><var class="term">NorM</var> does not begin with either uppercase <code>N</code> or uppercase <code>M</code>. </li>
<li><i>Pos</i> not numeric, or less than 1. </li>
<li><var class="term">pos</var> not numeric, or less than 1. </li>
</ul>
</ul>
<p>
<p>
<b>Notes</b></p>
<b>Notes</b></p>
<ul>
<ul>
<li>If <i>search</i> is null, #VERPOS returns 0, as long as the
<li>If <var class="term">search</var> is null, <var>#VERPOS</var> returns 0, as long as the
other arguments are not in error.
other arguments are not in error.
If <i>pos</i> is greater than #LEN(<i>search</i>), #VERPOS
If <var class="term">pos</var> is greater than <code>#LEN(<i>search</i>)</code>, <var>#VERPOS</var>
returns 0. </li>
returns 0. </li>


<li>If <i>search</i> is non-null and <i>target</i>
<li>If <var class="term">search</var> is non-null and <var class="term">target</var>
is null, #VERPOS returns 0 if <i>NorM</i> starts with 'M',
is null, <var>#VERPOS</var> returns 0 if <var class="term">NorM</var> starts with <code>M</code>.
otherwise #VERPOS returns :DT.<i>pos</i>. </li>
Otherwise <var>#VERPOS</var> returns <var class="term">pos</var>. </li>


<li>The function which performs this service is usually called
<li>The function that performs this service is usually called
"verify", but <code>#VERPOS</code> is used to distinguish it from
"verify", but <var>#VERPOS</var> is used to distinguish it from
the SOUL $Verify function:
the SOUL <var>$Verify</var> function:
<ul>
<ul>
<li>$VERIFY has only a "Boolean" (0 or 1) return; #VERPOS returns a
<li><var>[[$Verify]]</var> has only a "Boolean" (0 or 1) return; <var>#VERPOS</var> returns a
position or 0 to indicate search "failed". </li>
position or 0 to indicate search "failed." </li>


<li>$VERIFY only has a "nomatch" type of search. </li>
<li><var>$Verify</var> only has a "nomatch" type of search. </li>


<li>$VERIFY does not have a <i>pos</i> argument. </li>
<li><var>$Verify</var> does not have a <var class="term">pos</var> argument. </li>


<li>$VERIFY returns 0 if there is a character in <i>search</i>
<li><var>$Verify</var> returns 0 if there is a character in <var class="term">search</var>
which is not in <i>target</i>; #VERPOS (Nomatch)
that is not in <var class="term">target</var>. <code>#VERPOS(Nomatch)</code>
returns 0 if there is <i>no</i> such character. </li>
returns 0 if there is <var class="term">no</var> such character. </li>


<li>$VERIFY returns "some character in <i>search</i>
<li><var>$Verify</var> returns "some character in <var class="term">search</var>
is not in <i>target</i>" (0) if <i>search</i> is null and
is not in <var class="term">target</var>" (0) if <var class="term">search</var> is null and
<i>target</i> is not null; #VERPOS returns "all characters in
<var class="term">target</var> is not null. <var>#VERPOS</var> returns "all characters in
<i>search</i> are in <i>target</i>" if <i>search</i> is null,
<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>
whether or not <i>target</i> 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>


==#WORD: Return nth blank-delimited word from string==
==#WORD: Return nth blank-delimited word from string==
The #WORD function returns the designated
The <var>#WORD</var> function returns the designated delimited word within a string.
blank-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.
It requires an input string and a word number within the string.
 
<p class="code"><nowiki>%out = #WORD(str, word)
<p class="syntax"><span class="term">%out</span> = #WORD(<span class="term">str</span>, <span class="term">word</span>, [<span class="term">delimiter</span>])
</nowiki></p>
</p>
Where:
Where:
<table>
<table>
<tr><th>str</th><td>String containing blank-delimited words; required.</td></tr>
<tr><th>str</th>
<td>String containing blank-delimited words; required.</td></tr>


<tr><th>word</th><td>Number of word within <i>str</i> to return; required. Must be numeric greater than or equal to 1.</td></tr>
<tr><th>word</th>
<td>Number of word within <var class="term">str</var> to return; required. Must be numeric greater than or equal to 1.</td></tr>


<tr><th>%out</th><td>Set to the <i>word</i>th blank-delimited word within <i>str</i>. If <i>word</i> is greater than the number of words in <i>str</i>, the null string is returned.</td></tr>
<tr><th>delimiter</th>
<td>Optional one-character delimiter to separate words within <var class="term">str</var>. The default delimiter is a blank.
<p>
This argument is available as of version 4.6 of <var class="product">Fast/Unload</var>. </p></td></tr>
 
<tr><th>%out</th>
<td>Set to the <var class="term">word</var>th blank-delimited word within <var class="term">str</var>. If <var class="term">word</var> is greater than the number of words in <var class="term">str</var>, the null string is returned.</td></tr>
</table>
</table>
<p>Examples:
<p>
<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>
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:</p>
code of 8 when:</p>
<ul>
<ul>
<li><i>word</i> is not numeric, or less than 1. </li>
<li><var class="term">word</var> is not numeric, or less than 1. </li>
</ul>
</ul>


<p><b>Notes</b></p>
<p>
<b>Notes</b></p>
<ul>
<ul>
<li>The User Language $WORD function also has an optional
<li>The SOUL <var>[[$Word]]</var> function also has an optional
delimiter character argument, and its "<i>word</i>"
delimiter character argument, and its "<i>word</i>" argument is the third argument. </li>
argument is argument number 3. </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==
The #WORDS function returns the number of
The <var>#WORDS</var> function returns the number of delimited words in a string.
blank-delimited word 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.
It requires an input string.
 
<p class="code"><nowiki>%count = #WORDS(str)
<p class="syntax"><span class="term">%count</span> = #WORDS(<span class="term">str</span>, [<span class="term">delimiter</span>])
</nowiki></p>
</p>
Where:
Where:
<table>
<table>
<tr><th>str</th><td>String containing blank-delimited words; required.</td></tr>
<tr><th>str</th>
<tr><th>%count</th><td>Set to number of word within <i>str</i>.</td></tr>
<td>String containing delimited words; required.</td></tr>
 
<tr><th>delimiter</th>
<td>Optional one-character delimiter to separate words within <var class="term">str</var>. The default delimiter is a blank.
<p>
This argument is available as of version 4.6 of <var class="product">Fast/Unload</var>. </p></td></tr>
 
<tr><th>%count</th>
<td>Set to number of words within <var class="term">str</var>.</td></tr>
</table>
</table>
<p>Examples:
<p>
<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
#WORDS('ABC')       returns  1
#WORDS('ABC')                       returns  1
#WORDS('  ')       returns  0
#WORDS('  ')                       returns  0
#WORDS('The answer: Rosebud', ':')  returns  2
</nowiki></p>
</nowiki></p>
<p>This #function has no cancelling conditions.
<p>
This #function has no cancelling conditions.
</p>
</p>
<p>
<p>
<b>Notes</b></p>
<b>Notes</b></p>
<ul>
<ul>
<li>The User Language $WORDS function also has an optional
<li>The SOUL <var>[[$Words]]</var> function also has an optional
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==
The #X2C function converts a string of hexadecimal characters (the
The <var>#X2C</var> function converts a string of hexadecimal characters (the
digits <b>0</b>-<b>9</b> and the letters
digits <code>0-9</code> and the letters <code>A-F</code>) to the corresponding byte string.
<b>A</b>-<b>F</b>) to the corresponding byte string.
Each two characters in the input string become one character in the
Each two characters in the input string become one character in the
result string, with a leading <b>0</b> added to input strings
result string, with a leading <code>0</code> added to input strings
of odd length.
of odd length.
<p class="code"><nowiki>%str = #X2C(hex)
<p class="syntax"><span class="term">%str</span> = #X2C(<span class="term">hex</span>)
</nowiki></p>
</p>
Where:
Where:
<table>
<table>
<tr><th>hex</th><td>String to convert; contains only the characters 0-9 and A-F.</td></tr>
<tr><th>hex</th>
<tr><th>%str</th><td>Set to the string of bytes represented by <i>hex</i>.</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>
<td>Set to the string of bytes represented by <var class="term">hex</var>.</td></tr>
</table>
</table>
For example, in
<p>
<p class="code"><nowiki>%JUNK = #X2C('F1F2F3')
<b>Examples</b></p>
</nowiki></p>
This statement sets <code>%JUNK</code> to the string <code>123</code> (EBCDIC X'F1F2F3'):
%JUNK would be set to the string <b>123</b> (EBCDIC X'F1F2F3'), and in
<p class="code">%JUNK = #X2C('F1F2F3')
</p>
 
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>
%JUNK would be set to EBCDIC X'0102' which is a non-displayable string.
 
<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>Non-hexadecimal digit character in <i>hex</i>. </li>
</ul>
<p><b>Notes</b></p>
<ul>
<ul>
<li>The inverse of this #function is #C2X. </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 <i>hex</i> 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 User Language $X2C function (http://m204wiki.rocketsoftware.com/index.php/$X2C)
requires an even number of characters in <i>hex</i>. </li>


<li>The $X2C function returns the null string if <i>hex</i> has an error. </li>
<li>The <var>$X2C</var> function returns the null string if <var class="term">hex</var> has an error. </li>


<li>The User Language $IHEXA function (http://m204wiki.rocketsoftware.com/index.php/$IHexA)
<li>The SOUL <var>[[$IHexA]]</var> function converts any non-hex characters in <var class="term">hex</var> to 0. </li>
converts any non-hex characters in <i>hex</i> to 0. </li>
</ul>
</ul>


==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