|
|
||||||
| Contents |
|
To keep the implicit translations between Unicode and “ASCII” invertible when any of 1047EXT, 0037EXT, or 00285EXT is the base codepage, the Unicode character with the same numerical value as any of the above ASCII codepoints is not translatable to ASCII. For example, U+9F would not be translatable to ASCII. Using any of 1047EXT, 0037EXT, or 00285EXT as the base codepage affects translations involving “ASCII”, please refer to the Notes for Sirius Mods Version 7.6 for more detailed information. Migrating to codepage 1047EXT, 0037EXT, or 00285EXTIf you find that some of your XML document processing is unsuccessful because it contains some of the Unicode characters shown above as part of the Windows 1252 encodings, you may benefit by switching your base codepage, for example, from 0037 to 0037EXT. The principal effect of switching will be to allow the set of 27 Unicode characters, 26 of which were previously untranslatable to EBCDIC. Because one of these mappings (U+85) was translatable to EBCDIC (X'15'), you may see the following subtle differences using these codepages, compared to using their “non-EXT” counterparts (without any further modifications using the UNICODE command):
Unicode enhancement methodsEnhancement methods for Unicode type string objects are now allowed. Although the User Language Unicode type was introduced in Sirius Mods version 7.3, enhancement methods for Unicode objects have not been allowed until this release. For example, prior to Sirius Mods version 7.6, a local function like the following was invalid: Similarly, a function like the following inside a class was invalid: This restriction is now removed, and you can define an enhancement method like the following: This request produces the following result: Changes to Auto New and Allow AutoIf you append Auto New to an object variable declaration for a user-defined class object, you are not required to later provide a statement that explicitly instantiates the object. Specifying Auto New is valid only if the class definition includes Allow Auto. As of version 7.6 of the Sirius Mods, the Auto New functionality is allowed for extension classes — as long as all the base classes are defined as Allow Auto. In addition, a related enhancement is added to Allow Auto. Prior to this release, a class defined with Allow Auto was not allowed to contain a constructor. As of version 7.6 of the Sirius Mods, Allow Auto is allowed in a class that has a constructor. However, for an object variable declared with Auto New in such a class, an automatic instantiation of the object will not call any of the constructors in the class, even if the class has defined an explicit constructor with the name New. Method-variable assignment restriction is droppedAs of Sirius Mods version 7.6, you may assign an overridable method to a method variable. Prior to this version, such an assignment was not allowed.Intrinsic classesNew Float method: FloatToStringThis function converts a floating point number to a string with a specific length and number of decimal places. New Float method: RoundThis function returns a floating point number that is the method object number rounded to a specified number of decimal places. Negative numbers are rounded down to the nearest integer; positive numbers are rounded up. New String method: InsertThis function inserts an argument string inside the method object string, starting before the specified position in the method object string. The value of %before must be between 1 and the number of characters in the method object string plus one. An invalid position produces a request cancellation. New Unicode method: UnicodeWithThis function returns the Unicode string that is the concatenation of the method object Unicode string and its Unicode string argument. For example, the following is a simple UnicodeWith call: The result is: Collection classesNew system class: UnicodeNamedArrayListThe UnicodeNamedArrayList class is nearly identical to the NamedArraylist class. The main difference is that instead of EBCDIC subscript names for items as in the NamedArraylist class, the name subscripts in a UnicodeNamedArrayList object are Unicode values. UnicodeNamedArrayList items are stored by item name in Unicode order, whereas NamedArraylist items are stored by item name in EBCDIC order. Note: The names of UnicodeNamedArraylists are limited to 127 characters (versus 255 bytes for NamedArrayLists). Audit subroutineThis subroutine displays the contents of a UnicodeNamedArrayList in a readable form, useful for debugging, for example. Audit is identical to the Print method, except the result is sent to the Model 204 audit trail (like the User Language Audit statement). Copy functionThis function makes a “shallow” copy of the UnicodeNamedArrayList method object %unamrayl. If %unamrayl contains objects, they are not copied. If %unamrayl is Null, a Null is returned. Count propertyThis ReadOnly property returns the number of items in the UnicodeNamedArrayList method object. DeepCopy functionThis function makes a “deep copy” of the UnicodeNamedArrayList method object, %unamrayl. If %unamrayl contains objects, they are copied. If %unamrayl is Null, a Null is returned. Default propertyThis ReadWrite property indicates the value to be returned if a requested item name is not in the UnicodeNamedArrayList and the UseDefault property is set to True. Item propertyThis ReadWrite property returns or sets the value of the item that has the specified subscript name in the UnicodeNamedArrayList. ItemByNumber propertyThis ReadWrite property returns or sets the UnicodeNamedArrayList item that has the specified item number. Item number is ordinal, so ItemByNumber(3), for example, identifies the third item in the ordered-by-name UnicodeNamedArrayList. Maximum functionThis function returns the subscript name of the UnicodeNamedArrayList item that has the maximum value after the application of a specified function to each item. The function that gets applied to each UnicodeNamedArrayList item, which you identify in the argument to Maximum, must be a method that operates on the item type and returns a User Language intrinsic datatype (Float, String, Longstring, or Unicode) value. Minimum functionThis function returns the name (subscript) of the UnicodeNamedArrayList item that has the minimum value after the application of a specified function to each item. The function that gets applied to each UnicodeNamedArrayList item, which you identify in the argument to Minimum, must be a method that operates on the item type and returns a User Language intrinsic datatype (Float, String, Longstring, or Unicode) value. NameByNumber propertyThis ReadOnly property returns the subscript name of the item that has the specified item number (position) in the UnicodeNamedArrayList. New constructorThis method returns a new instance of a UnicodeNamedArrayList Number propertyThis ReadOnly property returns the item number (ordinal) of the item that has the specified subscript name in the UnicodeNamedArrayList. Print subroutineThis method displays the contents of a UnicodeNamedArrayList on the user's standard output device, typically a terminal. The list item values, displayed in order by their subscript names, are preceded by their item number and item name, both of which by default are followed by a colon (:) and a blank. RemoveItem functionThis callable function removes from the UnicodeNamedArrayList the item that has the specified subscript name. Trace subroutineThis subroutine displays the contents of a UnicodeNamedArrayList in a readable form, useful for debugging, for example. Trace is identical to the Print method, except the result is sent to the selected Trace stream (like the User Language Trace statement). UseDefault propertyThis ReadWrite property indicates whether an attempted retrieval of an item that is not on the UnicodeNamedArrayList should return the Default method value. UseDefault will return, or may be assigned, only the values True or False. Its initial value is False. Print method for collection classesIn versions of the Sirius Mods prior to 7.6, the standard way to view the entire contents of a collection is to loop through the list items and display each one using a User Language Print statement (or Audit or Trace). For a NamedArrayList, for example, you use a method for the item subscript name and a method for the item content: This is the result: As of version 7.6 of the Sirius Mods, the Print method for any collection does the work of the loop in the preceding example, and more. Supplied for debugging purposes, Print (or the essentially identical Audit or Trace method) would produce the following output using the example collection above (that is: %nal:print): Notice that Print outputs all the collection items (or, optionally, a range of items), and it also includes:
Print also has optional parameters that let you specify:
The Print method applies a ToString method (by default) to each item value (and always to each item name), to produce its result. Applying Print to a collection whose item types are not system classes will work only if the user class contains a ToString method. The general syntax of Print (Audit or Trace) for a collection is:
All parameters are optional and all except
As of Sirius Mods version 7.6, a variety of methods are common to all the
collection classes for the purpose of searching a collection for
the item(s) that satisfy one or more specified conditions.
The searching methods (all functions, listed below) have the same, or nearly
the same syntax.
They take two parameters:
The searching methods are:
The FindNextItem and FindPreviousItem methods also throw an
ItemNotFound exception
if no item matches the SelectionCriterion.
A SelectionCriterion object,
which might consist of multiple components, describes a
single selection criterion.
For example, the GE method in that class uses two parameters to form a
("greater than or equal to") comparison criterion to apply to the
collection items.
So, for SelectionCriterion object %sel,
which selects items whose absolute value is less than or equal to 1000,
you might have:
A simple search, starting from the eighth item in the %payoff arrayList,
might be:
The parameters of the SelectionCriterion GE method above provide the operands
for the comparison operator GE.
In this case, absolute, is an intrinsic Float method
which is applied to an item value.
In general, this must be a function that operates on the type of the items
in the collection, and it may be a local method or method variable or a class
member (variable, property).
The value that results from applying the Absolute method above is compared to
the second GE parameter, 1000.
This 1000 may be any User Language intrinsic expression,
such as a string or numeric literal.
In the fragment that follows, the function in the SelectionCriterion is a local method,
and the searching method, FindPreviousItemNumber, searches
backward starting with the tenth item in the collection to find the item
number of the first item that satisfies the criterion:
The local method myMod above, which calls the Mod intrinsic
Float method, is necessary in this case because the SelectionCriterion
function parameter may not itself specify a parameter.
The function parameter is a method value, not a User Language expression.
The preceding example also shows a SelectionCriterion object declaration,
which must suit the item type to which the criterion will be applied,
as described in Declaring a SelectionCriterion object variable.
In the following example, the
function parameter is the very useful identity function, This,
which returns the value of the item to which it is applied.
The searching method SubsetNew returns a collection of all
the items in the collection that satisfy either of the criteria
(< 0, > 999) that comprise the OR criterion:
Usage notes:
The special identity function, This, is now the default
function parameter value for the collection Minimum and Maximum methods
and for the SortOrder Ascending and Descending methods.
In addition, for the SortOrder argument in the sorting
methods, Ascending (which implies Ascending(this))
is now the default.
For example, instead of explicitly specifying This in the
printText statement in this request:
You can now use:
Similarly, for a sort, instead of %l:sort(descending(this),
you can now simply specify:
Furthermore, because Ascending is now the default argument,
explicitly specifying ascending(this) in the following request is now optional:
Instead, you can now simply specify:
Sirius Mods version 7.6 supports Find To and Sort To statements whose target is
an object of an extension class of either a RecordSet or a SortedRecordSet.
That is, a sequence of statements like the following will now succeed:
In Sirius Mods version 7.6, a Find To or Sort To statement that constructs
a recordSet object may execute a separate constructor method for the target variable
before finding records for the target.
For example, a statement like the following, which creates the already-declared
recordSet %trex, is now valid:
In the statement above, Find To first creates a new
RecordSet instance (with the specified For loop lockstrength)
and assigns it to the target object variable, %trex.
Then Find To populates %trex with the found records.
Note:
If the Find statement in the previous example is changed to this:
The locking in the %trex recordSet is ultimately governed by
the Find statement, so the resulting lockstrength here is None
in agreement with Find Without Locks.
Similarly, the target of a Text To statement may now execute a
constructor before populating the target list.
For example, the following is is now valid:
Previously, you would have to issue one more statement:
The Find To, Sort To, and Text To statements in Sirius Mods 7.6 all allow their
target to be a class variable or even a class property.
Before this version, none of
these were allowed, except Text To allowed the target to be a class variable.
Note:
The property support allows the target of a Find To to be a collection member.
For example, the following fragment outlines a statement sequence that would
validly instantiate the RecordSet object that is the item named
for %value in the %wrek NamedArrayList:
Prior to this release, the SortedRecordset and RecordsetCursor classes had no
constructor methods.
Such objects could only be created with factory methods or their equivalents.
Sirius Mods version 7.6 introduces simple New constructors for both classes:
Although such a new instance is not of significant value,
the New constructor is useful to enable the creation of an extension class
of the SortedRecordSet class, which the existing SortedRecordSet constructor
factory methods cannot do.
See, for example, this use of New in a Construct statement in an extension class:
Where:
Note:
It is an error to specify this argument if
If
Note:
This is different from the RecordSet and SortedRecordSet Cursor
methods, which construct a RecordSetCursor object.
Those Cursor methods still return a null if
As is the case for the SortedRecordSet New constructor described earlier,
the RecordSetCursor New constructor enables the creation of an extension class
of the RecordSetCursor class, which the existing RecordSetCursor-object
factory constructor cannot do.
A RecordSetCursor cursor is in any of multiple positions, or cursor states,
as it navigates a record set.
Sirius Mods version 7.6 adds the Empty state to the set of possible cursor states.
A cursor is in the Empty cursor state if it points to an empty record set.
The availability of the Empty state allows the New constructor to avoid returning
a null if it is applied to a record set that has no records.
And this becomes important if you are constructing an extension of the
RecordSetCursor or SortedRecordSet class.
An ItemNotFound exception indicates that a collection object search
located no collection items that satisfy the selection criterion
specified in the collection method that invoked the search.
There are several searching methods,
but only those that return a single found item produce an ItemNotFound exception.
This exception class has no properties.
It is simply a notification that a valid search found
no items that met the selection criterion.
The class's only method is the New constructor, which
you would typically use with a User Language Throw statement
to produce an ItemNotFound exception:
When working with the collection searching methods, remember that
an exception is thrown only if there is a catcher for the exception.
For example,
if you expect one or no matches from your search, you might specify
a block like the following:
On the other hand, if you always expect
a match, you might want a program crash to result if you are wrong
about the match, so you could leave out a Try/Catch.
The Try/Catch approach is slightly more efficient than a test for a zero result.
Try generates no quads other than the branch around the catch block if the
search succeeds.
And in fact, you could put a Try around a loop and use
the ItemNotFound exception to exit the loop:
This callable constructor generates an instance of an ItemNotFound exception.
The New method format follows:
The RecordLockingConflict exception class catches record locking conflict errors thrown by file
object operations, that is from methods in the file classes (Record, RecordSet, SortedRecordSet, RecordSetCursor).
An exception is thrown only if there is a Catcher for the exception.
There is no distinction between a Find conflict and a record locking conflict.
For example, you can use the following:
And you can also use:
You can even catch record locking conflicts caused by LoopLockStrength promotions
during a loop:
The members of the RecordLockingConflict class are described below.
Except for the constructor, New, all class members are
read-only properties:
The default values of the parameters are the null string or 0, as appropriate.
The XmlParseError exception class catches
parsing errors (including syntax, translation, and encoding errors)
thrown by the deserialization methods: LoadXml, WebReceive, and the ParseXml.
method of the HttpResponse class.
The members of the class are described below.
Except for the constructor, New, all class members are
read-only properties:
A violation of the syntax of an XML document.
The input UTF8 stream is invalid.
The input UTF16 stream is invalid.
The Unicode input contains a character that is not translatable to EBCDIC.
This exception can be avoided using the AllowUntranslatable
option of the deserialization method.
The EBCDIC input contains a character that is not translatable to Unicode.
The ISO-8859-n input contains a character that is not translatable to Unicode.
The Unicode input contains an invalid character.
The Reason argument is required;
all other arguments are optional, with default values of the
null string or 0 as appropriate.
Objects in the SelectionCriterion class are used primarily as input to the
collection class searching methods.
The searching methods take a SelectionCriterion object as a parameter which
provides an item selection specification for the search.
The following description is an introduction to the SelectionCriterion class and its methods.
For more detailed information, please refer to the
Notes for Sirius Mods Version 7.6 and
the Janus SOAP Reference Manual.
A selection specification, or criterion, is a relational expression (or more than one) that
tests whether a collection item is to be included in the result set.
The SelectionCriterion methods are named for the operation they provide:
EQ (equal to), NE (not equal to), LT (less than), LE (less than or equal to),
GT (greater than), GE (greater than or equal to).
The AND, OR, and NOT methods let you combine comparison operations in a single criterion.
The TRUE and FALSE methods respectively match all or no items.
Most SelectionCriterion objects use two parameters to construct a single criterion
for selecting a collection item; some use two or more SelectionCriterion objects
to construct a single criterion.
As an example specification, the selection criterion %sel in the following statement,
instantiated by the LT constructor method, matches a number whose square root is less than 10:
Where the left- and right-hand elements of the comparison operation are,
respectively, the LT parameter values:
This %sel criterion might be used as follows to locate the
next ArrayList item after item 3 whose square root is less than 10:
The requirements for the SelectionCriterion parameter exemplified by the SquareRoot
method above are:
Additional notes:
ANDs and ORs take 4 bytes, and
comparison selectors have 12 bytes of overhead plus the length of the value
rounded to a 4-byte multiple.
So, for example, an And condition with
seven 20-byte values would take 4+7*(20+12), or 228, bytes.
You can work around a criterion that exceeds 252 bytes by
encapsulating some or all of the conditions in a local method, since a local
enhancement method can be the method parameter for a comparison
SelectionCriterion.
The SelectionCriterion class operates on specific objects, so a variable of the
SelectionCriterion class must be qualified with the object to which it applies:
For example:
The declaration for %sel in the example in the preceding section
might be:
In general, the syntax for declaring a SelectionCriterion object variable is:
Where:
As stated earlier, most of the SelectionCriterion methods
accept two parameters, the first a “method value” and the second an
intrinsic value.
Regarding the first, just as
a User Language “numeric” argument can be a numeric literal or a variable or even an
expression that results in a number, a method value argument can be a method
literal or a method variable or an expression that results in a method.
More specifically,
a method value is a value assigned to a method variable.
And for a SelectionCriterion, the method variable's implicit
declaration is:
The method value argument must conform to the following rules:
These shared methods each create a new SelectionCriterion object
that is a relational expression used to select items from a collection.
Each of these constructors provides a different comparison operator.
The EQ method, for example, constructs an equality expression that
selects a collection item if the expression is true for that item.
The other methods construct, respectively, not-equal-to, greater-than-or-equal-to,
greater-than, less-than-or-equal-to, or less-than expressions.
The collection searching method that makes use of a selection criterion specifies:
The first of the two parameters in a selection criterion specifies a function
that is applied to a collection item.
The function result is the “left-side” operand in the criterion's expression.
The second selection criterion parameter is a string or numeric that is
the “right-side” operand in the expression.
EQ(name, 'Ortiz') specifies the expression name='Ortiz'.
The function parameter of one of these constructors might simply be an
identity function that returns the item value.
Or, for example,
it might be a function that returns the value of a class member
for an item that is an object.
This function must be a method that operates on the item type and returns a User Language
intrinsic datatype (Float, String, Longstring, or Unicode) value.
Notes:
These shared methods each create a new SelectionCriterion object
that is an expression used to select the items in a collection.
Each constructor uses a different logical operator
to form an expression that combines one or more SelectionCriterion objects.
An OR criterion returns true for a collection item if any of the
component SelectionCriterion expressions are true for the item;
otherwise it returns false.
An AND criterion returns true if all of the
component SelectionCriterion expressions are true for the item;
otherwise it returns false.
All OR and AND SelectionCriterion conditions are short-circuiting conditions.
That is, if any of the conditions in an OR return True, the subsequent conditions
are not evaluated and the OR returns True.
Similarly, if any of the conditions in an AND return False, the subsequent
conditions are not evaluated, and the AND returns a False.
Therefore, it is wise to put the most likely conditions first
in an OR, and it is wise to put the least likely first in an AND.
For a mix of conditions where some are simply variable references and others require method evaluation,
it probably is best to put the variable references first, as these are probably much cheaper to evaluate.
This shared method creates a new SelectionCriterion object
that is a logical negation of its SelectionCriterion parameter.
A NOT criterion returns true for a collection item if NOT's component SelectionCriterion
expression is false for the item; otherwise it returns true.
The NOT constructor is never necessary, and anything you can
do with the NOT can be done (probably more clearly) otherwise.
For example, the following two criteria are identical:
And the following two criteria are identical:
And these criteria are identical:
Internally, NOTs are always converted to the inverse of the parameter criterion.
These shared methods take no parameters and create a new SelectionCriterion object.
A TRUE criterion returns true for any collection item;
A FALSE criterion returns false for any collection item.
TRUE and FALSE thus provide the equivalent of an empty SelectionCriterion,
and they substitute for a New constructor in the SelectionCiterion class.
Notes:
In addition, if you are building a SelectionCriterion by using OR in conditions,
it might be useful to start out with a FALSE SelectionCriterion:
Similarly, if building a SelectionCriterion by using AND in conditions,
it might be useful to start out with a TRUE SelectionCriterion.
As of Sirius Mods version 7.6, XmlDocs contain Unicode rather than
EBCDIC; this is true for all string values, names, prefixes, and URIs.
As a consequence, most of the arguments and results
of the Xml API methods that formerly were strings are now Unicode strings.
This change will allow you to store Unicode in an XmlDoc, thus achieving
the W3C XML Recommendation (in which characters are Unicode), but without
needing to change your existing Xml API applications.
This is because automatic conversions are done between EBCDIC and Unicode
in Janus SOAP.
For example, you can still code:
The EBCDIC character strings above are automatically converted from EBCDIC to Unicode.
Similarly, you can code:
If the variable %str above is declared as type String or
Longstring, then the Unicode result of the Value method is automatically
converted from Unicode to EBCDIC when it is stored in %str.
This feature did require some changes to existing Janus SOAP Xml API methods.
Those changed methods are included in the following sections, even where the change is only of an
argument or result to Unicode.
A new XmlDoc property, AllowNull, is now available.
This Boolean property, which defaults to False, may
be set to True, which allows the XmlDoc to contain
null characters (U+0000) in node values.
Once this property has been set to True, null characters are
allowed for deserialization into the XmlDoc.
For example:
Null characters are also allowed for “direct setting” of a node's value.
For example:
When nodes have been added to an XmlDoc that has AllowNull=True, a “subtree copy”
operation (that is, either AddSubtree or InsertSubtreeBefore) is not allowed using it as the source (argument 1)
if the target (method object) of the operation is an XmlDoc with AllowNull=False.
Notes:
A new XmlNode subroutine, AppendValue, appends to
the value of a node in an XmlDoc.
Where:
For example, the following fragment appends a Unicode string and then a
StringList to an Element value:
The result is:
The new XmlNode property, NoEmptyElement, may be specified
for any Element node.
If set for an Element that contains
no children, the Element is serialized with a separate start tag
and end tag, rather than with a single empty element tag.
For example, <address></address> versus <address/>.
This formatting option can be useful if you are using the Janus SOAP ULI to
generate XHTML.
Tests show that some browsers work correctly for
certain childless elements only if they have an empty element tag,
and for other childless elements they work correctly only if there are
separate start and end tags.
(Therefore, you cannot obtain a “blanket” suppression of empty
element tags via using the NoEmptyElt option of the
serialization methods.)
The NoEmptyElement property accepts and returns a Boolean value.
Setting it to True suppresses an empty element tag.
The default is False.
A new option, AllowUntranslatable, is now available
for the LoadXml and WebReceive methods, as well as for the ParseXml
method of the HttpResponse class.
When this option is specified,
all valid Unicode strings are allowed in the XML document.
When this option is not specified, Unicode
strings that are not translatable to EBCDIC are not allowed.
How you use this option depends upon the application's
handling of the XmlDoc into which you are deserializing.
The basic rule is to use AllowUntranslatable only if the application
checks for translatability when accessing parts of the XmlDoc that may
have untranslatable Unicode content.
In this case, any access to the deserialized content is performed
without any Unicode to EBCDIC translation errors.
This approach detects (and throws an XmlParseError exception
with reason UntranslatableUnicode) for any untranslatable
Unicode in the serialized input XML document.
That is to say, given the following fragment:
The assignment to the EBCDIC string %val cannot fail due
to a Unicode translation problem: if there is any untranslatable
Unicode (including, of course, strings in the XML document which your
application never accesses), the WebReceive operation fails.
In this case, all Unicode characters in the serialized input XML document are
allowed and stored in the XmlDoc.
However, if the application later accesses content that is not translatable to
EBCDIC, and the access performs an implicit Unicode-to-EBCDIC translation,
the request will be cancelled.
The code below shows a way to get the benefit of specifying AllowUntranslatable
while limiting the risk of request cancellation.
In the example, it is believed that only the element comments might
contain untranslatable Unicode among all the data accessed from the XML document:
A new option, CharacterEncodeAll, is available
for the Print, Audit, and Trace methods.
This option uses character encoding in all contexts to display
Unicode characters that do not translate to EBCDIC.
With or without this option, non-translatable Unicode characters
in Attribute or Element values are displayed as character references.
For example:
The result of this fragment is:
However, with default serialization options, when an untranslatable
Unicode character occurs in a context other than element or attribute value
(that is, a name, comment, or PI), character encoding is not used.
For example, the following statements result in a request cancellation:
The Print method fails, attempting
to translate the element name, the U+2122 character, to EBCDIC.
This request cancellation can be overcome using CharacterEncodeAll:
The result of the above fragment is:
Note:
The result of a Print with CharacterEncodeAll can be misleading.
Request cancellation is avoided, but it produces multiple EBCDIC characters
where only a single Unicode character is stored.
The XmlDoc, %doc, above is not a legal XML document,
because the ampersand (&) is not a legal name character.
Similarly, for an untranslatable Unicode character added to a document
with AddComment or AddPI: printing with CharacterEncodeAll
produces a stream of characters that informs about a single character reference
but, if deserialized, would result in multiple stored characters.
The standard XML syntax does not recognize character references as such in
names, Comments, and PIs.
The InvalidChar property of the XmlDoc class is no longer supported.
Requests containing InvalidChar will fail under Sirius Mods version 7.6.
If you are using InvalidChar in source code to allow null characters, you
can use the AllowNull property instead.
The InvalidCharacterPosition method is enhanced as follows:
InvalidCharacterPosition returns zero if its argument string is:
Otherwise, it returns the character position of the first character
that does not meet these criteria.
The IsValidString method now accepts either
an EBCDIC or Unicode string.
Formerly, only an EBCDIC argument was allowed.
IsValidString now returns True if its argument string is:
Note:
IsValidString is deprecated, in favor of the InvalidCharacterPosition function.
The following features are new or changed in Janus TCP/IP Base.
There are two new forms of the JANUS LOADXT command:
The name of the table is given in the third word of the command,
shown as xtabName above.
The translations defined in the table are the same as the translations
between ASCII and EBCDIC defined in the current Unicode table, except
that, since there is no concept of “untranslatable” in the use
of the Janus translation tables, the following translations are used:
Untranslatable ASCII code points are translated to EBCDIC X'FF'.
Untranslatable EBCDIC code points are translated to ASCII X'3A'
(the ASCII colon character - “:”).
The translations defined between ASCII and EBCDIC are the translations
used by the AsciiToEBCDIC and EBCDICToAscii methods.
This can be used as an “undo” command; for example, if you had issued:
Then the following command will revert the STANDARD xtab to its default:
The following features are new or changed in Janus Sockets:
The new Disposition and Description parameter
options are added to the SMTP Helper AddPart method.
These name required parameters are strings that
provide content-disposition and content-description
headers for attachments added with AddPart.
AddPart adds a content-disposition header or a content-description header
to an e-mail attachment only if you specify, respectively,
a Disposition or a Description value.
The default value of the AttributeNames argument of the ToXmlDoc method in
the Record class has been changed.
Formerly, the default was False; the default now is True.
The reason for this change is that the AttributeNames=True format
is more well suited to operations on the XmlDoc, particularly a record copying
operation.
Two similar fixed problems may introduce backwards incompatibilities:
As of Sirius Mods version 7.6, the LockStrength of the target recordSet of a FD
statement that finds no records is always set to Share.
As of Sirius Mods version 7.6, these methods now correctly set these output
RecordSet locking strengths to be the same as that of the method objects.
The Print, Audit, and Trace statements now encode Unicode data for display.
In the case of the ampersand, this can change the result.
For example, in version 7.5 of the Sirius Mods, the following fragment:
produced the following result:
In version 7.6, however, it produces the following result:
In version 7.5 of Janus SOAP, some attempt is made to use the apostrophe (') to
bracket the serialization of an attribute if it contains a quote (").
In version 7.6, attributes are always bracketed by quotes.
For example, consider the following fragment:
This produces the following result with version 7.5:
However, starting with version 7.6, it produces the following result:
In versions 7.3 and 7.5 of Janus SOAP, although you are allowed to set and retrieve
the InvalidChar property of an XmlDoc object,
this property is ignored and has no effect.
In versions 7.2 and older
of Janus SOAP, this property allowed certain EBCDIC characters (nulls, for example)
to be stored in an XmlDoc which otherwise were not allowed.
Starting with version 7.6 of Janus SOAP, all Unicode characters may be
stored in an XmlDoc, except for the null character (U+0000), which is
prohibited by the XML Recommendation.
Therefore, the InvalidChar property would be extremely misleading,
so it has now been removed from Janus SOAP.
If you had been using InvalidChar=Allow to allow null characters in an XmlDoc,
this purpose can be achieved via AllowNull=True.
Also note that when providing EBCDIC characters to be stored in
an XmlDoc, those EBCDIC characters must be translatable to
Unicode.
If you have EBCDIC strings which may not be translatable, you
must handle those before passing them to an XmlDoc update operation;
for example, you may be able to use the Untranslatable
argument of the EbcdicToUnicode function.
Now the LoadParameterInfo method builds an XmlDoc such that:
Sirius Mods 7.5 supports only Model 204 versions V6R1 and V7R1.
The commercial release of Model 204 V7R1 is supported only by Sirius Mods 7.5
and later.
Two new parameters that affect Janus SOAP ULI “garbage collection”
are added.
Setting this User parameter reports garbage collection statistics
in a message to the audit trail, to the terminal, or to both.
The statistics include the number of objects discarded by the
garbage collection process and the amount of time taken.
The Janus SOAP ULI performs garbage collection automatically at user logout:
that is, at logout it removes user-created objects that were not
discarded by the user or by the Janus SOAP ULI during and after
each request.
This garbage collection process can also be invoked explicitly
(by %(object):GarbageCollect), and it may be
time consuming.
The AUTOGCN User parameter lets you invoke garbage collection
automatically during a user session whenever normal post-request cleanup
“leaves behind” a number of objects that meets or exceeds the AUTOGCN value.
For more information about garbage collection, please refer to the
Janus SOAP Reference Manual.
The following sections describe changes in the Janus SOAP ULI
in this release.
The MaxDaemExceeded exception class indicates that the Daemon class constructor
was invoked, but the calling thread is at its limit of daemon threads.
The maximum number of daemons allowed per master thread is set by the MAXDAEM
system parameter, whose default value is 1.
Many new intrinsic methods have been added, as described in the following subsections.
Many of the examples use the PrintText statement, which was introduced in Sirius Mods version 7.2
and is described in the Janus SOAP Reference Manual.
This function returns the string value of the single character at a specified
position in the method object Unicode string.
This function returns the left-most characters of the method object string,
possibly padding it on the right.
This function returns the number of characters in the method object string.
These functions return the numeric position of the first occurrence of one
character string inside another (character case respected).
The difference between the two methods is that for UnicodePositionIn, the method
object string is located in the first argument string, whereas for
UnicodePositionOf, the first argument string is located in the method object
string.
Which method is more convenient to use will be application dependent.
The starting position must be a positive number.
A zero or negative number results in request cancellation.
If the starting position is greater than the length of the haystack
plus one minus the length of the needle, a zero will always be
returned since there aren't enough characters in the haystack
to satisfy the search.
The UnicodePositionOf and UnicodePositionIn methods do exactly the same thing.
The only difference between them is that in UnicodePositionOf, the haystack
is the method object and the needle is the first argument.
In UnicodePositionIn, the method object and first argument are reversed.
Which method is preferable will depend on the application, and, in many
cases, it will be quite arbitrary which one is used.
The UnicodePositionOf and UnicodePositionIn methods are analogous to
the String intrinsic PositionIn and PositionOf methods.
This function returns a specified number of the right-most characters
of the method object string, possibly padding them on the left.
This function returns a specific number of characters starting at a
specific position in the method object Unicode string,
possibly padding it on the right.
Two new pairs of intrinsic conversion methods are added.
The FloatToBinary function in the Float intrinsic class
converts a numeric value to the binary string equivalent
of its floating point representation.
Since all Float types are processed in Model 204 as Float Len 8, FloatToBinary
always returns an 8-byte string.
The BinaryToFloat function in the String intrinsic class
converts a binary representation of a floating point number
to that number.
The method object can be a string of length 4, 8, or 16.
These methods convert between hex strings and integers.
IntegerToHex converts an integer to its hexadecimal string representation.
The method's arguments are the requested hex-byte output size, and an optional, boolean,
named-parameter: Signed
HexToInteger returns the integer value of a hex encoded string.
It has a single, optional, boolean named-parameter: Signed.
The EbcdicToUnicode method now takes the Untranslatable named
argument, which lets you specify how to handle EBCDIC input characters
that are not translatable to Unicode.
The Untranslatable argument is optional; if it is omitted and
an EBCDIC character is encountered that is not translatable to Unicode,
a CharacterTranslationException exception is thrown.
Otherwise, the value of the Untranslatable argument can be the
null string or can be a single Unicode character.
The following sections describe changes in the Janus SOAP Xml API.
The value of an XmlDoc's Version property may now be set to '1.1':
Also, 1.1 is accepted in the XML declaration in a deserialization operation:
This new shared method is a constructor that produces an XmlDoc object that contains
detailed information from a client certificate received by a Janus web server,
server socket, or Telnet server.
The XmlDoc that is returned includes details about the client and about the certificate's signer.
The ClientCertificate method provides much of the functionality of functions
in Janus Web Server ($Web_Cert_Info and $Web_Cert_Levels) and Janus Sockets
($Sock_Cert_Info and $Sock_Cert_Levels).
The ClientCertificate syntax is:
The AttributeNames and AttributeValues arguments indicate
how to display certificate detail names and values
within their XML document elements:
as the element name, or as the value of a “name” or “value” attribute.
For example, for the certificate detail named “locality”:
The default value for both is False, which produces element-name format.
The XmlDoc object produced by the ClientCertificate method is Null if:
The information returned by this method is most useful in the server port's
JANUS DEFINE NEWSESCMD processing.
The information method can be used anywhere:
no information in the client certificate is considered “secure.”
The following option is available for all deserialization methods:
CrPreserve is mutually exclusive with all other Wsp* options,
and with the LinefeedNoTrailingTabs option.
The following features are new or changed in Janus Web Server:
A new option has been added to the $Web_File_Content,
$Web_Input_Content, and $Web_Output_Content functions.
The name of this option is TextUtf8 and it is
mutually exclusive with the Text and Binary options.
The TextUtf8 option causes $Web_Input_Content to first convert each
two-byte UTF-8 sequence to the corresponding ASCII character, which is
then translated to EBCDIC using the translation table in effect for the
Janus Web Server connection.
For example:
Sirius Mods version 7.3 supports only Model 204 V6R1.
A number of Janus SOAP classes are now available to any Sirius Mods version 7.3 customer.
The following classes are not restricted to those with a Janus SOAP license:
Two new parameters that affect Model 204 retrieve key processing
are added.
This User 0 parameter specifies the size of the buffer
for the 3270 terminal PF key that retrieves previously input command lines.
The larger the retrieve buffer, the more commands you can save for retrieval.
The minimum and default setting of RETRVBUF is 288 bytes, and its maximum is 32767.
The parameter setting is always rounded
down to the nearest 8-byte multiple, so the largest buffer allowed is
actually 32760 bytes.
This user parameter is a bitmask parameter that controls some characteristics of the
Model 204 retrieve key.
The RETRVOPT bits are:
For example, if RETRVOPT is set to X'17' and RETRVKEY is 12,
the forward retrieve key is PF24.
And if RETRVOPT is set to X'17' and
RETRVKEY is 21 (Shift+PF9), the forward retrieve key is PF9.
Two new FUNCOPTS bit settings
allow a site to ease or eliminate the restrictions on who can use
the $PRIORTY function to change another user's priority:
The default value of SCRNSTBL is increased from 4096 to 6144.
The following feature is added to the Sirius regular expression support (the regex methods
in the StringList and String intrinsic class, and the $RegexMatch and $RegexReplace $functions).
The regex support is summarized in the “Regex Processing” chapters
in the Janus SOAP Reference Manual and the
Sirius Functions Reference Manual.
The following sections describe changes in the Janus SOAP ULI
in this release.
Three “smaller,” unrelated, system classes have been added.
These are all documented in the Janus SOAP Reference Manual.
As its name suggests, the RandomNumberGenerator class
is designed to generate random numbers.
It is patterned after the Sirius functions $Random and $Random_Seed, described
in the Sirius Functions Reference Manual.
The methods in the class include a New constructor to instantiate an object,
a Value method for printing as well as constraining the random number value
range, and an UpdateSeed method to reset the value of an object.
As an example, the methods in this request create a reproducible sequence of ten numbers
between 0 and 99:
A CharacterMap class object contains a mapping of characters to characters.
Each character in an In string
(the “input table”) is associated with, or mapped to, an individual character
from an Out string (the “output table”).
The output table may be supplemented with instances of a pad character
to ensure a one-to-one mapping with the input table characters.
CharacterMap includes a constructor, copy methods, and an update method
for modifying the map.
Most of these methods are shown in the following example,
which features the Translate method for longstrings (Translate function).
In the example, a new CharacterMap is the argument for the Translate method;
then that map is copied and modified, and the modified map is used in a
second Translate call:
The result is:
Intended for performance work, the UserStatistics class
is designed to replace $STAT and similar tools that return the
values for selected Model 204 User statistics.
The UserStatistics constructor takes a snapshot of the user stat block at the
time the constructor is invoked.
You then use the UserStatistics methods to extract
the statistical data from the instantiated object.
The object holds two types of user statistics:
Login and Request.
Login and Request statistics are not mutually exclusive.
Both Login and Request data are kept for some activities, so many
statistics appear in lists of both types and are valid in all methods
that are restricted to one type or the other.
The Model 204 System Manager's Guide
and the SirMon User's Guide are good sources of information
about the available statistics, although not all statistics shown in the
SirMon User's Guide are included in a UserStatistics object.
Where they occasionally differ in spelling the name of a statistic, the
Model 204 System Manager's Guide
is more likely to have the spelling required by the UserStatistics methods.
You can also view all the individual statistics contained in a UserStatistics
object by applying the ToString method to it, as follows:
The longstring output from this ToString method invocation displays all
the Login statistics followed by all the Request statistics.
Note:
The ToString method shown above can be applied implicitly:
simply print or audit an object variable, and
the ToString method is automatically applied to the object.
Print %statobject is equivalent to Print %statobject:ToString.
The following is a simple example that
shows how much CPU a request uses and how many DKRDs it did:
Specifying a statistic that is not a User statistic, or that is not the type of statistic
(Login or Request) that a method calls for, triggers an UnknownStatistic exception.
The StringTokenizer class is used to divide an input string (method object) into
substrings (tokens).
The tokens are separated by either of two types of delimiters:
A token is thus a sequence of
consecutive characters that are not delimiters, or it is
a single token-delimiter character.
The delimiters are user definable, are
specified per StringTokenizer object at creation time, and can be modified thereafter.
StringTokenizer operations maintain two positions within the
method object string:
To navigate the simplest path through the given string, you
“walk” forward (left to right) from the beginning of the string using token-sized
steps (that is, from whole token to next whole token to next whole token, and so on).
The following is a simple example of this in which three tokens are separated
by blank, non-token delimiters:
Each of the NextToken method calls above returns a token:
respectively, “a”, “tokenization”,
and “example”.
The StringTokenizer class also has methods that let you take character-sized steps
forward in the string, as well as methods that let you modify the position markers
and thereby select tokens or sub-tokens in the order you require.
You can also locate specified tokens, and you can return substrings that are
the characters in the entire string that precede a position or that follow a position.
The StringTokenizer class methods include:
This method returns a Boolean value that indicates whether
the present tokenizing position is immediately after the last token.
The value is True if the position at after the last token;
otherwise it is False.
This method returns a Boolean value that indicates whether
the current token is a quoted token.
A quoted token contains all the characters between a pair of identical
quotation characters.
The CurrentQuoted value is True if the current token is quoted;
otherwise it is False.
This method returns the string value of the current token.
The current token is typically the most recent token
returned by the NextToken or FindToken function. n
CurrentToken is invalid and cancels the request until one of these calls has been made.
You can also update the current token by explicitly setting the CurrentTokenPosition value.
This readWrite property returns or sets the position of the first character in
the current token.
If you change the current token (by invoking NextToken or FindToken),
CurrentTokenPosition is updated with a new value.
If you explicitly set CurrentTokenPosition, the current token value is adjusted accordingly.
This callable method returns a Boolean value that indicates whether
it finds a specified token.
The value is True if the token is found; otherwise it is False.
The search starts from the tokenizing position, the value of which is returned by NextPosition.
If the token is found, the position in the string is advanced past the found token, and CurrentToken
will return the found token.
Otherwise, AtEnd is set to True, and CurrentToken is set to the last token at the end of the string.
The delimiters that are involved in determining the tokens
are set initially by the New method that instantiates the StringTokenizer object.
The delimiters can be modified by the Spaces, Quotes, and and TokenChars methods.
This method returns a new instance of a StringTokenizer object.
It has three optional arguments that let you specify the delimiter characters
that determine the tokens in the string that is being tokenized.
This method returns the value of the character that is at the tokenizing position,
and it advances the tokenizing position past that character to the next character.
The tokenizing position is the value returned by the NextPosition property.
This readWrite property returns or sets the tokenizing position, the position of the character
from which the parsing of the next token begins.
Unless you explicitly set it otherwise, the tokenizing position is the position that follows the
(last) character in the value returned by the most recent call of NextToken, FindToken or NextChar.
This method returns the string value of the next token forward in the current tokenizer string.
The next token parsing begins from the tokenizing position, which is the value returned by NextPosition.
When the next token is determined, NextToken advances the tokenizing position
to the position following that token, then returns the token value.
The delimiters that are involved in determining the tokens
are set initially by the New method that instantiates the StringTokenizer object.
The delimiters can be modified by the Spaces, Quotes, and TokenChars methods.
This method returns a Boolean value that indicates whether or not
the present tokenizing position is after the last token in the tokenizer string.
The value is True if the position is not after the
last token; otherwise it is False.
The tokenizing position is given by NextPosition.
This method returns the value of the character that is at the tokenizing position.
The tokenizing position is the value returned by NextPosition.
After returning the character value, PeekChar does not advance the tokenizing position,
which remains what it was when PeekChar was called.
This method returns the string value of the next token forward in the current tokenizer string.
The next token parsing begins from the tokenizing position, which is the value returned by NextPosition.
When the next token is determined, PeekToken does not advance the tokenizing position,
which remains what it was when PeekToken was called.
The delimiters that are involved in determining the tokens are set initially by the New method
that instantiates the StringTokenizer object.
The delimiters can be modified by the Spaces, Quotes, and TokenChars methods.
This readWrite property returns or sets the characters that are recognized as quotation characters.
The text between each disjoint pair of identical quotation characters (a “quoted region”)
is treated as a single token, and any delimiter characters (Quote, Space, or TokenChar)
within a quoted region are treated as non-delimiters.
This readWrite property returns or sets the Boolean value that indicates
whether to remove the quote characters from the returned values of quoted tokens.
The default value for a new tokenizer is True.
This method returns the current non-tokenized substring of the tokenizer string.
This substring starts from the position after the next token,
and it includes the remaining characters going forward to the end of the string.
This readWrite property returns or sets the characters that are recognized as
“whitespace”characters, that is, as characters that separate tokens.
Such a character is also called a “non-token delimiter,”
because it is a delimiter that is not itself a token.
You can specify “token delimiters,” which are delimiters that are also tokens,
using the TokenChars method or the New constructor TokenChars parameter.
One or multiple consecutive whitespace characters mark the end or beginning
of a token, except when these spaces are part of a quoted region.
In that case, the spaces become non-delimiters.
This method returns the substring of the tokenizer string
that precedes the first character of the current token.
This readWrite property returns or sets the string to be tokenized.
This method returns the length of the current tokenizing string.
This string is the value of the String method.
This function returns a substring that is a specified length and starts at a specific
position in the tokenizing string.
The substring may be padded on the right.
This readWrite property returns or sets the characters that are recognized as
token-delimiter characters, that is, as single-character delimiters that are
also tokens themselves.
As a delimiter, a token-delimiter character is a non-included boundary at the
end or beginning of a token, unless the character is part of a quoted region
(in which case it is treated as a non-delimiter character).
This readWrite property returns or sets the Boolean value that indicates
whether to convert returned, non-quoted, tokens to all-lowercase characters.
The default value for a new tokenizer is False.
This readWrite property returns or sets the Boolean value that indicates
whether to convert returned, non-quoted, tokens to all-uppercase characters.
The default value for a new tokenizer is False.
The UnknownStatistic exception class describes an exception associated with
finding a string identifier that is not a valid or not an appropriate
Model 204 statistic name.
To produce an UnknownStatistic exception, you typically use a User Language
Throw statement with an UnknownStatistic constructor (New).
For example, the following statement throws an UnknownStatistic exception
for the value ABCD:
In addition to the New constructor that creates an object instance,
the class includes a Name property that returns the invalid statistic name.
Constant methods are methods that belong to system classes but are unique
because they are evaluated at compilation time.
These methods require constant inputs and may have no parameters,
but they have no run-time overhead.
For example, the following Constant method sets %x to a string with hex value x'0678':
The hex conversion is done at compilation time.
The method in this example (named X)
is a compile-time-only equivalent of the String intrinsic class HexToString method.
As other intrinsic methods,
the term “method object” is used for the constant value to which a Constant method is
applied, even though the value is not really an object.
Unlike other intrinsic methods, Constant methods may be invoked only against constants.
A variable as method object is not allowed:
Also, a statement like %x = 1234:x is not allowed, because a Constant method
requires the constant to have the correct datatype (in this case, String).
Once a Constant method is evaluated, the expression compilation is
replaced by the constant result of the evaluation, and all intermediate
work quads/variables are deleted.
Thus, '0d25':x is basically a hex constant.
The X function and the Unicode U constant function are
the only Constant methods as of Sirius Mods version 7.3.
Multiple new methods are added, as described in the following subsections.
Many of the examples use the PrintText statement, which was introduced
in Sirius Mods version 7.2 and is described in the
Janus SOAP Reference Manual.
This function returns a number that is the absolute value of the method object.
This function returns a number that is the natural anti-logarithm (or exponential)
of the method object value.
The result is the natural logarithmic base (e) raised to the power of the method object value.
AntiLogE is a synonym for AntiLog.
The AntiLog function is an object-oriented version of the $EXP function, which is described in the
Sirius Functions Reference Manual.
This function returns a number that is the base-10 anti-logarithm (or 10's exponent)
of the method object value.
The result is (10), the base-10 logarithmic base, raised to the power of the method object value.
The AntiLog10 function is an object-oriented version of the $EXP10 function, which is described in the
Sirius Functions Reference Manual.
This function returns a number that is the base-2 anti-logarithm (or 2's exponent) of the method object value.
The result is (2), the base-2 logarithmic base, raised to the power of the method object value.
The AntiLog2 function is an object-oriented version of the $EXP2 function, which is described in the
Sirius Functions Reference Manual.
This function returns the integer part of the result of dividing the method object by the method argument.
The numbers to be divided are first rounded to the nearest integer, including zero.
Any remainder from the division is ignored.
This function converts an integer to its binary string representation.
Only integers that convert to a string no longer than four characters are allowed.
This function returns a boolean value that indicates whether
the method object value, rounded to an integer, is prime.
This function returns a number that is the natural logarithm
(the logarithm base-e) of the method object value.
LogE is a synonym for Log.
The Log function is an object-oriented version of the $Log function, which is described in the
Sirius Functions Reference Manual.
This function returns a number that is the logarithm base-10 of the method object value.
The Log10 function is an object-oriented version of the $Log10 function, which is described in the
Sirius Functions Reference Manual.
If number is not greater than zero, the request is cancelled.
This function returns a number that is the logarithm base-2 of the method object value.
The Log2 function is an object-oriented version of the $Log2 function, which is described in the
Sirius Functions Reference Manual.
If number is not greater than zero, the request is cancelled.
This function returns the remainder from the division of the method object by the method argument.
The numbers to be divided are first rounded to an integer, including zero,
so the remainder is always an integer or zero.
Mod is a synonym for Modulus.
This function returns the next prime number after the method object value.
The method object value is initially rounded to the nearest integer before the next prime is determined.
This function returns the prime number that immediately precedes the method object value.
The method object value is initially rounded to the nearest integer before the preceding prime is determined.
This function returns a number that is the method object value
raised to the float power specified by the method argument.
The ToFloatPower function is an object-oriented version of the $RXPR function, which is described in the
Sirius Functions Reference Manual.
Consequently, you should generally use ToIntegerPower unless you are working with Float powers.
This function returns a number that is the method object value
raised to the power specified by the method argument.
The argument value is initially rounded to the nearest integral value.
ToPower is a synonym for ToIntegerPower.
The ToIntegerPower function is an object-oriented version of the $RXPI function, which is described in the
Sirius Functions Reference Manual.
If number is 0 and exponent is less than or equal to 0, the request is cancelled.
Multiple new methods are added, as described in the following subsections.
Many of the examples use the PrintText statement, which was introduced in Sirius Mods version 7.2
and is described in the Janus SOAP Reference Manual.
This function treats a string as if it were binary and converts it to an integer.
The string may contain no more than four characters.
The Center function is introduced.
For a given input string and suitable specified length, this function
returns a string of the requested length that has the original string
embedded in the center.
If the requested length is larger than the length of the input string,
pad characters are added to the input string to produce the returned string.
If the requested length is shorter, the input string's front and end are cropped
to produce the returned string.
Centre is a synonym for the Center function.
The Char function returns one byte of the method object string, at the
position requested by its argument.
If the position exceeds the length of method object string, the request is cancelled;
otherwise, Char is the same as the Substring function with the given position
argument and with the length argument set to 1.
This function returns a Boolean value that indicates whether the method object
string is matched by one of the strings in an input list of strings.
The input list of strings is concatenated in a single delimited longstring
argument to the method.
A returned value of True signals a successful match.
Available to Janus SOAP or Janus Network Security users,
this function returns the 16-byte (always) binary string that is the
MD5 digest (hash) of the method object string.
MD5 (Message-Digest algorithm 5) is a well-known cryptographic hashing function
which is used in the Janus Network Security product for digital signatures.
A complete explanation of MD5 hashing can be found at Wikipedia
http://en.wikipedia.org/wiki/MD5.
The 16-byte MD5 hash of a string is typically expressed as a 32-digit hex value.
In the following example, the output string from the MD5digest method is converted to hex using the
stringToHex intrinsic method:
This function returns a binary string that is the method object string encrypted or
decrypted with the specified RC4 encryption key.
The length of the returned string is the same as that of the object string.
RC4 is the default stream cipher (algorithm) used in Janus Network Security, and it may be used
by customers who license Janus Network Security or Janus SOAP.
RC4decrypt is a synonym for RC4encrypt; you can use the RC4decrypt synonym to
“document” that you are decrypting rather than encrypting in a call.
RC4 is a two-way, or symmetric, cipher, so encrypting a string with a key and then
encrypting the result of that encryption with the same key produces the original string.
That is, the following assertion should always hold:
The Replace method replaces one or multiple occurrences of a substring of an
input string (the method object) with a substitute string, and it returns the
modified version of the input string.
The Remove method removes one or multiple occurrences of a specified substring
from an input string, and it returns the modified version of the input string.
The Reverse function returns the characters in the method object string in right-to-left order.
Available to Janus SOAP or Janus Network Security users, this function returns
the 20-byte (always) binary string that is the SHA digest of the method object string.
SHA (Secure Hash Algorithm) is a set of cryptographic hashing functions.
SHAdigest provides
The ToUpper and ToLower functions return the alphabetic characters in the
method object string as all-uppercase or all-lowercase characters, respectively.
Non-alphabetic characters are returned as is, and the input string undergoes no other change.
The Translate method for longstrings is a method that is roughly
equivalent to $lstr_translate.
The Translate method takes a CharacterMap object as input.
A CharacterMap object maps In (“input table”) characters to Out (“output table”) characters.
In the following request, a's are translated to B's,
and c's are translated to d's, as dictated by the character mapping in %map:
The result is:
This function removes the whitespace characters from the method object string and it
returns the resulting string.
Options are available to:
New with this release, Collections may be members of Collections.
The members of a collection of any type (ArrayList, NamedArrayList,
FloatNamedArrayList) may themselves be collections of any single type.
To declare a collection of a collection, you name the container collection,
then as its type you fully identify the member collections.
For example:
As this declaration suggests, the collection members must all be the same
type of collection and item datatype.
Collections of collections are otherwise not different from other collections,
although referencing them is more complicated.
To operate on an item in a member collection, you might need to identify which
item it is in its array, as well as which item the array is in the containing array.
For example, to update the items in %scores, an Arraylist of Float,
you might use:
To perform a similar operation for the items in %AllScores, an Arraylist
of Arraylist of Float, you require an additional loop:
And for collection %x, a NamedArrayList of NamedArrayList of Float,
you might specify the following
to print the value of the bar item of the namedArraylist
whose item name in %x is foo:
If you use the syntax of the New function that explicitly indicates the class for
a collection of collections, both the collection and item datatypes must be
specified just as on the collection variable declaration:
This method returns the Model 204 User statistics for the thread associated with the daemon object.
It is useful for metering a daemon or for determining table usage by a compilation done on the daemon thread.
The daemon cannot be running asynchronously when this method is invoked.
The method takes no arguments and returns a UserStatistics object.
This method returns in a Janus SOAP XmlDoc object the fields and values of
the method Record object.
The method has options that let you:
The default is to display the field names as uppercase XML element names,
with field values as XML text; for example:
Usage Notes
No locks are required for a sorted record or in single-user mode.
Examples
The display of field data below is produced
by the following request
The following are sample results:
The default value of the SCRNSTBL user parameter is changed from 4096 to 6144.
SCRNSTBL specifies the maximum amount of STBL space available to an application
that uses a Screen object.
Prior to this release, the ToString method was the only way to return a string
representation of the value of a Janus SOAP ULI enumeration.
As of Sirius Mods 7.3, however, you no longer need to explicitly specify
ToString to print the value of a system or user-defined enumeration.
You can now simply print (or audit) the value of an enumeration,
as shown in the following example:
The Print and PrintText statements above produce these results:
In addition, the implicit ToString feature extends beyond enumerations:
upon any attempt to print or audit any object value, Janus SOAP ULI will try to apply a
ToString method to the object.
If the object is an enumeration (as shown above) or is an instance of a class that has a
ToString method (say, a user-defined class) a ToString is implicitly
applied and the result is a successful print or audit of the object value.
For example, the user-defined class in the following request includes a
ToString method:
If the object you try to print or audit directly is not an enumeration or is
an instance of a class (system or user) for which no ToString method is written,
you receive a compilation error.
For example, if %sl is a StringList object, no user ToString method exists,
and your request contains a Print %sl statement,
you get a message like the following:
The following sections describe changes in the Janus SOAP Xml API
in this release.
A pervasive change to XML processing in Janus SOAP is related to support of
the full 8-bit ASCII (ISO-8859-1) character set, that is, all Unicode code points with
a value less than U+0256 (see Unicode).
The changes to XML processing for full 8-bit ASCII character set support
are described in this section.
Some of these changes can cause compatibility issues, please refer to the
Notes for Sirius Mods Version 7.3
for more detailed information.
Previously, the XPathOrder property was available (with a default value
of Unicode) to allow EBCDIC ordered string comparisons in XPath.
This has now been removed, and it is a compatibility issue.
Previously, setting the InvalidChar property of an XmlDoc to Allow
let you store any EBCDIC character in the value of an Attribute
or Text node (using any “storing” method, such as Value or AddElement).
This toleration of any character did not apply to deserialization.
Version 1.1 of the XML standard has a different approach than XML 1.0 regarding
valid characters.
For deserialization, it allows a character reference to any character, in particular including control
characters (for example, ) — except not for the null character (x'00').
Therefore, in view of this loosening of the validity standard, the InvalidChar property
has no effect in version 7.3 of the Sirius Mods, and it is now deprecated.
That is, Sirius recommends that InvalidChar not be used, and at
some future date it may be removed from the Janus SOAP XML API.
In all cases in version 7.3, Janus SOAP deserialization allows references
to all non-null characters,
except those Unicode/ASCII characters that do not translate to an EBCDIC character.
(With the default Unicode-to-EBCDIC table, the only characters
that do not translate to an EBCDIC character were also disallowed —
as “control characters” — in previous versions of Janus SOAP.)
Any “storing” method in version 7.3 allows the storing of any non-null
EBCDIC character that translates to Unicode.
Note:
This change in character validity is a compatibility issue.
Previously, if the InvalidChar property is set to Allow, you were able to store any EBCDIC
character, including the null character and including a character that does not translate to Unicode.
Since the design of XML is to be human-readable, the serialization of
all control characters (for example, U+0008, the Backspace character)
now uses a character reference (in this example, ).
This is a compatibility issue.
Previously, when a control character (other than tab, carriage return, or linefeed)
occurs in an XmlDoc (which could only happen if it were added using a “store”
method while the XmlDoc InvalidChar property is set to Allow), it
is serialized “directly”, using the octet containing the control character.
When translating between EBCDIC and ASCII/Unicode,
the Janus SOAP XML API now correctly does the following:
Previously, all translations in this ASCII range (X'80' – X'FF') except
X'A2' were incorrect (Unicode U+0080 - U+00FF: 8 bit ASCII mentions some of the
types of characters in this range).
For translation from EBCDIC, many code points now translate to a character in the range
X'85' – X'FF'; previously these EBCDIC code points
did not translate to an ASCII/Unicode character.
Note that the above comments about translations apply for most of the
codepages, with no additional customization.
Both the codepage to use and any additional customization can be specified
during Model 204 initialization with the UNICODE command
(see UNICODE command).
When this XmlDoc property is
set to True, you can deserialize an XML document into the XmlDoc even
if the document contains elements whose names use the reserved character
sequence xml (in any case) as the start of the element name.
Elements whose name begins with “xml” were restricted due to
the following excerpt from the XML standard:
Therefore you should use care with element names: using
an element name such as XML makes you vulnerable to a change in the
standards that would leave your document incompatible with them.
Note:
This property does not allow the AddElement method to add an element
with a name that starts with “xml”.
However, it is easy to use the LoadXml method to accomplish this:
Two new methods are added to the XmlDoc and XmlNode classes: ToXpathString
and ToXpathStringList.
ToXpathStringList is simply a synonym for the existing XpathNodeID method.
ToXpathString performs the same function as XpathNodeid (returns
an absolute XPath expression), but
instead of returning a StringList like ToXPathStringList, it returns a string.
If the Stringlist returned from ToXpathStringList would contain multiple items,
the string returned from ToXpathString in the same context would
contain blank-delimited substrings.
The ToXpathString syntax, where %str is a string or longstring variable
and nr is an XmlDoc or XmlNode object, is:
The new OmitNullElement option of the Xml serialization methods
(Print, Serial, WebSend, Xml) has the following restrictions and effect:
For example, given the following User Language fragment:
The resulting output is:
Traditional representation of characters has relied on 8-bit character codes,
but an 8-bit character code only allows representation of at most 256 characters.
With the need to represent
many special-purpose characters
and
characters of many languages, 8-bit character sets have
become strained to represent all necessary characters.
This has led to the use of multiple 8-bit code sets: in EBCDIC, using multiple
code pages, and in ASCII, a variety of ISO-8859-x character sets.
It has also led to the use of escape sequences where it is absolutely necessary
(for example, with Kanji characters) to use more than 8 bits to represent a
single character.
The Unicode standard (or ISO-10646) establishes a new character encoding scheme,
and various representations for character codes, to allow for over 1 million
characters.
The first Unicode standard was published in 1990 (Unicode 1.0) and has evolved
since then.
The list of Unicode versions is available on the Internet at:
http://www.unicode.org/versions/enumeratedversions.html
A useful table of Unicode characters for Unicode Version 5.1 can be found at:
http://unicode.org/Public/5.1.0/ucd/UnicodeData.txt
Unicode is becoming ubiquitous; it is used as the encoding scheme on most non-mainframe
applications, and over time, more and more Model 204 applications will need to accept
Unicode data.
Unicode also provides an important reference point.
For example, you can discuss the square
bracket character codes, U+005B and U+005D, without concern about the code page
being used.
Version 7.3 of the Sirius Mods introduces support for Unicode, consisting of:
Before the complete discussion of Unicode and its support in version 7.3 of the
Sirius Mods, some applications of the UNICODE command are presented.
For the full syntax of the UNICODE command, see UNICODE command.
A number of incorrect translations involving XML in earlier versions of the Sirius Mods
have been corrected in version 7.3.
These changes are intended to improve the quality of data that is handled by the Janus SOAP
processing of XML documents, but there are some cases
in which the changes can cause problems for customer applications.
A discussion of some common problems and possible workarounds follows.
An invertible translation occurs when a code point in one code set translates to a
code point in another code set, and the translation of that other code point
is the original code point.
It is strongly desirable that all translations being used are invertible.
This helps enforce data quality, simplicity of application programming,
understandability of the Unicode translation tables, and consistent
“round-tripping” of XML documents.
All translations in the supported codepages are invertible.
Note:
Standardizing on a single code page and correcting all User Language code to use that
code page will ensure invertible translations and is the long term direction that
Sirius recommends.
However, because the correct translation of “special characters” has only
recently become important, it is quite possible that a variety of translation issues
have crept into User Language applications.
The following discussions of workarounds show how non-invertible translations can be
used to temporarily bypass common translation issues.
It is important that you recognize these as temporary workarounds and that the d
best long term solution is to achieve fully invertible translations using a standard
codepage.
In the UNICODE command, an invertible translation, or a two-way translation
or mapping, is specified with the Map form of the UNICODE updating command.
(Note, however, that specifying a Map subcommand can cause an existing
mapping to become uninvertible; see Vertical bar vs. broken bar.)
When a translation is uninvertible, unusual results can occur, and there
can be cases of this in ealier versions of Janus SOAP.
For example, if you employ the dual square bracket workaround described below and
your base codepage is 1047, then the following request fragment shows how
a character value can change merely by being serialized and then deserialized:
If you are receiving MSIR messages indicating
“error processing XPath expression,” especially if that message
is preceded by a message indicating “Invalid name character,”
you may be using a different set of EBCDIC square brackets than those
used by default in XML processing in version 7.3 of Janus SOAP.
Probably the best way to determine this is to run the following ad hoc request:
or, in the UK:
If this resolves your XPath problems, all applications are likely to be
consistently using square brackets from codepage 0037 or 0285.
If there are still some XPath errors, then the applications may
be inconsistent, with some using the 0037/0285 brackets, and some
using the 1047 brackets.
If either of the following is true, you may benefit from temporarily using
both common sets of square brackets in the Unicode tables:
In the longer term, you should attempt to standardize the codepages used
by User Language programmers and correct the square brackets in User Language applications
so that you can remove this workaround.
If your base codepage is 1047,
you can use the following commands to add the alternate square brackets:
If your base codepage is 0037,
you can use the following commands to add the alternate square brackets:
It is somewhat unusual to have mixed codepages among User Language programmers
when the base codepage is 0285, but since the square bracket mappings for 0285 are the
same as 0037, you can use the same approach as shown above for 0037.
For the sake of consistency, you should change “0037” in the comment
to “0285”.
The common translations for the vertical bar character (|)
and for the broken bar character
(¦)
are shown in the following
excerpt of the output of the UNICODE Display Codepage xxxx command
(where xxxx is any of the common codepages: 1047, 0037, or 0285):
For these common codepages, the above translations are used in
version 7.3 of Janus SOAP for XML processing.
However, in earlier versions the translations are not correct:
Note: This is but one example of the fact that in prior versions of the Sirius Mods,
almost all translations of ASCII code points greater than X'7F' are incorrect.
The concern is that you may have applications that depend on these incorrect translations.
In the following discussion, the term “solid bar” is used for the
vertical bar character, to help contrast it with the broken bar character.
Search your applications for instances of broken bars:
The proper long-term fix to your application is probably to use
solid bar rather than broken bar in the above two cases.
The next two subsections discuss the technique for searching your applications for broken bars,
and a workaround to use if you are not able to fix your applications at the time that you install
version 7.3 of the Sirius Mods.
Note: Probably due to odd behavior in some tn3270 packages, you should place the cursor
after the broken bar in the search string and delete the blank.
If you have applications with broken bars that need to be fixed when using version 7.3 of
Janus SOAP, but you are unable to make those changes at that time, you can use the
UNICODE command as follows to modify the Unicode tables to mimic some of the translations
used by earlier versions.
Place the following lines in your Model 204 initialization stream:
In EBCDIC, an 8-bit character set, code points vary from X'00'
through and including X'FF'.
As an example, the character “A” is mapped to the
EBCDIC code point X'C1'.
In ASCII, also an 8-bit character set, code points also vary from X'00'
through and including X'FF'.
As an example, the character “A” is mapped to the
ASCII code point X'41'.
The first 128 code points (X'00' through X'7F') have well-defined mappings;
for code points X'80' through X'FF', the mappings depend on the “flavor”
of ASCII being employed (ISO-8859-1 through ISO-8859-9).
In Unicode, the customary way to represent a code point is U+hhhhhh,
where hhhhhh is the hexadecimal representation of the value of the
code point.
As an example, the “trademark” character is mapped to the
code point U+2122.
Note that the first 256 code points in Unicode have the same mappings as the
code points in ISO-8859-1; for this reason, we may use the U+hh notation to
refer to ASCII code points.
Some characters are simple to deal with; here are some
common EBCDIC and corresponding ASCII mappings (note that these ASCII code points
are all less than X'80'):
In previous versions of the Sirius Mods, all translation between EBCDIC and ASCII
(other than the customization available with the JANUS LOADXT command)
was based on tables that ignored all but one ASCII code point greater than X'7F'
(the code point for the “cent sign”).
Please refer to the section titled “Corrected translations between ASCII/Unicode and
EBCDIC” in the Notes for Sirius Mods Version 7.3
for information about various translations that have been corrected.
As of 7.3 of the Sirius Mods, parsing an XML document and
non-EBCDIC serialization of an XmlDoc is
performed using the corrected translation tables.
The actual translations used can be controlled with the UNICODE command
during Model 204 initialization, chiefly by selecting the codepage to use.
The common codepages are:
EBCDIC column 5 of that yellow card corresponds to codepage 1047.
Here are some examples of Unicode characters in the range U+80 through U+FF:
Version 7.3 of the Sirius Mods introduces a new intrinsic data type, Unicode.
A string of type Unicode can contain any of the characters in Unicode's Basic Multilingual
Plane (any of the code points U+0000 through and including U+FFFD) which covers most languages and characters.
Each character in a Unicode string occupies 2 bytes.
Values X'D800' through X'DFFF' are used in Unicode
for surrogate pairs (not supported in version 7.3 of the Sirius Mods).
Values X'FFFE' and X'FFFF' are not characters.
So the valid code points of a character in a Unicode string are as follows:
Any Unicode character can be represented using UTF-8 or UTF-16.
As their names imply, these representations use items of 8 or 16 bits in length, respectively.
When using one of the User Language intrinsic functions (Unicode intrinsic functions)
to convert between a Unicode string and a UTF-8 or UTF-16 stream, UTF-8 or UTF-16 is stored as
a byte stream, in a User Language String or Longstring value.
For conversion from a Unicode string to UTF-8, each character of the UTF-8 representation
uses from 1 to 3 bytes per character.
This is the most common encoding of Unicode sent over
the Internet and usually results in the most compact byte stream.
For conversion from a Unicode string to UTF-16, each character
of the UTF-16 representation uses 2 bytes per character.
For most commonly used characters, this representation is longer
than a UTF-8 representation.
User Language programs and Janus Web Server operations have employed translation between
ASCII and EBCDIC for many years.
Unfortunately, these translations have historically been incorrect for many seldom-used code points.
Version 7.3 of the Sirius Mods corrects the translations for XmlDocs, and it also provides two
String intrinsic functions to perform correct translation:
EbcdicToAscii AsciiToEbcdic.
Since they are both 8-bit code sets, in principle there need not be untranslatable characters
between ASCII and EBCDIC.
In fact, however, there are about 30 code points in each which represent characters that do not
have representations in the other character set.
For example, the EBCDIC code point X'FF' is the EO (“Eight Ones”) control character; there is no
ASCII EO control character (ASCII X'FF' is the small letter “y with diaeresis”
which corresponds to EBCDIC X'DF').
Besides providing correct translations when they exist, the EbcdicToAscii and AsciiToEbcdic
functions throw an exception
(CharacterTranslationException exception class)
when a character cannot be translated.
AsciiToEbcdic alternatively allows encoding of untranslatable
characters using the XML “character reference” mechanism.
UnicodeToEbcdic also allows this.
The character references can be converted back to ASCII or Unicode
by, respectively, EbcdicToAscii or EbcdicToUnicode.
These methods treat their method object as a string of type Unicode.
This function gets the Unicode string resulting from applying the
Unicode replacement table to the input Unicode string.
Where:
By default (that is, when there is no Unicode replacement table),
this function merely copies its input.
Example:
Note that an updating UNICODE command is shown here “in-line”
with a User Language request, to make the example concrete.
In actual usage, updating UNICODE commands should only be issued
from your Model 204 initialization stream.
This function converts a Unicode string to EBCDIC.
Where:
This function throws a CharacterTranslationException exception
(CharacterTranslationException exception class)
if an input character cannot be translated or encoded.
Note: Unless the CharacterEncode argument is used, or you want to Catch a
CharacterTranslationException, this function is generally not needed, because a Unicode
string is implicitly converted to EBCDIC when used in an EBCDIC context.
Example:
This function converts a Unicode string to a UTF-16 Longstring byte stream.
Where:
Example:
This function converts a Unicode string to a UTF-8 Longstring byte stream.
Where:
This method may throw a CharacterTranslationException exception
(CharacterTranslationException exception class).
Example:
The result of the above fragment is:
This function finds the character position of the first character
in the input Unicode string that is not translatable to EBCDIC.
Where:
Example:
The result of the above fragment is:
These methods return a string of type Unicode.
This function converts an EBCDIC string to Unicode.
Where:
The default is False.
This function may throw a CharacterTranslationException exception
(CharacterTranslationException exception class).
Example:
The result of the above fragment is:
Similar to the hexadecimal constant function X,
U is a constant function that allows you to specify a Unicode constant.
Where:
Example:
The result of the above fragment is:
This function converts a UTF-16 Longstring byte stream to Unicode.
Where:
This function may throw a CharacterTranslationException exception.
Note:
The input UTF-16 stream may contain a Byte Order Mark (U+FEFF).
If one is present, that controls the conversion from UTF-16 to
Unicode.
If a Byte Order Mark is not present, the input stream is considered
to be a Big Endian stream, that is, it is the same as if the stream
were preceded by the two bytes X'FE' and X'FF', in that order.
For example:
This function converts a UTF-8 Longstring byte stream to Unicode.
Where:
This method may throw a CharacterTranslationException.
Example:
The result of the above fragment is:
These intrinsic String methods rely on the Unicode translation tables as optionally modified by the
UNICODE command.
This function converts an ASCII (ISO-8859-1) string to EBCDIC.
Where:
This function may throw a CharacterTranslationException exception
(further described CharacterTranslationException exception class).
Example:
This function converts an EBCDIC string to ASCII (ISO 8859-1).
Where:
The default is False.
This function may throw a CharacterTranslationException exception.
Example:
The result of the above fragment is:
This function removes the bytes from the EBCDIC input string
that do not translate to Unicode.
Where:
This function is useful because there is no way to convert
to Unicode an EBCDIC string that contains untranslatable characters.
Example:
The result of the above fragment is:
This function replaces any bytes from the EBCDIC input string
that do not translate to Unicode.
Non-translatable bytes are replaced with the character specified as the
function argument.
Where:
This function throws a CharacterTranslationException if the
argument character is not translatable to Unicode.
EbcdicTranslateNonUnicode is useful because there is no way to convert
to Unicode an EBCDIC string that contains untranslatable characters.
Example:
Various methods throw a CharacterTranslationException exception
when they encounter character translation problems.
To avert request cancellation, you can catch such an exception,
optionally catching to an object of this class.
This class has the following read-only properties:
This class has the following constructor:
The values of this class are returned by the Reason function
of the CharacterTranslationException exception class.
The enumeration values in this class are as follows:
As do all enumeration classes, this class also contains
the ToString method, which converts an enumeration value to a
character string whose value is the name of the enumeration value.
The UNICODE command is used to manage the Unicode tables, effecting the following:
In the descriptions of the UNICODE command that follow:
The command descriptions below use an initial capital letter to indicate
a keyword, and they use all-lowercase letters to indicate a term that is
substituted for a particular value in the command.
The various forms of the UNICODE command are:
For the updating subcommands:
You may test UNICODE command changes as part of a “private” test
Online (that is, one which only you access), so no other users
are running while you issue updating forms of the UNICODE command.
The various subcommand values of the updating forms of the
UNICODE command are:
The length of the resulting Unicode replacement string is limited to
127 characters.
No character in the replacement string
may be the U=hex4 value in any Rep subcommand.
For examples showing the use of the UNICODE command, please refer to the
Notes for Sirius Mods Version 7.3.
Please refer to the
Notes for Sirius Mods Version 7.3 for a discussion of any compatibility
issues with prior versions of the Sirius Mods and any bugs which have
been fixed in this version, but had not, as of the date of this release, been fixed
in the immediately prior version.
These three new Html/Text statement To options let you direct
the contents of an Html/Text block or line to the destinations
associated with the User Language statements Audit, Print, or Trace.
Respectively these destinations are
the journal/audit trail, the current print output device, or the
trace destination (which may be the audit trail, print device,
or CCATEMP trace table, or a combination of them).
These new keywords act like the Data keyword:
they denote that the HTML block consists of only the text that follows
the keyword on the logical line.
Further, they identify the output destination of the line's text,
implying To Audit, To Print, and To Trace, respectively.
These options are simply shortened forms of Text Audit, Text Print,
and Text Trace, respectively, that place the action first.
These are likely to be
the common way of auditing, printing, or tracing text when no additional Text
statement options need to be specified.
When this keyword is specified in a Text statement, the literal data in the
statement is stored in CCATEMP rather than STBL, avoiding excessive demands
on STBL space.
Designed for a Text statement with an unusually large amount of literal data,
this is an alternative to setting the X'01' bit of the SIRCOMP user parameter
(which performs the same function).
In a Text/Html statement block,
content enclosed in expression start and end characters is evaluated
as if it were the right-hand side of a User Language
assignment, and the resulting value
takes the place of the expression (and expression start and end characters)
in the HTML block.
For example, printText {$date} produces 08-02-29.
The special expression {~}, however, directs the compiler to replace
this expression with
the literal chartacter content of the next expression appearing on the same line.
So printText {~} {$date} produces $date 08-02-29.
The evaluation of the expression following {~} is carried out as usual.
The Longstring datatype is not supported inside images.
However, Sirius Mods version 7.2 introduces support for image items with
length greater than 255.
The following is an example of a declaration of a 300-byte image item:
Report writers
can use a lot of virtual storage which can adversely effect other users in an Online.
The new CURREP31, CURREP64, HGHREP31, and HGHREP64
system parameters indicate the current and greatest amounts of
31-bit and 64-bit virtual storage used in the Model 204 run by report writers.
The MAXREP31 and MAXREP64 parameters indicate the maximum amount allowed.
The only existing report writer is invoked by the SirTuneReport method of
the Dataset class.
That method is called by the SirTune product, and it can also be called directly.
Only the parameters that specify the maximum amount of storage (MAXREP31 and MAXREP64)
are resettable.
The JANUS TCPLOG subcommand lets you capture all input
and output streams for a particular Janus port.
The captured streams are written to a sequential file.
One suggested use for a file of captured streams is to provide “playback”
for customer-written applications that simulate real workloads during testing
of new system or application code.
Details of the format of the log file are available in the
Janus TCP/IP Base Reference Manual.
SirScan now supports the use of z/OS large datasets for CCAJRNL.
The Jump feature lets you alter the normal flow of program execution in the Debugger
by invoking an immediate transfer of control to a specified statement
and then executing that statement.
The target statement may be earlier or later in the request than the current statement.
You invoke a jump by right-clicking a line in the Client's Source Code
window or by using commands in a macro or mapped button or hot
key.
The commands offer additional functionality: jumps to a line
number, jumps that are a number of lines relative to the
current line, and jumps to lines that contain specified strings.
When white listing is on, the Debugger filters procedures
automatically, stopping to interactively debug only the
requests that are on the white list.
A non-listed procedure executes normally, but it is not
interactively debugged, and the Debugger Client's Audit Trail displays
are immediately refreshed (as of Sirius Mods 7.2) to specify
that such a procedure has been “skipped.”
Once the Debugger's White List processing is invoked, it continues in effect
unless you explicitly turn it off or until you exit the Debugger
Client.
It is manually interruptable, however, as of version 7.2 of
the Sirius Mods: the mappable Client command breakOnNextProc
lets you override the White List to interactively debug the
next procedure.
These features were added by update builds of the Client
subsequent to the release of Sirius Mods 7.1.
These macro-only commands are added:
assert failure messages are displayed in the macro
console, if it is open.
Otherwise, they are displayed in a Windows message box.
This feature lets you
pass an argument to a macro command at the time the macro runs.
You can use either a standard macro variable or a standard macro
function:
The client obtains the substitute value from the Variable or Field
text area, from the Macro Command Line tool, or from a mapped macro
command line.
When a macro command that contains a &&prompt
place of the command argument is executed, the Client
displays a dialog box which uses promptString
to solicit the value to substitute for the command argument.
The Macro Console is an independent window that logs
informational messages about the Debugger macros you run.
It is invoked from its option in the Client's Macros menu.
When a macro is called, the Macro Console
displays information about the macro, including its starting
and stopping, as well as any error messages.
The Macro Command Line menu option opens
the Macro Command Line dialog box, which provides a command line
interface for running macros.
This dialog box
stays available unless explicitly closed, so it is a
step-saver for macro testing.
A ... macro running indicator is now displayed on the Client's
title bar while a macro is running or waiting.
Prior to this feature, you add a global variable to the Client's
Watch Window by specifying the variable name (in any case) preceded by
“G.” or “g”.
Then the Debugger searched for (only) the variable with the
all-uppercase form of the variable's name.
As of Sirius Mods 7.2, if you enclose the variable name in single quotation
marks, however, the Debugger will search for exactly the case of
the characters that you specify.
These two changes to the Search feature enable
keyboard-invoked consecutive searches:
Note:This introduces a small upward incompatibility.
These mappable commands are added:
The new Data Display menu item Add Watch on Current Line has the same
effect as this command.
The new Breakpoints menu item Toggle Breakpoint on Current Line
has the same effect as this command.
The new Execution menu item Reload White List
has the same effect as this command.
The new Execution menu items Turn On White List and
Turn Off White List have the same effect as these commands.
Having the same effect as the Run Until Procedure button.,
this command was formerly a macro-only command.
The new Execution menu item Run Until Proc
has the same effect as this command.
An exception to ordinary request-cancellation handling is added
for the purpose of ON UNIT code debugging.
Instead of stopping you from stepping through a request when the request
has a canceling error, the Client lets you continue in the exceptional
case of the following error only
(which occurs within a User Language ON UNIT):
The DEBUGGERSERVER and DEBUGGERCLIENT Janus ports defined for the Debuggers
are now reported as DEBUGSRV and DEBUGCLI ports, respectively, in the
output from JANUS STATUS and JANUS DISPLAY commands.
Formerly, they were reported as SRVSOCK and CLSOCK types.
The Dataset class operates on datasets or streams defined by any of the
following:
The Dataset class uses two class-specific enumerations: the RecordFormat
enumeration, and the DatasetState enumeration.
The RecordFormat enumeration indicates the format of the blocks in the sequential
dataset.
While, strictly speaking, the RecordFormat enumeration actually describes block
formats or maybe file formats, it corresponds to the RECFM value used in DD cards,
ALLOCATE statements, etc., so the term RecordFormat was used.
The DatasetState enumeration describes the current state of a Dataset object.
A newly created Dataset object starts in the Closed state and then changes state
as certain methods are performed on it.
Certain methods are restricted to Dataset objects in a particular subset of
states.
User Language is a legacy programming language for which object-oriented capabilities are a
relatively recent addition.
So, one might expect that strings and numbers are not maintained internally
as objects, since their existence pre-dates objects.
This is in fact the case, though as has been shown, this is largely
irrelevant from a User Language programmer's perspective,
And even if object-oriented capabilities were present in User Language from its inception,
strings and numbers might have been special-cased for efficiency anyway.
However, beyond the internal representation of strings and numbers,
a distinction between User Language and pure object-oriented languages was that
the object:method syntax was not used to manipulate strings and numbers;
instead, strings and numbers were manipulated via $functions.
In Sirius Mods 7.2, this has been changed to allow the
object:method syntax against string and numeric variables and constants.
The following code fragment illustrates how the same operation can be accomplished
via traditional $functions and via object-oriented syntax:
While this might not seem very significant, it provides considerable value:
While it would have been possible to extend $functions to have this same
functionality (much as Sirius Mods provided callable $function support),
it makes more sense to provide it using true object-oriented syntax.
Given that this has now been done, it is unlikely that these capabilities
will ever be added to $functions.
The term “method object” (or “intrinsic method object”) is used for
the value or variable to which an intrinsic method is applied,
even though the value or variable isn't really an object.
This is justified because, strings and numbers can be considered
immutable objects, regardless of their history or internal representation.
For example, in the following case,
%str is the intrinsic method object for the Length method:
Intrinsic methods can be applied to constants, in addition to variables.
For example, the following assigns the length of the string literal
“Whatever” to %x:
As with other methods, the colon that separates the method object from
the method name can be optionally preceded or followed by spaces.
This could be done to enhance readability, or even to split a long line.
The following four statements are all equivalent:
As with most other uses of intrinsic variables or values, if the method
object is of a different type than the data type on which the method
operates, the input value is automatically converted into the target
datatype.
For example, the expression 7/3 clearly produces a numeric
value, but the Left method operates on strings.
So, in the statement:
Because of this automatic conversion, the specific class (String or Float) of
an intrinsic method cannot be determined from the datatype of its method
object.
This means that the class must be determined only from the name
of the method, which means that method names must be unique among all
intrinsic classes (that is, among String, Float, and Fixed).
For example, there may not be a Length method in both the String and
Float intrinsic classes.
In the case of Length, the method is an intrinsic String method.
Float intrinsic methods treat their method object as a Float value.
Any value that is not a Float value is automatically converted before it is
acted on by the method.
This function returns a number that is the square root of the method object.
An attempt to get the square root of a negative number results in request
cancellation.
Intrinsic String methods treat their method object as a Longstring value.
Any value that is not a String value is automatically converted before it is
acted on by the method.
Base-64 encoding is useful for encoding strings that might contain
binary or other characters that could cause problems in certain contexts.
This function returns the unencoded value of a base-64 encoded string.
This function returns the unencoded value of a hex encoded string.
Hex (short for hexadecimal) encoding is usually used for debugging
when there is a concern that non-displayable characters (including
trailing blanks) might be present in a string.
By hex encoding such a string, all non-displayable bytes are converted
to displayable hexadecimal equivalents.
This function returns the left-most characters of the method object string,
possibly padding it on the right.
This function returns the length in bytes of the method object string.
These functions return the numeric position of the first occurrence of one string
inside another.
The difference between the two methods is that for PositionIn, the method
object string is located in the first argument string, whereas for
PositionOf, the first argument string is located in the method object string.
Which is more convenient to use will be application dependent.
This function determines whether a given pattern (regular expression,
or “regex”) matches within a given string according to the “rules” of
regular expression matching.
This method repeatedly applies a regular expression,
or “regex,” to the method object string until it has tested the entire string.
This splits the string into the substrings that are matched by the regex
(the "separators") and the substrings that are not matched.
By default, the method saves each unmatched substring as a separate
item in the StringList result object.
The leftmost unmatched substring is the first item in the StringList, the next leftmost
is the second item, and so on.
A simple application of the method is to extract only the data
items from a string of comma-separated data items.
If the specified regex is a comma, each of the resulting StringList
items will contain one of the data items.
RegexSplit uses the rules of regular expression matching.
This function returns the right-most characters of the method object string,
possibly padding it on the right.
This function returns the base-64 encoded value of the method object string.
This function returns the hex encoded value of the method object string.
This function returns a specific number of bytes starting at a
specific position in the method object string, possibly padding it on the right.
To diagnose or correct or reduce the damage from run-time errors
that occur in places in a program where the use of a request
cancellation, return-value processing, or output-parameter processing
are insufficient, the Janus SOAP ULI introduces exception handling.
Exception handling consists of three parts:
Although the Janus SOAP ULI exception handling support is very similar to many other
object-oriented programming languages, such as Java or VB.Net,
each language's implementation of exception handling has
subtle or not so subtle differences from the others.
As a significant example,
while many object-oriented languages make all (or almost all) errors exceptions,
Janus SOAP ULI does not.
This is partially because many object-oriented languages are not, strictly speaking,
application languages — in addition
to writing applications in some other object-oriented languages,
one might write programming environments or even operating systems.
As such, a programming environment or operating system must be able to
intercept all errors and try to deal with them, so the object-oriented languages
facilitate this by making all errors catchable.
User Language is an application development language.
While it is theoretically possible to build a program environment in User Language,
or even an operating system, this is not really the focus of User Language and it is
not likely anyone would ever do this.
The User Language programming environment (Model 204, which is not, itself, written in User Language)
is responsible both for the ultimate catching of errors and the providing of
information about the nature of the errors so that they can be corrected.
The kinds of errors that Janus SOAP ULI does not turn into exceptions,
and thus are not trappable, fall into two broad categories:
For example, if CCATEMP fills up, it is exceedingly unlikely that a
request could recover gracefully.
Since CCATEMP is used for so many different things (including record
sets for finds, stringlists, collections, internal storage of objects
swapped out of a server, transaction backout logs, and so on), it would
be very difficult for an application to anticipate all the places that
CCATEMP could fill.
And even if it could anticipate the places, it would be very difficult to avoid
doing anything that might also require CCATEMP.
For example, a class member reference via a null object variable is usually
indicative of a programming error.
Similarly, a reference to an invalid collection item number is also generally
indicative of a programming error.
While there might be error-causing cases of “sloppy” references to
object variables or collection items that you would want to simply catch
when they happen:
The collection of data describing an error situation might be used
immediately after the error is detected, or it might be examined elsewhere.
As such, this error data should be able to persist indefinitely.
Given this requirement, it is clear that the logical place to
hold error information is inside an object.
And the description of the data associated with a particular error would be a class.
Classes that describe trappable error situations are called exception classes.
To a large degree, exception classes are no different from any other class:
User Language exception classes are denoted by using the Exception
keyword in the class header:
One can think of the Exception keyword on the Class declaration
as indicating that the class extends some hidden base class.
You can put the Exception keyword on almost all class declarations;
specifying it removes no capabilities from the class.
Doing so, however, is misleading, since most classes are likely never to be used
to indicate error situations.
In this regard, you can view the Exception keyword on a class declaration as
documentation that a class can be used as an exception class.
While the compiler cannot ensure that a class with an Exception
declaration will be used as an exception, it does ensure that a
class not declared as Exception is not used in exception contexts.
The one case where the Exception keyword is not allowed on class declarations
is in declarations that extend non-exception classes — exception classes
can only extend other exception classes.
When an error situation occurs, the code that detects the situation can do
one of two things:
Note:
In the Janus SOAP ULI implementation of exceptions, exceptions can only
be thrown by methods.
In both system and User Language methods, a thrown exception can only be handled
(caught) by the code that called the method, as opposed to
inside the same method that threw the exception.
The exceptions that might be thrown by a method
must be documented in the method header.
The exceptions thrown by a method are indicated by the Throws
clause in the method declaration and definition header.
For example, if the method Paint might throw a TackyColor and InvalidHexData
exception, it should be declared and defined as:
The keyword and is used to separate the exceptions
that might be thrown by a method.
The method can only ever throw one exception
at a time, and in most cases, it will not throw an exception at all.
The list of exceptions after a Throws keyword is the list of exception
class names.
These class names could be User Language exception class names, or they could be system
exception class names.
If the class is a system class name, it could be fully qualified with the
System: namespace indicator.
For instance, the previous example could be written as
As with most method descriptions, the Throws clause on a method declaration
and definition must match exactly.
Methods that implement an overridable method cannot throw any
exceptions not thrown by the implemented method; however, they do not
necessarily have to throw all the exceptions thrown by the implemented
method.
Once a method declaration indicates the exceptions it might throw,
that method could then throw the exception with the Throw statement.
The Throw statement must be followed by an instance of the exception
class being thrown.
For example, if the method header contains
An attempt to throw an exception object whose class does not match one
of the classes listed in the method declaration's Throws clause results
in a compilation error.
Exception classes can extend other exception classes.
As such, the class of an object specified in a Throw statement does not
have to match any class in the method's Throws list exactly —
it can be of an extension class of one of the Throws list classes.
Because an extension class can, itself, be extended, and because of
multiple inheritance, this means that a Thrown exception object might
match multiple classes in a method's Throws list.
The thrown (and so catchable) class is the first class in the Throws
list that matches the object in the Throw.
That is, the first class in the Throws list that exactly matches the thrown
object's class or that is a base class of the thrown object is used as the thrown
class for the method caller.
Without any action on a method caller's part, a thrown exception is,
for all intents and purposes, a request cancelling error.
To prevent the request cancellation, an exception must be “caught.”
This is achieved by the use of a Try/Catch block.
A Try/Catch block consists of two parts.
The first, the Try section contains one or more User Language statements that
might result in an exception.
The Try section is then followed by one or more Catch sections, each
one of them handling (catching) a particular class of exception.
The following fragment illustrates the use of a Try/Catch block to trap
an exception caused by invalid hexadecimal data:
This example illustrates a few points:
What gets thrown with an exception is an exception object that contains
information about the nature of the exception.
To reference the thrown exception object, you must specify a
To clause, followed by an object variable of the exception class being caught.
For example, if %daemon is a Daemon object and %daemonLost
is an object of the DaemonLost exception class, the following block
catches the exception thrown if the daemon thread was logged
off for some reason, and it displays the output of the last command
up to the point where it logged off:
The following are some differences between the Janus SOAP ULI implementation
of Try/Catch and implementations in other languages.
Outside of these differences, Try/Catch
support in Janus SOAP ULI is very similar to that in other languages.
Like in other languages, Try/Catch blocks can be nested.
That is, a Try/Catch block can be inside the try or catch clause of another
Try/Catch block.
An exception class might want to perform special processing at the time an
exception is thrown:
To provide this capability, Janus SOAP ULI special-cases two method names in a
User Language exception class: OnThrow and OnUncaught.
Both of these methods must be subroutines (as opposed to Functions or
Properties) and cannot have parameters.
The OnUncaught subroutine is automatically called whenever an exception
of the containing class is thrown, and the exception will not be caught.
The OnThrow subroutine is automatically called whenever an exception
of the containing class is thrown, and either the exception will not be
caught and there is no OnUncaught method in the class, or the exception
will be caught.
These two method names have no meaning in non-exception classes.
These methods can be called explicitly, and they can be either Private
or Public (though whether they are Public or Private is irrelevant for
implicit calls when an exception is thrown).
The following illustrates an OnThrow subroutine that makes sure the
exception data is valid at the time an exception is thrown:
The following illustrates an OnUncaught subroutine that logs information
from the exception to the audit trail before allowing the request to be cancelled:
If SirFact is available and capturing dumps for requesting cancelling
errors, all the information one would need is likely to be in the dump,
so there is probably little need to collect extra data in an OnUncaught
subroutine.
There is no way for an OnUncaught or OnThrow subroutine to undo the
effect of the exception, that is, to prevent a request cancellation
if the exception is uncaught.
Both routines, however, can force a request cancellation,
perhaps by using an Assert statement, even if the exception would
have been caught.
If a request cancellation occurs inside on OnThrow subroutine for
an exception that's about to be caught, the catching statements
are not executed, because the request is cancelled before the
OnThrow subroutine returns.
The Throws clause is invalid on an exception class's OnThrow and
OnUncaught subroutines, so these subroutines cannot, themselves,
throw an exception.
As already described, classes that describe trappable error situations are called exception classes.
System exception classes are maintained by the Janus SOAP ULI
environment, while User Language exception classes are
defined and maintained by User Language code.
The system exception classes added in Sirius Mods 7.2 are described in the
following sections.
The DaemonLost exception class indicates that a daemon thread associated
with a daemon object was lost, most probably because of a user restart.
The InvalidBase64Data exception class describes an exception associated with
finding non-base64-encoded data where base64-encoded data was expected,
usually when decoding base64-encoded data.
The InvalidHexData exception class describes an exception associated with finding
non-hexadecimal data where hexadecimal data was expected, usually
when translating the hexadecimal data to something else.
The InvalidRegex exception class describes an exception associated with an
invalid regular expression being passed to a method that takes a regular expression
argument.
The NoFreeDaemons exception class indicates that the Daemon class constructor
was invoked, but there were no daemon threads available to service the object.
When using a class, it is not uncommon to want to perform operations
on objects of the class that are not one of the standard methods
provided by the class.
Before Sirius Mods version 7.2, there were three ways of addressing this:
An enhancement method declaration has the following syntax:
For example, to declare and define an enhancement method version of
an “EveryOther” method, one would do something like the following:
This enhancement method could then be invoked as follows:
Using an enhancement method in a chain of methods makes this point
even clearer:
Enhancement methods are never automatically inherited by extension
classes of the methods to which they apply, regardless of whether
the Inherit keyword is specified on the class declaration for the
extension class.
For example, the EveryOther method
in the preceding section cannot be directly applied
to %mylist if %mylist is actually an object of class Funnylist,
where FunnyList is an extension of class Stringlist.
However, the method can be applied by explicitly specifying
the name of the class to which the method applies:
In some languages this is referred to as casting,
that is, casting a variable as one of its base classes.
You can also explicitly indicate that an extension class is to
inherit a base class's enhancement method with a special form
of the Inherit statement in the Public or Private Shared blocks:
Note: Because an enhancement method is not defined in the class
to which the method applies, it cannot reference private variables in that class.
However, it can reference private members of instances
of objects of the containing class.
In fact, one typical application for enhancement methods is to
provide a method for creating a new instance of the containing
class from an instance of the method object class.
These are a special kind of factory method.
Such a method might not need to access private members of the
method object class, but it might need to access private members of
the containing class, so an enhancement factory method is
perfectly suitable.
In addition to Enhancement methods, Sirius Mods 7.2 introduces
Intrinsic methods and classes (Intrinsic classes).
And, just as you can create enhancement methods for other system
classes, you can create enhancement methods for intrinsic classes,
specifically for the Float and String classes.
For example, the following definition creates an enhancement method that
calculates the length of the hypotenuse of a triangle given the
length of one side as the method object and the other side as a parameter:
The following is an example of a String enhancement method that returns
the number of vowels in a string:
You can invoke the above method as follows:
The preceding statement sets %nvowels to 3.
For a String enhancement method, the implicitly defined %this variable
has a Longstring datatype.
Enhancement methods can be added to any class, including
Collection classes (Arraylists, NamedArraylists, and so on).
Given this capability, it is quite common for a class to have
a need to create an enhancement method on a collection of that class.
For example, you might have an Order class that describes an order for widgets.
You might want to provide an enhancement method on Arraylist of
Order objects that creates a new Arraylist of objects that contains
items that need to be back-ordered (there are insufficient widgets
in stock to satisfy the order).
The method might look something like:
However, because a class has a special relationship to collections of objects of that
class, it is not necessary to indicate the class of the enhancement method.
That is, you can also write the above method invocation as:
It is possible to create enhancement methods with the same name as
standard collection methods.
For example, it is possible to create an Add method.
If you create such a method, the collection class method is completely hidden.
That is, there is no way to invoke the collection class method of the same
name, even from inside the enhancement method.
For this reason, it is generally not a good idea to create an enhancement
method for a collection class with the same name as a collection class
method.
The ability to hide collection class methods is available mainly to preserve
backward compatibility when a new collection class method is introduced.
If there were already enhancement methods of the same name, those methods
would continue to be invoked.
In Sirius Mods 7.2 and later, it is possible to to declare a class variable
as ReadOnly or Protected.
A ReadOnly variable can be examined by code outside the class, but it can only
be updated inside the class.
A Protected variable can be examined by code outside the class, but it can only
be updated inside the class or by code inside an extension class.
Since a ReadOnly or Protected variable must be accessible outside the class,
it would make no sense for such a variable to be in a Private section, so this
is not allowed.
ReadOnly and Protected variables are useful for providing an efficient means of
accessing relatively static information about objects in a class.
Unlike a property, retrieving ReadOnly or Protected variables requires no code
to be run in the class.
The term Protected is something of a misnomer.
In a very real sense, Protected variables aren't protected, at all.
After all, they can be updated by extension classes.
Their real purpose is to act as a sort of overridable variable, that is, a
value that can be overridden by an extension class.
For example, suppose a class has a ReadOnly variable called PartNumber.
Perhaps PartNumber is set by the class's constructor, and then it is never set
again (for a particular object instance).
Now, suppose this class wants to allow extension classes to set a different
PartNumber, probably in their constructors.
One approach would be to make PartNumber an Overridable ReadOnly property.
But this is a somewhat heavyweight approach, as it requires a bit of code
(the property Get method) for each extension class, and this code has to be
run every time PartNumber is retrieved.
Instead, PartNumber could be made a Protected variable, and an extension class's
constructor could simply set it after calling the base class constructor.
This allows the extension classes to override the base class's PartNumber
using little extra code and using a very efficient access path for the value.
Protected variables differ from Overridable ReadOnly properties,
however, in that an Overridable ReadOnly property always guarantees that the
extension class's code is run, so it overrides the base class's properties.
With a Protected variable, it would be possible for an extension class to
set it, and for the base class to then set it to something else, undoing
the extension class action.
Because they can be updated by both base and extension classes,
Protected variables are probably most useful for very
static values, like values that are only set by the constructors.
Use of Protected variables that can be set throughout the life of objects
of a class is likely to be error-prone, as it requires careful coordination
of updates between the base and extension classes.
These new methods are added to the System class:
Arguments, CallStack, CallStackDepth, and CallStackCaller.
For example, if procedure FOO contained the following:
The CallStack method returns the name of the procedure and the line within
the procedure that made the calls of the current method or subroutine.
Generally, each returned StringList item has the name of the file containing
the calling procedure at positions one through eight, followed by a blank,
followed by the name of the calling procedure, followed by a blank, followed
by the line number within the calling procedure.
The CallStackCaller method returns the name of the procedure and the line within
the procedure that made the calls of the current method or subroutine.
Generally, the returned string has the
name of the file containing the calling procedure at positions one through eight, followed
by a blank, followed by the name of the calling procedure, followed by a blank, followed
by the line number within the calling procedure.
At level-0 (immediately inside a Begin/End), CallStackDepth always returns 0.
For a method or subroutine called directly from level-0 code, CallStackDepth
would return 1.
For a method called from a method called from level-0, CallStackDepth would
return 2; and so on.
The following sections describe changes in the Janus SOAP Xml API
in this release.
XPath expressions may now contain multiple predicates in a single step.
Previous versions of Janus SOAP supported some, but not all,
cases of multiple predicates.
The primary purpose of the new multiple predicate support is to let you
use the position() function to filter based
on the position of nodes from the preceding predicate, rather than
from the step's nodetest.
For example, the following expression
selects the second chapter child of the book,
if its author is Alex:
The not() function is now supported in XPath predicates.
The argument is a Boolean expression, and the result is true
if the value of the argument is false, and false
otherwise.
Note: The result of the not() function applied to a comparison
expression is different than the same expression with the complementary comparison.
For example, this statement selects children that have the value of the status
attribute equal to "pending":
The following statement selects children that have the value of the status
attribute equal to something other than "pending":
And the following statement selects children that have the value of the status
attribute equal to something other than "pending", or that have no status attribute:
An XPath expression is now allowed to have a predicate that contains a location path which
itself contains a predicate; that is, predicates may be nested.
For example, this selects Chapters whose first Section has a Racy attribute:
In an XPath expression that has a predicate that contains a Boolean expression,
parentheses are now allowed for grouping in the Boolean operands.
For example, the following predicate is supported by Janus SOAP
in Sirius Mods 7.2 and later:
The various places in Janus SOAP that process a URI (for example, the third
argument of the AddElement method, or the string input to the LoadXml method)
now allow a URI to contain a “hexadecimal escape,” that is, a percent
sign (%) followed by two hexadecimal digits (which may be either uppercase
or lowercase when the letters A-F are used).
Note that there is no replacement of the hexadecimal values when URI
processing is performed.
For example, even though the ASCII code for the number “4” is
hexadecimal 34, the following two URIs are different and distinct:
The following features are new or changed in Janus Sockets:
Prior to the addition of the Send method, the
HTTPRequest class had methods only for HTTP GETs and POSTs.
The new Send method is a way to carry out HTTP methods in addition to GET or POST.
The Send function sends an HTTP request to an HTTP server
using a parameter value to identify which of any of the HTTP method types
(GET, POST, PUT, and so on) you want the function to perform.
Any HTTP method type is valid as long as its name is 16 characters or less.
The HTTP method type is specified with the Method (name required) parameter.
If you set the Method value to GET or POST,
the Send method invocation becomes equivalent to the existing Get method
or Post method, respectively, of the HTTPRequest class.
The following features are new or changed in Janus Web Server:
Janus Web Server now accepts any HTTP method in a request as long as the method
name is 16 bytes or shorter.
This feature is provided by:
The new OTHER option in the method parameter in the
JANUS WEB command refers to all methods other than PUT, GET, POST, and HEAD.
A method whose name exceeds 16 characters is not allowed.
Examples of rules that use OTHER follow:
Note:
This is a slight backward incompatibility: if a web rule specifies ANY,
URLs indicating methods other than GET, POST, PUT, or HEAD may now trigger
unexpected Web Server actions.
You can detect the method type in an application by a $web_hdr_parm('METHOD') query.
The following are new or changed features in the Sirius Functions:
Prior to Sirius Mods 7.2, the waiting time that remains for a user
paused by a $Wakeup call
is cancelled if a BROADCAST URGENT message is sent to the user.
As of Sirius Mods 7.2, the $Wakeup function accepts an optional argument so that
BROADCAST URGENT does not cause the $Wakeup function time to complete.
The string NOURGMSG (or any upper/lower case variant) is the
optional argument for $Wakeup that prevents a paused user from being immediately
wakened by BROADCAST URGENT.
The $Lstr_Word function now may return a Longstring, whose length exceeds 255 bytes.
Previously, attempting to return such a result either caused request cancellation,
or caused truncation to 255 bytes of the returned string.
Please refer to the
Notes for Sirius Mods Version 7.2 for a discussion of any compatibility
issues with prior versions of the Sirius Mods and any bugs which have
been fixed in this version, but had not, as of the date of this release, been fixed
in the immediately prior version.
The principal purpose of the release of version 4.4 of Fast/Unload is
to support the FILEORG X'80' feature introduced in
In addition, the OPEN command in a “batch” Fast/Unload job (that is, not
using the Fast/Unload User Language Interface) now allows specification of multiple filenames,
allowing the unload of an ad-hoc group of files.
Your FUEL program now may specify a group in the OPEN statement.
There are two alternatives to the OPEN statement:
The #FILENAME special variable is now available.
It obtains the name of the file currently being unloaded.
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
