Notation conventions for methods
The syntax for each Janus SOAP method is displayed in the form of a usage statement which shows how you specify a typical invocation of the method (and receive its result, if any).
The syntax includes:
- Keywords and placeholder words
- Punctuation literals (parentheses, colons, etc. that you must specify)
- Special characters (square brackets, hyphens) that you do not specify because they are part of the syntax structure, not the method content
For example, here is the syntax for the Patch method of the StringList class:
%updList = sl:Patch( patchList, [Options= string])
The Patch method accepts two arguments (the second of which is optional and also "named"), updates the StringList that is the method object (sl), and returns the updated version of that StringList to a StringList object variable (%updList).
The following sections describe additional aspects of the syntax.
Mixed case
Method names are in mixed case with initial and internal capital letters. User Language keywords and variable name references are also in mixed case. This mixed-case convention is adhered to in text and syntax; it is not strictly adhered to in code examples. For more information about mixed-case User Language, see "Mixed-case User Language".
Method type
The methods are labeled by type, of which there are four:
| Functions | Methods that produce an output value. |
|---|---|
| Subroutines | Methods that produce no output value. |
| Properties | Methods that produce an output value and that can sometimes be set to a value. |
| Constructors | Methods that produce a new object instance. |
Optional arguments
In syntax, method arguments are required unless otherwise stated. Omitting a mandatory argument results in a compilation error. Optional arguments are enclosed in brackets ([]) in syntax and are described in text with the word "optional."
Named parameters
Some method arguments may be passed by name; they are specified with a following equal sign (=) in method syntax diagrams. For arguments described as "name allowed" (or "name required"), you may specify (or must specify) the argument name along with the argument value when you invoke the method. You specify such argument name and value pairs in the form:
object:methodname(... argName=argValue ...). For example, the Stringlist method RegexCapture has two optional arguments whose names are required if you specify the argument:
sl:RegexCapture( string, regex, [Options= string], [Status= %output])
A "named parameter" is declared for a method within the class definition with the NameAllowed or NameRequired keyword.
Callable functions
Many functions that return a result may also be invoked by the keyword Call. The descriptions of such functions say that they are "callable" and display a bracketed %variable and equals sign in syntax. For example:
[%number =] sl:Add( itemList)
The Call keyword is optional for a callable function, so you can invoke it by simply specifying the method object followed by colon (:) and the method name:
%sl:Add('the end')
The definition of a callable function includes the keyword Callable.
Subroutines are always invocable with Call, though a subroutine definition does not and must not include the keyword Callable.
Methods are non-shared unless otherwise identified. Shared methods are denoted by the %(classname): notation preceding the method name in the method syntax, which implies that the method need not operate on a particular object. For example:
%max = %(Stringlist):MaxItemLength
Using the class name as above is one way you can invoke the method. You can also employ the %objectVariable: notation used by non-shared, or instance, methods.
For example, if %sl is a Stringlist object, the following statement assigns the same value to %max as in the preceding example statement:
%max = %sl:MaxItemLength
In this case, %sl indicates the class to which the method belongs, not that the method operates on %sl (which may even be null for a shared method invocation).
For a shared member whose datatype is an object of the member's class, a third variation of invocation is also available. If assigned to an object variable of the class, the member may be invoked with no method object:
%myobj = RebuildObj
Such a shared member is also known as a virtual constructor or factory method, and this syntax is also available to Constructors, as described further below.
Constructors
Constructors, which produce a new object instance, are recognizable by the [%(classname):] notation preceding the method name in the method syntax. As for a shared method, the classname in the syntax indicates both of the following:
- A constructor does not operate on an existing object instance (method object).
- The invocation of a constructor requires a context that identifies the class of the object instance that the method produces.
Unlike the syntax for a shared method, the class name is shown within square brackets (thus, optional) for a constructor, because a constructor is always able to be invoked by assignment to an object variable of its class with no other class identifier, as in:
%myobj = new
The object variable provides the class context.
The invocation of the New constructor, above, is equivalent to using the class name, as in:
%myobj = %(MyClass):new
And both forms of invocation above are equivalent to explicitly specifying a method object instead, although the method object merely identifies the class of the constructor and it is not operated upon:
%myobj = %myclass:new
%myclass above may even be Null.
Although the preceding examples of constructor invocation use assignment statements, you can invoke a constructor with or without a method object or explicit class specification in other contexts that allow its class to be determined, for example as a parameter in another method. This class-identifying requirement is not met, however, by this format, which is invalid: Print New