System classes and methods

Overview

The ability to define classes in User Language is a powerful facility. However, some classes are likely to be extremely heavily accessed, require access to facilities not directly accessible in User Language, 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 User Language, however, the class definitions are not available in User Language, so the documentation must be consulted to determine the methods available in each class.

Some system classes are available to all useres license for any Sirius Software product, and most system classes are available to all users licensed for Janus SOAP. However, 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 User Language 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 poperty 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 Language class becomes available. For example, suppose there was already a User Language 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 Language 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 Language 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 Language 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 Language classes. That said, it is probably best to avoid the names of system classes when declaring User Language classes.

Except for the way they are defined, system classes behave exactly like User Language 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 Language class or structure.
• Null tests and comparisons on system objects work the same way as for User Language objects.
• System object variables can be passed as parameters, and methods on system objects can be strung together.

One distinction between User Language 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 strings — 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 User Language file-oriented facilities.
Socket	Replaces $Sockets. Only available to licensees of both Janus Sockets and Janus SOAP.
Stringlist	Replaces $Lists.
XmlDoc, XmlNode, XmlNodelist	Replace $XML_ $functions. Only available to licensees of Janus SOAP.

Other system classes are documented in the manuals for the products to which they apply.

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 individual Constant methods are described in the following subsections.

X function

This function returns the unencoded value of a hex-encoded string. It treats each input character as an input hex digit.

The X method is available as of Sirius Mods version 7.3.

X syntax

%out = string:X

Syntax Terms

%out	A string variable to receive the unencoded value of the method object string.
string	A hex-encoded string value.

Usage Notes

• As in all Janus SOAP system methods with string outputs, the %out string variable provides longstring behavior. This adds 28 bytes of VTBL usage to every X constant, however.
• Although its utility is dubious, the following is valid and sets %x to X'01':

  %x = 'f0f1':x:x
  

• The X function requires a method object string with an even number of bytes.
• The X method is a compile-time-only equivalent of the HexToString method of the intrinsic String class.

Example

The following statement would display '1234':

printText {'f1f2f3f4':x}

U function

This function converts an EBCDIC method object string to a Unicode string. The function also converts XML style hexadecimal character references, XHTML entity references, and & references to the represented Unicode character.

The U method is available as of Sirius Mods version 7.3.

U syntax

%unicode = string:U

Syntax Terms

%unicode

A Unicode string variable to receive the Unicode encoding of the method object string.

string

A constant character string value, which may include an XML-style hexadecimal character reference or an XHTML entity reference. That is, string may contain an ampersand (&) in the following cases: As the substring '&'. This substring is converted to a single ampersand character. At the start of a hexadecimal character reference (for example, the eight characters '“' for the Unicode "Left double quotation mark"). The character reference is converted to the referenced character. As of Sirius Mods version 7.6, an XHTML entity reference (for example, the six characters ' ' for the "non-breaking-space" character). The entity reference is converted to the referenced character. A decimal character reference (for example, '¬') is not allowed.

Usage Notes

• The U method is a compile-time-only equivalent of the EbcdicToUnicode method of the intrinsic String class (with its CharacterDecode argument implicitly set to True).
• Using the U method (or EbcdicToUnicode) is necessary for converting to type Unicode if the string you want to convert may contain a hexadecimal character reference. Such a reference cannot be meaningfully assigned to a Unicode variable otherwise, whereas keyboard-available characters can simply be assigned directly to a Unicode variable without character reference and without conversion by U.
• You can find the list of XHTML entities on the Internet at http://www.w3.org/TR/xhtml1/dtds.html#h-A2

Example

The first Print statement below displays a plus sign ('+'); the second Print displays a copyright sign (©); the third displays '2122':

%p Unicode Initial('+')
print %p
 
* Entity for copyright symbol:
%copy Unicode Initial('©':U)
print %copy
 
* Constant for trademark symbol:
%tm Unicode Initial('™':U)
print %tm:UnicodeToUtf16:StringToHex

Simply specifying print %tm in the the third Print statement above (or its equivalent print %tm:UnicodeToEbcdic) would attempt to translate to EBCDIC and fail because the Unicode trademark character does not translate to a valid EBCDIC character. But the UnicodeToUtf16 method can convert the Unicode variable to a byte-stream Longstring, which the StringToHex method converts to its hex representation.