$ResetN: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
mNo edit summary
Line 6: Line 6:
This 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">User Language</var> request.  
This 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">User Language</var> request.  


<var>$Resetn</var> accepts one required and two optional arguments, and it returns a numeric value.
<var>$Resetn</var> accepts one required and two optional arguments, and it returns a numeric value.  
 
<ul>
<li>The first argument is a string which 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"]].
<li>The second argument is an optional numeric value. If specified, the parameter is reset to this value.
<li>The third argument is an optional %variable which is the target for the <var>$Resetn</var> return code. If specified, this %variable is set to one of the return codes shown in the table below. If this argument is omitted and a condition occurs that is associated with a non-zero value in the return code table, the request is cancelled.
This %variable may '''not''' be a ''[[Janus SOAP User Language Interface]]'' class variable.
<li>The returned value is the current value of the parameter (before <var>$Resetn</var> changes it). If the first argument is not the name of a parameter supported by $Resetn, the returned value is 0 (if argument 3 is supplied; otherwise this and all errors cause request cancellation).
</ul>
 
<var>$Resetn</var> is callable.
<var>$Resetn</var> is callable.


Line 21: Line 12:
<p class="syntax"><section begin="syntax" /> [%oldval =] $Resetn(parameter, newval, %rc_variable)
<p class="syntax"><section begin="syntax" /> [%oldval =] $Resetn(parameter, newval, %rc_variable)
<section end="syntax" /></p>
<section end="syntax" /></p>
<p class="caption">$Resetn Function
 
</p>
===Syntax terms===
<p class="caption">%oldval is set to the '''parameter''' value before being reset.</p>
<table class="syntaxTable">
<tr><th>%oldval</th>
<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>
<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>
<td>An optional numeric value. If specified, the parameter is reset to this value. </td></tr>
 
<tr><th>%rc_variable</th>
<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 in the table below. If this argument is omitted and a condition occurs that is associated with a non-zero value in the return code table, the request is cancelled.
<p>
This %variable may '''not''' be a <var class="product">[[Janus SOAP User Language Interface]]</var> class variable. </p></td></tr>
</table>


==Error codes==
==Error codes==
<p class="code">  
<p class="code">-1 &mdash; Invalid value for parameter
-1 - Invalid value for parameter
0 &mdash; Successful completion
  0 - Successful completion
1 &mdash; Invalid parameter name
  1 - Invalid parameter name
</p>
<p class="caption">$Resetn return codes (set in argument 3)
</p>
</p>


Line 37: Line 39:
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 = $Resetn('MSGCTL', 2)
<p class="code">%VAL = $Resetn('MSGCTL', 2)
OPEN 'MYFILE' PASSWORD 'UPDATE'
OPEN 'MYFILE' PASSWORD 'UPDATE'
%VAL = $Resetn('MSGCTL', %VAL)
%VAL = $Resetn('MSGCTL', %VAL)
</p>
</p>


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> RESET command. For example, the <tt>RESET ERMX -2</tt> command changes ERRMX 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 <tt>$Resetn('ERMX',-2)</tt> is rejected, because -2 is outside the legal range for ERMX.
==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>ERRMX</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>'''Note: ''' This situation is even more pointed for UDDLPP, which is currently not supported for <var>$Resetn</var> because there's little reason to change it from within a <var class="product">User Language</var> request.</p>  
<p>'''Note: ''' This situation is even more pointed for <var>UDDLPP</var>, which is currently not supported for <var>$Resetn</var> because there's little reason to change it from within a <var class="product">User Language</var> request.</p>  


The <tt>RESET UDDLPP -1</tt> command changes UDDLPP to a value, as shown by the response to the command or as returned by $VIEW, of 65535. However, the <tt>RESET UDDLPP 65535</tt> 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 <code>RESET UDDLPP -1</code> command changes <var>UDDLPP</var> to a value, as shown by the response to the command or as returned by <var>$VIEW</var>, of 65535. 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 first argument to <var>$Resetn</var> are shown in the following list, along with the minimum and maximum values and a terse description. For more information about these parameters, see the <i>[http://www.rocketsoftware.com/m204/products/index/documentation/v7r4/M204-Command-Ref/view Rocket Model 204 Parameter and Command Reference]</i>, except, where indicated, a parameter is not a base <var class="product">Model 204</var> parameter but is one that is delivered with the <var class="product">[[Sirius Mods]]</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. For more information about these parameters, see the <var class="product">[http://www.rocketsoftware.com/m204/products/index/documentation/v7r4/M204-Command-Ref/view Rocket Model 204 Parameter and Command Reference]</var>, except, where indicated, a parameter is not a base <var class="product">Model 204</var> parameter but is one that is delivered with the <var class="product">[[Sirius Mods]]</var>.


==Parameters resettable by $Resetn==
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>ENQRETRY</th>
<tr><th>ENQRETRY</th>
<td>0..255: Number of record locking retries</td></tr>
<td>0..255: Number of record locking retries</td></tr>
<tr><th>ERCNT</th>
<tr><th>ERCNT</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 [[$ErrSet]].)</td></tr>
<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 [[$ErrSet]].)</td></tr>
<tr><th>ERMX</th>
<tr><th>ERMX</th>
<td>-1..65,534: Maximum number of errors</td></tr>
<td>-1..65,534: Maximum number of errors</td></tr>
Line 80: Line 82:
</td></tr></table>
</td></tr></table>


As mentioned, the second argument to <var>$Resetn</var> is the '''numeric''' value to which the parameter should be set. Some of the parameters supported by <var>$Resetn</var> are treated as "hexadecimal" parameters by the <var class="product">Model 204</var> RESET command. For example, the <tt>VIEW&amp;thinsp.HDRCTL</tt> 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 <var>$Resetn</var> is extended to support, for example, UDDRFM, you might wish to supply an argument to <var>$Resetn</var> expressed in hex. This could be easily accomplished using the $X2D function. Again, assuming <var>$Resetn</var> 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:
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>
However, if <var>$Resetn</var> is extended to support, for example, UDDRFM, 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 = $Resetn('UDDRFM', $X2D('12'))
<p class="code">%VAL = $Resetn('UDDRFM', $X2D('12'))
</p>
</p>


See also [[$SirParm]].
==See also==
<ul>
<li><var>[[$SirParm]]</var>
</ul>


This $function is new in Version 6.0.
<ul class="smallAndTightList">
<ul class="smallAndTightList">
<li>[[Sirius functions]]</li>
<li>[[Sirius functions]]</li>

Revision as of 22:54, 23 October 2012

Reset or view M204 parameter

Most Sirius $functions have been deprecated in favor of Object Oriented methods. There is no OO equivalent for the $Resetn function.

This 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 User Language request.

$Resetn accepts one required and two optional arguments, and it returns a numeric value. $Resetn is callable.

Syntax

<section begin="syntax" /> [%oldval =] $Resetn(parameter, newval, %rc_variable) <section end="syntax" />

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 in the table below. If this argument is omitted and a condition occurs that is associated with a non-zero value in the return code table, the request is cancelled.

This %variable may not be a Janus SOAP User Language Interface class variable.

Error 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 ERRMX 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's little reason to change it from within a User Language request.

The RESET UDDLPP -1 command changes UDDLPP to a value, as shown by the response to the command or as returned by $VIEW, of 65535. 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. For more information about these parameters, see the Rocket Model 204 Parameter and Command Reference, except, where indicated, a parameter is not a base Model 204 parameter but is one that is delivered with the Sirius Mods.

ENQRETRY 0..255: Number of record locking retries
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'))

See also

Products authorizing $Resetn