Janus SOAP ULI V7.8 changes: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (added FromString method)
m (Content removed to M2o4Int page of same name)
 
(100 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{Hierarchy header}}
Content moved to M204Int, but history preserved here.
 
The following sections describe changes in the [[Janus SOAP User Language Interface|Janus SOAP ULI]]
in this release.
 
==New arguments for Record class ToXmlDoc method==
The [[ToXmlDoc]] method in the Record class has the following new
arguments:
<dl>
<dt><b>CodepageTable= </b><i>bool</i>
<dd>This Boolean argument, which defaults to <tt>False</tt>,
specifies whether to use the base codepage
translation table when creating the XmlDoc.
For more details, see the description of the <tt>CodepageTable=False|True</tt> argument in [[Janus SOAP XmlDoc API V7.8 changes#LoadFromRecord subroutine in XmlDoc and XmlNode classes|LoadFromRecord]].
Note that this argument was actually introduced in version 7.6 of
the ''Sirius Mods''.
<dt><b>AllowNull=</b><i> bool</i>
<dd>The value of this Boolean argument, which defaults to <tt>False</tt>,
is copied to the AllowNull property of the XmlDoc created by ToXmlDoc.
The XmlDoc's AllowNull property, in turn, determines whether field values that contain the X'00' character are stored in the
XmlDoc with base64 encoding. Such values are base64 encoded if AllowNull is <tt>False</tt>.
For more information, see the description of the <tt>AllowNull=</tt> argument in [[Janus SOAP XmlDoc API V7.8 changes#NewFromRecord shared function in XmlDoc class|NewFromRecord]].
Note that this argument was actually introduced in version 7.7 of the ''Sirius Mods''.
</dl>
 
==Field references in Record class CurrentRecord methods==
For methods declared with a CurrentRecord attribute, it was the case under ''Sirius Mods'' 7.7 that field references were an exception to the following rule:
<br>
''Statements within the method definition, even a CurrentRecord method call, may reference the record without having to be wrapped inside a record For loop.''
Under ''Sirius Mods'' 7.8, field references are no longer an exception to this rule.
You may reference a record field from within a method declared with
CurrentRecord without being inside a record For loop.
For example, for the field COLOR,
the <tt>For Record currentRecord</tt> and <tt>End For</tt>
statements containing the
<tt>print COLOR</tt> statement in the method definition below
may be discarded under ''Sirius Mods'' 7.8:
<pre>
    local subroutine (Record in file myproc):printField currentRecord in file myproc
      for record currentRecord
          print COLOR
      end for
    end subroutine
</pre>
 
==New exception class: BadJournal==
The BadJournal exception class reports
errors in CCAJRNL or CCAJLOG datasets or streams, including naming errors.
The [[New]] method of the [[Journal]] system class is the
system method that automatically throws a BadJournal exception.
The following example shows a Try and Catch of a Journal class, New method,
exception. An invalid journal name is specified to generate the BadJournal 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 Stringlist AppendJournalData method does not cancel if its Journal
parameter is null.
The request result shows the reason code (ReasonCode 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 BadJournal class are described in the following subsections.
===New constructor===
This constructor generates an instance of a BadJournal exception.
As shown below, the optional argument of the New method is a setting of
the ReasonCode property.
 
====New constructor syntax====
  [%bdJrnl =] [%(BadJournal):] New(ReasonCode=num)
===ReasonCode property===
This readOnly property returns a numeric reason code that indicates the
cause of the BadJournal exception.
====ReasonCode syntax====
  %rc = %bdJrnl:ReasonCode
Possible reason codes are:
<dl>
<dt>1
<dd>Either the dataset or stream name is invalid, or the journal is invalid.
<dt>2
<dd>The dataset or stream is empty.
<dt>3
<dd>The journal was created with a different ''Model 204'' version than the
current Online.
<dt>4
<dd>A merged journal is invalid.
</dl>
 
==Enhancement to exception handling: Success blocks==
Exception Try/Catch support is enhanced in Version 7.8 by the addition of Success blocks.
In cases where a Try block contains multiple statements, a                               
Success 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 <a> and, if no exceptions get Thrown,                         
you want to do statements <nowiki><b></nowiki>, <c>, <d>, <e>, and <f>.                                   
Otherwise, if statement <a> throws an exception,                                         
you want to do statements <x>, <y>, or <z>, depending on the exception.                 
                                                                                         
You code your Try/Catch block like this:
<pre>
  try           
    <a>         
    <b>         
    <c>         
    <d>         
    <e>         
    <f>         
  catch foo     
    <x>         
  catch bar     
    <y>         
  catch whatever
    <z>         
  end try
</pre>
 
If statement <a> does indeed throw an exception, statements <nowiki><b></nowiki> through <f>             
do not run, and the appropriate Catch statement takes affect.                           
However, if statement <a> does not throw an exception,                                   
there might be no way to know that statement <nowiki><b></nowiki>, <c>, <d>, <e>, or <f> might
throw an exception that is one of the exceptions in the subsequent Catch 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 Sirius Mods, there was                                               
no good way of preventing the catches to also be in effect for these statements         
as well as for statement <a>.                                                           
                                                                                         
As of ''Sirius Mods'' 7.8, a Success block inside the Try block                         
resolves the problem by making it clear that the Catches do not apply to                 
statements <nowiki><b></nowiki>, <c>, <d>, <e>, and <f>:
<pre>
  try         
    <a>       
  success     
    <b>       
    <c>       
    <d>       
    <e>       
    <f>       
  catch foo   
    <x>       
  catch bar   
    <y>       
  catch whatever
    <z>       
  end try
</pre>
 
A Success block may come before or after the Catch blocks:
<pre>
  try           
    <a>         
  catch foo     
    <x>         
  catch bar     
    <y>         
  catch whatever
    <z>         
  success       
    <b>         
    <c>         
    <d>         
    <e>         
    <f>         
  end try
</pre>
 
==New SelectionCriterion methods: IsNull and IsNotNull==
These shared methods take no parameters and create a new [[SelectionCriterion]] object.
The methods provide control for Null objects in the [[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 IsNull criterion selects a collection item if the item is a Null object;
an IsNotNull criterion selects an item objects if it is not Null.
The syntax of the methods follows:
  %selc = IsNull
  %selc = IsNotNull
The examples below test a variety of searches against
arraylist <tt>%al</tt> of objects of class <tt>T</tt>:
<pre>
    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)
</pre>
<ol>
<li>The Arraylist class [[FindNextItem]] method, which throws an exception
if its selection criterion
matches no item, fails in the Try 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:
<pre>
    try  %t = %al:findNextItem(EQ(x,1))
      printtext found t
      printtext {~} = {%t:x}
    catch itemNotFound
      printText None!
    end try
</pre>
The result is:
<pre>
    CANCELLING REQUEST: MSIR.0750: Class ARRAYLIST, function
      FindNextItem: reference to null object in line xx
</pre>
To complete this request without cancellation,
you can use an IsNotNull criterion to bypass Null items:
<pre>
    try  %t = %al:findNextItem(AND(isNotNull, EQ(x,1)))
      printtext found t
      printtext {~} = {%t:x}
    catch itemNotFound
      printText None!
    end try
</pre>
The search finds no matching items, so the Catch clause above catches the
method's ItemNotFound exception, and the result is:
<pre>
    None!
</pre>
<li>Instead of bypassing Null items, you might instead want the search to
include them:
<pre>
    try  %t = %al:findNextItem(OR(isNull, EQ(x,1)))
      printtext found t
      printtext {~} = {%t:x}
    catch itemNotFound
      printText None!
    end try
</pre>
The Null item is found, but the Try clause PrintText invocation
of <tt>%t:x</tt> fails, and the result is:
<pre>
    CANCELLING REQUEST: MSIR.0561: Text output:
      reference to null object in line xx
</pre>
If you want to search exclusively for the next Null item in a collection,
you can simply use this:
<pre>
    %t = %al:findNextItem(isNull)
</pre>
<li>To successfully locate the non-Null item in <tt>%al</tt>,
you could use either of the following method calls in the Try clause:
<pre>
    %t = %al:findNextItem(isNotNull)
    %t = %al:findNextItem(AND(isNotNull, EQ(x,0)))
</pre>
Thanks to the change in the EQ criterion in the second call above,
the result of trying either of these searches is:
<pre>
    found t
    %t:x=0
</pre>
</ol>
 
==New intrinsic Float methods: ToDegrees and ToRadians==
===ToDegrees===
This [[Float class|Float]] function converts to angular degrees its floating point argument which is a number of radians.
 
The syntax of ToDegrees is:
  %deg = number:toDegrees
 
where:
 
''%deg'' is a variable to contain the number of degrees of the method object.
 
''number'' is a Float value that is the number of radians.
 
The following example shows the result of several ToDegrees calls:
  begin                               
  printText {~} = {1:toDegrees}       
  printText {~} = {0:toDegrees}       
  printText {~} = {0.1:toDegrees}     
  printText {~} = {-0.1:toDegrees}   
  printText {~} = {3.1415926:toDegrees}
  printText {~} = {$pi:toDegrees}                                       
  end                                 
 
The result is:
 
  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 
                 
===ToRadians===
This Float function converts to radians its floating point argument which is a number of angular degrees.
 
The syntax of ToRadians is:
  %rad = number:toRadians
 
where:
 
''%rad'' is a variable to contain the number of radians of the method object.
 
''number'' is a Float value that is the number of degrees.
 
The following example shows the result of several ToRadians calls:
  begin                               
  printText {~} = {57:toRadians} 
  printText {~} = {0:toRadians}
  printText {~} = {120:toRadians}
  printText {~} = {-120:toRadians}
  printText {~} = {360:toRadians}
  end                                 
 
The result is:
 
  57:toRadians = 0.994837673636768
  0:toRadians = 0 
  120:toRadians = 2.0943951023932
  -120:toRadians = -2.0943951023932
  360:toRadians = 6.28318530717959
     
==New Collection methods==
Seven new methods are added to each of the [[collection classes]] in ''Sirius Mods'' Version 7.8.
 
===The Sum, Average, Variance, and StandardDeviation methods===
 
These functions have the same syntax and perform mathematical operations:     
                                                                                           
<dl>                                                                                       
<dt>Sum                                                                                     
<dd>Returns the simple sum of the values of the items in the collection.                   
<dt>Average                                                                                 
<dd>Returns the average of the values of the items in the collection.                       
<dt>Variance                                                                               
<dd>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.                                         
<dt>StandardDeviation                                                                       
<dd>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.       
</dl>
Here is an example:                                   
                                                       
  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                                                 
                                                       
The result is:                                         
                                                       
  16                                                 
  5.33333333333333                                   
  4.22222222222222                                   
  2.05480466765633                                   
                                                       
The syntax of the methods is:                         
  %num = %collectionType:methodName( [function] )       
                                                       
Where:                                                 
                                                       
''%num'' is a float variable to contain the numeric result.   
 
''%collectionType'' is an [[ArrayList class|ArrayList]], [[NamedArrayList class|NamedArrayList]], [[FloatNamedArrayList class|FloatNamedArrayList]],or [[UnicodeNamedArrayList  class|UnicodeNamedArrayList]] object variable.       
                                                                                         
''function'' is a function that operates on the type of                                     
the items in the collection. It may be a [[local method]] or [[method variable]] or a class     
member (variable, property), and it must return an [[intrinsic]] (probably float) value. The
default ''function'' value is the special identity function, <tt>This</tt>, which simply returns the item value.     
                                                                                         
The optional ''function'' 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 Average method's ''function'' parameter:
                                                                 
  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
 
The result is <tt>6.47140452079103</tt>.
 
===The CountSubset method===
 
The CountSubset function returns the number of items in a collection that match a
specified selection criterion. It is related to the SubsetNew collection mathod, which returns not the count but a collection of the matching items for a specified criterion.
 
The syntax of the method is:                         
  %num = %collectionType:CountSubset( criterion )       
                                                       
Where:
                                                       
''%num'' is a float variable to contain the numeric result.   
 
''%collectionType'' is an ArrayList, NamedArrayList, FloatNamedArrayList,or UnicodeNamedArrayList object variable.
                                                                                         
''criterion'' is a [[SelectionCriterion]] 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.
As a simple example, for the ArrayList whose items are the odd integers between 0 and 10, and the selection criterion <tt>LT(this, 9))</tt>, CountSubset returns <tt>4</tt>.
 
===The MinItem and MaxItem methods===
The MinItem and MaxItem functions return the minimum and maximum values in a collection. They are related to the Minimum and Maximum 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:
    %num = %collectionType:methodName( [function] ) 
 
Where:
                                                       
''%num'' is a float variable to contain the numeric result.   
 
''%collectionType'' is an ArrayList, NamedArrayList, FloatNamedArrayList,or UnicodeNamedArrayList object variable.
 
''function'' is a function that operates on the type of                                     
the items in the collection. It may be a [[local method]] or [[method variable]] or a class     
member (variable, property), and it must return an [[intrinsic]] (probably float) value. The
default ''function'' value is the special identity function, <tt>This</tt>, which simply returns the item value. 
 
The optional ''function'' 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 ArrayList <tt>%al</tt> whose items are the odd integers between 0 and 10, <tt>%al:maxItem</tt> returns <tt>9</tt>.
 
==Aliases for class names==
As of ''Sirius Mods'' Version 7.8, you can define an alias name for an existing user class.
You do so by specifying an <tt>Alias</tt> 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 <tt>Blue</tt> by another name, say <tt>Indigo</tt>. Your class declaration would be:             
                                                                           
    class blue alias indigo
 
You can then use either the primary class name or the alias when declaring objects of the class: 
 
    %foo    is object blue
    %bar    is object indigo
 
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 <tt>TouchUp</tt> for an object declared for the Indigo class:                                                         
                                                                               
    %bar:touchUp               
                                                                               
And method TouchUp does not exist in the class, the error message you receive is:
                                                                               
    MSIR.0733: Member TOUCHUP not found in class Blue                       
                                                                               
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:
 
    class blue alias indigo and ultramarine and navy                                   
 
You may declare a user-defined class with an alias name that matches the name of a system class.
 
==New common enumeration method: FromString==
''Sirius Mods'' Version 7.8 adds the FromString shared function as a method common to all system and user-defined enumerations. FromString converts a string argument into a value of the specified enumeration type.
This is the opposite of an enumeration ToString method, which converts an enumeration value to its String representation.
 
As an example, consider the following user-defined enumeration:
 
  enumeration Animal         
      public                 
        value cat           
        value dog           
        value gecko         
        value parrot       
      end public             
  end enumeration           
You can populate an Animal enumeration variable with one of the Animal enumeration values by making a call to FromString:           
                                                                               
  %pet is enumeration animal
  %pet = fromString('gecko')                                                     
The result of a Print of <tt>%pet</tt> above is <tt>gecko</tt>. In the method call, <tt>fromString</tt> does '''not''' have to be preceded by <tt>%(Animal):</tt> to identify the type of enumeration, because the FromString method is automatically available for any User Language 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, FromString throws an [[InvalidValue exception]]:                                     
                                                                               
  %pet = fromString('alien')                                                     
                                                                               
  ***  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                                 
 
{{Hierarchy footer}}

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"