|
|
| (103 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: Sum, Average, Variance, StandardDeviation==
| |
| | |
| Four new methods are added to each of the collection classes in ''Sirius Mods'' Version 7.8.
| |
| They are functions that have the same syntax and that 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 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>.
| |
| | |
| {{Hierarchy footer}}
| |