Janus SOAP ULI V7.8 changes: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (Content removed to M2o4Int page of same name)
 
(7 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 class="product">[[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 class|PersistentObjectInfo]]</var> class, which contains information about a [[Global and session objects|global or session object]] in the current thread.
<var>PersistentObjectInfo</var>
objects offer the advantage of the sorting, finding, and subsetting facilities of
collections.
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.
===Creating PersistentObjectInfo objects===
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.
Probably the most common way of creating <var>PersistentObjectInfo</var> objects is using
the <var>[[GlobalList (PersistentObjectInfo function)|GlobalList]]</var> and <var>[[SessionList (PersistentObjectInfo function)|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.
===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, instead of a declaration like this one:
<p class="code">%persInfoList is arraylist of object persistentObjectInfo </p>
You can simply specify:
<p class="code">%persInfoList is type persistentObjectInfoList</p>
 
'''Note:''' The keyword <var>Type</var> is required.
 
===The GlobalList and SessionList Object class methods===
In addition to belonging to the <var>PersistentObjectInfo</var> class, the <var>GlobalList</var> and <var>SessionList</var> methods 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>
 
==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>
==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 intrinsic methods==
 
===ToDegrees, ToRadians, and StringTokenizer===
 
====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>
 
====StringTokenizer====
The <var>[[String class|String]]</var> class <var>[[StringTokenizer (String function)|StringTokenizer]]</var> function
returns a new instance of a <var>StringTokenizer</var> object using the method object string as the tokenizer string.
 
The <var>StringTokenizer</var> syntax is:
{{Template:String:StringTokenizer syntax}}
 
where:
<table class="syntaxTable">
<tr><th>%stringTokenizer</th>
<td>A <var>StringTokenizer</var> object expression to contain the new object instance. </td></tr>
 
<tr><th>string</th>
<td>The string to be tokenized.</td></tr>
 
<tr><th><var>TokenChars</var></th>
<td>This name required string argument <var>TokenChars</var> is a set of single-character token-delimiters (delimiters that are also tokens) that may be separated by whitespace characters.</td></tr>
<tr><th><var>Spaces</var></th>
<td>This name required string argument <var>Spaces</var> is a set of "whitespace" characters, that is, characters that separate tokens.
<tr><th><var>Quotes</var></th>
<td>This name required string argument <var>Quotes</var> is a set of quotation characters. </td></tr>
</table>
 
===Date/time conversion methods===
These new date conversion methods correspond to the <var>$Sir_Date2N*</var> group and to the <var>$Sir_N*2Date</var> group.
 
<var>String</var> class:
<ul>
<li><var>[[StringToSeconds (String function)|StringToSeconds]]</var>
<li><var>[[StringToDays (String function)|StringToDays]]</var>
<li><var>[[StringToMilliseconds (String function)|StringToMilliseconds]]</var>
</ul>
 
<var>Float</var> class:
<ul>
<li><var>[[SecondsToString (Float function)|SecondsToString]]</var>
<li><var>[[DaysToString (Float function)|DaysToString]]</var>
<li><var>[[MillisecondsToString (Float function)|MillisecondsToString]]</var>
</ul>
 
==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 (SelectionCriterion function)|IsNull]]</var> criterion selects a collection item if the item is a Null object;
an <var>[[IsNotNull (SelectionCriterion function)|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 Stringlist class methods==
<var>[[AppendFieldValues (Stringlist function)|AppendFieldValues]]</var> and <var>[[AppendFieldImages (Stringlist function)|AppendFieldImages]]</var> are new <var>Stringlist</var> variants of <var>[[$Field_List]]</var> and <var>[[$Field_ListI]]</var>. <var>AppendFieldValues</var> has the same       
parameters as <var>$Field_list</var> except they are all <var>NameRequired</var>. <var>AppendFieldImages</var> has the same parameters as <var>$Field_listI</var> except they are <var>NameRequired</var> parameters.
 
==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>
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 (StringTokenizer property)|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>.
 
====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 (StringTokenizer property)|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 QuotesBreak property====
<var>[[QuotesBreak (StringTokenizer property)|QuotesBreak]]</var> determines whether quotes are considered     
boundaries of tokens. The string <code>peanut"butter"</code> will tokenize to <code>peanut</code> and
<code>butter</code> when <var>QuotesBreak</var> is true. Otherwise it will tokenize to <code>peanutbutter</code>
(assuming <var>[[RemoveQuotes (StringTokenizer property)|RemoveQuotes]]</var> is set). <var>QuotesBreak</var> is <var>True</var> by default.
 
===The PreviousChar, PeekPreviousChar, and StringUpTo methods===
<var>[[PreviousChar (StringTokenizer function)|PreviousChar]]</var> returns the value of the character that precedes the character that is at the tokenizing position, and it steps the tokenizing position back to the preceding character.
 
<var>[[PeekPreviousChar (StringTokenizer function)|PeekPreviousChar]]</var> returns the value of the character that precedes the character that is at the tokenizing position. It does not change the tokenizing position.
 
<var>[[StringUpTo (StringTokenizer function)|StringUpTo]]</var> advances the 
tokenizer position past the next occurrence of its argument string, and it returns a
substring of the tokenizing string, starting at the current position 
and ending just before the occurrence of its argument string.
 
==New System class methods==
The <var>[[LastSubsystemErrorFile (System function)|LastSubsystemErrorFile]]</var>, <var>[[LastSubsystemErrorSubsystem (System function)|LastSubsystemErrorSubsystem]]</var>, and <var>[[LastSubsystemErrorProcedure (System function)|LastSubsystemErrorProcedure]]</var>
methods return information about the invoked procedure that forced transfer to the APSY error procedure.
 
These date retrieval methods corresponding to the <var>[[$Sir_DateN*]]</var> group and to <var>[[$Sir_Date]]</var>:
<ul>
<li><var>[[CurrentTimeMilliseconds (System function)|CurrentTimeMilliseconds]]</var>
<li><var>[[CurrentTimeSeconds (System function)|CurrentTimeSeconds]]</var>
<li><var>[[CurrentTimeDays (System function)|CurrentTimeDays ]]</var>
<li><var>[[CurrentTimeString (System function)|CurrentTimeString ]]</var>
</ul>
 
==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>[[Exceptions#Try and Catch|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 %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>...
  &lt;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>&lt;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>&lt;b></code>, <code><c></code>, <code><d></code>, and <code><e></code>:
 
<p class="code">try
  <a>...
success
  &lt;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
  &lt;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>
 
==Enumeration comparisons==
The <var>SelectionCriterion</var> <var>[[Eq (SelectionCriterion function)|Eq]]</var> and <var>[[Ne (SelectionCriterion function)|Ne]]</var> methods now allow equality and inequality tests for [[enumerations|enumerations]] so that you can do something like:<p class="code">%suspects = %villagers:subsetNew(or(eq(evil, true), ne(nationality, usa))) </p>
where <code>Nationality</code> is an enumeration. Enumeration comparisons are not allowed in any other <var>SelectionCriterion</var> methods.
 
==Enumeration attributes and attribute inverses==
[[Enumerations#User Language enumerations|User Language enumeration]] support now includes [[Enumerations#The Enumeration block|enumeration attributes]]. These are constant data (types <var>String</var>, <var>Float</var>, and <var>Enumeration</var> are supported) that can be attached to enumeration values. Here's an example:       
<p class="code">enumeration coffee
    public
      attribute oz is float
      attribute price is float
 
      value tall (oz=12, price=2.99)
      value grande (oz=16, price=3.99)
      value venti (price=4.99, oz=20)
    end public
end enumeration
 
%order is enumeration coffee
%order = venti               
 
printtext {~} = {%order:price}  </p>           
                                           
The result is:
<p class="code">%order:price = 4.99 </p>
 
New generic [[Enumerations#Inverse attribute methods|inverse attribute methods]] return an enumeration value based on the value of one of
its attributes. You do this by declaring an "inverse" method after an attribute declaration. The <code>fromOz</code> method below is an example:
<p class="code">enumeration coffee                                                     
    public
      attribute oz is float inverse fromOz 
 
      value tall  (12)
      value grande (16)
      value venti  (20)
    end public 
end enumeration           
 
%order is enumeration coffee
 
%order = fromOz(16) 
Print %order
</p>
<p>
The result is: </p>
<p class="code">grande</p>
 
==Anonymous functions==
[[Method variables#Anonymous functions|Anonymous functions]] are methods whose definition you specify but do not bind to a specific name. Typically, you define such a method in the context in which it is actually used.
 
{{Template:Content index: V7.8 Release Notes}}

Latest revision as of 21:38, 17 October 2013

Content moved to M204Int, but history preserved here.

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=Janus_SOAP_ULI_V7.8_changes&oldid=65437"