$ResetN: Difference between revisions
m (1 revision) |
No edit summary |
||
(20 intermediate revisions by 3 users not shown) | |||
Line 1: | Line 1: | ||
{{DISPLAYTITLE:$ | {{DISPLAYTITLE:$ResetN}} | ||
<span class="pageSubtitle">Reset or view M204 parameter</span> | <span class="pageSubtitle">Reset or view M204 parameter</span> | ||
<p class=" | <p class="warn"><b>Note:</b> Many $functions have been deprecated in favor of Object Oriented methods. There is no OO equivalent for the <var>$ResetN</var> function.</p> | ||
This [[Calling Sirius Mods $functions|callable]] function retrieves the current value of a <var class="product">Model 204</var> parameter, and it can also change the value of that parameter. Not all parameters are resettable by $ | This [[Calling Sirius Mods $functions|callable]] function retrieves the current value of a <var class="product">Model 204</var> parameter, and it can also change the value of that parameter. Not all parameters are resettable by $ResetN: the supported subset includes only parameters considered useful to change as well as safe to change during evaluation of a <var class="product">SOUL</var> request. | ||
<var>$ | <var>$ResetN</var> accepts one required and two optional arguments, and it returns a numeric value. | ||
==Syntax== | ==Syntax== | ||
<p class="syntax" | <p class="syntax">[%oldval =] $ResetN(parameter, newval, %rc_variable) | ||
</p> | |||
===Syntax terms=== | ===Syntax terms=== | ||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
<tr><th>%oldval</th> | <tr><th>%oldval</th> | ||
<td>The returned value is the current value of <var class="term">parameter</var> (before <var>$ | <td>The returned value is the current value of <var class="term">parameter</var> (before <var>$ResetN</var> changes it). If the <var class="term">parameter</var> is not the name of a parameter supported by <var>$ResetN</var>, the returned value is 0 (if <var class="term">%rc_variable</var> is supplied; otherwise this and all errors cause request cancellation).</td></tr> | ||
<tr><th>parameter</th> | <tr><th>parameter</th> | ||
<td>A string that is the name of the parameter to retrieve (and optionally reset). See the list of allowed parameters in [[#Parameters resettable by $ | <td>A string that is the name of the parameter to retrieve (and optionally reset). See the list of allowed parameters in [[#Parameters resettable by $ResetN|Parameters resettable by $ResetN]]. </td></tr> | ||
<tr><th>newval</th> | <tr><th>newval</th> | ||
Line 24: | Line 24: | ||
<tr><th>%rc_variable</th> | <tr><th>%rc_variable</th> | ||
<td>An optional %variable that is the target for the <var>$ | <td>An optional %variable that is the target for the <var>$ResetN</var> return code. If specified, this %variable is set to one of the return codes shown [[#Return codes|below]]. If this argument is omitted and a condition occurs that is associated with a non-zero return code value, the request is cancelled. | ||
<p> | <p> | ||
This %variable may '''not''' be a <var class="product"> | This %variable may '''not''' be a <var class="product">SOUL</var> [[Classes_and_Objects#Variable_declarations|class variable]]. </p></td></tr> | ||
</table> | </table> | ||
Line 38: | Line 38: | ||
For example, the following fragment will to prevent the <code>M204.0620 FILE OPENED</code> and <code>M204.1203 FILE WAS LAST UPDATED</code> messages from going to the user's terminal: | For example, the following fragment will to prevent the <code>M204.0620 FILE OPENED</code> and <code>M204.1203 FILE WAS LAST UPDATED</code> messages from going to the user's terminal: | ||
<p class="code">%VAL = $ | <p class="code">%VAL = $ResetN('MSGCTL', 2) | ||
OPEN 'MYFILE' PASSWORD 'UPDATE' | OPEN 'MYFILE' PASSWORD 'UPDATE' | ||
%VAL = $ | %VAL = $ResetN('MSGCTL', %VAL) | ||
</p> | </p> | ||
==Parameters resettable by $ | ==Parameters resettable by $ResetN== | ||
In the following list of parameters, the minimum and maximum value is shown. Note that these values may be more strict than the corresponding minimums and maximums allowed by the <var class="product">Model 204</var> <var>RESET</var> command. For example, the <code>RESET ERMX -2</code> command changes <var>ERMX</var> to a value, as shown by the response to the command, of 65534. However, the value of -2 is not "meaningful" for <var>ERMX</var>. To avoid this, an attempt to invoke <code>$ | In the following list of parameters, the minimum and maximum value is shown. Note that these values may be more strict than the corresponding minimums and maximums allowed by the <var class="product">Model 204</var> <var>[[RESET command|RESET]]</var> command. For example, the <code>RESET ERMX -2</code> command changes <var>[[ERMX parameter|ERMX]]</var> to a value, as shown by the response to the command, of 65534. However, the value of -2 is not "meaningful" for <var>ERMX</var>. To avoid this, an attempt to invoke <code>$ResetN('ERMX',-2)</code> is rejected, because -2 is outside the legal range for <var>ERMX</var>. | ||
<p class="note">'''Note: ''' This situation is even more pointed for <var>UDDLPP</var>, which is currently not supported for <var>$ResetN | |||
</var> because there is little reason to change it from within a <var class="product">SOUL</var> request.</p> | |||
The <code>RESET UDDLPP -1</code> command changes <var>[[UDDLPP parameter|UDDLPP]]</var> to a value of 65535, as shown by the response to the command or as returned by <var>$VIEW</var>. However, the <code>RESET UDDLPP 65535</code> command issues an error message and changes <var>UDDLPP</var> to the value of 32767, which is very different from the meaning of -1 for <var>UDDLPP</var>. | |||
The valid parameter names which may be supplied as the <var class="term">parameter</var> argument to <var>$ResetN</var> are shown in the following list, along with the minimum and maximum values and a terse description. | |||
<table> | |||
<tr><th><var>[[ENQRETRY parameter|ENQRETRY]]</var></th> | |||
<td>0..255: Record-locking retry count</td></tr> | |||
<tr><th><var>[[ENQTIME parameter|ENQTIME]]</var></th> | |||
<td>1..60000: Record-locking retry wait time, milliseconds (new in version 7.8, or in 7.7 with zap 77Z299)</td></tr> | |||
<tr><th><var>[[ERCNT parameter|ERCNT]]</var></th> | |||
<td>0..65,535: Error count (provided by the <var class="product">Sirius Mods</var>). (Note that the you can also increment or clear this using <var>[[$ErrSet]]</var>.)</td></tr> | |||
<tr><th><var>[[ERMX parameter|ERMX]]</var></th> | |||
<tr><th | |||
<td>-1..65,534: Maximum number of errors</td></tr> | <td>-1..65,534: Maximum number of errors</td></tr> | ||
<tr><th>FSOUTPUT</th> | |||
<tr><th><var>[[FSOUTPUT parameter|FSOUTPUT]]</var></th> | |||
<td>0..2: Full screen color and highlighting</td></tr> | <td>0..2: Full screen color and highlighting</td></tr> | ||
<tr><th>HDRCTL</th> | |||
<tr><th><var>[[HDRCTL parameter|HDRCTL]]</var></th> | |||
<td>0..255: Header control</td></tr> | <td>0..255: Header control</td></tr> | ||
<tr><th>MBSCAN</th> | |||
<tr><th><var>[[MBSCAN parameter|MBSCAN]]</var></th> | |||
<td>-2,147,483,647..2,147,483,647: Maximum table B to records scan</td></tr> | <td>-2,147,483,647..2,147,483,647: Maximum table B to records scan</td></tr> | ||
<tr><th>MCNCT</th> | |||
<tr><th><var>[[MCNCT parameter|MCNCT]]</var></th> | |||
<td>-2,147,483,647..2,147,483,647: Maximum connect time</td></tr> | <td>-2,147,483,647..2,147,483,647: Maximum connect time</td></tr> | ||
<tr><th>MCPU</th> | |||
<tr><th><var>[[MCPU parameter|MCPU]]</var></th> | |||
<td>-2,147,483,647..2,147,483,647: Maximum CPU time</td></tr> | <td>-2,147,483,647..2,147,483,647: Maximum CPU time</td></tr> | ||
<tr><th>MDKRD</th> | |||
<tr><th><var>[[MDKRD parameter|MDKRD]]</var></th> | |||
<td>-2,147,483,647..2,147,483,647: Maximum disk reads</td></tr> | <td>-2,147,483,647..2,147,483,647: Maximum disk reads</td></tr> | ||
<tr><th>MDKWR</th> | |||
<tr><th><var>[[MDKWR parameter|MDKWR]]</var></th> | |||
<td>-2,147,483,647..2,147,483,647: Maximum disk writes</td></tr> | <td>-2,147,483,647..2,147,483,647: Maximum disk writes</td></tr> | ||
<tr><th>MOUT</th> | |||
<tr><th><var>[[MOUT parameter|MOUT]]</var></th> | |||
<td>-2,147,483,647..2,147,483,647: Maximum output lines</td></tr> | <td>-2,147,483,647..2,147,483,647: Maximum output lines</td></tr> | ||
<tr><th>MSGCTL</th> | |||
<tr><th><var>[[MSGCTL parameter|MSGCTL]]</var></th> | |||
<td>0..255: Message printing options</td></tr> | <td>0..255: Message printing options</td></tr> | ||
<tr><th>MUDD</th> | |||
<tr><th><var>[[MUDD parameter|MUDD]]</var></th> | |||
<td>-2,147,483,647..2,147,483,647: Maximum USE dataset lines | <td>-2,147,483,647..2,147,483,647: Maximum USE dataset lines | ||
</td></tr></table> | </td></tr></table> | ||
Some of the parameters supported by <var>$ | Some of the parameters supported by <var>$ResetN</var> are treated as "hexadecimal" parameters by the <var class="product">Model 204</var> <var>RESET</var> command. For example, the <code>VIEW HDRCTL</code> command displays a result such as <code>X'01'</code>. It so happens that this is a moot point with any of these "hex" parameters currently supported by <var>$ResetN</var>, because the maximum value they may have is 7, which is the same in base 10 and base 16. | ||
<p> | <p> | ||
However, if <var>$ | However, if <var>$ResetN</var> is extended to support, for example, <var>UDDRFM</var>, you might wish to supply an argument to <var>$ResetN</var> expressed in hex. This could be easily accomplished using the <var>$X2D</var> function. Again, assuming <var>$ResetN</var> were extended to support <var>UDDRFM</var>, you could set the USE dataset record format to variable length records with ASA carriage control with the following statement:</p> | ||
<p class="code">%VAL = $ | <p class="code">%VAL = $ResetN('UDDRFM', $X2D('12')) | ||
</p> | </p> | ||
Line 93: | Line 108: | ||
</ul> | </ul> | ||
==Products authorizing {{PAGENAMEE}}== | ==Products authorizing {{PAGENAMEE}}== | ||
<ul class="smallAndTightList"> | <ul class="smallAndTightList"> | ||
<li>[[Sirius | <li>[[Sirius Functions]]</li> | ||
<li>[[Fast/Unload User Language Interface]]</li> | <li>[[Fast/Unload User Language Interface]]</li> | ||
<li>[[Janus Open Client]]</li> | <li>[[Media:JoclrNew.pdf|Janus Open Client]]</li> | ||
<li>[[Janus Open Server]]</li> | <li>[[Media:JosrvrNew.pdf|Janus Open Server]]</li> | ||
<li>[[Janus Sockets]]</li> | <li>[[Janus Sockets]]</li> | ||
<li>[[Janus Web Server]]</li> | <li>[[Janus Web Server]]</li> | ||
<li> | <li>Japanese functions</li> | ||
<li>[[Sir2000 Field Migration Facility]]</li> | <li>[[Media:SirfieldNew.pdf|Sir2000 Field Migration Facility]]</li> | ||
</ul> | </ul> | ||
[[Category:$Functions|$ | [[Category:$Functions|$ResetN]] |
Latest revision as of 00:16, 11 November 2019
Reset or view M204 parameter
Note: Many $functions have been deprecated in favor of Object Oriented methods. There is no OO equivalent for the $ResetN function.
This callable function retrieves the current value of a Model 204 parameter, and it can also change the value of that parameter. Not all parameters are resettable by $ResetN: the supported subset includes only parameters considered useful to change as well as safe to change during evaluation of a SOUL request.
$ResetN accepts one required and two optional arguments, and it returns a numeric value.
Syntax
[%oldval =] $ResetN(parameter, newval, %rc_variable)
Syntax terms
%oldval | The returned value is the current value of parameter (before $ResetN changes it). If the parameter is not the name of a parameter supported by $ResetN, the returned value is 0 (if %rc_variable is supplied; otherwise this and all errors cause request cancellation). |
---|---|
parameter | A string that is the name of the parameter to retrieve (and optionally reset). See the list of allowed parameters in Parameters resettable by $ResetN. |
newval | An optional numeric value. If specified, the parameter is reset to this value. |
%rc_variable | An optional %variable that is the target for the $ResetN return code. If specified, this %variable is set to one of the return codes shown below. If this argument is omitted and a condition occurs that is associated with a non-zero return code value, the request is cancelled.
This %variable may not be a SOUL class variable. |
Return codes
-1 — Invalid value for parameter 0 — Successful completion 1 — Invalid parameter name
Examples
For example, the following fragment will to prevent the M204.0620 FILE OPENED
and M204.1203 FILE WAS LAST UPDATED
messages from going to the user's terminal:
%VAL = $ResetN('MSGCTL', 2) OPEN 'MYFILE' PASSWORD 'UPDATE' %VAL = $ResetN('MSGCTL', %VAL)
Parameters resettable by $ResetN
In the following list of parameters, the minimum and maximum value is shown. Note that these values may be more strict than the corresponding minimums and maximums allowed by the Model 204 RESET command. For example, the RESET ERMX -2
command changes ERMX to a value, as shown by the response to the command, of 65534. However, the value of -2 is not "meaningful" for ERMX. To avoid this, an attempt to invoke $ResetN('ERMX',-2)
is rejected, because -2 is outside the legal range for ERMX.
Note: This situation is even more pointed for UDDLPP, which is currently not supported for $ResetN because there is little reason to change it from within a SOUL request.
The RESET UDDLPP -1
command changes UDDLPP to a value of 65535, as shown by the response to the command or as returned by $VIEW. However, the RESET UDDLPP 65535
command issues an error message and changes UDDLPP to the value of 32767, which is very different from the meaning of -1 for UDDLPP.
The valid parameter names which may be supplied as the parameter argument to $ResetN are shown in the following list, along with the minimum and maximum values and a terse description.
ENQRETRY | 0..255: Record-locking retry count |
---|---|
ENQTIME | 1..60000: Record-locking retry wait time, milliseconds (new in version 7.8, or in 7.7 with zap 77Z299) |
ERCNT | 0..65,535: Error count (provided by the Sirius Mods). (Note that the you can also increment or clear this using $ErrSet.) |
ERMX | -1..65,534: Maximum number of errors |
FSOUTPUT | 0..2: Full screen color and highlighting |
HDRCTL | 0..255: Header control |
MBSCAN | -2,147,483,647..2,147,483,647: Maximum table B to records scan |
MCNCT | -2,147,483,647..2,147,483,647: Maximum connect time |
MCPU | -2,147,483,647..2,147,483,647: Maximum CPU time |
MDKRD | -2,147,483,647..2,147,483,647: Maximum disk reads |
MDKWR | -2,147,483,647..2,147,483,647: Maximum disk writes |
MOUT | -2,147,483,647..2,147,483,647: Maximum output lines |
MSGCTL | 0..255: Message printing options |
MUDD | -2,147,483,647..2,147,483,647: Maximum USE dataset lines |
Some of the parameters supported by $ResetN are treated as "hexadecimal" parameters by the Model 204 RESET command. For example, the VIEW HDRCTL
command displays a result such as X'01'
. It so happens that this is a moot point with any of these "hex" parameters currently supported by $ResetN, because the maximum value they may have is 7, which is the same in base 10 and base 16.
However, if $ResetN is extended to support, for example, UDDRFM, you might wish to supply an argument to $ResetN expressed in hex. This could be easily accomplished using the $X2D function. Again, assuming $ResetN were extended to support UDDRFM, you could set the USE dataset record format to variable length records with ASA carriage control with the following statement:
%VAL = $ResetN('UDDRFM', $X2D('12'))