https://m204wiki.rocketsoftware.com/api.php?action=feedcontributions&feedformat=atom&user=Adrianm204wiki - User contributions [en]2026-04-19T13:19:34ZUser contributionsMediaWiki 1.43.1https://m204wiki.rocketsoftware.com/index.php?title=Record_loops&diff=107663Record loops2018-02-28T06:38:45Z<p>Adrian: /* FOR EACH RECORD statement */</p>
<hr />
<div><div class="toclimit-3"><br />
<br />
==Overview==<br />
<p><br />
This page identifies the statements used to create and process record loops. The <var>For Each Record</var> statement initiates a record loop to refer to each record within a set of records, such as one located by a <var>Find</var> statement. </p><br />
<p><br />
A <b>record loop</b> is a portion of a request that executes a series of statements once for each record in a record set before proceeding to other statements in the request.</p><br />
<p><br />
Record loops can be nested (embedded) any number of levels deep. </p><br />
<p><br />
You can also use value loops, index loops, and repeat loops to execute a series of statements. </p><br />
<ul><br />
<li>Value loops perform a loop on a set of values and are discussed in detail in [[Value loops]].</li><br />
<li>Index and repeat index loops (discussed in [[Flow of control in User Language]]) perform a loop on a set of statements.</li><br />
</ul><br />
<br />
===Processing records in order===<br />
<p><br />
The IN ORDER option of the FOR EACH RECORD statement processes records in index order, sort order, or sort key order, without requiring a sort of the records.</p><br />
<br />
===The prefetch feature===<br />
<p><br />
<var class="product">Model&nbsp;204</var> supports a [[#The_prefetch (look-ahead_read) feature|prefetch feature]] (look-ahead read), which can provide performance improvements for applications containing FOR EACH RECORD statements. </p><br />
<br />
===Processing a single record or limited number of records===<br />
<p><br />
The FOR RECORD NUMBER statement provides a very efficient method to retrieve a specified record and initiate a record loop.</p><br />
<p><br />
The FOR <var class="term">k</var> RECORDS statement allows you to indicate a maximum number of times the loop is to be repeated.</p><br />
<br />
===Skip processing===<br />
<p><br />
When you are processing a found set of records in a FOR EACH RECORD loop, you can instruct <var class="product">Model&nbsp;204</var> to skip a specified number of records between successive iterations of the loop. This feature also allows you to process records in a forward or backward direction and, for ordered loops, allows you to process records in descending record number order within each value range.</p><br />
<p><br />
The skip processing feature also gives you the flexibility to vary the number of records skipped, and the direction of the skip, between successive iterations of the loop. For example, between the first and second times through the loop you can skip five records forward. Then, you can again specify the number of records to skip so that between the second and third times through the loop, you skip three records backward, and so on.</p><br />
<br />
===Saving and recalling position in a FOR loop===<br />
<p><br />
The REMEMBER and POSITION statements allow you to store the current processing position in a FOR loop, then recall it at a later time and resume FOR processing where you left off. This technique was developed primarily for use with global found sets and lists, but can be used with non-global found sets and lists as well. See [[Global features#Saving and recalling a POSITION in a FOR loop|Saving and recalling a POSITION in a FOR loop]] for a detailed discussion of this topic.</p><br />
<br />
===PAI INTO statement===<br />
<p><br />
The PAI INTO statement provides a convenient method to determine field names and values encountered within a FOR EACH RECORD loop.</p><br />
<br />
==FOR EACH RECORD statement==<br />
<p><br />
You can use the FOR EACH RECORD statement to perform: </p><br />
<ul><br />
<li>Retrieval and looping</li><br />
<li>Looping only</li><br />
</ul><br />
<b>Syntax</b><br />
<p class="syntax">FOR <span class="squareb">{</span>EACH <span class="squareb">|</span> <span class="term">n</span><span class="squareb">}</span> <span class="squareb">{</span>RECORD <span class="squareb">|</span> RECORDS<span class="squareb">}</span> -<br />
[IN <span class="term">label</span> <span class="squareb">|</span> ON [LIST] <span class="term">listname</span>] -<br />
[IN [ASCENDING <span class="squareb">|</span> DESCENDING] [SORTKEY] ORDER] -<br />
[BY [EACH] <span class="term">fieldname</span>] -<br />
[FROM <span class="term">value1</span>] [TO <span class="term">value2</span>]<br />
[BY {<span class="term">%variable</span> <span class="squareb">|</span> <span class="term">literal</span>}] -<br />
[OPTIMIZING FNV]<br />
[{WHERE <span class="squareb">|</span> WITH} <span class="term">retrieval-conditions</span>]<br />
</p><br />
<br />
<b>Where</b><br />
<ul><br />
<li><var class="term">n</var> limits the number of records to retrieve. For example, if <var class="term">n</var> equals 17, the first 17 records in the file are retrieved.</li><br />
<br />
<li><var class="term">label</var> specifies the label of a preceding FIND statement. </li><br />
<br />
<li><var class="term">listname</var> specifies a list from a preceding FIND statement.</li><br />
<br />
<li><var class="term">fieldname</var> identifies the field from which to retrieve values.</li><br />
<br />
<li><var class="term">value1</var> and <var class="term">value2</var> specify the beginning and ending range of values to retrieve.</li><br />
<br />
<li><var class="term">%variable</var> or <var class="term">literal</var> specify a comparison value</li><br />
<br />
<li><var class="term">retrieval-conditions</var> can be:<br />
<p class="syntax"><span class="squareb">[</span><span class="term">fieldname</span> <span class="squareb">{</span>EQ <span class="squareb">|</span> NE<span class="squareb">}</span> VALUE IN <span class="term">value_set</span><span class="squareb">]</span><br />
</p><br />
<p><br />
or</p><br />
<p class="syntax"><span class="squareb">[</span><span class="term">fieldname</span> <span class="squareb">{</span>EQ <span class="squareb">|</span> NE<span class="squareb">}</span> VALUE (<span class="term">expression</span>)<span class="squareb">]</span><br />
</p><br />
<br />
<ul><br />
<li>The <var class="term">value_set</var> label represents an existing value set. Values of the value set in the <code>EQ VALUE IN <i>value_set</i></code> clause are treated as boolean OR, for example:<br />
<p class="code"><i>field</i> = <i>value1</i> OR <i>field</i> = <i>value2</i> OR....<br />
</p></li><br />
<li>The <code>NE VALUE IN <i>value_set</i> clause</code> is likewise treated as boolean AND, for example:<br />
<p class="code"><i>field</i> <> <i>value1</i> AND <i>field</i> <> <i>value2</i> AND....<br />
</p><br />
<p><br />
See also [[Basic SOUL statements and commands#Processing a VALUE IN clause|Processing a VALUE IN clause]].</p></li><br />
<br />
<li><var class="term">expression</var> is enclosed in parentheses and can be of any type listed in [[Using variables and values in computation#Using expressions for value retrieval|Using expressions for value retrieval]].</li><br />
</ul><br />
</ul><br />
<br />
===Retrieval and looping===<br />
<p><br />
When the FOR EACH RECORD statement is specified without the IN option, it functions as a FIND statement as well as initiating a loop.</p><br />
<p><br />
This form of the FOR EACH RECORD statement is more efficient than when FOR EACH RECORD is used for looping only, because records are locked until they are processed. </p><br />
<p><br />
Use this form when the set of records being processed is not referred to by subsequent statements outside the loop. </p><br />
<br />
====Example====<br />
<p class="code">BEGIN<br />
FOR EACH RECORD<br />
PRINT FULLNAME WITH AGENT AT COLUMN 30<br />
END FOR<br />
END<br />
</p><br />
<br />
===Looping only===<br />
<p><br />
When the FOR EACH RECORD statement is specified with the IN/ON option, it functions as a loop statement only and refers back to a previously found set in order to process the records.</p><br />
<p><br />
Use this form when the set of records being processed is referred to by subsequent statements outside the loop.</p><br />
<br />
====Example====<br />
<p class="code">BEGIN<br />
GET.RECS: FIND ALL RECORDS<br />
END FIND<br />
FOR EACH RECORD IN GET.RECS<br />
PRINT FULLNAME WITH AGENT AT COLUMN 30<br />
END FOR<br />
END<br />
</p><br />
<br />
===Handling empty found sets===<br />
<p><br />
Before doing any FOR EACH RECORD processing, <var class="product">Model&nbsp;204</var> checks to see if the referenced found set is empty. If the found set is empty, no processing takes place.</p><br />
<br />
===Using expressions for value retrieval===<br />
<p><br />
You can use expressions to provide the values in:</p><br />
<ul><br />
<li>the FROM ... TO clause of a FOR EACH RECORD IN ORDER BY statement</li><br />
<br />
<li>the EQ VALUE clause of a FOR EACH RECORD WHERE statement</li><br />
</ul><br />
<br />
===FOR EACH RECORD IN ORDER BY===<br />
<b>Syntax</b><br />
<p class="syntax">FOR EACH RECORD IN ORDER BY <span class="term">fieldname</span> FROM (<span class="term">expression1</span>) TO (<span class="term">expression2</span>)<br />
</p><br />
<b>Where</b><br />
<p><br />
<var class="term">expression1</var> and <var class="term">expression2</var> are enclosed in parentheses and can be of the following types: function call, string concatenation, arithmetic operation, User Language construct, or Boolean expression.</p><br />
<br />
====Example====<br />
<p class="code">B<br />
%MM IS STRING LEN 2<br />
%DD IS STRING LEN 2<br />
%MM = '09'<br />
%DD1 = '05'<br />
%DD2 = '30'<br />
PRINT 'FR1'<br />
FR1:<br />
IN CLIENTS FOR EACH RECORD IN ORDER BY ANNIV DATE -<br />
FROM (%MM WITH %DD1) TO (%MM WITH %DD2)<br />
PAI<br />
PRINT<br />
END FOR<br />
END<br />
</p><br />
<br />
===FOR EACH RECORD WHERE===<br />
<b>Syntax</b><br />
<p class="syntax">FOR EACH RECORD WHERE <span class="term">fieldname</span> EQ VALUE (<span class="term">expression</span>)<br />
</p><br />
<b>Where</b><br />
<p><br />
<var class="term">expression</var> is enclosed in parentheses and is one of the following types: function call, string concatenation, arithmetic operation, User Language construct, or Boolean expression.</p><br />
<br />
====Example====<br />
<p class="code">B<br />
%MM IS STRING LEN 2<br />
%DD IS STRING LEN 2<br />
%MM = '09'<br />
%DD = '17'<br />
PRINT 'FR1'<br />
FR1:<br />
IN CLIENTS FOR EACH RECORD WHERE ANNIV DATE EQ VALUE(%MM WITH %DD)<br />
PAI<br />
PRINT<br />
END FOR<br />
END<br />
</p><br />
<br />
===Using $LOBLEN to get the size of a Large Object data===<br />
<p><br />
You can tell how large a Large Object field is by issuing the $LOBLEN function using the Large Object field name in a FOR RECORD loop. The $LOBLEN function takes one argument that can be a field name or a field name variable (%%variable).</p><br />
<br />
====Example====<br />
<p class="code">%x=$LOBLEN(NOVEL)<br />
</p><br />
<p><br />
or, to determine the length of a specific occurrence of the field:</p><br />
<p class="code">%x=$LOBLEN(NOVEL(<i>n</i>))<br />
</p><br />
<p><br />
<var class="term">%x</var> is set to the length, in bytes, of the Large Object field.</p><br />
<br />
===Using the $LOBLEN and $LOBRESERVE functions===<br />
<p><br />
The following procedure shows how you can store some data, but have additional space to accommodate an increase in the size of the Large Object data up to the RESERVE number of bytes.</p><br />
<p class="code">BEGIN<br />
%S IS STRING LEN 100 ARRAY(3)<br />
%S(1) = 'OBJECT DATA, MAX = 1000'<br />
%S(2) = 'OBJECT DATA, MAX = 2000'<br />
%S(3) = 'OBJECT DATA, MAX = 3000'<br />
IMAGE LOB.IMAGE<br />
S IS STRING LEN 100<br />
END IMAGE<br />
PREPARE IMAGE LOB.IMAGE<br />
FOR %I FROM 1 TO 3 BY 1<br />
%LOB.IMAGE:S = %S(%I)<br />
WRITE IMAGE LOB.IMAGE ON BUFFER POSITION=1<br />
%RESERVE = %I * 1000<br />
STORE RECORD<br />
BLOB = BUFFER,1,100 RESERVE %RESERVE BYTES<br />
END STORE<br />
END FOR<br />
FR<br />
PRINT '$LOBLEN=' WITH $LOBLEN(BLOB)<br />
PRINT '$LOBRESERVE=' WITH $LOBRESERVE(BLOB)<br />
PAI LOB_DATA<br />
END<br />
</p><br />
<p><br />
This is the output from the previous procedure:</p><br />
<p class="code">$LOBLEN=100<br />
$LOBRESERVE=1000<br />
BLOB = (length 100) (reserve 1000)<br />
OBJECT DATA, MAX = 1000<br />
<br />
$LOBLEN=100<br />
$LOBRESERVE=2000<br />
BLOB = (length 100) (reserve 2000)<br />
OBJECT DATA, MAX = 2000<br />
<br />
$LOBLEN=100<br />
$LOBRESERVE=3000<br />
BLOB = (length 100) (reserve 3000)<br />
OBJECT DATA, MAX = 3000<br />
</p><br />
<br />
===Other FOR EACH RECORD options===<br />
<p><br />
The FOR EACH RECORD statement without any options specified processes every record in the current file or group.</p><br />
<p><br />
Other options available for the FOR EACH RECORD statement are described in detail on this page.</p><br />
<br />
==Restricting FOR EACH RECORD processing==<br />
<b>Syntax</b><br />
<p><br />
Use this form of the FOR EACH RECORD statement to place one or more restrictions on the retrieval of records during FOR EACH RECORD processing:</p><br />
<p class="syntax">FOR EACH RECORD <span class="squareb">[</span>IN <span class="term">label</span><span class="squareb">]</span> <span class="squareb">[</span>OPTIMIZING FNV<span class="squareb">]</span> <br />
[{WHERE <span class="squareb">|</span> WITH} <span class="term">retrieval-conditions</span>]<br />
</p><br />
<p><br />
where <var class="term">retrieval-conditions</var> are any conditions that are valid for the FIND statement, such as:</p><br />
<p class="syntax"><span class="squareb">[</span><span class="term">fieldname</span><span class="squareb">]</span> <span class="squareb">{</span>EQ <span class="squareb">|</span> NE<span class="squareb">}</span> VALUE IN <span class="term">value-set</span><br />
</p><br />
<p><br />
Refer to [[Record retrievals|"Record retrievals"]] for more information about retrieval conditions.</p><br />
<br />
===Field name variable optimization===<br />
<p><br />
The purpose of the OPTIMIZING FNV option is to prevent field name variables from triggering the retrieval of all fields and/or all occurrences of a field when used inside a FOR EACH RECORD loop. This option is valid only when you are using Parallel Query Option/204. If your site is not running Parallel Query Option/204, OPTIMIZING FNV compiles without generating errors, but is ignored.</p><br />
<p><br />
With the FOR EACH RECORD statement, the OPTIMIZING FNV option must be specified immediately before the WHERE or WITH clause, or, when the WHERE/WITH clause is not used, at the end of the FOR statement.</p><br />
<p><br />
OPTIMIZING FNV can be abbreviated to OPT FNV.</p><br />
<p><br />
With the OPTIMIZING FNV option, only the initial value of the field name variable(s) at the start of the FOR loop is used to select the fields to be retrieved and sent to the client node. For this option to work properly, the field name variable must have the intended value at the time the FOR loop is first executed. </p><br />
<p><br />
A side effect of this requirement is that if the field name variable is changed, inside the FOR loop, to the name of another field that was not explicitly referenced within the loop, that field is not retrieved. In this case, a default value of null is used for the field name variable.</p><br />
<p><br />
See [[Using variables and values in computation#Field name variables|Field name variables]] for a detailed discussion.</p><br />
<p><br />
You can also use OPTIMIZING FNV with the FOR RECORD NUMBER statement. See [[#Processing a single record|Processing a single record]] for a discussion of this statement.</p><br />
<br />
===Using WHERE or WITH clause with other options===<br />
<p><br />
If the WHERE or WITH clause is used with any other option on the FOR EACH RECORD statement, the WHERE or WITH clause must be the last option specified.</p><br />
<p><br />
You can combine the IN option with the WHERE or WITH clauses in a FOR EACH RECORD statement to further filter a previously found set. </p><br />
<br />
====Example====<br />
<p class="code">begin<br />
getpol: find all records for which<br />
policy no is greater than 100320<br />
end find<br />
for each record in getpol where<br />
(total premium is greater than 393<br />
agent is greater than 'CASOLA')<br />
print policy no with agent at column 30<br />
end for</p><br />
<p class="note"><b>Note:</b> If the retrieval conditions specified in the WHERE or WITH clause results in a direct search of the data (Table B), it is more efficient to use the FOR EACH RECORD statement without retrieval conditions specified and use the IF statement within the loop to specify the criteria. </p><br />
<br />
===Specify retrieval criteria on one logical line===<br />
<p><br />
You must specify the retrieval criteria on one logical line. </p><br />
<p><br />
A hyphen can be used to note the continuation of the set of conditions.</p><br />
<p><br />
Use parentheses to continue a line. Bear in mind that <var class="product">Model&nbsp;204</var> treats the unstated Boolean operator as an implied AND.</p><br />
<p class="note"><b>Note:</b> The rule for using parentheses with the FOR EACH RECORD WHERE construct is different from the rule for using parentheses with the FIND construct (see [[Record retrievals#Interpretation of Boolean operators in retrievals|Interpretation of Boolean operators in retrievals]]).</p><br />
<br />
====Example====<br />
<p><br />
This statement is considered one logical line:</p><br />
<p class="code">for each record where<br />
(total premium is greater than 393<br />
agent is greater than 'CASOLA') or incident is T1</p><br />
<p><br />
In this example, an implied AND is generated at the end of the first select criteria. </p><br />
<br />
==Processing records in order==<br />
<p><br />
The IN ORDER option of the FOR EACH RECORD statement processes records in index order or sort order, without requiring a sort of the records. When the IN ORDER option is not used, records are processed in entry order on a segment-by-segment basis. </p><br />
<p><br />
You can use index order processing with fields that were defined with the ORDERED attribute. Record loops in index order execute more slowly than record loops in sort order. </p><br />
<p><br />
You can use sort order processing for records in a file which were defined as a sorted file. The execution of a record loop in sort order might be slower than that of an unordered record loop (if you have many spilled records) but faster than that of an index order loop. </p><br />
<p class="note"><b>Note:</b> If the IN ORDER option processes a field that is a sort key but also has the ORDERED attribute, and if SORTKEY is not specified, index order processing is performed. </p><br />
<p><br />
If you want to produce a sort order which is not provided for by the syntax of the IN ORDER option, see [[Sorting#Sorting|Sorting]] for information about the SORT statement.</p><br />
<br />
===Reference context===<br />
<p><br />
Index order and sort order processing can be performed only on records from a single file. Therefore, do not use the IN ORDER option with groups in FOR EACH RECORD loops. Such use of the IN ORDER option with groups results in a counting error and this error message:</p><br />
<p class="code">M204.0243 'IN ORDER' NOT VALID IN GROUP CONTEXT<br />
</p><br />
<p><br />
If you want to process records from a group in sorted order, use the SORT statement. (SORT statement processing typically is slower than index order or sort order processing.)</p><br />
<p><br />
The IN ORDER and VALUE IN options are supported in remote file context. See [[#Referring to the current value|Referring to the current value]] for a discussion of the VALUE IN option.</p><br />
<br />
===Specifying processing order===<br />
<p><br />
If the fields processed by the FOR EACH RECORD statement have the ORDERED attribute, or if the file is a sorted file, ordered processing can occur without requiring a separate sort of the found records.</p><br />
<p><br />
If the file processed is a sorted file, the SORTKEY option forces records to be processed in order according to the values of the sort key field.</p><br />
<b>Syntax</b><br />
<p><br />
This form of the FOR EACH RECORD statement demonstrates how you specify processing order:</p><br />
<p class="syntax">FOR EACH RECORD <span class="squareb">[</span>IN <span class="term">label</span> <span class="squareb">|</span> ON <span class="term">list</span><span class="squareb">]</span> IN <br />
[ASCENDING <span class="squareb">|</span> DESCENDING] <br />
[SORTKEY] ORDER [BY <span class="term">fieldname</span>] <br />
[FROM <span class="term">value1</span>] [TO <span class="term">value2</span>]<br />
</p><br />
<b>Where</b><br />
<ul><br />
<li>ASCENDING and DESCENDING indicate the order in which the record set is sorted. ASCENDING order is the default. </li><br />
<br />
<li>SORTKEY forces records to be processed in sort key order when a sorted file's sort key also has the ORDERED attribute. If SORTKEY is omitted, and the specified field is both a sort key and an ORDERED field, processing order defaults to Ordered Index order. </li><br />
<br />
<li>BY <var class="term">fieldname</var> specifies the ORDERED field to be used to establish processing order. For sorted files, BY is optional.</li><br />
<br />
<li>The FROM and TO clauses specify the range of values to be processed. FROM indicates the beginning value; TO indicates an ending value. You can explicitly define a range by using both FROM and TO, or you can implicitly define a range by specifying only one of these options. Care must be taken in specifying values for FROM and TO; sort key processing behaves differently from Ordered Index processing when you use value ranges. </li><br />
</ul><br />
<br />
===Specifying value ranges for FOR EACH RECORD processing===<br />
<br />
====Records in which the BY field is not present====<br />
<p><br />
If a range is specified (that is either FROM <var class="term">value1</var> TO <var class="term">value2</var> or just FROM <var class="term">value1</var> or just TO <var class="term">value2</var>), records that do not have the field present are not processed.</p><br />
<p><br />
If no range limits are specified and a pattern is not specified using the WHERE or WITH option, records for which the field is not present are processed at the end of the ordered set.</p><br />
<br />
====Order of FROM and TO values====<br />
<p><br />
With sort key order processing, the values for FROM and TO can be presented in either order, for both of the ASCENDING or the DESCENDING options. For example, the two code fragments below each produce the same result:</p><br />
<p class="code"> ...<br />
FOR EACH RECORD IN FD1 IN ASCENDING SORTKEY ORDER BY FULLNAME -<br />
FROM 'ALTON, CHARLES Z' TO 'BAIN, THEODORE S'<br />
PRINT FULLNAME AND POLICY NO AND STATE AND MARITAL STATUS<br />
END FOR<br />
...<br />
FOR EACH RECORD IN FD1 IN ASCENDING SORTKEY ORDER BY FULLNAME -<br />
FROM 'BAIN, THEODORE S' TO 'ALTON, CHARLES Z'<br />
PRINT FULLNAME AND POLICY NO AND STATE AND MARITAL STATUS<br />
END FOR<br />
...<br />
</p><br />
<p><br />
With Ordered Index processing (when SORTKEY is not specified), the order in which you specify the FROM and TO values is sensitive to whether you are doing ASCENDING or DESCENDING order processing. For example, if you are doing DESCENDING order processing, the FROM value must be higher than the TO value, as in the following example, which produces output for the year 1990 in descending INCIDENT DATE order (assuming INCIDENT DATE is defined as an ORDERED field):</p><br />
<p class="code"> ...<br />
FOR EACH RECORD IN FOUNDSET IN DESCENDING ORDER BY INCIDENT DATE<br />
FROM 19901231 TO 19900101<br />
PRINT 'DATE: ' WITH INCIDENT DATE WITH 'DRIVER NAME: ' -<br />
WITH FULLNAME<br />
END FOR<br />
...<br />
</p><br />
<p><br />
If, in the preceding example, you had specified DESCENDING order, but had given the range as <code>FROM 900101 TO 901231</code>, the request would compile without producing errors, but no records would be printed. </p><br />
<br />
====Processing behavior with implicitly specified ranges====<br />
<p><br />
You can specify a value range for FOR EACH RECORD processing implicitly by using only one of the FROM and TO options. <var class="product">Model&nbsp;204</var> then makes an assumption about the unspecified end of the range before proceeding. The following table summarizes these assumptions and categorizes them based on your choice of ASCENDING or DESCENDING processing, and whether the processing is based on Ordered Index or sort key (for sorted files) order. </p><br />
<p><br />
Sort key processing behavior for DESCENDING order with implicitly specified value ranges is the opposite of the corresponding behavior for Ordered Index processing.</p><br />
<table><br />
<caption>FOR EACH RECORD processing behavior with implicitly defined value ranges</caption><br />
<tr class="head"><br />
<th rowspan="2" style="vertical-align:top">Processing direction</th><br />
<th rowspan="2" style="vertical-align:top">Range value specified</th><br />
<th colspan="2">Value range processed</th><br />
</tr><br />
<tr><br />
<th>Ordered Index<br />
processing</th><br />
<th>SORTKEY<br />
processing</th><br />
</tr><br />
<tr><br />
<td rowspan="2">ASCENDING</td><br />
<td>FROM only</td><br />
<td>From specified value<br />
to highest field value</td><br />
<td>From specified value<br />
to highest field value</td><br />
</tr><br />
<tr><br />
<td>TO only</td><br />
<td>From lowest field value to specified value</td><br />
<td>From lowest field value to specified value</td><br />
</tr><br />
<tr><br />
<td rowspan="2">DESCENDING</td><br />
<td>FROM only</td><br />
<td>From specified value<br />
to lowest field value</td><br />
<td>From highest field value to specified value</td><br />
</tr><br />
<tr><br />
<td>TO only</td><br />
<td>From highest field value<br />
to specified value</td><br />
<td>From specified value<br />
to lowest field value</td><br />
</tr><br />
</table><br />
<br />
===Optimization of FOR statement LIKE option===<br />
<p><br />
Whenever the LIKE option is used with the FOR EACH RECORD or FOR EACH VALUE statement which is performing Ordered index processing against an existing found set or list, an attempt is made to create pattern driven terms. <var class="product">Model&nbsp;204</var> optimizes the FROM and TO values with the pattern terms to minimize Ordered Index processing. This optimization creates the most restrictive FROM and TO value based on the specified FROM and TO value (if any) and the current pattern term.</p><br />
<p class="note"><b>Note:</b> This optimization does not take place when the FOR statement is performing both retrieval and looping (when it is used without the IN option; see [[#Retrieval and looping|Retrieval and looping]]).</p><br />
<p><br />
For example (data = 'ABCG' 'ABDG' 'ABEG' 'ABFG' 'ADFG' 'AEFG'): </p><br />
<p class="code">FR IN ORDER BY ORD_FLD FROM 'A' TO 'ABFG' LIKE 'ABE*'<br />
PRINT ORD_FLD<br />
END FOR<br />
</p><br />
<p><br />
The optimization changes the FROM value to ABE (more restrictive than A) and changes the TO value to ABF (more restrictive than ABFG). This results in searching just two values (ABEG and ABFG) to print ABEG. </p><br />
<p><br />
If the FROM or TO value is omitted, the optimization creates an implied FROM or TO value based on the pattern specified after the LIKE keyword. In the example above, if the FROM value were omitted, the results would be the same. The optimization would create an implied FROM value of ABE while changing the TO value to ABF.</p><br />
<br />
===Referring to the current value===<br />
<p><br />
The current value of the ORDERED field can be referred to by using a VALUE IN phrase if the FOR EACH RECORD statement is labeled. In this example, the VALUE IN phrase is used to obtain the current value and assign it to a %variable. (See [[Using variables and values in computation]] for a discussion of %variables.)</p><br />
<p class="code">FORNAME: FOR EACH RECORD IN ORDER BY FULLNAME<br />
%X = VALUE IN FORNAME<br />
...<br />
</p><br />
<br />
==Field group SORT support==<br />
You can use field groups in sorted sets. SORT statement support for field groups not only allows records with field groups in them to be sorted, it lets you reference field groups in the sorted sets. For example, you can issue a FOR FIELDGROUP statement or FEO FIELDGROUP statement against the sorted set.<br />
===Restrictions sorting an individual field in a field group===<br />
Individual fields within field groups can cause syntax errors. In the following example INCIDENT_TYPE is a field in a field group:<br />
<p class="code"><nowiki><br />
*** M204.0542: EDIT COMPLETE - GO<br />
*** 1 M204.2845: INVALID FIELDGROUP CONTEXT FOR<br />
INCIDENT_TYPE<br />
2 SORT RECORDS IN 1 BY INCIDENT_TYPE<br />
(FILE = CCATEMP , PROCEDURE = 0, LINE = 3)<br />
*** M204.1042: COMPILATION ERRORS<br />
></nowiki><br />
</p><br />
The previous example is invalid because the field group context for the SORT statement is the record context. In the record context, you can reference fields inside a field group if, and only if, the field is both:<br />
<ul><br />
<li>In an outer level field group, which is true in the previous example</li><br />
<li>Defined as EXACTLY-ONE or AT-MOST-ONE, which is not true in the previous example</li><br />
</ul><br />
Without these restrictions it is ambiguous as to which occurrence a field group field reference is referring. In the previous case, OTHER_DRIVER is in field group DRIVER, but is defined as REPEATABLE. The REPEATABLE attribute makes OTHER_DRIVER ineligible to be a sort key.<br />
<p class="code"><br />
BEGIN<br />
FD: IN POLICIES FD POLICY_NUMBER = 100095 OR 100096<br />
END FIND<br />
SR: SORT RECORDS IN FD BY MODEL<br />
FR SR<br />
PRINT ’MODELS:’ AND EACH MODEL<br />
PRINT ’MAKES:’ AND EACH MAKE<br />
END FOR<br />
END</p><br />
<br />
<p>Output:</p><br />
<p class="code"><br />
MODELS: ENVOY TACOMA<br />
MAKES: GMC TOYOTA<br />
MODELS: NEW BEETLE ECLIPSE SUBURBAN<br />
MAKES: VOLKSWAGEN MITSUBISHI CHEVROLET<br />
</p><br />
<br />
===Usage notes for SORT processing and field groups===<br />
The EACH clause for fields inside field groups is not allowed. A compile error or run-time error, depending on whether a field name variable is used or not, will be returned.<br />
<p class="code"><nowiki><br />
BEGIN<br />
FD: IN POLICIES FD POLICY_NUMBER = 100095 OR 100096<br />
END FIND<br />
SR: SORT RECORDS IN FD BY EACH MODEL<br />
FR SR<br />
PRINT ’MODELS:’ AND EACH MODEL<br />
PRINT ’MAKES:’ AND EACH MAKE<br />
END FOR<br />
END<br />
*** 1 M204.2845: INVALID FIELDGROUP CONTEXT FOR MODEL<br />
SR: SORT RECORDS IN FD BY EACH MODEL<br />
(FILE = CCATEMP, PROCEDURE = 0, LINE = 4)<br />
*** M204.1042: COMPILATION ERRORS<br />
</nowiki></p><br />
An unsubscripted reference to a field in a field group in a SORT statement is allowed.<br />
<br />
==The prefetch (look-ahead read) feature==<br />
<p><br />
The prefetch feature improves performance of <var class="product">Model&nbsp;204</var> for record-number order retrieval of a record set, particularly in a batch environment. Prefetch is for User Language applications only and applies only to Table B. It is not supported for Host Language Interface applications. </p><br />
<p><br />
The prefetch feature initiates a read of the next Table B page when a previous page is first declared to be current. The look-ahead reads are issued for the FOR EACH RECORD sequential record retrieval mode. Look-ahead read is suppressed if the FR statement contains an IN ORDER clause or if it references a sorted set. </p><br />
<br />
===Performance considerations===<br />
<ul><br />
<li>You can use the prefetch feature during large, multiuser <var class="product">Model&nbsp;204</var> runs, but it is most suitable in a batch environment.</li><br />
<br />
<li>If you use the prefetch feature with many active users, and you are near the buffer limits (see below), you might get a decrease in throughput. To use this feature effectively, each user needs reserved resources, to avoid concurrency conflicts for resources (for example, FIND record conflicts, file level locking, buffer constraints, and so on).</li><br />
<br />
<li>A major factor determining the impact of prefetch is the amount of processing per page I/O. If processing performed per page I/O cycle is high, then prefetch provides significant performance improvements. If processing per page I/O cycle is small, then performance gains are minimal (see [[#perfgains|Performance gains using the prefetch feature]]). A variety of performance tests have resulted in performance gains in the range of 10-40%.<br />
<p><br />
The first of each set of diagrams in [[#perfgains|Performance gains using the prefetch feature]] shows the relationship between page I/O and processing time when the prefetch feature is disabled. The second diagram of each set reflects this relationship when the prefetch feature is in operation. Note that as the amount of processing increases, the performance gains using prefetch also increase. If <code>y</code> (processing) is less than or equal to <code>x</code> (page I/O, including waits), then the gain from using the prefetch feature is roughly <code>y *</code> pages. If <code>y</code> is greater than <code>x</code>, then the gain is <code>x *</code> pages.</p><br />
<br />
<div id="perfgains"></div><br />
<p class="caption">Performance gains using the prefetch feature</p><br />
[[File:prefetchPerf.png|center|border|472px]]<br />
<br><br />
<br />
<li>The prefetch feature involves a small CPU time cost, which is application dependent; you might want to test to determine if the additional overhead is an acceptable level for a specific application in your environment.</li><br />
<br />
<li>If there is terminal I/O for each Table B page, then user delays in pressing Enter might cause a page that was preread into the buffer pool by the prefetch feature to be removed. In that case, the page would need to be read into the buffer pool again, resulting in an increased system I/O level.</li><br />
<br />
<li>The interaction of the prefetch feature and the obsolete file skewing feature can affect performance positively or negatively, depending on the amount of CPU time consumed processing each Table B page.</li><br />
</ul><br />
<br />
===Enabling the feature===<br />
<p><br />
The prefetch feature can be enabled only by users with system manager privileges.</p><br />
<p><br />
Before you enable the prefetch feature, ensure sufficient above the bar or below the bar storage by setting a large enough value for the <var>[[NUMBUFG parameter|NUMBUFG]]</var> or the <var>[[MAXBUF parameter|MAXBUF]]</var> parameter, respectively. </p><br />
<p><br />
To enable the prefetch feature, the system parameter <var>[[SEQOPT parameter|SEQOPT]]</var> must be set to 1 (the default is 0). </p><br />
<br />
==Processing a limited number of records==<br />
<p><br />
You can process only a sample of the data by using the FOR k RECORDS statement. </p><br />
<b>Syntax</b><br />
<p><br />
The form of the <var>FOR k RECORDS</var> statement is:</p><br />
<p class="syntax">FOR <span class="term">k</span> RECORDS <span class="squareb">[</span><span class="term">options</span><span class="squareb">]</span><br />
</p><br />
<b>Where</b><br />
<ul><br />
<li><var class="term">k</var> is an integer value of the sample size.</li><br />
<br />
<li><var class="term">options</var> is any of the options that can be specified on a <var>FOR EACH RECORD</var> statement. </li><br />
</ul><br />
<br />
===FOR k RECORDS processing===<br />
<p><br />
The <var>FOR k RECORDS</var> statement begins a loop that is repeated up to <var class="term">k</var> times, depending on the statement. If <var class="term">k</var> equals zero, the loop is skipped. If <var class="term">k</var> is negative or if there are fewer than <var class="term">k</var> records, then the loop is repeated for all the records in the found set (<var>IN</var> label).</p><br />
<br />
====Example====<br />
<p><br />
This request prints all information for the first five driver records in a file:</p><br />
<p class="code">BEGIN<br />
DRIVERS: IN CLIENTS FIND ALL RECORDS FOR WHICH<br />
RECTYPE = DRIVER<br />
END FIND<br />
FOR 5 RECORDS IN DRIVERS<br />
PRINT ALL INFORMATION<br />
SKIP 1 LINE<br />
END FOR<br />
END<br />
</p><br />
===Processing a single record===<br />
<p><br />
As discussed in [[Record retrievals]], the <var>POINT$</var> condition can be used to retrieve a range of record numbers. </p><br />
<p><br />
If single records must be retrieved by record number, a more efficient method of retrieval is with the <var>For Record Number</var> statement.</p><br />
<br />
===For Record Number processing===<br />
<p><br />
The <var>For Record Number</var> statement retrieves the specified record and initiates a record loop. The record loop functions in a manner identical to a loop initiated by a <var>For Each Record</var> statement. </p><br />
<p><br />
The <var>For Record Number</var> statement is supported in remote file and scattered group contexts.</p><br />
<b>Syntax</b><br />
<p><br />
The format of the <var>For Record Number</var> statement is:</p><br />
<p class="syntax">For Record Number <span class="squareb">{</span><span class="term">value</span> <span class="squareb">|</span> IN <span class="term">label</span><span class="squareb">}</span> <span class="squareb">[</span>OPTIMIZING FNV<span class="squareb">]</span><br />
</p><br />
<b>Where</b><br />
<ul><br />
<li><var class="term">value</var> specifies the number of the record to be processed. The value can be a literal number or string, a %variable, or a VALUE IN phrase. (The VALUE IN phrase is discussed later in this section; %variables are discussed in [[Using variables and values in computation]].) If the specified value is not numeric, or is not a valid record number in the current file, the body of the loop is bypassed and processing continues with the next statement that is at the same nesting level as the <var>For Record Number</var> statement.<br />
<br />
<p class="note"><b>Note:</b><br />
If this form of the <var>For Record Number</var> statement is used in group context, it must be preceded by an IN clause which refers to a file. [[Files, groups, and reference context]] discusses the IN clause in detail. </p><br />
<br />
<li>The IN label clause specifies the label of a previous <var>For Each Record</var> or <var>Store Record</var> statement. (Refer to [[Data maintenance#STORE RECORD statement|Store Record statement]] for more information.)<br />
<br />
<p class="note"><b>Note:</b><br />
This form of the <var>For Record Number</var> statement automatically assumes the file or group context of the statement to which the label refers. Therefore, it cannot be preceded by an IN clause. </p></li><br />
<br />
<li>The OPTIMIZING FNV option is used in remote context to prevent field name variables from triggering the retrieval of all fields and/or all occurrences of a field. With the FOR RECORD NUMBER statement, OPTIMIZING FNV must be specified at the end of the statement. <br />
<p><br />
OPTIMIZING FNV is valid only in remote context; in local context, it is ignored. OPTIMIZING FNV can be abbreviated OPT FNV. See [[#Field name variable optimization|Field name variable optimization]] for a more detailed discussion.</p><br />
</li><br />
</ul><br />
<br />
====Example====<br />
<p><br />
In the following example, the IN label form of the <var>For Record Number</var> statement is used to create one line of output from data obtained from two different found sets in different files:</p><br />
<p class="code">BEGIN<br />
FIND1: IN MASTER FIND ALL RECORDS<br />
END FIND<br />
FR1: FOR EACH RECORD IN FIND1<br />
N1: NOTE SSNO<br />
FIND2: IN PAYROLL FIND ALL RECORDS FOR WHICH<br />
SSNO = VALUE IN N1<br />
END FIND<br />
FOR 1 RECORD IN FIND2<br />
FOR RECORD NUMBER IN FR1<br />
PRINT SSNO AND NAME AND ...<br />
END FOR<br />
PRINT PAY AND DEDUCTIONS<br />
END FOR<br />
END FOR<br />
END<br />
</p><br />
<br />
===Returning the record number of the current record===<br />
<p><br />
The <var>[[$CURREC]]</var> function can be used to return the record number of the record being processed. </p><br />
<br />
===Using an expression with For Record Number===<br />
<p><br />
The <var>For Record Number</var> statement (abbreviation: <var>FRN</var>) accepts an expression to supply its value.</p><br />
<b>Syntax</b><br />
<p class="syntax">FRN <span class="term">expression</span><br />
</p><br />
<p><br />
A multi-part expression must be enclosed in parentheses; for example:</p><br />
<p class="code">FRN (%A + %B)<br />
</p><br />
<b>Where</b><br />
<p><br />
<var class="term">expression</var> is one of the following types: function call, string concatenation, arithmetic operation, SOUL construct, or Boolean expression.</p><br />
<br />
===Example===<br />
<p class="code">IN FILE CLAIMS STORE RECORD<br />
...<br />
END STORE<br />
IN FILE CLAIMS FRN $CURREC<br />
...<br />
END FOR<br />
</p><br />
<br />
==Skip processing==<br />
<p><br />
You can direct <var class="product">Model&nbsp;204</var> to process a user-specified fraction of a record set (for example, every third record) with the FOR EACH RECORD statement. This is called skip processing, and the skipping can be forward (from the beginning of the record set to the end) or backward. </p><br />
<p><br />
For Ordered Index record sets that have duplicate field values, you can invoke a skip processing option to process the record set by ascending or descending record number (as described in [[#Descending record number processing|Descending record number processing]]), within each Ordered Index value. </p><br />
<br />
===Forward or backward skip processing===<br />
<p><br />
Skip processing is invoked for a <var>FOR EACH RECORD</var> or <var>FOR EACH VALUE</var> statement by including a <var>BY</var> clause with the following syntax:</p><br />
<p class="syntax"><span class="literal">BY</span> <span class="squareb">{</span><span class="term">%variable</span> <span class="squareb">|</span> <span class="term">literal</span><span class="squareb"><span class="squareb">}</span></span><br />
</p><br />
<b>Where</b><br />
<ul><br />
<li><var class="term">%variable</var> or <var class="term">literal</var> indicates how many records to skip before retrieving the record to process in the next iteration of the <var>FOR</var> loop. If set to <var class="term">n</var>, every <var class="term">n</var>th record is processed (and <var class="term">n</var>-1 records are skipped in between). The value of <var class="term">%variable</var> or <var class="term">literal</var> must be an integer between and including positive or negative 2,147,483,647. A setting of zero is not allowed. </li><br />
<br />
<li>Negative settings invoke backward skipping. However, you cannot skip backward in a given record set until you have first skipped forward in the record set. This is equivalent to saying that you cannot start at the beginning of the record set and skip backward. </li><br />
<br />
<li>You can change the direction and number of records to skip each time through the loop by using a %variable in the <var>BY</var> clause and changing the value of the %variable inside the loop. <var class="product">Model&nbsp;204</var> checks the value of the %variable immediately before beginning the next iteration of the loop.</li><br />
<br />
<li>You can use backward processing with Ordered Index record sets only if one of the following is true:<br />
<ul><br />
<li><var>EACH</var> is specified in the <var>FOR</var> statement.</li><br />
<li>The field in question is defined with <var>OCCURS 1</var>.</li><br />
<li>The field in question is defined with <var>AT-MOST-ONE</var>.</li><br />
</ul><br />
</ul><br />
<br />
===Specifying ascending or descending order with ORDERED fields===<br />
<p><br />
If you are processing ORDERED fields, use the following FOR EACH RECORD syntax to get skip processing in ascending or descending order. The placement of the skip processing BY clause in the FOR EACH VALUE statement syntax is similar.</p><br />
<p class="syntax">FOR EACH RECORD <span class="squareb">[</span>IN <span class="term">label</span> <span class="squareb">|</span> ON <span class="term">list</span><span class="squareb">]</span><br />
IN <span class="squareb">[</span>ASCENDING <span class="squareb">|</span> DESCENDING<span class="squareb">]</span> ORDER BY <span class="term">fieldname</span><br />
<span class="squareb">[</span>FROM <span class="term">value1</span><span class="squareb">]</span> <span class="squareb">[</span>TO <span class="term">value2</span><span class="squareb">]</span> <span class="squareb">[</span>BY <span class="squareb">{</span><span class="term">%variable</span> <span class="squareb">|</span> <span class="term">literal</span><span class="squareb">}</span><span class="squareb">]</span><br />
<span class="squareb">[</span>WHERE <span class="term">fieldname</span> IS LIKE <span class="term">pattern</span><span class="squareb">]</span><br />
</p><br />
<p><br />
Use the following syntax for unordered and sorted record sets:</p><br />
<p class="syntax">FOR EACH <span class="squareb">[</span>RECORD <span class="squareb">|</span> VALUE<span class="squareb">]</span> IN <span class="term">foundset</span><br />
BY <span class="squareb">{</span><span class="term">%variable</span> <span class="squareb">|</span> <span class="term">literal</span><span class="squareb">}</span><br />
</p><br />
<p><br />
Use the following syntax for record sets from sorted files:</p><br />
<p class="syntax">FOR EACH RECORD <span class="squareb">[</span>IN <span class="term">label</span> <span class="squareb">|</span> ON <span class="term">list</span><span class="squareb">]</span> IN SORTKEY ORDER<br />
BY <span class="term">fieldname</span> BY <span class="squareb">{</span><span class="term">%variable</span> <span class="squareb">|</span> <span class="term">literal</span><span class="squareb">}</span><br />
</p><br />
<b>Where</b><br />
<ul><br />
<li><var>SORTKEY</var> invokes skip processing in order according to the values of the sort key field. The sort key field is <var class="term">fieldname</var> in the first <var>BY</var> clause.</li><br />
<br />
<li>If you do not specify <var>SORTKEY</var>, and <var class="term">fieldname</var> in the first <var>BY</var> clause is both a sort key and an <var>ORDERED</var> field, <var class="product">Model&nbsp;204</var> uses skip processing for the Ordered Index ordering of the <var class="term">fieldname</var> values.</li><br />
</ul><br />
<br />
===Example===<br />
<p><br />
The following example demonstrates the flexibility of skip processing. Note that the value of the skip increment, <code>%I</code> in this example, is recomputed inside the FOR loop. This allows both the direction of and the interval of the skip to be different for each iteration of the loop. </p><br />
<p class="code"><b></b>***************************************************************<br />
<b></b>* THIS ROUTINE FINDS THE NUMBER OF A RECORD WHOSE VALUE<br />
<b></b>* EQUALS OR PRECEDES THAT OF %LONGNAME. IT SETS USE.REC<br />
<b></b>* TO THAT RECORD NUMBER. A BINARY SEARCH IMPLEMENTED WITH<br />
<b></b>* SKIP PROCESSING IS USED TO DETERMINE THE RECORD NUMBER.<br />
<b></b>***************************************************************<br />
BEGIN<br />
<b></b>* PROCEDURE TO PERFORM BINARY SEARCH IN SORTED FILES USING SKIP<br />
<b></b>* BY %VAR<br />
<b></b>* %V CONTAINS A VALUE TO BE FOUND<br />
%FOUND = 0<br />
FND:<br />
FIND ALL RECORDS<br />
END FIND<br />
CT:<br />
COUNT RECORDS IN FND<br />
%COUNT = COUNT IN CT<br />
%I = %COUNT / 2<br />
%BGN = 0<br />
%END = %COUNT + 1<br />
%C = %I<br />
<b></b>* %C IS THE CENTER POINT REACHED BY THE NEW %I<br />
FOR EACH RECORD IN FND IN SORTKEY ORDER BY FIELD1 BY %I<br />
IF FIELD1 EQ %V THEN<br />
%FOUND = 1<br />
JUMP TO GOT.NUM<br />
ELSEIF FIELD1 GT %V THEN<br />
<b></b>* GOING BACKWARD<br />
%END = %C<br />
%I = -(%END - %BEG)/2<br />
%C = %END + %I<br />
ELSE<br />
<b></b>* GOING FORWARD<br />
%BEG = %C<br />
%I = (%END - %BEG) / 2<br />
%C = %BEG + %I<br />
END IF<br />
IF %I EQ 0 THEN<br />
%I = 1<br />
<b></b>* SKIP VALUE MAY NOT BE ZERO EVEN WHEN WE LEAVE THE LOOP<br />
JUMP TO GOT.NUM<br />
END IF<br />
END FOR<br />
GOT.NUM:<br />
IF %FOUND = 0 THEN<br />
PRINT 'NOT FOUND: ' %V<br />
ELSE<br />
PRINT 'FOUND: ' %V<br />
END IF<br />
END<br />
</p><br />
<br />
===Descending record number processing===<br />
<p><br />
You can process Ordered Index record sets in descending record number order per field value. The FOR EACH RECORD statement skip processing option is extended to permit descending record number ordering. Previously, IN ORDER BY processing was always in ascending record number order. <i>This extension is only valuable for processing record sets in which a field has duplicate data values.</i> </p><br />
<p><br />
For example, use the following syntax for Ordered Index skip processing with record number ordering. The extension to skip processing syntax is shown in bold. </p><br />
<br />
<p class="syntax">FOR EACH RECORD <span class="squareb">[</span>IN <span class="term">label</span> <span class="squareb">|</span> ON <span class="term">list</span><span class="squareb">]</span><br />
IN [ASCENDING <span class="squareb">|</span> DESCENDING] ORDER BY <span class="term">fieldname</span> [FROM <span class="term">value1</span>] [TO <span class="term">value2</span>]<br />
[BY [<b><u>ASCENDING RECORD</u></b> <span class="squareb">|</span> <b>DESCENDING RECORD</b>] {<span class="term">%variable</span> <span class="squareb">|</span> <span class="term">literal</span>}]<br />
[WHERE <span class="term">fieldname</span> IS LIKE <span class="term">pattern</span>]<br />
</p><br />
<b>Where</b><br />
<ul><br />
<li><var>ASCENDING RECORD</var> or <var>DESCENDING RECORD</var> indicates the records are to be processed in ascending or descending record number within <var class="term">fieldname</var> value. If neither <var>ASCENDING</var> nor <var>DESCENDING</var> is specified, the default is <var>ASCENDING RECORD</var>.</li><br />
<br />
<li>If specified with the <var>IN ORDER BY</var> clause, a <var class="term">%variable</var> or <var class="term">literal</var> value is required when the skip processing <var>BY</var> is specified. </li><br />
</ul><br />
<br />
===Examples===<br />
<p><br />
In [[#Example 1|Example 1]], the record set below is processed using the default behavior of the <var>FOR EACH RECORD</var> statement. In [[#Example 2|Example 2]], it is processed using a <var>FOR EACH RECORD</var> statement with record number ordering. </p><br />
<table><br />
<tr class="head"><br />
<th>Record number <br>(value of field RECNO)</th><br />
<th>Value of field ORDCHAR</th><br />
</tr><br />
<tr><br />
<td>01</td><br />
<td>A</td><br />
</tr><br />
<tr><br />
<td>02</td><br />
<td>A</td><br />
</tr><br />
<tr><br />
<td>03</td><br />
<td>B</td><br />
</tr><br />
<tr><br />
<td>04</td><br />
<td>B</td><br />
</tr><br />
<tr><br />
<td>05</td><br />
<td>C</td><br />
</tr><br />
<tr><br />
<td>06</td><br />
<td>C</td><br />
</tr><br />
<tr><br />
<td>07</td><br />
<td>A</td><br />
</tr><br />
<tr><br />
<td>08</td><br />
<td>A</td><br />
</tr><br />
<tr><br />
<td>09</td><br />
<td>B</td><br />
</tr><br />
<tr><br />
<td>10</td><br />
<td>B</td><br />
</tr><br />
<tr><br />
<td>11</td><br />
<td>C</td><br />
</tr><br />
<tr><br />
<td>12</td><br />
<td>C</td><br />
</tr><br />
</table><br />
<br />
====Example 1====<br />
Prior to skip processing and record number ordering, the <var>FOR EACH RECORD</var> statement ordering by field name was always in ascending record number order, as the output from the following statements show:<br />
<br />
<p class="code">PRINT 'ORDCHAR' AND 'RECNO'<br />
FR IN label IN DESCENDING ORDER BY ORDCHAR<br />
PRINT ORDCHAR WITH RECNO AT 9<br />
END FOR<br />
</p><br />
<p><br />
These statements print ascending record numbers within the descending ORDCHAR values: </p><br />
<p class="code">ORDCHAR RECNO<br />
C 05<br />
C 06<br />
C 11<br />
C 12<br />
B 03<br />
B 04<br />
B 09<br />
B 10<br />
A 01<br />
A 02<br />
A 07<br />
A 08<br />
</p><br />
<br />
====Example 2====<br />
In this example, the <var>FOR EACH RECORD</var> statement specifies record number ordering:<br />
<p class="code">PRINT 'ORDCHAR' AND 'RECNO'<br />
FR IN label IN DESCENDING ORDER BY ORDCHAR -<br />
BY DESCENDING RECORD %variable<br />
PRINT ORDCHAR WITH RECNO AT 9<br />
END FOR<br />
</p><br />
<p><br />
These statements print descending record numbers within the descending <var>ORDCHAR</var> values:</p><br />
<p class="code">ORDCHAR RECNO<br />
C 12<br />
C 11<br />
C 06<br />
C 05<br />
B 10<br />
B 09<br />
B 04<br />
B 03<br />
A 08<br />
A 07<br />
A 02<br />
A 01<br />
</p><br />
<br />
<div id="noteStmt"></div><br />
<br />
==Note statement==<br />
<!--Caution: <div> above--><br />
<br />
<p><br />
As described in [[Introduction to User Language#Fields|Fields]], <var class="product">Model&nbsp;204</var> retrieves sets of records by means of one or more fields contained in each record. </p><br />
<p><br />
By using the <var>Note</var> statement, you can cause <var class="product">Model&nbsp;204</var> to temporarily store the value of any field in the retrieved set, permitting its use in subsequent retrievals within the same request.</p><br />
<br />
<p class="note"><b>Note:</b> The <var>Note</var> statement has been deprecated in favor of using [[#Alternative: use assignment statements|assignment statements]] for subsequent retrievals and cross referencing.</p><br />
<br />
<b>Syntax</b><br />
<p><br />
This statement directs <var class="product">Model&nbsp;204</var> to remember the value of a retrieved field:</p><br />
<p class="syntax">label: Note <span class="term">fieldname</span><br />
</p><br />
<br />
===Note processing===<br />
<p><br />
A <var>Note <i>fieldname</i></var> statement can be used only within a <var>FOR EACH RECORD</var> or <var>FOR RECORD NUMBER</var> loop. </p><br />
<p><br />
Each time the loop is executed, another record in the retrieved set is processed and the value of the field in that record is saved. This value can then be used in a subsequent <var>Find</var> statement by using the <var>Value In</var> phrase to refer to the noted value. </p><br />
<br />
===Example===<br />
<p><br />
The following request finds all current and potential policyholders in cities covered by the agent <code>GOODRICH</code>:</p><br />
<p class="code">begin<br />
get.agent: find all records for which<br />
agent = 'GOODRICH'<br />
end find<br />
process: for each record in get.agent<br />
city.name: note city<br />
city.val: find all records for which<br />
city = value in city.name<br />
end find<br />
print.info: for each record in city.val<br />
print city with agent at column 20 -<br />
with policy no at column 40<br />
end for<br />
end for<br />
tot.goodrich: count records in get.agent<br />
print count in tot.goodrich<br />
end<br />
</p><br />
<p><br />
In this example, the <code>process</code> label begins a loop. Cross-referencing (see the next section) is repeated until all records with <code>agent = 'GOODRICH'</code> have been processed. </p><br />
<p><br />
The <code>city</code> label notes the city of each record for agent <code>GOODRICH</code>. The <code>city.val</code> label retrieves all records in the file, regardless of agent, that have a value equal to the noted city. The <code>print.info</code> statement prints the city, agent, and policy number, and then <var class="product">Model&nbsp;204</var> loops back to the <code>process</code> label and notes the city on the next <code>agent = 'GOODRICH'</code> record, and so on. When all <code>agent = 'GOODRICH'</code> records have been exhausted, execution continues with the <code>tot.goodrich</code> label.</p><br />
<br />
===Alternative: Use assignment statements===<br />
<p><br />
The functions of the <var>Note</var> statement can be performed more efficiently with the assignment statement because the assignment statement uses less user table space during compilation. See also:</p><br />
<ul><br />
<li>[[Using variables and values in computation#Assigning values to %variables|Assigning values to %variables]]</li><br />
<br />
<li>[[Large request considerations#Description of tables|Description of tables]]</li><br />
</ul><br />
<p><br />
In the preceding example, an assignment statement could be used by replacing <code>note city</code> with <code>%city = city</code>, as in the following example:</p><br />
<p class="code">begin<br />
%city is string len 255<br />
get.agent: find all records for which<br />
agent = 'GOODRICH'<br />
end find<br />
process: for each record in get.agent<br />
%city = city<br />
city.val: find all records for which<br />
city = %city<br />
end find<br />
print.info: for each record in city.val<br />
print city with agent at column 20 -<br />
with policy no at column 40<br />
end for<br />
end for<br />
tot.goodrich: count records in get.agent<br />
print count in tot.goodrich<br />
end</p><br />
<br />
===Noting character strings===<br />
<p><br />
The following form of the <var>Note</var> statement can be used to set a value for later reference by the <var>Value In</var> phrase: </p><br />
<p class="code">label: NOTE 'string'<br />
</p><br />
<p><br />
For example:</p><br />
<p class="code">BEGIN<br />
NAME: NOTE 'ABBOTT, FRANKLIN G'<br />
FIND.RECS: FIND ALL RECORDS FOR WHICH<br />
FULLNAME = VALUE IN NAME<br />
END FIND<br />
CT: COUNT RECORDS IN FIND.RECS<br />
PRINT COUNT IN CT -<br />
WITH ' RECORDS FOR ' -<br />
WITH VALUE IN NAME<br />
END<br />
</p><br />
<p><br />
results in the output:</p><br />
<p class="output">2 RECORDS FOR ABBOTT, FRANKLIN G<br />
</p><br />
<p><br />
Refer to [[#Nested loops|Nested loops]] for an additional example using the <var>Value In</var> phrase.</p><br />
<br />
==Cross-referencing==<br />
<p><br />
Cross-referencing involves using a field from one record to find another record or set of records.The following examples illustrate the use of cross-referencing.</p><br />
<br />
===Efficient cross-referencing===<br />
<p><br />
This example illustrates a technique for creating efficient cross-referencing requests. Consider the CLIENTS and VEHICLES files that contain records for people and records for cars, respectively. Records might be related by having a common field (for example, POLICY NO in one file and OWNER POLICY in the other). To find the total premium paid by each policyholder owning a SAAB, you could write this request: </p><br />
<p class="code">BEGIN<br />
%OWNER_POLICY IS STRING LEN 6<br />
SAABS: IN VEHICLES FIND ALL RECORDS FOR WHICH<br />
MAKE = SAAB<br />
END FIND<br />
FOR EACH RECORD IN SAABS<br />
%OWNER_POLICY = OWNER POLICY<br />
POLICY.VAL: IN CLIENTS FIND ALL RECORDS FOR WHICH<br />
POLICY NO = %OWNER_POLICY<br />
RECTYPE = POLICYHOLDER<br />
END FIND<br />
FOR EACH RECORD IN POLICY.VAL<br />
PRINT POLICYHOLDER -<br />
WITH TOTAL PREMIUM TO COLUMN 25<br />
END FOR<br />
END FOR SAABS<br />
END<br />
</p><br />
<br />
===Moving constant retrieval outside FOR loop===<br />
<p><br />
If the first statement retrieves 500 records with MAKE = SAAB, the FIND statement in POLICY.VAL is executed 500 times. </p><br />
<p><br />
The cost of a FIND is directly related to the number of retrieval conditions specified. In Example 1, the retrieval condition RECTYPE = POLICYHOLDER is the same for each repetition of POLICY.VAL. </p><br />
<p><br />
Greater efficiency is gained by moving constant retrieval conditions outside the FOR loop. For example:</p><br />
<p class="code">BEGIN<br />
SAABS: IN VEHICLES FIND ALL RECORDS FOR WHICH<br />
MAKE = SAAB<br />
END FIND<br />
POL.HOLDERS: IN CLIENTS FIND ALL RECORDS FOR WHICH<br />
RECTYPE = POLICYHOLDER<br />
END FIND<br />
SAAB.LOOP: FOR EACH RECORD IN SAABS<br />
POLICY: NOTE OWNER POLICY<br />
POLICY.VAL: FIND ALL RECORDS IN POL.HOLDERS FOR WHICH<br />
POLICY NO = VALUE IN POLICY<br />
END FIND<br />
FOR EACH RECORD IN POLICY.VAL<br />
PRINT POLICYHOLDER -<br />
WITH TOTAL PREMIUM TO COLUMN 25<br />
END FOR<br />
END FOR<br />
END<br />
</p><br />
<br />
===Record locking considerations===<br />
<p><br />
The preceding technique might not be appropriate for an application in which many users retrieve data from and update the same file concurrently. </p><br />
<p><br />
The POLICYHOLDER records in the second request are locked out from updates for the duration of the request. In the first request, the POLICYHOLDER records would be accessible for updating between repetitions of the outer loop. Refer to [[Record level locking and concurrency control#Record locking and release statements|Record locking and release statements]] for more discussion.</p><br />
<br />
===Nested loops===<br />
<p><br />
The following example illustrates cross-referencing with nested loops. This request finds all drivers of vehicles used for carpool purposes who also have a vehicle that is not used for carpools.</p><br />
<p><br />
This example illustrates referring to noted values in output statements.</p><br />
<p class="code">BEGIN<br />
SET HEADER 1 'PRINCIPLE DRIVER' -<br />
WITH 'POLICY NO.' AT COLUMN 20<br />
SET HEADER 2<br />
NEW PAGE<br />
FD.CARPOOLS: IN VEHICLES FIND ALL RECORDS FOR WHICH<br />
USAGE = CARPOOL<br />
END FIND<br />
FOR EACH RECORD IN FD.CARPOOLS<br />
NOTE.DRIVER: NOTE PRINCIPLE DRIVER<br />
FD.NO.CP: FIND ALL RECORDS FOR WHICH<br />
PRINCIPLE DRIVER = VALUE IN NOTE.DRIVER<br />
USAGE = NOT CARPOOL<br />
END FIND<br />
FOR EACH RECORD IN FD.NO.CP<br />
PRINT VALUE IN NOTE.DRIVER AT COLUMN 5 -<br />
WITH OWNER POLICY AT COLUMN 22<br />
END FOR<br />
END FOR<br />
END<br />
</p><br />
<br />
===The VALUE IN phrase===<br />
<p><br />
The VALUE IN phrase can be used in place of an explicit field name in a PRINT statement. Each time the loop containing the PRINT statement is executed, the current value of the noted field is printed. </p><br />
<p><br />
This output is generated by the PRINT statement in the previous request:</p><br />
<p class="code">PRINCIPLE DRIVER POLICY NO.<br />
<br />
100735 100304<br />
102081 100865<br />
101693 100761<br />
. .<br />
. .<br />
</p><br />
<p><br />
The VALUE IN phrase can be used in SET HEADER and SET TRAILER statements to print what was noted. VALUE IN also can be used to replace any value in a retrieval statement (FIND). </p><br />
<br />
==Counting records in a found set==<br />
<br />
===Issues===<br />
<p><br />
Records retrieved by a FOR EACH RECORD statement cannot be counted using the COUNT RECORDS statement. </p><br />
<p><br />
In addition, counting records retrieved by a FIND statement and counted within a record loop can produce unexpected results. </p><br />
<br />
===Example===<br />
<p><br />
Consider the problem of trying to count the total number of records retrieved by the FIND.RECS statement below: </p><br />
<p class="code">%zip is string len 5<br />
get.agent: find all records for which<br />
agent = 'CASOLA'<br />
end find<br />
for each record in get.agent<br />
%zip = zip<br />
find.recs: find all records for which<br />
zip = %zip<br />
end find<br />
</p><br />
<p><br />
Suppose 25 records were found each time through the loop, or 100 records after four iterations. Then the sequence:</p><br />
<p class="code"> .<br />
.<br />
.<br />
ct.recs: count records in find.recs<br />
print count in ct.recs<br />
end for<br />
</p><br />
<p><br />
would print, not 100, but</p><br />
<p class="code">25<br />
25<br />
25<br />
25<br />
</p><br />
<p><br />
and the sequence</p><br />
<p class="code"> .<br />
.<br />
.<br />
ct.recs: count records in find.recs<br />
end for<br />
print.ct: print count in ct.recs<br />
</p><br />
<p><br />
would print only the last of the four counts, or</p><br />
<p class="code">25<br />
</p><br />
<br />
===Solution===<br />
<br />
<p><br />
<br />
The correct total could be obtained by the following statements (which use the assignment statement discussed in [[Using variables and values in computation#Assigning values to %variables|Assigning values to %variables]]):</p><br />
<br />
<p class="code"> .<br />
.<br />
.<br />
<br />
ct.recs: count records in find.recs<br />
<br />
%total = %total + count in ct.recs<br />
<br />
end for<br />
<br />
print.ct: print %total<br />
</p><br />
<p><br />
However, this technique would be accurate only if the record found by the FIND.RECS statement was not found in any earlier iteration. If the records were found earlier, then a list should be used to arrive at the correct total. [[Lists#Lists|Lists]] describes the statements used to create lists. </p><br />
<br />
==PRINT ALL INFORMATION (or PAI) INTO statement==<br />
<p><br />
The PRINT ALL INFORMATION (PAI) INTO statement lets you move a record's field names and values into a form of storage that can be easily manipulated. The benefits of the PAI INTO statement include an effective copy-record capability, and also a convenient way to determine field names and values encountered within a FOR EACH RECORD loop.</p><br />
<b>Syntax</b><br />
<p><br />
The form of the PAI INTO statement is:</p><br />
<p class="code">PRINT ALL INFORMATION option INTO<br />
array_1, array_2, [array_3]<br />
[FROM start] [COUNT ct]<br />
</p><br />
<b>Where</b><br />
<ul><br />
<li>option can be one of the following and specifies how Large Object fields are handled:<br />
<p><br />
LOB_DATA &mdash; If the LOB is 255 bytes or less and the field value array element is large enough, the LOB data is copied to the field value array element. Otherwise, $STATUS is set to 2, $STATUSD is set to 3, and the entire record is output in PAI format to the output device.</p><br />
<p><br />
The default option for the PAI INTO statement is LOB_DATA.</p><br />
<p><br />
LOB_SHORT_DATA &mdash; Copies the first 255 bytes of the LOB data to the field value array element.</p><br />
<p><br />
LOB_NO_DATA &mdash; No LOB data is copied to the field value array. The field name and LOB descriptor are copied to array_1 and array_3, respectively.</p><br />
<p><br />
LOB_NONE &mdash; No LOB information--field name, LOB data, nor LOB descriptor--is copied to the output arrays.</p><br />
<li>array_1 through array_3 are string %variable or image item arrays. This form of the PAI statement fills:</li><br />
<p><br />
array_1 with field names</p><br />
<p><br />
array_2 with field values</p><br />
<p><br />
array_3 with the Large Object descriptor, of at least 27 bytes starting at X'800000', from which you can extract the field length, reserve, and so on.</p><br />
<p><br />
When writing requests using the PAI INTO statement, remember to add a subscript to the name of each array variable. The subscripts determine which element of the array receives the first value generated by the PAI INTO statement. The subscripts for the three arrays should be the same, and, unless you have a specific reason for wanting to reserve elements at the beginning of the arrays, the value of each subscript should be 1, as shown in [[#PRINT ALL INFORMATION (or PAI) INTO statement|PRINT ALL INFORMATION (or PAI) INTO statement]].</p><br />
<p><br />
The lengths of the field name and field value arrays must equal, respectively, the length of the longest known field name plus one and the length of the longest known field value plus one. The extra byte is required for the length byte which precedes each field name and field value. The length of the Large Object descriptor must be at least 27 bytes, otherwise you will get a $STATUSD=4 return code.</p></li><br />
<br />
<li>start is a scalar %variable. If supplied, start is a relative field pointer indicating where to start extracting field values. The default is 1.</li><br />
<br />
<li>ct is a scalar %variable that indicates the number of fields that have been extracted from the record after the PAI INTO statement executes. If you specify ct as a %variable, <var class="product">Model&nbsp;204</var> uses the %variable as a counter to keep track of the number of fields extracted. </li><br />
</ul><br />
<br />
===Usage===<br />
<p><br />
The PAI INTO statement writes only to the arrays, not to the terminal.</p><br />
<br />
===Error messages===<br />
<p><br />
Error messages are issued if the INTO arguments are not string arrays, or if ct is a literal. Since PAI INTO can fail for a variety of storage-related reasons, error conditions are stored in $STATUS and $STATUSD. </p><br />
<p><br />
The possible $STATUS values are:</p><br />
<table><br />
<tr><br />
<td align="right">0</td><br />
<td>PAI INTO completed successfully.</td><br />
</tr><br />
<tr><br />
<td align="right">2</td><br />
<td>PAI INTO failed, see $STATUSD for details.</td><br />
</tr><br />
</table><br />
<p><br />
$STATUSD values are:</p><br />
<table><br />
<tr><br />
<td align="right">0</td><br />
<td>PAI INTO completed successfully.</td><br />
</tr><br />
<tr><br />
<td align="right">1</td><br />
<td>PAI INTO failed because either the field name array, the field value array, or the Large Object descriptor array was not large enough to contain all of the record's fields.</td><br />
</tr><br />
<tr><br />
<td align="right">2</td><br />
<td>PAI INTO failed because a field name was too large for an array element.</td><br />
</tr><br />
<tr><br />
<td align="right">3</td><br />
<td>PAI INTO failed because a field value was too large for an array element.</td><br />
</tr><br />
<tr><br />
<td align="right">4</td><br />
<td>PAI INTO failed because a Large Object descriptor was too large for an array element.</td><br />
</tr><br />
</table><br />
<p><br />
If $STATUSD is nonzero, then the value of the ct %variable contains the index value (as in the arrays shown in the following example) of the last field name and value successfully extracted. </p><br />
<br />
===Record locking with PAI processing===<br />
<p><br />
When you are processing unlocked records (such as records on lists or in sets produced via FIND WITHOUT LOCKS) through a PAI loop in local context, <var class="product">Model&nbsp;204</var> puts a share lock on each record as it is being processed. This lock prevents other updating users from changing records as they are being processed, but might cause record locking conflicts.</p><br />
<p><br />
To help catch such conflicts, add an ON RECORD LOCKING CONFLICT unit to User Language procedures using PAI against unlocked records.</p><br />
<p><br />
When you are using the Parallel Query Option/204 and you are working with a remote file, no locks are issued against the records in the remote file since <var class="product">Model&nbsp;204</var> works from a local copy of the remote records.</p><br />
<br />
===Example===<br />
<p><br />
The following schematic example shows one way to set up a PAI INTO statement to perform a "copy record" function.</p><br />
<p class="code">BEGIN<br />
DECLARE %FIELDNAM IS STRING LEN 20 ARRAY(100)<br />
DECLARE %FIELDVAL IS STRING LEN 80 ARRAY(100) NO FS<br />
DECLARE %FGO IS FIXED<br />
DECLARE %RET IS FIXED<br />
DECLARE %STAT IS FIXED<br />
DECLARE %INDX IS FIXED<br />
<br />
FINDLOOP: IN FILE1 FIND ALL RECORDS...<br />
FOR EACH RECORD IN FINDLOOP<br />
STORELOOP: IN FILE2 STORE RECORD<br />
END STORE<br />
%FGO = 1<br />
PAI INTO %FIELDNAM(1), %FIELDVAL(1) FROM %FGO -<br />
COUNT %RET<br />
%STAT = $STATUS<br />
<b></b>* (optional error processing goes here)<br />
FOR RECORD NUMBER IN STORELOOP<br />
FOR %INDX FROM 1 to %RET<br />
IF %FIELDVAL(%INDX) NE &apos;&apos; THEN<br />
ADD %%FIELDNAM(%INDX) = %FIELDVAL(%INDX)<br />
ELSE<br />
ADD %%FIELDNAM(%INDX) = &apos;&apos;<br />
END IF<br />
END FOR<br />
END FOR<br />
END FOR<br />
END<br />
</p><br />
<br />
===Null field values===<br />
<p><br />
Notice that the ADD statement logic in the previous example includes an ELSE clause that forces processing of null field values. This logic is necessary because assigning a null value from a %variable stores nothing in the output file. If you do not need to copy null field values, then omit this special processing. </p><br />
<br />
</div> <!-- end of toc limit div --><br />
<br />
[[Category:SOUL]]</div>Adrianhttps://m204wiki.rocketsoftware.com/index.php?title=Methods&diff=105055Methods2018-02-01T14:21:50Z<p>Adrian: /* Named parameters */</p>
<hr />
<div>As discussed in [[Classes and Objects]], a <var>Class</var> block can contain declaration blocks and/or '''method''' definitions. This page describes the characteristics of these class methods and <br />
their definitions. For information about defining special-purpose methods that are less broadly applicable and therefore not part of the class, see [[Local and Common entities]]. <br />
<br />
==Method definition syntax==<br />
All declaration blocks must appear before any method definitions. A method definition consists of the method header, which is basically a reiteration of the method declaration, the method body (code), and an End method statement:<br />
<p class="syntax"><span class="term">methodHeader</span><br />
<span class="squareb">[</span><span class="term">[[#Internal parameter names|internalNamesBlock]]</span><span class="squareb">]</span><br />
<span class="term">methodBody</span><br />
<span class="literal">End</span> <span class="term">methodType</span> <span class="squareb">[</span><span class="term">methodName</span><span class="squareb">]</span><br />
</p><br />
<br />
The ''methodHeader'' must nearly match the method declaration (which is described in detail in [[Classes and Objects#Method declarations and method types|Method declarations and method types]]), except:<br />
<br />
<ul><br />
<li>Named parameters do not have to appear in the same order. </li><br />
<br />
<li>The optional <var>Public</var>, <var>Private</var>, or <var>Shared</var> indication may be present on one and not the other. </li><br />
</ul><br />
<br />
The parameter names must be present on the method declarations (as opposed to the <var>Declare Subroutine</var> statement) and must match the parameter names in the method header. This redundancy may seem extreme, it has several benefits:<br />
<br />
<ul><br />
<li>It ensures that a complete method description is available in both the declaration block and the method definition. The former is convenient for users of the class and someone trying to understand the class as a whole. The latter is convenient for someone looking at the method in isolation. Meaningful parameter names on the method declarations will make the method functionality much clearer than the parameter datatype alone. </li><br />
<br />
<li>Complete redundancy makes it possible to cut-and-paste or copy a method declaration to the method definition, or vice versa. The method body consists of the code that implements the method or methods. </li><br />
</ul><br />
<br />
<div id="props"></div><br />
<var>Functions</var> and <var>Subroutines</var> have one method, but <var>Properties</var> can have two methods: one for retrieving the property (a <var>Get</var> method), and one for setting the property (a <var>Set</var> method). The <var>Get</var> and <var>Set</var> methods are enclosed in <var>Get</var> and <var>Set</var> blocks:<br />
<br />
<p class="syntax"><span class="literal">Property</span> <span class="term">name</span> <span class="squareb">[</span><span class="term">(parameters)</span><span class="squareb">]</span> <span class="squareb">[</span><span class="literal">Is</span><span class="squareb">]</span> <span class="term">type</span><br />
[[#Internal parameter names|<span class="squareb">[</span><span class="term">internalNamesBlock</span><span class="squareb">]</span>]]<br />
<span class="literal">Get</span><br />
<span class="term">getmethodBody</span><br />
<span class="literal">End Get</span> <span class="squareb">[</span><span class="term">methodName</span><span class="squareb">]</span><br />
<span class="literal">Set</span><br />
<span class="term">setmethodBody</span><br />
<span class="literal">End Set</span> <span class="squareb">[</span><span class="term">methodName</span><span class="squareb">]</span><br />
<span class="literal">End</span> <span class="literal">Property</span> <span class="squareb">[</span><span class="term">methodName</span><span class="squareb">]</span><br />
</p><br />
The <var>Get</var> and <var>Set</var> methods can appear in any order inside the <var>Property</var> definition block, though must both appear within a single property definition block. <var>ReadOnly</var> methods have a <var>Get</var> method only. <var>WriteOnly</var> methods have a <var>Set</var> method only.<br />
<br />
==Comparing methods to complex subroutines==<br />
Methods behave very much like <var class="product">SOUL</var> [[Subroutines|complex subroutines]], and they have some important differences:<br />
<br />
<ul><br />
<li>Methods can have optional parameters, that is, parameters not specified in the method invocation. </li><br />
<br />
<li>Method Input parameters (unless they are arrays) are passed to the method by value &mdash; by copying the corresponding argument values provided when the method is invoked, instead of working with a pointer to the argument values. This copying allows the parameters to be updated within the method without consequence to the arguments outside the method. Method Output parameters are passed by reference &#x2014; pointers to the argument values are passed instead of argument value copies, and updates to the parameters within the method affect the actual arguments outside the method. </li><br />
<br />
<div id="methobj2"></div><br />
<li>Instance-specific (non-<var>Shared</var>) methods always have an implicit input parameter: the object on which they operate, also known as the '''method object'''. This implicit object can be referred to by the parameter name <var>%this</var>.<br />
<br />
<p class="note">'''Note:''' It is not valid to declare a local variable named <code>%this</code> in non-<var>Shared</var> methods because it is implicitly declared by <var class="product">SOUL</var>. </p></li><br />
<br />
<li>The <var>Set</var> method in a <var>Property</var> has another implicit input parameter: the value to which the property is being set. This parameter has the same name as the property. For example, if a property is called <code>Height</code>, the input value in a <var>Set</var> method for an instance-specific (non-shared) method may be referenced as:<br />
<br />
<p class="code">%this:height</p><br />
<br />
<p class="note">'''Note:''' Within the <var>Set</var> method, the input value is copied (not referenced directly), so it may be updated. </p></li><br />
<br />
<li>Methods, being part of a class, can access the <var>Private</var> methods and variables in a class. </li><br />
<br />
<li>All statement labels within a method definition must be unique. </li><br />
<br />
<li>Local variables in methods are always auto-initialized upon entry. They take either their explicit Initial values or implicit initial values by datatype (0 for Fixed and Float, a null string for <var>String</var> and <var>Longstring</var>, a null for Objects). </li><br />
<br />
<li>Local variables are always stacked for recursive entry to methods. That is, if a method is called directly by itself or indirectly by other methods, the subsequent executions get their own copies of all local variables. </li><br />
<br />
<li>Object variables and <var>Longstrings</var> are automatically cleaned up on exit from methods. Object variables are set to null, and if a variable is the last reference to an object, the object is discarded (see, [[Object variables]]). <var>Longstrings</var> are set to null, and any CCATEMP pages associated with the <var>Longstrings</var> are freed. </li><br />
<br />
<li>Methods that return a value must have the return value indicated on the <var>Return</var> statement. </li><br />
</ul><br />
<br />
==Examples of method definitions==<br />
<br />
====Function====<br />
The following is an example of a Function that adds an amount to a private variable and returns the new value:<br />
<br />
<p class="code">class account<br />
private<br />
variable balance is fixed dp 2<br />
end private<br />
public<br />
function adjustBalance(%amount is fixed dp 2) -<br />
is fixed dp 2 callable<br />
end public<br />
<br />
function adjustBalance(%amount is fixed dp 2) is fixed dp 2 callable<br />
%this:balance = %this:balance + %amount<br />
return %this:balance<br />
end function<br />
end class<br />
...<br />
%myAccount is object account<br />
...<br />
%balance = %myAccount:adjustBalance(50.00)<br />
</p><br />
If the application does not need the new balance resulting from the <code>AdjustBalance</code>, the last line could be written:<br />
<br />
<p class="code">%myAccount:adjustBalance(50.00) </p><br />
<br />
As when invoking <var>Variable</var> members of a class, the colon (<tt>:</tt>) that separates the object variable <code>%myaccount</code> and the method <code>adjustBalance</code>, above, may alternatively be specified with a single blank before and/or after it.<br />
<br />
====Property====<br />
The following example illustrates a <var>Property</var> that returns or sets a temperature in Fahrenheit, and that uses a public variable to retrieve or set the Celsius temperature. <br />
<br />
<p class="code">class thermometer<br />
<br />
public<br />
variable celsius is float<br />
property fahrenheit is float<br />
end public<br />
property fahrenheit is float<br />
get<br />
return (1.8 * %this:celsius) + 32<br />
end get<br />
set<br />
%this:celsius = (%fahrenheit - 32) / 1.8<br />
end set<br />
end property fahrenheit<br />
end class<br />
<br />
%temp is object thermometer<br />
...<br />
%temp:fahrenheit = %input<br />
...<br />
print 'Temperature fahrenheit: ' %temp:fahrenheit<br />
print 'Temperature celsius: ' %temp:celsius<br />
</p><br />
<br />
Inside a non-shared method, references to the implicit input object, <code>%this</code>, can omit the &#x201C;this:&#x201D; and refer to public and private class variables as if they were local variables. For example, the above <code>Fahrenheit</code> property could have been written as:<br />
<br />
<p class="code">property fahrenheit is float<br />
get<br />
return (1.8 * %celsius) + 32<br />
end get<br />
...<br />
end property fahrenheit<br />
</p><br />
Nevertheless, the <code>this:</code> can be specified to make clear that a reference is to a class variable or to distinguish a class variable from a local variable:<br />
<br />
<p class="code">property fahrenheit is float<br />
...<br />
set<br />
%celsius is fixed dp 2<br />
%this:celsius = (%fahrenheit - 32) / 1.8<br />
%celsius = %this:celsius<br />
print 'Temperature changed to ' %celsius<br />
end set<br />
end property fahrenheit </p><br />
<br />
Because a local variable is accessed instead of a class variable by the same name, the <code>%this</code> is required to reference the class variable inside a class method. This precedence of local variables ahead of class variables means that public or private variables can be added to a class without fear of &#x201C;breaking&#x201D; methods that might have local variables with the same name. This might be important in very large classes with many methods. There are other cases where the <code>%this</code> is required to access the method object.<br />
<br />
====Subroutine====<br />
The following is an example of a <var>Subroutine</var> that sets a private class variable and then displays all private variables in the class:<br />
<br />
<p class="code">class comic<br />
private<br />
variable name is string len 32<br />
variable pratfalls is fixed<br />
variable trademark is longstring<br />
end private<br />
public<br />
subroutine display(%newName is string len 32)<br />
end public<br />
subroutine display(%newName is string len 32)<br />
%name = %newName<br />
print 'Name = ' %name<br />
print 'Pratfalls = ' %pratfalls<br />
print 'Trademark = ' %trademark<br />
end subroutine display<br />
end class<br />
%stooge is object comic<br />
...<br />
%stooge:display('Curly')<br />
</p><br />
<br />
==<b id="optionalParams"></b>Optional and default parameters==<br />
Methods support optional parameters, that is, parameters that do not need to be passed on every invocation of the method. For example, suppose a function returns the number of items in a bin. And suppose that function can be passed a number of items to add to the bin. Usually when the function is invoked, no items are added, but once in a while, they are. So the function can be declared as follows:<br />
<br />
<p class="code">class bin<br />
...<br />
public<br />
...<br />
function numberOfItems(%add is fixed optional)<br />
...<br />
end public<br />
...<br />
end class </p><br />
<br />
Given this declaration, the function could be invoked as follows:<br />
<br />
<p class="code">%yellow is object bin<br />
...<br />
%yellow = new<br />
...<br />
print %yellow:numberOfItems </p><br />
<br />
It can also be invoked as follows:<br />
<br />
<p class="code">print %yellow:numberOfItems() </p><br />
<br />
And, finally, in cases where a value is to be passed to the method, it could be invoked as follows:<br />
<br />
<p class="code">%items = %yellow:numberOfItems(%number) </p><br />
<br />
When a parameter is optional and it is not passed by the invoker, that parameter has a standard value, based on its datatype, inside the method. This standard value is the standard initial value for a variable of the parameter's datatype. These initial values for each datatype are the following:<br />
<br />
<dl><br />
<dt>String <dd>A null (zero-length) string.<br />
<dt>Longstring <dd>A null (zero-length) string.<br />
<dt>Float <dd>0.<br />
<dt>Fixed <dd>0.<br />
<dt>Object <dd>Null. <br />
<br />
<p class="note"><b>Note:</b> Because specifying the <var>Optional</var> keyword for an <var>Object</var> parameter means that the absence of the parameter presents a null object parameter variable to the method, <var>Optional</var> implies the <var>AllowNull</var> keyword and, in fact, it cannot be specified along with <var>AllowNull</var>. </p><br />
<br />
<dt>Structure <dd>Each item in the structure is given its default initial value, which is the same as indicated in this list for the other datatypes, unless an Initial clause was used in a structure item declaration in the structure definition. So, if a method is defined as follows: <br />
<br />
<p class="code">function square(%number is float optional)<br />
...<br />
return %number * %number<br />
...<br />
end function </p><br />
<br />
The following will print <code>0</code>:<br />
<br />
<p class="code">print %object:square </p><br />
</dl><br />
<br />
For the &#x201C;simple&#x201D; datatypes <var>Fixed</var>, <var>Float</var>, or <var>String</var>, it is possible to specify an alternative value to be passed to a method for an unspecified argument. This is done by specifying the <var>Default</var> keyword instead of <var>Optional</var>. As of Sirius Mods 7.1, default values can also be specified for <var>Enumeration</var> parameters, including <var>Booleans</var>. The <var>Default</var> keyword must be followed by a string, numeric, or enumeration constant in parentheses:<br />
<br />
<p class="code">function square(%number is float default(-1))<br />
...<br />
return %number * %number<br />
...<br />
end function </p><br />
<br />
And the following statement prints <code>1</code> since the square of -1 is 1:<br />
<br />
<p class="code">print %object:square </p><br />
<br />
The following method declaration uses an alternative default string value:<br />
<br />
<p class="code">subroutine addCustomer(%lname is string len 32 -<br />
default('***Unknown***') ) </p><br />
<br />
The following method indicates a default value of <code>Share</code> for a <var>LockStrength</var> enumeration parameter:<br />
<br />
<p class="code">function getRecord(%key is string len 10, -<br />
%ls is enumeration lockstrength default(share)) -<br />
is object record in file foo </p><br />
<br />
Optional or default parameters are allowed on any kind of method: functions, subroutines, properties, or constructors. Constructors, especially, can often benefit greatly from optional parameters as there are often extra qualifiers for newly instantiated objects that might be present, but often are not. For example, one might have a constructor for a product object that allows, but does not require, the specification of a product code:<br />
<br />
<p class="code">constructor new(%productCode is string len 8 optional) </p><br />
<br />
In this example, the <code>New</code> function could then be invoked with or without the optional<br />
product code:<br />
<br />
<p class="code">%cake = new<br />
...<br />
%pie = new('31415929') </p><br />
<br />
===<b id="isPresent"></b>Is [Not] Present test for optional or default parameter===<br />
<br />
Generally, it is sufficient for a method to simply use the replacement value for an optional or default parameter without caring whether that value was specified explicitly or generated implicitly. For example, if a method is declared as follows:<br />
<br />
<p class="code">subroutine increment(%amount is fixed default(1)) </p><br />
<br />
It probably does not matter whether it is invoked as<br />
<br />
<p class="code">%object:increment(1) </p><br />
<br />
or<br />
<br />
<p class="code">%object:increment </p><br />
<br />
However, there may be cases where a method wants to distinguish between the two cases. For example, consider the following class:<br />
<br />
<p class="code">class incident<br />
public<br />
subroutine setComment( -<br />
%comment is string len 64 optional)<br />
...<br />
end public<br />
private<br />
variable haveComment is float<br />
variable comment is string len 64<br />
...<br />
end private<br />
...<br />
end class </p><br />
<br />
A null string might be a valid comment, but it also might be useful to be able to use the <code>SetComment</code> method defined above to indicate that there is no comment. So, it might be necessary to distinguish the following two invocations:<br />
<br />
<p class="code">%object:setComment<br />
...<br />
%object:setComment('') </p><br />
<br />
To make this possible, SOUL provides the <var>Is Present</var> and <var>Is Not Present</var> tests for optional and default method parameters:<br />
<br />
<p class="code">subroutine setComment(%comment is string len 64 optional)<br />
if %comment is present then<br />
%this:haveComment = 1<br />
%this:comment = %comment<br />
else<br />
%this:haveComment = 0<br />
%this:comment = ''<br />
end if<br />
end subroutine setComment </p><br />
<br />
The <var>Is Present</var> and <var>Is Not Present</var> tests can be especially useful in code where the default value is not a constant. The most common example of this is a date parameter that is usually the current date, but not always. For example, consider a constructor that sets the start date for a transaction to the current date, unless an optional date is passed<br />
to the constructor:<br />
<br />
<p class="code">constructor new(%startDate is string len 8 optional)<br />
if %startDate is not present then<br />
%startDate = $sir_date('YYYYMMDD')<br />
end if <br />
... </p><br />
<br />
While the same thing could probably be accomplished, in this case, by checking for a null value, it is a bit neater to check for the presence of the parameter.<br />
<br />
==Named parameters==<br />
Methods support <b>named parameters</b>, that is, parameters that are passed by name rather than position. For example, one might have a method called <code>Roundabout</code> that has a parameter that specifies a value for an exit. It might be invoked as follows:<br />
<p class="code">%bypass:roundabout('KIDLINGTON')<br />
</p><br />
If the first parameter for this method were allowed to be invoked by name, this method might also be invoked as:<br />
<p class="code">%bypass:roundabout(exit='KIDLINGTON')<br />
</p><br />
As this example illustrates, a named parameter is indicated by the name of the parameter followed by an equal sign, which is then followed by any expression that is to be assigned to the parameter.<br />
<br />
Named parameters are supported for both system and user-written methods.<br />
<br />
Arguments that are passed by name are called <b>named</b> arguments, while those that are not are called <b>positional</b> arguments, because their meaning is determined by their position in an argument list. While a method can be invoked with both positional and named arguments, all the positional arguments must precede the named arguments. That is, the following is valid because all the positional arguments precede the named ones:<br />
<p class="code">%mini:addPetrol(24, 'Stratford', price=89.5, brand='BP')<br />
</p><br />
But the following is invalid because the named parameter litres precedes the positional parameter <code>Stratford</code>.<br />
<p class="code">%mini:addPetrol(litres=24, 'Stratford', price=89.5)<br />
</p><br />
A name on an argument can be allowed or required. If allowed, the argument can be specified either positionally or by name. If required, the argument can only be specified by name. Whether the name on an argument is allowed or required has nothing to do with whether the argument is required. That is, just as positional parameters can be required, Optional, or Default, so too can named parameters. That said, named parameters will tend to be optional, since required parameters usually have a fixed position in a parameter list.<br />
<br />
As noted before, system methods can have named parameters. To determine which parameters on a system method are positional, name allowed, or name required, see the documentation for that method. An example of a system method with a name required parameter is the <var>ParseLines</var> method, which has a name required (but optional) <var>StripTrailingNull</var> parameter:<br />
<p class="code"> %list:parseLines(%string, stripTrailingNull=false)<br />
</p><br />
For user-written methods, the distinction between positional, name allowed, and name required parameters is made on the method declaration and definition header. By default, the parameters in user-written methods are positional. For example, in the following method declaration, all parameters are positional:<br />
<p class="code">subroutine display(%customerId is string len 10, -<br />
%startyear is float, -<br />
%showFamily is enumeration boolean optional, -<br />
%showEmployer is enumeration boolean optional, -<br />
%showMedical is enumeration boolean optional)<br />
</p><br />
So the method might be invoked as follows:<br />
<p class="code">%cust:display(%crn, %year, true, , true)<br />
</p><br />
To indicate that a name can be used for a parameter, the <var>NameAllowed</var> keyword should be specified on the parameter declaration:<br />
<p class="code">subroutine display(%customerId is string len 10, -<br />
%startyear is float, -<br />
%showFamily is enumeration boolean optional, -<br />
%showEmployer is enumeration boolean optional, -<br />
%showMedical is enumeration boolean optional nameAllowed)<br />
</p><br />
So that the method could then be invoked either as before, or as follows:<br />
<p class="code">%cust:display(%crn, %year, true, , showMedical=true)<br />
</p><br />
<p class="note">'''Note:''' Even though the parameter name is declared with a leading percent character (<tt>%</tt>), the name of the parameter when invoking the method should exclude the percent character. </p><br />
<br />
If the <var>NameRequired</var> keyword is specified on a parameter definition, the parameter must always be passed as a named argument rather than a positional one:<br />
<p class="code">subroutine display(%customerId is string len 10, -<br />
%startyear is float, -<br />
%showFamily is enumeration boolean optional, -<br />
%showEmployer is enumeration boolean optional, -<br />
%showMedical is enumeration boolean optional nameRequired)<br />
</p><br />
If a parameter other than the last is specified with <var>NameAllowed</var>, all parameters after that are also treated as if <var>NameAllowed</var> were specified on their declarations. That is, the following two declarations are equivalent:<br />
<p class="code">subroutine display(%customerId is string len 10, -<br />
%startyear is float, -<br />
%showFamily is enumeration boolean optional nameAllowed, -<br />
%showEmployer is enumeration boolean optional nameAllowed, -<br />
%showMedical is enumeration boolean optional nameAllowed)<br />
</p><br />
<p class="code">subroutine display(%customerId is string len 10, -<br />
%startyear is float, -<br />
%showFamily is enumeration boolean optional nameAllowed, -<br />
%showEmployer is enumeration boolean optional, -<br />
%showMedical is enumeration boolean optional)<br />
</p><br />
Similarly, a <var>NameRequired</var> keyword implies <var>NameRequired</var> for all subsequent parameters. A NameRequired parameter can follow a NameAllowed parameter though, of course, all parameters after the NameRequired parameter are also assumed to be <var>NameRequired</var>, whether or not that keyword is specified. A NameAllowed parameter cannot follow a NameRequired parameter. Named arguments can be specified in any order, so given the above declaration, the following two invocations are identical:<br />
<p class="code">%cust:display(%crn, %year, showFamily=true, showMedical=false)<br />
</p><br />
<p class="code">%cust:display(%crn, %year, showMedical=false, showFamily=true)<br />
</p><br />
There are many reasons to use named parameters. One is to make method invocations easier to understand. If a method has many parameters, the invocations can look like:<br />
<p class="code">%cust:display(%crn, %year, true, false)<br />
</p><br />
And, if a programmer looking at this did not have the parameters for this method memorized, she would have to go to the method declaration to have an idea of what was being done here. But naming the arguments makes the code much clearer:<br />
<p class="code">%cust:display(%crn, %year, showFamily=true, showMedical=false)<br />
</p><br />
As this example illustrates, named parameters can be particularly useful for boolean switches that alter the behavior of a method, especially when there are many of these switches.<br />
<br />
Another advantage of named parameters is that they are order independent. This means that place-holders do not have to be specified for optional parameters that are not specified on their invocation. This is especially important for methods with many optional parameters. For example, in the absence of named parameters, a method with seven optional parameters might be invoked as follows:<br />
<p class="code">%mini:drive(,,,,,,,65)<br />
</p><br />
Such a call can be made much easier to read, and much less error prone, by using a named parameter:<br />
<p class="code">%mini:drive(speed=65)<br />
</p><br />
Named parameters can also be useful to delay decisions about parameter order. That is, if a method has, say, two optional parameters, and it is not immediately obvious which one is most likely to be used more often (and thus be the first positional parameter), the parameters can be initially declared as NameRequired:<br />
<p class="code">subroutine add(%oil is float optional nameRequired, -<br />
%petrol is float optional nameRequired)<br />
</p><br />
All invocations of the method would then have to use names:<br />
<p class="code">%mg:add(petrol=18)<br />
</p><br />
If after some experience, it is determined that one parameter is much more commonly used than another, that parameter can be changed to a <var>NameAllowed</var> parameter:<br />
<p class="code">subroutine add(%petrol is float optional <var>NameAllowed</var>, -<br />
%oil is float optional nameRequired)<br />
</p><br />
When that change is made, invocations of the method can use the <var>NameAllowed</var> parameter positionally:<br />
<p class="code">%mg:add(18)<br />
</p><br />
Note that this delaying tactic can even be useful with non-optional parameters, if there is a possibility that some of the non-optional parameters might be made optional some day &mdash; perhaps after appropriate defaults are determined.<br />
<br />
Finally, named parameters can be used to &#x201C;rescue&#x201D; a (retrospectively) bad decision about parameter order. For example, if after some use, it is determined that for a method with many parameters, the fifth parameter is more often specified than any of the earlier parameters, it can be turned into a <var>NameAllowed</var> parameter, making it possible to specify that parameter without having to specify the earlier parameters. All this said, named parameters are not a panacea. There are some drawbacks to using named parameters:<br />
<br />
<ul><br />
<li>They make method invocations more verbose, sometimes with little or no benefit. This is especially true for methods with one or two parameters where the meaning of the parameter(s) are obvious from the name of the method.<br />
<br />
<li>Time and care must be taken to chose good parameter names. Once a parameter name is chosen for a named parameter, it can be quite difficult to change it, as this would require changing all code that specifies that parameter name in a method invocation.<br />
</ul><br />
<br />
So, as with most programming constructs, the use of named parameters is an art rather than a science. As named parameters should be used where appropriate, they should be avoided where inappropriate. But other than the vague and not inviolate principle that named parameters are more likely to be useful in methods with more parameters, the appropriateness of named parameters is a subjective matter.<br />
<br />
<p class="note">'''Note:''' A final point should be made about named parameters: their syntax is somewhat of an inconsistency in <var class="product">User Language</var>. In most contexts where user-written expressions are allowed, an equal sign is treated as a comparison operator. </p><br />
<br />
For example, in the following statement the variables <code>%value</code> and <code>%crn</code> are compared, and, if equal, the global <code>CRN</code> is set to 1, otherwise it is set to 0: <br />
<p class="code">$setg('CRN', %value=%crn)<br />
</p><br />
If <code>%value</code> or <code>%crn</code> were not defined, this statement would generate a compilation error.<br />
<br />
Given this syntactic structure, one might expect that a named argument in a method invocation would be interpreted as a comparison of a field name with a value. For example, one might expect the argument to the <var>New</var> method to be the result of a comparison between field <code>Host</code> and the variable <code>%target</code>:<br />
<p class="code">%socket = new(host=%target)<br />
</p><br />
The reality is that the use of the equal sign is almost always limited to conditions in an <var>If</var> statement, so one probably wouldn't expect to find a comparison in the above context. Object-oriented SOUL takes one step further by interpreting any single token followed by an equal sign in a method parameter as a named argument, whether or not what is to the left of the equal sign is a valid parameter name. For example, the following will produce a compilation error, even if <code>%input</code> is a defined variable, and even though it is not a valid parameter name:<br />
<p class="code">%object:doIfTrue(%input = 1)<br />
</p><br />
In the odd cases where one really wants to pass the result of an equality comparison to a method, the alternative character comparison operator can be used:<br />
<p class="code">%object:doIfTrue(%input eq 1)<br />
</p><br />
or, the comparison can be wrapped in an extra parenthesis:<br />
<p class="code">%object:doIfTrue((%input eq 1))<br />
</p><br />
<br />
==Internal parameter names==<br />
A method declaration contains a description of method parameters. A parameter description includes the parameter name, type, and attributes (<var>Optional</var>, <var>AllowNull</var>, and so on). The names should be descriptive, as this makes it easier for users of a method to understand what the method does by looking at its declaration. For example, the following method declaration<br />
<br />
<p class="code">subroutine fill(%petrol is float, %oil is float)</p><br />
<br />
is much more helpful than this declaration:<br />
<br />
<p class="code">subroutine fill(%x is float, %y is float)</p><br />
<br />
With the availability of named parameters, the use of meaningful parameter names becomes even more important, because the parameter names will actually appear in the method invocations:<br />
<br />
<p class="code">%multipla:fill(oil=0.5)</p><br />
<br />
It is possible that the ideal names for method declarations are not the ideal names for the parameters inside the actual methods themselves. For example, one might have a standard that all parameters should start with <code>parm.</code> in method code, so that it is easy to tell which variables are parameters. If this standard is extended to the names on the declaration, the result is ugly and redundant parameter names in declarations and method invocations:<br />
<br />
<p class="code">%multipla:fill(parm.oil=0.5)</p><br />
<br />
The <var>InternalNames</var> block is provided to allow mapping of parameter names on declarations to another name to be used inside the method, making it possible to use the optimal names on method declarations and inside methods, even if the two names are not the same.<br />
<br />
The syntax of the <var>InternalNames</var> block is:<br />
<br />
<p class="syntax"><span class="literal">InternalNames</span><br />
<span class="term">newName</span> <span class="squareb">[</span><span class="literal">Is</span><span class="squareb">]</span> <span class="term">parameterName</span><br />
...<br />
<span class="literal">End InternalNames</span><br />
</p><br />
<br />
Where:<br />
<br />
<table><br />
<tr><th>newName</th><td>The name to be assigned to that parameter for internal use.</td></tr><br />
<tr><th>parameterName</th><td>The name of the parameter as it appears in the method declaration.</td></tr><br />
</table><br />
<br />
The <var>InternalNames</var> statement must be the first statement after a method definition header, which means that for properties it must appear before the <var>Get</var> and <var>Set</var> blocks.<br />
<br />
For properties, the <var>InternalNames</var> block changes the names of parameters for both the <var>Get</var> and <var>Set</var> methods. <var>InternalNames</var> can be used to rename implicit parameters, such as:<br />
<br />
<ul><br />
<li>%this, which is used to reference the method object. </li><br />
<br />
<li>The input value parameter for properties, which has the same name as the property (preceded by a percent). </li><br />
</ul><br />
<br />
In the following example, the input variables <code>%petrol</code> and <code>%oil</code> are mapped to the names <code>%parm.petrol</code> and <code>%parm.oil</code>, respectively:<br />
<br />
<p class="code">subroutine add(%petrol is float nameRequired optional, -<br />
%oil is float nameRequired optional)<br />
internalNames<br />
%parm.petrol is %petrol<br />
%parm.oil is %oil<br />
end internalNames<br />
...<br />
%petrol = %petrol + %parm.petrol<br />
%oil = %oil + %parm.oil<br />
</p><br />
<br />
This example illustrates how if <code>petrol</code> and <code>oil</code> were private class variables, the <var>InternalNames</var> block makes it possible to have parameters in a method declaration with the same name, but to avoid naming conflict or confusion between the private class variables and the parameter names.<br />
<br />
==Stringing method invocations together==<br />
Often, a method will return an object, that is, an instance of a class. In such cases, it is possible to invoke another method against the result object by stringing together method invocations.<br />
<br />
In the following example, the method object for the <code>Slap</code> subroutine is the object returned by the <code>Call</code> function:<br />
<br />
<p class="code">class comic<br />
public<br />
function call(%name is string len 32) is object comic<br />
subroutine slap<br />
...<br />
end public<br />
...<br />
end class<br />
...<br />
%moe is object comic<br />
...<br />
%moe:call('Curly):slap </p><br />
<br />
The same is true for stringing a method invocation to an object variable in a class:<br />
<br />
<p class="code">class comic<br />
public<br />
variable brother is object comic<br />
subroutine slap<br />
...<br />
end public<br />
...<br />
end class<br />
...<br />
%moe is object comic<br />
...<br />
%moe:brother:slap </p><br />
<br />
This stringing of method/variable names can be extended indefinitely and is one of the big advantages of object-oriented syntax over standard procedure syntax. Procedural syntax accomplishes the same economy using nesting:<br />
<br />
<p class="code">call $slap($brother(%moe)) </p><br />
<br />
With procedural syntax, the evaluation is from the inside out and should be read that way. Evaluation of strung-together class members is left to right, and so it can be read in that more natural order. If there is more than one input object to a method, object oriented syntax must also resort to nesting, but this is relatively rare and still requires one fewer nested object than procedural syntax.<br />
<br />
==See also==<br />
<ul><br />
<li>[[Classes and Objects]]<br />
<li>[[Local and Common entities]]<br />
<li>[[Enhancement methods]]<br />
<li>[[Print, Audit, and Trace methods for user objects]]<br />
<li>[[Object oriented programming in SOUL]]<br />
</ul><br />
<br />
[[Category:Overviews]]<br />
[[Category:SOUL object-oriented programming topics]]</div>Adrianhttps://m204wiki.rocketsoftware.com/index.php?title=RKTools&diff=104801RKTools2018-01-02T01:52:58Z<p>Adrian: /* PL command */</p>
<hr />
<div><br />
<var class="product">RKTools</var> &mdash; ''Rocket Tools for Model 204'' &mdash; is a family of products implemented as <var class="product">SOUL</var> [[Application Subsystem development|application subsystems]], designed to function together in a <var class="product">Model&nbsp;204</var> Online. Prior to version 7.5 of RKTools (October, 2015), the product was known as UL/SPF.<br />
<br />
Each [[#components|product in the family]] can be installed and run independently, or each can be installed and run as a component of the integrated <var class="product">RKTools</var> framework. All <var class="product">RKTools</var> products share a common look and feel, providing a highly productive full screen 3270 interface to a variety of common <var class="product">Model&nbsp;204</var> functions. In addition, many of the component subsystems also support web interfaces.<br />
<br />
==<b id="components"></b>RKTools components==<br />
<var class="product">RKTools</var> comprises the following products:<br />
<dl><br />
<dt>[[SirDBA]] <dd>A system that analyzes <var class="product">Model&nbsp;204</var> databases to determine their logical structure, populating an internal catalog. <var class="product">SirDBA</var> is distributed as a component of the Sir2000 Database Analysis Tools.<br />
<br />
<dt>[[SirFile]] <br />
<dd>A comprehensive facility both for monitoring the physical storage utilization of <var class="product">Model&nbsp;204</var> database files and for warning users of the need for file reorganizations. <var class="product">SirFile</var> maintains historical information that allows it to predict when file sizing problems will occur, allowing a DBA to take preventative action before an application outage results.<br />
<br />
<dt>[[SirLib]] <br />
<dd>A powerful and flexible system that provides change management and<br />
configuration control for <var class="product">Model&nbsp;204</var> <var class="product">SOUL</var> applications. <var class="product">SirLib</var> is fully integrated within the <var class="product">SirPro</var> programming environment.<br />
<br />
<dt>[[SirMon]] <br />
<dd>A comprehensive facility for monitoring the performance and availability of <var class="product">Model&nbsp;204</var> online systems. <var class="product">SirMon</var> combines the real time monitoring of<br />
<var class="product">Model&nbsp;204</var> performance with intelligent full screen displays that facilitate System Manager and Administrator duties.<br />
<br />
<dt>[[SirPro]] <br />
<dd>A collection of powerful and easy to use tools for programmers, database administrators, and application managers. <var class="product">SirPro</var> provides programmers with powerful facilities for managing large libraries of <var class="product">SOUL</var> procedures, and it provides system managers with intuitive ISPF-like front ends to many <var class="product">Model&nbsp;204</var> system management commands. <br />
<p><br />
As of <var class="product">RKTools</var> version 7.5, SirPro also incorporates the user-extensible [[SoulEdit]] editor, which can also be invoked from a command line call to the (optional) <var class="product">Model&nbsp;204</var> application subsystem <code>SE</code>. Because the procedure list feature of <var class="product">SirPro</var> is so central, it too has an optional standalone subsystem called <code>PL</code>. </p><br />
<br />
<dt>[[SirScan]] <br />
<dd>A high performance utility that allows users in a <var class="product">Model&nbsp;204</var> Online to browse the contents of its journal in real time. <var class="product">SirScan</var> permits ordinary users to view journal entries generated by their own online session, and it allows users in [[ADMIN SCLASS]]es to browse journal entries for any set of users. The data is displayed in a full-screen browser with powerful searching commands and filtering options.<br />
</dl><br />
<br />
In addition:<br />
<ul><br />
<li>As of version 7.7, RKTools products are accessed by a web interface (<b>[[RKWeb]]</b>) as well as by the traditional 3270 interface. </li><br />
<br />
<li>The <code>FACT</code> subsystem, a utility for browsing <var class="product"><b>[[SirFact]]</b></var> dumps, is indirectly linked into the <var class="product">RKTools</var> menuing structure as [[SirFact FACT subsystem#Using SirPro|a SirPro option]]. <code>FACT</code> is also available from the RKWeb interface (<code>Build > Fact Dump Analysis</code>).</li><br />
<br />
<li>As of version 7.7, RKTools provides access to <b>[[Dictionary/204 overview|Dictionary/204]]</b>, notably including the [[System requirements for Application Subsystems#Overview of the Subsystem Management facility|Subsystem Management facility]] (SUBSYSMGMT) and the [[FILEMGMT overview|File Management facility]] (FILEMGMT). These facilities are available from the RKTools TN3270 main menu and from the RKWeb interface (<code>Manage > Subsystem Management</code> and the <code>Manage > Dictionary</code> sub-menu options).</li><br />
<br />
<li>As of version 7.7, RKTools provides access to the Model&nbsp;204 <b>[[SQL catalog#Using the SQL catalog|SQL Server]]</b> DDL-generation tools CCACATREPT and CCATSF. These facilities are available from the RKTools TN3270 main menu and from the RKWeb interface (<code>Manage > Dictionary > SQL Catalog Reports</code> and <code>Manage > Dictionary > Table Specifications</code>).</li><br />
<br />
<li>As of version 7.7, RKWeb provides access (<code>Build > Tune Reports</code>) to the the reporting portion of <b>[[SirTune]]</b>, the SOUL program <code>SIRTUNEREPORT</code>. </li><br />
<br />
<li>Many sample web and client-server applications developed for the [[Janus TCP/IP Base#The Janus family|Janus product family]] are distributed and installed along with the <var class="product">RKTools</var> products, although they are <i>not</i> linked into the <var class="product">RKTools</var> TN3270 menuing structure. <br />
<p><br />
These applications include: </p><br />
<ul> <br />
<li><code>JanCat</code>, an application that builds normalized views of <var class="product">Model&nbsp;204</var> data for use<br />
by <b><var class="product">[[Media:JsdsrNew.pdf|Janus Specialty Data Store]]</var></b> applications. </li><br />
<br />
<li><code>JanSSL</code>, a <b>[[Janus Network Security]]</b> system for creating and managing SSL certificate requests. This application is available from the RKWeb interface (<code>Manage > SSL Certificates</code>). </li><br />
</ul></li><br />
</ul><br />
<br />
==RKTools packaging and installation requirements==<br />
All of the <var class="product">RKTools</var> products are <var class="product">Model&nbsp;204</var> application subsystems written in <var class="product">SOUL</var>.<br />
<var class="product">RKTools</var> is distributed as a set of <var class="product">Model&nbsp;204</var> files in a backup format produced by the <var class="product">Model&nbsp;204</var> <var>[[DUMP command|DUMP]]</var> command.<br />
<br />
All <var class="product">SOUL</var>-based products are<br />
distributed in a single <var class="product">Model&nbsp;204</var> procedure file. The file is <code>M204PROC</code> as of RKTools 7.7; for earlier versions the file is <code>SIRIUS</code>. <br />
<br />
<var class="product">RKTools</var> makes extensive use of specialized [[Object oriented programming in SOUL|SOUL OO]] classes and $functions. These classes and $functions enable the creation of powerful <var class="product">SOUL</var> application systems that can support complex environments with minimal server size requirements.<br />
<br />
Installing <var class="product">RKTools</var> requires:<br />
<ol><br />
<li>Downloading the <code>M204PROC</code> or <code>SIRIUS</code> file, and restoring it to the <var class="product">Model&nbsp;204</var> environment where the tools will run. </li> <br />
<br />
<li>Setting up some subsidiary <var class="product">Model&nbsp;204</var> files.</li><br />
<br />
<li>Verifying that the environment has the appropriate parameter settings. </li><br />
<br />
<li>Running a program that performs all installation functions for new users and all upgrade functions for reinstalling users. </li><br />
</ol><br />
<br />
For details, see [[RKTools installation]].<br />
<br />
Upgrades to <var class="product">RKTools</var> can almost always be handled by restoring a fresh copy of the <code>M204PROC</code> or <code>SIRIUS</code> file. <br />
<br />
==Integrating <var class="product">RKTools</var> with other subsystems==<br />
<var class="product">RKTools</var> and any of its constituent products can be easily integrated with other <var class="product">SOUL</var> subsystems. Whenever an <var class="product">RKTools</var> component product is exiting, it first checks to see if the global variable <var>SIRIUS.COMM</var> exists and has a non-null value. If so, the <var class="product">RKTools</var> product performs a subsystem transfer using the value in <var>SIRIUS.COMM</var> as the name of the target subsystem.<br />
<br />
For example, the following code fragment lets you transfer into subsystem <code>SIRMON</code>. When <code>SIRMON</code> exits, control is transferred to the application subsystem <code>MENUSYS</code>, provided that <code>NEXT</code> is the current subsystem's communication global variable:<br />
<p class="code">%rc = $Setg('SIRIUS.COMM','MENUSYS')<br />
%rc = $Setg('NEXT','XFER')<br />
%rc = $Setg('XFER','SIRMON')<br />
STOP<br />
</p><br />
<p id="mainmenu"><br />
In addition to the individual <var class="product">SOUL</var> subsystems that implement the <var class="product">RKTools</var> products,<br />
Rocket Software distributes an umbrella <var class="product">RKTools</var> subsystem, accessed by entering <code>RKTOOLS</code> from the Model&nbsp;204 command line. The <b>RKTOOLS</b> subsystem provides a menu that contains entries for all <var class="product">RKTOOLS</var> components installed at a site: </p><br />
<br />
<p class="caption" style="width:450px">RKTools main menu (V7.7)</p><br />
<p class="figure">[[File:RKToolsMainMenu77.png|450px]]</p><br />
<br />
===Fast-pathing===<br />
The <var class="product">RKTOOLS</var> subsystems support fast-path navigation. For example, a <var class="product">SirMon</var> user can transfer into the <var class="product">SirPro</var> main menu option 1 destination (the [[SirPro procedure-list selection]] screen) by using the component subsystem name or short-code along with a menu number: <br />
<p class="code">sirpro 1<br />
</p><br />
Or:<br />
<p class="code">pro 1<br />
</p><br />
And a user in <var class="product">SirScan</var> can enter <code>sirmon 3.1</code> on the command line and be transferred directly to the option 1 (<b>Resource Usage</b>) destination of the <var class="product">SirMon</var> main menu option 3 (<b>User Monitor</b>) screen.<br />
<br />
====PL command====<br />
<var>PL</var> is both a special subsystem and a command that lets you directly enter the [[SirPro procedure-list operations#Overview|Procedure List screen]] in <var class="product">SirPro</var>. The command is like a <code>pro 1</code> fast-path command combined with procedure-search specifications.<br />
<br />
The command format is:<br />
<p class="syntax">PL [<span class="term">procedurePattern</span>] [FILE <span class="term">filename</span> | GROUP <span class="term">groupname</span>][HAS <span = class="term">searchValue</span> | CONTAINS <span = class="term">searchValue</span>]<br />
</p><br />
where <var class="term">procedurePattern</var> supports the wildcard usage described in [[SirPro procedure-list selection#procname|Procedure name]]. <br />
<br />
If you do not specify a <var>FILE</var> or <var>GROUP</var> clause, one of the following is used:<br />
<ul><br />
<li>The current open context. This context is obtained using <code>VIEW APDFCNTX</code> or <code>$view('APDFCNTX')</code> (see the <var>[[DEFCNTX and APDFCNTX parameters|APDFCNTX]]</var> parameter). </li><br />
<br />
<li>The last-visited SirPro procedure list. </li><br />
</ul> <br />
<br />
<blockquote class="note"><br />
<p><b>Note:</b> To search for procedure names that contain the words "FILE" or "GROUP", use a <var>PL</var> command like the following: </p><br />
<p class="code">PL File FILE <i>filename</i></p><br />
<p><br />
where: </p><br />
<ul><br />
<li><code>File</code> indicates procedures whose name contains the word "File".</li><br />
<br />
<li><code>FILE</code> is required because the context is not automatically added if searching for the words "FILE" or "GROUP". </li><br />
</ul><br />
</blockquote><br />
<br />
==Release notes==<br />
Each RKTools release has the version number of the Model&nbsp;204 release whose features it can exploit. <br />
<br />
For information about member product changes and new features contained in a release, see the [[M204wiki main page#rktools_notes|RKTools release notes]] appropriate for your version of Model&nbsp;204: <br />
<ul><br />
<li>[[Release notes for RKTools V7.5]] for Model&nbsp;204 V7.5 </li><br />
<br />
<li>[[Release notes for RKTools V7.7]] for Model&nbsp;204 V7.6 and V7.7 </li><br />
</ul><br />
<br />
[[Category: RKTools]]</div>Adrianhttps://m204wiki.rocketsoftware.com/index.php?title=$D2C&diff=84557$D2C2016-06-09T01:00:07Z<p>Adrian: </p>
<hr />
<div>{{DISPLAYTITLE:$D2C}}<br />
<span class="pageSubtitle">Binary byte representation of integer</span><br />
<br />
<p class="warn"><b>Note: </b>Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $D2C function is <var>[[IntegerToBinary (Float function)|IntegerToBinary]]</var>. For a full list of string and numeric conversion functions see [[List of String methods]] and [[List of Float methods]].</p><br />
<br />
The <var>$D2C</var> function returns a byte string which is the binary equivalent of an integer. <br />
<br />
<var>$D2C</var> accepts one required and one optional argument and returns a byte string value. <br />
<br />
The first argument is the integer to be converted. If it is omitted, or if after conversion to an integer it is outside the range -2,147,483,647..2,147,483,647, the null string is the result. <br />
<br />
The second argument is the number of output bytes in the string. If it is omitted, the first argument must be non-negative, and as many bytes as necessary (1, 2, 3, or 4) are used as the result. If, after conversion to an integer, argument two is not in the range 0..255, the null string is the result. <br />
<br />
The returned result is a byte string representing, in binary, the integer part of argument one. If argument two is omitted, the result has as many bytes needed to represent (the non-negative) argument one. Otherwise, the result is sign-extended to as many bytes as specified in argument two, or truncated. A null string is returned for invalid arguments.<br />
<br />
==Syntax==<br />
<p class="syntax"><span class="term">%result</span> = $D2C(int_val, width)<br />
</p><br />
<br />
<p><var class="term">%result</var> is set to the width-char binary byte representation of <var class="term">int_val</var>.</p><br />
<br />
==Usage notes==<br />
<ul><br />
<li><var>$D2C</var> is similar to the standard <var>[[$BINARY]]</var> function, with some differences, such as being able to specify the output length in bytes rather than bits, and being able to specify results of lengths other than 2 or 4 bytes in length. <br />
<br />
<li>The inverse of <var>$D2C</var> is <var>[[$C2D]]</var>. See also the <var>[[$D2X]]</var> and <var>[[$X2D]]</var> functions and the <var>[[$C2X]]</var> and <var>[[$X2C]]</var> functions.<br />
</ul><br />
<br />
==Example==<br />
The following program will print the value <code>AB</code>:<br />
<br />
<p class="code">B<br />
PRINT $D2C(256 * $X2D('C1') + $X2D('C2'))<br />
END<br />
</p><br />
<br />
Here are some other results, with the result shown as the hexadecimal representation of the returned byte string, or as &apos; &apos; to indicate the null string:<br />
<br />
<p class="code">$D2C(9) -> X'09'<br />
$D2C(129) -> X'81'<br />
$D2C(129, 1) -> X'81'<br />
$D2C(129, 2) -> X'0081'<br />
$D2C(257, 1) -> X'01'<br />
$D2C(-127, 1) -> X'81'<br />
$D2C(-127, 2) -> X'FF81'<br />
$D2C(-127) -> &apos;&apos;<br />
$D2C(-1, 4) -> X'FFFFFFFF'<br />
$D2C(12, 0) -> &apos;&apos;<br />
</p><br />
<br />
==Products authorizing {{PAGENAMEE}}== <br />
<ul class="smallAndTightList"><br />
<li>[[List of $functions|Sirius functions]]</li><br />
<li>[[Fast/Unload User Language Interface]]</li><br />
<li>[[Media:JoclrNew.pdf|Janus Open Client]]</li><br />
<li>[[Media:JosrvrNew.pdf|Janus Open Server]]</li><br />
<li>[[Janus Sockets]]</li><br />
<li>[[Janus Web Server]]</li><br />
<li>Japanese functions</li><br />
<li>[[Media:SirfieldNew.pdf|Sir2000 Field Migration Facility]]</li><br />
</ul><br />
<p class="caption">Products authorizing $D2C<br />
</p><br />
<br />
<br />
[[Category:$Functions|$D2C]]</div>Adrianhttps://m204wiki.rocketsoftware.com/index.php?title=DigestAlgorithm_enumeration&diff=78546DigestAlgorithm enumeration2015-07-25T14:16:29Z<p>Adrian: </p>
<hr />
<div>The <var>DigestAlgorithm</var> enumeration is used by the [[Stringlist_class|StringList]] methods [[AppendSignedCertificate_(Stringlist_function)|AppendSignedCertificate]] and [[AppendSignedClientCertificate_(Stringlist_function)|AppendSignedClientCertificate]] to specify which Signature Algorithm to use when signing certificates for SSL processing.<br />
<br />
Valid enumeration values are:-<br />
<li>MD5</li><br />
<li>SHA1</li> <br />
<li>SHA256</li><br />
<br />
Please note that <var>SHA1</var> is being depreciated by most modern browsers.</div>Adrianhttps://m204wiki.rocketsoftware.com/index.php?title=DigestAlgorithm_enumeration&diff=78545DigestAlgorithm enumeration2015-07-25T14:11:47Z<p>Adrian: </p>
<hr />
<div>The <var>DigestAlgorithm</var> enumeration is used by the [[Stringlist_class|StringList]] methods [[AppendSignedCertificate_(Stringlist_function)|AppendSignedCertificate]] and [[AppendSignedClientCertificate_(Stringlist_function)|AppendSignedClientCertificate]] to specify which Signature Algorithm should be used when signing certificates for SSL processing.<br />
<br />
Valid enumeration values are:-<br />
<li>MD5</li><br />
<li>SHA1</li> <br />
<li>SHA256</li><br />
<br />
Please note that <var>SHA1</var> is being depreciated by most modern browsers.</div>Adrianhttps://m204wiki.rocketsoftware.com/index.php?title=DigestAlgorithm_enumeration&diff=78544DigestAlgorithm enumeration2015-07-25T14:10:30Z<p>Adrian: </p>
<hr />
<div>The <var>DigestAlgorithm</var> enumeration is used by the [[Stringlist_class|StringList]] method [[AppendSignedCertificate_(Stringlist_function)|AppendSignedCertificate]] to specify which Signature Algorithm should be used when signing certificates for SSL processing.<br />
<br />
Valid enumeration values are:-<br />
<li>MD5</li><br />
<li>SHA1</li> <br />
<li>SHA256</li><br />
<br />
Please note that <var>SHA1</var> is being depreciated by most modern browsers.</div>Adrianhttps://m204wiki.rocketsoftware.com/index.php?title=DigestAlgorithm_enumeration&diff=78543DigestAlgorithm enumeration2015-07-25T14:04:13Z<p>Adrian: </p>
<hr />
<div>The <var>DigestAlgorithm</var> enumeration is used by the <var>StringList</var> function <var>AppendSignedCertificate</var> to specify which Signature Algorithm should be used when signing certificates for SSL processing.<br />
<br />
Valid enumeration values are:-<br />
<li>MD5</li><br />
<li>SHA1</li> <br />
<li>SHA256</li><br />
<br />
Please note that <var>SHA1</var> is being depreciated by most modern browsers.</div>Adrianhttps://m204wiki.rocketsoftware.com/index.php?title=DigestAlgorithm_enumeration&diff=78542DigestAlgorithm enumeration2015-07-25T14:03:42Z<p>Adrian: Created page with "The <var>DigestAlgorithm</var> enumeration is used by the <var>StringList</var> function <var>AppendSignedCertificate</var> and is used to specify which Signature Algorithm sh..."</p>
<hr />
<div>The <var>DigestAlgorithm</var> enumeration is used by the <var>StringList</var> function <var>AppendSignedCertificate</var> and is used to specify which Signature Algorithm should be used when signing certificates for SSL processing.<br />
<br />
Valid enumeration values are:-<br />
<li>MD5</li><br />
<li>SHA1</li> <br />
<li>SHA256</li><br />
<br />
Please note that <var>SHA1</var> is being depreciated by most modern browsers.</div>Adrianhttps://m204wiki.rocketsoftware.com/index.php?title=Template:List_of_classes_and_methods&diff=78541Template:List of classes and methods2015-07-25T13:54:38Z<p>Adrian: /* Enumerations */</p>
<hr />
<div>==System classes==<br />
<table><br />
<tr><td style="border-right:0">CharacterMap class:</td><td style="border-left:0">[[CharacterMap class|Synopsis]] | [[List of CharacterMap methods|Methods]]</td></tr><br />
<br />
<tr><td style="border-right:0">CharacterToUnicodeMap class:</td><td style="border-left:0">[[CharacterToUnicodeMap class|Synopsis]] | [[List of CharacterToUnicodeMap methods|Methods]]</td></tr><br />
<br />
<tr><td style="border-right:0">[[Collections|Collection]] classes <ul class="nobul"><li>Arraylist class:<li>FloatNamedArraylist class:<li>NamedArraylist class:<li>UnicodeNamedArraylist class:</ul> </td><br />
<br />
<td style="border-left:0">&nbsp;<ul class="nobulnoindent"><li>[[Arraylist class|Synopsis]] | [[List of Arraylist methods|Methods]]<li>[[FloatNamedArraylist class|Synopsis]] | [[List of FloatNamedArraylist methods|Methods]]<li>[[NamedArraylist class|Synopsis]] | [[List of NamedArraylist methods|Methods]]<li>[[UnicodeNamedArraylist class|Synopsis]] | [[List of UnicodeNamedArraylist methods|Methods]]</ul></td></tr><br />
<br />
<tr><td style="border-right:0">Daemon class:</td><td style="border-left:0">[[Daemon class|Synopsis]] | [[List of Daemon methods|Methods]]</td></tr><br />
<br />
<tr><td style="border-right:0">Dataset class:</td><td style="border-left:0">[[Dataset class|Synopsis]] | [[List of Dataset methods|Methods]]</td></tr><br />
<br />
<tr><td style="border-right:0">Email class:</td><td style="border-left:0">[[Email class|Synopsis]] | [[List of Email methods|Methods]]</td></tr><br />
<br />
<tr><td style="border-right:0">FastUnloadTask class:</td><td style="border-left:0">[[FastUnloadTask class|Synopsis]] | [[List of FastUnloadTask methods|Methods]]</td></tr><br />
<br />
<tr><td style="border-right:0">[[File classes]] <ul class="nobul"><li>Recordset class:<li>Record class:<li>SortedRecordset class:<li>RecordsetCursor class:</ul></td><br />
<td style="border-left:0">&nbsp;<ul class="nobulnoindent"><li>[[Recordset class|Synopsis]] | [[List of Recordset methods|Methods]]<li>[[Record class|Synopsis]] | [[List of Record methods|Methods]]<li>[[SortedRecordset class|Synopsis]] | [[List of SortedRecordset methods|Methods]]<li>[[RecordsetCursor class|Synopsis]] | [[List of RecordsetCursor methods|Methods]]</ul></td></tr><br />
<br />
<tr><td style="border-right:0">[[HTTP Helper|HTTP Helper]] classes: <ul class="nobul"><li>HttpRequest class:<li>HttpResponse class:</ul></td><br />
<td style="border-left:0">[[List of HTTP Helper methods|HTTP Helper methods]]<ul class="nobulnoindent"><li>[[HttpRequest class|Synopsis]] | [[List of HttpRequest methods|Methods]]<li>[[HttpResponse class|Synopsis]] | [[List of HttpResponse methods|Methods]]</ul></td></tr><br />
<br />
<tr><td style="border-right:0">[[Intrinsic classes|Intrinsic]] classes: <ul class="nobul"><li>Float class:<li>String class:<li>Unicode class:</ul></td><br />
<td style="border-left:0">&nbsp;<ul class="nobulnoindent"><li>[[List of Float methods|Methods]]<li>[[List of String methods|Methods]]<li>[[List of Unicode methods|Methods]]</ul></td></tr><br />
<br />
<tr><td style="border-right:0">Journal class:</td><td style="border-left:0">[[Journal class|Synopsis]] | [[List of Journal methods|Methods]]</td></tr><br />
<br />
<tr><td style="border-right:0">Json class:</td><td style="border-left:0">[[Json class|Synopsis]] | [[List of Json methods|Methods]]</td></tr><br />
<br />
<tr><td style="border-right:0">LDAP class:</td><td style="border-left:0">[[LDAP class|Synopsis]] | [[List of LDAP methods|Methods]]</td></tr><br />
<br />
<tr><td style="border-right:0">Object class:</td><td style="border-left:0">[[Object class|Synopsis]] | [[List of Object methods|Methods]]</td></tr><br />
<br />
<tr><td style="border-right:0">PersistentObjectInfo class:</td><td style="border-left:0">[[PersistentObjectInfo class|Synopsis]] | [[List of PersistentObjectInfo methods|Methods]]</td></tr><br />
<br />
<tr><td style="border-right:0">ProcedureInfo class:</td><td style="border-left:0">[[ProcedureInfo class|Synopsis]] | [[List of ProcedureInfo methods|Methods]]</td></tr><br />
<br />
<tr><td style="border-right:0">RandomNumberGenerator class:</td><td style="border-left:0">[[RandomNumberGenerator class|Synopsis]] | [[List of RandomNumberGenerator methods|Methods]]</td></tr><br />
<br />
<tr><td style="border-right:0">Screen and ScreenField classes:</td><br />
<td style="border-left:0">[[Screen classes|Synopsis]] | [[List of Screen API methods|Methods]]</td></tr><br />
<br />
<tr><td style="border-right:0">SelectionCriterion class:</td><td style="border-left:0">[[SelectionCriterion class|Synopsis]] | [[List of SelectionCriterion methods|Methods]]</td></tr><br />
<br />
<tr><td style="border-right:0">Socket class:</td><td style="border-left:0">[[Socket class|Synopsis]] | [[List of Socket methods|Methods]]</td></tr><br />
<br />
<tr><td style="border-right:0">SortOrder class:</td><td style="border-left:0">[[SortOrder class|Synopsis]] | [[List of SortOrder methods|Methods]]</td></tr><br />
<br />
<tr><td style="border-right:0">Stringlist class:</td><td style="border-left:0">[[Stringlist class|Synopsis]] | [[List of Stringlist methods|Methods]]</td></tr><br />
<br />
<tr><td style="border-right:0">StringTokenizer class:</td><td style="border-left:0">[[StringTokenizer class|Synopsis]] | [[List of StringTokenizer methods|Methods]]</td></tr><br />
<br />
<tr><td style="border-right:0"><ul class="nobulnoindent"><li>System class:<li>Subsystem class:</ul></td><br />
<td style="border-left:0"><ul class="nobulnoindent"><li>[[System and Subsystem classes|Synopsis]] | [[List of System methods|Methods]]<li>[[System and Subsystem classes|Synopsis]] | [[List of Subsystem methods|Methods]]</ul></td></tr><br />
<br />
<tr><td style="border-right:0">UdpSocket class:</td><td style="border-left:0">[[UdpSocket class|Synopsis]] | [[List of UdpSocket methods|Methods]]</td></tr><br />
<br />
<tr><td style="border-right:0">UserStatistics class:</td><td style="border-left:0">[[UserStatistics class|Synopsis]] | [[List of UserStatistics methods|Methods]]</td></tr><br />
<br />
<tr><td style="border-right:0">Web class:</td><td style="border-left:0">[[Web class|Synopsis]] | [[List of Web methods|Methods]]</td></tr><br />
<br />
<tr><td style="border-right:0">[[XmlDoc API]] classes <ul class="nobul"><li>XmlDoc class:<li>XmlNode class:<li>XmlNodelist class:</ul> </td><br />
<td style="border-left:0">[[List of XmlDoc API methods|XmlDoc API methods]]<ul class="nobulnoindent"><li>[[XmlDoc API#The XmlDoc class|Synopsis]] | [[List of XmlDoc methods|XmlDoc methods]]<li>[[XmlDoc API#The XmlNode and XmlNodelist classes, and XPath|Synopsis]] | [[List of XmlNode methods|XmlNode methods]]<li>[[XmlDoc API#The XmlNode and XmlNodelist classes, and XPath|Synopsis]] | [[List of XmlNodelist methods|XmlNodelist methods]]</ul></td></tr><br />
<br />
<tr><br />
<td style="border-right:0">[[XmlParser API]] classes <ul class="nobul"><li>XmlParser class:<li>XmlSelector class:<li>XmlAttributeList class:</ul>XmlParser API types <ul class="nobul"><li>[[XmlStartHandler type]]<li>[[XmlEndHandler type]]<li>[[XmlPIHandler type]]</ul> </td><br />
<td style="border-left:0">[[List of XmlParser API methods|XmlParser API methods]]<ul class="nobulnoindent"><li>[[XmlParser class|Synopsis]] | [[List of XmlParser methods|XmlParser methods]]<li>[[XmlSelector class|Synopsis]] | [[List of XmlSelector methods|XmlSelector methods]]<li>[[XmlAttributeListClass|Synopsis]] | [[List of XmlAttributeList methods|XmlAttributeList methods]]</ul></td></tr><br />
</table><br />
<br />
==Enumerations==<br />
<table> <br />
<tr><td colspan="2"><strong>[[Enumerations]]</strong><br />
<table class="noBorder"><tr><td style="border-right:0"><ul class="nobulnoindent"><br />
<li>&nbsp;&nbsp;[[ActionKey enumeration|ActionKey]]</li><br />
<li>&nbsp;&nbsp;[[AddToRecordErrorReason enumeration|AddToRecordErrorReason]] </li><br />
<li>&nbsp;&nbsp;[[Boolean enumeration|Boolean]]</li><br />
<li>&nbsp;&nbsp;[[CursorState enumeration|CursorState]]</li><br />
<li>&nbsp;&nbsp;[[DaemonState enumeration|DaemonState]]</li><br />
<li>&nbsp;&nbsp;[[DatasetState enumeration|DatasetState]]</li><br />
<li>&nbsp;&nbsp;[[DigestAlgorithm enumeration|DigestAlgorithm]]</li><br />
<li>&nbsp;&nbsp;[[FastUnloadTaskState enumeration|FastUnloadTaskState]]</li><br />
<li>&nbsp;&nbsp;[[FieldColor enumeration|FieldColor]]</li><br />
<li>&nbsp;&nbsp;[[Highlight enumeration|Highlight]]</li><br />
<li>&nbsp;&nbsp;[[JsonType enumeration|JsonType]]</li><br />
<li>&nbsp;&nbsp;[[LineEnd enumeration|LineEnd]]</li><br />
<li>&nbsp;&nbsp;[[LockStrength enumeration|LockStrength]]</li><br />
</ul></td><br />
<td style="border-left:0"><ul class="nobul"><br />
<li>&nbsp;&nbsp;&nbsp;[[RecordFormat enumeration|RecordFormat]]</li><br />
<li>&nbsp;&nbsp;&nbsp;[[RecordLockType enumeration|RecordLockType]]</li><br />
<li>&nbsp;&nbsp;&nbsp;[[RegexSplitOutputOptions enumeration|RegexSplitOutputOptions]]</li><br />
<li>&nbsp;&nbsp;&nbsp;[[TranslationExceptionReason enumeration|TranslationExceptionReason]]</li><br />
<li>&nbsp;&nbsp;&nbsp;[[XmlAdjacentTextSetting enumeration|XmlAdjacentTextSetting]]</li><br />
<li>&nbsp;&nbsp;&nbsp;[[XmlInvalidChar enumeration|XmlInvalidChar]]</li><br />
<li>&nbsp;&nbsp;&nbsp;[[XmlNamespaceSetting enumeration|XmlNamespaceSetting]]</li><br />
<li>&nbsp;&nbsp;&nbsp;[[XmlNodeType enumeration|XmlNodeType]]</li><br />
<li>&nbsp;&nbsp;&nbsp;[[XmlParseErrorReason enumeration|XmlParseErrorReason]]</li><br />
<li>&nbsp;&nbsp;&nbsp;[[XPathErrorReason enumeration|XPathErrorReason]]</li><br />
</ul></td></tr></table></td></tr><br />
</table><br />
<br />
==Exceptions==<br />
<table><br />
<tr><td style="border-right:0"><div id="except"></div><strong>[[Exceptions|Exception]]</strong> classes<ul class="nobul"><br />
<li>AddToRecordError: </li><br />
<li>BadJournal: </li><br />
<li>CharacterTranslationException: </li><br />
<li>DaemonLost: </li><br />
<li>IncorrectDaemonState: </li><br />
<li>InvalidBase64Data: </li><br />
<li>InvalidBitNumber: </li><br />
<li>InvalidDateString: </li><br />
<li>InvalidDeflateData: </li><br />
<li>InvalidGZipData: </li><br />
<li>InvalidHexData: </li><br />
<li>InvalidJsonType: </li><br />
<li>InvalidRegex: </li><br />
<li>InvalidSortSpecification: </li><br />
<li>InvalidValue: </li><br />
<li>ItemNotFound: </li><br />
<li>ItemNotPresent: </li><br />
<li>JsonCircularReference: </li><br />
<li>JsonParseError: </li><br />
<li>MaxDaemExceeded: </li><br />
<li>MismatchedQuote: </li><br />
<li>NoFreeDaemons: </li><br />
<li>NotJanusConnection: </li><br />
<li>OutOfBounds: </li><br />
<li>RecordLockingConflict: </li><br />
<li>ScreenReadError: </li><br />
<li>UnknownStatistic: </li><br />
<li>WebScreenException: </li><br />
<li>XmlParseError: </li><br />
<li>XPathError: </li></ul></td><br />
<br />
<td nowrap style="border-left:0">&nbsp;<ul class="nobulnoindent"><br />
<li>[[AddToRecordError class|Synopsis]] | [[AddToRecordError class#The AddToRecordError methods|Methods]]<br />
<li>[[BadJournal class|Synopsis]] | [[BadJournal class#The BadJournal methods|Methods]]<br />
<li>[[CharacterTranslationException class|Synopsis]] | [[CharacterTranslationException class#The CharacterTranslationException methods|Methods]]<br />
<li>[[DaemonLost class|Synopsis]] | [[DaemonLost class#The DaemonLost methods|Methods]]<br />
<li>[[IncorrectDaemonState class|Synopsis]] | [[IncorrectDaemonState class#The IncorrectDaemonState methods|Methods]]<br />
<li>[[InvalidBase64Data class|Synopsis]] | [[InvalidBase64Data class#The InvalidBase64Data methods|Methods]]<br />
<li>[[InvalidBitNumber class|Synopsis]] | [[InvalidBitNumber class#The InvalidBitNumber methods|Methods]]<br />
<li>[[InvalidDateString class|Synopsis]] | [[InvalidDateString class#The InvalidDateString methods|Methods]]<br />
<li>[[InvalidDeflateData class|Synopsis]] | [[InvalidDeflateData class#The InvalidDeflateData methods|Methods]]<br />
<li>[[InvalidGZipData class|Synopsis]] | [[InvalidGZipData class#The InvalidGZipData methods|Methods]]<br />
<li>[[InvalidHexData class|Synopsis]] | [[InvalidHexData class#The InvalidHexData methods|Methods]]<br />
<li>[[InvalidJsonType class|Synopsis]] | [[InvalidJsonType class#The InvalidJsonType methods|Methods]]<br />
<li>[[InvalidRegex class|Synopsis]] | [[InvalidRegex class#The InvalidRegex methods|Methods]]<br />
<li>[[InvalidSortSpecification class|Synopsis]] | [[InvalidSortSpecification class#The InvalidSortSpecification methods|Methods]]<br />
<li>[[InvalidValue class|Synopsis]] | [[InvalidValue class#The InvalidValue methods|Methods]]<br />
<li>[[ItemNotFound class|Synopsis]] | [[ItemNotFound class#The ItemNotFound methods|Methods]]<br />
<li>[[ItemNotPresent class|Synopsis]] | [[ItemNotPresent class#The ItemNotPresent methods|Methods]]<br />
<li>[[JsonCircularReference class|Synopsis]] | [[JsonCircularReference class#The JsonCircularReference methods|Methods]]<br />
<li>[[JsonParseError class|Synopsis]] | [[ JsonParseError class#The JsonParseError methods|Methods]]<br />
<li>[[MaxDaemExceeded class|Synopsis]] | [[MaxDaemExceeded class#The MaxDaemExceeded methods|Methods]]<br />
<li>[[MismatchedQuote class|Synopsis]] | [[MismatchedQuote class#The MismatchedQuote methods|Methods]]<br />
<li>[[NoFreeDaemons class|Synopsis]] | [[NoFreeDaemons class#The NoFreeDaemons methods|Methods]]<br />
<li>[[NotJanusConnection class|Synopsis]] | [[NotJanusConnection class#The NotJanusConnection methods|Methods]]<br />
<li>[[OutOfBounds class|Synopsis]] | [[OutOfBounds class#The OutOfBounds methods|Methods]]<br />
<li>[[RecordLockingConflict class|Synopsis]] | [[RecordLockingConflict class#The RecordLockingConflict methods|Methods]]<br />
<li>[[ScreenReadError class|Synopsis]] | [[ScreenReadError class#The ScreenReadError methods|Methods]]<br />
<li>[[UnknownStatistic class|Synopsis]] | [[UnknownStatistic class#The UnknownStatistic methods|Methods]]<br />
<li>[[WebScreenException class|Synopsis]] | [[WebScreenException class#The WebScreenException methods|Methods]]<br />
<li>[[XmlParseError class|Synopsis]] | [[XmlParseError class#The XmlParseError methods|Methods]]<br />
<li>[[XPathError class|Synopsis]] | [[XPathError class#The XPathError methods|Methods]]</ul></td></tr><br />
</table><br />
<br />
==System types==<br />
<table><br />
<tr><td style="border-right:0"><div id="except"></div>System types<ul class="nobul"><br />
<li>CertificateChecker</li><br />
<li>ProcedureInfoList</li><br />
<li>WebScreenCallback</li><br />
</ul></td> <br />
<td nowrap style="border-left:0">&nbsp;<ul class="nobulnoindent"><br />
<li>[[CertificateChecker type|Synopsis]]</li><br />
<li>[[ProcedureInfoList type|Synopsis]]</li><br />
<li>[[WebScreenCallback type|Synopsis]]</li><br />
</ul></td></tr><br />
</table></div>Adrianhttps://m204wiki.rocketsoftware.com/index.php?title=AppendSignedCertificate_(Stringlist_function)&diff=78540AppendSignedCertificate (Stringlist function)2015-07-25T13:52:16Z<p>Adrian: /* Syntax terms */</p>
<hr />
<div>{{Template:Stringlist:AppendSignedCertificate subtitle}}<br />
<br />
This [[Notation conventions for methods#Callable functions|callable]] method signs an X.509 certificate request and adds the lines of the signed certificate to the end of a <var>Stringlist</var>.<br />
<br />
==Syntax==<br />
{{Template:Stringlist:AppendSignedCertificate syntax}}<br />
<br />
===Syntax terms===<br />
<table class="syntaxTable"><br />
<tr><th>%rc</th><br />
<td>An, optional, numeric variable that is set to zero if the function is a success. The possible return codes are described below in [[#Return codes|"Return codes"]]. </td></tr><br />
<tr><th>sl</th><br />
<td>A <var>Stringlist</var> object.</td></tr><br />
<tr><th><var>PrivateKey</var></th><br />
<td>This [[Notation conventions for methods#Named parameters|name allowed]] argument is a <var>Stringlist</var> that contains the private key to be used for signing.</td></tr><br />
<tr><th><var>Request</var></th><br />
<td>This name allowed argument is a <var>Stringlist</var> that contains the base-64 encoded X.509 certificate request.</td></tr><br />
<tr><th><var>Signer</var></th><br />
<td>This optional, name allowed, argument is a <var>Stringlist</var> that contains the base-64 encoded CA (certifying authority) X.509 certificate. If not specified, the <var>Request</var> <var>Stringlist</var> is used: that is, the certificate will be self-signed. </td></tr><br />
<tr><th><var>StartDate</var></th><br />
<td>This optional, name allowed, argument is a string that contains the Start date for the signed certificate (in YYMMDDHHMISS format). The default is today's date.</td></tr><br />
<tr><th><var>EndDate</var></th><br />
<td>This optional, name allowed, argument is a string that contains the End date for the signed certificate (in YYMMDDHHMISS format). The default is 24 hours from <var>StartDate</var>.</td></tr><br />
<tr><th><var>SerialNumber</var></th><br />
<td>This optional, name allowed, argument is a numeric value that is the Serial number for the signed certificate. The default is a number guaranteed to increase by 1 for every call and guaranteed to increase from run to run, unless there is an extreme amount<br />
of signing occurrences. </td></tr><br />
<tr><th><var>SignatureAlgorithm</var></th><br />
<td>This optional, name allowed, argument is an enumerated <var>DigestAlgorithm</var> value. Valid options are:- <var>MD5</var>, <var>SHA1</var>, <var>SHA256</var>.<br/><b>NOTE:</b> Although supported and currently the default, most modern browsers are deprecating <var>SHA1</var>.</td></tr><br />
</table><br />
<br />
===Return codes===<br />
<table><br />
<tr><th>0</th><td>All is well.</td></tr><br />
<tr><th>3</th><td>Out of CCATEMP.</td></tr><br />
<tr><th>5</th><td><var>Stringlist</var> identifier missing.</td></tr><br />
<tr><th>6</th><td>Invalid <var>Stringlist</var> identifier.</td></tr><br />
<tr><th>7</th><td>Insufficient storage.</td></tr><br />
<tr><th>10</th><td>Private key <var>Stringlist</var> identifier missing.</td></tr><br />
<tr><th>11</th><td>Invalid private key <var>Stringlist</var> identifier.</td></tr><br />
<tr><th>12</th><td>Invalid private key <var>Stringlist</var> data (not correctly base-64 encoded).</td></tr><br />
<tr><th>13</th><td>Certificate request <var>Stringlist</var> identifier missing.</td></tr><br />
<tr><th>14</th><td>Invalid certificate request <var>Stringlist</var> identifier.</td></tr> <br />
<tr><th>15</th><td>Invalid certificate request.</td></tr> <br />
<tr><th>16</th><td>Invalid CA certificate <var>Stringlist</var> identifier.</td></tr> <br />
<tr><th>17</th><td>Invalid CA certificate.</td></tr> <br />
<tr><th>18</th><td>Invalid start date.</td></tr> <br />
<tr><th>19</th><td>Invalid end date.</td></tr> <br />
<tr><th>20</th><td>Invalid serial number.</td></tr> <br />
<tr><th>21</th><td>Private key does not match signer public key.</td></tr><br />
</table><br />
<br />
==Examples==<br />
<br />
==See also==<br />
<ul><br />
<li><var>[[AppendCertificateInfo (Stringlist function)|AppendCertificateInfo]]</var><br />
<li><var>[[AppendCertificateRequest (Stringlist function)|AppendCertificateRequest]]</var><br />
<li><var>[[AppendCertificateRequestInfo (Stringlist function)|AppendCertificateRequestInfo]]</var><br />
<li><var>[[AppendClientCertificateRequest (Stringlist function)|AppendClientCertificateRequest]]</var><br />
<li><var>[[AppendEncryptedSecurityData (Stringlist subroutine)|AppendEncryptedSecurityData]]</var><br />
<li><var>[[AppendGeneratedPrivateKey (Stringlist subroutine)|AppendGeneratedPrivateKey]]</var><br />
<li><var>[[AppendPrivateKeyInfo (Stringlist function)|AppendPrivateKeyInfo]]</var><br />
<li><var>[[AppendSignedClientCertificate (Stringlist function)|AppendSignedClientCertificate]]</var></li><br/><br />
<br />
<li><var>[[CheckCertificate (Stringlist function)|CheckCertificate]]</var><br />
<li><var>[[CheckCertificateRequest (Stringlist function)|CheckCertificateRequest]]</var><br />
<li>[[Release notes for Sirius Mods V8.0#XmlDoc version of SSL entities|DER-to-XmlDoc methods (String class)]]</li><br/><br />
</ul><br />
<br />
{{Template:Stringlist:AppendSignedCertificate footer}}</div>Adrianhttps://m204wiki.rocketsoftware.com/index.php?title=SoulEdit&diff=78352SoulEdit2015-07-21T05:57:08Z<p>Adrian: /* Auditing */</p>
<hr />
<div>'''SoulEdit''' is a code editor, written in SOUL, specifically designed for SOUL application development. SoulEdit features extended editing capability &mdash; like split/join, bookmarks, display filtering and syntax-specific colors &mdash; as well as facilities that make running, debugging, and testing SOUL code more seamless and intuitive.<br />
<br />
SoulEdit runs as an [[Application Subsystem development|application subsystem]], so it needs a subsystem definition along with at least a 640K server size (750K is safer as that provides room for future enhancements and the addition of user-written macros). The [[UL/SPF installation guide]] contains more information about setting up the environment for SoulEdit. <br />
<br />
SoulEdit is built into <var class="product">SirPro</var>, one of the [[ULSPF|UL/SPF]] family of products from Rocket Software, and it can also be run as a standalone editor by setting up a separate application subsystem. At Rocket it runs as an application subsystem called <code>SE</code>, so it is executable from the command line. Details for setting up your own SoulEdit subsystem are also in the UL/SPF installation guide.<br />
<br />
==Overview==<br />
<br />
<var class="product">SirPro</var> is a menu-driven application subsystem that provides tools for programmers, database administrators and application managers inside the Model&nbsp;204 environment. <var class="product">SirPro</var>'s primary feature set is centered on the manipulation of <var class="product">Model 204</var> procedures contained in Model 204 files. To access SoulEdit from <var class="product">SirPro</var>, use the <code>E</code> prefix command from the list of procedures. If SoulEdit is defined as a standalone subsystem (for example, <code>SE</code>), simply type the subsystem name with a procedure: <code>SE MYPROCEDURE</code>, where <code>MYPROCEDURE</code> is a procedure in the current file.<br />
<br />
One of the most useful features of SoulEdit is the ability to run a program via the GO command and immediately view the output in a scrollable [[Stringlist class | StringList]]. If errors occurred while running, a series of <var>AUDIT</var> commands is available to display the audit trail output of the procedure you've just run.<br />
<br />
<p class="caption" style="margin-right:15em">SoulEdit main editing screen</p> <br />
<p class="figure">[[File:SoulEdit_Overview.png|border|750px]] </p><br />
<br />
The top line shows the name of the SOUL procedure, the file where the procedure lives, and a warning if the file is in read-only mode. At the right are shown the line numbers with the current top-of-the-screen line number. Note the color-coding of lines in the sample; colors are user-settable via the <var>COLORS</var> command.<br />
<br />
==Command line options== <br />
<table class="thJustBold"><br />
<tr class="head"><th>Command</th><th>Result</th></tr><br />
<br />
<tr><th>T[<i>n</i>] | TOP [<i>n</i>] | M+PF7 </th><br />
<td>Go to the top of the editor content; optional <i>n</i> (linenum) as top of page. </td></tr><br />
<br />
<tr><th>B | BOTTOM | M+PF8 </th><br />
<td>Go to the bottom of the editor content. </td></tr><br />
<br />
<tr><th>C <i>lineNumber</i> </th><br />
<td>Center the line specified by <i>lineNumber</i>. <i>lineNumber</i> is absolute, not relative. </td></tr><br />
<br />
<tr><th>+ | -<i>numericValue</i> </th><br />
<td>Position content relative to the numeric value. </td></tr><br />
<br />
<tr><th>[-]F | Find <i>value</i> </th><br />
<td>Find previous/next value from cursor position (PF5 repeats last find). </td></tr><br />
<br />
<tr><th>[-]/<i>value</i> </th><br />
<td>Find previous/next value from cursor position (PF5 repeats last find). </td></tr><br />
<br />
<tr><th>R | REPLACE/<i>replaceThis</i>/<i>withThis</i>[[/<i>n</i>] ALL] </th><br />
<td>Replace, where <i>n</i> specifies replacements per line. The character immediately following the <var>R</var> or <var>REPLACE</var> is used as a delimiter between tokens (cannot be alphanumeric). </td></tr><br />
<br />
<tr><th>A | ALL <i>value</i> </th><br />
<td>Hide all lines that do not match <i>value</i>. A command without a <i>value</i> performs a <var>SHOW ALL</var> instead. </td></tr><br />
<br />
<tr><th>HIDE <i>value</i> </th><br />
<td>Hide all lines that match <i>value</i>. </td></tr><br />
<br />
<tr><th>SHOW | HIDE COMMENTS </th><br />
<td>Show or hide all comment lines. </td></tr><br />
<br />
<tr><th>UNHIDE <i>value</i> </th><br />
<td>Unhide all lines that match <i>value</i>. </td></tr><br />
<br />
<tr><th>CLEAR HIDDEN | RESET HIDDEN </th><br />
<td>Clear all hidden lines (unhide). </td></tr><br />
<br />
<tr><th>SHOW ALL | SHOW HIDDEN </th><br />
<td>Clear all hidden lines (unhide). </td></tr><br />
<br />
<tr><th>GO </th><br />
<td>Run the program, and capture the output into a scrollable screen. </td></tr><br />
<br />
<tr><th>[IN <i>fileName</i> ]GET <i>procName</i> </th><br />
<td>Obtain the named procedure and insert into editor. You can use line command targeting. </td></tr><br />
<br />
<tr><th>SAVE[ <i>procName</i>] </th><br />
<td>Save current editor content (optional save into a different named procedure, including temporary procedures). </td></tr><br />
<br />
<tr><th>END </th><br />
<td>Perform <var>SAVE</var> and exit the editor. </td></tr><br />
<br />
<tr><th>QUIT </th><br />
<td>Exit the editor without saving or giving a modification warning. </td></tr><br />
<br />
<tr><th>ALIGN <i>value</i> </th><br />
<td>Requires BB line command range (has issues when crossing "block" statements). </td></tr><br />
<br />
<tr><th>SORT [A | D | ASC | DESC | ASCENDING | DESCENDING]</th><br />
<td>Requires BB line command range. </td></tr> <br />
<br />
<tr><th>CLEAR </th><br />
<td>Clear all line commands. </td></tr><br />
<br />
<tr><th>RESET PROC | RELOAD | RELOAD PROC </th><br />
<td>Discards any changes by reloading the current procedure from file. </td></tr><br />
<br />
<tr><th>REFRESH PAGE </th><br />
<td>Ignore any changes to this page since last enter. </td></tr><br />
<br />
<tr><th>NUM | NUMS | NUMBERS [ON | OFF] </th><br />
<td>Show line numbers in prefix field (toggle). </td></tr><br />
<br />
<tr><th>= </th><br />
<td>Repeat last command (same as PF9). </td></tr><br />
<br />
<tr><th><i>command stack</i> (PF6) </th><br />
<td>Cycles through the command stack. </td></tr><br />
<br />
<tr><th>SET COMMAND STACK <i>n</i> </th><br />
<td>Defaults to 10; user may increase/decrease. </td></tr><br />
<br />
<tr><th>Split/join lines (PF2) </th><br />
<td>Cursor sensitive: if no data from cursor, a join is performed; else split is performed. </td></tr><br />
<br />
<tr><th>FLIP HIDDEN </th><br />
<td>Flip the hidden state of lines: hidden->shown && shown->hidden. </td></tr><br />
<br />
<tr><th>FF | BB+FORMAT - FORMAT [<i>width</i>] [INDENT <i>n</i>] </th><br />
<td>Format range (indents and alignment). <i>Not fully completed, but mostly functional.</i> </td></tr><br />
<br />
<tr><th>UNDO FORMAT </th><br />
<td>Reinstate the last <var>FORMAT</var> to its state before the format (does not check if code has changed). </td></tr><br />
<br />
<tr><th>SET FORMAT <i>type</i> </th><br />
<td>Force the formatting type used by <var>FORMAT/FF</var>. Valid types: M204, XSL. </td></tr><br />
<br />
<tr><th nowrap>RUN (saves and runs code in a daemon)<br />
RUN TERM (saves and runs code on current thread)<br />
RUN [TERM] [<i>procName</i> [FILE <i>filename</i> [PASS <i>password</i>]]] </th><br />
<td>Output from the execution is scrollable (lost daemons are trapped and reported). </td></tr><br />
<br />
<tr><th>SHOW [ [RUN | OUTPUT] | RUN OUTPUT] </th><br />
<td>Show the output from the last executed code or command line VAR/SHOW [SEQ] CHANGES. </td></tr><br />
<br />
<tr><th>SHOW CHANGES </th><br />
<td>Compares current content against procedure on file, and display in a scrollable form. </td></tr><br />
<br />
<tr><th>SHOW SEQ CHANGES </th><br />
<td>Do compare against SEQ version in same procedure file. </td></tr><br />
<br />
<tr><th>SCALE (toggles on/off) </th><br />
<td><code> |...+....1....+....2....+....3...</code> etc. </td></tr><br />
<br />
<tr><th>PFKEYS (toggles on/off) </th><br />
<td>Show valid PF keys on the last line of the page. </td></tr><br />
<br />
<tr><th>NEW PROC[EDURE] </th><br />
<td>Clear current code (essentially a quit), and start with a blank procedure. </td></tr><br />
<br />
<tr><th>Formatting for XSL </th><br />
<td>Change formatting where procedure name ends with <code>.xsl</code>. </td></tr><br />
<br />
<tr><th>HELP (PF1) </th><br />
<td>Display Help text. </td></tr><br />
<br />
<tr><th>VAR | VARS | VARIABLES </th><br />
<td>Show variable usage(counts) within scope. </td></tr><br />
<br />
<tr><th>SETUP | PROFILE </th><br />
<td>Set user editor preferences. </td></tr><br />
<br />
<tr><th>COLORS </th><br />
<td>Set user editor-color preferences. </td></tr><br />
<br />
<tr><th>.<i>value</i> </th><br />
<td>Bookmarks. For example: <code>.foo</code> as a line command bookmarks the line. <code>.foo</code> as a command focuses the bookmark. </td></tr><br />
<br />
<tr><th>CLEAR BOOKMARKS </th><br />
<td>Clear all bookmarks. </td></tr><br />
<br />
<tr><th>XCOMPARE | XC [EXACT | DEBLANK | COMPRESS] </th><br />
<td>XCompares current content against procedure on file; displays in a scrollable form. </td></tr><br />
<br />
<tr><th>XCOMPARE SEQ| XCS [EXACT | DEBLANK | COMPRESS] </th><br />
<td>Do XCompare against SEQ version in same procedure file (only works for SirLib users). </td></tr><br />
<br />
<tr><th>LAYOUT | MAP </th><br />
<td>List all class/subroutines/functions. PF4 focuses entry from listing. </td></tr><br />
<br />
<tr><th>INCLUDES command </th><br />
<td>Show hierarchy of all includes referenced within the current procedure. </td></tr><br />
<br />
<tr><th>PROTECT/UNPROTECT </th><br />
<td>Force the displayed content to be protected/unprotected.</td></tr><br />
<br />
<tr><th>BB | BLOCK WHERE </th><br />
<td>Add BB markers to the current "where" scope. </td></tr><br />
<br />
<tr><th>AUDIT [<i>minutes</i> | <i>timestamp</i> | LAST[RUN]] </th><br />
<td>Shows the journal lines for the user. It defaults to the last minute, unless an optional time is supplied. </td></tr><br />
<br />
<tr><th>SET FILE <i>fileName</i> </th><br />
<td>Sets the file name for saving procedures; also clears the procedure name. </td></tr><br />
<br />
<tr><th>SNAP | SNAPSHOT </th><br />
<td>Takes a copy of the code in the current editing session and saves it as snapshot.</td></tr><br />
<br />
<tr><th>XCB [<i>previous-snapshot-offset</i>] </th><br />
<td>Compare the current code against the last snapshot taken. </td></tr><br />
</table> <br />
<br />
Used in conjunction with the pf12 key on the run output when compilation/runtime errors occur, the following commands can be used to navigate <br />
through the errors in the currently loaded procedure: <br />
<br />
<table class="thJustBold"> <br />
<tr><th>NE | NEXT ERROR </th><br />
<td>Navigate to the next error. </td></tr><br />
<br />
<tr><th>PE | PREVIOUS ERROR </th><br />
<td>Navigate to the previous error. </td></tr><br />
<br />
<tr><th>CE | CURRENT ERROR </th><br />
<td>Navigate to the current error. </td></tr><br />
<br />
<tr><th>CLE | CLEAR ERRORS </th><br />
<td>Clear the error bookmarks. </td></tr><br />
</table> <br />
==Line prefix commands==<br />
<br />
===Block prefixes, with repeating ignored=== <br />
<table class="thJustBold"><br />
<tr><th>CC</th><br />
<td>Block copy (requires targeting prefix). </td></tr><br />
<br />
<tr><th>MM</th><br />
<td>Block move (requires targeting prefix).</td></tr><br />
<br />
<tr><th>DD</th><br />
<td>Block delete.</td></tr><br />
<br />
<tr><th>HH</th><br />
<td>Block hide.</td></tr><br />
<br />
<tr><th>**</th><br />
<td>Block comment (set/clear; first line is used to determine state switch. If first character is <code>*</code>, comments are removed).</td></tr><br />
<br />
<tr><th>BB</th><br />
<td>Block boundaries. Used with editor commands: SORT, ALIGN, FORMAT. Optional for R, REPLACE.</td></tr><br />
<br />
<tr><th>FF</th><br />
<td>Format the specified block. Sets indenting to the number of spaces specified in the user profile.</td></tr><br />
</table><br />
<br />
===Block prefixes, with repeating honored===<br />
For example, <code>""3</code> replicates the block three times.<br />
<br />
<table class="thJustBold"><br />
<tr><th>RR ""</th><br />
<td>Block replicate</td></tr><br />
<br />
<tr><th><< ((</th><br />
<td>Block shift left (with protections to prevent loss of leading text)</td></tr><br />
<br />
<tr><th>>> ))</th><br />
<td>Block shift right (with protections to prevent loss of trailing text)</td></tr><br />
</table><br />
<br />
===Targeting prefixes===<br />
<table class="thJustBold"> <br />
<tr><th>A</th><br />
<td>Target after line</td></tr><br />
<br />
<tr><th>F</th><br />
<td>Target following line </td></tr><br />
<br />
<tr><th>B</th><br />
<td>Target before line</td></tr><br />
<br />
<tr><th> P</th><br />
<td>Target previous line</td></tr><br />
</table><br />
<br />
===Singular prefixes, with repeating ignored===<br />
<table class="thJustBold"> <br />
<tr><th>C</th><br />
<td>Copy (requires targeting prefix).</td></tr><br />
<br />
<tr><th>M</th><br />
<td>Move (requires targeting prefix).</td></tr><br />
<br />
<tr><th>E</th><br />
<td>Expand line to 255 bytes (toggles on/off).</td></tr><br />
<br />
<tr><th>/</th><br />
<td>Center this line.</td></tr><br />
<br />
<tr><th>-</th><br />
<td>Folding of blocks; hide lines from marked line to closing/opening block. <p>Example: <code>if -> end if... </code></p></td></tr><br />
<br />
<tr><th>X</th><br />
<td>Expand/collapse INCLUDE inline. Only usable on <var>INCLUDE</var> lines. The expanded INCLUDE lines are protected.</td></tr><br />
</table><br />
<br />
===Singular prefixes, with repeating honored===<br />
<table class="thJustBold"> <br />
<tr><th>H</th><br />
<td>Hide</td></tr><br />
<br />
<tr><th>S +</th><br />
<td>Show</td></tr><br />
<br />
<tr><th>D</th><br />
<td>Delete</td></tr><br />
<br />
<tr><th>R "</th><br />
<td>Replicate</td></tr><br />
<br />
<tr><th>*</th><br />
<td>Comment (set/clear; if first character is <code>*</code>, comments are removed)</td></tr><br />
<br />
<tr><th>< (</th><br />
<td>Shift line left (with protections to prevent loss of leading text)</td></tr><br />
<br />
<tr><th>> )</th><br />
<td>Shift line right (with protections to prevent loss of trailing text)</td></tr> <br />
</table><br />
<br />
==PF keys==<br />
<table class="thJustBold"><br />
<tr><td>PF1</td><td>Help</td></tr><br />
<br />
<tr><td>PF2</td><td>Split the current line at the cursor, or join the current line with the next line if cursor is at end-of-line.</td></tr><br />
<br />
<tr><td>PF3</td><td>Quit the editor without saving.</td></tr><br />
<br />
<tr><td>PF4</td><td></td></tr> <br />
<br />
<tr><td>PF5</td><td></td></tr><br />
<br />
<tr><td>PF6</td><td>Cycle through the command stack. The command stack size defaults to 10 but can be reset via SET.</td></tr><br />
<br />
<tr><td>PF7</td><td>Scroll up / use with M to scroll to top.</td></tr><br />
<br />
<tr><td>PF8</td><td>Scroll down / use with M to scroll to bottom.</td></tr><br />
<br />
<tr><td>PF9</td><td>Repeat previous command.</td></tr><br />
<br />
<tr><td>PF10</td><td>Shift+PF10 performs an ALL for the text under the cursor.</td></tr><br />
<br />
<tr><td>PF11</td><td>Creates/appends the value under the cursor to a traceText upon the following line.</td></tr><br />
<br />
<tr><td>PF12</td><td>Saves current procedure and opens the INCLUDEd text under the cursor. If the cursor is not on an INCLUDE line, no action is taken.</td></tr><br />
</table><br />
<br />
==User-written extensions (SCMDs)==<br />
<br />
SoulEdit has a facility that lets you add command-line extensions to the editor.<br />
<br />
As an example, INFO is a user-written command-line extension provided by Rocket Software. It provides XML-formatted information about any Model 204 system method (output from a <var>[[LoadSystemMethodInfo (XmlDoc subroutine)|LoadSystemMethodInfo]]</var> method call). If during an ordinary editing session you type <code>info currenttimestring</code> into the command line of SoulEdit:<br />
<br />
<p class="caption" style="margin-right:23em">User-defined command entered on command line</p><br />
<p class="figure">[[File:SOUL_UserCommands1.png|border|500px]]</p><br />
<br />
You see the output of the <var>LoadSystemMethodInfo</var> call displayed in a scrollable screen:<br />
<br />
<p class="figure">[[File:SOUL_UserCommands2.png|border|750px]]</p><br />
<br />
Pressing the PF3 key returns to the in-progress editing session.<br />
<br />
The editor extensions are created via '''SCMD''' procedures stored in a user-designated file. You can see how INFO works by looking at procedure <code>SCMD\INFO</code> in the UL/SPF <code>SIRIUS</code> file.<br />
<br />
To create your own commands, specify the procedure file where they will reside using the <var>PROFILE</var> command and ''Custom Macros File''. SoulEdit scans this file for procedures prefixed with <code>SCMD\</code> and loads them into memory at the beginning of the editing session. Copy <code>SCMD\INFO</code> into your Macros file with a new name, and customize the ''run'' method to your liking.<br />
<br />
==Timed backups==<br />
SoulEdit can take timed backups of the procedures you are editing. This feature can be enabled on a user-by-user basis with the <var>PROFILE</var> command. Backups are taken by default to the same file in which a procedure is being edited. Optionally a separate backup file can be specified, also using <var>PROFILE</var>.<br />
<br />
==Auditing==<br />
SoulEdit has an Auditing feature to list entries from the current journal.<br />
<br />
<var>AUDIT</var> options are:-<br />
<br />
<table><br />
<tr><td>AUDIT</td><td>list the previous 1 minute of the current journal.</td></tr><br />
<tr><td>AUDIT <n></td><td>where <n> is numeric from 1 to 999 indicating how many minutes of the journal to show.</td></tr><br />
<tr><td style="white-space:nowrap;">AUDIT HH:MI[:SS.XX]</td><td>list the journal entries from the specified time. The : and . are optional</td></tr><br />
<tr><td style="white-space:nowrap;">AUDIT LAST[ RUN]</td><td>After running a procedure with the <var>GO</var> or <var>RUN</var> command from inside SoulEdit this command will show all the journal entries pertaining to the job run. It excludes anything not associated with the GO/RUN. In addition to the journal entries for the thread RUN it also includes all spawned child threads by the RUN thread.</td></tr><br />
</table><br />
<br />
The colors used by SoulEdit for displaying journal entries are taken from the users SIRSCAN profile. If the user does not have a SIRISCAN profile then default colors for SIRSCAN are used.<br />
<br />
==See also==<br />
<ul><br />
<li>[[SirPro]] </li><br />
<br />
<li>[[SirLib]] </li><br />
</ul><br />
<br />
[[Category:Sirius Software products]]</div>Adrianhttps://m204wiki.rocketsoftware.com/index.php?title=SoulEdit&diff=78349SoulEdit2015-07-21T05:54:57Z<p>Adrian: /* Auditing */</p>
<hr />
<div>'''SoulEdit''' is a code editor, written in SOUL, specifically designed for SOUL application development. SoulEdit features extended editing capability &mdash; like split/join, bookmarks, display filtering and syntax-specific colors &mdash; as well as facilities that make running, debugging, and testing SOUL code more seamless and intuitive.<br />
<br />
SoulEdit runs as an [[Application Subsystem development|application subsystem]], so it needs a subsystem definition along with at least a 640K server size (750K is safer as that provides room for future enhancements and the addition of user-written macros). The [[UL/SPF installation guide]] contains more information about setting up the environment for SoulEdit. <br />
<br />
SoulEdit is built into <var class="product">SirPro</var>, one of the [[ULSPF|UL/SPF]] family of products from Rocket Software, and it can also be run as a standalone editor by setting up a separate application subsystem. At Rocket it runs as an application subsystem called <code>SE</code>, so it is executable from the command line. Details for setting up your own SoulEdit subsystem are also in the UL/SPF installation guide.<br />
<br />
==Overview==<br />
<br />
<var class="product">SirPro</var> is a menu-driven application subsystem that provides tools for programmers, database administrators and application managers inside the Model&nbsp;204 environment. <var class="product">SirPro</var>'s primary feature set is centered on the manipulation of <var class="product">Model 204</var> procedures contained in Model 204 files. To access SoulEdit from <var class="product">SirPro</var>, use the <code>E</code> prefix command from the list of procedures. If SoulEdit is defined as a standalone subsystem (for example, <code>SE</code>), simply type the subsystem name with a procedure: <code>SE MYPROCEDURE</code>, where <code>MYPROCEDURE</code> is a procedure in the current file.<br />
<br />
One of the most useful features of SoulEdit is the ability to run a program via the GO command and immediately view the output in a scrollable [[Stringlist class | StringList]]. If errors occurred while running, a series of <var>AUDIT</var> commands is available to display the audit trail output of the procedure you've just run.<br />
<br />
<p class="caption" style="margin-right:15em">SoulEdit main editing screen</p> <br />
<p class="figure">[[File:SoulEdit_Overview.png|border|750px]] </p><br />
<br />
The top line shows the name of the SOUL procedure, the file where the procedure lives, and a warning if the file is in read-only mode. At the right are shown the line numbers with the current top-of-the-screen line number. Note the color-coding of lines in the sample; colors are user-settable via the <var>COLORS</var> command.<br />
<br />
==Command line options== <br />
<table class="thJustBold"><br />
<tr class="head"><th>Command</th><th>Result</th></tr><br />
<br />
<tr><th>T[<i>n</i>] | TOP [<i>n</i>] | M+PF7 </th><br />
<td>Go to the top of the editor content; optional <i>n</i> (linenum) as top of page. </td></tr><br />
<br />
<tr><th>B | BOTTOM | M+PF8 </th><br />
<td>Go to the bottom of the editor content. </td></tr><br />
<br />
<tr><th>C <i>lineNumber</i> </th><br />
<td>Center the line specified by <i>lineNumber</i>. <i>lineNumber</i> is absolute, not relative. </td></tr><br />
<br />
<tr><th>+ | -<i>numericValue</i> </th><br />
<td>Position content relative to the numeric value. </td></tr><br />
<br />
<tr><th>[-]F | Find <i>value</i> </th><br />
<td>Find previous/next value from cursor position (PF5 repeats last find). </td></tr><br />
<br />
<tr><th>[-]/<i>value</i> </th><br />
<td>Find previous/next value from cursor position (PF5 repeats last find). </td></tr><br />
<br />
<tr><th>R | REPLACE/<i>replaceThis</i>/<i>withThis</i>[[/<i>n</i>] ALL] </th><br />
<td>Replace, where <i>n</i> specifies replacements per line. The character immediately following the <var>R</var> or <var>REPLACE</var> is used as a delimiter between tokens (cannot be alphanumeric). </td></tr><br />
<br />
<tr><th>A | ALL <i>value</i> </th><br />
<td>Hide all lines that do not match <i>value</i>. A command without a <i>value</i> performs a <var>SHOW ALL</var> instead. </td></tr><br />
<br />
<tr><th>HIDE <i>value</i> </th><br />
<td>Hide all lines that match <i>value</i>. </td></tr><br />
<br />
<tr><th>SHOW | HIDE COMMENTS </th><br />
<td>Show or hide all comment lines. </td></tr><br />
<br />
<tr><th>UNHIDE <i>value</i> </th><br />
<td>Unhide all lines that match <i>value</i>. </td></tr><br />
<br />
<tr><th>CLEAR HIDDEN | RESET HIDDEN </th><br />
<td>Clear all hidden lines (unhide). </td></tr><br />
<br />
<tr><th>SHOW ALL | SHOW HIDDEN </th><br />
<td>Clear all hidden lines (unhide). </td></tr><br />
<br />
<tr><th>GO </th><br />
<td>Run the program, and capture the output into a scrollable screen. </td></tr><br />
<br />
<tr><th>[IN <i>fileName</i> ]GET <i>procName</i> </th><br />
<td>Obtain the named procedure and insert into editor. You can use line command targeting. </td></tr><br />
<br />
<tr><th>SAVE[ <i>procName</i>] </th><br />
<td>Save current editor content (optional save into a different named procedure, including temporary procedures). </td></tr><br />
<br />
<tr><th>END </th><br />
<td>Perform <var>SAVE</var> and exit the editor. </td></tr><br />
<br />
<tr><th>QUIT </th><br />
<td>Exit the editor without saving or giving a modification warning. </td></tr><br />
<br />
<tr><th>ALIGN <i>value</i> </th><br />
<td>Requires BB line command range (has issues when crossing "block" statements). </td></tr><br />
<br />
<tr><th>SORT [A | D | ASC | DESC | ASCENDING | DESCENDING]</th><br />
<td>Requires BB line command range. </td></tr> <br />
<br />
<tr><th>CLEAR </th><br />
<td>Clear all line commands. </td></tr><br />
<br />
<tr><th>RESET PROC | RELOAD | RELOAD PROC </th><br />
<td>Discards any changes by reloading the current procedure from file. </td></tr><br />
<br />
<tr><th>REFRESH PAGE </th><br />
<td>Ignore any changes to this page since last enter. </td></tr><br />
<br />
<tr><th>NUM | NUMS | NUMBERS [ON | OFF] </th><br />
<td>Show line numbers in prefix field (toggle). </td></tr><br />
<br />
<tr><th>= </th><br />
<td>Repeat last command (same as PF9). </td></tr><br />
<br />
<tr><th><i>command stack</i> (PF6) </th><br />
<td>Cycles through the command stack. </td></tr><br />
<br />
<tr><th>SET COMMAND STACK <i>n</i> </th><br />
<td>Defaults to 10; user may increase/decrease. </td></tr><br />
<br />
<tr><th>Split/join lines (PF2) </th><br />
<td>Cursor sensitive: if no data from cursor, a join is performed; else split is performed. </td></tr><br />
<br />
<tr><th>FLIP HIDDEN </th><br />
<td>Flip the hidden state of lines: hidden->shown && shown->hidden. </td></tr><br />
<br />
<tr><th>FF | BB+FORMAT - FORMAT [<i>width</i>] [INDENT <i>n</i>] </th><br />
<td>Format range (indents and alignment). <i>Not fully completed, but mostly functional.</i> </td></tr><br />
<br />
<tr><th>UNDO FORMAT </th><br />
<td>Reinstate the last <var>FORMAT</var> to its state before the format (does not check if code has changed). </td></tr><br />
<br />
<tr><th>SET FORMAT <i>type</i> </th><br />
<td>Force the formatting type used by <var>FORMAT/FF</var>. Valid types: M204, XSL. </td></tr><br />
<br />
<tr><th nowrap>RUN (saves and runs code in a daemon)<br />
RUN TERM (saves and runs code on current thread)<br />
RUN [TERM] [<i>procName</i> [FILE <i>filename</i> [PASS <i>password</i>]]] </th><br />
<td>Output from the execution is scrollable (lost daemons are trapped and reported). </td></tr><br />
<br />
<tr><th>SHOW [ [RUN | OUTPUT] | RUN OUTPUT] </th><br />
<td>Show the output from the last executed code or command line VAR/SHOW [SEQ] CHANGES. </td></tr><br />
<br />
<tr><th>SHOW CHANGES </th><br />
<td>Compares current content against procedure on file, and display in a scrollable form. </td></tr><br />
<br />
<tr><th>SHOW SEQ CHANGES </th><br />
<td>Do compare against SEQ version in same procedure file. </td></tr><br />
<br />
<tr><th>SCALE (toggles on/off) </th><br />
<td><code> |...+....1....+....2....+....3...</code> etc. </td></tr><br />
<br />
<tr><th>PFKEYS (toggles on/off) </th><br />
<td>Show valid PF keys on the last line of the page. </td></tr><br />
<br />
<tr><th>NEW PROC[EDURE] </th><br />
<td>Clear current code (essentially a quit), and start with a blank procedure. </td></tr><br />
<br />
<tr><th>Formatting for XSL </th><br />
<td>Change formatting where procedure name ends with <code>.xsl</code>. </td></tr><br />
<br />
<tr><th>HELP (PF1) </th><br />
<td>Display Help text. </td></tr><br />
<br />
<tr><th>VAR | VARS | VARIABLES </th><br />
<td>Show variable usage(counts) within scope. </td></tr><br />
<br />
<tr><th>SETUP | PROFILE </th><br />
<td>Set user editor preferences. </td></tr><br />
<br />
<tr><th>COLORS </th><br />
<td>Set user editor-color preferences. </td></tr><br />
<br />
<tr><th>.<i>value</i> </th><br />
<td>Bookmarks. For example: <code>.foo</code> as a line command bookmarks the line. <code>.foo</code> as a command focuses the bookmark. </td></tr><br />
<br />
<tr><th>CLEAR BOOKMARKS </th><br />
<td>Clear all bookmarks. </td></tr><br />
<br />
<tr><th>XCOMPARE | XC [EXACT | DEBLANK | COMPRESS] </th><br />
<td>XCompares current content against procedure on file; displays in a scrollable form. </td></tr><br />
<br />
<tr><th>XCOMPARE SEQ| XCS [EXACT | DEBLANK | COMPRESS] </th><br />
<td>Do XCompare against SEQ version in same procedure file (only works for SirLib users). </td></tr><br />
<br />
<tr><th>LAYOUT | MAP </th><br />
<td>List all class/subroutines/functions. PF4 focuses entry from listing. </td></tr><br />
<br />
<tr><th>INCLUDES command </th><br />
<td>Show hierarchy of all includes referenced within the current procedure. </td></tr><br />
<br />
<tr><th>PROTECT/UNPROTECT </th><br />
<td>Force the displayed content to be protected/unprotected.</td></tr><br />
<br />
<tr><th>BB | BLOCK WHERE </th><br />
<td>Add BB markers to the current "where" scope. </td></tr><br />
<br />
<tr><th>AUDIT [<i>minutes</i> | <i>timestamp</i> | LAST[RUN]] </th><br />
<td>Shows the journal lines for the user. It defaults to the last minute, unless an optional time is supplied. </td></tr><br />
<br />
<tr><th>SET FILE <i>fileName</i> </th><br />
<td>Sets the file name for saving procedures; also clears the procedure name. </td></tr><br />
<br />
<tr><th>SNAP | SNAPSHOT </th><br />
<td>Takes a copy of the code in the current editing session and saves it as snapshot.</td></tr><br />
<br />
<tr><th>XCB [<i>previous-snapshot-offset</i>] </th><br />
<td>Compare the current code against the last snapshot taken. </td></tr><br />
</table> <br />
<br />
Used in conjunction with the pf12 key on the run output when compilation/runtime errors occur, the following commands can be used to navigate <br />
through the errors in the currently loaded procedure: <br />
<br />
<table class="thJustBold"> <br />
<tr><th>NE | NEXT ERROR </th><br />
<td>Navigate to the next error. </td></tr><br />
<br />
<tr><th>PE | PREVIOUS ERROR </th><br />
<td>Navigate to the previous error. </td></tr><br />
<br />
<tr><th>CE | CURRENT ERROR </th><br />
<td>Navigate to the current error. </td></tr><br />
<br />
<tr><th>CLE | CLEAR ERRORS </th><br />
<td>Clear the error bookmarks. </td></tr><br />
</table> <br />
==Line prefix commands==<br />
<br />
===Block prefixes, with repeating ignored=== <br />
<table class="thJustBold"><br />
<tr><th>CC</th><br />
<td>Block copy (requires targeting prefix). </td></tr><br />
<br />
<tr><th>MM</th><br />
<td>Block move (requires targeting prefix).</td></tr><br />
<br />
<tr><th>DD</th><br />
<td>Block delete.</td></tr><br />
<br />
<tr><th>HH</th><br />
<td>Block hide.</td></tr><br />
<br />
<tr><th>**</th><br />
<td>Block comment (set/clear; first line is used to determine state switch. If first character is <code>*</code>, comments are removed).</td></tr><br />
<br />
<tr><th>BB</th><br />
<td>Block boundaries. Used with editor commands: SORT, ALIGN, FORMAT. Optional for R, REPLACE.</td></tr><br />
<br />
<tr><th>FF</th><br />
<td>Format the specified block. Sets indenting to the number of spaces specified in the user profile.</td></tr><br />
</table><br />
<br />
===Block prefixes, with repeating honored===<br />
For example, <code>""3</code> replicates the block three times.<br />
<br />
<table class="thJustBold"><br />
<tr><th>RR ""</th><br />
<td>Block replicate</td></tr><br />
<br />
<tr><th><< ((</th><br />
<td>Block shift left (with protections to prevent loss of leading text)</td></tr><br />
<br />
<tr><th>>> ))</th><br />
<td>Block shift right (with protections to prevent loss of trailing text)</td></tr><br />
</table><br />
<br />
===Targeting prefixes===<br />
<table class="thJustBold"> <br />
<tr><th>A</th><br />
<td>Target after line</td></tr><br />
<br />
<tr><th>F</th><br />
<td>Target following line </td></tr><br />
<br />
<tr><th>B</th><br />
<td>Target before line</td></tr><br />
<br />
<tr><th> P</th><br />
<td>Target previous line</td></tr><br />
</table><br />
<br />
===Singular prefixes, with repeating ignored===<br />
<table class="thJustBold"> <br />
<tr><th>C</th><br />
<td>Copy (requires targeting prefix).</td></tr><br />
<br />
<tr><th>M</th><br />
<td>Move (requires targeting prefix).</td></tr><br />
<br />
<tr><th>E</th><br />
<td>Expand line to 255 bytes (toggles on/off).</td></tr><br />
<br />
<tr><th>/</th><br />
<td>Center this line.</td></tr><br />
<br />
<tr><th>-</th><br />
<td>Folding of blocks; hide lines from marked line to closing/opening block. <p>Example: <code>if -> end if... </code></p></td></tr><br />
<br />
<tr><th>X</th><br />
<td>Expand/collapse INCLUDE inline. Only usable on <var>INCLUDE</var> lines. The expanded INCLUDE lines are protected.</td></tr><br />
</table><br />
<br />
===Singular prefixes, with repeating honored===<br />
<table class="thJustBold"> <br />
<tr><th>H</th><br />
<td>Hide</td></tr><br />
<br />
<tr><th>S +</th><br />
<td>Show</td></tr><br />
<br />
<tr><th>D</th><br />
<td>Delete</td></tr><br />
<br />
<tr><th>R "</th><br />
<td>Replicate</td></tr><br />
<br />
<tr><th>*</th><br />
<td>Comment (set/clear; if first character is <code>*</code>, comments are removed)</td></tr><br />
<br />
<tr><th>< (</th><br />
<td>Shift line left (with protections to prevent loss of leading text)</td></tr><br />
<br />
<tr><th>> )</th><br />
<td>Shift line right (with protections to prevent loss of trailing text)</td></tr> <br />
</table><br />
<br />
==PF keys==<br />
<table class="thJustBold"><br />
<tr><td>PF1</td><td>Help</td></tr><br />
<br />
<tr><td>PF2</td><td>Split the current line at the cursor, or join the current line with the next line if cursor is at end-of-line.</td></tr><br />
<br />
<tr><td>PF3</td><td>Quit the editor without saving.</td></tr><br />
<br />
<tr><td>PF4</td><td></td></tr> <br />
<br />
<tr><td>PF5</td><td></td></tr><br />
<br />
<tr><td>PF6</td><td>Cycle through the command stack. The command stack size defaults to 10 but can be reset via SET.</td></tr><br />
<br />
<tr><td>PF7</td><td>Scroll up / use with M to scroll to top.</td></tr><br />
<br />
<tr><td>PF8</td><td>Scroll down / use with M to scroll to bottom.</td></tr><br />
<br />
<tr><td>PF9</td><td>Repeat previous command.</td></tr><br />
<br />
<tr><td>PF10</td><td>Shift+PF10 performs an ALL for the text under the cursor.</td></tr><br />
<br />
<tr><td>PF11</td><td>Creates/appends the value under the cursor to a traceText upon the following line.</td></tr><br />
<br />
<tr><td>PF12</td><td>Saves current procedure and opens the INCLUDEd text under the cursor. If the cursor is not on an INCLUDE line, no action is taken.</td></tr><br />
</table><br />
<br />
==User-written extensions (SCMDs)==<br />
<br />
SoulEdit has a facility that lets you add command-line extensions to the editor.<br />
<br />
As an example, INFO is a user-written command-line extension provided by Rocket Software. It provides XML-formatted information about any Model 204 system method (output from a <var>[[LoadSystemMethodInfo (XmlDoc subroutine)|LoadSystemMethodInfo]]</var> method call). If during an ordinary editing session you type <code>info currenttimestring</code> into the command line of SoulEdit:<br />
<br />
<p class="caption" style="margin-right:23em">User-defined command entered on command line</p><br />
<p class="figure">[[File:SOUL_UserCommands1.png|border|500px]]</p><br />
<br />
You see the output of the <var>LoadSystemMethodInfo</var> call displayed in a scrollable screen:<br />
<br />
<p class="figure">[[File:SOUL_UserCommands2.png|border|750px]]</p><br />
<br />
Pressing the PF3 key returns to the in-progress editing session.<br />
<br />
The editor extensions are created via '''SCMD''' procedures stored in a user-designated file. You can see how INFO works by looking at procedure <code>SCMD\INFO</code> in the UL/SPF <code>SIRIUS</code> file.<br />
<br />
To create your own commands, specify the procedure file where they will reside using the <var>PROFILE</var> command and ''Custom Macros File''. SoulEdit scans this file for procedures prefixed with <code>SCMD\</code> and loads them into memory at the beginning of the editing session. Copy <code>SCMD\INFO</code> into your Macros file with a new name, and customize the ''run'' method to your liking.<br />
<br />
==Timed backups==<br />
SoulEdit can take timed backups of the procedures you are editing. This feature can be enabled on a user-by-user basis with the <var>PROFILE</var> command. Backups are taken by default to the same file in which a procedure is being edited. Optionally a separate backup file can be specified, also using <var>PROFILE</var>.<br />
<br />
==Auditing==<br />
SoulEdit has an Auditing feature to list entries from the current journal.<br />
<br />
<var>AUDIT</var> options are:-<br />
<br />
<table><br />
<tr><td>AUDIT</td><td>list the previous 1 minute of the current journal.</td></tr><br />
<tr><td>AUDIT <n></td><td>where <n> is numeric from 1 to 999 indicating how many minutes of the journal to show.</td></tr><br />
<tr><td style="white-space:nowrap;">AUDIT HH:MI[:SS.XX]</td><td>list the journal entries from the specified time. The : and . are optional</td></tr><br />
<tr><td style="white-space:nowrap;">AUDIT LAST[ RUN]</td><td>After running a procedure with the <var>GO</var> or <var>RUN</var> command from inside SoulEdit this command will show all the journal entries pertaining to the job run. It excludes anything not associated with the GO/RUN. In addition to the journal entries for the thread RUN it also includes all spawned child threads by the RUN thread.</td></tr><br />
</table><br />
<br />
==See also==<br />
<ul><br />
<li>[[SirPro]] </li><br />
<br />
<li>[[SirLib]] </li><br />
</ul><br />
<br />
[[Category:Sirius Software products]]</div>Adrianhttps://m204wiki.rocketsoftware.com/index.php?title=SoulEdit&diff=78338SoulEdit2015-07-21T05:23:47Z<p>Adrian: /* Auditing */</p>
<hr />
<div>'''SoulEdit''' is a code editor, written in SOUL, specifically designed for SOUL application development. SoulEdit features extended editing capability &mdash; like split/join, bookmarks, display filtering and syntax-specific colors &mdash; as well as facilities that make running, debugging, and testing SOUL code more seamless and intuitive.<br />
<br />
SoulEdit runs as an [[Application Subsystem development|application subsystem]], so it needs a subsystem definition along with at least a 640K server size (750K is safer as that provides room for future enhancements and the addition of user-written macros). The [[UL/SPF installation guide]] contains more information about setting up the environment for SoulEdit. <br />
<br />
SoulEdit is built into <var class="product">SirPro</var>, one of the [[ULSPF|UL/SPF]] family of products from Rocket Software, and it can also be run as a standalone editor by setting up a separate application subsystem. At Rocket it runs as an application subsystem called <code>SE</code>, so it is executable from the command line. Details for setting up your own SoulEdit subsystem are also in the UL/SPF installation guide.<br />
<br />
==Overview==<br />
<br />
<var class="product">SirPro</var> is a menu-driven application subsystem that provides tools for programmers, database administrators and application managers inside the Model&nbsp;204 environment. <var class="product">SirPro</var>'s primary feature set is centered on the manipulation of <var class="product">Model 204</var> procedures contained in Model 204 files. To access SoulEdit from <var class="product">SirPro</var>, use the <code>E</code> prefix command from the list of procedures. If SoulEdit is defined as a standalone subsystem (for example, <code>SE</code>), simply type the subsystem name with a procedure: <code>SE MYPROCEDURE</code>, where <code>MYPROCEDURE</code> is a procedure in the current file.<br />
<br />
One of the most useful features of SoulEdit is the ability to run a program via the GO command and immediately view the output in a scrollable [[Stringlist class | StringList]]. If errors occurred while running, a series of <var>AUDIT</var> commands is available to display the audit trail output of the procedure you've just run.<br />
<br />
<p class="caption" style="margin-right:15em">SoulEdit main editing screen</p> <br />
<p class="figure">[[File:SoulEdit_Overview.png|border|750px]] </p><br />
<br />
The top line shows the name of the SOUL procedure, the file where the procedure lives, and a warning if the file is in read-only mode. At the right are shown the line numbers with the current top-of-the-screen line number. Note the color-coding of lines in the sample; colors are user-settable via the <var>COLORS</var> command.<br />
<br />
==Command line options== <br />
<table class="thJustBold"><br />
<tr class="head"><th>Command</th><th>Result</th></tr><br />
<br />
<tr><th>T[<i>n</i>] | TOP [<i>n</i>] | M+PF7 </th><br />
<td>Go to the top of the editor content; optional <i>n</i> (linenum) as top of page. </td></tr><br />
<br />
<tr><th>B | BOTTOM | M+PF8 </th><br />
<td>Go to the bottom of the editor content. </td></tr><br />
<br />
<tr><th>C <i>lineNumber</i> </th><br />
<td>Center the line specified by <i>lineNumber</i>. <i>lineNumber</i> is absolute, not relative. </td></tr><br />
<br />
<tr><th>+ | -<i>numericValue</i> </th><br />
<td>Position content relative to the numeric value. </td></tr><br />
<br />
<tr><th>[-]F | Find <i>value</i> </th><br />
<td>Find previous/next value from cursor position (PF5 repeats last find). </td></tr><br />
<br />
<tr><th>[-]/<i>value</i> </th><br />
<td>Find previous/next value from cursor position (PF5 repeats last find). </td></tr><br />
<br />
<tr><th>R | REPLACE/<i>replaceThis</i>/<i>withThis</i>[[/<i>n</i>] ALL] </th><br />
<td>Replace, where <i>n</i> specifies replacements per line. The character immediately following the <var>R</var> or <var>REPLACE</var> is used as a delimiter between tokens (cannot be alphanumeric). </td></tr><br />
<br />
<tr><th>A | ALL <i>value</i> </th><br />
<td>Hide all lines that do not match <i>value</i>. A command without a <i>value</i> performs a <var>SHOW ALL</var> instead. </td></tr><br />
<br />
<tr><th>HIDE <i>value</i> </th><br />
<td>Hide all lines that match <i>value</i>. </td></tr><br />
<br />
<tr><th>SHOW | HIDE COMMENTS </th><br />
<td>Show or hide all comment lines. </td></tr><br />
<br />
<tr><th>UNHIDE <i>value</i> </th><br />
<td>Unhide all lines that match <i>value</i>. </td></tr><br />
<br />
<tr><th>CLEAR HIDDEN | RESET HIDDEN </th><br />
<td>Clear all hidden lines (unhide). </td></tr><br />
<br />
<tr><th>SHOW ALL | SHOW HIDDEN </th><br />
<td>Clear all hidden lines (unhide). </td></tr><br />
<br />
<tr><th>GO </th><br />
<td>Run the program, and capture the output into a scrollable screen. </td></tr><br />
<br />
<tr><th>[IN <i>fileName</i> ]GET <i>procName</i> </th><br />
<td>Obtain the named procedure and insert into editor. You can use line command targeting. </td></tr><br />
<br />
<tr><th>SAVE[ <i>procName</i>] </th><br />
<td>Save current editor content (optional save into a different named procedure, including temporary procedures). </td></tr><br />
<br />
<tr><th>END </th><br />
<td>Perform <var>SAVE</var> and exit the editor. </td></tr><br />
<br />
<tr><th>QUIT </th><br />
<td>Exit the editor without saving or giving a modification warning. </td></tr><br />
<br />
<tr><th>ALIGN <i>value</i> </th><br />
<td>Requires BB line command range (has issues when crossing "block" statements). </td></tr><br />
<br />
<tr><th>SORT [A | D | ASC | DESC | ASCENDING | DESCENDING]</th><br />
<td>Requires BB line command range. </td></tr> <br />
<br />
<tr><th>CLEAR </th><br />
<td>Clear all line commands. </td></tr><br />
<br />
<tr><th>RESET PROC | RELOAD | RELOAD PROC </th><br />
<td>Discards any changes by reloading the current procedure from file. </td></tr><br />
<br />
<tr><th>REFRESH PAGE </th><br />
<td>Ignore any changes to this page since last enter. </td></tr><br />
<br />
<tr><th>NUM | NUMS | NUMBERS [ON | OFF] </th><br />
<td>Show line numbers in prefix field (toggle). </td></tr><br />
<br />
<tr><th>= </th><br />
<td>Repeat last command (same as PF9). </td></tr><br />
<br />
<tr><th><i>command stack</i> (PF6) </th><br />
<td>Cycles through the command stack. </td></tr><br />
<br />
<tr><th>SET COMMAND STACK <i>n</i> </th><br />
<td>Defaults to 10; user may increase/decrease. </td></tr><br />
<br />
<tr><th>Split/join lines (PF2) </th><br />
<td>Cursor sensitive: if no data from cursor, a join is performed; else split is performed. </td></tr><br />
<br />
<tr><th>FLIP HIDDEN </th><br />
<td>Flip the hidden state of lines: hidden->shown && shown->hidden. </td></tr><br />
<br />
<tr><th>FF | BB+FORMAT - FORMAT [<i>width</i>] [INDENT <i>n</i>] </th><br />
<td>Format range (indents and alignment). <i>Not fully completed, but mostly functional.</i> </td></tr><br />
<br />
<tr><th>UNDO FORMAT </th><br />
<td>Reinstate the last <var>FORMAT</var> to its state before the format (does not check if code has changed). </td></tr><br />
<br />
<tr><th>SET FORMAT <i>type</i> </th><br />
<td>Force the formatting type used by <var>FORMAT/FF</var>. Valid types: M204, XSL. </td></tr><br />
<br />
<tr><th nowrap>RUN (saves and runs code in a daemon)<br />
RUN TERM (saves and runs code on current thread)<br />
RUN [TERM] [<i>procName</i> [FILE <i>filename</i> [PASS <i>password</i>]]] </th><br />
<td>Output from the execution is scrollable (lost daemons are trapped and reported). </td></tr><br />
<br />
<tr><th>SHOW [ [RUN | OUTPUT] | RUN OUTPUT] </th><br />
<td>Show the output from the last executed code or command line VAR/SHOW [SEQ] CHANGES. </td></tr><br />
<br />
<tr><th>SHOW CHANGES </th><br />
<td>Compares current content against procedure on file, and display in a scrollable form. </td></tr><br />
<br />
<tr><th>SHOW SEQ CHANGES </th><br />
<td>Do compare against SEQ version in same procedure file. </td></tr><br />
<br />
<tr><th>SCALE (toggles on/off) </th><br />
<td><code> |...+....1....+....2....+....3...</code> etc. </td></tr><br />
<br />
<tr><th>PFKEYS (toggles on/off) </th><br />
<td>Show valid PF keys on the last line of the page. </td></tr><br />
<br />
<tr><th>NEW PROC[EDURE] </th><br />
<td>Clear current code (essentially a quit), and start with a blank procedure. </td></tr><br />
<br />
<tr><th>Formatting for XSL </th><br />
<td>Change formatting where procedure name ends with <code>.xsl</code>. </td></tr><br />
<br />
<tr><th>HELP (PF1) </th><br />
<td>Display Help text. </td></tr><br />
<br />
<tr><th>VAR | VARS | VARIABLES </th><br />
<td>Show variable usage(counts) within scope. </td></tr><br />
<br />
<tr><th>SETUP | PROFILE </th><br />
<td>Set user editor preferences. </td></tr><br />
<br />
<tr><th>COLORS </th><br />
<td>Set user editor-color preferences. </td></tr><br />
<br />
<tr><th>.<i>value</i> </th><br />
<td>Bookmarks. For example: <code>.foo</code> as a line command bookmarks the line. <code>.foo</code> as a command focuses the bookmark. </td></tr><br />
<br />
<tr><th>CLEAR BOOKMARKS </th><br />
<td>Clear all bookmarks. </td></tr><br />
<br />
<tr><th>XCOMPARE | XC [EXACT | DEBLANK | COMPRESS] </th><br />
<td>XCompares current content against procedure on file; displays in a scrollable form. </td></tr><br />
<br />
<tr><th>XCOMPARE SEQ| XCS [EXACT | DEBLANK | COMPRESS] </th><br />
<td>Do XCompare against SEQ version in same procedure file (only works for SirLib users). </td></tr><br />
<br />
<tr><th>LAYOUT | MAP </th><br />
<td>List all class/subroutines/functions. PF4 focuses entry from listing. </td></tr><br />
<br />
<tr><th>INCLUDES command </th><br />
<td>Show hierarchy of all includes referenced within the current procedure. </td></tr><br />
<br />
<tr><th>PROTECT/UNPROTECT </th><br />
<td>Force the displayed content to be protected/unprotected.</td></tr><br />
<br />
<tr><th>BB | BLOCK WHERE </th><br />
<td>Add BB markers to the current "where" scope. </td></tr><br />
<br />
<tr><th>AUDIT [<i>minutes</i> | <i>timestamp</i> | LAST[RUN]] </th><br />
<td>Shows the journal lines for the user. It defaults to the last minute, unless an optional time is supplied. </td></tr><br />
<br />
<tr><th>SET FILE <i>fileName</i> </th><br />
<td>Sets the file name for saving procedures; also clears the procedure name. </td></tr><br />
<br />
<tr><th>SNAP | SNAPSHOT </th><br />
<td>Takes a copy of the code in the current editing session and saves it as snapshot.</td></tr><br />
<br />
<tr><th>XCB [<i>previous-snapshot-offset</i>] </th><br />
<td>Compare the current code against the last snapshot taken. </td></tr><br />
</table> <br />
<br />
Used in conjunction with the pf12 key on the run output when compilation/runtime errors occur, the following commands can be used to navigate <br />
through the errors in the currently loaded procedure: <br />
<br />
<table class="thJustBold"> <br />
<tr><th>NE | NEXT ERROR </th><br />
<td>Navigate to the next error. </td></tr><br />
<br />
<tr><th>PE | PREVIOUS ERROR </th><br />
<td>Navigate to the previous error. </td></tr><br />
<br />
<tr><th>CE | CURRENT ERROR </th><br />
<td>Navigate to the current error. </td></tr><br />
<br />
<tr><th>CLE | CLEAR ERRORS </th><br />
<td>Clear the error bookmarks. </td></tr><br />
</table> <br />
==Line prefix commands==<br />
<br />
===Block prefixes, with repeating ignored=== <br />
<table class="thJustBold"><br />
<tr><th>CC</th><br />
<td>Block copy (requires targeting prefix). </td></tr><br />
<br />
<tr><th>MM</th><br />
<td>Block move (requires targeting prefix).</td></tr><br />
<br />
<tr><th>DD</th><br />
<td>Block delete.</td></tr><br />
<br />
<tr><th>HH</th><br />
<td>Block hide.</td></tr><br />
<br />
<tr><th>**</th><br />
<td>Block comment (set/clear; first line is used to determine state switch. If first character is <code>*</code>, comments are removed).</td></tr><br />
<br />
<tr><th>BB</th><br />
<td>Block boundaries. Used with editor commands: SORT, ALIGN, FORMAT. Optional for R, REPLACE.</td></tr><br />
<br />
<tr><th>FF</th><br />
<td>Format the specified block. Sets indenting to the number of spaces specified in the user profile.</td></tr><br />
</table><br />
<br />
===Block prefixes, with repeating honored===<br />
For example, <code>""3</code> replicates the block three times.<br />
<br />
<table class="thJustBold"><br />
<tr><th>RR ""</th><br />
<td>Block replicate</td></tr><br />
<br />
<tr><th><< ((</th><br />
<td>Block shift left (with protections to prevent loss of leading text)</td></tr><br />
<br />
<tr><th>>> ))</th><br />
<td>Block shift right (with protections to prevent loss of trailing text)</td></tr><br />
</table><br />
<br />
===Targeting prefixes===<br />
<table class="thJustBold"> <br />
<tr><th>A</th><br />
<td>Target after line</td></tr><br />
<br />
<tr><th>F</th><br />
<td>Target following line </td></tr><br />
<br />
<tr><th>B</th><br />
<td>Target before line</td></tr><br />
<br />
<tr><th> P</th><br />
<td>Target previous line</td></tr><br />
</table><br />
<br />
===Singular prefixes, with repeating ignored===<br />
<table class="thJustBold"> <br />
<tr><th>C</th><br />
<td>Copy (requires targeting prefix).</td></tr><br />
<br />
<tr><th>M</th><br />
<td>Move (requires targeting prefix).</td></tr><br />
<br />
<tr><th>E</th><br />
<td>Expand line to 255 bytes (toggles on/off).</td></tr><br />
<br />
<tr><th>/</th><br />
<td>Center this line.</td></tr><br />
<br />
<tr><th>-</th><br />
<td>Folding of blocks; hide lines from marked line to closing/opening block. <p>Example: <code>if -> end if... </code></p></td></tr><br />
<br />
<tr><th>X</th><br />
<td>Expand/collapse INCLUDE inline. Only usable on <var>INCLUDE</var> lines. The expanded INCLUDE lines are protected.</td></tr><br />
</table><br />
<br />
===Singular prefixes, with repeating honored===<br />
<table class="thJustBold"> <br />
<tr><th>H</th><br />
<td>Hide</td></tr><br />
<br />
<tr><th>S +</th><br />
<td>Show</td></tr><br />
<br />
<tr><th>D</th><br />
<td>Delete</td></tr><br />
<br />
<tr><th>R "</th><br />
<td>Replicate</td></tr><br />
<br />
<tr><th>*</th><br />
<td>Comment (set/clear; if first character is <code>*</code>, comments are removed)</td></tr><br />
<br />
<tr><th>< (</th><br />
<td>Shift line left (with protections to prevent loss of leading text)</td></tr><br />
<br />
<tr><th>> )</th><br />
<td>Shift line right (with protections to prevent loss of trailing text)</td></tr> <br />
</table><br />
<br />
==PF keys==<br />
<table class="thJustBold"><br />
<tr><td>PF1</td><td>Help</td></tr><br />
<br />
<tr><td>PF2</td><td>Split the current line at the cursor, or join the current line with the next line if cursor is at end-of-line.</td></tr><br />
<br />
<tr><td>PF3</td><td>Quit the editor without saving.</td></tr><br />
<br />
<tr><td>PF4</td><td></td></tr> <br />
<br />
<tr><td>PF5</td><td></td></tr><br />
<br />
<tr><td>PF6</td><td>Cycle through the command stack. The command stack size defaults to 10 but can be reset via SET.</td></tr><br />
<br />
<tr><td>PF7</td><td>Scroll up / use with M to scroll to top.</td></tr><br />
<br />
<tr><td>PF8</td><td>Scroll down / use with M to scroll to bottom.</td></tr><br />
<br />
<tr><td>PF9</td><td>Repeat previous command.</td></tr><br />
<br />
<tr><td>PF10</td><td>Shift+PF10 performs an ALL for the text under the cursor.</td></tr><br />
<br />
<tr><td>PF11</td><td>Creates/appends the value under the cursor to a traceText upon the following line.</td></tr><br />
<br />
<tr><td>PF12</td><td>Saves current procedure and opens the INCLUDEd text under the cursor. If the cursor is not on an INCLUDE line, no action is taken.</td></tr><br />
</table><br />
<br />
==User-written extensions (SCMDs)==<br />
<br />
SoulEdit has a facility that lets you add command-line extensions to the editor.<br />
<br />
As an example, INFO is a user-written command-line extension provided by Rocket Software. It provides XML-formatted information about any Model 204 system method (output from a <var>[[LoadSystemMethodInfo (XmlDoc subroutine)|LoadSystemMethodInfo]]</var> method call). If during an ordinary editing session you type <code>info currenttimestring</code> into the command line of SoulEdit:<br />
<br />
<p class="caption" style="margin-right:23em">User-defined command entered on command line</p><br />
<p class="figure">[[File:SOUL_UserCommands1.png|border|500px]]</p><br />
<br />
You see the output of the <var>LoadSystemMethodInfo</var> call displayed in a scrollable screen:<br />
<br />
<p class="figure">[[File:SOUL_UserCommands2.png|border|750px]]</p><br />
<br />
Pressing the PF3 key returns to the in-progress editing session.<br />
<br />
The editor extensions are created via '''SCMD''' procedures stored in a user-designated file. You can see how INFO works by looking at procedure <code>SCMD\INFO</code> in the UL/SPF <code>SIRIUS</code> file.<br />
<br />
To create your own commands, specify the procedure file where they will reside using the <var>PROFILE</var> command and ''Custom Macros File''. SoulEdit scans this file for procedures prefixed with <code>SCMD\</code> and loads them into memory at the beginning of the editing session. Copy <code>SCMD\INFO</code> into your Macros file with a new name, and customize the ''run'' method to your liking.<br />
<br />
==Timed backups==<br />
SoulEdit can take timed backups of the procedures you are editing. This feature can be enabled on a user-by-user basis with the <var>PROFILE</var> command. Backups are taken by default to the same file in which a procedure is being edited. Optionally a separate backup file can be specified, also using <var>PROFILE</var>.<br />
<br />
==Auditing==<br />
SoulEdit has an Auditing feature to list entries from the current journal.<br />
<br />
<var>AUDIT</var> options are:-<br />
<br />
<table><br />
<tr><td>AUDIT</td><td>list the previous 1 minute of the current journal</td></tr><br />
<tr><td>AUDIT <n></td><td>where <n> is a positive number indicating how many minutes of the journal to show.</td></tr><br />
<tr><td style="white-space:nowrap;">AUDIT LAST[ RUN]</td><td>After running a procedure with the <var>GO</var> or <var>RUN</var> command from inside SoulEdit this command will show all the journal entries pertaining to the job run. It excludes anything not associated with the GO/RUN. In addition to the journal entries for the thread RUN it also includes all spawned daemon threads by the thread.</td></tr><br />
</table><br />
<br />
==See also==<br />
<ul><br />
<li>[[SirPro]] </li><br />
<br />
<li>[[SirLib]] </li><br />
</ul><br />
<br />
[[Category:Sirius Software products]]</div>Adrianhttps://m204wiki.rocketsoftware.com/index.php?title=RecordLockingConflict_class&diff=69106RecordLockingConflict class2014-04-25T04:20:19Z<p>Adrian: /* Usage notes */</p>
<hr />
<div><!-- RecordLockingConflict class --><br />
The <var>RecordLockingConflict</var> exception class catches record locking conflict errors thrown by file object operations, that is, from methods in the <var>[[File_classes|file]]</var> classes (<var>[[Record_class|Record]]</var>, <var>[[Recordset_class|Recordset]]</var>, <var>[[SortedRecordset_class|SortedRecordset]]</var>, and <var>[[RecordsetCursor_class|RecordsetCursor]]</var>).<br />
<div class="toclimit-3">__TOC__</div><br />
<br />
=Summary=<br />
A <var>RecordLockingConflict</var> exception is thrown only if there is a Catcher for the exception. This allows <code>On Record Locking Conflict</code> and <code>On Find Conflict</code> units to trap record locking conflicts if there is no <var>[[Exceptions#Try and Catch|Catch]]</var> block for the exception.<br />
<br />
There is no distinction between a <var>Find</var> conflict and a <var>Record Locking</var> conflict. For example, you can use the following:<br />
<br />
<p class="code">[[Exceptions#Try and Catch|try]]<br />
fd to %foo<br />
...<br />
end find<br />
[[Exceptions#Try and Catch|catch]] recordLockingConflict<br />
...<br />
end try<br />
</p><br />
<br />
And you can also use:<br />
<p class="code">try<br />
%rec = [[New_(Record_constructor)|new]](%recnum, exclusive)<br />
for record %rec<br />
...<br />
end for<br />
catch recordLockingConflict<br />
...<br />
end try<br />
</p><br />
<br />
You can even catch record locking conflicts caused by <var>[[LoopLockStrength_(Record_property)|LoopLockStrength]]</var> promotions during a loop:<br />
<p class="code">%rec = new(%recnum, none, loopLockStrength=share)<br />
...<br />
try for record %rec<br />
...<br />
end for<br />
catch recordLockingConflict<br />
...<br />
end try<br />
</p><br />
<br />
Or as in the following:<br />
<p class="code">%curser = new(%recset, loopLockStrength=none)<br />
...<br />
try<br />
for record at cursor %curser<br />
...<br />
end for<br />
catch recordLockingConflict<br />
..<br />
end try<br />
</p><br />
<br />
Or as in this example:<br />
<p class="code">fdwol to %recset = new(loopLockStrength=exclusive)<br />
...<br />
end find<br />
...<br />
try for each record in %recset<br />
...<br />
end for<br />
catch recordLockingConflict<br />
...<br />
end try<br />
</p><br />
<br />
In the latter example, note that any iteration of the <var>For</var> loop can [[Exceptions#Throwing exceptions|throw]] an exception, and there is no way of picking up where you left off (at the next record, say) if you get a <var>RecordLockingConflict</var> exception in such a case. So, unless you always want to lose the whole loop on a record locking conflict, such a case is almost always better structured with a cursor on the recordset and with <var>Try</var> around the <var>For Record At Cursor</var> loop:<br />
<p class="code">fdwol to %recset = new(loopLockStrength=exclusive)<br />
...<br />
end find<br />
...<br />
%curser = new(%recset, loopLockStrength=exclusive)<br />
repeat while %curser:state eq hasRecord<br />
try for record at cursor %curser<br />
...<br />
end for<br />
catch recordLockingConflict<br />
...<br />
end try<br />
%curser:next<br />
end repeat<br />
</p><br />
<br />
<b>Note:</b> The <var>For</var> statement can be on the same line as the <var>Try</var>, or it can be inside the <var>Try</var> block.<br />
<br />
=The RecordLockingConflict methods=<br />
{{Template:List of RecordLockingConflict methods}}<br />
<br />
The methods in the class are described in the subsections that follow. In addition:<br />
<ul><br />
<li>[[Notation conventions for methods|"Notation conventions for methods"]] has information<br />
about the conventions followed. <br />
<li>[[RecordLockingConflict methods syntax|"RecordLockingConflict methods syntax"]] is a single page that contains the syntax diagrams of all the methods in the class.<br />
</ul><br />
<br />
<br />
==ConflictingLockStrength property==<br />
<br />
{{Template:RecordLockingConflict:ConflictingLockStrength subtitle}}<br />
<br />
This <var>[[Classes and Objects#readWrite|ReadOnly]]</var> method returns a <var>[[LockStrength_enumeration|LockStrength]]</var> enumeration value indicating the strength of the lock held by another user that caused the conflict.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:ConflictingLockStrength syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%lockStrength</th><br />
<td>A variable to receive the output value, a <var>LockStrength</var> enumeration value.</td></tr><br />
<br />
<tr><th>recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.<br />
</td></tr></table><br />
<br />
====Usage notes====<br />
<ul><br />
<li>If the <var>[[RECLOCKO_parameter|RECLOCKO]]</var> parameter X'04' bit is not set, this property returns a <var>Null</var> value.<br />
<br />
<li>Since an unlocked record (<var>LockStrength</var> <code>None</code>) cannot cause a record locking conflict, a non-<var>Null</var> return value should always be either <var>Share</var> or <var>Exclusive</var>.<br />
</ul><br />
<br />
<br />
==ConflictingRecordLockType property==<br />
<br />
{{Template:RecordLockingConflict:ConflictingRecordLockType subtitle}}<br />
<br />
This <var>[[Classes and Objects#readWrite|ReadOnly]]</var> method returns a <var>[[RecordLockType_enumeration|RecordLockType]]</var> enumeration value indicating the type of the lock held by another user that caused the conflict.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:ConflictingRecordLockType syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%recordLockType</th><br />
<td>A variable to receive the output value, a <var>RecordLockType</var> enumeration value.</td></tr><br />
<br />
<tr><th>recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.</td></tr><br />
</table><br />
<br />
====Usage notes====<br />
<ul><br />
<li>If the <var>[[RECLOCKO_parameter|RECLOCKO]]</var> parameter X'04' bit isn't set, this property will return a <var>Null</var> value.<br />
</ul><br />
<br />
<br />
==ConflictTimeMilliseconds property==<br />
{{Template:RecordLockingConflict:ConflictTimeMilliseconds subtitle}}<br />
<br />
This <var>ReadOnly</var> property returns a number that is the number of milliseconds since 1900 that the record locking conflict occurred.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:ConflictTimeMilliseconds syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%number</th><br />
<td>A variable to receive the output value.<br />
</td></tr><br />
<tr><th>recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.<br />
</td></tr></table><br />
<br />
====Usage notes====<br />
<ul><br />
<li>If the <var>[[RECLOCKO_parameter|RECLOCKO]]</var> parameter X'04' bit is not set, this property returns a <var>0</var> value.<br />
<li>The <var>[[MillisecondsToString (Float function)|MillisecondsToString]]</var> method can be used to convert this value to a more human-friendly format.<br />
</ul><br />
<br />
==Copy and DeepCopy functions==<br />
{{Template:RecordLockingConflict:Copy subtitle}}<br />
<br />
{{Template:RecordLockingConflict:DeepCopy subtitle}}<br />
<br />
These functions return a copy of the method object, that is the <var>RecordLockingConflict</var> object to which they are applied.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:Copy syntax}}<br />
{{Template:RecordLockingConflict:DeepCopy syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%outRecordLockingConflict</th><br />
<td>A RecordLockingConflict object variable to receive the output value.<br />
</td></tr><br />
<tr><th>recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.<br />
</td></tr></table><br />
<br />
====Usage notes====<br />
<ul><br />
<br />
<li>Since <var>RecordLockingConflict</var> objects contain no references to other objects, there is no difference between a <var>Copy</var> and <var>DeepCopy</var> method for these objects.<br />
<li>The presence of a <var>DeepCopy</var> method for the <var>RecordLockingConflict</var> class means that classes that contain references to <var>RecordLockingConflict</var> objects can also be <var>DeepCopy</var>-able.<br />
</ul><br />
<br />
<br />
==Filename property==<br />
{{Template:RecordLockingConflict:Filename subtitle}}<br />
<br />
This <var>ReadOnly</var> property returns a <var>Longstring</var> that contains the name of the file in which the last record locking conflict occurred.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:Filename syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%string</th><br />
<td>A <var>longstring</var> to receive the file name.<br />
</td></tr><br />
<tr><th>recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.<br />
</td></tr></table><br />
<br />
<br />
==LockTimeMilliseconds property==<br />
{{Template:RecordLockingConflict:LockTimeMilliseconds subtitle}}<br />
<br />
This <var>ReadOnly</var> property returns a number that is the number of milliseconds since 1900 that the record that caused the record locking conflict was locked.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:LockTimeMilliseconds syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%number</th><br />
<td>A variable to receive the output value.</td></tr><br />
<br />
<tr><th>recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.</td></tr><br />
</table><br />
<br />
====Usage notes====<br />
<ul><br />
<li>If the <var>[[RECLOCKO_parameter|RECLOCKO]]</var> parameter X'04' bit is not set, this property returns a <var>0</var> value.<br />
<li>The <var>[[MillisecondsToString (Float function)|MillisecondsToString]]</var> method can be used to convert this value to a more human-friendly format.<br />
<br />
<li>LockingTimeMilliseconds, along with the <var>[[#LockingUserNumber property|LockingUserNumber]]</var> property should make it relatively easy to locate the request that locked the record that caused the record lock in the audit trail.<br />
<br />
<li>Strictly speaking, the returned lock time is the time the finding and locking process began for the locked record, not when it was actually locked. Since the primary purpose this value is to locate audit trail information for the request that locked the conficting record, and since the entire locking process always happens within a single request, this distinction should be relatively unimportant. <br />
</ul><br />
<br />
==LockingUserNumber property==<br />
{{Template:RecordLockingConflict:LockingUserNumber subtitle}}<br />
<br />
This <var>[[Classes and Objects#readWrite|ReadOnly]]</var> property returns the user number of the user that originally locked the conflicting record. This might be different from the value returned by the <var>[[#UserNumber property|UserNumber]]</var> property if a file object is passed between threads as a session object. In fact, a record lock caused by a file object in a closed session would return the session PST's user number for <var>UserNumber</var> but would return the user number that originally locked the record that caused the conflict. <br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:LockingUserNumber syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%number</th><br />
<td>A variable to receive the output value.</td></tr><br />
<br />
<tr><th>recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.</td></tr><br />
</table><br />
<br />
====Usage notes====<br />
<ul><br />
<li>If the <var>[[RECLOCKO_parameter|RECLOCKO]]</var> parameter X'04' bit is not set, this property returns a <var>-1</var> value.<br />
<li><var>LockingUserNumber</var>, along with the <var>LockTimeMilliseconds</var> property should make it relatively easy to locate the request that locked the record that caused the record lock in the audit trail.<br />
</ul><br />
<br />
==New constructor==<br />
{{Template:RecordLockingConflict:New subtitle}}<br />
<br />
This <var>Constructor</var> generates an instance of a <var>RecordLockingConflict</var> exception. As shown in the syntax that follows, the <var>New</var> method arguments set the values of the class properties having the corresponding names. Each argument to <var>New</var> sets the value of the corresponding property of the newly constructed <var>RecordLockingConflict</var> object.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:New syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.</td></tr><br />
<br />
<tr><th><var>[%(RecordLockingConflict):]</var></th><br />
<td>The class name in parentheses denotes a <var>[[Notation conventions for methods#Constructors|Constructor]]</var>.</td></tr><br />
<br />
<tr><th><var>Filename</var></th><br />
<td>This [[Methods#Named parameters|name required]] parameter specifies the <var>[[Longstrings|Longstring]]</var> value (<var class="term">string</var>) to be assigned to the object's <var>[[Filename_(RecordLockingConflict_property)|Filename]]</var> property. Its default value is a null string.</td></tr><br />
<br />
<tr><th><var>RecordNumber</var></th><br />
<td>This name required parameter specifies the numeric value (<var class="term">number</var>) to be assigned to the object's <var>[[RecordNumber_(RecordLockingConflict_property)|RecordNumber]]</var> property. Its default value is 0.</td></tr><br />
<br />
<tr><th><var>UserNumber</var></th><br />
<td>This name required parameter specifies the numeric value (<var class="term">number</var>) to be assigned to the exception object's <var>[[UserID_(RecordLockingConflict_property)|UserNumber]]</var> property. Its default value is 0.</td></tr><br />
<br />
<tr><th><var>UserID</var></th><br />
<td>This name required parameter specifies the longstring value (<var class="term">string</var>) to be assigned to the object's <var>[[UserNumber_(RecordLockingConflict_property)|UserID]]</var> property. Its default value is a null string.</td></tr><br />
<br />
<tr><th><var>LockingUserNumber</var></th><br />
<td>This optional, name required parameter specifies the numeric value (<var class="term">number</var>) to be assigned to the object's <var>[[LockingUserNumber_(RecordLockingConflict_property)|LockingUserNumber]]</var> property. Its default value is <var>-1</var>, which is not a valid user number, and is the value set for the <var>LockingUserNumber</var> property by the system when the <var>[[RECLOCKO parameter|RECLOCKO]]</var> parameter X'04' bit is not set and a <var>RecordLockingConflict</var> exception is thrown. <br />
</td></tr><br />
<br />
<tr><th><var>LockTimeMilliseconds</var></th><br />
<td>This optional, name required parameter specifies the numeric value (<var class="term">number</var>) to be assigned to the object's <var>[[LockTimeMilliseconds_(RecordLockingConflict_property)|LockTimeMilliseconds]]</var> property. Its default value is a <var>0</var>, which is the value set for the LockTimeMilliseconds property by the system when the <var>RECLOCKO</var> parameter X'04' bit is not set and a <var>RecordLockingConflict</var> exception is thrown. </td></tr><br />
<br />
<tr><th><var>ConflictTimeMilliseconds</var></th><br />
<td>This optional, name required parameter specifies the numeric value (<var class="term">number</var>) to be assigned to the object's <var>[[ConflictTimeMilliseconds_(RecordLockingConflict_property)|ConflictTimeMilliseconds]]</var> property. Its default value is a <var>0</var>, which is the value set for the <var>ConflictTimeMilliseconds</var> property by the system when the <var>RECLOCKO</var> parameter X'04' bit is not set and a <var>RecordLockingConflict</var> exception is thrown. </td></tr><br />
<br />
<tr><th><var>ConflictingLockStrength</var></th><br />
<td>This optional, name required parameter specifies the <var>[[LockStrength]]</var> enumeration value to be assigned to the object's <var>[[ConflictingLockStrength_(RecordLockingConflict_property)|ConflictingLockStrength]]</var> property. Its default value is a <var>Null</var>, which is the value set for the <var>ConflictingLockStrength</var> property by the system when the <var>RECLOCKO</var> parameter X'04' bit is not set and a <var>RecordLockingConflict</var> exception is thrown. Since a record locking conflict cannot be caused by an unlocked record, setting this value to <var>None</var> is equivalent to setting it to <var>Null</var>.</td></tr><br />
<br />
<tr><th><var>ConflictingRecordLockType</var></th><br />
<td>This optional, name required parameter specifies the <var>[[RecordLockType]]</var> enumeration value to be assigned to the object's <var>[[ConflictingRecordLockType_(RecordLockingConflict_property)|ConflictingRecordLockType]]</var> property. Its default value is a <var>Null</var>, which is the value set for the <var>ConflictingRecordLockType</var> property by the system when the <var>RECLOCKO parameter</var> X'04' bit is not set and a <var>RecordLockingConflict</var> exception is thrown.</td></tr><br />
</table><br />
<br />
<br />
==NewFromLastConflict constructor==<br />
{{Template:RecordLockingConflict:NewFromLastConflict subtitle}}<br />
<br />
This <var>Constructor</var> generates an instance of an <var>[[RecordLockingConflict_class|RecordLockingConflict]]</var> exception. Unlike the New method, this method obtains the values of the object properties from the last record locking conflict that occurred, whether or not it was trapped (caught or handled by an On unit). In fact, the greatest utility of this method would be to create a <var>RecordLockingConflict</var> instance that contains all record locking information in an <var>On Record Locking Conflict</var> or <var>On Find Conflict</var> unit. This is especially useful for accessing the properties set by the <var>[[RECLOCKO]]</var> parameter X'04' bit in an <var>On</var> unit. These properties are <var>LockingUserNumber</var>, <var>LockTimeMilliseconds</var>, <var>ConflictTimeMilliseconds</var>, <var>ConflictingLockStrength</var>, and <var>ConflictingRecordLockType</var>.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:NewFromLastConflict syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%reclockInfo</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.</td></tr><br />
<br />
<tr><th><var>[%(RecordLockingConflict):]</var></th><br />
<td>The class name in parentheses denotes a <var>[[Notation conventions for methods#Constructors|Constructor]]</var>.</td></tr><br />
</table><br />
<br />
====Usage notes====<br />
<ul><br />
<li>If there have been no record locking conflicts in the current request, this method returns a <var>Null</var>.<br />
<li>Since <var class="product">Model 204</var> clears the record locking conflict information at the start of each request, this method cannot be used to retrieve information from a previous request.<br />
</ul><br />
<br />
<br />
==RecordNumber property==<br />
{{Template:RecordLockingConflict:RecordNumber subtitle}}<br />
<br />
This <var>[[Classes and Objects#readWrite|ReadOnly]]</var> property returns the numeric value of the <var class="product">Model 204</var> internal record number of the record that has the conflict.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:RecordNumber syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%number</th><br />
<td>A numeric variable to receive the record number.<br />
</td></tr><br />
<br />
<tr><th>recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.<br />
</td></tr></table><br />
<br />
====Example====<br />
The following example shows all the properties of the <var>RecordLockingConflict</var> class. While the standard record locking conflict information is available for retrieval via the <var class="product">User Language</var> functions $rlcfile, $rlcrec, $rlcuid, and $rlcusr, that information is also set in the exception object and retrievable via that object:<br />
<p class="code">%rlc is object RecordLockingConflict<br />
...<br />
%rec = new(%recnum, none, loopLockStrength=share)<br />
...<br />
try for record %rec<br />
...<br />
end for<br />
catch recordLockingConflict to %rlc<br />
[[Audittext|auditText]] Conflict on record {%rlc:recordNumber} -<br />
in file {%rlc:filename}<br />
auditText Conflicting user was userid {%rlc:userid}, -<br />
with user number:{%rlc:userNumber}<br />
end try<br />
</p><br />
<br />
<br />
==UserID property==<br />
{{Template:RecordLockingConflict:UserID subtitle}}<br />
<br />
This <var>ReadOnly</var> property returns the <var class="product">Model 204</var> userid (login name) of the user that has the conflict.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:UserID syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%string</th><br />
<td>A <var>[[Longstrings|longstring]]</var> to receive the userid value.</td></tr><br />
<br />
<tr><th>recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.</td></tr><br />
</table><br />
<br />
<br />
==UserNumber property==<br />
{{Template:RecordLockingConflict:UserNumber subtitle}}<br />
<br />
This <var>ReadOnly</var> property returns the user number (unique per session) of the user that has the conflict.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:UserNumber syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%number</th><br />
<td>A numeric variable to receive the user number.</td></tr><br />
<br />
<tr><th>recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.</td></tr><br />
</table><br />
<br />
<br />
[[Category:System exception classes]]</div>Adrianhttps://m204wiki.rocketsoftware.com/index.php?title=RecordLockingConflict_class&diff=69105RecordLockingConflict class2014-04-25T04:19:25Z<p>Adrian: /* Usage notes */</p>
<hr />
<div><!-- RecordLockingConflict class --><br />
The <var>RecordLockingConflict</var> exception class catches record locking conflict errors thrown by file object operations, that is, from methods in the <var>[[File_classes|file]]</var> classes (<var>[[Record_class|Record]]</var>, <var>[[Recordset_class|Recordset]]</var>, <var>[[SortedRecordset_class|SortedRecordset]]</var>, and <var>[[RecordsetCursor_class|RecordsetCursor]]</var>).<br />
<div class="toclimit-3">__TOC__</div><br />
<br />
=Summary=<br />
A <var>RecordLockingConflict</var> exception is thrown only if there is a Catcher for the exception. This allows <code>On Record Locking Conflict</code> and <code>On Find Conflict</code> units to trap record locking conflicts if there is no <var>[[Exceptions#Try and Catch|Catch]]</var> block for the exception.<br />
<br />
There is no distinction between a <var>Find</var> conflict and a <var>Record Locking</var> conflict. For example, you can use the following:<br />
<br />
<p class="code">[[Exceptions#Try and Catch|try]]<br />
fd to %foo<br />
...<br />
end find<br />
[[Exceptions#Try and Catch|catch]] recordLockingConflict<br />
...<br />
end try<br />
</p><br />
<br />
And you can also use:<br />
<p class="code">try<br />
%rec = [[New_(Record_constructor)|new]](%recnum, exclusive)<br />
for record %rec<br />
...<br />
end for<br />
catch recordLockingConflict<br />
...<br />
end try<br />
</p><br />
<br />
You can even catch record locking conflicts caused by <var>[[LoopLockStrength_(Record_property)|LoopLockStrength]]</var> promotions during a loop:<br />
<p class="code">%rec = new(%recnum, none, loopLockStrength=share)<br />
...<br />
try for record %rec<br />
...<br />
end for<br />
catch recordLockingConflict<br />
...<br />
end try<br />
</p><br />
<br />
Or as in the following:<br />
<p class="code">%curser = new(%recset, loopLockStrength=none)<br />
...<br />
try<br />
for record at cursor %curser<br />
...<br />
end for<br />
catch recordLockingConflict<br />
..<br />
end try<br />
</p><br />
<br />
Or as in this example:<br />
<p class="code">fdwol to %recset = new(loopLockStrength=exclusive)<br />
...<br />
end find<br />
...<br />
try for each record in %recset<br />
...<br />
end for<br />
catch recordLockingConflict<br />
...<br />
end try<br />
</p><br />
<br />
In the latter example, note that any iteration of the <var>For</var> loop can [[Exceptions#Throwing exceptions|throw]] an exception, and there is no way of picking up where you left off (at the next record, say) if you get a <var>RecordLockingConflict</var> exception in such a case. So, unless you always want to lose the whole loop on a record locking conflict, such a case is almost always better structured with a cursor on the recordset and with <var>Try</var> around the <var>For Record At Cursor</var> loop:<br />
<p class="code">fdwol to %recset = new(loopLockStrength=exclusive)<br />
...<br />
end find<br />
...<br />
%curser = new(%recset, loopLockStrength=exclusive)<br />
repeat while %curser:state eq hasRecord<br />
try for record at cursor %curser<br />
...<br />
end for<br />
catch recordLockingConflict<br />
...<br />
end try<br />
%curser:next<br />
end repeat<br />
</p><br />
<br />
<b>Note:</b> The <var>For</var> statement can be on the same line as the <var>Try</var>, or it can be inside the <var>Try</var> block.<br />
<br />
=The RecordLockingConflict methods=<br />
{{Template:List of RecordLockingConflict methods}}<br />
<br />
The methods in the class are described in the subsections that follow. In addition:<br />
<ul><br />
<li>[[Notation conventions for methods|"Notation conventions for methods"]] has information<br />
about the conventions followed. <br />
<li>[[RecordLockingConflict methods syntax|"RecordLockingConflict methods syntax"]] is a single page that contains the syntax diagrams of all the methods in the class.<br />
</ul><br />
<br />
<br />
==ConflictingLockStrength property==<br />
<br />
{{Template:RecordLockingConflict:ConflictingLockStrength subtitle}}<br />
<br />
This <var>[[Classes and Objects#readWrite|ReadOnly]]</var> method returns a <var>[[LockStrength_enumeration|LockStrength]]</var> enumeration value indicating the strength of the lock held by another user that caused the conflict.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:ConflictingLockStrength syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%lockStrength</th><br />
<td>A variable to receive the output value, a <var>LockStrength</var> enumeration value.</td></tr><br />
<br />
<tr><th>recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.<br />
</td></tr></table><br />
<br />
====Usage notes====<br />
<ul><br />
<li>If the <var>[[RECLOCKO_parameter|RECLOCKO]]</var> parameter X'04' bit is not set, this property returns a <var>Null</var> value.<br />
<br />
<li>Since an unlocked record (<var>LockStrength</var> <code>None</code>) cannot cause a record locking conflict, a non-<var>Null</var> return value should always be either <var>Share</var> or <var>Exclusive</var>.<br />
</ul><br />
<br />
<br />
==ConflictingRecordLockType property==<br />
<br />
{{Template:RecordLockingConflict:ConflictingRecordLockType subtitle}}<br />
<br />
This <var>[[Classes and Objects#readWrite|ReadOnly]]</var> method returns a <var>[[RecordLockType_enumeration|RecordLockType]]</var> enumeration value indicating the type of the lock held by another user that caused the conflict.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:ConflictingRecordLockType syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%recordLockType</th><br />
<td>A variable to receive the output value, a <var>RecordLockType</var> enumeration value.</td></tr><br />
<br />
<tr><th>recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.</td></tr><br />
</table><br />
<br />
====Usage notes====<br />
<ul><br />
<li>If the <var>[[RECLOCKO_parameter|RECLOCKO]]</var> parameter X'04' bit isn't set, this property will return a <var>Null</var> value.<br />
</ul><br />
<br />
<br />
==ConflictTimeMilliseconds property==<br />
{{Template:RecordLockingConflict:ConflictTimeMilliseconds subtitle}}<br />
<br />
This <var>ReadOnly</var> property returns a number that is the number of milliseconds since 1900 that the record locking conflict occurred.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:ConflictTimeMilliseconds syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%number</th><br />
<td>A variable to receive the output value.<br />
</td></tr><br />
<tr><th>recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.<br />
</td></tr></table><br />
<br />
====Usage notes====<br />
<ul><br />
<li>If the <var>[[RECLOCKO_parameter|RECLOCKO]]</var> parameter X'04' bit is not set, this property returns a <var>0</var> value.<br />
<li>The <var>[[MillisecondsToString (Float function)|MillisecondsToString]]</var> method can be used to convert this value to a more human-friendly format.<br />
</ul><br />
<br />
==Copy and DeepCopy functions==<br />
{{Template:RecordLockingConflict:Copy subtitle}}<br />
<br />
{{Template:RecordLockingConflict:DeepCopy subtitle}}<br />
<br />
These functions return a copy of the method object, that is the <var>RecordLockingConflict</var> object to which they are applied.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:Copy syntax}}<br />
{{Template:RecordLockingConflict:DeepCopy syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%outRecordLockingConflict</th><br />
<td>A RecordLockingConflict object variable to receive the output value.<br />
</td></tr><br />
<tr><th>recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.<br />
</td></tr></table><br />
<br />
====Usage notes====<br />
<ul><br />
<br />
<li>Since <var>RecordLockingConflict</var> objects contain no references to other objects, there is no difference between a <var>Copy</var> and <var>DeepCopy</var> method for these objects.<br />
<li>The presence of a <var>DeepCopy</var> method for the <var>RecordLockingConflict</var> class means that classes that contain references to <var>RecordLockingConflict</var> objects can also be <var>DeepCopy</var>-able.<br />
</ul><br />
<br />
<br />
==Filename property==<br />
{{Template:RecordLockingConflict:Filename subtitle}}<br />
<br />
This <var>ReadOnly</var> property returns a <var>Longstring</var> that contains the name of the file in which the last record locking conflict occurred.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:Filename syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%string</th><br />
<td>A <var>longstring</var> to receive the file name.<br />
</td></tr><br />
<tr><th>recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.<br />
</td></tr></table><br />
<br />
<br />
==LockTimeMilliseconds property==<br />
{{Template:RecordLockingConflict:LockTimeMilliseconds subtitle}}<br />
<br />
This <var>ReadOnly</var> property returns a number that is the number of milliseconds since 1900 that the record that caused the record locking conflict was locked.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:LockTimeMilliseconds syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%number</th><br />
<td>A variable to receive the output value.</td></tr><br />
<br />
<tr><th>recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.</td></tr><br />
</table><br />
<br />
====Usage notes====<br />
<ul><br />
<li>If the <var>[[RECLOCKO_parameter|RECLOCKO]]</var> parameter X'04' bit is not set, this property returns a <var>0</var> value.<br />
<li>The <var>[[MillisecondsToString (Float function)|MillisecondsToString]]</var> method can be used to convert this value to a more human-friendly format.<br />
<br />
<li>LockingTimeMilliseconds, along with the <var>[[#LockingUserNumber property|LockingUserNumber]]</var> property should make it relatively easy to locate the request that locked the record that caused the record lock in the audit trail.<br />
<br />
<li>Strictly speaking, the returned lock time is the time the finding and locking process began for the locked record, not when it was actually locked. Since the primary purpose this value is to locate audit trail information for the request that locked the conficting record, and since the entire locking process always happens within a single request, this distinction should be relatively unimportant. <br />
</ul><br />
<br />
==LockingUserNumber property==<br />
{{Template:RecordLockingConflict:LockingUserNumber subtitle}}<br />
<br />
This <var>[[Classes and Objects#readWrite|ReadOnly]]</var> property returns the user number of the user that originally locked the conflicting record. This might be different from the value returned by the <var>[[#UserNumber property|UserNumber]]</var> property if a file object is passed between threads as a session object. In fact, a record lock caused by a file object in a closed session would return the session PST's user number for <var>UserNumber</var> but would return the user number that originally locked the record that caused the conflict. <br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:LockingUserNumber syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%number</th><br />
<td>A variable to receive the output value.</td></tr><br />
<br />
<tr><th>recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.</td></tr><br />
</table><br />
<br />
====Usage notes====<br />
<ul><br />
<li><var>LockingUserNumber</var>, along with the <var>LockTimeMilliseconds</var> property should make it relatively easy to locate the request that locked the record that caused the record lock in the audit trail.<br />
</ul><br />
<br />
<br />
==New constructor==<br />
{{Template:RecordLockingConflict:New subtitle}}<br />
<br />
This <var>Constructor</var> generates an instance of a <var>RecordLockingConflict</var> exception. As shown in the syntax that follows, the <var>New</var> method arguments set the values of the class properties having the corresponding names. Each argument to <var>New</var> sets the value of the corresponding property of the newly constructed <var>RecordLockingConflict</var> object.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:New syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.</td></tr><br />
<br />
<tr><th><var>[%(RecordLockingConflict):]</var></th><br />
<td>The class name in parentheses denotes a <var>[[Notation conventions for methods#Constructors|Constructor]]</var>.</td></tr><br />
<br />
<tr><th><var>Filename</var></th><br />
<td>This [[Methods#Named parameters|name required]] parameter specifies the <var>[[Longstrings|Longstring]]</var> value (<var class="term">string</var>) to be assigned to the object's <var>[[Filename_(RecordLockingConflict_property)|Filename]]</var> property. Its default value is a null string.</td></tr><br />
<br />
<tr><th><var>RecordNumber</var></th><br />
<td>This name required parameter specifies the numeric value (<var class="term">number</var>) to be assigned to the object's <var>[[RecordNumber_(RecordLockingConflict_property)|RecordNumber]]</var> property. Its default value is 0.</td></tr><br />
<br />
<tr><th><var>UserNumber</var></th><br />
<td>This name required parameter specifies the numeric value (<var class="term">number</var>) to be assigned to the exception object's <var>[[UserID_(RecordLockingConflict_property)|UserNumber]]</var> property. Its default value is 0.</td></tr><br />
<br />
<tr><th><var>UserID</var></th><br />
<td>This name required parameter specifies the longstring value (<var class="term">string</var>) to be assigned to the object's <var>[[UserNumber_(RecordLockingConflict_property)|UserID]]</var> property. Its default value is a null string.</td></tr><br />
<br />
<tr><th><var>LockingUserNumber</var></th><br />
<td>This optional, name required parameter specifies the numeric value (<var class="term">number</var>) to be assigned to the object's <var>[[LockingUserNumber_(RecordLockingConflict_property)|LockingUserNumber]]</var> property. Its default value is <var>-1</var>, which is not a valid user number, and is the value set for the <var>LockingUserNumber</var> property by the system when the <var>[[RECLOCKO parameter|RECLOCKO]]</var> parameter X'04' bit is not set and a <var>RecordLockingConflict</var> exception is thrown. <br />
</td></tr><br />
<br />
<tr><th><var>LockTimeMilliseconds</var></th><br />
<td>This optional, name required parameter specifies the numeric value (<var class="term">number</var>) to be assigned to the object's <var>[[LockTimeMilliseconds_(RecordLockingConflict_property)|LockTimeMilliseconds]]</var> property. Its default value is a <var>0</var>, which is the value set for the LockTimeMilliseconds property by the system when the <var>RECLOCKO</var> parameter X'04' bit is not set and a <var>RecordLockingConflict</var> exception is thrown. </td></tr><br />
<br />
<tr><th><var>ConflictTimeMilliseconds</var></th><br />
<td>This optional, name required parameter specifies the numeric value (<var class="term">number</var>) to be assigned to the object's <var>[[ConflictTimeMilliseconds_(RecordLockingConflict_property)|ConflictTimeMilliseconds]]</var> property. Its default value is a <var>0</var>, which is the value set for the <var>ConflictTimeMilliseconds</var> property by the system when the <var>RECLOCKO</var> parameter X'04' bit is not set and a <var>RecordLockingConflict</var> exception is thrown. </td></tr><br />
<br />
<tr><th><var>ConflictingLockStrength</var></th><br />
<td>This optional, name required parameter specifies the <var>[[LockStrength]]</var> enumeration value to be assigned to the object's <var>[[ConflictingLockStrength_(RecordLockingConflict_property)|ConflictingLockStrength]]</var> property. Its default value is a <var>Null</var>, which is the value set for the <var>ConflictingLockStrength</var> property by the system when the <var>RECLOCKO</var> parameter X'04' bit is not set and a <var>RecordLockingConflict</var> exception is thrown. Since a record locking conflict cannot be caused by an unlocked record, setting this value to <var>None</var> is equivalent to setting it to <var>Null</var>.</td></tr><br />
<br />
<tr><th><var>ConflictingRecordLockType</var></th><br />
<td>This optional, name required parameter specifies the <var>[[RecordLockType]]</var> enumeration value to be assigned to the object's <var>[[ConflictingRecordLockType_(RecordLockingConflict_property)|ConflictingRecordLockType]]</var> property. Its default value is a <var>Null</var>, which is the value set for the <var>ConflictingRecordLockType</var> property by the system when the <var>RECLOCKO parameter</var> X'04' bit is not set and a <var>RecordLockingConflict</var> exception is thrown.</td></tr><br />
</table><br />
<br />
<br />
==NewFromLastConflict constructor==<br />
{{Template:RecordLockingConflict:NewFromLastConflict subtitle}}<br />
<br />
This <var>Constructor</var> generates an instance of an <var>[[RecordLockingConflict_class|RecordLockingConflict]]</var> exception. Unlike the New method, this method obtains the values of the object properties from the last record locking conflict that occurred, whether or not it was trapped (caught or handled by an On unit). In fact, the greatest utility of this method would be to create a <var>RecordLockingConflict</var> instance that contains all record locking information in an <var>On Record Locking Conflict</var> or <var>On Find Conflict</var> unit. This is especially useful for accessing the properties set by the <var>[[RECLOCKO]]</var> parameter X'04' bit in an <var>On</var> unit. These properties are <var>LockingUserNumber</var>, <var>LockTimeMilliseconds</var>, <var>ConflictTimeMilliseconds</var>, <var>ConflictingLockStrength</var>, and <var>ConflictingRecordLockType</var>.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:NewFromLastConflict syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%reclockInfo</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.</td></tr><br />
<br />
<tr><th><var>[%(RecordLockingConflict):]</var></th><br />
<td>The class name in parentheses denotes a <var>[[Notation conventions for methods#Constructors|Constructor]]</var>.</td></tr><br />
</table><br />
<br />
====Usage notes====<br />
<ul><br />
<li>If there have been no record locking conflicts in the current request, this method returns a <var>Null</var>.<br />
<li>Since <var class="product">Model 204</var> clears the record locking conflict information at the start of each request, this method cannot be used to retrieve information from a previous request.<br />
</ul><br />
<br />
<br />
==RecordNumber property==<br />
{{Template:RecordLockingConflict:RecordNumber subtitle}}<br />
<br />
This <var>[[Classes and Objects#readWrite|ReadOnly]]</var> property returns the numeric value of the <var class="product">Model 204</var> internal record number of the record that has the conflict.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:RecordNumber syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%number</th><br />
<td>A numeric variable to receive the record number.<br />
</td></tr><br />
<br />
<tr><th>recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.<br />
</td></tr></table><br />
<br />
====Example====<br />
The following example shows all the properties of the <var>RecordLockingConflict</var> class. While the standard record locking conflict information is available for retrieval via the <var class="product">User Language</var> functions $rlcfile, $rlcrec, $rlcuid, and $rlcusr, that information is also set in the exception object and retrievable via that object:<br />
<p class="code">%rlc is object RecordLockingConflict<br />
...<br />
%rec = new(%recnum, none, loopLockStrength=share)<br />
...<br />
try for record %rec<br />
...<br />
end for<br />
catch recordLockingConflict to %rlc<br />
[[Audittext|auditText]] Conflict on record {%rlc:recordNumber} -<br />
in file {%rlc:filename}<br />
auditText Conflicting user was userid {%rlc:userid}, -<br />
with user number:{%rlc:userNumber}<br />
end try<br />
</p><br />
<br />
<br />
==UserID property==<br />
{{Template:RecordLockingConflict:UserID subtitle}}<br />
<br />
This <var>ReadOnly</var> property returns the <var class="product">Model 204</var> userid (login name) of the user that has the conflict.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:UserID syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%string</th><br />
<td>A <var>[[Longstrings|longstring]]</var> to receive the userid value.</td></tr><br />
<br />
<tr><th>recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.</td></tr><br />
</table><br />
<br />
<br />
==UserNumber property==<br />
{{Template:RecordLockingConflict:UserNumber subtitle}}<br />
<br />
This <var>ReadOnly</var> property returns the user number (unique per session) of the user that has the conflict.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:UserNumber syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%number</th><br />
<td>A numeric variable to receive the user number.</td></tr><br />
<br />
<tr><th>recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.</td></tr><br />
</table><br />
<br />
<br />
[[Category:System exception classes]]</div>Adrianhttps://m204wiki.rocketsoftware.com/index.php?title=RecordLockingConflict_class&diff=69104RecordLockingConflict class2014-04-25T04:17:42Z<p>Adrian: /* Usage notes */</p>
<hr />
<div><!-- RecordLockingConflict class --><br />
The <var>RecordLockingConflict</var> exception class catches record locking conflict errors thrown by file object operations, that is, from methods in the <var>[[File_classes|file]]</var> classes (<var>[[Record_class|Record]]</var>, <var>[[Recordset_class|Recordset]]</var>, <var>[[SortedRecordset_class|SortedRecordset]]</var>, and <var>[[RecordsetCursor_class|RecordsetCursor]]</var>).<br />
<div class="toclimit-3">__TOC__</div><br />
<br />
=Summary=<br />
A <var>RecordLockingConflict</var> exception is thrown only if there is a Catcher for the exception. This allows <code>On Record Locking Conflict</code> and <code>On Find Conflict</code> units to trap record locking conflicts if there is no <var>[[Exceptions#Try and Catch|Catch]]</var> block for the exception.<br />
<br />
There is no distinction between a <var>Find</var> conflict and a <var>Record Locking</var> conflict. For example, you can use the following:<br />
<br />
<p class="code">[[Exceptions#Try and Catch|try]]<br />
fd to %foo<br />
...<br />
end find<br />
[[Exceptions#Try and Catch|catch]] recordLockingConflict<br />
...<br />
end try<br />
</p><br />
<br />
And you can also use:<br />
<p class="code">try<br />
%rec = [[New_(Record_constructor)|new]](%recnum, exclusive)<br />
for record %rec<br />
...<br />
end for<br />
catch recordLockingConflict<br />
...<br />
end try<br />
</p><br />
<br />
You can even catch record locking conflicts caused by <var>[[LoopLockStrength_(Record_property)|LoopLockStrength]]</var> promotions during a loop:<br />
<p class="code">%rec = new(%recnum, none, loopLockStrength=share)<br />
...<br />
try for record %rec<br />
...<br />
end for<br />
catch recordLockingConflict<br />
...<br />
end try<br />
</p><br />
<br />
Or as in the following:<br />
<p class="code">%curser = new(%recset, loopLockStrength=none)<br />
...<br />
try<br />
for record at cursor %curser<br />
...<br />
end for<br />
catch recordLockingConflict<br />
..<br />
end try<br />
</p><br />
<br />
Or as in this example:<br />
<p class="code">fdwol to %recset = new(loopLockStrength=exclusive)<br />
...<br />
end find<br />
...<br />
try for each record in %recset<br />
...<br />
end for<br />
catch recordLockingConflict<br />
...<br />
end try<br />
</p><br />
<br />
In the latter example, note that any iteration of the <var>For</var> loop can [[Exceptions#Throwing exceptions|throw]] an exception, and there is no way of picking up where you left off (at the next record, say) if you get a <var>RecordLockingConflict</var> exception in such a case. So, unless you always want to lose the whole loop on a record locking conflict, such a case is almost always better structured with a cursor on the recordset and with <var>Try</var> around the <var>For Record At Cursor</var> loop:<br />
<p class="code">fdwol to %recset = new(loopLockStrength=exclusive)<br />
...<br />
end find<br />
...<br />
%curser = new(%recset, loopLockStrength=exclusive)<br />
repeat while %curser:state eq hasRecord<br />
try for record at cursor %curser<br />
...<br />
end for<br />
catch recordLockingConflict<br />
...<br />
end try<br />
%curser:next<br />
end repeat<br />
</p><br />
<br />
<b>Note:</b> The <var>For</var> statement can be on the same line as the <var>Try</var>, or it can be inside the <var>Try</var> block.<br />
<br />
=The RecordLockingConflict methods=<br />
{{Template:List of RecordLockingConflict methods}}<br />
<br />
The methods in the class are described in the subsections that follow. In addition:<br />
<ul><br />
<li>[[Notation conventions for methods|"Notation conventions for methods"]] has information<br />
about the conventions followed. <br />
<li>[[RecordLockingConflict methods syntax|"RecordLockingConflict methods syntax"]] is a single page that contains the syntax diagrams of all the methods in the class.<br />
</ul><br />
<br />
<br />
==ConflictingLockStrength property==<br />
<br />
{{Template:RecordLockingConflict:ConflictingLockStrength subtitle}}<br />
<br />
This <var>[[Classes and Objects#readWrite|ReadOnly]]</var> method returns a <var>[[LockStrength_enumeration|LockStrength]]</var> enumeration value indicating the strength of the lock held by another user that caused the conflict.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:ConflictingLockStrength syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%lockStrength</th><br />
<td>A variable to receive the output value, a <var>LockStrength</var> enumeration value.</td></tr><br />
<br />
<tr><th>recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.<br />
</td></tr></table><br />
<br />
====Usage notes====<br />
<ul><br />
<li>If the <var>[[RECLOCKO_parameter|RECLOCKO]]</var> parameter X'04' bit is not set, this property returns a <var>Null</var> value.<br />
<br />
<li>Since an unlocked record (<var>LockStrength</var> <code>None</code>) cannot cause a record locking conflict, a non-<var>Null</var> return value should always be either <var>Share</var> or <var>Exclusive</var>.<br />
</ul><br />
<br />
<br />
==ConflictingRecordLockType property==<br />
<br />
{{Template:RecordLockingConflict:ConflictingRecordLockType subtitle}}<br />
<br />
This <var>[[Classes and Objects#readWrite|ReadOnly]]</var> method returns a <var>[[RecordLockType_enumeration|RecordLockType]]</var> enumeration value indicating the type of the lock held by another user that caused the conflict.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:ConflictingRecordLockType syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%recordLockType</th><br />
<td>A variable to receive the output value, a <var>RecordLockType</var> enumeration value.</td></tr><br />
<br />
<tr><th>recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.</td></tr><br />
</table><br />
<br />
====Usage notes====<br />
<ul><br />
<li>If the <var>[[RECLOCKO_parameter|RECLOCKO]]</var> parameter X'04' bit isn't set, this property will return a <var>Null</var> value.<br />
</ul><br />
<br />
<br />
==ConflictTimeMilliseconds property==<br />
{{Template:RecordLockingConflict:ConflictTimeMilliseconds subtitle}}<br />
<br />
This <var>ReadOnly</var> property returns a number that is the number of milliseconds since 1900 that the record locking conflict occurred.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:ConflictTimeMilliseconds syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%number</th><br />
<td>A variable to receive the output value.<br />
</td></tr><br />
<tr><th>recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.<br />
</td></tr></table><br />
<br />
====Usage notes====<br />
<ul><br />
<li>If the <var>[[RECLOCKO_parameter|RECLOCKO]]</var> parameter X'04' bit is not set, this property returns a <var>0</var> value.<br />
<li>The <var>[[MillisecondsToString (Float function)|MillisecondsToString]]</var> method can be used to convert this value to a more human-friendly format.<br />
</ul><br />
<br />
==Copy and DeepCopy functions==<br />
{{Template:RecordLockingConflict:Copy subtitle}}<br />
<br />
{{Template:RecordLockingConflict:DeepCopy subtitle}}<br />
<br />
These functions return a copy of the method object, that is the <var>RecordLockingConflict</var> object to which they are applied.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:Copy syntax}}<br />
{{Template:RecordLockingConflict:DeepCopy syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%outRecordLockingConflict</th><br />
<td>A RecordLockingConflict object variable to receive the output value.<br />
</td></tr><br />
<tr><th>recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.<br />
</td></tr></table><br />
<br />
====Usage notes====<br />
<ul><br />
<br />
<li>Since <var>RecordLockingConflict</var> objects contain no references to other objects, there is no difference between a <var>Copy</var> and <var>DeepCopy</var> method for these objects.<br />
<li>The presence of a <var>DeepCopy</var> method for the <var>RecordLockingConflict</var> class means that classes that contain references to <var>RecordLockingConflict</var> objects can also be <var>DeepCopy</var>-able.<br />
</ul><br />
<br />
<br />
==Filename property==<br />
{{Template:RecordLockingConflict:Filename subtitle}}<br />
<br />
This <var>ReadOnly</var> property returns a <var>Longstring</var> that contains the name of the file in which the last record locking conflict occurred.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:Filename syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%string</th><br />
<td>A <var>longstring</var> to receive the file name.<br />
</td></tr><br />
<tr><th>recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.<br />
</td></tr></table><br />
<br />
<br />
==LockTimeMilliseconds property==<br />
{{Template:RecordLockingConflict:LockTimeMilliseconds subtitle}}<br />
<br />
This <var>ReadOnly</var> property returns a number that is the number of milliseconds since 1900 that the record that caused the record locking conflict was locked.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:LockTimeMilliseconds syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%number</th><br />
<td>A variable to receive the output value.</td></tr><br />
<br />
<tr><th>recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.</td></tr><br />
</table><br />
<br />
====Usage notes====<br />
<ul><br />
<li>The <var>[[MillisecondsToString (Float function)|MillisecondsToString]]</var> method can be used to convert this value to a more human-friendly format.<br />
<br />
<li>LockingTimeMilliseconds, along with the <var>[[#LockingUserNumber property|LockingUserNumber]]</var> property should make it relatively easy to locate the request that locked the record that caused the record lock in the audit trail.<br />
<br />
<li>Strictly speaking, the returned lock time is the time the finding and locking process began for the locked record, not when it was actually locked. Since the primary purpose this value is to locate audit trail information for the request that locked the conficting record, and since the entire locking process always happens within a single request, this distinction should be relatively unimportant. <br />
</ul><br />
<br />
<br />
==LockingUserNumber property==<br />
{{Template:RecordLockingConflict:LockingUserNumber subtitle}}<br />
<br />
This <var>[[Classes and Objects#readWrite|ReadOnly]]</var> property returns the user number of the user that originally locked the conflicting record. This might be different from the value returned by the <var>[[#UserNumber property|UserNumber]]</var> property if a file object is passed between threads as a session object. In fact, a record lock caused by a file object in a closed session would return the session PST's user number for <var>UserNumber</var> but would return the user number that originally locked the record that caused the conflict. <br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:LockingUserNumber syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%number</th><br />
<td>A variable to receive the output value.</td></tr><br />
<br />
<tr><th>recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.</td></tr><br />
</table><br />
<br />
====Usage notes====<br />
<ul><br />
<li><var>LockingUserNumber</var>, along with the <var>LockTimeMilliseconds</var> property should make it relatively easy to locate the request that locked the record that caused the record lock in the audit trail.<br />
</ul><br />
<br />
<br />
==New constructor==<br />
{{Template:RecordLockingConflict:New subtitle}}<br />
<br />
This <var>Constructor</var> generates an instance of a <var>RecordLockingConflict</var> exception. As shown in the syntax that follows, the <var>New</var> method arguments set the values of the class properties having the corresponding names. Each argument to <var>New</var> sets the value of the corresponding property of the newly constructed <var>RecordLockingConflict</var> object.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:New syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.</td></tr><br />
<br />
<tr><th><var>[%(RecordLockingConflict):]</var></th><br />
<td>The class name in parentheses denotes a <var>[[Notation conventions for methods#Constructors|Constructor]]</var>.</td></tr><br />
<br />
<tr><th><var>Filename</var></th><br />
<td>This [[Methods#Named parameters|name required]] parameter specifies the <var>[[Longstrings|Longstring]]</var> value (<var class="term">string</var>) to be assigned to the object's <var>[[Filename_(RecordLockingConflict_property)|Filename]]</var> property. Its default value is a null string.</td></tr><br />
<br />
<tr><th><var>RecordNumber</var></th><br />
<td>This name required parameter specifies the numeric value (<var class="term">number</var>) to be assigned to the object's <var>[[RecordNumber_(RecordLockingConflict_property)|RecordNumber]]</var> property. Its default value is 0.</td></tr><br />
<br />
<tr><th><var>UserNumber</var></th><br />
<td>This name required parameter specifies the numeric value (<var class="term">number</var>) to be assigned to the exception object's <var>[[UserID_(RecordLockingConflict_property)|UserNumber]]</var> property. Its default value is 0.</td></tr><br />
<br />
<tr><th><var>UserID</var></th><br />
<td>This name required parameter specifies the longstring value (<var class="term">string</var>) to be assigned to the object's <var>[[UserNumber_(RecordLockingConflict_property)|UserID]]</var> property. Its default value is a null string.</td></tr><br />
<br />
<tr><th><var>LockingUserNumber</var></th><br />
<td>This optional, name required parameter specifies the numeric value (<var class="term">number</var>) to be assigned to the object's <var>[[LockingUserNumber_(RecordLockingConflict_property)|LockingUserNumber]]</var> property. Its default value is <var>-1</var>, which is not a valid user number, and is the value set for the <var>LockingUserNumber</var> property by the system when the <var>[[RECLOCKO parameter|RECLOCKO]]</var> parameter X'04' bit is not set and a <var>RecordLockingConflict</var> exception is thrown. <br />
</td></tr><br />
<br />
<tr><th><var>LockTimeMilliseconds</var></th><br />
<td>This optional, name required parameter specifies the numeric value (<var class="term">number</var>) to be assigned to the object's <var>[[LockTimeMilliseconds_(RecordLockingConflict_property)|LockTimeMilliseconds]]</var> property. Its default value is a <var>0</var>, which is the value set for the LockTimeMilliseconds property by the system when the <var>RECLOCKO</var> parameter X'04' bit is not set and a <var>RecordLockingConflict</var> exception is thrown. </td></tr><br />
<br />
<tr><th><var>ConflictTimeMilliseconds</var></th><br />
<td>This optional, name required parameter specifies the numeric value (<var class="term">number</var>) to be assigned to the object's <var>[[ConflictTimeMilliseconds_(RecordLockingConflict_property)|ConflictTimeMilliseconds]]</var> property. Its default value is a <var>0</var>, which is the value set for the <var>ConflictTimeMilliseconds</var> property by the system when the <var>RECLOCKO</var> parameter X'04' bit is not set and a <var>RecordLockingConflict</var> exception is thrown. </td></tr><br />
<br />
<tr><th><var>ConflictingLockStrength</var></th><br />
<td>This optional, name required parameter specifies the <var>[[LockStrength]]</var> enumeration value to be assigned to the object's <var>[[ConflictingLockStrength_(RecordLockingConflict_property)|ConflictingLockStrength]]</var> property. Its default value is a <var>Null</var>, which is the value set for the <var>ConflictingLockStrength</var> property by the system when the <var>RECLOCKO</var> parameter X'04' bit is not set and a <var>RecordLockingConflict</var> exception is thrown. Since a record locking conflict cannot be caused by an unlocked record, setting this value to <var>None</var> is equivalent to setting it to <var>Null</var>.</td></tr><br />
<br />
<tr><th><var>ConflictingRecordLockType</var></th><br />
<td>This optional, name required parameter specifies the <var>[[RecordLockType]]</var> enumeration value to be assigned to the object's <var>[[ConflictingRecordLockType_(RecordLockingConflict_property)|ConflictingRecordLockType]]</var> property. Its default value is a <var>Null</var>, which is the value set for the <var>ConflictingRecordLockType</var> property by the system when the <var>RECLOCKO parameter</var> X'04' bit is not set and a <var>RecordLockingConflict</var> exception is thrown.</td></tr><br />
</table><br />
<br />
<br />
==NewFromLastConflict constructor==<br />
{{Template:RecordLockingConflict:NewFromLastConflict subtitle}}<br />
<br />
This <var>Constructor</var> generates an instance of an <var>[[RecordLockingConflict_class|RecordLockingConflict]]</var> exception. Unlike the New method, this method obtains the values of the object properties from the last record locking conflict that occurred, whether or not it was trapped (caught or handled by an On unit). In fact, the greatest utility of this method would be to create a <var>RecordLockingConflict</var> instance that contains all record locking information in an <var>On Record Locking Conflict</var> or <var>On Find Conflict</var> unit. This is especially useful for accessing the properties set by the <var>[[RECLOCKO]]</var> parameter X'04' bit in an <var>On</var> unit. These properties are <var>LockingUserNumber</var>, <var>LockTimeMilliseconds</var>, <var>ConflictTimeMilliseconds</var>, <var>ConflictingLockStrength</var>, and <var>ConflictingRecordLockType</var>.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:NewFromLastConflict syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%reclockInfo</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.</td></tr><br />
<br />
<tr><th><var>[%(RecordLockingConflict):]</var></th><br />
<td>The class name in parentheses denotes a <var>[[Notation conventions for methods#Constructors|Constructor]]</var>.</td></tr><br />
</table><br />
<br />
====Usage notes====<br />
<ul><br />
<li>If there have been no record locking conflicts in the current request, this method returns a <var>Null</var>.<br />
<li>Since <var class="product">Model 204</var> clears the record locking conflict information at the start of each request, this method cannot be used to retrieve information from a previous request.<br />
</ul><br />
<br />
<br />
==RecordNumber property==<br />
{{Template:RecordLockingConflict:RecordNumber subtitle}}<br />
<br />
This <var>[[Classes and Objects#readWrite|ReadOnly]]</var> property returns the numeric value of the <var class="product">Model 204</var> internal record number of the record that has the conflict.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:RecordNumber syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%number</th><br />
<td>A numeric variable to receive the record number.<br />
</td></tr><br />
<br />
<tr><th>recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.<br />
</td></tr></table><br />
<br />
====Example====<br />
The following example shows all the properties of the <var>RecordLockingConflict</var> class. While the standard record locking conflict information is available for retrieval via the <var class="product">User Language</var> functions $rlcfile, $rlcrec, $rlcuid, and $rlcusr, that information is also set in the exception object and retrievable via that object:<br />
<p class="code">%rlc is object RecordLockingConflict<br />
...<br />
%rec = new(%recnum, none, loopLockStrength=share)<br />
...<br />
try for record %rec<br />
...<br />
end for<br />
catch recordLockingConflict to %rlc<br />
[[Audittext|auditText]] Conflict on record {%rlc:recordNumber} -<br />
in file {%rlc:filename}<br />
auditText Conflicting user was userid {%rlc:userid}, -<br />
with user number:{%rlc:userNumber}<br />
end try<br />
</p><br />
<br />
<br />
==UserID property==<br />
{{Template:RecordLockingConflict:UserID subtitle}}<br />
<br />
This <var>ReadOnly</var> property returns the <var class="product">Model 204</var> userid (login name) of the user that has the conflict.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:UserID syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%string</th><br />
<td>A <var>[[Longstrings|longstring]]</var> to receive the userid value.</td></tr><br />
<br />
<tr><th>recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.</td></tr><br />
</table><br />
<br />
<br />
==UserNumber property==<br />
{{Template:RecordLockingConflict:UserNumber subtitle}}<br />
<br />
This <var>ReadOnly</var> property returns the user number (unique per session) of the user that has the conflict.<br />
<br />
====Syntax====<br />
{{Template:RecordLockingConflict:UserNumber syntax}}<br />
<br />
====Syntax terms====<br />
<table class="syntaxTable"><br />
<tr><th>%number</th><br />
<td>A numeric variable to receive the user number.</td></tr><br />
<br />
<tr><th>recordLockingConflict</th><br />
<td>A reference to an instance of a <var>RecordLockingConflict</var> object.</td></tr><br />
</table><br />
<br />
<br />
[[Category:System exception classes]]</div>Adrianhttps://m204wiki.rocketsoftware.com/index.php?title=System_and_Subsystem_classes&diff=13966System and Subsystem classes2012-10-30T00:45:47Z<p>Adrian: /* System-wide objects */</p>
<hr />
<div><!-- System and Subsystem classes --><br />
<!-- on System class page, #REDIRECT [[System and Subsystem classes]]<br />
on Subystem class page, #REDIRECT [[System and Subsystem classes]] --> <br />
The System and Subsystem classes are collections of shared methods that<br />
operate on entities (globals, strings, objects) made<br />
available to all users in an Online system or all users in a subsystem,<br />
or that operate on environmental entities such as the current INCLUDE<br />
arguments, or the current call stack that are essentially part of the<br />
&ldquo;system.&rdquo;<br />
<br />
There are no System or Subsystem objects, per se.<br />
That is, you cannot instantiate an instance of a System or Subsystem object,<br />
nor assign references from one variable to another, nor are there any<br />
instance-specific methods in these classes.<br />
You can, however, declare objects of these classes.<br />
The main use of such objects is to provide a short-hand way of referencing<br />
the classes:<br />
<pre style="xmp"><br />
%sys is object system<br />
%subsys is object subsystem<br />
...<br />
%sys:setGlobal('GOOSE', 'SAUCE')<br />
%subsys:setGlobal('GANDER', 'SAUCE')<br />
</pre><br />
<br />
Even though you cannot instantiate or invoke instance-specific<br />
methods against System or Subsystem objects, you may find it<br />
helpful to think of there being an implicit System object<br />
that contains system-wide and thread-specific context for the system,<br />
and a SubSystem object for every valid subsystem context.<br />
Still, all System and Subsystem class methods are shared methods,<br />
so they are invokable via their class names:<br />
<pre style="xmp"><br />
%(system):setString('STATUS', %status)<br />
print %(subsystem):string('INFO')<br />
</pre><br />
==Subsystem context==<br />
Subsystem class methods operate on entities associated with the current<br />
subsystem context.<br />
This context is, by default, the current subsystem in which a request<br />
is running.<br />
It is, possible, however, to run with a subsystem context different from<br />
the current subsystem.<br />
This subsystem context can be a subsystem other than the one being run,<br />
or it can even be a context that isn't associated with a real subsystem &mdash;<br />
the context is simply a name, and it is not required to be a started or<br />
even defined subsystem.<br />
It is also possible to set a subsystem context for requests that are not even<br />
inside a subsystem.<br />
<br />
When a subsystem is entered, the subsystem context is automatically set to<br />
the name of the one being entered.<br />
When the subsystem is exited, the context is set back to the subsystem<br />
context in effect at entry to the subsystem, whether or not the subsystem was<br />
changed inside the subsystem.<br />
<br />
Once the subsystem context is set, all Subsystem class methods apply to<br />
that subsystem context.<br />
For example, if subsystem ORDER is entered, the following statement<br />
sets a subsystem string for that subsystem:<br />
<pre style="xmp"><br />
%(subsystem):setString('DEBUG', 'ON')<br />
</pre><br />
However, if the following statement is run before it,<br />
the SetString method actually applies to the DISORDER subsystem context:<br />
<pre style="xmp"><br />
%(subsystem):context = 'DISORDER'<br />
</pre><br />
<br />
Since setting the subsystem context allows a request to modify entities<br />
associated with another subsystem, the ability to set subsystem context<br />
is protected.<br />
Ordinarily, only a system manager can set the subsystem context, though<br />
the ability to set subsystem context can be controlled with SIRMETH<br />
rules.<br />
==Using SIRMETH to specify security rules==<br />
The ability to modify system or subsystem entities gives a user the<br />
ability to cause problems in threads other than their own.<br />
As such, this capability must be protected to prevent malicious or<br />
unintentional modification of system-wide or subsystem-wide<br />
entities.<br />
<br />
The default protection for system-wide and subsystem-wide entities<br />
is:<br />
<ul><br />
<li>Only system managers can modify system-wide entities (system globals<br />
and strings, for example).<br />
<li>Only pre-compiled procedures in a subsystem can modify subsystem-wide<br />
entities.<br />
<li>Only system managers can set their subsystem context.<br />
</ul><br />
<br />
While these rules prevent intentional or unintentional tampering<br />
with system or subsystem entities, they can also be onerous:<br />
<ul><br />
<li>There might be several trusted subsystems that one would want to<br />
allow to set System globals.<br />
<li>One might want to set SubSystem globals in non-precompiled procedures.<br />
<li>One might want several subsystems to operate under the same subsystem<br />
context, that is, share subsystem entities.<br />
<li>For development and debugging, one might want very loose restrictions<br />
on what programmers can and cannot do.<br />
</ul><br />
While most of these problems can be worked around by giving programmers system<br />
manager privileges or by having subsystems run with system manager privileges,<br />
this might be further than one wants to go to provide these capabilities.<br />
<br />
To ameliorate these problems, the SIRMETH command is provided.<br />
The SIRMETH command provides a way of giving specific subsystems or all<br />
users access to certain System or Subsystem class capabilities.<br />
Of course, the SIRMETH command itself requires system manager privileges.<br />
===SIRMETH command syntax===<br />
SIRMETH {ALLOW | DISALLOW} -<br />
{SYSTEMSET | SUBSYSTEMSET | -<br />
SUBSYSTEMCONTEXT csubsys | ALL} -<br />
[SUBSYSTEM subsys [NONPRE] ]<br />
Where:<br />
<dl><br />
<dt>ALLOW<br />
<dd>Indicates that requests matching the rule will be allowed to perform<br />
the indicated action.<br />
<dt>DISALLOW<br />
<dd>Indicates that requests matching the rule will not be allowed to perform<br />
the indicated action.<br />
<dt>SYSTEMSET<br />
<dd>Indicates the ability to set system strings or globals.<br />
This applies to the SetGlobal and SetString methods in the System<br />
class, as well as the $setg_sys function.<br />
<dt>SUBSYSTEMSET<br />
<dd>Indicates the ability to set subsytem strings or globals.<br />
This applies to the SetGlobal and SetString methods in the SubSystem<br />
class, as well as the $setg_subsys function (when the third argument,<br />
the subsystem name, is not specified).<br />
<dt>SUBSYSTEMCONTEXT<br />
<dd>Indicates the ability to change subsytem context to the subsystem<br />
indicated by ''csubsys''.<br />
''csubsys'' can be a specific subsystem name such as SIRPRO,<br />
or it can be a wild-card such as SIR* or ???PRO.<br />
<dt>ALL<br />
<dd>Only allowed on a DISALLOW rule, this indicates that no extra<br />
capabilities are to be provided to requests matching the rule.<br />
<dt>SUBSYSTEM<br />
<dd>Indicates that the action is to be allowed to methods in the subsystem<br />
indicated by ''subsys''.<br />
''subsys'' can be a specific subsystem name such as INVENTORY, or it<br />
can be a wild-card such as INV* or INVENTO?Y.<br />
<br />
Note that if SUBSYSTEM is specified, the rule applies to the real subsystem<br />
being run, regardless of the current subsystem context.<br />
Note also that unless followed by the keyword NONPRE, the rule only applies<br />
to pre-compiled procedures in the subsystem.<br />
<dt>NONPRE<br />
<dd>Indicates that non-pre-compiled<br />
procedures in the subsystem are also to be given the capabilities indicated by<br />
the SIRMETH rule.<br />
NONPRE must immediately follow the subsystem name.<br />
</dl><br />
<br />
You can specify as many SIRMETH rules as you want.<br />
A SIRMETH rule that<br />
totally encompasses a previous rule preempts that rule.<br />
For example, in the following two rules,<br />
the second SIRMETH rule completely encompasses the first, so the first<br />
rule is discarded:<br />
<pre style="xmp"><br />
SIRMETH ALLOW SUBSYSTEMSET SUBSYS FOOBAR<br />
SIRMETH ALLOW SUBSYSTEMSET SUBSYS FOO*<br />
</pre><br />
A SIRMETH DISALLOW ALL preempts all previous rules,<br />
so it is a way of starting from a clean slate.<br />
If you place a SIRMETH DISALLOW ALL at the start of a<br />
sequence of SIRMETH rules (most likely in a procedure), those rules<br />
can be run again and again, perhaps after some of the rules have been<br />
modified.<br />
Of course, in the interval between the SIRMETH DISALLOW ALL and the<br />
subsequent rules, some ordinarily legal requests might be disallowed,<br />
so it is probably not a good idea to reapply SIRMETH rules in<br />
a production region.<br />
<br />
Generally, SIRMETH rules are placed in the CCAIN stream or in<br />
a procedure INCLUDE'd in the CCAIN stream.<br />
<br />
The reason for the NONPRE keyword is that many debugging and development<br />
subsystems allow users (programmers, typically) to run arbitrary code<br />
from inside the subsystem.<br />
Typically, this arbitrary code is run from a non-pre-compiled<br />
procedure that includes the programmer's code.<br />
To prevent such code from picking up the subsystem's capabilities,<br />
System and Subsystem class security does not apply SIRMETH rules<br />
to non-pre-compiled procedures, unless the NONPRE keyword is specified<br />
on the rule.<br />
Since most subsystems don't allow users to run arbitrary code inside<br />
them, and since it is quite likely that you might want to set<br />
subsystem globals or switch subsystem contexts inside a non-pre-compiled<br />
procedure, it is probably a good idea to specify NONPRE for those<br />
subsystems.<br />
<br />
In a development environment,<br />
to avoid the effort of modifying multiple individual SIRMETH rules,<br />
you may be willing to risk letting<br />
programmers modify any system or subsystem entity.<br />
If so, the following rules allow everyone<br />
to do everything with system and subsystem entities:<br />
<pre style="xmp"><br />
SIRMETH ALLOW SUBSYSTEMSET<br />
SIRMETH ALLOW SUBSYSTEMSET<br />
SIRMETH ALLOW SUBSYSTEMCONTEXT<br />
</pre><br />
<br />
It is worth reiterating that while the System and Subsystem classes are<br />
the preferred interface for setting system and subsystem globals,<br />
the SIRMETH rules also apply to $setg_sys and $setg_subsys.<br />
If the third parameter of $setg_subsys (subsystem name) is specified,<br />
no SIRMETH rules apply, and the user must be a system manager.<br />
You can get the same effect as a $setg_subsys with a subsystem<br />
name by saving the subsystem context, setting it, and then restoring it:<br />
<pre style="xmp"><br />
%oldContext = %(subsystem):context<br />
%(subsystem):context = 'CUSTOMER'<br />
%(subsystem):setGlobal('CUSTFILE', 'GROUP CUST2004')<br />
%(subsystem):context = %oldContext<br />
</pre><br />
==System and subsystem globals and strings==<br />
Typically, a $getg function or a dummy string compile-time string<br />
(that is, something that begins with <tt>?&</tt>) is resolved from a thread-level<br />
global variable (that is, a variable set via $setg).<br />
Often, however, all requests in an Online or subsystem will use the<br />
same value for some of these globals, so it seems appealing for these<br />
users to share a copy of those globals rather than each wasting GTBL<br />
space to hold a copy for each thread.<br />
System and subsystem globals make this feasible.<br />
<br />
By default, if a global reference (either a $getg or a dummy string)<br />
cannot be resolved with thread-level globals, subsystem and then system<br />
globals will be searched.<br />
If one of these matches the requested global, that global will be<br />
returned for the $getg or the dummy string.<br />
<br />
For example, if the following statement exists in a subsystem initialization<br />
procedure:<br />
<pre style="xmp"><br />
%(subsystem):setGlobal('INVFILE', 'PERM GROUP INV2004')<br />
</pre><br />
the following line<br />
<pre style="xmp"><br />
%inventoryRecords is object recordSet in ?&INVFILE<br />
</pre><br />
is resolved as<br />
<pre style="xmp"><br />
%inventoryRecords is object recordSet in PERM GROUP INV2004<br />
</pre><br />
<br />
$SIRPARM has settings to indicate that $get or dummy string lookup<br />
should use subsystem or system globals ahead of thread-specific globals.<br />
For example, the following statement<br />
indicates that subsystem or system globals are to be used ahead of thread-specific<br />
globals for dummy strings:<br />
<pre style="xmp"><br />
%rc = $sirparm('DUMMYSYS', 1)<br />
</pre><br />
And the following call indicates that subsystem or system globals are to be used<br />
ahead of thread-specific globals for $getg calls:<br />
<pre style="xmp"><br />
%rc = $sirparm('GETGSYS', 1)<br />
</pre><br />
<br />
Note that system and subsystem globals are different from system and<br />
subsystem strings.<br />
The latter are never returned for $getg or dummy string requests,<br />
and they can only be retrieved via the [[String (System/Subsystem function)|String]]<br />
function.<br />
Also, system and subsystem global values can never be longer than 255 bytes,<br />
whereas<br />
system and subsystem strings are longstrings, which can be up to 2**31-1 bytes<br />
long.<br />
==System-wide objects==<br />
<var class="product">Sirius Mods</var> version 6.7 adds methods to the Janus System and Subsystem classes<br />
that make designated objects available to all users in an Online or of a subsystem.<br />
Such objects, referred to as '''system-wide''' objects, are made available<br />
via deep copy, so only<br />
deep copyable (see [[Copying objects]]) objects are eligible.<br />
<br />
An object becomes system-wide if and only if it is saved by the System class<br />
SetObject method or by the Subsystem class SetObject method.<br />
If by the System class SetObject method, the &ldquo;system&rdquo; in system-wide<br />
refers to all users in the Online; if by the Subsystem SetObject method, all<br />
users in the current or a specified subsystem.<br />
<br />
System-wide objects belong to a namespace that is not the same as<br />
that for System and Subsystem longstrings.<br />
That is, both a System longstring and a system-wide object may be called by the<br />
same name at the same time.<br />
<br />
The methods that work with system-wide objects are one System and one Subsystem<br />
class version of each of the following:<br />
<table><br />
<tr><br />
<th>Method</th><br />
<th>Summary</th><br />
<th>System</th><br />
<th>SubSystem</th><br />
<tr><br />
<td><b>SetObject</b></td><br />
<td>Makes an object available system-wide with a specified name.</td><br />
<td>[[SetObject (System function)|SetObject]]</td><br />
<td>[[SetObject (Subsystem function)|SetObject]]</td><br />
</tr><br />
<tr><br />
<td><b>GetObject</b></td><br />
<td>Retrieves a copy of the specified system-wide object.</td><br />
<td>[[GetObject (System function)|GetObject]]</td><br />
<td>[[GetObject (Subsystem function)|GetObject]]</td><br />
</tr><br />
<tr><br />
<td><b>DeleteObject</b></td><br />
<td>Deletes the specified system-wide object.</td><br />
<td>[[DeleteObject (System subroutine)|DeleteObject]]</td><br />
<td>[[DeleteObject (Subsystem subroutine)|DeleteObject]]</td><br />
</tr><br />
<tr><br />
<td><b>ListOfObjects</b></td><br />
<td>Returns a Stringlist containing information about system-wide objects</td><br />
<td>[[ListOfObjects (System function)|ListOfObjects]]</td><br />
<td>[[ListOfObjects (Subsystem function)|ListOfObjects]]</td><br />
</tr><br />
</table><br />
<br />
==Lists of System and Subsystem methods==<br />
The individual System methods are summarized in [[List of System methods|"List of System methods"]].<br />
<p></p><br />
The individual Subsystem methods are summarized in [[List of Subsystem methods|"List of Subsystem methods"]].</div>Adrianhttps://m204wiki.rocketsoftware.com/index.php?title=System_and_Subsystem_classes&diff=13965System and Subsystem classes2012-02-16T03:57:44Z<p>Adrian: /* System-wide objects */</p>
<hr />
<div><!-- System and Subsystem classes --><br />
<!-- on System class page, #REDIRECT [[System and Subsystem classes]]<br />
on Subystem class page, #REDIRECT [[System and Subsystem classes]] --> <br />
The System and Subsystem classes are collections of shared methods that<br />
operate on entities (globals, strings, objects) made<br />
available to all users in an Online system or all users in a subsystem,<br />
or that operate on environmental entities such as the current INCLUDE<br />
arguments, or the current call stack that are essentially part of the<br />
&ldquo;system.&rdquo;<br />
<br />
There are no System or Subsystem objects, per se.<br />
That is, you cannot instantiate an instance of a System or Subsystem object,<br />
nor assign references from one variable to another, nor are there any<br />
instance-specific methods in these classes.<br />
You can, however, declare objects of these classes.<br />
The main use of such objects is to provide a short-hand way of referencing<br />
the classes:<br />
<pre style="xmp"><br />
%sys is object system<br />
%subsys is object subsystem<br />
...<br />
%sys:setGlobal('GOOSE', 'SAUCE')<br />
%subsys:setGlobal('GANDER', 'SAUCE')<br />
</pre><br />
<br />
Even though you cannot instantiate or invoke instance-specific<br />
methods against System or Subsystem objects, you may find it<br />
helpful to think of there being an implicit System object<br />
that contains system-wide and thread-specific context for the system,<br />
and a SubSystem object for every valid subsystem context.<br />
Still, all System and Subsystem class methods are shared methods,<br />
so they are invokable via their class names:<br />
<pre style="xmp"><br />
%(system):setString('STATUS', %status)<br />
print %(subsystem):string('INFO')<br />
</pre><br />
==Subsystem context==<br />
Subsystem class methods operate on entities associated with the current<br />
subsystem context.<br />
This context is, by default, the current subsystem in which a request<br />
is running.<br />
It is, possible, however, to run with a subsystem context different from<br />
the current subsystem.<br />
This subsystem context can be a subsystem other than the one being run,<br />
or it can even be a context that isn't associated with a real subsystem &mdash;<br />
the context is simply a name, and it is not required to be a started or<br />
even defined subsystem.<br />
It is also possible to set a subsystem context for requests that are not even<br />
inside a subsystem.<br />
<br />
When a subsystem is entered, the subsystem context is automatically set to<br />
the name of the one being entered.<br />
When the subsystem is exited, the context is set back to the subsystem<br />
context in effect at entry to the subsystem, whether or not the subsystem was<br />
changed inside the subsystem.<br />
<br />
Once the subsystem context is set, all Subsystem class methods apply to<br />
that subsystem context.<br />
For example, if subsystem ORDER is entered, the following statement<br />
sets a subsystem string for that subsystem:<br />
<pre style="xmp"><br />
%(subsystem):setString('DEBUG', 'ON')<br />
</pre><br />
However, if the following statement is run before it,<br />
the SetString method actually applies to the DISORDER subsystem context:<br />
<pre style="xmp"><br />
%(subsystem):context = 'DISORDER'<br />
</pre><br />
<br />
Since setting the subsystem context allows a request to modify entities<br />
associated with another subsystem, the ability to set subsystem context<br />
is protected.<br />
Ordinarily, only a system manager can set the subsystem context, though<br />
the ability to set subsystem context can be controlled with SIRMETH<br />
rules.<br />
==Using SIRMETH to specify security rules==<br />
The ability to modify system or subsystem entities gives a user the<br />
ability to cause problems in threads other than their own.<br />
As such, this capability must be protected to prevent malicious or<br />
unintentional modification of system-wide or subsystem-wide<br />
entities.<br />
<br />
The default protection for system-wide and subsystem-wide entities<br />
is:<br />
<ul><br />
<li>Only system managers can modify system-wide entities (system globals<br />
and strings, for example).<br />
<li>Only pre-compiled procedures in a subsystem can modify subsystem-wide<br />
entities.<br />
<li>Only system managers can set their subsystem context.<br />
</ul><br />
<br />
While these rules prevent intentional or unintentional tampering<br />
with system or subsystem entities, they can also be onerous:<br />
<ul><br />
<li>There might be several trusted subsystems that one would want to<br />
allow to set System globals.<br />
<li>One might want to set SubSystem globals in non-precompiled procedures.<br />
<li>One might want several subsystems to operate under the same subsystem<br />
context, that is, share subsystem entities.<br />
<li>For development and debugging, one might want very loose restrictions<br />
on what programmers can and cannot do.<br />
</ul><br />
While most of these problems can be worked around by giving programmers system<br />
manager privileges or by having subsystems run with system manager privileges,<br />
this might be further than one wants to go to provide these capabilities.<br />
<br />
To ameliorate these problems, the SIRMETH command is provided.<br />
The SIRMETH command provides a way of giving specific subsystems or all<br />
users access to certain System or Subsystem class capabilities.<br />
Of course, the SIRMETH command itself requires system manager privileges.<br />
===SIRMETH command syntax===<br />
SIRMETH {ALLOW | DISALLOW} -<br />
{SYSTEMSET | SUBSYSTEMSET | -<br />
SUBSYSTEMCONTEXT csubsys | ALL} -<br />
[SUBSYSTEM subsys [NONPRE] ]<br />
Where:<br />
<dl><br />
<dt>ALLOW<br />
<dd>Indicates that requests matching the rule will be allowed to perform<br />
the indicated action.<br />
<dt>DISALLOW<br />
<dd>Indicates that requests matching the rule will not be allowed to perform<br />
the indicated action.<br />
<dt>SYSTEMSET<br />
<dd>Indicates the ability to set system strings or globals.<br />
This applies to the SetGlobal and SetString methods in the System<br />
class, as well as the $setg_sys function.<br />
<dt>SUBSYSTEMSET<br />
<dd>Indicates the ability to set subsytem strings or globals.<br />
This applies to the SetGlobal and SetString methods in the SubSystem<br />
class, as well as the $setg_subsys function (when the third argument,<br />
the subsystem name, is not specified).<br />
<dt>SUBSYSTEMCONTEXT<br />
<dd>Indicates the ability to change subsytem context to the subsystem<br />
indicated by ''csubsys''.<br />
''csubsys'' can be a specific subsystem name such as SIRPRO,<br />
or it can be a wild-card such as SIR* or ???PRO.<br />
<dt>ALL<br />
<dd>Only allowed on a DISALLOW rule, this indicates that no extra<br />
capabilities are to be provided to requests matching the rule.<br />
<dt>SUBSYSTEM<br />
<dd>Indicates that the action is to be allowed to methods in the subsystem<br />
indicated by ''subsys''.<br />
''subsys'' can be a specific subsystem name such as INVENTORY, or it<br />
can be a wild-card such as INV* or INVENTO?Y.<br />
<br />
Note that if SUBSYSTEM is specified, the rule applies to the real subsystem<br />
being run, regardless of the current subsystem context.<br />
Note also that unless followed by the keyword NONPRE, the rule only applies<br />
to pre-compiled procedures in the subsystem.<br />
<dt>NONPRE<br />
<dd>Indicates that non-pre-compiled<br />
procedures in the subsystem are also to be given the capabilities indicated by<br />
the SIRMETH rule.<br />
NONPRE must immediately follow the subsystem name.<br />
</dl><br />
<br />
You can specify as many SIRMETH rules as you want.<br />
A SIRMETH rule that<br />
totally encompasses a previous rule preempts that rule.<br />
For example, in the following two rules,<br />
the second SIRMETH rule completely encompasses the first, so the first<br />
rule is discarded:<br />
<pre style="xmp"><br />
SIRMETH ALLOW SUBSYSTEMSET SUBSYS FOOBAR<br />
SIRMETH ALLOW SUBSYSTEMSET SUBSYS FOO*<br />
</pre><br />
A SIRMETH DISALLOW ALL preempts all previous rules,<br />
so it is a way of starting from a clean slate.<br />
If you place a SIRMETH DISALLOW ALL at the start of a<br />
sequence of SIRMETH rules (most likely in a procedure), those rules<br />
can be run again and again, perhaps after some of the rules have been<br />
modified.<br />
Of course, in the interval between the SIRMETH DISALLOW ALL and the<br />
subsequent rules, some ordinarily legal requests might be disallowed,<br />
so it is probably not a good idea to reapply SIRMETH rules in<br />
a production region.<br />
<br />
Generally, SIRMETH rules are placed in the CCAIN stream or in<br />
a procedure INCLUDE'd in the CCAIN stream.<br />
<br />
The reason for the NONPRE keyword is that many debugging and development<br />
subsystems allow users (programmers, typically) to run arbitrary code<br />
from inside the subsystem.<br />
Typically, this arbitrary code is run from a non-pre-compiled<br />
procedure that includes the programmer's code.<br />
To prevent such code from picking up the subsystem's capabilities,<br />
System and Subsystem class security does not apply SIRMETH rules<br />
to non-pre-compiled procedures, unless the NONPRE keyword is specified<br />
on the rule.<br />
Since most subsystems don't allow users to run arbitrary code inside<br />
them, and since it is quite likely that you might want to set<br />
subsystem globals or switch subsystem contexts inside a non-pre-compiled<br />
procedure, it is probably a good idea to specify NONPRE for those<br />
subsystems.<br />
<br />
In a development environment,<br />
to avoid the effort of modifying multiple individual SIRMETH rules,<br />
you may be willing to risk letting<br />
programmers modify any system or subsystem entity.<br />
If so, the following rules allow everyone<br />
to do everything with system and subsystem entities:<br />
<pre style="xmp"><br />
SIRMETH ALLOW SUBSYSTEMSET<br />
SIRMETH ALLOW SUBSYSTEMSET<br />
SIRMETH ALLOW SUBSYSTEMCONTEXT<br />
</pre><br />
<br />
It is worth reiterating that while the System and Subsystem classes are<br />
the preferred interface for setting system and subsystem globals,<br />
the SIRMETH rules also apply to $setg_sys and $setg_subsys.<br />
If the third parameter of $setg_subsys (subsystem name) is specified,<br />
no SIRMETH rules apply, and the user must be a system manager.<br />
You can get the same effect as a $setg_subsys with a subsystem<br />
name by saving the subsystem context, setting it, and then restoring it:<br />
<pre style="xmp"><br />
%oldContext = %(subsystem):context<br />
%(subsystem):context = 'CUSTOMER'<br />
%(subsystem):setGlobal('CUSTFILE', 'GROUP CUST2004')<br />
%(subsystem):context = %oldContext<br />
</pre><br />
==System and subsystem globals and strings==<br />
Typically, a $getg function or a dummy string compile-time string<br />
(that is, something that begins with <tt>?&</tt>) is resolved from a thread-level<br />
global variable (that is, a variable set via $setg).<br />
Often, however, all requests in an Online or subsystem will use the<br />
same value for some of these globals, so it seems appealing for these<br />
users to share a copy of those globals rather than each wasting GTBL<br />
space to hold a copy for each thread.<br />
System and subsystem globals make this feasible.<br />
<br />
By default, if a global reference (either a $getg or a dummy string)<br />
cannot be resolved with thread-level globals, subsystem and then system<br />
globals will be searched.<br />
If one of these matches the requested global, that global will be<br />
returned for the $getg or the dummy string.<br />
<br />
For example, if the following statement exists in a subsystem initialization<br />
procedure:<br />
<pre style="xmp"><br />
%(subsystem):setGlobal('INVFILE', 'PERM GROUP INV2004')<br />
</pre><br />
the following line<br />
<pre style="xmp"><br />
%inventoryRecords is object recordSet in ?&INVFILE<br />
</pre><br />
is resolved as<br />
<pre style="xmp"><br />
%inventoryRecords is object recordSet in PERM GROUP INV2004<br />
</pre><br />
<br />
$SIRPARM has settings to indicate that $get or dummy string lookup<br />
should use subsystem or system globals ahead of thread-specific globals.<br />
For example, the following statement<br />
indicates that subsystem or system globals are to be used ahead of thread-specific<br />
globals for dummy strings:<br />
<pre style="xmp"><br />
%rc = $sirparm('DUMMYSYS', 1)<br />
</pre><br />
And the following call indicates that subsystem or system globals are to be used<br />
ahead of thread-specific globals for $getg calls:<br />
<pre style="xmp"><br />
%rc = $sirparm('GETGSYS', 1)<br />
</pre><br />
<br />
Note that system and subsystem globals are different from system and<br />
subsystem strings.<br />
The latter are never returned for $getg or dummy string requests,<br />
and they can only be retrieved via the [[String (System/Subsystem function)|String]]<br />
function.<br />
Also, system and subsystem global values can never be longer than 255 bytes,<br />
whereas<br />
system and subsystem strings are longstrings, which can be up to 2**31-1 bytes<br />
long.<br />
==System-wide objects==<br />
''Sirius Mods'' version 6.7 adds methods to the Janus System and Subsystem classes<br />
that make designated objects available to all users in an Online or of a subsystem.<br />
Such objects, referred to as '''system-wide''' objects, are made available<br />
via deep copy, so only<br />
deep copyable (see [[Copying objects]]) objects are eligible.<br />
<br />
An object becomes system-wide if and only if it is saved by the System class<br />
SetObject method or by the Subsystem class SetObject method.<br />
If by the System class SetObject method, the &ldquo;system&rdquo; in system-wide<br />
refers to all users in the Online; if by the Subsystem SetObject method, all<br />
users in the current or a specified subsystem.<br />
<br />
System-wide objects belong to a namespace that is not the same as<br />
that for System and Subsystem longstrings.<br />
That is, both a System longstring and a system-wide object may be called by the<br />
same name at the same time.<br />
<br />
The methods that work with system-wide objects are one System and one Subsystem<br />
class version of each of the following:<br />
<table><br />
<tr><br />
<th>Method</th><br />
<th>Summary</th><br />
<th>System</th><br />
<th>SubSystem</th><br />
<tr><br />
<td><b>SetObject</b></td><br />
<td>Makes an object available system-wide with a specified name.</td><br />
<td>[[SetObject (System function)|SetObject]]</td><br />
<td>[[SetObject (Subsystem function)|SetObject]]</td><br />
</tr><br />
<tr><br />
<td><b>GetObject</b></td><br />
<td>Retrieves a copy of the specified system-wide object.</td><br />
<td>[[GetObject (System function)|GetObject]]</td><br />
<td>[[GetObject (Subsystem function)|GetObject]]</td><br />
</tr><br />
<tr><br />
<td><b>DeleteObject</b></td><br />
<td>Deletes the specified system-wide object.</td><br />
<td>[[DeleteObject (System subroutine)|DeleteObject]]</td><br />
<td>[[DeleteObject (Subsystem subroutine)|DeleteObject]]</td><br />
</tr><br />
<tr><br />
<td><b>ListOfObjects</b></td><br />
<td>Returns a Stringlist containing information about system-wide objects</td><br />
<td>[[ListOfObjects (System function)|ListOfObjects]]</td><br />
<td>[[ListOfObjects (Subsystem function)|ListOfObjects]]</td><br />
</tr><br />
</table><br />
<br />
==Lists of System and Subsystem methods==<br />
The individual System methods are summarized in [[List of System methods|"List of System methods"]].<br />
<p></p><br />
The individual Subsystem methods are summarized in [[List of Subsystem methods|"List of Subsystem methods"]].</div>Adrian