Janus SOAP ULI V7.8 changes: Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
Line 115: Line 115:
<dd>A merged journal is invalid.
<dd>A merged journal is invalid.
</dl>
</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==
==New SelectionCriterion methods: IsNull and IsNotNull==
These shared methods take no parameters and create a new [[SelectionCriterion]] object.
These shared methods take no parameters and create a new [[SelectionCriterion]] object.

Revision as of 04:53, 14 December 2010

{{#hierarchy-top:}}

The following sections describe changes in the 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:

CodepageTable= bool
This Boolean argument, which defaults to False, specifies whether to use the base codepage translation table when creating the XmlDoc. For more details, see the description of the CodepageTable=False|True argument in LoadFromRecord subroutine in XmlDoc and XmlNode classes. Note that this argument was actually introduced in version 7.6 of the Sirius Mods.
AllowNull= bool
The value of this Boolean argument, which defaults to False, 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 False. For more information, see the description of the AllowNull= argument in NewFromRecord shared function in XmlDoc class. Note that this argument was actually introduced in version 7.7 of the Sirius Mods.

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:
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 For Record currentRecord and End For statements containing the print COLOR statement in the method definition below may be discarded under Sirius Mods 7.8:

    local subroutine (Record in file myproc):printField currentRecord in file myproc
       for record currentRecord
           print COLOR
       end for
    end subroutine

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:

    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

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:

    %journal = new('OLD~RNL') is: Failure!!! Reason code is: 1
    0
    0

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:

1
Either the dataset or stream name is invalid, or the journal is invalid.
2
The dataset or stream is empty.
3
The journal was created with a different Model 204 version than the current Online.
4
A merged journal is invalid.

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 <b>, <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:

   try            
     <a>          
     <b>          
     <c>          
     <d>          
     <e>          
     <f>          
   catch foo      
     <x>          
   catch bar      
     <y>          
   catch whatever 
     <z>          
   end try 

If statement <a> does indeed throw an exception, statements <b> 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 <b>, <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 <b>, <c>, <d>, <e>, and <f>:

   try           
     <a>         
   success       
     <b>         
     <c>         
     <d>         
     <e>         
     <f>         
   catch foo     
     <x>         
   catch bar     
     <y>         
   catch whatever
     <z>         
   end try 

A Success block may come before or after the Catch blocks:

   try            
     <a>          
   catch foo      
     <x>          
   catch bar      
     <y>          
   catch whatever 
     <z>          
   success        
     <b>          
     <c>          
     <d>          
     <e>          
     <f>          
   end try 

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 %al of objects of class T:

    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)
  1. 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:
        try  %t = %al:findNextItem(EQ(x,1))
           printtext found t
           printtext {~} = {%t:x}
        catch itemNotFound
           printText None!
        end try
    

    The result is:

        CANCELLING REQUEST: MSIR.0750: Class ARRAYLIST, function
           FindNextItem: reference to null object in line xx
    

    To complete this request without cancellation, you can use an IsNotNull criterion to bypass Null items:

        try  %t = %al:findNextItem(AND(isNotNull, EQ(x,1)))
           printtext found t
           printtext {~} = {%t:x}
        catch itemNotFound
           printText None!
        end try
    

    The search finds no matching items, so the Catch clause above catches the method's ItemNotFound exception, and the result is:

        None!
    
  2. Instead of bypassing Null items, you might instead want the search to include them:
        try  %t = %al:findNextItem(OR(isNull, EQ(x,1)))
           printtext found t
           printtext {~} = {%t:x}
        catch itemNotFound
           printText None!
        end try
    

    The Null item is found, but the Try clause PrintText invocation of %t:x fails, and the result is:

        CANCELLING REQUEST: MSIR.0561: Text output:
           reference to null object in line xx
    

    If you want to search exclusively for the next Null item in a collection, you can simply use this:

        %t = %al:findNextItem(isNull)
    
  3. To successfully locate the non-Null item in %al, you could use either of the following method calls in the Try clause:
        %t = %al:findNextItem(isNotNull)
        %t = %al:findNextItem(AND(isNotNull, EQ(x,0)))
    

    Thanks to the change in the EQ criterion in the second call above, the result of trying either of these searches is:

        found t
        %t:x=0
    

New intrinsic Float methods: ToDegrees and ToRadians

ToDegrees

This 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-bottom:}}