|
|
| (72 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
|
| | Content moved to M204Int, but history preserved here. |
| The following sections describe changes in the <var>[[Janus SOAP User Language Interface|Janus SOAP ULI]]</var>
| |
| in this release.
| |
|
| |
| ==New arguments for Record class ToXmlDoc method==
| |
| The <var>[[ToXmlDoc (Record function)|ToXmlDoc]]</var> method in the <var>Record</var> class has the following new
| |
| arguments:
| |
| <table>
| |
| <tr><th>CodepageTable
| |
| </th><td>This optional, <var>[[Methods#Named parameters|NameRequired]]</var>, <var>[[Enumerations#Using Boolean enumerations|Boolean]]</var> argument, which defaults to <var>False</var>, specifies whether to use the base codepage translation table when creating the <var>XmlDoc.</var> For more details, see the description of the <var>CodepageTable</var> argument in [[Janus SOAP XmlDoc API V7.8 changes#LoadFromRecord subroutine in XmlDoc and XmlNode classes|"LoadFromRecord subroutine in XmlDoc and XmlNode classes"]].
| |
|
| |
| This argument was actually introduced in version 7.6 of the <var class="product">Sirius Mods</var>.
| |
| </td></tr>
| |
| <tr><th>AllowNull
| |
| </th><td>The value of this optional, <var>[[Methods#Named parameters|NameRequired]]</var>, <var>Boolean</var> argument, which defaults to <var>False</var>, is copied to the <var>AllowNull</var> property of the <var>XmlDoc</var> created by <var>ToXmlDoc</var>. The <var>XmlDoc</var>'s <var>AllowNull</var> property, in turn, determines whether field values that contain the X'00' character are stored in the <var>XmlDoc</var> with base64 encoding. Such values are base64 encoded if <var>AllowNull</var> is <var>False</var>.
| |
|
| |
| For more information, see the description of the <var>AllowNull</var> argument in [[Janus SOAP XmlDoc API V7.8 changes#NewFromRecord shared function in XmlDoc class|"NewFromRecord shared function in XmlDoc class"]].
| |
|
| |
| This argument was actually introduced in version 7.7 of the <var class="product">Sirius Mods</var>.
| |
| </td></tr></table>
| |
| | |
| ==Field references in Record class CurrentRecord methods==
| |
| For methods declared with a <var>CurrentRecord</var> attribute, it was the case under <var class="product">Sirius Mods</var> 7.7 that field references were an exception to the following rule:
| |
| <br>
| |
| ''Statements within the method definition, even a <var>CurrentRecord</var> method call, may reference the record without having to be wrapped inside a record <var>For</var> loop.''
| |
|
| |
| Under <var class="product">Sirius Mods</var> 7.8, field references are no longer an exception to this rule.
| |
| You may reference a record field from within a method declared with <var>CurrentRecord</var>
| |
| without being inside a record <var>For</var> loop.
| |
|
| |
| For example, for the field COLOR,
| |
| the <code>For Record currentRecord</code> and <code>End For</code>
| |
| statements containing the
| |
| <code>print COLOR</code> statement in the method definition below
| |
| may be discarded under <var class="product>Sirius Mods</var> 7.8:
| |
| <p class="code">local subroutine (Record in file myproc):printField currentRecord in file myproc
| |
| for record currentRecord
| |
| print COLOR
| |
| end for
| |
| end subroutine
| |
| </p>
| |
|
| |
| ==New class: PersistentObjectInfo==
| |
| <var class="product">Sirius Mods</var> 7.8 contains the new <var>PersistentObjectInfo</var> class, which contains information about a [[Global and session objects|global or session object]] in the current thread.
| |
|
| |
| Persistent information was typically stored in <var>Stringlists</var> (or <var>$lists</var>), and individual values all began at designated columns. This approach at least allowed for the sorting of these values.
| |
| But the availability of generic sorting for <var>Arraylists</var> makes <var>Arraylists</var> of information objects the correct way to provide information to <var class="product">User Language</var>:
| |
| <ul>
| |
| <li>It eliminates the reliance on column positions in <var class="product">User Language</var> code.
| |
|
| |
| <li>It makes it possible to change the size of values or to add information to the
| |
| Info class in the future without breaking existing applications.
| |
| </ul>
| |
|
| |
| In addition to occupying considerably less space than fixed column $lists, <var>PersistentObjectInfo</var>
| |
| objects also offer the advantage of the sorting, finding, and subsetting facilities of
| |
| collections.
| |
| | |
| ===The information accessing methods===
| |
| Three pieces of information (provided by class functions named as follows) are available for a global or
| |
| session object in the <var>PersistentObjectInfo</var> class:
| |
| <table class="syntaxTable">
| |
| <tr><td><var>Name</var></td>
| |
| <td>The global/session name associated with the object.</td></tr>
| |
| <tr><td><var>SetTime</var></td>
| |
| <td>The time the global/session object was set in YYYYMMDDHHMISSXXX format.
| |
| <tr><td><var>ClassDescription</var></td>
| |
| <td>A description of the class of the object. For example, "System:Stringlist", or "MyUserLanguageClass", or "Arraylist of Object MyUserLanguageClass".
| |
| </td></tr></table>
| |
|
| |
| <var>SetTime</var> and <var>ClassDescription</var> are intended for debugging and problem diagnosis and not for application purposes:
| |
| <ul>
| |
| <li>For Global/Session variable declarations,
| |
| <var>SetTime</var> does '''not''' change if request <code>A</code> sets a variable to an object
| |
| instance, and then request <code>B</code> sets it to a new value, <var>SetTime</var> still indicates
| |
| the time the object reference was set in request <code>A</code>.
| |
|
| |
| <li>The format of the data in <var>ClassDescription</var> is subject to change by Sirius; for example, a change in casing.
| |
| </ul>
| |
|
| |
| ===Creating PersistentObjectInfo objects===
| |
| ====Using NewFromGlobal or NewFromSession====
| |
| One way of creating a <var>PersistentObjectInfo</var> object is with the <var>[[NewFromGlobal (PersistentObjectInfo function)|NewFromGlobal]]</var> method
| |
| or the <var>[[NewFromSession (PersistentObjectInfo function)|NewFromSession]]</var>
| |
| method. These methods take a single, required, unnamed string parameter which indicates the name
| |
| of the global or session variable:
| |
| <p class="code">%persInfo is object persistentObjectInfo
| |
| ...
| |
| %persInfo = newFromGlobal('FOOBAR')
| |
| printText *** {~} = {%persInfo:name}, {~} = {%persInfo:setTime}, {~} = {%persInfo:classDescription}
| |
| ...
| |
| %persInfo = newFromSession('SNAFU')
| |
| printText *** {~} = {%persInfo:name}, {~} = {%persInfo:setTime}, {~} = {%persInfo:classDescription}
| |
| </p>
| |
|
| |
| A <var>NewFromSession</var> request cancels if not in a session.
| |
|
| |
| ====Using GlobalList or SessionList====
| |
| Probably the most common way of creating <var>PersistentObjectInfo</var> objects is using
| |
| the <var>GlobalList</var> and <var>SessionList</var> methods. These are [[Notation conventions for methods#Shared methods|shared]] methods that return an
| |
| <var>Arraylist of Object PersistentObjectInfo</var>.
| |
| | |
| The <var>GlobalList</var> and <var>SessionList</var> methods have one
| |
| optional parameter that contains the name of the variables to be returned, with wildcards allowed.
| |
| These wildcards are the <var class="product">User Language</var> standard, non-regex, wildcards.
| |
| Specifying no variable name is the same as specifying an asterisk (<tt>*</tt>) for the variable name: the information is returned for all global or session objects.
| |
|
| |
| For example:
| |
| <p class="code">%persInfoList is arraylist of object persistentObjectInfo
| |
| ...
| |
| %persInfoList = %(persistentObjectInfo):globalList
| |
| for %i from 1 to %persInfoList:count
| |
| printText *** {~} = {%i}, {~} = {%persInfoList(%i):name}, {~} = {%persInfoList(%i):classDescription}
| |
| end for
| |
| </p>
| |
|
| |
| ===The PersistentObjectInfoList type===
| |
| As a coding convenience, this Info class feature also introduces a new <var class="product">User Language</var> %variable declaration type: <var>PersistentObjectInfoList</var>.
| |
| This type is defined as an "Arraylist of Object PersistentObjectInfo". Consequently, you can specify a declaration like the one in the preceding example for <code>%persInfoList</code> more simply as:
| |
| <p class="code">%persInfoList is type persistentObjectInfoList</p>
| |
| | |
| '''Note:''' The keyword <var>Type</var> is required.
| |
|
| |
| ===The GlobalList and SessionList Object class methods===
| |
| The <var>GlobalList</var> and <var>SessionList</var> methods are members of two classes.
| |
| In addition to belonging to the <var>PersistentObjectInfo</var> class, they are also <var>[[Object class|Object]]</var> class shared methods. This means that both of these statements are valid:
| |
|
| |
| <p class="code">%persInfoList = %(persistentObjectInfo):globalList
| |
|
| |
| %persInfoList = %(object):globalList</p>
| |
| | |
| And a statement like the following is also valid:
| |
| <p class="code">%persInfoList = %(object):globalList:sortNew(descending(setTime))</p>
| |
|
| |
| In this last case, the class name before the <var>GlobalList</var> method is unavoidable.
| |
| | |
| ==New exception class: BadJournal==
| |
| The <var>[[BadJournal class|BadJournal]]</var> exception class reports
| |
| errors in CCAJRNL or CCAJLOG datasets or streams, including naming errors.
| |
| The <var>[[New (BadJournal constructor)|New]]</var> method of the <var>[[Journal class|Journal]]</var> system class is the
| |
| system method that automatically throws a <var>BadJournal</var> exception.
| |
|
| |
| The following example shows a <var>Try</var> and <var>Catch</var> of a <var>Journal</var> class, <var>New</var> method,
| |
| exception. An invalid journal name is specified to generate the <var>BadJournal</var> exception:
| |
| <pre>
| |
| Begin
| |
|
| |
| %sl is object stringlist
| |
| %rc is float
| |
| %journal is object journal
| |
| %bdjrnl is object BadJournal
| |
|
| |
| try printtext {~} is: {%journal = new('OLD~RNL')}
| |
| catch BadJournal to %bdjrnl
| |
| Print 'Failure!!! Reason code is: ' %bdjrnl:reasonCode
| |
| end try
| |
|
| |
| %rc = %sl:appendJournalData( -
| |
| Options='MAXIO=1000 WIDTH=138 ST AA USER', -
| |
| Threads='*', Journal=%journal)
| |
| Print %rc
| |
| Print %sl:count
| |
| %sl:print
| |
|
| |
| End
| |
| </pre>
| |
|
| |
| The <var>Stringlist</var> <var>AppendJournalData</var> method does not cancel if its <var>Journal</var>
| |
| parameter is null.
| |
| The request result shows the reason code (<var>[[#ReasonCode property|ReasonCode]]</var> property value)
| |
| stored in the exception object:
| |
| <pre>
| |
| %journal = new('OLD~RNL') is: Failure!!! Reason code is: 1
| |
| 0
| |
| 0
| |
| </pre>
| |
|
| |
| The methods of the <var>BadJournal</var> class are described in the following subsections.
| |
| ===New constructor===
| |
| This constructor generates an instance of a <var>BadJournal</var> exception.
| |
| As shown below, the optional argument of the <var>New</var> method is a setting of
| |
| the <var>ReasonCode</var> property.
| |
|
| |
| ====New constructor syntax====
| |
| [%bdJrnl =] [%(BadJournal):] <var class="literal">New</var>(<var class="literal">ReasonCode=</var>num)
| |
| ===ReasonCode property===
| |
| This <var>[[Classes and Objects#readWrite|ReadOnly]]</var> property returns a numeric reason code that indicates the
| |
| cause of the <var>BadJournal</var> exception.
| |
| ====ReasonCode syntax====
| |
| <p class="code">%rc = %bdJrnl<var class="literal">:ReasonCode</var></p>
| |
| <br>
| |
| Possible reason codes are:
| |
| <table>
| |
| <tr><th>1
| |
| </th><td>Either the dataset or stream name is invalid, or the journal is invalid.
| |
| </td></tr>
| |
| <tr><th>2
| |
| </th><td>The dataset or stream is empty.
| |
| </td></tr>
| |
| <tr><th>3
| |
| </th><td>The journal was created with a different ''Model 204'' version than the current Online.
| |
| </td></tr>
| |
| <tr><th>4
| |
| </th><td>A merged journal is invalid.
| |
| </td></tr></table>
| |
|
| |
| ==Enhancement to exception handling: Success blocks==
| |
| Exception <var>Try</var>/<var>Catch</var> support is enhanced in Version 7.8 by the addition of <var>Success</var> blocks.
| |
| In cases where a <var>Try</var> block contains multiple statements, a
| |
| <var>Success</var> block makes it clear in the code which statement is expected to produce
| |
| the exceptions that are being caught.
| |
| They also protect you from an inadvertent exception thrown in an unexpected context.
| |
|
| |
| For example, consider the following scenario.
| |
| You want to try statement <code><a></code> and, if no exceptions get Thrown,
| |
| you want to do statements <code><nowiki><b></nowiki></code>, <code><c></code>, <code><d></code>, <code><e></code>, and <code><f></code>.
| |
| Otherwise, if statement <code><a></code> throws an exception,
| |
| you want to do statements <code><x></code>, <code><y></code>, or <code><z></code>, depending on the exception.
| |
|
| |
| You code your <var>Try</var>/<var>Catch</var> block like this:
| |
| <p class="code"><nowiki>try
| |
| <a>
| |
| <b>
| |
| <c>
| |
| <d>
| |
| <e>
| |
| <f>
| |
| catch foo
| |
| <x>
| |
| catch bar
| |
| <y>
| |
| catch whatever
| |
| <z>
| |
| end try
| |
| </nowiki></p>
| |
|
| |
| If statement <code><a></code> does indeed throw an exception, statements <code><nowiki><b></nowiki></code> through <code><f></code>
| |
| do not run, and the appropriate <var>Catch</var> statement takes affect.
| |
| However, if statement <code><a></code> does not throw an exception,
| |
| there might be no way to know that statement <code><nowiki><b></nowiki></code>, <code><c></code>, <code><d></code>, <code><e></code>, or <code><f></code> might
| |
| throw an exception that is one of the exceptions in the subsequent <var>Catch</var> statements.
| |
| Or you might be aware of their capacity to do so,
| |
| but you might not expect an exception from any of them in this context. Prior to
| |
| Version 7.8 of the <var class="product">Sirius Mods</var>, there was
| |
| no good way of preventing the catches to also be in effect for these statements
| |
| as well as for statement <code><a></code>.
| |
|
| |
| As of <var class="product">Sirius Mods</var> 7.8, a <var>Success</var> block inside the <var>Try</var> block
| |
| resolves the problem by making it clear that the <var>Catch</var> statements do not apply to
| |
| statements <code><nowiki><b></nowiki></code>, <code><c></code>, <code><d></code>, <code><e></code>,and <code><f></code>:
| |
| <p class="code"><nowiki>try
| |
| <a>
| |
| success
| |
| <b>
| |
| <c>
| |
| <d>
| |
| <e>
| |
| <f>
| |
| catch foo
| |
| <x>
| |
| catch bar
| |
| <y>
| |
| catch whatever
| |
| <z>
| |
| end try
| |
| </nowiki></p>
| |
|
| |
| A <var>Success</var> block may come before or after the <var>Catch</var> blocks:
| |
| <p class="code"><nowiki>try
| |
| <a>
| |
| catch foo
| |
| <x>
| |
| catch bar
| |
| <y>
| |
| catch whatever
| |
| <z>
| |
| success
| |
| <b>
| |
| <c>
| |
| <d>
| |
| <e>
| |
| <f>
| |
| end try
| |
| </nowiki></p>
| |
|
| |
| ==New SelectionCriterion methods: IsNull and IsNotNull==
| |
| These shared methods take no parameters and create a new <var>[[SelectionCriterion class|SelectionCriterion]]</var> object.
| |
| The methods provide control for Null objects in the [[Collections|collection]] you are searching.
| |
| They also let you determine whether a collection contains items that are objects,
| |
| because they cancel the request if the collection being searched contains
| |
| non-object (intrinsic type) items.
| |
|
| |
| An <var>IsNull</var> criterion selects a collection item if the item is a Null object;
| |
| an <var>IsNotNull</var> criterion selects an item object if it is not Null.
| |
|
| |
| The syntax of the methods follows:
| |
| {{Template:SelectionCriterion:IsNull syntax}}
| |
| {{Template:SelectionCriterion:IsNotNull syntax}}
| |
|
| |
| The examples below test a variety of searches against
| |
| <var>Arraylist</var> <code>%al</code> of objects of class <code>T</code>:
| |
| <p class="code">class T
| |
| public
| |
| variable x is float
| |
| end public
| |
| end class
| |
|
| |
| %al is arraylist of object t
| |
| %t is object t
| |
| %t1 is object t
| |
| %t2 is object t
| |
|
| |
| %t1 = null
| |
| %t2 = new
| |
| %al = list(%t1, %t2)
| |
| </p>
| |
| <ol>
| |
| <li>The <var>Arraylist</var> class <var>[[FindNextItem (Arraylist function)|FindNextItem]]</var> method, which throws an exception if its selection criterion
| |
| matches no item, fails in the <var>Try</var> clause below when it tests the Null object item.
| |
| The method's exception is not thrown because the test failure prevents the method
| |
| from completing its search:
| |
| <p class="code">try %t = %al:findNextItem(EQ(x,1))
| |
| printtext found t
| |
| printtext {~} = {%t:x}
| |
| catch itemNotFound
| |
| printText None!
| |
| end try
| |
| </p>
| |
|
| |
| The result is:
| |
| <p class="output">CANCELLING REQUEST: MSIR.0750: Class ARRAYLIST, function
| |
| FindNextItem: reference to null object in line xx
| |
| </p>
| |
| To complete this request without cancellation,
| |
| you can use an <var>IsNotNull</var> criterion to bypass Null items:
| |
| <p class="code">try %t = %al:findNextItem(AND(isNotNull, EQ(x,1)))
| |
| printtext found t
| |
| printtext {~} = {%t:x}
| |
| catch itemNotFound
| |
| printText None!
| |
| end try
| |
| </p>
| |
|
| |
| The search finds no matching items, so the <var>Catch</var> clause above catches the
| |
| method's <var>ItemNotFound</var> exception, and the result is:
| |
| <p class="output">None!
| |
| </p>
| |
| <li>Instead of bypassing Null items, you might instead want the search to
| |
| include them:
| |
| <p class="code">try %t = %al:findNextItem(OR(isNull, EQ(x,1)))
| |
| printtext found t
| |
| printtext {~} = {%t:x}
| |
| catch itemNotFound
| |
| printText None!
| |
| end try
| |
| </p>
| |
|
| |
| The Null item is found, but the <var>Try</var> clause <var>[[PrintText statement|PrintText]]</var> invocation
| |
| of <code>%t:x</code> fails, and the result is:
| |
| <p class="output">CANCELLING REQUEST: MSIR.0561: Text output:
| |
| reference to null object in line xx
| |
| </p>
| |
|
| |
| If you want to search exclusively for the next Null item in a collection,
| |
| you can simply use this:
| |
| <p class="code">%t = %al:findNextItem(isNull)
| |
| </p>
| |
| <li>To successfully locate the non-Null item in <code>%al</code>,
| |
| you could use either of the following method calls in the <var>Try</var> clause:
| |
| <p class="code">%t = %al:findNextItem(isNotNull)
| |
| %t = %al:findNextItem(AND(isNotNull, EQ(x,0)))
| |
| </p>
| |
|
| |
| Thanks to the change in the <var>Eq</var> criterion in the second call above,
| |
| the result of trying either of these searches is:
| |
| <p class="output">found t
| |
| %t:x=0
| |
| </p>
| |
| </ol>
| |
|
| |
| ==New intrinsic Float methods: ToDegrees and ToRadians==
| |
| ===ToDegrees===
| |
| This <var>[[Float class|Float]]</var> function converts to angular degrees its floating point argument which is a number of radians.
| |
|
| |
| The syntax of <var>ToDegrees</var> is:
| |
| {{Template:Float:ToDegrees syntax}}
| |
| Where:
| |
| <table class="syntaxTable">
| |
| <tr><th>%number</th>
| |
| <td>A variable to contain the number of degrees of the method object.</td></tr>
| |
| <tr><th>float</th>
| |
| <td>A <var>Float</var> (datatype) value that is the number of radians.</td></tr>
| |
| </table>
| |
| The following example shows the result of several <var>ToDegrees</var> calls:
| |
| <p class="code">begin
| |
| printText {~} = {1:toDegrees}
| |
| printText {~} = {0:toDegrees}
| |
| printText {~} = {0.1:toDegrees}
| |
| printText {~} = {-0.1:toDegrees}
| |
| printText {~} = {3.1415926:toDegrees}
| |
| printText {~} = {$pi:toDegrees}
| |
| end
| |
| </p>
| |
|
| |
| The result is:
| |
| <p class="code">1:toDegrees = 57.2957795130823
| |
| 0:toDegrees = 0
| |
| 0.1:toDegrees = 5.72957795130823
| |
| -0.1:toDegrees = -5.72957795130823
| |
| 3.1415926:toDegrees = 179.999996929531
| |
| $pi:toDegrees = 180
| |
| </p>
| |
| ===ToRadians===
| |
| This <var>Float</var> function converts to radians its floating point argument which is a number of angular degrees.
| |
|
| |
| The syntax of <var>ToRadians</var> is:
| |
| {{Template:Float:ToRadians syntax}}
| |
| Where:
| |
| <table class="syntaxTable">
| |
| <tr><th>%number</th>
| |
| <td>A variable to contain the number of radians of the method object.</td></tr>
| |
| <tr><th>float</th>
| |
| <td>A <var>Float</var> value that is the number of degrees.</td></tr>
| |
| </table>
| |
| The following example shows the result of several <var>ToRadians</var> calls:
| |
| <p class="code">begin
| |
| printText {~} = {57:toRadians}
| |
| printText {~} = {0:toRadians}
| |
| printText {~} = {120:toRadians}
| |
| printText {~} = {-120:toRadians}
| |
| printText {~} = {360:toRadians}
| |
| end
| |
| </p>
| |
|
| |
| The result is:
| |
| <p class="output">57:toRadians = 0.994837673636768
| |
| 0:toRadians = 0
| |
| 120:toRadians = 2.0943951023932
| |
| -120:toRadians = -2.0943951023932
| |
| 360:toRadians = 6.28318530717959
| |
| </p>
| |
|
| |
| ==New Collection methods==
| |
| Seven new methods are added to each of the [[Collections|collection classes]]
| |
| in <var class="product">Sirius Mods</var> Version 7.8.
| |
|
| |
| ===The Sum, Average, Variance, and StandardDeviation methods===
| |
|
| |
| These functions have the same syntax and perform mathematical operations:
| |
|
| |
| <table>
| |
| <tr><th>Sum
| |
| </th><td>Returns the simple sum of the values of the items in the collection.
| |
| </td></tr>
| |
| <tr><th>Average
| |
| </th><td>Returns the average of the values of the items in the collection.
| |
| </td></tr>
| |
| <tr><th>Variance
| |
| </th><td>Returns the "mean standard deviation" of the values of the items in the collection. From statistics, this is the average of the squares of the deviations of the value of each item from the mean of all the items.
| |
| </td></tr>
| |
| <tr><th>StandardDeviation
| |
| </th><td>Returns the standard deviation, the variation from the mean, of the values of the items in the collection. This is the square root of the collection's variance.
| |
| </td></tr></table>
| |
| Here is an example:
| |
| <p class="code">b
| |
| %al is arrayList of float
| |
|
| |
| %al = new
| |
| %al:add(5)
| |
| %al:add(3)
| |
| %al:add(8)
| |
|
| |
| print %al:sum
| |
| print %al:average
| |
| print %al:variance
| |
| print %al:standardDeviation
| |
| end
| |
| </p>
| |
| The result is:
| |
| <p class="output">16
| |
| 5.33333333333333
| |
| 4.22222222222222
| |
| 2.05480466765633
| |
| </p>
| |
| The syntax of the methods is:
| |
| <p class="code">%num = %collectionType:methodName( [method] )
| |
| </p>
| |
| Where:
| |
| <table class=syntaxTable">
| |
| <tr><th>%num</th>
| |
| <td>A <var>Float</var> variable to contain the numeric result.</td></tr>
| |
| <tr><th>%collectionType</th>
| |
| <td>An <var>[[Arraylist class|Arraylist]]</var>, <var>[[NamedArraylist class|NamedArraylist]]</var>, <var>[[FloatNamedArraylist class|FloatNamedArraylist]]</var>, or <var>[[UnicodeNamedArraylist class|UnicodeNamedArraylist]]</var> object variable.</td></tr>
| |
| <tr><th>method</th>
| |
| <td>A function that operates on the type of the items in the collection. It may be a
| |
| [[Local and Common entities#Defining and invoking a local method|local method]]
| |
| or [[Method variables|method variable]] or a class
| |
| member (<var>Variable</var>, <var>Property</var>), and it must return an
| |
| [[Intrinsic classes|intrinsic]] (probably <var>Float</var>) value.
| |
| The default <var class="term">method</var> value is the special identity function, <var>This</var>, which simply returns the item value.</td></tr>
| |
| </table>
| |
| The optional <var class="term">method</var> parameter lets you further manipulate the collection item values
| |
| before performing the requested method's operation.
| |
| If your collection's items are not intrinsic
| |
| values, you must specify a function that can map the item values
| |
| to intrinsic values or the method will fail.
| |
|
| |
| For example, for a collection that is a list of coordinates, you could
| |
| return the average of their distance from the origin by first applying a local function as the <var>Average</var> method's <var class="term">method</var> parameter:
| |
| <p class="code">b
| |
| class point
| |
| public
| |
| constructor new(%x is float, %y is float)
| |
| variable x is float
| |
| variable y is float
| |
| end public
| |
|
| |
| constructor new(%x is float, %y is float)
| |
| %this:x = %x
| |
| %this:y = %y
| |
| end constructor
| |
| end class
| |
|
| |
| local function (point):distance is float
| |
| return (%this:x * %this:x + %this:y * %this:y):squareRoot
| |
| end function
| |
|
| |
| %al is arrayList of object point
| |
|
| |
| %al = new
| |
| %al:add(new(1,1))
| |
| %al:add(new(3,4))
| |
| %al:add(new(-5,12))
| |
|
| |
| print %al:average(distance)
| |
|
| |
| end
| |
| </p>
| |
| The result is <code>6.47140452079103</code>.
| |
|
| |
| ===The CountSubset method===
| |
|
| |
| The <var>CountSubset</var> function returns the number of items in a collection that match a
| |
| specified selection criterion. It is related to the <var>SubsetNew</var> collection mathod, which returns not the count but a collection of the matching items for a specified criterion.
| |
|
| |
| The syntax of the method is:
| |
| <p class="syntax">%num = %collectionType<var class="literal">:CountSubset</var>( criterion )
| |
| </p>
| |
| Where:
| |
| <table class="syntaxTable">
| |
| <tr><th>%num</th>
| |
| <td>A float variable to contain the numeric result.</td></tr>
| |
| <tr><th>%collectionType</th>
| |
| <td>An <var>[[Arraylist class|Arraylist]]</var>, <var>[[NamedArraylist class|NamedArraylist]]</var>, <var>[[FloatNamedArraylist class|FloatNamedArraylist]]</var>, or <var>[[UnicodeNamedArraylist class|UnicodeNamedArraylist]]</var> object variable.</td></tr>
| |
| <tr><th>criterion</th>
| |
| <td>A <var>[[SelectionCriterion class|SelectionCriterion]]</var> object, which is a relational expression that is applied to each collection item value to determine whether the value satisfies the expression. This is a required parameter.</td></tr>
| |
| </table>
| |
| As a simple example, for the <var>ArrayList</var> whose items are the odd integers between 0 and 10, and the selection criterion <code>LT(this, 9))</code>, <var>CountSubset</var> returns <code>4</code>.
| |
|
| |
| ===The MinItem and MaxItem methods===
| |
| The <var>MinItem</var> and <var>MaxItem</var> functions return the minimum and maximum values in a collection. They are related to the <var>Minimum</var> and <var>Maximum</var> collection methods, which return the number or name of the item that has the minimum or maximum value in the collection.
| |
|
| |
| The syntax of these methods is:
| |
| <p class="syntax">%num = %collectionType:methodName( [method] )
| |
| </p>
| |
| Where:
| |
| <table class="syntaxTable">
| |
| <tr><th>%num</th>
| |
| <td>A float variable to contain the numeric result.</td></tr>
| |
| <tr><th>%collectionType</th>
| |
| <td>An <var>[[Arraylist class|Arraylist]]</var>, <var>[[NamedArraylist class|NamedArraylist]]</var>, <var>[[FloatNamedArraylist class|FloatNamedArraylist]]</var>, or <var>[[UnicodeNamedArraylist class|UnicodeNamedArraylist]]</var> object variable.</td></tr>
| |
| <tr><th>method</th>
| |
| <td>A function that operates on the type of the items in the collection. It may be a [[local method]] or [[Method variables|method variable]] or a class member (<var>Variable</var>, <var>Property</var>), and it must return an [[Intrinsic classes|intrinsic]] (probably <var>Float</var>) value. The default <var class="term">method</var> value is the special identity function, <var>This</var>, which simply returns the item value. </td></tr>
| |
| </table>
| |
|
| |
| The optional <var class="term">method</var> parameter lets you further manipulate the collection item values
| |
| before performing the requested method's operation.
| |
| If your collection's items are not intrinsic
| |
| values, you must specify a function that can map the item values
| |
| to intrinsic values or the method will fail.
| |
|
| |
| For the <var>ArrayList</var> <code>%al</code> whose items are the odd integers between 0 and 10, <code>%al:maxItem</code> returns <code>9</code>.
| |
|
| |
| ==New StringTokenizer methods==
| |
| Several new methods are added to the <var>[[StringTokenizer class|StringTokenizer]]</var> class in <var class="product">Sirius Mods</var> Version 7.8.
| |
|
| |
| ===The Separators method===
| |
| This readWrite property introduces another class of characters in the
| |
| <var>StringTokenizer</var> to delimit, or separate, tokens. Prior to this version, only <var>[[Spaces (StringTokenizer property)|Spaces]]</var> and <var>[[TokenChars (StringTokenizer property)|TokenChars]]</var> characters were available to separate tokens.
| |
| The new <var>Separators</var> characters are similar to <var>Spaces</var> and <var>TokenChars</var>, but
| |
| in addition to delimiting tokens, <var>Separators</var> characters:
| |
| <ul>
| |
| <li>do not compress to a single separator (like <var>Spaces</var> characters)
| |
| <li>are not themselves tokens (like <var>TokenChars</var> characters), so are not returned by repeated <var>[[NextToken (StringTokenizer function)|NextToken]]</var> calls
| |
| that encounter consecutive <var>Separators</var> characters
| |
| </ul>
| |
|
| |
| The syntax of the method is:
| |
| <p class="syntax"> %string = %tok<var class="literal">:Separators</var>
| |
|
| |
| %tok<var class="literal">:Separators</var> = %string
| |
| </p>
| |
| Where:
| |
| <table>
| |
| <tr><th>%string
| |
| </th><td>A string variable to contain the returned value of the current separator characters or to be set as the new value(s). The default value for a new tokenizer instance is the null string.
| |
|
| |
| If you are setting <var>Separators</var>, each character in the separator string is a separator, and no character may repeat (except for apostrophe, which may be doubled).
| |
| </td></tr>
| |
| <tr><th>%tok
| |
| </th><td>A <var>StringTokenizer</var> object variable.
| |
| </td></tr></table>
| |
| Separators provide a way to handle consecutive occurrences of the same token delimiter character, for example, in a comma-separated value (csv) file, where they indicate a missing value.
| |
| As an example, the adjacent separators in the token string below
| |
| are detected and returned as nulls by the <var>NextToken</var> method:
| |
| <p class="code"> b
| |
| %toke is object StringTokenizer
| |
| %toke = new(separators=',;')
| |
| %toke:string = '0,1,2,,4,;6'
| |
|
| |
| repeat while %toke:notAtEnd
| |
| printtext {~} = '{%toke:nextToken}'
| |
| end repeat
| |
| end
| |
| </p>
| |
|
| |
| The result is:
| |
| <p class="output"> %toke:nextToken = '0'
| |
| %toke:nextToken = '1'
| |
| %toke:nextToken = '2'
| |
| %toke:nextToken = <nowiki>''</nowiki>
| |
| %toke:nextToken = '4'
| |
| %toke:nextToken = <nowiki>''</nowiki>
| |
| %toke:nextToken = '6'
| |
| </p>
| |
|
| |
| Separators override default and explicitly defined <var>Spaces</var> characters.
| |
| For example, if the only change to the example above is that the tokenizer string is <code>"please, don't go"</code>,
| |
| the result is:
| |
| <p class="output"> %toke:nextToken = 'please'
| |
| %toke:nextToken = 'don't go'
| |
| </p>
| |
|
| |
| The blank after <code>don't</code> does not act as a token delimiter.
| |
|
| |
| '''Note:''' Separators do '''not''' override explicitly defined <var>TokenChars</var> characters. If both separators and token characters are defined, all such characters act as token delimiters.
| |
|
| |
| ===The CompressSpaces, FoldDoubledQuotes, and QuotesBreak methods===
| |
| These readWrite properties all return or set a <var>[[Enumerations#Using Boolean enumerations|Boolean]]</var> value.
| |
|
| |
| ====The CompressSpaces property====
| |
| <var>CompressSpaces</var> compresses the intermediate spaces in a string of whitespace characters.
| |
| For example, consider the following <code>%toke</code> <var>StringTokenizer</var> string, defined with a blank as the whitespace character and with comma as a non-token [[#The Separators method|separator]] character:
| |
| <p class="output"> this, is a compression , example
| |
| </p>
| |
| Without compression, repeated calls of <code>%toke:NextToken</code> strip the leading and trailing whitespace and select the following tokens:
| |
| <p class="output"> this
| |
| is a compression
| |
| example
| |
| </p>
| |
| Without compression, that is, with <var>CompressSpaces</var> set to <var>True</var>, the result is:
| |
| <p class="output"> this
| |
| is a compression
| |
| example
| |
| </p>
| |
| <var>CompressSpaces</var> compresses a token's intermediate whitespace
| |
| to a single whitespace character. If multiple whitespace
| |
| characters are defined, the first character in the <var>Spaces</var> string is the character to which intermediate whitespace is compressed. For example, if <code>Spaces='X '</code>, the token
| |
| <code>'foot ball'</code> will compress to <code>'footXball'</code>.
| |
|
| |
| The <var>CompressSpaces</var> default value is <var>False</var>.
| |
|
| |
| '''Note:''' <var>CompressSpaces</var> affects
| |
| processing only when one or more <var>Separators</var> characters are set, because otherwise a
| |
| token cannot contain internal whitespace.
| |
|
| |
| ====The FoldDoubledQuotes property====
| |
| The practice of doubling an apostrophe ( ' ) to yield a single apostrophe is common in <var class="product">User Language</var> <var>Print</var> statements. For example, the result of <code>Print 'Please, don<nowiki>''</nowiki>t go'</code> is:
| |
| <p class="output"> Please, don't go</p>
| |
| The doubled, or escaped, apostrophe is implicitly folded to a single apostrophe.
| |
| Similarly, if double quotation marks instead of the apostrophes are used to indicate a quoted string (as is [[V7.8 changes affecting all or multiple products#Double quotation marks for quoted strings|allowed]] as of <var class="product>Sirius Mods</var> version 7.8): <code>Print "Please, don""t go"</code>
| |
| The result is: <p class="output"> Please, don"t go</p>
| |
| The escaped double quotation mark is implicitly folded to one double quotation mark.
| |
|
| |
| The <var>StringTokenizer</var>, however, does not perform this implicit folding if it encounters a doubled <var>[[Quotes (StringTokenizer property)|Quotes]]</var> character within a quoted region. For example:
| |
| <p class="code">b
| |
| %toke is object StringTokenizer
| |
| %toke = new(quotes='"')
| |
| %toke:string = '"Please, don""t go"'
| |
|
| |
| repeat while %toke:notAtEnd
| |
| printtext {~} = '{%toke:nextToken}'
| |
| end repeat
| |
| end
| |
| </p>
| |
| The result of this request is:
| |
| <p class="output">%toke:nextToken = 'Please, don'
| |
| %toke:nextToken = 't go'
| |
| </p>
| |
| To provide for cases where you might expect or want implicit folding of a doubled <var>Quotes</var> character, version 7.8 adds the <var>FoldDoubledQuotes</var> property to the <var>StringTokenizer</var> class.
| |
| If the <var>FoldDoubledQuotes</var> property is set to <var>True</var> (this is not the default), the tokenizer considers two adjacent <var>Quotes</var> characters within a quoted region ''that is begun by the same <var>Quotes</var> character'' to be an escape sequence for a single quotation character, and the result of tokenizing <code>%toke:string = '"Please, don""t go"'</code> from the previous request is:
| |
| <p class="output"> Please, don"t go</p>
| |
|
| |
| The syntax of the <var>FoldDoubledQuotes</var> method is:
| |
| <p class="syntax"> %bool = %tok<var class="literal">:FoldDoubledQuotes</var>
| |
|
| |
| %tok<var class="literal">:FoldDoubledQuotes =</var> %bool
| |
| </p>
| |
| Where:
| |
| <table>
| |
| <tr><th>%bool
| |
| </th><td>An enumeration object of type <var>[[Boolean enumeration|Boolean]]</var> to contain or set the value of <var>FoldDoubledQuotes.</var> The default value for a new tokenizer instance is <var>False</var>.
| |
| </td></tr>
| |
| <tr><th>%tok
| |
| </th><td>A <var>StringTokenizer</var> object variable.
| |
| </td></tr></table>
| |
| | |
| ==Aliases for class names==
| |
| As of <var class="product">Sirius Mods</var> Version 7.8, you can define an alias name for an existing user class.
| |
| You do so by specifying an <var>Alias</var> parameter setting on the existing class declaration. For example,
| |
| you are changing a naming convention for some code, and you want to refer to user-defined class <code>Blue</code> by another name, say <code>Indigo</code>. Your class declaration would be:
| |
| <p class="code">class blue alias indigo
| |
| </p>
| |
| You can then use either the primary class name or the alias when declaring objects of the class:
| |
| <p class="code">%foo is object blue
| |
| %bar is object indigo
| |
| </p>
| |
| An object of the alias class is compiled as an object
| |
| of the primary class, and the runtime class of an
| |
| object variable that was defined using an alias is the primary class.
| |
| Consequently, all system messages you receive will specify the primary class.
| |
|
| |
| For example, given the declarations above, if you call method <code>TouchUp</code> for an object declared for the Indigo class:
| |
| <p class="code">%bar:touchUp
| |
| </p>
| |
| And method <code>TouchUp</code> does not exist in the class, the error message you receive is:
| |
| <p class="code">MSIR.0733: Member TOUCHUP not found in class Blue
| |
| </p>
| |
| While this might seem potentially confusing, aliases are intended primarily for migrating class names, so any confusion will be limited to this migration period. In addition, only the owner of a class can declare an alias, so aliases are not likely to proliferate in your site's code.
| |
|
| |
| Should it ever be necessary, you may also specify multiple aliases:
| |
| <p class="code">class blue alias indigo and ultramarine and navy
| |
| </p>
| |
| You may declare a user-defined class with an alias name that matches the name of a system class.
| |
|
| |
| ==Success block added to exception catching==
| |
| You use a <var>Try/Catch</var> statement block to catch a thrown <var class="product">User Language</var> exception. For example, the following block catches an <var>InvalidSortSpecification</var> exception thrown by a <var>Stringlist</var> <var>Sort</var> statement:
| |
| <p class="code">[[Try statement|try]] %strlist:sort(%sortSpec)
| |
| catch invalidSortSpecification
| |
| Print 'Invalid sort spec'
| |
| end try
| |
| </p>
| |
| | |
| However, in more complex cases, opportunity for confusion exists if you want to execute additional statements after a <var>Try</var> statement if it produces no exceptions:
| |
| <p class="code">try
| |
| <a>...
| |
| <b>...
| |
| <c>...
| |
| <d>...
| |
| <e>...
| |
| catch foo
| |
| <x>...
| |
| catch bar
| |
| <y>...
| |
| catch another
| |
| <z>...
| |
| end try
| |
| </p>
| |
| | |
| The problem is that there's no way to know that <code><b></code>, <code><c></code>, <code><d></code>, and <code><e></code> can't throw an exception that might be one of the caught exceptions. In fact they might,
| |
| but you might not expect an exception from any of them in this context. There
| |
| seems no good way of preventing the catches to be in effect for them.
| |
| | |
| But as of <var class="product">Sirius Mods</var> Version 7.8, you can use a <var>Success</var> block to make it clear that the catches apply to statement <code><a></code> and do '''not''' apply to <code><b></code>, <code><c></code>, <code><d></code>, and <code><e></code>:
| |
| | |
| <p class="code">try
| |
| <a>...
| |
| success
| |
| <b>...
| |
| <c>...
| |
| <d>...
| |
| <e>...
| |
| catch foo
| |
| <x>...
| |
| catch bar
| |
| <y>...
| |
| catch another
| |
| <z>...
| |
| end try
| |
| </p>
| |
| | |
| The principle benefits of the <var>Success</var> statement are:
| |
| <ul>
| |
| <li>It makes it clear in the code which statement is expected to produce the exceptions being caught.
| |
| <li>It prevents a catch from accidentally catching an exception from a statement that didn't really expect that exception.
| |
| </ul>
| |
| | |
| You can also reverse the order of the the <var>Success</var> and catches:
| |
| | |
| <p class="code">try
| |
| <a>...
| |
| catch foo
| |
| <x>...
| |
| catch bar
| |
| <y>...
| |
| catch another
| |
| <z>...
| |
| success
| |
| <b>...
| |
| <c>...
| |
| <d>...
| |
| <e>...
| |
| end try
| |
| </p>
| |
| ==New common enumeration method: FromString==
| |
| <var class="product">Sirius Mods</var> Version 7.8 adds the <var>[[Enumerations#FromString function|FromString]]</var> shared function as a method common to all system and user-defined enumerations. <var>FromString</var> converts a string argument into a value of the specified enumeration type.
| |
| This is the opposite of an enumeration <var>ToString</var> method, which converts an enumeration value to its <var>String</var> representation.
| |
|
| |
| As an example, consider the following user-defined enumeration:
| |
| <p class="code">enumeration Animal
| |
| public
| |
| value cat
| |
| value dog
| |
| value gecko
| |
| value parrot
| |
| end public
| |
| end enumeration
| |
| </p>
| |
| You can populate an <code>Animal</code> enumeration variable with one of the <code>Animal</code> enumeration values by making a call to <var>FromString</var>:
| |
| <p class="code">%pet is enumeration animal
| |
| %pet = fromString('gecko')
| |
| </p>
| |
| The result of a <var>Print</var> of <code>%pet</code> above is <code>gecko</code>. In the method call, <code>fromString</code> does '''not''' have to be preceded by <code>%(Animal):</code> to identify the type of enumeration, because the <var>FromString</var> method is automatically available for any <var class="product">User Language</var> enumeration, system or user-defined.
| |
|
| |
| Only strings that match a value of the particular enumeration type
| |
| can be converted. If a string cannot be converted to an enumeration
| |
| value, <var>FromString</var> throws an <var>[[InvalidValue class|InvalidValue]]</var> exception:
| |
| <p class="code">%pet = fromString('alien')
| |
|
| |
| <nowiki>***</nowiki> 1 CANCELLING REQUEST: MSIR.0750: Class Animal, function
| |
| FromString: InvalidValue exception: ALIEN is not a valid enumeration
| |
| value in line 84, procedure ENUM, file MYPROC
| |
| </p>
| |
| | |
| | |
| {{Template:Content index: V7.8 Release Notes}}
| |