System classes and methods
Overview
The ability to define classes in SOUL is a powerful facility. However, some classes are likely to be extremely heavily accessed, require access to facilities not directly accessible in SOUL, or both. It is for such cases that system classes were created.
A system class is a class that is built into the Model 204 nucleus and is typically written in Assembler language. As such, these classes are very efficient and provide an object-oriented interface to the Model 204 kernel. Because these classes are not written in SOUL, however, the class definitions are not available in SOUL, so the documentation must be consulted to determine the methods available in each class.
Some system classes are available to all users licensed for version 7.5 or higher of Model 204, and some system classes are tied to another product and so only available to users licensed for that product. For example, the system Socket class is only available to users licensed for Janus Sockets.
All the system classes for which a user is authorized are available in any SOUL request and do not need to be declared. To use a system class, simply declare an object of that class. For example, the Stringlist class implements what is effectively an unbounded array of strings. To use this class, just declare a Stringlist object:
%list is object stringlist ... %list = new %list:add('First item') %list:add('Second item')
Some system classes have shared methods and, like user classes, these can be accessed with any object of the class or with the class name in parentheses. For example, the MaxItemLength property in the Stringlist class returns the maximum length of any Stringlist item. Since this length does not depend on a particular instance, it is a shared method and can be accessed as such:
print %(Stringlist):maxItemLength ... %list is object stringList print %list:maxItemLength
There are already a large number of system classes, and their number is expected to grow over time. This raises the question of what happens when a new system class with the same name as a user class becomes available. For example, suppose there was already a user-written Stringlist class when the system class of the same name became available. What would be made of the following code?
class stringList ... end class ... %list is object stringList
The answer is that the code would continue to work as it had before. This is because it is perfectly valid to declare a user class with the same name as a system class, and in such situations, all references to the class name are assumed to refer to the user class. To access the system Stringlist class in this situation, you precede the class name with system: wherever it appears:
%systemList is object system:stringList ... print %(system:Stringlist):maxItemLength
The system: prefix can be used, of course, regardless of whether a user class by the same name exists. In fact, some sites may wish to adopt a local standard that all system class references must be preceded by system: to make clear what they are and to avoid confusion with user-written classes. That said, it is probably best to avoid the names of system classes when declaring user classes.
Except for the way they are defined, system classes behave exactly like user-written classes:
- Object variables are declared, constructed (New), and discarded in the same way.
- Object variables of a system class can be declared inside a user class or structure.
- Null tests and comparisons on system objects work the same way as for user objects.
- System object variables can be passed as parameters, and methods on system objects can be strung together.
One distinction between user classes and system classes is that the system class methods do not have explicit declarations. So the only way to understand the return values and parameters to a system method is through the documentation.
For documentation purposes, all system method parameters and return values (or inputs and outputs) can be thought of as having one of four basic types:
| Object | Some method outputs or inputs are objects of a particular class. The input and output classes will be specified in the documentation. |
|---|---|
| Float | All numeric input and outputs can be thought of as being declared as Float. Of course, Model 204's handling of Float values makes a Float input or output suitable even where only integral values are expected. |
| Longstring | Any input or output that is a string, even if it is guaranteed to be shorter than 256 bytes should be considered a Longstring. Longstring values are treated differently in certain expressions and have different truncation behavior than other String values — they will cause request cancellation if assigned to something that requires the Longstring to be truncated. |
| Unicode | Identical to Longstring except the character set is considered to be the double-byte Unicode character set. Unicode variables and values are passed as Unicode parameters without any conversion, while all other values are converted to an EBCDIC string as needed, and then converted to Unicode using the Online's EBCDIC to Unicode translation tables. Any untranslatable EBCDIC string results in a request canceling error. |
The one exception to this simple picture is the Item input and output from collection classes. Methods in collection classes behave as if any item input or output was an assignment to or from the item class type. To illustrate the importance of this distinction, consider the following code:
%list is object stringList %string is string len 10 %list = new %list:add('The bear went over the mountain') %string = %list:item(1)
In this example, the last assignment would result in a request cancellation because, even though the first Stringlist item is only 31 bytes long, it is a Longstring value so causes request cancellation when truncated on assignment.
On the other hand consider the following:
%list is collection arrayList of string len 255 %string is string len 10 %list = new %list:add('The bear went over the mountain') %string = %list:item(1)
In this case the last assignment does not cause request cancellation, because
it acts like an assignment from a String Len 255 variable to a String Len 10,
which results in silent truncation of the input.
Using system classes instead of $functions
There are several suites of $functions that are heavily used at many sites that "behave badly" in an object-oriented environment, especially inside non-shared methods. For example, the $list suite of $functions do not work well inside of methods. You might want a $list for each instance of a class, and it might seem logical to do something like the following:
class section public constructor new variable list is float end public constructor new %list = $listnew end constructor end class
The preceding code would compile without errors and actually work, more or less
correctly, as long as only a single instance of the class is created.
Unfortunately, if a second instance of the class were created,
the $listnew in the New constructor for the object would return the same $list identifier as
for the first instance, and it would cause any data in the $list for the first instance to be deleted.
Furthermore, since both objects would have the same $list identifier, they would be sharing the same $list, which is not likely to be what was intended. The Stringlist class avoids these problems:
class section public constructor new variable list is object stringlist end public constructor new %list = new end constructor end class
Clearly, the code is no more complicated than the $list version, but by
using a system object, the statement %list = new creates a
new Stringlist instance for each instance of the Section class, thereby
solving the problem with the $list version.
In addition, the Stringlist object is strongly datatyped, so users
or maintainers of the class have a clearer sense of the function of the List variable.
Also, errors such as assigning a number to that List
variable are caught at compile-time.
Finally, use of an object in this context makes it possible to
take advantage of the better object-oriented syntax for "stringing" methods:
%calculus is object section ... %calculus:list:add(%student)
The system classes that replace existing handle-based suites of $functions are:
| Recordset, Record, SortedRecordset, RecordsetCursor | Replace traditional SOUL file-oriented facilities. |
|---|---|
| Socket | Replaces $Sockets. Only available to licensees of Janus Sockets. |
| Stringlist | Replaces $lists. |
| XmlDoc, XmlNode, XmlNodelist | Replace $XML_ $functions. Only available to licensees of Janus SOAP. |
Other system classes are included in the Lists of classes and methods.
Constant methods
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':
%x = '0678':x
The hex conversion is done at compilation time. The method in this example (named X) is a compile-time-only equivalent of the intrinsic String 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:
%x = %y:x
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 following are the available Constant methods:
| Method | Description |
|---|---|
| U function | Converts an EBCDIC string to a Unicode string |
| X function | Returns the unencoded value of a hex-encoded string |