|
|
| (20 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 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 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 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>
| |
|
| |
| The syntax of the method is:
| |
| <p class="syntax"> %string = %tok<var class="literal">:Separators</var>
| |
|
| |
| %tok<var class="literal">:Separators</var> = %string
| |
| </p>
| |
| Where:
| |
| <table>
| |
| <tr><th>%string
| |
| </th><td>A string variable to contain the returned value of the current separator characters or to be set as the new value(s). The default value for a new tokenizer instance is the null string.
| |
|
| |
| If you are setting <var>Separators</var>, each character in the separator string is a separator, and no character may repeat (except for apostrophe, which may be doubled).
| |
| </td></tr>
| |
| <tr><th>%tok
| |
| </th><td>A <var>StringTokenizer</var> object variable.
| |
| </td></tr></table>
| |
| 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>.
| |
|
| |
| '''Note:''' <var>CompressSpaces</var> affects
| |
| processing only when one or more <var>Separators</var> characters are set, because otherwise a
| |
| token cannot contain internal whitespace.
| |
| | |
| ====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</var> property to the <var>StringTokenizer</var> class.
| |
| If the <var>[[FoldDoubledQuotes (StringTokenizer property)|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 syntax of the <var>FoldDoubledQuotes</var> method is:
| |
| <p class="syntax"> %bool = %tok<var class="literal">:FoldDoubledQuotes</var>
| |
|
| |
| %tok<var class="literal">:FoldDoubledQuotes =</var> %bool
| |
| </p>
| |
| Where:
| |
| <table>
| |
| <tr><th>%bool
| |
| </th><td>An enumeration object of type <var>[[Boolean enumeration|Boolean]]</var> to contain or set the value of <var>FoldDoubledQuotes.</var> The default value for a new tokenizer instance is <var>False</var>.
| |
| </td></tr>
| |
| <tr><th>%tok
| |
| </th><td>A <var>StringTokenizer</var> object variable.
| |
| </td></tr></table>
| |
| | |
| ====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).
| |
| | |
| ===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.
| |
| | |
| <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>...
| |
| <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><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><b></code>, <code><c></code>, <code><d></code>, and <code><e></code>:
| |
| | |
| <p class="code">try
| |
| <a>...
| |
| success
| |
| <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
| |
| <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}}
| |