|
|
| (107 intermediate revisions by 5 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 subroutine in XmlDoc and XmlNode classes]].
| |
|
| |
| 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 shared function in XmlDoc class]].
| |
|
| |
| 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 is no way to know that statement <nowiki><b></nowiki>, <c>, <d>, <e>, and <f> might not
| |
| throw an exception that might be 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
| |
|
| |
| {{Hierarchy footer}}
| |